Явное кэширование Gemini (cachedContents)

Кэширование в Gemini бывает двух видов:

• Неявное кэширование (автоматическое) — модель сама обнаруживает и переиспользует повторяющиеся префиксы промптов, без какой-либо настройки. Это поведение по умолчанию, описанное в статье Кэширование промптов; попадание работает по принципу «best-effort», и любое незначительное изменение префикса может привести к промаху.
• Явное кэширование (эта статья) — вы самостоятельно создаёте из большого контекста объект-кэш, получаете дескриптор cachedContents/{id} и ссылаетесь на него в последующих запросах generateContent. Попадание детерминированное: пока кэш не истёк, ссылка всегда попадает.

Используйте явное кэширование, когда у вас есть большой, стабильный контекст, который переиспользуется многократно (длинные документы, кодовые базы, базы знаний, фиксированные system-инструкции) и нужны управляемый показатель попаданий и предсказуемая тарификация.

Когда использовать явное кэширование

Эндпоинты

OfoxAI предоставляет полный набор эндпоинтов cachedContents в нативном протоколе Gemini:

POST   https://api.ofox.ai/gemini/v1beta/cachedContents              # Создание
GET    https://api.ofox.ai/gemini/v1beta/cachedContents/{id}         # Запрос
DELETE https://api.ofox.ai/gemini/v1beta/cachedContents/{id}         # Удаление

Для ссылки на кэш при генерации контента используется стандартный эндпоинт generateContent — в тело запроса добавляется cachedContent:

POST   https://api.ofox.ai/gemini/v1beta/models/{model}:generateContent

Аутентификация

Как и в других эндпоинтах Gemini, используйте заголовок x-goog-api-key:

x-goog-api-key: <Ваш OFOXAI_API_KEY>

Полный сценарий

Ниже показан полный путь: создание кэша → генерация со ссылкой на кэш → удаление кэша.

1. Создание кэша

Поместите большой контекст для переиспользования в contents и укажите model и ttl (время жизни):

from google import genai
from google.genai import types
 
client = genai.Client(
    api_key="<Ваш OFOXAI_API_KEY>",
    http_options={"api_version": "v1beta", "base_url": "https://api.ofox.ai/gemini"},
)
 
# Большой документ для многократного переиспользования (должен достигать минимального порога по токенам)
LONG_DOCUMENT = open("knowledge_base.txt").read()
 
cache = client.caches.create(
    model="google/gemini-3.1-pro-preview",
    config=types.CreateCachedContentConfig(
        contents=[LONG_DOCUMENT],
        ttl="600s",  # кэш живёт 10 минут
    ),
)
 
print(cache.name)  # cachedContents/xxxxxxxx — дескриптор для последующих ссылок

import { GoogleGenAI } from '@google/genai'
import fs from 'node:fs'
 
const ai = new GoogleGenAI({
  apiKey: '<Ваш OFOXAI_API_KEY>',
  httpOptions: { apiVersion: 'v1beta', baseUrl: 'https://api.ofox.ai/gemini' },
})
 
const longDocument = fs.readFileSync('knowledge_base.txt', 'utf-8')
 
const cache = await ai.caches.create({
  model: 'google/gemini-3.1-pro-preview',
  config: {
    contents: [longDocument],
    ttl: '600s', // кэш живёт 10 минут
  },
})
 
console.log(cache.name) // cachedContents/xxxxxxxx — дескриптор для последующих ссылок

curl "https://api.ofox.ai/gemini/v1beta/cachedContents" \
  -H "x-goog-api-key: $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.1-pro-preview",
    "contents": [
      { "role": "user", "parts": [{ "text": "<сюда поместите большой блок контекста для переиспользования>" }] }
    ],
    "ttl": "600s"
  }'

Возвращаемое поле name (вида cachedContents/xxxxxxxx) — это дескриптор кэша; сохраните его для последующих ссылок и управления.

2. Генерация со ссылкой на кэш

