Almacenamiento en caché del contexto en Firebase AI Logic

En el caso de tu función basada en IA, es posible que pases los mismos tokens de entrada (contenido) una y otra vez a un modelo. Para estos casos de uso, puedes almacenar en caché este contenido, lo que significa que lo pasas al modelo una vez, lo almacenas y haces referencia a él en las solicitudes posteriores.

El almacenamiento en caché de contexto puede reducir significativamente la latencia y el costo de las tareas repetitivas que involucran una gran cantidad de contenido, como grandes cantidades de texto, un archivo de audio o un archivo de video. Algunos casos de uso comunes del contenido almacenado en caché incluyen documentos detallados de arquetipos de clientes, bases de código o manuales.

Los modelos de Gemini ofrecen dos mecanismos de almacenamiento en caché diferentes:

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

Tanto para el almacenamiento en caché implícito como para el explícito, el campo cachedContentTokenCount en los metadatos de tu respuesta indica la cantidad de tokens en la parte almacenada en caché de tu entrada. Para el almacenamiento en caché explícito, asegúrate de revisar la información sobre los precios que se encuentra en la parte inferior de esta página.

Modelos compatibles

El almacenamiento en caché se admite cuando se usan los siguientes modelos:

  • gemini-3.1-pro-preview
  • gemini-3-flash-preview
  • gemini-3.1-flash-lite
  • gemini-2.5-pro
  • gemini-2.5-flash
  • gemini-2.5-flash-lite

Los modelos que generan contenido multimedia (por ejemplo, los modelos de Nana Banana como gemini-3.1-flash-image-preview) no admiten el almacenamiento en caché del contexto.

Límites de tamaño del contenido almacenado en caché

Cada modelo tiene un requisito de recuento de tokens mínimo para el contenido almacenado en caché. El máximo está determinado por la ventana de contexto del modelo.

  • Gemini Modelos Pro: 4,096 tokens como mínimo
  • Gemini Modelos Flash: 1,024 tokens como mínimo

Además, el tamaño máximo del contenido que puedes almacenar en caché con un BLOB o texto es de 10 MB.


Almacenamiento en caché implícito

El almacenamiento en caché implícito está habilitado de forma predeterminada y disponible para la mayoría de los modelos de Gemini.

Google transfiere automáticamente los ahorros de costos si tu solicitud alcanza el contenido almacenado en caché. Estas son algunas formas de aumentar las probabilidades de que tu solicitud use el almacenamiento en caché implícito:

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

La cantidad de tokens en la parte almacenada en caché de tu entrada se proporciona en el campo cachedContentTokenCount de los metadatos de una respuesta.


Almacenamiento en caché explícito

El almacenamiento en caché explícito no está habilitado de forma predeterminada y es una capacidad opcional de los modelos Gemini.

Sigue estos pasos para configurar y trabajar con cachés de contenido explícito:

Ten en cuenta que las cachés de contenido explícito interactúan con el almacenamiento en caché implícito, lo que puede generar almacenamiento en caché adicional más allá del contenido explícito almacenado en caché. Puedes evitar la retención de datos de caché si inhabilitas el almacenamiento en caché implícito y no creas cachés explícitas. Para obtener más información, consulta Habilita e inhabilita el almacenamiento en caché.


Crea y usa una caché explícita

Para crear y usar una caché de contenido explícito, se requiere lo siguiente:

  1. Crea una caché explícita.

  2. Haz referencia a la caché en una plantilla de instrucción del servidor.

  3. Haz referencia a la plantilla de instrucciones del servidor en una solicitud de instrucciones de tu app.

Información importante sobre la creación y el uso de una caché explícita

