El almacenamiento de contexto en caché

En un flujo de trabajo de IA típico, puedes pasar 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 (automático, sin garantía de ahorro de costos)
  • Almacenamiento en caché explícito (manual, garantía de ahorro de costos)

El almacenamiento en caché implícito está habilitado de forma predeterminada en los modelos Gemini 2.5. Si una solicitud contiene contenido que es un acierto de caché, te reenviamos automáticamente el ahorro de costos.

La caché explícita es útil en los casos en los que deseas garantizar ahorros en costos, pero con un trabajo adicional del 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. Transferimos automáticamente los ahorros de costos si tu solicitud llega a las cachés. No es necesario que realices ninguna acción para habilitar esta función. Entrará en vigencia el 8 de mayo de 2025. El recuento mínimo de tokens de entrada para la caché de contexto es de 1,024 para Flash 2.5 y de 2,048 para Flash 2.5 Pro.

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

  • Intenta colocar contenido grande y común al comienzo de la instrucción.
  • Intenta enviar solicitudes con un prefijo similar en un período breve.

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

Almacenamiento en caché explícito

Con la función de almacenamiento en caché explícita de la API de Gemini, puedes pasar cierto contenido al modelo una vez, almacenar en caché los tokens de entrada y, luego, consultar los tokens almacenados en caché para las solicitudes posteriores. En ciertos volúmenes, usar tokens almacenados en caché tiene un costo más bajo que pasar el mismo corpus de tokens de forma reiterada.

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

En esta sección, se supone que instalaste un SDK de Gemini (o tienes instalado curl) 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 generar contenido con una instrucción del sistema y un archivo de video almacenados en caché.

Videos

import os
import pathlib
import requests
import time

from google import genai
from google.genai import types

client = genai.Client()

# Download video file
url = 'https://storage.googleapis.com/generativeai-downloads/data/SherlockJr._10min.mp4'
path_to_video_file = pathlib.Path('SherlockJr._10min.mp4')
if not path_to_video_file.exists():
  with path_to_video_file.open('wb') as wf:
    response = requests.get(url, stream=True)
    for chunk in response.iter_content(chunk_size=32768):
      wf.write(chunk)

# Upload the video using the Files API
video_file = client.files.upload(file=path_to_video_file)

# Wait for the file to finish processing
while video_file.state.name == 'PROCESSING':
  print('Waiting for video to be processed.')
  time.sleep(2)
  video_file = client.files.get(name=video_file.name)

print(f'Video processing complete: {video_file.uri}')

# You must use an explicit version suffix: "-flash-001", not just "-flash".
model='models/gemini-2.0-flash-001'

# Create a cache with a 5 minute TTL
cache = client.caches.create(
    model=model,
    config=types.CreateCachedContentConfig(
      display_name='sherlock jr movie', # used to identify the cache
      system_instruction=(
          'You are an expert video analyzer, and your job is to answer '
          'the user\'s query based on the video file you have access to.'
      ),
      contents=[video_file],
      ttl="300s",
  )
)

# Construct a GenerativeModel which uses the created cache.
response = client.models.generate_content(
  model = model,
  contents= (
    'Introduce different characters in the movie by describing '
    'their personality, looks, and names. Also list the timestamps '
    'they were introduced for the first time.'),
  config=types.GenerateContentConfig(cached_content=cache.name)
)

print(response.usage_metadata)

# The output should look something like this:
#
# prompt_token_count: 696219
# cached_content_token_count: 696190
# candidates_token_count: 214
# total_token_count: 696433

print(response.text)

PDF

from google import genai
from google.genai import types
import io
import httpx

client = genai.Client()

long_context_pdf_path = "https://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"

# Retrieve and upload the PDF using the File API
doc_io = io.BytesIO(httpx.get(long_context_pdf_path).content)

document = client.files.upload(
  file=doc_io,
  config=dict(mime_type='application/pdf')
)

model_name = "gemini-2.0-flash-001"
system_instruction = "You are an expert analyzing transcripts."

# Create a cached content object
cache = client.caches.create(
    model=model_name,
    config=types.CreateCachedContentConfig(
      system_instruction=system_instruction,
      contents=[document],
    )
)

# Display the cache details
print(f'{cache=}')

# Generate content using the cached prompt and document
response = client.models.generate_content(
  model=model_name,
  contents="Please summarize this transcript",
  config=types.GenerateContentConfig(
    cached_content=cache.name
  ))

# (Optional) Print usage metadata for insights into the API call
print(f'{response.usage_metadata=}')

# Print the generated text
print('\n\n', response.text)

Enumera las cachés

No es posible recuperar ni ver el contenido almacenado en caché, pero puedes recuperar los metadatos de la caché (name, model, display_name, usage_metadata, create_time, update_time y expire_time).

Para enumerar los metadatos de todas las cachés subidas, usa CachedContent.list():

for cache in client.caches.list():
  print(cache)

Para recuperar los metadatos de un objeto de caché, si conoces su nombre, usa get:

client.caches.get(name=name)

Actualiza una caché

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

En el siguiente ejemplo, se muestra cómo actualizar el ttl de una caché con client.caches.update().

from google import genai
from google.genai import types

client.caches.update(
  name = cache.name,
  config  = types.UpdateCachedContentConfig(
      ttl='300s'
  )
)

Para establecer la hora de vencimiento, se aceptará un objeto datetime o una cadena de fecha y hora con formato ISO (dt.isoformat(), como 2025-01-27T16:02:36.473528+00:00). La hora debe incluir una zona horaria (datetime.utcnow() no adjunta una zona horaria, datetime.now(datetime.timezone.utc) sí).

from google import genai
from google.genai import types
import datetime

# You must use a time zone-aware time.
in10min = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(minutes=10)

client.caches.update(
  name = cache.name,
  config  = types.UpdateCachedContentConfig(
      expire_time=in10min
  )
)

Borra una memoria 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é:

client.caches.delete(cache.name)

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

La caché de contexto es particularmente adecuada para situaciones en las que se hace referencia a un contexto inicial sustancial de forma reiterada a través de solicitudes más cortas. Considera usar el almacenamiento en caché de contexto para casos de uso como los siguientes:

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

Cómo la caché explícita reduce los costos

La caché de 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 en función de 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 tokens de entrada y salida que no están almacenados en caché.

Para obtener detalles actualizados sobre los precios, consulta la página de precios de la API de Gemini. Para aprender a contar tokens, consulta la Guía de tokens.

Consideraciones adicionales

Ten en cuenta las siguientes consideraciones cuando uses la caché de contexto:

  • El recuento de tokens de entrada mínimo para la caché de contexto es de 1,024 para Flash 2.5 y de 2,048 para 2.5 Pro. El máximo es el mismo que el máximo del modelo determinado. (Para obtener más información sobre cómo contar tokens, consulta la Guía de tokens).
  • El modelo no hace ninguna distinción 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 de frecuencia ni de uso especiales en la caché de contexto. Se aplican los límites de frecuencia estándar para GenerateContent, y los límites de tokens incluyen los tokens almacenados en caché.
  • La cantidad de tokens almacenados en caché se muestra 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é.