> Чтобы получить чистый Markdown любой страницы, добавьте .md к URL страницы. > Для полного индекса документации см. https://api.vega.chat/docs/llms.txt. > Для полного содержания документации см. https://api.vega.chat/docs/llms-full.txt. > Для интеграции AI‑клиентов (Claude Code, Cursor и др.) подключитесь к серверу MCP по адресу https://api.vega.chat/docs/_mcp/server. # Кеширование подсказок Чтобы сэкономить на расходах на вывод, вы можете включить кеширование подсказок у поддерживаемых провайдеров и моделей. Большинство провайдеров автоматически включают кеширование подсказок, но имейте в виду, что некоторые (см. ниже Alibaba и Anthropic) требуют включать его для каждого сообщения отдельно. При использовании кеширования (будь то автоматическое в поддерживаемых моделях или через свойство `cache_control`), **VEGA** использует provider sticky routing для максимального количества попаданий в кеш — подробнее см. раздел [Provider Sticky Routing](#provider-sticky-routing) ниже. ## Provider Sticky Routing Чтобы максимизировать процент попаданий в кеш, **VEGA** использует **provider sticky routing** для направления последующих запросов к тому же конечному пункту провайдера после кешированного запроса. Это работает автоматически как с неявным кешированием (например, OpenAI, DeepSeek, Gemini 2.5), так и с явным кешированием (например, точки прерывания `cache_control` от Anthropic). **Как это работает:** * После запроса, использующего кеширование подсказок, **VEGA** запоминает, какой провайдер обслужил ваш запрос. * Последующие запросы к той же модели направляются к тому же провайдеру, поддерживая ваш кеш в «тёплом» состоянии. * Привязка к провайдеру активируется только тогда, когда стоимость чтения кеша у провайдера ниже, чем обычная цена за подсказку, гарантируя экономию. * Если выбранный провайдер становится недоступным, **VEGA** автоматически переключается на следующий лучший провайдер. * Привязка к провайдеру не используется, если вы задаёте ручной [порядок провайдеров](/docs/api-reference/provider-preferences) через `provider.order` — в этом случае приоритет имеет ваш явный порядок. **Гранулярность привязки к провайдеру:** Привязка к провайдеру отслеживается на уровне аккаунта, модели и беседы. По умолчанию **VEGA** идентифицирует беседы, хешируя первое системное (или developer) сообщение и первое сообщение, не являющееся системным, в каждом запросе, поэтому запросы с одинаковыми начальными сообщениями направляются к одному и тому же провайдеру. Это означает, что разные беседы естественно привязываются к разным провайдерам, улучшая балансировку нагрузки и пропускную способность, одновременно поддерживая кеш в «тёплом» состоянии внутри каждой беседы. ### Использование `session_id` для привязанных сессий Для более явного контроля над привязкой к провайдеру вы можете передать `session_id` в запросе. Когда `session_id` присутствует, **VEGA** использует его напрямую в качестве ключа привязки, вместо того чтобы генерировать его из хеширования сообщений. Это особенно полезно в многошаговых агентных рабочих процессах, где начальные сообщения могут изменяться между запросами, но вы всё равно хотите направлять их к одному и тому же провайдеру. Вы можете указать `session_id` двумя способами: * **Тело запроса**: включите `session_id` как поле верхнего уровня в теле запроса. Если указаны оба, значение из тела имеет приоритет. * **Заголовок**: установите HTTP‑заголовок `x-session-id`. `session_id` может содержать не более 256 символов. ```json { "model": "anthropic/claude-sonnet-4", "session_id": "my-agent-session-abc123", "messages": [ { "role": "user", "content": "Continue our conversation..." } ] } ``` Когда `session_id` установлен, привязка к провайдеру активируется при любом успешном запросе — даже до того, как будет замечено использование кеша — так что последующие запросы в той же сессии сразу получают выгоду от кеширования подсказок. Без `session_id` привязка активируется только после обнаружения попадания в кеш. ## Проверка использования кеша Чтобы увидеть, сколько кеширование сэкономило на каждой генерации, вы можете: 1. Нажать кнопку деталей на странице [Activity](/activity). 2. Воспользоваться API `/api/v1/generation`, [описанным здесь](/docs/api/api-reference/generations/get-generation). 3. Проверить объект `prompt_tokens_details` в [ответе об использовании](/docs/cookbook/administration/usage-accounting), включённом в каждый ответ API. Поле `cache_discount` в теле ответа покажет, сколько было сэкономлено за счёт использования кеша. Некоторые провайдеры, такие как Anthropic, могут иметь отрицательную скидку при записи в кеш, но положительную скидку (снижающую общую стоимость) при чтении из кеша. ### Поля объекта usage Объект usage в ответах API содержит детальные метрики кеша в поле `prompt_tokens_details`: ```json { "usage": { "prompt_tokens": 10339, "completion_tokens": 60, "total_tokens": 10399, "prompt_tokens_details": { "cached_tokens": 10318, "cache_write_tokens": 0 } } } ``` Ключевые поля: * `cached_tokens`: количество токенов, считанных из кеша (попадание в кеш). Когда значение больше нуля, вы получаете выгоду от кешированного контента. * `cache_write_tokens`: количество токенов, записанных в кеш. Появляется в первом запросе при создании новой записи кеша. ## OpenAI Изменения цен на кеширование: * **Запись в кеш**: бесплатно * **Чтение из кеша**: (в зависимости от модели) стоимость 0.25x или 0.5x цены оригинального ввода [Нажмите здесь, чтобы посмотреть цены на кеширование OpenAI по моделям.](https://platform.openai.com/docs/pricing) Кеширование подсказок в OpenAI автоматизировано и не требует дополнительной настройки. Минимальный размер подсказки — 1024 токена. [Нажмите здесь, чтобы узнать больше о кешировании подсказок в OpenAI и его ограничениях.](https://platform.openai.com/docs/guides/prompt-caching) ## Grok Изменения цен на кеширование: * **Запись в кеш**: бесплатно * **Чтение из кеша**: стоимость {GROK_CACHE_READ_MULTIPLIER}x цены оригинального ввода [Нажмите здесь, чтобы посмотреть цены на кеширование Grok по моделям.](https://docs.x.ai/docs/models#models-and-pricing) Кеширование подсказок в Grok автоматизировано и не требует дополнительной настройки. ## Moonshot AI Изменения цен на кеширование: * **Запись в кеш**: бесплатно * **Чтение из кеша**: стоимость {MOONSHOT_CACHE_READ_MULTIPLIER}x цены оригинального ввода Кеширование подсказок в Moonshot AI автоматизировано и не требует дополнительной настройки. ## Groq Изменения цен на кеширование: * **Запись в кеш**: бесплатно * **Чтение из кеша**: стоимость {GROQ_CACHE_READ_MULTIPLIER}x цены оригинального ввода Кеширование подсказок в Groq автоматизировано и не требует дополнительной настройки. В настоящее время доступно на моделях Kimi K2. [Нажмите здесь, чтобы посмотреть документацию Groq.](https://console.groq.com/docs/prompt-caching) ## Alibaba Qwen Изменения цен на кеширование при явном кешировании: * **Запись в кеш**: стоимость {ALIBABA_CACHE_WRITE_MULTIPLIER}x цены оригинального ввода * **Чтение из кеша**: стоимость {ALIBABA_CACHE_READ_MULTIPLIER}x цены оригинального ввода Alibaba требует явных точек прерывания кеша. Добавьте `cache_control: { "type": "ephemeral" }` к блокам контента, которые вы хотите кешировать, используя тот же синтаксис, что и у Anthropic. Записи в кеш используют TTL 5 минут. Явное кеширование в Alibaba доступно для моделей `deepseek/deepseek-v3.2`, `qwen/qwen3-max`, `qwen/qwen-plus`, `qwen/qwen3.6-plus`, `qwen/qwen3-coder-plus` и `qwen/qwen3-coder-flash`. Точки доступа Snapshot, включая `qwen/qwen3.5-plus-02-15` и `qwen/qwen3.5-flash-02-23`, не поддерживают явное кеширование. ### Пример ```json { "model": "qwen/qwen3-coder-plus", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Use the reference below when answering." }, { "type": "text", "text": "HUGE TEXT BODY", "cache_control": { "type": "ephemeral" } }, { "type": "text", "text": "Summarize the main implementation details." } ] } ] } ``` ## Anthropic Claude Изменения цен на кеширование: * **Запись в кеш (TTL 5 минут)**: стоимость {ANTHROPIC_CACHE_WRITE_MULTIPLIER}x цены оригинального ввода * **Запись в кеш (TTL 1 час)**: стоимость 2x цены оригинального ввода * **Чтение из кеша**: стоимость {ANTHROPIC_CACHE_READ_MULTIPLIER}x цены оригинального ввода Существует два способа включить кеширование подсказок в Anthropic: * **Автоматическое кеширование**: добавьте единственное поле `cache_control` на верхнем уровне вашего запроса. Система автоматически применяет точку прерывания кеша к последнему кешируемому блоку и продвигает её вперёд по мере роста беседы. Лучший вариант для многошаговых диалогов. * **Явные точки прерывания кеша**: разместите `cache_control` непосредственно на отдельных блоках контента для тонкой настройки того, что именно кешировать. Ограничение — четыре явные точки прерывания. Рекомендуется использовать их для больших объёмов текста, таких как карточки персонажей, CSV‑данные, RAG‑данные, главы книг и т.д. **Автоматическое кеширование** (верхний уровень `cache_control`) поддерживается только когда запросы направляются непосредственно к провайдеру **Anthropic**. Amazon Bedrock и Google Vertex AI в настоящее время не поддерживают `cache_control` верхнего уровня — когда он присутствует, **VEGA** будет направлять запросы только к провайдеру Anthropic и исключать конечные точки Bedrock и Vertex. Явные точки прерывания `cache_control` на уровне блоков работают со всеми совместимыми с Anthropic провайдерами, включая Bedrock и Vertex. **Поддержка Responses API:** [Responses API](/docs/api-reference/responses/create-a-model-response) поддерживает только **автоматическое кеширование** через `cache_control` верхнего уровня. Явные точки прерывания `cache_control` внутри элементов `input` **не** доступны через Responses API — используйте [Chat Completions](/docs/api-reference/chat/create-a-chat-completion) или [Anthropic Messages](/docs/api-reference/messages/create-a-message) API, если нужны тонкие точки прерывания. По умолчанию кеш истекает через 5 минут, но вы можете увеличить срок до 1 часа, указав `"ttl": "1h"` в объекте `cache_control`. [Нажмите здесь, чтобы узнать больше о кешировании подсказок Anthropic и его ограничениях.](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) ### Минимальные требования к токенам У каждой модели есть минимальная длина подсказки, пригодной для кеширования (см. [ограничения кеша Anthropic](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations)): * **4 096 токенов**: Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Opus 4.5, Claude Haiku 4.5 * **2 048 токенов**: Claude Haiku 3.5 * **1 024 токена**: Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4 Подсказки короче этих минимумов не будут кешироваться. ### Параметры TTL кеша **VEGA** поддерживает два значения TTL кеша для Anthropic: * **5 минут** (по умолчанию): `"cache_control": { "type": "ephemeral" }` * **1 час**: `"cache_control": { "type": "ephemeral", "ttl": "1h" }` TTL в 1 час полезен для длительных сессий, когда необходимо сохранять кешированный контент между несколькими запросами без повторных расходов на запись в кеш. TTL в 1 час стоит дороже при записях в кеш (2x базовой цены ввода против 1.25x для TTL 5 минут), но может экономить деньги в длительных сессиях, избегая повторных записей в кеш. TTL в 1 час для явных точек прерывания кеша поддерживается всеми провайдерами моделей Claude (Anthropic, Amazon Bedrock и Google Vertex AI). ### Примеры #### Автоматическое кеширование (рекомендовано для многошаговых диалогов) При автоматическом кешировании добавьте `cache_control` на верхний уровень запроса. Система автоматически кеширует весь контент до последнего кешируемого блока: ```json { "model": "~anthropic/claude-sonnet-latest", "cache_control": { "type": "ephemeral" }, "messages": [ { "role": "system", "content": "You are a historian studying the fall of the Roman Empire. You know the following book very well: HUGE TEXT BODY" }, { "role": "user", "content": "What triggered the collapse?" } ] } ``` По мере роста беседы точка прерывания кеша автоматически продвигается, охватывая растущую историю сообщений. Автоматическое кеширование с TTL 1 час: ```json { "model": "~anthropic/claude-sonnet-latest", "cache_control": { "type": "ephemeral", "ttl": "1h" }, "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "What is the meaning of life?" } ] } ``` #### Явные точки прерывания кеша (тонкая настройка) Пример кеширования системного сообщения (TTL по умолчанию 5 минут): ```json { "messages": [ { "role": "system", "content": [ { "type": "text", "text": "You are a historian studying the fall of the Roman Empire. You know the following book very well:" }, { "type": "text", "text": "HUGE TEXT BODY", "cache_control": { "type": "ephemeral" } } ] }, { "role": "user", "content": [ { "type": "text", "text": "What triggered the collapse?" } ] } ] } ``` Пример кеширования пользовательского сообщения с TTL 1 час: ```json { "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Given the book below:" }, { "type": "text", "text": "HUGE TEXT BODY", "cache_control": { "type": "ephemeral", "ttl": "1h" } }, { "type": "text", "text": "Name all the characters in the above book" } ] } ] } ``` ## DeepSeek Изменения цен на кеширование: * **Запись в кеш**: стоимость такая же, как у оригинального ввода * **Чтение из кеша**: стоимость {DEEPSEEK_CACHE_READ_MULTIPLIER}x цены оригинального ввода Кеширование подсказок в DeepSeek автоматизировано и не требует дополнительной настройки. ## Google Gemini ### Неявное кеширование Модели Gemini 2.5 Pro и 2.5 Flash теперь поддерживают **неявное кеширование**, предоставляя автоматическую функцию кеширования, аналогичную автоматическому кешированию OpenAI. Неявное кеширование работает без проблем — не требуется ручная настройка или дополнительные точки прерывания `cache_control`. Изменения цен: * Нет расходов на запись в кеш или хранение. * Кешированные токены стоят {GOOGLE_CACHE_READ_MULTIPLIER}x оригинальной цены за ввод. Обратите внимание, что TTL в среднем 3‑5 минут, но может варьироваться. Для Gemini 2.5 Flash требуется минимум {GOOGLE_CACHE_MIN_TOKENS_2_5_FLASH} токенов, а для Gemini 2.5 Pro — минимум {GOOGLE_CACHE_MIN_TOKENS_2_5_PRO} токенов, чтобы запросы могли быть кешированы. [Официальное объявление от Google](https://developers.googleblog.com/en/gemini-2-5-models-now-support-implicit-caching/) Чтобы максимизировать попадания в неявный кеш, сохраняйте начальную часть массивов сообщений одинаковой между запросами. Вариации (например, вопросы пользователя или динамические элементы контекста) размещайте ближе к концу подсказки/запросов. ### Изменения цен для кешированных запросов: * **Запись в кеш:** Стоимость равна цене токенов ввода плюс 5 минут хранения кеша, рассчитывается так: ``` Cache write cost = Input token price + (Cache storage price × (5 minutes / 60 minutes)) ``` * **Чтение из кеша:** Стоимость {GOOGLE_CACHE_READ_MULTIPLIER}× оригинальной цены токенов ввода. ### Поддерживаемые модели и ограничения Только некоторые модели Gemini поддерживают кеширование. Пожалуйста, обратитесь к [документации по ценам Gemini API от Google](https://ai.google.dev/gemini-api/docs/pricing) для актуальной информации. Записи в кеш имеют время жизни (TTL) 5 минут, которое не обновляется. По истечении 5 минут кеш истекает и необходимо создать новый кеш. У моделей Gemini обычно минимум 4096 токенов для записи в кеш. Кешированные токены учитываются в максимальном лимите токенов модели. Gemini 2.5 Pro имеет минимум {GOOGLE_CACHE_MIN_TOKENS_2_5_PRO} токенов, а Gemini 2.5 Flash — минимум {GOOGLE_CACHE_MIN_TOKENS_2_5_FLASH} токенов. ### Как работает кеширование подсказок Gemini в **VEGA**: **VEGA** упрощает управление кешем Gemini, абстрагируя сложности: * Вам **не нужно** вручную создавать, обновлять или удалять кеши. * Вам **не нужно** явно управлять именами кешей или TTL. ### Как включить кеширование подсказок Gemini: Кеширование Gemini в **VEGA** требует явного вставления точек прерывания `cache_control` в содержимое сообщений, аналогично Anthropic. Мы рекомендуем использовать кеширование в основном для больших фрагментов контента (например, CSV‑файлы, объёмные карточки персонажей, данные RAG или обширные текстовые источники). Нет ограничения на количество точек прерывания `cache_control`, которые вы можете включить в запрос. **VEGA** будет использовать только последнюю точку прерывания для кеширования Gemini в обычном содержимом сообщений. Включение нескольких точек прерывания безопасно и может помочь поддерживать совместимость с Anthropic, но только последняя будет использована для Gemini. У Gemini есть единственное поле `systemInstruction`, и кешированный контент Gemini рассматривает его как неизменяемый. В **VEGA** это означает, что `cache_control` внутри первого сообщения `system` или `developer` может кешировать нормализованную системную подсказку, но не может сохранять некешируемый динамический хвост в том же сообщении. Если вам нужно, чтобы часть подсказки оставалась динамичной, переместите динамический контент в более позднее сообщение `user`, а не добавляйте его после кешируемого блока в первом сообщении `system`. ### Примеры #### Пример кеширования системного сообщения ```json { "messages": [ { "role": "system", "content": [ { "type": "text", "text": "You are a historian studying the fall of the Roman Empire. Below is an extensive reference book:" }, { "type": "text", "text": "HUGE TEXT BODY HERE", "cache_control": { "type": "ephemeral" } } ] }, { "role": "user", "content": [ { "type": "text", "text": "What triggered the collapse?" } ] } ] } ``` Этот шаблон работает, когда кешируемый системный контент стабилен между запросами. Если нужен динамический сегмент подсказки, разместите его в более позднем сообщении `user`, а не как некешируемый завершающий контент в первом сообщении `system`. #### Пример кеширования пользовательского сообщения ```json { "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Based on the book text below:" }, { "type": "text", "text": "HUGE TEXT BODY HERE", "cache_control": { "type": "ephemeral" } }, { "type": "text", "text": "List all main characters mentioned in the text above." } ] } ] } ```