Tu caché debe estar alineada con las solicitudes de instrucciones de tu app y la plantilla de instrucciones del servidor:

  • La caché es específica de un proveedor de Gemini API. La solicitud de instrucciones de tu app debe usar el mismo proveedor.
    Para Firebase AI Logic, recomendamos enfáticamente usar cachés de contenido explícito solo con Vertex AI Gemini API. Toda la información y los ejemplos de esta página son específicos de ese proveedor de Gemini API.

  • La caché es específica de un modelo de Gemini. La solicitud de instrucción de tu app debe usar el mismo modelo.

  • La caché es específica de una ubicación cuando se usa Vertex AI Gemini API.
    La ubicación de la caché explícita debe coincidir con la ubicación de la plantilla de instrucciones del servidor y la ubicación en la que accedes al modelo en la solicitud de instrucciones de tu app.

Además, ten en cuenta las siguientes limitaciones y requisitos para el almacenamiento en caché explícito:

  • Una vez que se crea una caché explícita, no puedes cambiar nada sobre ella, excepto el TTL o el tiempo de vencimiento.

  • Puedes almacenar en caché cualquier tipo de MIME de archivo de entrada compatible o incluso solo el texto proporcionado en la solicitud de creación de caché.

  • Si quieres incluir un archivo en la caché, debes proporcionarlo como un URI Cloud Storage. No puede ser una URL de navegador ni de YouTube.

    Además, las restricciones de acceso al archivo se verifican en el momento de la creación de la caché, y no se vuelven a verificar en el momento de la solicitud del usuario. Por este motivo, asegúrate de que los datos incluidos en la caché explícita sean adecuados para cualquier usuario que realice una solicitud que incluya esa caché.

  • Si quieres usar instrucciones o herramientas del sistema (como ejecución de código, contexto de URL o fundamentación con Google Search), la caché debe contener sus configuraciones. No se pueden configurar en la plantilla de mensaje del servidor ni en la solicitud de mensaje de tu app. Ten en cuenta que las plantillas de instrucciones del servidor aún no admiten llamadas a funciones (ni chat). Para obtener detalles sobre cómo configurar instrucciones y herramientas del sistema en tu caché, consulta la API de REST de Vertex AI Gemini API.

Paso 1: Crea la caché

Crea la caché directamente con la API de REST de Vertex AI Gemini API.

El siguiente es un ejemplo que crea una caché explícita de un archivo PDF como su contenido.

Sintaxis:

PROJECT_ID="PROJECT_ID"
MODEL_ID="GEMINI_MODEL"  # for example, gemini-3-flash-preview
LOCATION="LOCATION"  # location for both the cache and the model
MIME_TYPE="MIME_TYPE"
CACHED_CONTENT_URI="CLOUD_STORAGE_FILE_URI"  # must be a Cloud Storage URI
CACHE_DISPLAY_NAME="CACHE_DISPLAY_NAME"  # optional
TTL="CACHE_TIME_TO_LIVE"  # optional (if not specified, defaults to 3600s)

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
  "model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "${MIME_TYPE}",
            "fileUri": "${CACHED_CONTENT_URI}"
          }
        }
      ]
    }
  ],
  "displayName": "${CACHE_DISPLAY_NAME}",
  "ttl": "${TTL}"
}
EOF

Ejemplo de solicitud:

PROJECT_ID="my-amazing-app"
MODEL_ID="gemini-3-flash-preview"
LOCATION="global"
MIME_TYPE="application/pdf"
CACHED_CONTENT_URI="gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf"
CACHE_DISPLAY_NAME="Gemini - A Family of Highly Capable Multimodal Model (PDF)"
TTL="7200s"

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
  "model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "${MIME_TYPE}",
            "fileUri": "${CACHED_CONTENT_URI}"
          }
        }
      ]
    }
  ],
  "displayName": "${CACHE_DISPLAY_NAME}",
  "ttl": "${TTL}"
}
EOF

Ejemplo de respuesta:

La respuesta incluye un recurso name completamente calificado que es único a nivel global para la caché (ten en cuenta que el último segmento es el ID de la caché). Usarás todo este valor de name en el próximo paso del flujo de trabajo.

{
  "name": "projects/861083271981/locations/global/cachedContents/4545031458888089601",
  "model": "projects/my-amazing-app/locations/global/publishers/google/models/gemini-3-flash-preview",
  "createTime": "2024-06-04T01:11:50.808236Z",
  "updateTime": "2024-06-04T01:11:50.808236Z",
  "expireTime": "2024-06-04T02:11:50.794542Z"
}

