El almacenamiento de contexto en caché

En un flujo de trabajo típico de IA, es posible que pases los mismos tokens de entrada una y otra vez a un modelo. La API de Gemini ofrece dos mecanismos de almacenamiento en caché diferentes:

  • Almacenamiento en caché implícito (se habilita automáticamente en los modelos de Gemini 2.5, sin garantía de ahorro de costos)
  • Almacenamiento en caché explícito (se puede habilitar manualmente en la mayoría de los modelos, garantía de ahorro de costos)

El almacenamiento en caché explícito es útil en los casos en los que deseas garantizar el ahorro de costos, pero con algo de trabajo adicional para el desarrollador.

Almacenamiento en caché implícito

El almacenamiento en caché implícito está habilitado de forma predeterminada para todos los modelos de Gemini 2.5. Si tu solicitud llega a las memorias caché, te transferimos automáticamente los ahorros en costos. No es necesario que realices ninguna acción para habilitar esta función. Entrará en vigencia el 8 de mayo de 2025. En la siguiente tabla, se indica la cantidad mínima de tokens de entrada para el almacenamiento en caché del contexto de cada modelo:

Modelo Límite mínimo de tokens
Versión preliminar de Gemini 3 Pro 4096
Gemini 2.5 Pro 4096
Gemini 2.5 Flash 1024

Para aumentar las probabilidades de un acierto de caché implícito, haz lo siguiente:

  • Intenta colocar contenido grande y común al principio de tu instrucción.
  • Intenta enviar solicitudes con prefijos similares en un corto período

Puedes ver la cantidad de tokens que fueron aciertos de caché en el campo usage_metadata del objeto de respuesta.

Almacenamiento en caché explícito

Con la función de almacenamiento explícito en caché de la API de Gemini, puedes pasar contenido al modelo una vez, almacenar en caché los tokens de entrada y, luego, hacer referencia a los tokens almacenados en caché para las solicitudes posteriores. Con ciertos volúmenes, usar tokens almacenados en caché es más económico que pasar el mismo corpus de tokens de forma repetida.

Cuando almacenas en caché un conjunto de tokens, puedes elegir cuánto tiempo quieres que exista la caché antes de que los tokens se borren automáticamente. Esta duración del almacenamiento en caché se denomina tiempo de actividad (TTL). Si no se establece, el TTL predeterminado es de 1 hora. El costo del almacenamiento en caché depende del tamaño de los tokens de entrada y del tiempo que desees que persistan los tokens.

En esta sección, se supone que instalaste un SDK de Gemini (o que tienes curl instalado) y que configuraste una clave de API, como se muestra en la guía de inicio rápido.

Genera contenido con una caché

En el siguiente ejemplo, se muestra cómo crear una caché y, luego, usarla para generar contenido.

Videos

wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
  "model": "models/gemini-2.0-flash-001",
  "contents":[
    {
      "parts":[
        {
          "inline_data": {
            "mime_type":"text/plain",
            "data": "'$(base64 $B64FLAGS a11.txt)'"
          }
        }
      ],
    "role": "user"
    }
  ],
  "systemInstruction": {
    "parts": [
      {
        "text": "You are an expert at analyzing transcripts."
      }
    ]
  },
  "ttl": "300s"
}' > request.json

curl -X POST "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d @request.json \
> cache.json

CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash-001:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [
        {
          "parts":[{
            "text": "Please summarize this transcript"
          }],
          "role": "user"
        },
      ],
      "cachedContent": "'$CACHE_NAME'"
    }'

PDF

DOC_URL="https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"
DISPLAY_NAME="A17_FlightPlan"
SYSTEM_INSTRUCTION="You are an expert at analyzing transcripts."
PROMPT="Please summarize this transcript"
MODEL="models/gemini-2.0-flash-001"
TTL="300s"

# Download the PDF
wget -O "${DISPLAY_NAME}.pdf" "${DOC_URL}"

MIME_TYPE=$(file -b --mime-type "${DISPLAY_NAME}.pdf")
NUM_BYTES=$(wc -c < "${DISPLAY_NAME}.pdf")

echo "MIME_TYPE: ${MIME_TYPE}"
echo "NUM_BYTES: ${NUM_BYTES}"

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GOOGLE_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${DISPLAY_NAME}.pdf" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo "file_uri: ${file_uri}"

# Clean up the downloaded PDF
rm "${DISPLAY_NAME}.pdf"

