KV cache: como funciona e por que o contexto ainda pesa

A entrada em cache custa menos porque o modelo reaproveita um trabalho que já fez. O KV cache guarda 2 conjuntos de dados de atenção, as chaves e os valores, para que um modelo de linguagem de grande porte continue uma conversa sem reconstruir o estado de todos os tokens anteriores. Isso reduz o custo de processar um contexto repetido, mas conversas longas continuam ocupando memória e deixam mais contexto para cada novo token consultar.

Preserve os prefixos úteis e controle quanto histórico você mantém. São tarefas distintas. O prefixo é o início da requisição que permanece igual; armazená-lo em cache pode reduzir o processamento da entrada, mas não elimina o restante do trabalho de um agente.

Os preços e as regras de cache apresentados abaixo foram conferidos nas páginas de preços e na documentação dos fornecedores em 15 de outubro de 2026. Os cálculos de memória derivam das dimensões documentadas dos tensores, e não de medições em uma GPU específica.

O que é KV cache e como ele reaproveita um prompt?

KV cache é o estado de atenção salvo para reutilização. A atenção é o mecanismo que um transformer usa para incorporar informações anteriores relevantes à previsão atual. Um token, unidade de texto ou de outra entrada do modelo, produz representações numéricas em cada camada de atenção. O cache mantém as chaves e os valores daquela camada para uso posterior. A explicação de cache da Hugging Face descreve esse armazenamento por camada.

Os três papéis da atenção ficam mais claros se pensarmos em uma biblioteca de pesquisa:

• A consulta (query) expressa o que a posição atual procura.
• A chave (key) permite encontrar uma posição anterior por correspondência.
• O valor (value) fornece a informação que essa correspondência pode trazer.

Imagine organizar e indexar anotações de pesquisa antes de escrever um relatório. Cada nova frase pode consultar as anotações já preparadas. Refazer o índice e as notas a cada frase repetiria trabalho; mantê-los prontos ocupa espaço. A analogia, porém, não descreve a implementação: o modelo armazena arrays numéricos, não fichas legíveis nem um resumo dos seus documentos.

A consulta atual é comparada às chaves anteriores, e os pesos de atenção resultantes combinam os respectivos valores. Em um transformer causal, posições anteriores não podem consultar o futuro. Por isso, acrescentar um token mais adiante não exige alterar os estados já calculados das posições anteriores. É essa propriedade que permite reutilizá-los. O artigo original sobre PagedAttention descreve esses cálculos de atenção e o processo de geração.

Isso também explica por que o cache convencional guarda K e V, em vez de todas as consultas anteriores. A próxima previsão precisa da consulta atual e das chaves e dos valores acumulados; as consultas antigas já cumpriram sua função.

Em um agente de atendimento, os estados mantidos podem representar as instruções, as definições de ferramentas, os documentos de políticas e a conversa até aquele momento. Esses estados dependem do modelo e do contexto anterior. Não são os pesos aprendidos no treinamento do modelo nem um banco de dados permanente de memória sobre o cliente.

Um prefixo em cache também é diferente de uma resposta em cache. O modelo continua gerando uma nova continuação. Uma nova pergunta sobre o mesmo documento pode reaproveitar o estado já preparado desse documento sem devolver a resposta anterior.

Prefill e decode: como o KV cache entra na geração

O prefill prepara a entrada; o decode dá continuidade a ela. Essas fases explicam por que uma requisição pode começar a responder mais rápido quando encontra conteúdo no cache e, ainda assim, demorar para terminar.

Em um transformer autorregressivo convencional, o fluxo pode ser descrito assim:

Prefill: tokens do prompt → processar o prompt → manter chaves e valores por camada → prever o primeiro token de saída.

Decode: último token gerado + chaves e valores mantidos → processar esse token e consultar o contexto por atenção → prever o próximo token; acrescentar as novas chaves e os novos valores calculados.

Repetição do decode: reutilizar o cache crescente até o fim da geração.

