Кэширование промптов Qwen4: как повторно использовать контекст агента и найти причину промахов

Поставьте точку кэширования Qwen4, сравните два запроса и правильно прочитайте расход. Локальный генератор запросов и проверка причин промахов.

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

Если агент многократно читает одни и те же справочные материалы, разместите постоянный контекст перед точкой кэширования, а меняющийся вопрос — после неё. Затем проверьте сообщённое API чтение из кэша. Похожие запросы и более быстрый ответ сами по себе не доказывают, что кэш сработал.

Здесь рассматривается прямой API Qwen4 в QwenCloud, проверенный 16 ноября 2026 года. Статья продолжает руководство по подключению Qwen4-Max и миграции. Приведённый ниже генератор запросов работает локально без ключа. Платных запросов для проверки кэша мы не выполняли: примеры описывают воспроизводимый эксперимент, а не измеренную экономию или задержку.

Определите, что должно оставаться неизменным

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

Явно разделите входные данные:

Постоянный контекстМеняющаяся задача
Утверждённая версия инструкцииТекущий вопрос клиента
Фиксированные определения инструментовРезультаты инструментов для текущей задачи
Постоянный порядок инструкцийТребуемый результат этого хода
Зафиксированная сериализация документаНовые сведения, меняющие анализ

Не сохраняйте неверную информацию только ради высокого процента попаданий. Если инструкция изменилась, новый префикс уместен. Записывайте версию документа и хэш: так намеренное обновление можно отличить от случайного изменения форматирования.

Официальное руководство по кэшу Qwen4 указывает минимальный кэшируемый префикс в 1 024 токена, точное совпадение префикса в пределах одного пользователя и поддержку Chat Completions, Responses и Anthropic Messages. Явный кэш Qwen4 не поддерживается в DashScope. Число слов или символов не равно точному числу токенов.

Создайте два запроса локально

Возьмите синтетический или неконфиденциальный справочный документ, который вы вправе отправить выбранному провайдеру. Сохраните его как reference.txt. Между первым и вторым запросом содержимое не должно меняться.

Сохраните следующий код как build_cache_requests.py:

import hashlib
import json
from pathlib import Path

reference = Path("reference.txt").read_text(encoding="utf-8")
if not reference.strip():
    raise SystemExit("reference.txt is empty")

questions = [
    "List the three main responsibilities described in the reference.",
    "Which responsibilities in the reference require an explicit approval?"
]
for number, question in enumerate(questions, 1):
    payload = {
        "model": "qwen4-max",
        "messages": [{
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": reference,
                    "prompt_cache_breakpoint": {"mode": "explicit"}
                },
                {"type": "text", "text": question}
            ]
        }],
        "enable_thinking": False,
        "max_completion_tokens": 1024
    }
    Path(f"request-{number}.json").write_text(
        json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
    )
print("Reference SHA256:", hashlib.sha256(reference.encode()).hexdigest())
print("Created two request files; no network requests were sent.")

Выполните python3 build_cache_requests.py. Проверьте полученный JSON: первый блок содержимого и его точка кэширования должны совпадать полностью; отличаться должен только вопрос во втором блоке. Скрипт не подсчитывает токены документа. До платного запроса проверьте минимальный объём средствами провайдера или проверенным токенизатором именно этой модели.

Точка кэширования относится к блоку содержимого, поэтому content сообщения — массив. В примере один маркер; не смешивайте его с другим синтаксисом маркеров кэша в том же запросе. Первый вызов предназначен для создания повторно используемого контекста, второй — для его повторного использования. Произошло ли это, определяют фактические поля расхода в ответах.

Отправьте запросы последовательно по нужному маршруту

Настройте ключ QwenCloud с оплатой по использованию для выбранного региона по официальной инструкции. Команда ниже использует endpoint Chat Completions в Сингапуре. Ключи Ofox или Token Plan нельзя подставлять вместо него как взаимозаменяемые.

curl --silent --show-error --fail-with-body --max-time 120 \
  https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request-1.json -o response-1.json

Прежде чем продолжить, проверьте HTTP-результат, тело ответа и расход. После успешного завершения первого запроса повторите команду, заменив имена на request-2.json и response-2.json. Уложитесь в документированный срок действия кэша. Не отправляйте оба запроса одновременно: последовательное выполнение помогает отличить создание от повторного использования.