Paso 2: Haz referencia a la caché en una plantilla de instrucción del servidor

Después de crear la caché, haz referencia a ella por medio de name dentro de la propiedad cachedContent de una plantilla de mensaje del servidor.

Asegúrate de cumplir con estos requisitos cuando crees tu plantilla de instrucciones del servidor:

  • Usa el recurso name completamente calificado de la respuesta cuando creaste la caché. Este no es el nombre visible opcional que especificaste en la solicitud.

  • La ubicación de la plantilla de mensaje del servidor debe coincidir con la ubicación de la caché.

  • Para usar instrucciones o herramientas del sistema, deben configurarse como parte de la caché y no como parte de la plantilla de instrucciones del servidor.

Sintaxis:

{{cachedContent name="YOUR_CACHE_RESOURCE_NAME"}}

{{role "user"}}
{{userPrompt}}

Ejemplo:

{{cachedContent name="projects/861083271981/locations/global/cachedContents/4545031458888089601"}}

{{role "user"}}
{{userPrompt}}

Como alternativa, el valor del parámetro name en la plantilla de mensaje del servidor puede ser una variable de entrada dinámica. Por ejemplo, {{cachedContent name=someVariable}} te permite incluir el name de la caché como entrada para la solicitud de tu app.

Paso 3: Haz referencia a la plantilla de mensaje del servidor en la solicitud de tu app

Ten mucho cuidado con lo siguiente cuando escribas tu solicitud:

  • Usa Vertex AI Gemini API, ya que la caché se creó con ese proveedor de Gemini API.

  • La ubicación desde la que accedes al modelo en la solicitud de instrucciones de tu app debe coincidir con la ubicación de la plantilla de instrucciones del servidor y la caché.

Swift 

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
let model = FirebaseAI.firebaseAI(backend: .vertexAI(location: "LOCATION"))
                                  .templateGenerativeModel()

do {
    let response = try await model.generateContent(
        // Specify your template ID
        templateID: "TEMPLATE_ID"
    )
    if let text = response.text {
        print("Response Text: \(text)")
    }
} catch {
    print("An error occurred: \(error)")
}
print("\n")

Kotlin 

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
val model = Firebase.ai(backend = GenerativeBackend.vertexAI(location = "LOCATION"))
                        .templateGenerativeModel()

val response = model.generateContent(
    // Specify your template ID
    "TEMPLATE_ID",
)

val text = response.text
println(text)

Java 

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance().templateGenerativeModel();

TemplateGenerativeModelFutures model = TemplateGenerativeModelFutures.from(generativeModel);

Future<GenerateContentResponse> response = model.generateContent(
    // Specify your template ID
    "TEMPLATE_ID"
);
addCallback(response,
      new FutureCallback<GenerateContentResponse>() {
          public void onSuccess(GenerateContentResponse result) {
            System.out.println(result.getText());
          }
          public void onFailure(Throwable t) {
            reportError(t);
          }
    }
executor);

Web 

// ...

// Initialize the Vertex AI Gemini API backend service
// Make sure to specify the same location as the server prompt template and the cache
const ai = getAI(app, { backend: new VertexAIBackend('LOCATION') });

// Create a `TemplateGenerativeModel` instance
const model = getTemplateGenerativeModel(ai);

const result = await model.generateContent(
  // Specify your template ID
  'TEMPLATE_ID'
);

const response = result.response;
const text = response.text();

Dart 

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
var _model = FirebaseAI.vertexAI(location: 'LOCATION').templateGenerativeModel()

var response = await _model.generateContent(
        // Specify your template ID
        'TEMPLATE_ID',
      );

var text = response?.text;
print(text);

Unity 

// ...

// Initialize the Vertex AI Gemini API backend service
// Make sure to specify the same location as the server prompt template and the cache
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.VertexAI(location: "LOCATION"));

