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.

Armazenamento em cache de contexto no Firebase AI Logic

Para o recurso de IA, você pode transmitir os mesmos tokens de entrada (conteúdo) várias vezes para um modelo. Para esses casos de uso, é possível armazenar esse conteúdo em cache, o que significa que você transmite o conteúdo para o modelo uma vez, armazena e faz referência a ele em solicitações subsequentes.

O armazenamento em cache de contexto pode reduzir significativamente a latência e o custo de tarefas repetitivas que envolvem uma grande quantidade de conteúdo, como grandes quantidades de texto, um arquivo de áudio ou um arquivo de vídeo. Alguns casos de uso comuns para conteúdo armazenado em cache incluem documentos detalhados de personas, bases de código ou manuais.

Gemini modelos oferecem dois mecanismos de armazenamento em cache diferentes:

Armazenamento em cache implícito: automaticamente ativado na maioria dos modelos, sem economia de custos garantida
Armazenamento em cache explícito: pode ser ativado opcionalmente e manualmente na maioria dos modelos, geralmente resulta em economia de custos

O armazenamento em cache explícito é útil nos casos em que você quer garantir a economia de custos, mas com algum trabalho extra do desenvolvedor.

Para o armazenamento em cache implícito e explícito, o campo cachedContentTokenCount nos metadados da resposta indica o número de tokens na parte armazenada em cache da entrada. Para o armazenamento em cache explícito, revise as informações de preços na parte de baixo desta página.

Modelos compatíveis

O armazenamento em cache é compatível com os seguintes 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

Os modelos de geração de mídia (por exemplo, os modelos Nana Banana, como gemini-3.1-flash-image-preview) não oferecem suporte ao armazenamento em cache de contexto.

Limites de tamanho de conteúdo armazenado em cache

Cada modelo tem um requisito de contagem de tokens mínimo para conteúdo armazenado em cache. O máximo é determinado pela janela de contexto do modelo.

Gemini Modelos Pro: mínimo de 4.096 tokens
Modelos Gemini Flash: mínimo de 1.024 tokens

Além disso, o tamanho máximo de conteúdo que pode ser armazenado em cache usando um blob ou texto é de 10 MB.

Armazenamento em cache implícito

O armazenamento em cache implícito é ativado por padrão e está disponível para a maioria dos modelos Gemini.

O Google transmite automaticamente a economia de custos se a solicitação atingir o conteúdo armazenado em cache. Confira algumas maneiras de aumentar a chance de a solicitação usar o armazenamento em cache implícito:

Tente colocar conteúdo grande e comum no início do comando.
Tente enviar solicitações com um prefixo semelhante em um curto período.

O número de tokens na parte armazenada em cache da entrada é fornecido no campo cachedContentTokenCount nos metadados de uma resposta.

Armazenamento em cache explícito

O armazenamento em cache explícito não é ativado por padrão e é um recurso opcional dos modelos Gemini.

Veja como configurar e trabalhar com caches de conteúdo explícitos:

Criar e usar um cache explícito
Gerenciar caches explícitos, incluindo:

Os caches de conteúdo explícitos interagem com o armazenamento em cache implícito, o que pode levar a um armazenamento em cache adicional além do conteúdo em cache explícito. É possível impedir a retenção de dados de cache desativando o armazenamento em cache implícito e não criando caches explícitos. Para mais informações, consulte Ativar e desativar o armazenamento em cache.

Criar e usar um cache explícito

Para criar e usar um cache de conteúdo explícito, é necessário:

Criar um cache explícito.
Fazer referência ao cache em um modelo de comando do servidor.
Fazer referência ao modelo de comando do servidor em uma solicitação de comando do app.

Informações importantes sobre como criar e usar um cache explícito

O cache precisa estar alinhado às solicitações de comando do app e ao modelo de comando do servidor:

O cache é específico de um Gemini API provedor. A solicitação de comando do app precisa usar o mesmo provedor.
Para Firebase AI Logic, recomendamos usar caches de conteúdo explícito somente com a Vertex AI Gemini API. Todas as informações e exemplos nesta página são específicos desse Gemini API provedor.
O cache é específico de um Gemini modelo. A solicitação de comando do app precisa usar o mesmo modelo.
O cache é específico de um local ao usar o Vertex AI Gemini API.
O local do cache explícito precisa corresponder ao local do modelo de comando do servidor e ao local em que você acessa o modelo na solicitação de comando do app.

Além disso, esteja ciente das seguintes limitações e requisitos para o armazenamento em cache explícito:

Depois que um cache explícito é criado, não é possível mudar nada sobre ele, exceto o TTL ou o prazo de validade.
É possível armazenar em cache qualquer tipo MIME de arquivo de entrada compatível ou até mesmo apenas o texto fornecido na solicitação de criação de cache.
Se você quiser incluir um arquivo no cache, forneça o arquivo como um Cloud Storage URI. Ele não pode ser um URL do navegador ou do YouTube.

