Skip to Content
Руководство для пользователейВозможностиСтоимость резидентного контекста

Стоимость резидентного контекста

Каждый запрос, отправляемый сессией, несёт один и тот же префикс до начала вашего разговора: системный промпт, схемы всех объявленных инструментов, ваши контекстные файлы (QWEN.md) и список навыков. Вы платите за этот префикс на каждом ходу, включая ходы, которые просто отвечают на вопрос. Эта страница посвящена измерению и сокращению префикса.

Кэширование токенов снижает цену префикса. Эта страница уменьшает сам префикс. Эти подходы дополняют друг друга — меньший префикс дешевле и в кэше.

Посмотрите, за что вы платите

/context detail

/context выводит разбивку по категориям; detail добавляет строки по каждому элементу — каждый встроенный инструмент, каждый MCP-инструмент, каждый контекстный файл, каждый навык в списке — чтобы вы могли увидеть, какая именно запись самая дорогая. Читайте его на первом ходу сессии, когда разговор ещё пуст и всё, что вы видите, — это префикс.

Категории — это то, что сообщает /context, плюс две служебные строки: startupContext (блок окружения, отправляемый как первый ход пользователя) и явный остаток для всего, что категории не атрибутировали, чтобы части всегда складывались в итог.

Используйте стоимость простоя, а не процент окна

Процент контекстного окна — это не целевой показатель, потому что знаменатель произволен. Одна и та же конфигурация читается как 6,5% для модели с контекстом 1M и 37% для модели 128k — одинаковый текст, одинаковая стоимость, совершенно разные числа. Вместо этого используйте:

Стоимость простоя — входные токены сессии, которая задаёт один вопрос и не вызывает ни одного инструмента.

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

Рычаги, в порядке эффективности

1. Отключите неиспользуемые возможности

Каждый инструмент, объявленный модели, добавляет свою схему в каждый запрос. Отключение опциональных возможностей с крупными резидентными инструментами может сэкономить токены запроса. Отложенные инструменты вместо этого добавляют короткие записи каталога и стоимость последующего обнаружения или вызова. Отключение возможности также удаляет её инструменты у субагентов, чего следующий рычаг не всегда делает.

2. Оставьте в eager-поверхности только то, что реально используете

tools.eager — это allowlist встроенных инструментов, чьи схемы остаются в начальном запросе. Всё остальное становится отложенным (deferred): по-прежнему зарегистрировано, по-прежнему видно в /tools, по-прежнему вызываемо — модель достигает этого через бридж tool_search → tool_call, когда выясняется, что инструмент нужен.

{
  "tools": {
    "eager": [
      "read_file",
      "write_file",
      "edit",
      "glob",
      "grep_search",
      "run_shell_command",
      "skill",
    ],
  },
}

Измеряйте allowlist относительно правильного baseline. Инструменты, которые по умолчанию загружаются по требованию сами по себе, уже отсутствуют в первом запросе, и с тех пор как tools.toolSearch.threshold начал по умолчанию равняться 0, ничто не предзагружает их обратно, так что экономия от allowlist — это только схемы eager-by-default инструментов, которые он удерживает, а не вся встроенная поверхность. Сделайте свежее измерение /context на версии, которую вы реально используете, прежде чем приписывать число вашему списку.

