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-3.1-flash-lite. Learn more.

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

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Armazenamento em cache de contexto no Firebase AI Logic

Para seu 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 em cache esse conteúdo. Isso 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 em cache incluem documentos detalhados de personas, bases de código ou manuais.

Os modelos Gemini oferecem dois mecanismos de cache diferentes:

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

O armazenamento em cache explícito é útil quando você quer garantir mais 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, confira 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
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 são compatíveis com o armazenamento em cache de contexto.

Limites de tamanho do 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
Gemini Modelos 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 está ativado por padrão e disponível para a maioria dos modelos do Gemini.

O Google repassa automaticamente a economia de custos se sua solicitação atingir o conteúdo em cache. Confira algumas maneiras de aumentar a chance de sua solicitação usar o 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 sua 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ícito:

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

Observação: os caches de conteúdo explícito interagem com o armazenamento em cache implícito, o que pode levar a um armazenamento em cache adicional além do conteúdo explícito em cache. Para evitar a retenção de dados em cache, desative o armazenamento em cache implícito e não crie 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:

Crie um cache explícito.
Faça referência ao cache em um modelo de comando do servidor.
Faça referência ao modelo de comando do servidor em uma solicitação de comando do seu app.

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

O cache precisa estar alinhado com as solicitações de comandos do app e o modelo de comando do servidor:

O cache é específico de um provedor Gemini API. A solicitação de comando do seu app precisa usar o mesmo provedor.
Para Firebase AI Logic, recomendamos usar caches de conteúdo explícito apenas com o Vertex AI Gemini API. Todas as informações e exemplos nesta página são específicos desse provedor de Gemini API.
O cache é específico para um modelo Gemini. A solicitação de comando do seu 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 solicitação 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 armazenamento em cache explícito:

Depois que um cache explícito é criado, não é possível mudar nada nele, exceto o TTL ou o tempo de expiração.
É 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 como um URI Cloud Storage. Não pode ser um URL do navegador ou do YouTube.

Além disso, as restrições de acesso ao arquivo são verificadas em cache-creation-time, e as restrições de acesso não são verificadas novamente em user-request-time. Por isso, verifique se 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 Google Search), o próprio cache precisará conter as configurações delas. Eles não podem ser configurados no modelo de solicitação do servidor ou na solicitação de solicitação do app. Observe que os modelos de solicitação do servidor ainda não são compatíveis com chamadas de função (ou chat). Para detalhes sobre como configurar instruções e ferramentas do sistema no seu cache, consulte a API REST do Vertex AI Gemini API.

Etapa 1: criar o cache

Crie o cache usando diretamente a API REST de 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 recurso totalmente qualificado name que é globalmente exclusivo para o 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: referenciar o cache em um modelo de solicitação do servidor

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

Siga estes requisitos ao criar o modelo de solicitação do servidor:

Use o recurso totalmente qualificado name da resposta quando você criou o cache. Esse não é o nome de exibição opcional especificado na solicitação.
O local do modelo de solicitação 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 solicitação do servidor.

Sintaxe:

{{cachedContent name="YOUR_CACHE_RESOURCE_NAME"}}

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

Exemplo:

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

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

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

Etapa 3: referenciar o modelo de solicitação do servidor na solicitação do app

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

Use o Vertex AI Gemini API, já que o cache foi criado com esse provedor Gemini API.
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 como gerenciar caches de conteúdo explícito, incluindo como listar todos os caches, receber metadados sobre um cache, atualizar o TTL ou o tempo de expiração de um cache e excluir um cache.

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

Depois que um cache de conteúdo explícito é criado, não é possível mudar nada nele, exceto o TTL ou o tempo de expiração.

Listar todos os caches

É possível listar todos os caches explícitos disponíveis para seu projeto. Esse comando retornará apenas 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, é possível 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 do recurso totalmente qualificado name 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 ser 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, a TTL padrão será de uma hora. Não há limites mínimos ou máximos para o TTL.

Para caches explícitos, é possível adicionar ou atualizar o ttl ou o expire_time. É necessário fornecer o CACHE_ID, que é o segmento final do recurso totalmente qualificado name 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.