Тайм-аут не доказывает, что провайдер ничего не сделал. Перед повтором проверьте его журнал запросов и задайте явный бюджет эксперимента. Эта статья не запускает команды от вашего имени.

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

Читайте расход для фактически использованного протокола

В эксперименте с Chat Completions выше проверьте usage.prompt_tokens_details. Важно различать чтение из кэша, запись в кэш и обычный ввод. Наличие поля кэша не доказывает повторное использование всего документа.

import json
from pathlib import Path

for name in ["response-1.json", "response-2.json"]:
    response = json.loads(Path(name).read_text(encoding="utf-8"))
    usage = response.get("usage") or {}
    details = usage.get("prompt_tokens_details") or {}
    print(name, {
        "input_tokens": usage.get("prompt_tokens"),
        "cache_read_tokens": details.get("cached_tokens"),
        "cache_write_tokens": details.get("cache_write_tokens"),
        "output_tokens": usage.get("completion_tokens")
    })

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

Например, в QwenCloud данные кэша Responses находятся в input_tokens_details, а Anthropic-совместимый расход использует собственные поля чтения и создания. Некоторые поля являются псевдонимами: сложение псевдонима и соответствующего ему значения завысит расход. Смотрите таблицы протоколов в справочнике расхода кэша.

Диагностируйте промах, меняя по одному условию

НаблюдениеЧто проверитьСледующий контролируемый эксперимент
Первый запрос не сообщает о повторно используемом префиксеМинимум токенов, положение маркера, поддерживаемый протоколЗафиксируйте маршрут и проверьте сериализованный запрос
Во втором запросе нет чтения из кэшаТочное совпадение префикса, пользователь, прошедшее времяСравните первые блоки побайтово
Кэширована лишь часть вводаГде заканчивается точка кэширования и что изменилосьОтделите постоянный документ от текущего вопроса
Ранее рабочая последовательность перестала попадать в кэшВерсия справочника, определения инструментов, сериализация клиентаСравните сохранённые запросы с последней рабочей парой
Полей расхода нетПротокол, формат ответа, потоковый режимНачните с полного непотокового ответа
Возвращается ошибка параметраПоддержка на маршруте и структура JSONСократите запрос до документированного примера с одним маркером

Для длинных диалогов агентов есть дополнительная граница: официальная документация описывает поиск назад максимум по 20 блокам содержимого для каждой точки кэширования и сохранение только последних четырёх действующих точек, включая автоматическую, если она используется. Если растущая история вытесняет полезный префикс за это окно, пересмотрите разбиение на блоки и явно поставьте точку на границе постоянного контекста. Не удаляйте необходимые результаты инструментов или историю рассуждений только ради попадания в кэш. Сохраните снимки запросов до и после изменения и проверьте полученный расход.

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

При ошибке ID или endpoint используйте руководство по model not found (на английском). Если кэш работает, но многошаговый агент теряет результаты инструментов, это отдельная проблема истории; см. сохранение многошаговых вызовов инструментов.

Считайте экономию по полностью принятым задачам

Запись в кэш может стоить иначе, чем чтение или обычный ввод. Сравнивайте полную последовательность, включая первоначальную запись и каждый сгенерированный ответ, с той же последовательностью без кэша. Берите текущие тарифы нужного региона из цен QwenCloud, а не ставку другого региона или акцию для preview.

Для каждого вызова записывайте: версию документа, входные токены, токены чтения и записи кэша, обычный ввод, выходные токены, время и результат приёмки. Не учитывайте псевдонимы дважды. Скидка на кэшированный ввод не означает такой же процент скидки на всю задачу агента: вывод и внешние инструменты могут составлять значительную часть расходов.

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

Это рабочий процесс прямого QwenCloud. В проверенном 16 ноября каталоге Ofox Qwen4 не была указана. Для существующих маршрутов Ofox проверьте точную запись модели, используйте аутентификацию Ofox и обработку ошибок Ofox. Эти документы не подтверждают, что новые параметры кэша QwenCloud доступны через Ofox.

Часто задаваемые вопросы

Повтор промпта доказывает, что Qwen4 использовала кэш?
Нет. Проверьте поля чтения из кэша в отчёте провайдера. Более быстрый ответ или повторяющийся текст сами по себе не подтверждают попадание.
Можно ли использовать эти параметры кэша в Ofox?
Статья описывает прямой API Qwen4 в QwenCloud. В проверенном 16 ноября каталоге Ofox Qwen4 не было; не считайте модель и контракт кэша автоматически доступными через Ofox.