O prefill pode processar em conjunto as posições já conhecidas do prompt. O decode avança por uma continuação cujos próximos tokens ainda não foram escolhidos. Essa diferença aparece na descrição do fluxo de geração e execução do artigo sobre PagedAttention.

O KV cache reduz o custo do próximo token em comparação com recalcular todo o prefixo. Isso não torna o custo desse token independente do tamanho do contexto. Na atenção completa convencional, sua consulta ainda interage com as chaves e os valores mantidos. Quanto mais contexto preservado, mais dados de atenção precisam ser usados. A Hugging Face documenta esse trabalho de atenção que permanece a cada passo.

Vale distinguir dois tipos de reaproveitamento. Dentro de uma resposta, o KV cache evita repetir cálculos durante a geração. Entre requisições, o cache de prefixo, também chamado de prompt caching nas APIs hospedadas, preserva os estados elegíveis para que uma chamada posterior pule parte do prefill. Um identificador de conversa, por si só, não comprova que esses estados estão disponíveis.

Suponha que um agente leia um documento de políticas, chame uma ferramenta e depois peça ao modelo que decida o que fazer com o resultado. A próxima requisição pode manter as instruções e o documento anteriores como prefixo comum e acrescentar o resultado da ferramenta ao final. Se o cache atender aos critérios de uso e estiver disponível, o fornecedor não precisa preparar novamente esse início compartilhado.

Para quem desenvolve com APIs, isso é motivo para acompanhar tanto a espera pelo primeiro token quanto o tempo gasto na geração da resposta. Receber o primeiro token mais cedo não comprova um decode mais rápido. A documentação de Automatic Prefix Caching do vLLM distingue explicitamente a economia no prefill do tempo de decode.

Como o trabalho reaproveitado vira entrada em cache na cobrança

O desconto se aplica ao trabalho de entrada reutilizado, conforme as regras de cobrança do fornecedor. Não há um percentual universal, e encontrar conteúdo no cache não dá desconto em todos os tokens da requisição.

Nas APIs que separam entrada comum, gravações em cache e leituras do cache, a parcela de entrada pode ser expressa assim:

Custo da entrada = (U × p_input + W × p_write + R × p_read) / 1,000,000

Aqui, U representa os tokens de entrada comum, W os tokens cobrados como gravações em cache e R os tokens cobrados como leituras do cache. Cada p é o preço por milhão de tokens daquela categoria. As categorias precisam ser mutuamente exclusivas: um token de gravação não deve ser cobrado novamente pela tarifa de entrada comum. É uma conta de análise dimensional com as categorias de preço da OpenAI e da Anthropic.

Depois, some a saída, as cobranças de ferramentas aplicáveis e qualquer armazenamento de cache cobrado à parte. O cache explícito do Google acrescenta o tempo de retenção à conta, por isso um modelo baseado apenas em gravações e leituras não basta nesse caso. Os exemplos ilustram as regras de cobrança; não são um ranking de modelos.

Anthropic: marque o prefixo que pode ser reutilizado

A Anthropic disponibiliza o cache de prompt por meio de cache_control, tanto no nível superior da requisição, para gerenciamento automático dos pontos de corte, quanto em blocos individuais de conteúdo. Um ponto de corte marca o fim do prefixo a preservar. A documentação de preços descreve as duas opções.

Exemplo de preços na API padrão do Claude: no Claude Sonnet 5.5, a entrada custa $2, as leituras do cache $0.10, as gravações com duração de 5 minutos $2.50 e as gravações de 1 hora $4, sempre por milhão de tokens. Preços da Anthropic.

Nesse modelo, o prefixo mínimo para uso do cache tem 512 tokens. O conteúdo precisa ser exatamente igual até o limite do cache. As leituras renovam sua duração sem nova cobrança de gravação, mas a contagem começa no início da requisição; portanto, a geração da resposta consome parte desse intervalo. Outros modelos Claude têm mínimos e descontos de leitura diferentes. Regras de cache de prompt da Anthropic.

