BroadRouter

Как структурировать промпты, чтобы префикс кэшировался

Команда BroadNet Inference · 4 мин чтения · Опубликовано · Обновлено

Упорядочивайте каждый запрос от самого стабильного к самому изменчивому: системный промпт, описания инструментов, справочные документы, история диалога, затем новое сообщение. Каждый слой должен быть побайтово одинаковым между вызовами: никаких меток времени и ID в начале, инструменты отсортированы, JSON сериализуется детерминированно, а история только дописывается. Затем измерьте cached_tokens, чтобы убедиться, что префикс действительно используется повторно.

Кэшированные входные токены дешёвые: в BroadNet Inference модель DeepSeek V4.1 Flash тарифицирует их по $0.0055 за 1 млн вместо $0.175. Цена и то, как читать поле usage, разобраны в статье о кэшированных токенах. Эта статья — о проектировании: как выстроить промпт, чтобы кэш действительно срабатывал, и как это доказать.

Почему порядок в промпте определяет долю попаданий в кэш?

Все крупные провайдеры кэшируют по префиксу. В руководстве OpenAI сказано, что для повторного использования должен совпадать весь отрендеренный префикс. Документация DeepSeek описывает то же правило: запрос попадает в кэш, только если полностью совпадает с сохранённым префиксом, а запрос, который расходится с ним на середине, не попадает. Anthropic строит кэш в порядке: инструменты, system, messages.

Под капотом сервер повторно использует KV-кэш, построенный для этого префикса. Поэтому кэш — это прямая линия от первого токена. Первый байт, который отличается от прошлого вызова, обрывает пригодную для повторного использования часть. Однострочная метка времени в начале промпта на 50 000 токенов заставит вас заплатить за все 50 000 токенов по полной цене.

Какой порядок слоёв правильный?

Слой Меняется Пример Правило
1. Системный промпт При деплое Роль, правила, формат вывода Никаких дат, ID, имён пользователей
2. Описания инструментов При деплое Схемы функций Отсортированный, детерминированный JSON
3. Справочные материалы На сессию или задачу Файлы репозитория, договоры, документация продукта Фиксированный порядок, стабильные метки
4. История диалога На каждой реплике, только дописывается Предыдущие реплики пользователя и ассистента Никогда не редактировать, только добавлять
5. Новое сообщение При каждом вызове Вопрос плюс текущее время, если оно нужно Изменчивые данные — сюда

Слой 5 — место для всего изменчивого: текущей даты, локали пользователя, ID запроса, найденных фрагментов, которые отличаются от вопроса к вопросу.

Что незаметно ломает префикс?

  1. Порядок в словаре. Фреймворки часто собирают массив tools из словаря или реестра. Если плагины загрузятся в другом порядке, байты изменятся.
  2. Форматирование JSON. json.dumps(x) и json.dumps(x, indent=2) — разные префиксы. Как и два сериализатора с разным порядком ключей.
  3. Пробелы в шаблоне. Пробел в конце строки или \r\n из одной ветки кода и \n из другой.
  4. Динамические списки инструментов. Удаление инструментов, недоступных пользователю, меняет префикс. Руководство OpenAI рекомендует держать описания стабильными и ограничивать использование через tool_choice или настройку разрешённых инструментов.
  5. Пересказ истории на месте. Переписывание старых реплик в сводку сбрасывает всё, что идёт после системного промпта. Пересказывайте редко и крупными шагами.
  6. Результаты поиска перед инструкциями. Фрагменты RAG между системным промптом и инструментами отличаются для каждого запроса и ломают заодно и слой инструментов.

Как собрать запрос, удобный для кэша, в коде?

Сделайте каждый слой функцией только от стабильных входных данных и сериализуйте детерминированно:

import json, os
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

SYSTEM = open("prompts/system.md").read()  # versioned file, no templating