# Create the cached content request
echo '{
  "model": "'$MODEL'",
  "contents":[
    {
      "parts":[
        {"file_data": {"mime_type": "'$MIME_TYPE'", "file_uri": '$file_uri'}}
      ],
    "role": "user"
    }
  ],
  "system_instruction": {
    "parts": [
      {
        "text": "'$SYSTEM_INSTRUCTION'"
      }
    ],
    "role": "system"
  },
  "ttl": "'$TTL'"
}' > request.json

# Send the cached content request
curl -X POST "${BASE_URL}/v1beta/cachedContents?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d @request.json \
> cache.json

CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)
echo "CACHE_NAME: ${CACHE_NAME}"
# Send the generateContent request using the cached content
curl -X POST "${BASE_URL}/${MODEL}:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [
        {
          "parts":[{
            "text": "'$PROMPT'"
          }],
          "role": "user"
        }
      ],
      "cachedContent": "'$CACHE_NAME'"
    }' > response.json

cat response.json

echo jq ".candidates[].content.parts[].text" response.json

Enumera cachés

No es posible recuperar ni ver el contenido almacenado en caché, pero puedes recuperar los metadatos de la caché (name, model, displayName, usageMetadata, createTime, updateTime y expireTime).

curl "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY"

Actualiza una caché

Puedes establecer un nuevo ttl o expireTime para una caché. No se admite cambiar ningún otro aspecto de la caché.

En el siguiente ejemplo, se muestra cómo actualizar el ttl de una caché.

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{"ttl": "600s"}'

Borra una caché

El servicio de almacenamiento en caché proporciona una operación de eliminación para quitar contenido de la caché de forma manual. En el siguiente ejemplo, se muestra cómo borrar una caché.

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"

Almacenamiento en caché explícito con la biblioteca de OpenAI

Si usas una biblioteca de OpenAI, puedes habilitar el almacenamiento en caché explícito con la propiedad cached_content en extra_body.

Cuándo usar el almacenamiento en caché explícito

El almacenamiento en caché del contexto es especialmente adecuado para situaciones en las que las solicitudes más cortas hacen referencia repetidamente a un contexto inicial sustancial. Considera usar el almacenamiento en caché de contexto para casos de uso como los siguientes:

  • Chatbots con instrucciones del sistema detalladas
  • Análisis repetitivo de archivos de video extensos
  • Consultas recurrentes en grandes conjuntos de documentos
  • Análisis frecuente del repositorio de código o corrección de errores

Cómo el almacenamiento en caché explícito reduce los costos

El almacenamiento en caché del contexto es una función pagada diseñada para reducir los costos operativos generales. La facturación se basa en los siguientes factores:

  1. Cantidad de tokens almacenados en caché: Es la cantidad de tokens de entrada almacenados en caché, que se facturan a una tarifa reducida cuando se incluyen en instrucciones posteriores.
  2. Duración del almacenamiento: Es la cantidad de tiempo que se almacenan los tokens en caché (TTL), y se factura según la duración del TTL del recuento de tokens en caché. No hay límites mínimos ni máximos para el TTL.
  3. Otros factores: Se aplican otros cargos, como los de los tokens de entrada y salida no almacenados en caché.

Para obtener detalles actualizados sobre los precios, consulta la página de precios de la API de Gemini. Para obtener información sobre cómo contar tokens, consulta la Guía de tokens.

Consideraciones adicionales

Ten en cuenta las siguientes consideraciones cuando uses el almacenamiento en caché del contexto:

  • La cantidad mínima de tokens de entrada para el almacenamiento en caché del contexto es de 1,024 para 2.5 Flash, 4,096 para 2.5 Pro y 2,048 para 3 Pro Preview. El máximo es el mismo que el máximo para el modelo determinado. (Para obtener más información sobre el recuento de tokens, consulta la Guía de tokens).
  • El modelo no distingue entre los tokens almacenados en caché y los tokens de entrada normales. El contenido almacenado en caché es un prefijo de la instrucción.
  • No hay límites especiales de tarifas o uso para el almacenamiento en caché del contexto; se aplican los límites de tarifas estándar para GenerateContent, y los límites de tokens incluyen los tokens almacenados en caché.
  • La cantidad de tokens almacenados en caché se devuelve en usage_metadata desde las operaciones de creación, obtención y lista del servicio de caché, y también en GenerateContent cuando se usa la caché.