Em um agente que trabalha com documentos e retoma a atividade depois de uma longa pausa do usuário, o tempo de retenção pode definir se a próxima chamada lê um prefixo existente ou o grava de novo. Confira cache_creation_input_tokens e cache_read_input_tokens nos dados de uso; repetir um documento não comprova, por si só, que houve uma leitura com desconto. Campos de uso.

OpenAI: confira as regras de gravação do modelo

A OpenAI ativa o cache de prompt por padrão nos modelos compatíveis, e os mais recentes aceitam pontos de corte implícitos e explícitos. O comportamento varia conforme o modelo. Cache de prompt da OpenAI.

Exemplo de preços na faixa Standard de contexto curto: no GPT-6.1 Sol, a entrada custa $2.00, a entrada em cache $0.10 e as gravações em cache $2.50 por milhão de tokens; as tarifas de entrada e de cache de toda a requisição dobram acima de 272K tokens de entrada. Preços da OpenAI, limite do modelo.

No GPT-5.6 e posteriores, o mínimo é de 1,024 tokens de entrada visíveis, e a duração documentada do cache é de pelo menos 30 minutos após a última gravação ou reutilização. A tarifa de gravação em cache substitui a de entrada comum para esses tokens; não é uma cobrança adicional de toda a entrada. Modelos anteriores seguem outras regras de gravação e retenção. Regras atuais de cache.

Na Responses API, confira usage.input_tokens_details.cached_tokens e cache_write_tokens. Manter uma sessão não garante que o cache será aproveitado. Consulte o guia de diagnóstico de cache de prompt do GPT-6 do site para investigar a organização da requisição e o uso informado.

Google Gemini: reutilização implícita e armazenamento explícito são diferentes

O Google Gemini oferece cache implícito automático, com a economia repassada quando há reutilização. No exemplo do Gemini 3.8 Flash, o mínimo documentado é de 4,096 tokens de entrada. Colocar o conteúdo comum no início e fazer requisições próximas no tempo aumenta a chance de reaproveitamento. Guia de cache de contexto do Google.

Exemplo de preços na modalidade paga Standard da Gemini Developer API: no Gemini 3.8 Flash, a entrada custa $0.75, a entrada em cache $0.075 por milhão de tokens e o armazenamento de cache explícito $0.50 por milhão de tokens por hora, até 31 de dezembro de 2026. Preços do Google.

O cache explícito usa um recurso nomeado de conteúdo em cache, com uma configuração de expiração, que requisições posteriores a generateContent referenciam. Como há cobrança de armazenamento, manter um documento sem uso ainda pode gerar custo. Referência da API de cache do Google.

A escolha da API faz diferença: a Interactions API aceita apenas cache implícito. O guia atual do Google também exclui o cache explícito para o Gemini 4 Argon e posteriores; os modelos compatíveis das famílias Gemini 3 e 2.5 usam generateContent para caches explícitos. Na Interactions API, confira usage.total_cached_tokens, conforme a documentação. Regras do Google por API.

Para quem opera com essas APIs, a diferença prática está entre acompanhar os reaproveitamentos automáticos e pagar deliberadamente para manter um recurso. Ao criar uma abstração de cache que atenda a vários fornecedores, não presuma que essas opções tenham o mesmo ciclo de vida.

Por que o KV cache cresce com o contexto mantido?

Nas camadas convencionais de atenção completa, a memória bruta do KV cache cresce linearmente com a quantidade de tokens mantidos. Uma conversa longa exige um conjunto de dados de trabalho cada vez maior, mesmo quando seu início se qualifica para um desconto na cobrança.

Para sequências de mesmo comprimento e camadas de atenção com geometria uniforme:

KV bytes ≈ 2 × B × T × L × H_kv × D × S

• 2: um array de chaves e um de valores.
• B: sequências simultâneas, supondo que seus dados de cache não sejam compartilhados.
• T: tokens processados e mantidos por sequência, incluindo os do prompt e os gerados.
• L: camadas de atenção que mantêm esse tipo de cache.
• H_kv: cabeças de chave/valor por camada.
• D: valores escalares por cabeça.
• S: bytes usados para armazenar cada valor escalar.

