Almacenamiento en caché del contexto en Firebase AI Logic

Para tu función potenciada por IA, puedes pasar 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 pasas el contenido al modelo una vez, lo almacenas y haces referencia a él en las solicitudes posteriores.

La 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 para el contenido almacenado en caché incluyen documentos detallados de personas, 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 un ahorro de costos, pero con un trabajo adicional para el desarrollador.

En el caso del almacenamiento en caché implícito y explícito, el campo cachedContentTokenCount de los metadatos de la respuesta indica la cantidad de tokens en la parte almacenada en caché de la entrada. Para el almacenamiento en caché explícito, asegúrate de revisar la información de precios en la parte inferior de esta página.

Modelos compatibles

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

  • gemini-4-argon (solo almacenamiento en caché implícito; no se admite el almacenamiento en caché explícito)
  • gemini-3.8-flash
  • gemini-3.5-flash-lite (y la versión anterior gemini-3.1-flash-lite)

Los modelos de Gemini 3.x Flash de uso general más antiguos admiten esta capacidad, pero ya no se recomienda su uso debido a las próximas fechas de cierre o al enrutamiento automático a modelos más nuevos.

Los modelos que generan contenido multimedia (por ejemplo, los modelos de Gemini Nano Banana como gemini-nano-banana-2.1) no admiten el almacenamiento en caché de 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 4 Argon: 4,096 tokens como mínimo (Gemini Developer API) o 6,144 tokens como mínimo (Agent Platform Gemini API (formerly Vertex AI))
  • Modelos de Gemini Pro: 4,096 tokens como mínimo
  • Modelos de Flash de Gemini: 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 llega al contenido almacenado en caché. Estas son algunas formas de aumentar la probabilidad de que tu solicitud use el almacenamiento en caché implícito:

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

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 función opcional de los modelos de Gemini.

Ten en cuenta que el modelo gemini-4-argon no admite el almacenamiento en caché explícito.

A continuación, se muestra cómo configurar y trabajar con cachés de contenido explícitas:

Ten en cuenta que las cachés de contenido explícito interactúan con el almacenamiento en caché implícito, lo que puede generar un almacenamiento en caché adicional más allá del contenido almacenado en caché explícito. Puedes evitar la retención de datos de la caché inhabilitando el almacenamiento en caché implícito y no creando 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ícita, se requiere lo siguiente:

  1. Crea una caché explícita.

  2. Haz referencia a la caché en una plantilla de instrucciones del servidor.

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

Información importante sobre cómo crear y usar una caché explícita

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

  • La caché es específica de un proveedor de Gemini API. La solicitud de mensaje de tu app debe usar el mismo proveedor.
    Para Firebase AI Logic, recomendamos enfáticamente usar cachés de contenido explícitas solo con Agent Platform Gemini API (formerly Vertex AI). 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 Agent Platform Gemini API (formerly Vertex AI).
    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 instrucción 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 de ella, excepto el TTL o la hora 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 de Cloud Storage. No puede ser una URL del navegador ni de YouTube.

    Además, las restricciones de acceso al archivo se verifican en el momento de 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 la ejecución de código, el contexto de URL, la fundamentación con Google Search o la fundamentación con Google Maps), la caché debe contener sus parámetros de configuración. No se pueden configurar en la plantilla de instrucciones del servidor ni en la solicitud de instrucciones de tu app. Ten en cuenta que las plantillas de instrucciones del servidor todavía no admiten la llamada a funciones (ni el chat). Para obtener detalles sobre cómo configurar las instrucciones y herramientas del sistema en tu caché, consulta la API de REST de Agent Platform Gemini API (formerly Vertex AI).

Paso 1: Crea la caché

Crea la caché con la API de REST de Agent Platform Gemini API (formerly Vertex AI) directamente.

En el siguiente ejemplo, se 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.8-flash
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.8-flash"
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

Respuesta de ejemplo:

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 siguiente paso del flujo de trabajo.

{
  "name": "projects/861083271981/locations/global/cachedContents/4545031458888089601",
  "model": "projects/my-amazing-app/locations/global/publishers/google/models/gemini-3.8-flash",
  "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 instrucciones del servidor

Después de crear la caché, haz referencia a ella por name dentro de la propiedad cachedContent de una plantilla de instrucciones 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 que obtuviste cuando creaste la caché. Este no es el nombre visible opcional que especificaste en la solicitud.

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

  • Para usar instrucciones o herramientas del sistema, se deben configurar 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 instrucciones del servidor puede ser una variable de entrada dinámica. Por ejemplo, {{cachedContent name=someVariable}} te permite incluir el name de la caché como una entrada para la solicitud desde tu app.

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

Ten mucho cuidado con lo siguiente cuando escribas tu solicitud:

  • Usa Agent Platform Gemini API (formerly Vertex AI), 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 instrucción de tu app debe coincidir con la ubicación de la plantilla de instrucciones del servidor y la caché.

Swift

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
let model = FirebaseAI.firebaseAI(backend: .agentPlatform(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 Agent Platform Gemini API backend service (formerly Vertex AI).
// 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.agentPlatform(location = "LOCATION"))
                        .templateGenerativeModel()

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

val text = response.text
println(text)

Java

// ...

// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance(GenerativeBackend.agentPlatform("LOCATION"))
      .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 Agent Platform Gemini API backend service (formerly Vertex AI).
// Make sure to specify the same location as the server prompt template and the cache.
const ai = getAI(app, { backend: new AgentPlatformBackend('LOCATION') });

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

const result = await model.generateContent({
  // Specify your template ID.
  templateId: 'TEMPLATE_ID',
  templateVariables: {},
});

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

Dart

// ...

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

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

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

Unity

// ...

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

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

try
{
  var response = await model.GenerateContentAsync(
      // Specify your template ID.
      "TEMPLATE_ID",
      new Dictionary<string, object>()
  );
  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, lo que incluye cómo enumerar todas las cachés, obtener metadatos sobre una caché, actualizar el TTL o el tiempo de vencimiento de una caché y borrar una caché.

Administra las cachés explícitas con la API de REST de Agent Platform Gemini API (formerly Vertex AI).

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

Enumera todas las cachés

Puedes enumerar todas las cachés explícitas disponibles para tu proyecto. Este comando solo devolverá las cachés de 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 real almacenado en caché. 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 en el recurso name 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 el tiempo de vencimiento de una caché

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

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

  • expire_time: Es 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 el ttl o el expire_time. Debes proporcionar el CACHE_ID, que es el segmento final en el recurso name completamente calificado de la caché.

Actualiza 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'"
}'

Actualiza 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 en el recurso name 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 para el 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é: Para el almacenamiento en caché explícito, también hay costos de almacenamiento según el tiempo que se almacenen las cachés. No hay costos de almacenamiento para el almacenamiento en caché implícito. Para obtener más información, consulta los precios de Agent Platform Gemini API (formerly Vertex AI).

  • Uso del contenido almacenado en caché: El almacenamiento en caché explícito garantiza un descuento cuando se hace referencia a las cachés explícitas, lo que significa que obtienes un descuento en los tokens de entrada cuando hacen referencia a una caché existente. Para 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.