Visão geral do armazenamento em cache de contexto

O armazenamento em cache de contexto ajuda a reduzir o custo e a latência das solicitações ao Gemini que contêm conteúdo repetido. A Gemini Enterprise Agent Platform oferece dois tipos de armazenamento em cache:

  • Armazenamento em cache implícito: armazenamento em cache automático ativado por padrão que gera economia de custos quando ocorrem ocorrências em cache. O armazenamento em cache implícito inclui o armazenamento em cache na memória e o armazenamento em cache durável.
  • Armazenamento em cache explícito: armazenamento em cache manual ativado usando a API Gemini Enterprise, em que você declara explicitamente o conteúdo que quer armazenar em cache e se os comandos devem ou não se referir ao conteúdo armazenado em cache.

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.

Custos de armazenamento em cache

Para o armazenamento em cache implícito e explícito, você recebe uma cobrança pelos tokens de entrada usados para criar o cache pelo preço padrão do token de entrada. Para o armazenamento em cache explícito, também há custos de armazenamento com base no tempo de armazenamento dos caches. Não há custos de armazenamento para o armazenamento em cache implícito. Para mais informações, consulte Preços da Agent Platform.

Armazenamento em cache implícito

Todos os projetos do Google Cloud têm o armazenamento em cache implícito ativado por padrão. O armazenamento em cache implícito oferece um desconto de 90% nos tokens armazenados em cache em comparação com os tokens de entrada padrão. Quando ativada, a economia de custos implícita de ocorrência em cache é repassada automaticamente para você.

O armazenamento em cache implícito armazena prefixos em dois níveis de armazenamento:

  • Cache em memória: os prefixos em cache são mantidos na memória. A capacidade de memória é limitada, então os prefixos são removidos à medida que a capacidade é recuperada.
  • Armazenamento em cache durável: quando um prefixo é removido do armazenamento na memória, ele é movido para o armazenamento durável em vez de ser descartado. Uma solicitação posterior que reutiliza o prefixo ainda pode receber uma ocorrência em cache, o que aumenta as taxas de ocorrência em cache para cargas de trabalho que reutilizam o mesmo contexto em intervalos mais longos.

Os dois níveis são ativados por padrão. Um prefixo em cache expira no máximo 24 horas após a criação, e a maioria das entradas é removida antes disso. É possível desativar o armazenamento em cache durável e manter o cache em memória ou desativar completamente o armazenamento em cache implícito. Se você tiver dúvidas sobre a retenção de dados, consulte Retenção de dados zero, que descreve como os dados em cache são processados e como desativar cada nível.

Para aumentar a probabilidade de uma ocorrência em cache implícita, faça o seguinte:

  • Coloque conteúdos grandes e comuns no início do comando.
  • Envie solicitações com um prefixo semelhante em um curto período.

Modelos compatíveis

O armazenamento em cache implícito está disponível nos modelos do Gemini compatíveis, e o armazenamento em cache durável está disponível em um subconjunto desses modelos.

Caches na memória

O armazenamento em cache na memória é compatível com os seguintes modelos:

Clique para abrir os modelos compatíveis

Armazenamento em cache durável

O armazenamento em cache durável é compatível com os seguintes modelos:

O armazenamento em cache implícito também é compatível com modelos abertos. Para mais informações, consulte Modelos abertos da Agent Platform para MaaS.

Armazenamento em cache explícito

O armazenamento em cache explícito oferece mais controle e garante um desconto nos tokens de entrada que fazem referência a um cache de contexto atual. Nos modelos Gemini 2.5 ou mais recentes, esse desconto é de 90%. Nos modelos Gemini 2.0, o desconto é de 75%.

Com a API Gemini Enterprise, é possível realizar as seguintes tarefas:

Também é possível usar a API Gemini Enterprise para recuperar informações sobre um cache de contexto.

Os caches 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 especificado ao criar um cache. Para evitar a retenção de dados em cache, desative o armazenamento em cache implícito e evite criar caches explícitos. Para mais informações, consulte Ativar e desativar o armazenamento em cache.

Modelos compatíveis

O armazenamento em cache explícito é compatível com os seguintes modelos:

Clique para abrir os modelos compatíveis

Quando usar o armazenamento em cache de contexto

O armazenamento em cache de contexto é particularmente adequado para cenários em que um contexto inicial substancial é referenciado repetidamente por solicitações subsequentes.

Itens de contexto armazenados em cache, como uma grande quantidade de texto, um arquivo de áudio ou um arquivo de vídeo, podem ser usados em um solicitações de comando à API Gemini para gerar saída. Solicitações que usam o mesmo cache no comando também podem incluir textos exclusivos para cada comando. Por exemplo, cada solicitação de comando que compõe uma conversa no chat pode incluir o mesmo cache de contexto que faz referência a um vídeo junto com um texto exclusivo que compreende cada turno no chat.

Use o armazenamento em cache de contexto para os seguintes casos de uso:

  • Chatbots com instruções abrangentes do sistema
  • Análise repetitiva de arquivos de vídeo longos
  • Consultas recorrentes em grandes conjuntos de documentos
  • Análise frequente do repositório de código ou correção de bugs

O armazenamento em cache implícito e explícito é compatível com a Capacidade de Processamento Provisionada em pré-lançamento. Consulte o guia de capacidade de processamento provisionada para mais detalhes. Os caches funcionam em todos os tipos de tráfego. Por exemplo, um cache criado ao usar a Capacidade de Processamento Provisionada também funciona com o PayGo.

Disponibilidade

O armazenamento em cache de contexto está disponível nas regiões em que a IA generativa na Agent Platform está disponível. Para mais informações, consulte IA generativa em locais da Agent Platform.

Limites

O armazenamento em cache de contexto segue os limites da tabela a seguir:

Limites de armazenamento em cache contextual

Contagem mínima de tokens de cache para armazenamento em cache implícito e explícito
  • Modelos Gemini 3 (com exceções) e Gemini 4: 4.096 tokens
  • Pré-lançamento do Gemini 3.0 Flash, pré-lançamento do 3.1 Pro, 3.7 Flash e 3.8 Flash (somente armazenamento em cache implícito): 6.144 tokens
  • Modelos da família Gemini 2: 2.048 tokens

Tamanho máximo de conteúdo que pode ser armazenado em cache usando um blob ou texto

 10 MB

Tempo mínimo antes de um cache expirar após ser criado

 1 minuto

O tempo máximo para que um cache expire após ser criado

 Não há uma duração máxima de cache

Ciclo de vida máximo de um prefixo armazenado em cache implicitamente

 Até 24 horas

Isolamento e segurança de dados em cache para cargas de trabalho de agentes

OGoogle Cloud usa o número do projeto para isolar os dados armazenados em cache, e o conteúdo em cache nunca é compartilhado entre projetos.

Para evitar o vazamento de dados entre usuários em cargas de trabalho de agentes, limite os dados e as saídas de comandos armazenados em cache para cada sessão de usuário. Ao executar agentes em segundo plano ou proxies multilocatários, alinhe os limites de cache com as permissões do usuário final para que um agente não possa reutilizar credenciais ou dados armazenados em cache entre usuários.

Suporte do VPC Service Controls

O armazenamento em cache de contexto é compatível com o VPC Service Controls, o que significa que seu cache não pode ser exfiltrado além do perímetro de serviço. Se você usar o Cloud Storage para criar o cache, inclua o bucket no perímetro de serviço para proteger o conteúdo do cache.

Para mais informações, consulte VPC Service Controls com a plataforma de agentes na documentação da plataforma de agentes.

A seguir