A fórmula deriva da contagem de elementos nas dimensões documentadas do cache por camada e na organização das cabeças de chave/valor do vLLM. Ela estima os tensores brutos, não toda a memória do dispositivo.

A quantidade de cabeças faz diferença. Na atenção com consultas agrupadas, em que várias cabeças de consulta compartilham cabeças de chave/valor, essa fórmula precisa usar o número de cabeças KV. Substituí-lo pela quantidade maior de cabeças de consulta superestimaria o cache.

Mantendo o modelo e a precisão de armazenamento, dobrar T dobra o cache denso bruto. Se você dobrar tanto T quanto o número de sequências independentes simultâneas, o cache fica quatro vezes maior. Esse resultado vem da álgebra; não é uma afirmação sobre a capacidade de uma GPU específica nem sobre uma taxa de processamento medida.

Para um serviço de atendimento em infraestrutura própria, surge uma pergunta útil de capacidade: quantos tokens mantidos estão ativos entre todos os clientes ao mesmo tempo? Fazer o modelo caber na memória é só o começo. O servidor também precisa acomodar o estado de inferência desses clientes, que muda ao longo do uso.

A documentação de estratégias de cache da Hugging Face descreve o limite das camadas com janela, enquanto o projeto do cache de prefixo do vLLM aborda os blocos físicos reutilizáveis. Quando a arquitetura usar algo diferente desses arrays densos convencionais de chaves e valores, siga sua organização de estado documentada.

Para quem usa uma API hospedada, esse crescimento aparece de outra forma: mais tokens podem ser cobrados como leituras a cada turno, mesmo com uma taxa estável de acertos no cache. Um preço unitário menor multiplicado por uma entrada crescente ainda resulta em uma cobrança crescente. A geração da saída também continua consultando o contexto por atenção, e os limites das faixas de preço podem depender do comprimento total da entrada.

Como otimizar o KV cache no vLLM

O vLLM, um motor de código aberto para servir LLMs, oferece a quem opera infraestrutura própria controles de alocação, reutilização e representação. Antes de mudar a implantação, escolha o controle que ataca seu gargalo.

PagedAttention: aloque blocos conforme a conversa cresce

O PagedAttention permite que a atenção opere sobre dados KV armazenados em blocos físicos separados. Uma sequência lógica não precisa de uma grande reserva contígua para todo o seu crescimento futuro possível. O projeto original reduz o desperdício de alocação e permite compartilhamento. Artigo sobre PagedAttention.

A analogia da biblioteca continua valendo: um projeto de pesquisa em expansão recebe trechos disponíveis das estantes, e um mapa registra sua ordem. Não é preciso reservar um corredor enorme e vazio antes de saber quanto material o projeto vai produzir.

O uso de páginas, por si só, não reduz a informação armazenada para cada token. Ele melhora a distribuição dessa informação na memória disponível. Além disso, o vLLM identifica sua página sobre o kernel de Paged Attention como histórica; aproveite o conceito sem tratar aquela descrição antiga do kernel como a implementação atual.

Cache de prefixo: poupe o trabalho já feito em outra requisição

O Automatic Prefix Caching reutiliza o estado KV de um prefixo correspondente. O vLLM documenta enable_prefix_caching=True; esse é o recurso relevante quando perguntas recorrentes sobre documentos ou turnos de um agente apresentam sempre o mesmo início. Automatic Prefix Caching.

A identidade do cache inclui o prefixo anterior, e não apenas o texto de um bloco isolado. Portanto, não se pode presumir que parágrafos idênticos, mas precedidos por instruções diferentes, sejam intercambiáveis. O projeto de cache baseado em hash do vLLM explicita essa dependência.

O limite está na carga de trabalho: prompts sem relação entre si compartilham pouco processamento, e respostas longas podem continuar gastando a maior parte do tempo no decode. Se a decisão envolve escolher o próprio motor de inferência, a comparação entre vLLM e SGLang aborda esse cenário mais amplo.