Além disso, as restrições de acesso ao arquivo são verificadas no momento da criação do cache, e as restrições de acesso não são verificadas novamente no momento da solicitação do usuário. Por esse motivo, verifique se todos os dados incluídos no cache explícito são adequados para qualquer usuário que faça uma solicitação que inclua esse cache.
Se você quiser usar instruções ou ferramentas do sistema (como execução de código, contexto de URL ou embasamento com a Pesquisa Google), o próprio cache precisará conter as configurações. Elas não podem ser configuradas no modelo de comando do servidor ou na solicitação de comando do app. Observe que os modelos de comandos do servidor ainda não oferecem suporte a chamadas de função (ou chat). Para detalhes sobre como configurar instruções e ferramentas do sistema no seu cache, consulte a API REST da Vertex AI Gemini API.

Etapa 1: criar o cache

Crie o cache usando diretamente a API REST do Vertex AI Gemini API.

Confira a seguir um exemplo que cria um cache explícito de um arquivo PDF como conteúdo.

Sintaxe :

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

Exemplo de solicitação :

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

Exemplo de resposta :

A resposta inclui um name de recurso totalmente qualificado que é globalmente exclusivo do cache (observe que o último segmento é o ID do cache). Você vai usar todo esse valor name na próxima etapa do fluxo de trabalho.

{
  "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"
}

Etapa 2: fazer referência ao cache em um modelo de comando do servidor

Depois de criar o cache, faça referência a ele por name na cachedContent propriedade de um modelo de comando do servidor.

Siga estes requisitos ao criar o modelo de comando do servidor:

Use o name de recurso totalmente qualificado da resposta ao criar o cache. Esse não é o nome de exibição opcional especificado na solicitação.
O local do modelo de comando do servidor precisa corresponder ao local do cache.
Para usar instruções ou ferramentas do sistema, elas precisam ser configuradas como parte do cache e não como parte do modelo de comando do servidor.

Sintaxe :

{{cachedContent name="YOUR_CACHE_RESOURCE_NAME"}}

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

Exemplo :

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

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

Como alternativa, o valor do parâmetro name no modelo de comando do servidor pode ser uma variável de entrada dinâmica. Por exemplo, {{cachedContent name=someVariable}} permite incluir o name do cache como uma entrada para a solicitação do seu app.

Etapa 3: fazer referência ao modelo de comando do servidor na solicitação do app

Tenha muito cuidado com o seguinte ao escrever a solicitação:

Use o Vertex AI Gemini API já que o cache foi criado com esse Gemini API provedor.
O local em que você acessa o modelo na solicitação de comando do app precisa corresponder ao local do modelo de comando do servidor e do cache.

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}");
}

Gerenciar caches explícitos

Esta seção descreve o gerenciamento de caches de conteúdo explícitos, incluindo como listar todos os caches, receber metadados sobre um cache, atualizar o TTL ou o prazo de validade de um cache, e excluir um cache.

Você gerencia caches explícitos usando a API REST da Vertex AI Gemini API.

Depois que um cache de conteúdo explícito é criado, não é possível mudar nada sobre ele, exceto o TTL ou o prazo de validade.

Listar todos os caches

É possível listar todos os caches explícitos disponíveis para o projeto. Esse comando só vai retornar os caches no local especificado.

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

Receber metadados sobre um cache

Não é possível recuperar ou visualizar o conteúdo armazenado em cache. No entanto, você pode recuperar metadados sobre um cache explícito, incluindo name, model, display_name, usage_metadata, create_time, update_time, e expire_time.

É necessário fornecer o CACHE_ID, que é o segmento final no name de recurso totalmente qualificado do cache.

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}

Atualizar o TTL ou o prazo de validade de um cache

Ao criar um cache explícito, é possível definir o ttl ou o expire_time.

ttl: o TTL (tempo de vida) do cache, especificamente o número de segundos e nanossegundos que o cache permanece depois de criado ou depois que o ttl é atualizado antes de expirar. Quando você define o ttl, o expireTime do cache é atualizado automaticamente.
expire_time: um Timestamp (como 2024-06-30T09:00:00.000000Z) que especifica a data e a hora absolutas em que o cache expira.

Se você não definir nenhum desses valores, o TTL padrão será de 1 hora. Não há limites mínimos ou máximos no TTL.

Para caches explícitos atuais, é possível adicionar ou atualizar o ttl ou expire_time. É necessário fornecer o CACHE_ID, que é o segmento final no name de recurso totalmente qualificado do cache.

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

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

Excluir um cache

Quando um cache explícito não for mais necessário, você poderá excluí-lo.