← Cloudflare AI Gateway / ai-gateway / features

Кеширование

Когда кэширование включено, AI Gateway может кэшировать ответы от ваших провайдеров ИИ-моделей и отдавать их напрямую из кэша Cloudflare для идентичных запросов.

• Меньшая задержка: Обслуживайте пользователей быстрее, избегая обращения к исходному AI-провайдеру при повторных запросах.
• Экономия затрат: Сведите к минимуму количество платных запросов к вашему AI-провайдеру, особенно для часто запрашиваемого или статичного контента.
• Повышенная пропускная способность: Разгрузите вашего AI-провайдера от повторяющихся запросов, чтобы он мог эффективнее обрабатывать уникальные запросы.

Кэширование отключено по умолчанию. Чтобы включить кэширование глобально, задайте конфигурацию кэширования по умолчанию:

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

Чтобы проверить, пришёл ли ответ из кэша, cf-aig-cache-status будет обозначен как HIT или MISS.

По умолчанию AI Gateway формирует ключ кэша, объединяя следующее и хешируя результат с помощью SHA-256:

• Провайдер (например, openai, anthropic)
• Конечная точка (путь API)
• Модель (например, gpt-4o)
• Заголовок аутентификации провайдера (например, Authorization bearer-токен)
• Полное тело запроса

Это означает, что кэширование основано на точное совпадение всего запроса. Любое различие в теле запроса, включая сообщения, инструменты или параметры модели, приведёт к созданию отдельной записи кеша. Чтобы изменить это поведение, используйте заголовок пользовательского ключа кеша.

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

Чтобы удовлетворить эти потребности, AI Gateway позволяет переопределять поведение кэширования по умолчанию для каждого запроса с помощью специальных HTTP-заголовков. Это даёт точный контроль для оптимизации кэширования отдельных вызовов API.

Следующие заголовки позволяют задать это поведение кэширования на уровне запроса:

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

Вы можете использовать заголовок cf-aig-skip-cache чтобы пропустить кешированную версию запроса.

Например, при отправке запроса в OpenAI укажите заголовок следующим образом:

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "cf-aig-skip-cache: true" \
  --data '{
    "model": "openai/gpt-4.1-mini",
    "messages": [
      {
        "role": "user",
        "content": "how to build a wooden spoon in 3 short steps? give as short as answer as possible"
      }
    ]
  }'

Cache TTL, или Time To Live (время жизни), это время, в течение которого кэшированный запрос остается действительным до истечения срока и обновления из исходного источника. Используйте cf-aig-cache-ttl чтобы задать длительность кеширования для запроса, который уже использует кеширование. Чтобы включить кеширование для отдельного запроса, добавьте cf-aig-cache-key. Минимальный TTL составляет 60 секунд, а максимальный TTL составляет один месяц.

Например, если вы установите TTL в один час, это означает, что запрос будет храниться в кэше в течение часа. В течение этого часа идентичный запрос будет обслуживаться из кэша, а не из исходного API. Через час срок действия кэша истечёт, и запрос отправится в исходный API для получения свежего ответа, который снова заполнит кэш на следующий час.

Например, при отправке запроса в OpenAI укажите заголовок следующим образом:

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
# Use a key shared only by requests with equivalent responses.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "cf-aig-cache-key: responseWithCustomTtl" \
  --header "cf-aig-cache-ttl: 3600" \
  --data '{
    "model": "openai/gpt-4.1-mini",
    "messages": [
      {
        "role": "user",
        "content": "how to build a wooden spoon in 3 short steps? give as short as answer as possible"
      }
    ]
  }'

cf-aig-cache-key заголовок позволяет переопределить ключ кеша по умолчанию и включить кеширование для запроса.

Выберите пользовательский ключ, который группирует только запросы с эквивалентными ответами. Запросы с одинаковым пользовательским ключом используют общий кэшированный ответ. При использовании cf-aig-cache-key заголовок в первый раз, вы получите ответ от провайдера. Последующие запросы с тем же значением пользовательского ключа будут возвращать закешированный ответ. Если вы укажете cf-aig-cache-ttl, запрос использует это значение в качестве TTL кеша. В противном случае запрос использует TTL кеша по умолчанию, настроенный для шлюза. Для запросов, которые включают cf-aig-cache-key, TTL кеша составляет 5 минут, если ни cf-aig-cache-ttl ни TTL кеша шлюза по умолчанию не настроен.

Например, при отправке запроса в OpenAI укажите заголовок следующим образом:

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "cf-aig-cache-key: responseA" \
  --data '{
    "model": "openai/gpt-4.1-mini",
    "messages": [
      {
        "role": "user",
        "content": "how to build a wooden spoon in 3 short steps? give as short as answer as possible"
      }
    ]
  }'