Quantização do KV cache: reduza os bytes por valor armazenado

A quantização do KV cache reduz a precisão dos valores numéricos armazenados. O vLLM aceita armazenamento de cache em FP8 por meio de kv_cache_dtype="fp8" e recomenda calibrar as escalas com um conjunto de dados para preservar a qualidade. As opções disponíveis dependem do backend de atenção. Documentação de cache quantizado do vLLM.

Passar de valores de 16 bits para 8 bits reduz pela metade o volume bruto dos dados escalares na fórmula, antes dos metadados de escala e da sobrecarga de alocação. Isso não reduz pela metade toda a memória do servidor nem comprova um ganho de velocidade medido. Quantizar os pesos do modelo é uma decisão separada de quantizar o estado de atenção.

Em um agente em produção, avalie as tarefas longas que realmente importam: manter as restrições, selecionar ferramentas e recuperar detalhes de mensagens anteriores. Um estado menor só é útil se a tarefa continuar sendo concluída corretamente. O simples fato de o servidor iniciar não comprova que a qualidade permaneceu igual.

Compressão do KV cache: diferencie precisão de conteúdo

Guardar valores menos precisos e manter menos posições envolvem escolhas diferentes. A quantização altera a representação dos valores. Uma janela de atenção limitada altera quais posições continuam disponíveis naquela camada. Os modos de falha dessas abordagens não devem ser agrupados sob uma alegação genérica de compressão. Estratégias de cache da Hugging Face.

Um primeiro passo prático é parar de enviar saídas irrelevantes das ferramentas. Isso reduz o contexto futuro na origem, mas é uma decisão da aplicação: antes de otimizar o estado mantido, preserve as evidências de que o agente precisa.

Offloading do KV cache: mantenha mais estado ao custo de transferências

O offloading move o estado reutilizável para outra camada de memória. O OffloadingConnector do vLLM pode manter blocos concluídos na memória do host, acessível pela CPU, e em camadas secundárias compatíveis, trazendo os blocos reutilizados de volta à GPU quando necessário. Guia de offloading do vLLM.

Isso pode ajudar quando prefixos continuam úteis por mais tempo do que permanecem na GPU. Em contrapartida, há movimentação de dados. Compare o benefício de evitar novos cálculos com o trabalho de transferência na sua carga; não existe um ganho universal de latência a citar.

Quando a demanda do estado KV ativo pressiona a memória disponível, o vLLM pode interromper requisições por preempção e refazer seus cálculos mais tarde. Seu guia de otimização recomenda examinar a concorrência e a alocação de memória quando essas interrupções se tornam frequentes. Para quem opera o serviço, o aumento no número de preempções orienta melhor uma ação do que a simples constatação de que a memória da GPU parece cheia.

O que a taxa de acertos no cache não conta

Uma taxa alta de acertos no cache não equivale a um agente eficiente. Ela mede reutilização, enquanto o negócio precisa de uma tarefa concluída com sucesso, dentro de um prazo e de um orçamento aceitáveis.

Uma conversa pode reaproveitar quase toda a entrada anterior e ainda crescer a cada turno. Pode reler repetidamente conteúdo irrelevante, pagando uma tarifa com desconto. Também pode gastar a maior parte do tempo gerando saída, etapa para a qual a reutilização de prefixos não oferece um atalho direto.

Não mantenha um histórico inchado só para proteger uma métrica de cache. Faça a compactação ou reinicie quando o material antigo deixar de ajudar, aceitando que um prefixo alterado pode precisar de novo processamento. A decisão deve acompanhar a qualidade da tarefa e o trabalho total. O guia de engenharia de contexto do site explica como decidir o que deve fazer parte do contexto de trabalho.

Para quem desenvolve usando APIs, vale otimizar desde já a organização dos prompts se as requisições compartilham conteúdo substancial com frequência. Se a carga raramente repete um prefixo, uma gestão elaborada de cache pode esperar. Para quem opera infraestrutura própria, investigue a pressão sobre a alocação e as preempções antes de concluir que o modelo precisa de mais capacidade de processamento. Uma carga de requisições curtas, isoladas e sem relação entre si oferece pouco trabalho a reaproveitar entre chamadas.

