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 plataforma de agentes do Gemini Enterprise oferece dois tipos de armazenamento em cache:

  • Armazenamento em cache implícito:armazenamento em cache automático ativado por padrão que oferece economia de custos quando ocorrem ocorrências em cache.
  • 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 precisam ou não se referir ao conteúdo armazenado em cache.

Para o armazenamento em cache implícito e explícito, o cachedContentTokenCount campo 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 cobranças pelos tokens de entrada usados para criar o cache com o 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 em que os caches são armazenados. Não há custos de armazenamento para o armazenamento em cache implícito. Para mais informações, consulte os preços da plataforma de agentes.

Armazenamento em cache implícito

Todos os Google Cloud projetos 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 ativado, as economias de custo de ocorrência em cache implícito são transferidas automaticamente para você. Para aumentar as chances de uma ocorrência em cache implícito:

  • 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 é compatível com os seguintes modelos:

O armazenamento em cache implícito também oferece suporte aos aliases mais recentes, incluindo:

  • gemini-flash-latest
  • gemini-flash-lite-latest

O armazenamento em cache implícito também oferece suporte a modelos abertos. Para mais informações, consulte Modelos abertos da plataforma de agentes 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 existente. Nos modelos Gemini 2.5 ou mais recentes, esse desconto é de 90%. Nos modelos Gemini 2.0, esse desconto é de 75%.

Usando a API Gemini Enterprise, é possível:

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 de 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:

O armazenamento em cache explícito também oferece suporte aos aliases mais recentes, incluindo:

  • gemini-flash-latest
  • gemini-flash-lite-latest

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 armazenamento em cache de contexto para casos de uso como estes:

  • 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 tem suporte na capacidade de processamento provisionada no pré-lançamento. Consulte o guia da 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 plataforma de agentes do Gemini Enterprise está disponível. Para mais informações, consulte IA generativa em locais da plataforma de agentes do Gemini Enterprise.

Limites

O conteúdo armazenado em cache explicitamente precisa obedecer aos limites mostrados na 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 e Gemini 3.1:4.096 tokens
  • Modelos Gemini 2.0 e 2.5: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

Suporte do VPC Service Controls

O armazenamento em cache de contexto oferece suporte ao VPC Service Controls, o que significa que o 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 também para proteger o conteúdo do cache.

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

A seguir