Четыре вещи, которые нужно знать перед использованием:

  • Это не отключение. Пониженный инструмент остаётся достижимым. Если вы хотели убрать инструмент, используйте правило permissions.deny на весь инструмент или tools.disabled.
  • Некоторые инструменты исключены и сохраняют обычное поведение загрузки независимо от списка: tool_search и tool_call (две половины бриджа, который достигает удержанного инструмента), structured_output, инструменты жизненного цикла plan-режима (enter_plan_mode, exit_plan_mode, ask_user_question), task_stop, MCP-инструменты (mcp__*) и инструменты Computer Use (computer_use__*). task_stop и семейство Computer Use и так загружаются по требованию, так что их ограничение ничего не сэкономит; MCP-инструменты управляются через tools.toolSearch.* и фильтры includeTools / excludeTools на сервер; а ничто в tools.eager не может убрать остальные: для этого нужно правило permissions.deny на весь инструмент, запись tools.disabled или --exclude-tools — а для пары бриджа, tools.toolSearch.enabled: false удаляет обе половины сразу. Удаление половины бриджа — это не нейтральный выход из allowlist: каждый обычный отложенный инструмент (все MCP-инструменты, отложенное семейство Computer Use) затем принудительно объявляется в каждом запросе, тогда как удержанный инструмент не предлагается модели и не может быть загружен обратно через бридж — он остаётся зарегистрированным, так что прямой вызов по имени всё ещё проходит через обычное одобрение.
  • permissions.allow ничего не экономит. Это чистое автоодобрение: оно никогда не понижает, не скрывает и не удаляет инструмент. Режимы одобрения тоже.
  • Нужны обе половины бриджа. Удержанный инструмент просматривается через tool_search и вызывается через tool_call; один tool_search может прочитать схему, но не может её вызвать. Если хотя бы одна не зарегистрирована — tools.toolSearch.enabled: false запрещает обе; правило deny на tool_search/tool_call, запись --exclude-tools или запись tools.disabled удаляет одну — allowlist всё равно удерживает схемы, загрузить их обратно нечему, и пониженные инструменты не предлагаются модели для этой сессии (предупреждение записывается в лог); они остаются зарегистрированными, так что прямой вызов по имени всё ещё проходит через обычное одобрение. Обычные отложенные инструменты в этом случае возвращаются к объявлению через eager; инструменты, которые вы понизили через tools.eager, — нет.

tools.visible — это лазейка для одного инструмента, который вы хотите объявить заранее, хотя по умолчанию он отложенный.

Координация агентов и целей (agent, list_agents, get_goal, update_goal и propose_goal) по умолчанию отложена; конфигурация tools.eager не нужна. Модель видит короткие записи обнаружения вместо полных схем. Их первое использование требует обнаружения через бридж, поэтому сравнивайте стоимость всей задачи и успешность делегирования/завершения целей, а не только первого запроса. Это обычные отложенные инструменты: tools.visible, предзагрузка и фолбэк eager при неполном бридже, описанный выше, всё ещё применимы. Предзагрузка работает по принципу всё или ничего для всего пула кандидатов на отложенную загрузку, и эти пять объявлений большие, так что tools.toolSearch.threshold, который раньше показывал каждый отложенный инструмент при старте сессии, теперь может не показать ни одного. Сделайте повторное измерение /context после изменения любого из них.

3. Перенесите сценарные рекомендации из контекстных файлов в навыки

Контекстный файл подклеивается в каждый запрос каждой сессии, к которой он применим, без фильтрации по релевантности. Навык указывается только именем и описанием — в одном измеренном примере 84 навыка в среднем занимали около 55 токенов каждый — и загружает своё тело при вызове, а навык с фильтром по paths: даже не указывается в списке, пока не затронут подходящий файл.

Оставьте в контекстном файле только то, что всегда истинно — идентичность, словарь, жёсткое ограничение — а «когда делаете X, делайте Y» поместите в навык или правило с фильтром paths:. /context detail называет каждый контекстный файл, а для файла расширения указывает расширение, которому он принадлежит.

4. Системный промпт — в последнюю очередь

Базовый промпт уже является самой маленькой из резидентных категорий, и примерно треть его — это текст безопасности и разрешений, который нельзя редактировать. Его инструментальные рекомендации с фильтрами следуют объявленному набору, за исключением доступного через бридж Agent; другим инструментам, названным в этих записях, всё ещё нужны объявления. Сокращение поверхности инструментов может поэтому также уменьшить эти рекомендации. Полная замена через --system-prompt возможна и является самым рискованным изменением на этой странице; если делаете это, сравнивайте с вышестоящим промптом при каждом обновлении.

