Перейти к основному содержимому

Кэширование промпта

GigaChat хранит префиксный key-value (KV) кэш в течение короткого окна. Когда последующий запрос имеет неизменный префикс, совпадающий с предыдущим, GigaChat переиспользует сохранённое состояние вместо повторной обработки этих токенов и сообщает число переиспользованных токенов как precached_prompt_tokens.

Шлюз отдаёт это значение как OpenAI usage.prompt_tokens_details.cached_tokens и Anthropic cache_read_input_tokens, поэтому любой OpenAI/Anthropic-клиент может наблюдать попадания в кэш без изменения своего кода.

Что было измерено​

Поведение ниже измерено на живом GigaChat API с GigaChat-2-Max и стабильным системным промптом примерно на 1200 токенов. Считайте эти числа порядком величины, а не контрактом.

НаблюдениеРезультат
Время жизни кэша (TTL) после последнего попаданияпримерно 30 секунд
Переиспользованные токены на повторном длинном префикседо ~99% токенов промпта
Доля попаданий при фиксированном X-Session-ID100% (15/15, два прогона)
Доля попаданий при случайном X-Session-ID на каждый вызов87% (13/15, два прогона)

Отсюда два вывода:

  • Кэш недолговечен. Он помогает интерактивным сценариям (агенты, чат, многошаговые циклы с инструментами, повторные попытки), где следующие запросы приходят за секунды, и почти не помогает пакетным задачам с интервалом в минуты.
  • Стабильный X-Session-ID повышает долю попаданий. Он удерживает запросы на той же записи кэша, а не полагается на собственную маршрутизацию вышестоящего сервиса.

Как включить​

1. Проброс заголовка клиентом​

Любой клиент может передать X-Session-ID. Шлюз пересылает его наверх без изменений:

curl http://localhost:8090/v1/chat/completions \
  -H "Authorization: Bearer <proxy-api-key>" \
  -H "X-Session-ID: conversation-123" \
  -H "Content-Type: application/json" \
  -d '{"model": "GigaChat-2-Max", "messages": [{"role": "user", "content": "..."}]}'

Используйте один идентификатор на логический диалог и разные для несвязанных диалогов. GIGACHAT_SESSION_ID задаёт глобальное значение по умолчанию, которое перекрывается заголовком запроса. Рабочий пример лежит в examples/openai/chat_completions/basic/session_cache_usage.py.

2. Идентификатор сессии из префикса​

Многие OpenAI/Anthropic/Gemini-клиенты не умеют передавать свои заголовки. Если включено, шлюз собирает стабильный X-Session-ID из собственного стабильного префикса запроса (односторонний хэш текста промпта, а не сам текст):

GPT2GIGA_CACHE_SESSION_ENABLED=True
GPT2GIGA_CACHE_SESSION_SCOPE=system
GPT2GIGA_CACHE_SESSION_MIN_PREFIX_TOKENS=1024
ПеременнаяПо умолчаниюНазначение
GPT2GIGA_CACHE_SESSION_ENABLEDFalseСобирать X-Session-ID из стабильного префикса запроса.
GPT2GIGA_CACHE_SESSION_SCOPEsystemsystem — хэш только системного промпта; prefix дополнительно включает ведущий пользовательский ход. system стоит по умолчанию, потому что остается стабильным между ходами диалога.
GPT2GIGA_CACHE_SESSION_MIN_PREFIX_TOKENS1024Минимальная оценка токенов префикса, при которой идентификатор сессии применяется.

Идентификатор сессии из префикса работает для OpenAI Chat Completions, OpenAI Responses, Anthropic Messages и Gemini GenerateContent, включая потоковые запросы. Для Responses системный префикс включает instructions и ведущие сообщения system или developer внутри input. Режим prefix также включает первый пользовательский ход. Если шлюз восстанавливает историю диалога, он использует собранный префикс: следующий запрос может переиспользовать сессию без повторной передачи этого префикса.

Хэш учитывает фактическую модель upstream после применения настроек шлюза, модели маршрута и доверенных переопределений модели. Поэтому разные модели получают разные идентификаторы для одного префикса. Если upstream выбирает модель через assistant или thread, в хэше используется соответствующий идентификатор. Идентификатор сессии из префикса не применяется, если:

  • клиент уже передал X-Session-ID;
  • задан GIGACHAT_SESSION_ID (приоритет у значения оператора);
  • в запросе нет пригодного префикса;
  • префикс короче GPT2GIGA_CACHE_SESSION_MIN_PREFIX_TOKENS (короткие промпты дают мало выгоды, поэтому их не трогают).

Такой идентификатор сессии не меняет промпт или настройки генерации. Он влияет на маршрутизацию кэша upstream. Когда GigaChat возвращает идентификатор сессии в заголовках ответа, шлюз отдаёт его как metadata.gigachat_x_session_id; для собранной сессии это односторонний хэш самого вызывающего, а не сырой текст промпта.

Где кэш помогает​

Время жизни ~30 секунд подходит шаблонам запросов, которые повторяются за секунды:

  • Многошаговые агенты и циклы инструментов. Каждый шаг заново отправляет растущую историю; неизменный префикс кэшируется между шагами.
  • Повторные попытки и fallback. Повтор через секунды после таймаута переиспользует префикс.
  • Параллельные подзадачи с общим промптом. Одновременные вызовы с одним системным промптом попадают в одну запись.
  • Интерактивный чат. Следующий ход в том же диалоге переиспользует прежнюю историю.

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

Как проверить попадания в кэш​

Смотрите usage.prompt_tokens_details.cached_tokens (формат OpenAI) или cache_read_input_tokens (формат Anthropic) в ответе. Ненулевое значение означает, что вышестоящий сервис переиспользовал кэшированные токены для этого запроса.