Caché explícito de Gemini (cachedContents)

Gemini ofrece dos tipos de caché:

• Caché implícito (automático) — el modelo detecta y reutiliza automáticamente los prefijos de prompt repetidos, sin necesidad de configuración. Este es el comportamiento por defecto que se trata en Caché de prompts; los aciertos son «best-effort» (de mejor esfuerzo), y cualquier pequeño cambio en el prefijo puede provocar un fallo de acierto.
• Caché explícito (esta página) — usted crea de forma activa un gran fragmento de contexto como un objeto de caché, recibe un identificador cachedContents/{id} y lo referencia en solicitudes generateContent posteriores. Los aciertos son deterministas: mientras el caché no haya expirado, una referencia siempre acierta.

Use el caché explícito cuando tenga un contexto grande y estable que se reutiliza repetidamente (documentos largos, bases de código, bases de conocimiento, instrucciones de sistema fijas) y quiera tasas de acierto controlables y facturación predecible.

Cuándo usar el caché explícito

Endpoints

OfoxAI ofrece los endpoints completos de cachedContents bajo el protocolo nativo de Gemini:

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

Para referenciar un caché en la generación de contenido, use el endpoint estándar generateContent y agregue cachedContent al cuerpo de la solicitud:

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

Autenticación

Al igual que los demás endpoints de Gemini, use el header x-goog-api-key:

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

Flujo completo

A continuación se muestra un flujo completo: crear caché → referenciar el caché para generar → eliminar el caché.

1. Crear un caché

Coloque en contents el gran contexto que desea reutilizar y especifique model y ttl (tiempo de vida):

from google import genai
from google.genai import types
 
client = genai.Client(
    api_key="<su OFOXAI_API_KEY>",
    http_options={"api_version": "v1beta", "base_url": "https://api.ofox.ai/gemini"},
)
 
# Un documento grande reutilizado repetidamente (debe alcanzar el umbral 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",  # el caché vive 10 minutos
    ),
)
 
print(cache.name)  # cachedContents/xxxxxxxx —— el identificador para referencias posteriores

import { GoogleGenAI } from '@google/genai'
import fs from 'node:fs'
 
const ai = new GoogleGenAI({
  apiKey: '<su 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', // el caché vive 10 minutos
  },
})
 
console.log(cache.name) // cachedContents/xxxxxxxx —— el identificador para referencias posteriores

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": "<un gran bloque de contexto para reutilizar>" }] }
    ],
    "ttl": "600s"
  }'

El name devuelto (con la forma cachedContents/xxxxxxxx) es el identificador del caché. Guárdelo para las referencias y la administración posteriores.

2. Referenciar el caché para generar

Referencie el identificador del caché mediante cachedContent en una solicitud generateContent; contents solo necesita la nueva pregunta de este turno:

response = client.models.generate_content(
    model="google/gemini-3.1-pro-preview",
    contents="Basándote en el documento anterior, resume tres puntos clave",
    config=types.GenerateContentConfig(
        cached_content=cache.name,  # referencia el caché
    ),
)
 
print(response.text)
# Acierto de caché: la parte cacheada se cobra a la tarifa de «lectura» más baja
print(response.usage_metadata.cached_content_token_count)

const response = await ai.models.generateContent({
  model: 'google/gemini-3.1-pro-preview',
  contents: 'Basándote en el documento anterior, resume tres puntos clave',
  config: {
    cachedContent: cache.name, // referencia el caché
  },
})
 
console.log(response.text)
// Acierto de caché: la parte cacheada se cobra a la tarifa de «lectura» más baja
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": "Basándote en el documento anterior, resume tres puntos clave" }] }
    ]
  }'

En un acierto, el usageMetadata.cachedContentTokenCount de la respuesta muestra cuántos tokens provienen del caché. El mismo caché puede referenciarse cualquier número de veces, cada una con un acierto determinista, hasta que expire.

3. Consultar y eliminar

Consulte los metadatos del caché, o elimínelo de forma proactiva cuando ya no lo necesite (sin esperar a que el TTL expire):

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

// Consultar
const info = await ai.caches.get({ name: cache.name })
console.log(info.expireTime)
 
// Eliminar
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"
 
# Eliminar
curl -X DELETE "https://api.ofox.ai/gemini/v1beta/cachedContents/xxxxxxxx" \
  -H "x-goog-api-key: $OFOX_API_KEY"

Ciclo de vida y TTL

Especifique el tiempo de vida mediante ttl al crear, como una cadena de segundos terminada en s (p. ej. "600s").

• Dentro del TTL, el caché puede referenciarse repetidamente con aciertos deterministas.
• Tras expirar el TTL, el caché se invalida automáticamente y referenciarlo dará error (el caché ya no existe).
• Puede delete en cualquier momento para liberarlo anticipadamente.

Facturación

El caché explícito se factura de forma transparente por token, en tres partes:

Mejora en OfoxAI: enrutamiento determinista

OfoxAI balancea la carga entre múltiples regiones de GCP / proyectos de Vertex. Los cachés explícitos son region-scoped (vinculados a la región): un caché creado en un proyecto de GCP debe referenciarse en ese mismo proyecto, de lo contrario dará 404.

OfoxAI gestiona esto automáticamente: al crear el caché, registra la instancia upstream a la que está vinculado, y luego busca esa instancia por el identificador del caché y fija de forma rígida las referencias de vuelta al mismo upstream. Independientemente de si su solicitud de referencia lleva un identificador de usuario o de cómo se programe la carga, las referencias se enrutan con precisión al proyecto que creó el caché, con cero deriva. No necesita preocuparse por la distribución de regiones subyacente.

Caché explícito vs. caché implícito

Documentación relacionada

• Caché de prompts (caché implícito / visión general entre protocolos)
• Gemini generateContent API
• Catálogo de modelos y precios