The latest Gemini models, like Gemini 3.1 Flash Image (Nano Banana 2), are available to use with Firebase AI Logic! Learn more.

Gemini 2.0 Flash and Flash-Lite models will shut down on June 1, 2026. To avoid service disruption, update to a newer model like gemini-2.5-flash-lite. Learn more.

All Imagen models will shut down on June 24, 2026. Learn about migrating your apps to use Nano Banana.

Almacenamiento en caché del contexto en Firebase AI Logic

En tu función de 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 solicitudes posteriores.

El almacenamiento en caché de contexto puede reducir significativamente la latencia y el costo de las tareas repetitivas que implican 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 personajes, bases de código o manuales.

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

Almacenamiento en caché implícito: Se habilita automáticamente en la mayoría de los modelos, sin ahorros de costos garantizados.
Almacenamiento en caché explícito: Se puede habilitar opcionalmente y manualmente en la mayoría de los modelos, lo que suele generar ahorros de costos.

El almacenamiento en caché explícito es útil en los casos en los que deseas garantizar más ahorros de costos, pero con un poco más de trabajo para el desarrollador.

Para el almacenamiento en caché implícito y 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 en la parte inferior de esta página.

Modelos compatibles

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

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

Los modelos que generan contenido multimedia (por ejemplo, los modelos Nana Banana como gemini-3.1-flash-image-preview) 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.

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

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

Almacenamiento en caché implícito

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

Google pasa automáticamente los ahorros de costos si tu solicitud alcanza el 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 grande y común al comienzo de tu 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 capacidad opcional de los modelos Gemini.

A continuación, te mostramos cómo configurar y trabajar con memorias caché de contenido explícito:

Crea y usa una caché explícita
Administra memorias caché explícitas, incluidas las siguientes acciones:

Ten en cuenta que las memorias caché 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 caché inhabilitando el almacenamiento en caché implícito y no creando memorias caché explícitas. Para obtener más información, consulta Habilita y 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:

Crea una caché explícita.
Haz referencia a la caché en una plantilla de instrucciones del servidor.
Haz referencia a la plantilla de instrucciones del servidor en una solicitud de instrucción 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 tu plantilla de instrucciones del servidor:

La caché es específica de un Gemini API proveedor. La solicitud de instrucción de tu app debe usar el mismo proveedor.
Para Firebase AI Logic, te recomendamos que uses memorias caché de contenido explícito solo con la Vertex AI Gemini API. Toda la información y ejemplos de esta página son específicos de ese Gemini API proveedor.
La caché es específica de un Gemini modelo. 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 la 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 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 sobre ella, excepto el TTL o la fecha de vencimiento.
Puedes almacenar en caché cualquier tipo MIME de archivo de entrada compatible o incluso solo el texto proporcionado en la solicitud de creación de caché.
Si deseas incluir un archivo en la caché, debes proporcionarlo como un Cloud Storage URI. No puede ser una URL del navegador ni una URL de YouTube.

Además, las restricciones de acceso al archivo se verifican en el momento de la creación de la caché, y las restricciones de acceso 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 deseas usar instrucciones o herramientas del sistema (como la ejecución de código, el contexto de URL o la fundamentación con la Búsqueda de Google), la caché en sí debe contener sus configuraciones. 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 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 la Vertex AI Gemini API.

Paso 1: Crea la caché

Para crear la caché, usa directamente la API de REST de la 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 name de recurso completamente calificado que es globalmente único para la caché (ten en cuenta que el último segmento es el ID de la caché). Usarás todo este valor 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-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 instrucciones del servidor

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

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

Usa el name de recurso completamente calificado de la respuesta cuando creaste la caché. 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, 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 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 entrada para la solicitud de 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 el Vertex AI Gemini API, ya que la caché se creó con ese Gemini API proveedor.
La ubicación en 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 memorias caché explícitas

En esta sección, se describe la administración de memorias caché de contenido explícito, incluido cómo enumerar todas las memorias caché, obtener metadatos sobre una memoria caché, actualizar el TTL o la fecha de vencimiento de una memoria caché, y borrar una memoria caché.

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

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

Enumera todas las memorias caché

Puedes enumerar todas las memorias caché explícitas disponibles para tu proyecto. Este comando solo mostrará las memorias caché 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 memoria 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 en el name de 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 memoria caché

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

ttl: El TTL (tiempo de actividad) para la caché, específicamente la cantidad de segundos y nanosegundos que dura la caché después de que se crea o después de que se actualiza el ttl antes de que venza. Cuando estableces el ttl, el expireTime de la caché se actualiza automáticamente.
expire_time: Una 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 en el TTL.

En el caso de las memorias caché 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 name de recurso 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 memoria caché

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