Dúvidas sobre KV cache em LLMs

O ChatGPT usa KV cache?

A OpenAI documenta o cache de prompt baseado em KV para suas APIs. Isso explica o funcionamento do recurso público da API, não todos os detalhes da infraestrutura interna que atende o ChatGPT. Ao desenvolver, siga as regras de cache publicadas e os campos de uso do modelo de API escolhido. Documentação da OpenAI.

Devo fazer offloading do KV cache para a memória da GPU?

Na inferência em GPU, o estado de atenção ativo é usado na GPU. No recurso de offloading do vLLM, os blocos reutilizáveis vão para a memória do host ou outras camadas compatíveis e voltam sob demanda. Considere essa opção quando preservar mais prefixos compensar o trabalho de transferência. Offloading no vLLM.

O que acontece quando o KV cache fica cheio?

O vLLM pode remover blocos em cache que não estão em uso; sob pressão de requisições ativas, pode interromper o trabalho por preempção e refazer os cálculos depois. Isso afeta a latência. É uma situação diferente de ultrapassar o limite da janela de contexto do modelo. Gerenciamento de cache, preempção.

Como reduzir o KV cache?

Reduza o contexto mantido ou o número de sequências simultâneas, reutilize prefixos compartilhados elegíveis ou avalie armazenar o cache com menor precisão. O offloading muda onde o estado fica, sem necessariamente reduzir seu tamanho total. Avalie o resultado pela qualidade da tarefa e pela latência observada, além da memória. Estratégias de cache.

Três hábitos para manter uma boa taxa de acertos no cache dos agentes

Mantenha o início estável e, durante uma tarefa ativa, acrescente as mudanças apenas ao final. A reutilização de prefixos exatos favorece requisições previsíveis, dentro das regras de tamanho mínimo, retenção e disponibilidade do fornecedor.

1. 1

   Deixe o prompt de sistema estável no início

   Coloque as instruções duradouras, as definições de ferramentas e o material de referência reutilizável antes dos dados variáveis da tarefa, respeitando a estrutura de mensagens exigida pela API. Mantenha estáveis a redação, a ordem das ferramentas e a serialização. Na Anthropic, a hierarquia é ferramentas, sistema e, depois, mensagens; alterar o conjunto de ferramentas pode invalidar o reaproveitamento do conteúdo seguinte. Estrutura de cache da Anthropic.

2. 2

   Acrescente ao histórico em vez de reescrevê-lo

   Preserve as mensagens anteriores e acrescente o novo turno do usuário, a chamada de ferramenta do assistente ou o resultado da ferramenta. Evite reconstruir os turnos anteriores com resumos ou formatação que mudam a cada chamada. Quando for necessário compactar, faça disso um ponto de mudança deliberado e estabeleça um novo prefixo estável dali em diante. Essa prática decorre da dependência entre cada bloco e os tokens que o precedem. Identidade do prefixo no vLLM.

3. 3

   Tire os timestamps do início

   Coloque a hora atual, o identificador da requisição e outros metadados variáveis depois do material reutilizável. Um timestamp no começo pode invalidar a reutilização do contexto que vem em seguida. Com pontos de corte explícitos, marque o fim do prefixo estável, antes do sufixo variável. Orientações da Anthropic sobre pontos de corte.

No próximo dia de trabalho, examine uma conversa representativa de um agente no ponto em que as requisições são montadas. Compare o prefixo exato de chamadas sucessivas e confira as gravações e leituras de cache informadas pelo fornecedor junto com a entrada total, a saída e a latência. Corrija um prefixo instável antes de trocar de fornecedor. Se a taxa de acertos já estiver boa e o agente continuar lento, investigue o contexto mantido, o tamanho da saída e a disputa por recursos do servidor.

Assine a newsletter para receber explicações práticas sobre os sistemas por trás dos agentes de IA.