Cache explícito do Gemini (cachedContents)

O Gemini oferece dois tipos de cache:

• Cache implícito (automático) — o modelo detecta e reutiliza automaticamente prefixos de prompt repetidos, sem nenhuma configuração. Esse é o comportamento padrão descrito em Cache de prompt; os acertos são best-effort, e qualquer pequena alteração no prefixo pode causar um miss.
• Cache explícito (esta página) — você ativamente cria um grande bloco de contexto como um objeto de cache, recebe um handle cachedContents/{id} e o referencia nas requisições generateContent seguintes. Os acertos são determinísticos: enquanto o cache não expirar, uma referência sempre acerta.

Use o cache explícito quando você tem um contexto grande e estável reutilizado repetidamente (documentos longos, bases de código, bases de conhecimento, instruções de system fixas) e quer taxas de acerto controláveis e faturamento previsível.

Quando usar o cache explícito

Endpoints

O OfoxAI fornece os endpoints completos de cachedContents sob o protocolo nativo do Gemini:

POST   https://api.ofox.ai/gemini/v1beta/cachedContents              # Criar
GET    https://api.ofox.ai/gemini/v1beta/cachedContents/{id}         # Consultar
DELETE https://api.ofox.ai/gemini/v1beta/cachedContents/{id}         # Excluir

Para referenciar um cache na geração de conteúdo, use o endpoint padrão generateContent e adicione cachedContent ao corpo da requisição:

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

Autenticação

Como nos demais endpoints do Gemini, use o header x-goog-api-key:

x-goog-api-key: <Sua OFOXAI_API_KEY>

Fluxo completo

O exemplo a seguir demonstra um fluxo completo: criar cache → referenciar o cache para gerar → excluir o cache.

1. Criar um cache

Coloque o grande contexto que você quer reutilizar em contents e especifique model e ttl (tempo de vida):

from google import genai
from google.genai import types
 
client = genai.Client(
    api_key="<Sua OFOXAI_API_KEY>",
    http_options={"api_version": "v1beta", "base_url": "https://api.ofox.ai/gemini"},
)
 
# Um documento grande reutilizado repetidamente (deve atingir o limite mínimo de tokens)
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",  # o cache vive por 10 minutos
    ),
)
 
print(cache.name)  # cachedContents/xxxxxxxx — o handle para referências futuras

import { GoogleGenAI } from '@google/genai'
import fs from 'node:fs'
 
const ai = new GoogleGenAI({
  apiKey: '<Sua 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', // o cache vive por 10 minutos
  },
})
 
console.log(cache.name) // cachedContents/xxxxxxxx — o handle para referências futuras

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": "<coloque aqui um grande bloco de contexto a reutilizar>" }] }
    ],
    "ttl": "600s"
  }'

O name retornado (no formato cachedContents/xxxxxxxx) é o handle do cache. Salve-o para referências e gerenciamento futuros.

2. Referenciar o cache para gerar

Referencie o handle do cache via cachedContent em uma requisição generateContent; contents só precisa conter a nova pergunta desta vez:

response = client.models.generate_content(
    model="google/gemini-3.1-pro-preview",
    contents="Com base no documento acima, resuma três pontos principais",
    config=types.GenerateContentConfig(
        cached_content=cache.name,  # referencia o cache
    ),
)
 
print(response.text)
# Cache hit: a parte em cache é cobrada pela tarifa de "leitura" mais baixa
print(response.usage_metadata.cached_content_token_count)

const response = await ai.models.generateContent({
  model: 'google/gemini-3.1-pro-preview',
  contents: 'Com base no documento acima, resuma três pontos principais',
  config: {
    cachedContent: cache.name, // referencia o cache
  },
})
 
console.log(response.text)
// Cache hit: a parte em cache é cobrada pela tarifa de "leitura" mais baixa
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": "Com base no documento acima, resuma três pontos principais" }] }
    ]
  }'

No acerto, o usageMetadata.cachedContentTokenCount da resposta mostra quantos tokens vieram do cache. O mesmo cache pode ser referenciado qualquer número de vezes, cada uma com acerto determinístico, até expirar.

3. Consultar e excluir

Consulte os metadados do cache ou exclua-o proativamente quando não for mais necessário (sem precisar esperar o TTL expirar):

# Consultar
info = client.caches.get(name=cache.name)
print(info.expire_time)
 
# Excluir
client.caches.delete(name=cache.name)

// Consultar
const info = await ai.caches.get({ name: cache.name })
console.log(info.expireTime)
 
// Excluir
await ai.caches.delete({ name: cache.name })

# Consultar
curl "https://api.ofox.ai/gemini/v1beta/cachedContents/xxxxxxxx" \
  -H "x-goog-api-key: $OFOX_API_KEY"
 
# Excluir
curl -X DELETE "https://api.ofox.ai/gemini/v1beta/cachedContents/xxxxxxxx" \
  -H "x-goog-api-key: $OFOX_API_KEY"

Ciclo de vida e TTL

Especifique o tempo de vida via ttl na criação, como uma string de segundos terminada em s (por exemplo, "600s").

• Dentro do TTL, o cache pode ser referenciado repetidamente com acertos determinísticos.
• Após o TTL expirar, o cache é invalidado automaticamente, e referenciá-lo gerará erro (o cache não existe mais).
• Você pode delete a qualquer momento para liberá-lo antecipadamente.

Faturamento

O cache explícito é cobrado de forma transparente por token, em três partes:

Aprimoramento no OfoxAI: roteamento determinístico

O OfoxAI faz balanceamento de carga entre várias regiões GCP / projetos Vertex. Os caches explícitos são region-scoped (vinculados à região): um cache criado em um projeto GCP deve ser referenciado no mesmo projeto, caso contrário retorna 404.

O OfoxAI trata isso automaticamente: na criação, registra a instância upstream à qual o cache está vinculado e, depois, busca essa instância pelo handle do cache e trava (hard-lock) as referências de volta ao mesmo upstream. Independentemente de a requisição de referência levar ou não um identificador de user, e de como a carga é distribuída, as referências são roteadas com precisão para o projeto que criou o cache, com zero drift. Você não precisa se preocupar com a distribuição de regiões subjacente.

Cache explícito vs cache implícito

Documentos relacionados

• Cache de prompt (cache implícito / visão geral entre protocolos)
• API generateContent do Gemini
• Catálogo de modelos e preços