Ловушки

  • Субагенты тоже получают отложенные инструменты. Субагент, не объявляющий явный список инструментов, получает схемы всех зарегистрированных инструментов, включая отложенные, и не проходит через ToolSearch. tools.eager и permissions.deny — единственные рычаги, которые до него доходят; порог предзагрузки — нет.
  • Фоновым агентам памяти нужны их полные списки инструментов, и эти два списка различаются. Dream-воркер проекта нуждается в шести инструментах (read_file, grep_search, glob, run_shell_command, write_file, edit); автоматическое извлечение нуждается в пяти — тот же набор без run_shell_command, который оно запрещает по дизайну. Запрет инструмента, который реально есть у любого из этих агентов, тихо деградирует его работу, а не выдаёт ошибку. Поэтому не запрещайте run_shell_command глобально, чтобы просто убрать его объявление: Dream всё ещё нуждается в нём.
  • Токены могут переместиться, а не исчезнуть. Уберите grep_search и glob, и модель может обратиться к grep и find через оболочку, чей вывод попадёт в разговор. Новый вывод добавляет входные токены при первой отправке; неизменная история с ним может попасть в кэш префикса провайдера при последующих запросах. Оценивайте изменение по общим входным токенам на задачу, кэшированным и некэшированным входам от провайдера и реальному счёту, а не только по префиксу.
  • Возобновлённые сессии повторно отправляют то, что нужно. Пониженный инструмент, появившийся в истории возобновлённой сессии, автоматически получает свою схему обратно; отклонённый инструмент — нет.
  • Раскрытие удержанного инструмента больше не переписывает префикс — но раньше переписывало, и старые советы предполагают обратное. Обнаружение проходит через бридж tool_search → tool_call, который оставляет список объявленных инструментов байт-стабильным, так что префикс кэша промпта переживает обнаружение в середине сессии; стоимость — один дополнительный раунд обмена перед первым использованием удержанного инструмента. Вот почему tools.toolSearch.threshold теперь по умолчанию равен 0: переноска отложенного набора на каждом ходу больше не является более выгодной стороной компромисса. Повышайте порог только чтобы вернуть этот раунд обмена для обычных отложенных инструментов (MCP-инструменты и встроенные по требованию) в сессии, которая определённо в них нуждается — он никогда не предзагружает инструмент, который вы понизили через tools.eager; те остаются за бриджем при любом пороге. Предзагрузка также запускается при старте сессии, а MCP-серверы обычно подключаются после неё, так что свежий запуск не объявляет никаких MCP-инструментов независимо от порога; они попадают в предзагрузку со следующего старта сессии (в CLI, после /clear) или немедленно при QWEN_CODE_LEGACY_MCP_BLOCKING=1.
  • Модели с кэшированием префикса раньше инвертировали этот компромисс; для отложенных инструментов больше не инвертируют. Для моделей, чья скидка зависит от неизменного префикса, сохранение списка объявлений идентичным когда-то было важнее, чем сохранение его маленьким — вот почему некоторые развёртывания отключали ToolSearch вручную. Раскрытие удержанного инструмента теперь оставляет этот список байт-стабильным, так что эта конкретная причина устарела — за одним исключением, указанным в самом описании tool_search: обновление набора инструментов может всё ещё повторно объявить удержанный инструмент, когда в живой истории есть прямой вызов к нему, и это действительно перемещает префикс. Стабильность префикса всё ещё аргумент против всего остального, что переписывает префикс в середине сессии, например, редактирование контекстного файла между ходами.
  • Области настроек протекают. Настройки применяются к каждому клиенту, который их читает (CLI, Web Shell, serve), поэтому поверхность инструментов для конкретного развёртывания нуждается в собственной области настроек.

Проверьте экономию

  1. Запишите стоимость простоя до изменения: свежая сессия, один простой вопрос, /context на первом ходу.
  2. Применяйте по одному рычагу за раз и повторяйте, перезапуская сессию — большинство этих настроек читаются при старте.
  3. Убедитесь, что возможность (capability) сохранилась, на собственном наборе задач: частота успешных вызовов инструментов, как часто приходится вызывать tool_search, и результаты задач. Пониженный инструмент, до которого модель не догадывается обратиться, не падает с ошибкой; он просто перестаёт использоваться.
  4. Смотрите на счёт, а не только на префикс — см. ловушку о токенах, переместившихся в разговор.

См. также

  • Кэширование токенов — что кэширование делает с ценой того, что осталось.
  • Правила — контекст с условием paths:, включая то, что может внести расширение.
  • Навыки — прогрессивное раскрытие и фильтрация по paths:.
  • Справочник настроек — точная семантика tools.eager, tools.visible, tools.disabled, tools.toolSearch.*, permissions.deny.
Last updated on
Кэширование токеновПесочница