Prompt Caching

Как это работает

Когда вы отправляете один и тот же префикс промпта в нескольких API-вызовах, upstream-провайдер распознаёт дубликат, пропускает повторную обработку и взимает плату по сниженному тарифу за кэшированную часть. Типичная экономия:

Кэширование включено по умолчанию для всех поддерживаемых моделей — настройка не требуется. Провайдер автоматически управляет жизненным циклом кэша (кэш обычно сохраняется 5–30 минут, в зависимости от провайдера и нагрузки).

Дизайн промптов, оптимизированный для кэширования

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

# ✅ GOOD: Static content first = high cache hit rate
messages = [
    {"role": "system", "content": "You are a legal assistant. Reference case law when answering..."},
    {"role": "user", "content": "What are the elements of negligence?"},
]

# ❌ BAD: Dynamic prefix kills cache
messages = [
    {"role": "user", "content": "What are the elements of negligence?"},  # Cache miss
    {"role": "system", "content": "You are a legal assistant..."},  # Too late
]

Чек-лист по дизайну

• Системное сообщение первым — всегда размещайте его как первый элемент в messages
• Статический контекст перед динамическими запросами — Few-shot примеры, извлечённый RAG-контекст, определения инструментов идут перед текущим вопросом пользователя
• Никаких временных меток / ID в префиксах — не добавляйте уникальные данные запроса перед кэшируемым содержимым
• Сохраняйте системные промпты идентичными — весь префикс должен совпадать побайтово для попадания в кэш
• Чем длиннее префикс, тем больше экономия — Кэширование системного промпта на 10K токенов экономит значительно больше, чем на 200 токенов

Мониторинг попаданий в кэш

Объект usage в ответе показывает, попал ли ваш промпт в кэш:

• Claude (Anthropic): Ищите cache_read_input_tokens и cache_creation_input_tokens
• GPT (OpenAI): Кэшированные токены отражаются в уменьшенном биллинге prompt_tokens
• Gemini (Google): Контекстное кэширование отображается в метаданных использования

import requests

response = requests.post(
    "https://api.tokspan.com/v1/chat/completions",
    headers={"Authorization": "Bearer sk-your-key"},
    json={"model": "MODEL_NAME", "messages": [...]},
)

# Check for cache hits in the usage object
usage = response.json()["usage"]
if "cache_read_input_tokens" in usage:
    print(f"Cache hit! {usage['cache_read_input_tokens']} tokens served from cache")
    print(f"Cache creation: {usage.get('cache_creation_input_tokens', 0)} tokens written")
else:
    print("Cache miss — all prompt tokens billed at full price")

Поддерживаемые модели