Порядок инструментов и стабильность запроса

Один и тот же набор инструментов может попасть в два запроса в разном порядке. Для приложения список возможностей остался прежним. Для префиксного кэша изменилось начало входа — как раз перед историей, которую хотелось переиспользовать.

Синтетический кейс. Возьмём два учебных JSON-запроса с одинаковыми сообщениями и описаниями функций. Во втором переставим инструменты местами и проверим, как это изменение находит layout_linter.py.

Откуда берётся перестановка

Агент может заново собирать инструменты на каждом шаге: загрузить плагины, отфильтровать действия по правам пользователя, объединить списки из нескольких источников. Если порядок нигде не закреплён, одинаковый набор сериализуется по-разному.

Префиксный кэш учитывает последовательность токенов. Когда описания инструментов находятся перед историей диалога, перестановка меняет вход ещё до этой истории. Подробнее о ключах блоков — в документации vLLMВнешняя ссылка, откроется в новой вкладке.

Два запроса

В первом файлеВнешняя ссылка, откроется в новой вкладке порядок такой:

lookup_policy → write_file

Во второмВнешняя ссылка, откроется в новой вкладке:

write_file → lookup_policy

Модель, системное и пользовательское сообщения, определения функций и схема ответа одинаковы. Различается порядок элементов массива tools.

Правило AP-2 в layout_linter.py проверяет сортировку инструментов по имени. В этом примере первый запрос проходит проверку, второй получает замечание о перестановке.

Как повторить проверку

Понадобятся Git, Python 3.10 или новее и локальная копия репозитория сайтаВнешняя ссылка, откроется в новой вкладке, где лежат оба запроса. Из её корня скачайте анализатор версии v0.1.3, на которой получен результат:

test ! -e .evidence-tools/audit-prompt-caching-v0.1.3 && \
  git clone --depth 1 --branch v0.1.3 \
  https://github.com/sernote/audit-prompt-caching.git \
  .evidence-tools/audit-prompt-caching-v0.1.3

Если каталог уже существует, используйте его после проверки версии.

git -C .evidence-tools/audit-prompt-caching-v0.1.3 remote get-url origin | \
  grep -Fx 'https://github.com/sernote/audit-prompt-caching.git'
git -C .evidence-tools/audit-prompt-caching-v0.1.3 describe --tags --exact-match HEAD | \
  grep -Fx 'v0.1.3'
git -C .evidence-tools/audit-prompt-caching-v0.1.3 rev-parse HEAD | \
  grep -Fx 'cbf216e73b0b49064e44e7a9ed1a174d1c5dbd23'

Запустите проверку первого файла:

python3 .evidence-tools/audit-prompt-caching-v0.1.3/audit-prompt-caching/scripts/layout_linter.py \
  evidence/v3/agent-session-cache-reuse/step-stable.json

Он возвращает код 0 и результат:

{
  "status": "ok",
  "findings": [],
  "clean_checks": ["AP-1", "AP-2"]
}

Теперь проверьте файл с перестановкой:

python3 .evidence-tools/audit-prompt-caching-v0.1.3/audit-prompt-caching/scripts/layout_linter.py \
  evidence/v3/agent-session-cache-reuse/step-drift.json

Код 1 означает, что анализатор нашёл замечание. В результате будет:

{
  "rule_id": "AP-2",
  "severity": "high",
  "category": "tool-schema-stability",
  "issue": "tool definitions are not sorted by stable name",
  "evidence": "tools order is ['write_file', 'lookup_policy']"
}

Полный вывод обоих запусковВнешняя ссылка, откроется в новой вкладке сохранён вместе с командами и версией скрипта.

Что изменить в агенте

Если порядок инструментов не влияет на их выбор моделью, его можно закрепить перед сериализацией. В нашем примере подходит сортировка по имени. Проверка готового массива в тестах поможет поймать новую перестановку после изменения кода сборки запроса.

В своём агенте сначала проверьте, имеет ли порядок значение для модели и API. Отдельно учитывайте изменения состава: если инструмент стал недоступен по правам, его нужно убрать, даже если префикс станет короче.

AP-2 помогает найти место для проверки. Причину ищите в сборке списка: порядке загрузки плагинов, объединении реестров и применении прав.

Как проверить работу кэша

После исправления сохраните два готовых запроса одного сценария и сравните их общее начало после шаблонизации. Затем повторите вызовы на той же реплике или в той же области кэширования провайдера. По данным чтения кэша и времени до первого токена будет видно, помогло ли изменение.

Если вход стабилен, а повторного использования всё ещё нет, проверьте маршрут и сохранность блоков. Этот шаг разобран в главе «Префиксный кэш».

Проверить свой проект с audit-prompt-caching можно, начав с кода сборки запросов. Авторский разбор того, как изменения промпта влияют на кэш, — в статье «Короткий промпт ≠ дешёвый промпт: как оптимизация ломает prefix cache в LLM-агентах»Внешняя ссылка, откроется в новой вкладке.