// Create a `TemplateGenerativeModel` instance
var model = firebaseAI.GetTemplateGenerativeModel();

try
{
  var response = await model.GenerateContentAsync(
      // Specify your template ID
      "TEMPLATE_ID"
  );
  Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
  Debug.LogError($"An error occurred: {e.Message}");
}


Administra cachés explícitas

En esta sección, se describe cómo administrar las cachés de contenido explícito, incluido cómo listar todas las cachés, obtener metadatos sobre una caché, actualizar el TTL o la hora de vencimiento de una caché y borrar una caché.

Administras las memorias caché explícitas con la API de REST de Vertex AI Gemini API.

Una vez que se crea una caché de contenido explícito, no puedes cambiar nada sobre la caché, excepto el TTL o la hora de vencimiento.

Enumera todas las memorias caché

Puedes enumerar todas las cachés explícitas disponibles para tu proyecto. Este comando solo devolverá las cachés en la ubicación especificada.

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"

curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents

Obtén metadatos sobre una caché

No es posible recuperar ni ver el contenido almacenado en caché real. Sin embargo, puedes recuperar metadatos sobre una caché explícita, incluidos name, model, display_name, usage_metadata, create_time, update_time y expire_time.

Debes proporcionar el CACHE_ID, que es el segmento final del name del recurso completamente calificado de la caché.

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache

curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}

Actualiza el TTL o la fecha de vencimiento de una caché

Cuando creas una caché explícita, puedes establecer de forma opcional ttl o expire_time.

  • ttl: Es el TTL (tiempo de actividad) de la caché, específicamente la cantidad de segundos y nanosegundos que la caché permanece activa después de su creación o después de que se actualiza el ttl antes de que venza. Cuando configuras el ttl, el expireTime de la caché se actualiza automáticamente.

  • expire_time: Un Timestamp (como 2024-06-30T09:00:00.000000Z) que especifica la fecha y hora absolutas en las que vence la caché.

Si no estableces ninguno de estos valores, el TTL predeterminado es de 1 hora. No hay límites mínimos ni máximos para el TTL.

En el caso de las cachés explícitas existentes, puedes agregar o actualizar ttl o expire_time. Debes proporcionar el CACHE_ID, que es el segmento final del name del recurso completamente calificado de la caché.

Actualizar ttl

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache
TTL="CACHE_TIME_TO_LIVE"

curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
  "ttl": "'$TTL'"
}'

Actualizar expire_time

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache
EXPIRE_TIME="ABSOLUTE_TIME_CACHE_EXPIRES"

curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
  "expire_time": "'$EXPIRE_TIME'"
}'

Borra una caché

Cuando ya no necesites una caché explícita, puedes borrarla.

Debes proporcionar el CACHE_ID, que es el segmento final del name del recurso completamente calificado de la caché.

PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID"  # the final segment in the `name` of the cache

curl \
-X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}


Precios del almacenamiento en caché explícito

El almacenamiento en caché explícito es una función pagada diseñada para reducir costos. Los precios se basan en los siguientes factores:

  • Tokens de entrada para la creación de la caché: Tanto para el almacenamiento en caché implícito como explícito, se te facturan los tokens de entrada que se usan para crear la caché al precio estándar de los tokens de entrada.

  • Almacenamiento de caché: En el caso del almacenamiento en caché explícito, también hay costos de almacenamiento según el tiempo que se almacena la caché. No hay costos de almacenamiento para el almacenamiento en caché implícito. Para obtener más información, consulta los precios de Vertex AI Gemini API.

  • Uso de contenido almacenado en caché: El almacenamiento en caché explícito garantiza un descuento cuando se hace referencia a cachés explícitas, lo que significa que obtienes un descuento en los tokens de entrada cuando hacen referencia a una caché existente. En el caso de los modelos Gemini 2.5 y posteriores, este descuento es del 90%.

La cantidad de tokens en la parte almacenada en caché de tu entrada se proporciona en el campo cachedContentTokenCount de los metadatos de una respuesta.