def stable_tools(registry: dict) -> list:
    # Sort by name, sort keys inside each schema.
    return [json.loads(json.dumps(registry[name], sort_keys=True)) for name in sorted(registry)]

def docs_block(paths: list[str]) -> str:
    parts = [f"=== {p} ===\n{open(p).read()}" for p in sorted(paths)]
    return "\n\n".join(parts)

def build_messages(history: list, user_text: str, now_iso: str, doc_paths: list[str]):
    return (
        [{"role": "system", "content": SYSTEM},
         {"role": "user", "content": docs_block(doc_paths)}]
        + history                                   # append-only
        + [{"role": "user", "content": f"(now: {now_iso})\n{user_text}"}]
    )

resp = client.chat.completions.create(
    model="broadnet/deepseek-v4.1-flash",
    messages=build_messages(history, question, now_iso, files),
    tools=stable_tools(TOOLS),
)
history += [{"role": "user", "content": question}, resp.choices[0].message.model_dump(exclude_none=True)]

Две детали. Текущее время идёт в последнее сообщение, а не в системный промпт. А история хранит сообщение ассистента ровно в том виде, в каком оно вернулось, так что следующий вызов отправит идентичные байты.

Как доказать, что префикс кэшируется?

Запустите тест из двух вызовов в CI или в ноутбуке:

  1. Соберите запрос с реальным системным промптом, инструментами и документами.
  2. Отправьте его. Запишите usage.prompt_tokens.
  3. Измените только последнее сообщение пользователя и отправьте снова.
  4. Прочитайте usage.prompt_tokens_details.cached_tokens во втором вызове. Он должен покрывать почти весь общий префикс.
  5. Если он нулевой или маленький, сравните сериализованные тела запросов побайтово. Первое различие и есть то, что ломает кэш.

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

Что меняется для агентов и длинного контекста?

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

  • Один диалог на задачу. Новый диалог для каждого подшага выбрасывает префикс.
  • Читайте файлы один раз, ближе к началу. Если агент перечитывает файл, дописывайте новую копию, а не заменяйте старую, если только файл не изменился.

С контекстным окном на 1 млн токенов слой 3 может вместить целый репозиторий. На ключе с оплатой за токены это по карману, только если он кэшируется, поэтому порядок слоёв тем важнее, чем длиннее промпты. Кэшированные префиксы к тому же обычно сокращают время до первого токена; см. TTFT и пропускная способность.

Какое место здесь занимает BroadNet Inference

В BroadNet Inference блок usage сообщает prompt_tokens_details.cached_tokens, если модель это возвращает, а вход из кэша на DeepSeek V4.1 Flash, GLM 5.3 и Qwen3.8 27B оплачивается по более низкой ставке, указанной на странице цен. В документации BroadNet нет явных точек разрыва кэша или параметра ключа кэша, так что описанная выше схема — это и есть вся техника. На безлимитном тарифе кэш не влияет на счёт, потому что у сессий нет счётчика токенов, но та же структура всё равно помогает с задержкой.

Вопросы и ответы

Почему у меня низкая доля попаданий в кэш промптов?

Что-то в начале промпта меняется при каждом вызове. Обычные причины: метка времени или ID запроса в системном промпте, инструменты, сериализованные в другом порядке, найденные документы, поставленные перед инструкциями, или история, которую пересказывают и переписывают.

Ставить вопрос пользователя до или после длинных документов?

После. Документы — в начало, вопрос — в конец. Тогда документы образуют префикс, пригодный для повторного использования, а многие модели к тому же отвечают лучше, когда вопрос идёт после материала.

Ломают ли описания инструментов кэширование промптов?

Только если они меняются. Инструменты — часть префикса, поэтому держите тот же набор в том же порядке с тем же JSON. Чтобы ограничить инструменты для одного вызова, используйте tool_choice, а не правку списка.

Важен ли порядок few-shot примеров для кэширования?

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

Открыть в MarkdownСпросить ChatGPTСпросить ClaudeСпросить Perplexity