В запросе generateContent сошлитесь на дескриптор кэша через cachedContent; в contents достаточно поместить только новый вопрос этого хода:

response = client.models.generate_content(
    model="google/gemini-3.1-pro-preview",
    contents="На основе документа выше сформулируй три ключевых тезиса",
    config=types.GenerateContentConfig(
        cached_content=cache.name,  # ссылка на кэш
    ),
)
 
print(response.text)
# Попадание в кэш: кэшированная часть тарифицируется по более низкой цене «чтения»
print(response.usage_metadata.cached_content_token_count)

const response = await ai.models.generateContent({
  model: 'google/gemini-3.1-pro-preview',
  contents: 'На основе документа выше сформулируй три ключевых тезиса',
  config: {
    cachedContent: cache.name, // ссылка на кэш
  },
})
 
console.log(response.text)
// Попадание в кэш: кэшированная часть тарифицируется по более низкой цене «чтения»
console.log(response.usageMetadata?.cachedContentTokenCount)

curl "https://api.ofox.ai/gemini/v1beta/models/google/gemini-3.1-pro-preview:generateContent" \
  -H "x-goog-api-key: $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cachedContent": "cachedContents/xxxxxxxx",
    "contents": [
      { "role": "user", "parts": [{ "text": "На основе документа выше сформулируй три ключевых тезиса" }] }
    ]
  }'

При попадании поле ответа usageMetadata.cachedContentTokenCount показывает число токенов, взятых из кэша. На один и тот же кэш можно ссылаться сколько угодно раз, каждый раз с детерминированным попаданием, пока он не истечёт.

3. Запрос и удаление

Запросите метаданные кэша или удалите его заранее, когда он больше не нужен (ждать истечения TTL не обязательно):

# Запрос
info = client.caches.get(name=cache.name)
print(info.expire_time)
 
# Удаление
client.caches.delete(name=cache.name)

// Запрос
const info = await ai.caches.get({ name: cache.name })
console.log(info.expireTime)
 
// Удаление
await ai.caches.delete({ name: cache.name })

# Запрос
curl "https://api.ofox.ai/gemini/v1beta/cachedContents/xxxxxxxx" \
  -H "x-goog-api-key: $OFOX_API_KEY"
 
# Удаление
curl -X DELETE "https://api.ofox.ai/gemini/v1beta/cachedContents/xxxxxxxx" \
  -H "x-goog-api-key: $OFOX_API_KEY"

Жизненный цикл и TTL

При создании укажите время жизни через ttl — строкой с числом секунд, оканчивающейся на s (например, "600s").

• В пределах TTL на кэш можно ссылаться многократно с детерминированными попаданиями.
• По истечении TTL кэш автоматически становится недействительным, и ссылка на него вернёт ошибку (кэша больше нет).
• В любой момент можно выполнить delete, чтобы освободить его заранее.

Тарификация

Явное кэширование тарифицируется прозрачно по токенам и состоит из трёх частей:

Усиление в OfoxAI: детерминированная маршрутизация

OfoxAI балансирует нагрузку между несколькими регионами GCP / проектами Vertex. Явный кэш привязан к региону (region-scoped): в каком проекте GCP кэш создан, в том же проекте он и должен попадать по ссылке, иначе вернётся 404.

OfoxAI обрабатывает это автоматически: при создании кэша записывается привязанный к нему upstream-инстанс, после чего по дескриптору кэша он находится и жёстко фиксируется обратно на тот же upstream. Независимо от того, несёт ли ваш запрос-ссылка идентификатор user и как распределяется нагрузка, ссылка точно маршрутизируется в проект, где был создан кэш, с нулевым дрейфом. Вам не нужно думать о нижележащем распределении по регионам.

Явное против неявного кэширования

Связанные документы

• Кэширование промптов (неявное кэширование / обзор по протоколам)
• API Gemini generateContent
• Каталог моделей и тарифы