SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor · Atualizado 2026-10-22

Cache KV ou cache de prompt: qual é a diferença?

Entenda por que o cache KV consome RAM ou VRAM a cada pedido e pode impedir o carregamento do modelo, enquanto o cache de prompt só reduz custo e latência.

Cache KV versus cache de prompt: a resposta curta

O cache KV e o cache de prompt de um fornecedor partilham uma palavra e quase nada mais. O cache KV é memória de trabalho por pedido. Fica na RAM ou VRAM do seu servidor durante toda a duração de um pedido e aumenta com o tamanho do contexto e com o número de pedidos executados em simultâneo. O cache de prompt do fornecedor é uma funcionalidade de faturação e latência. Um prefixo estável do seu prompt é armazenado nos servidores do fornecedor e, quando o envia novamente, é cobrado com desconto.

Um é memória que compra como hardware. O outro é memória que outra entidade mantém e cujo uso lhe cobra.

A diferença prática é mais importante do que a definição. Pode ficar sem cache KV. Quando isso acontece, o modelo não carrega ou o pedido é rejeitado. Não pode ficar sem cache de prompt. Só pode não o atingir e, nesse caso, paga silenciosamente o preço total.

O que a cache KV armazena e por que existe

Um transformer que gera o token número 500 precisa de aplicar atenção aos 499 tokens anteriores. Para cada um desses tokens, todas as camadas precisam de um vetor de chave e de um vetor de valor. Recalcular todos esses vetores para cada novo token faria com que o tempo de geração crescesse com o quadrado do comprimento da sequência. Por isso, o runtime mantém-nos armazenados. Esse armazenamento é a cache KV (cache de chave/valor).

O estado é específico de cada pedido porque é construído a partir da sequência exata de tokens desse pedido. Dois utilizadores que enviem prompts diferentes não podem partilhar essa cache, exceto quando o runtime utiliza caching de prefixos. Essa é uma funcionalidade separada, descrita mais adiante.

O serving ocorre em duas fases. O prefill lê todo o prompt e preenche a cache. Essa fase é limitada pela capacidade de processamento. O decode produz um token de cada vez e acrescenta-o à cache. Essa fase é limitada pela largura de banda da memória. É por isso que o processamento do prompt e a geração de tokens apresentam velocidades diferentes quando mede tokens por segundo no seu próprio servidor.

Quanta memória a cache KV usa?

Não procure uma tabela do fornecedor. O tamanho é uma operação aritmética que pode repetir para qualquer modelo:

bytes per token = 2 * layers * kv_heads * head_dim * bytes per element

O 2 representa a chave e o valor. Todos os outros números vêm da config.json do modelo, publicada na página do modelo no Hugging Face.

Considere o Llama 3.1 8B. A configuração indica num_hidden_layers 32 e num_key_value_heads 8. A hidden_size de 4096 distribuída por 32 cabeças de atenção dá uma dimensão de cabeça de 128. Em f16, cada elemento ocupa 2 bytes:

2 * 32 * 8 * 128 * 2 = 131072 bytes = 128 KiB per token

Multiplique esse valor pelo contexto solicitado e depois pelo número de pedidos executados em simultâneo.

GráficoLlama 3.1 8B KV cache at f16, in GiB
Os dados por trás deste gráfico
[
  {
    "label": "2k context",
    "one_request_gib": 0.25,
    "four_requests_gib": 1
  },
  {
    "label": "8k context",
    "one_request_gib": 1,
    "four_requests_gib": 4
  },
  {
    "label": "32k context",
    "one_request_gib": 4,
    "four_requests_gib": 16
  },
  {
    "label": "128k context",
    "one_request_gib": 16,
    "four_requests_gib": 64
  }
]

Com um contexto de 8k, a cache ocupa 1 GiB para um pedido. Com 32k, ocupa 4 GiB, um valor da mesma ordem dos próprios pesos de 4 bits. No contexto máximo de 128k do modelo, ocupa 16 GiB para um pedido e 64 GiB se quatro pedidos preencherem o contexto. Os pesos não mudaram. Apenas a cache mudou.

A atenção de consulta agrupada (GQA) tem um papel importante nesse valor. O Llama 3.1 8B tem 8 cabeças de chave/valor a servir 32 cabeças de consulta, pelo que quatro cabeças de consulta partilham cada par de chave/valor armazenado. Um modelo cujo num_key_value_heads seja igual ao seu num_attention_heads usa quatro vezes mais cache com o mesmo número de parâmetros. Verifique esse campo antes de assumir que dois modelos 8B têm o mesmo custo de execução.

Por que um modelo que funcionava com 2k se recusa a carregar com 32k

Isto acontece porque o runtime reserva a KV cache quando carrega o modelo. O tamanho da reserva corresponde ao context length configurado, não ao prompt que efetivamente envia. O valor predefinido do Ollama já não é um único número. Desde outubro de 2026, a documentação do context length define o valor com base na VRAM: 4k em máquinas com menos de 24 GiB, 32k entre 24 e 48 GiB e 256k com 48 GiB ou mais. Os modelos cloud usam, por predefinição, o valor máximo. Uma VPS apenas com CPU ou uma GPU pequena começa com 4k. Se aumentar esse valor para 32k, está a pedir uma alocação adicional de 4 GiB antes de chegar um único token. Numa placa de 24 GiB, 32k já é o valor predefinido. A reserva é feita mesmo que não a tenha pedido.

OLLAMA_CONTEXT_LENGTH=32768 ollama serve

A mesma configuração por sessão, a partir do prompt interativo:

ollama run llama3.1:8b
/set parameter num_ctx 32768

A falha apresenta-se de forma diferente em cada stack. O vLLM verifica os cálculos no arranque e recusa iniciar:

ValueError: To serve at least one request with the model's max seq len (131072), (16.0 GiB KV cache is needed, which is larger than the available KV cache memory (9.56 GiB). Based on the available memory, the estimated maximum model length is 78336. Try increasing `gpu_memory_utilization` (which also controls CPU memory on the CPU backend) or decreasing `max_model_len` when initializing the engine. See https://docs.vllm.ai/en/latest/configuration/conserving_memory/ for more details.

Numa VPS apenas com CPU que execute Ollama ou llama.cpp, a alocação usa a RAM normal do sistema e a falta de memória pode não ser detetada no arranque. Nesse caso, o kernel termina o processo através do out-of-memory killer e deixa a evidência no buffer circular do kernel:

dmesg -T | grep -i "killed process"

Uma linha que identifique o processo de serving significa que o sistema prometeu mais memória do que tinha disponível. A correção é reduzir o context length, não aumentar o ficheiro de swap: uma KV cache paginada para o disco é lida em cada token gerado, o que torna a geração demasiado lenta para ser útil. A escolha de um valor adequado é explicada no nosso guia sobre num_ctx e context length no Ollama.

Como a simultaneidade afeta o número

Cada pedido em curso mantém a sua própria cache KV. Este é o ponto que a maioria dos planos de capacidade ignora. Quatro utilizadores, cada um com um contexto de 32k, precisam de 16 GiB no total, além dos pesos.

Os runtimes diferem quanto ao rigor com que aplicam este limite. Ollama e llama.cpp reservam o contexto solicitado quando o modelo é carregado, pelo que a memória fica comprometida mesmo que ninguém a utilize. O vLLM divide o pool em blocos de tamanho fixo e atribui-os à medida que cada pedido cresce, pelo que um pedido de 500 tokens ocupa apenas o espaço correspondente a 500 tokens. Em qualquer dos casos, o pool é finito. Quando fica cheio, os novos pedidos entram em fila em vez de serem executados. O impacto dessa fila nos tempos de resposta é explicado em quantos utilizadores simultâneos um LLM autoalojado pode servir.

Quatro formas de reduzir o tamanho da cache KV

  1. Reduza o comprimento do contexto. Esta é a medida com maior impacto e, normalmente, a mais barata. A maioria das cargas de trabalho de chat nunca se aproxima de 32k.
  2. Quantize a própria cache. O OLLAMA_KV_CACHE_TYPE do Ollama usa f16 por predefinição e aceita q8_0, que usa cerca de metade da memória, e q4_0, que usa cerca de um quarto. Os equivalentes no llama.cpp são -ctk q8_0 e -ctv q8_0.
  3. Escolha um modelo com menos cabeças de key/value ou menos camadas. Leia config.json antes de descarregar 40 GB de pesos.
  4. Sirva menos pedidos em simultâneo e coloque os restantes em fila.

Em q4_0, o valor do Llama 3.1 8B desce de 128 KiB por token para cerca de 32 KiB. Assim, 32k de contexto ocupa cerca de 1 GiB, em vez de 4 GiB. Esta redução não é gratuita. As keys e os values são armazenados com menor precisão. Por isso, compare a saída com os seus próprios prompts antes de manter esta configuração.

O que o cache de prompts do provedor oferece na prática

O cache de prompts do provedor é um produto diferente, com uma unidade de contabilização diferente. Você marca um prefixo estável, o provedor armazena esse prefixo e as chamadas posteriores que repetem exatamente o mesmo prefixo são cobradas a uma tarifa reduzida, em vez do preço integral de entrada.

Os multiplicadores publicados pela Anthropic, em outubro de 2026, são os seguintes: uma gravação de cache de 5 minutos custa 1.25 vezes o preço base dos tokens de entrada. Uma gravação de 1 hora custa 2 vezes, e uma leitura do cache custa 0.1 vezes na maioria dos modelos. Nos modelos mais recentes, a leitura custa ainda menos: 0.05 vezes no Claude Opus 5.5 e no Sonnet 5.5, e 0.025 vezes no Claude Fable 5.1 e no Mythos 5.1. Se você colocar um prompt de sistema com 20,000 tokens atrás dos números padrão, o benefício fica evidente.

GráficoCost of a 20,000 token prefix, in base input token equivalents
Os dados por trás deste gráfico
[
  {
    "label": "No caching, every call",
    "billed_token_equivalents": "20,000"
  },
  {
    "label": "First call, 5 minute cache write",
    "billed_token_equivalents": "25,000"
  },
  {
    "label": "First call, 1 hour cache write",
    "billed_token_equivalents": "40,000"
  },
  {
    "label": "Every later call, cache hit",
    "billed_token_equivalents": "2,000"
  }
]

Veja isso como uma conta. O adicional da gravação de 5 minutos equivale a 5,000 tokens na primeira chamada: 25,000 contra 20,000 para enviá-lo sem cache. Cada chamada posterior dentro da janela cobra 2,000 em vez de 20,000, uma economia de 18,000. Portanto, o cache de 5 minutos já compensa a partir da segunda chamada.

O cache de 1 hora envolve uma decisão diferente. A gravação cobra 40,000, um adicional de 20,000 tokens equivalentes. Por isso, são necessários dois acertos dentro da hora para começar a compensar. Isso depende do padrão do seu tráfego, não do modelo. O cálculo completo, incluindo como escolher a janela, está em a matemática do ponto de equilíbrio do cache de prompts do Claude.

Dois detalhes determinam se você conseguirá usar o cache. Primeiro, um prefixo menor que o comprimento mínimo do modelo não é armazenado em cache, sem aviso: em outubro de 2026, o mínimo documentado é de 512 tokens para Claude Opus 5, Opus 5.5 e Sonnet 5.5, e de 1,024 tokens para Claude Sonnet 5. Uma solicitação menor é processada normalmente, sem retornar erro. Segundo, a validade é medida a partir do início da solicitação que grava ou lê a entrada, e cada leitura renova essa validade sem custo adicional. Portanto, um endpoint com muitas chamadas mantém um cache de 5 minutos ativo indefinidamente. Um endpoint chamado uma vez a cada dez minutos paga o adicional de gravação todas as vezes e nunca obtém o benefício.

Verifique a resposta em vez de presumir. O objeto usage informa cache_creation_input_tokens e cache_read_input_tokens. Uma contagem de leituras igual a zero em todas as chamadas significa que você está pagando pelas gravações sem receber nenhum benefício.

Onde as duas caches se encontram

Um prompt de sistema longo é o ponto de encontro, e é cobrado dos dois lados ao mesmo tempo.

Localmente, um prompt de sistema com 20,000 tokens ocupa cerca de 2.4 GiB de cache KV num servidor Llama 3.1 8B a f16. Esse espaço é ocupado separadamente por cada pedido concorrente que inclua o prompt. Remotamente, o mesmo prefixo custa uma escrita na cache e, em cada chamada posterior, 0.1 vezes o custo de entrada, ou menos nos modelos mais recentes. O custo local cresce com o número de utilizadores. O custo remoto cresce com o tráfego e é reposto durante os períodos de inatividade.

Existe uma funcionalidade local semelhante ao prompt caching dos fornecedores e que é frequentemente confundida com ele: o prefix caching. A documentação do vLLM descreve o automatic prefix caching como a colocação em cache "da cache KV de consultas existentes, para que uma nova consulta possa reutilizar diretamente a cache KV se partilhar o mesmo prefixo com uma das consultas existentes". As versões atuais do vLLM ativam-no por predefinição. O servidor llama.cpp mantém uma prompt cache por slot, também por predefinição, e --cache-reuse N define o menor bloco que tentará reutilizar.

O prefix caching poupa no processamento de prefill. O prompt de sistema com 20,000 tokens é processado uma vez, em vez de ser processado em cada pedido, o que reduz bastante o tempo até ao primeiro token. No vLLM, os blocos partilhados são reutilizados em vez de duplicados, pelo que o consumo de memória também melhora. O que esta funcionalidade nunca faz é reduzir a cache que tem de manter para os tokens atualmente ativos. Manter os pesos residentes entre pedidos é um mecanismo relacionado, mas separado, descrito em manter um modelo Ollama carregado entre pedidos.

O que medir no seu próprio servidor

Carregue o modelo com o contexto pretendido e leia os valores reais, em vez de confiar na estimativa.

ollama ps
nvidia-smi --query-gpu=memory.used,memory.total --format=csv
free -g

ollama ps lista o modelo carregado, o respetivo tamanho, o contexto usado no carregamento e se está a ser executado na GPU ou na CPU. Verifique primeiro a coluna do contexto, porque o valor predefinido depende agora da sua VRAM. Se um modelo que esperava manter inteiramente na GPU indicar uma divisão com a CPU, isso significa que a cache KV expulsou parte do modelo, e a velocidade de geração diminuirá em conformidade. nvidia-smi apresenta o valor real de VRAM, e free -g faz o mesmo num VPS apenas com CPU. Aumente o contexto gradualmente, recarregue o modelo e observe como o valor muda. Os seus cálculos e o valor apresentado devem ficar próximos. Quando isso não acontece, a diferença costuma corresponder aos buffers de computação próprios do runtime, e não a um erro na fórmula.

Se estes valores o levarem a considerar hardware que preferia não alugar, a comparação com o pagamento por token está detalhada em GPU VPS em comparação com tokens de API.

FAQ

A cache KV é a mesma coisa que o caching de prompts?

Não. A cache KV é memória por pedido dentro do processo de serving. Guarda os vetores key e value de cada token no contexto atual. Fica na RAM ou VRAM e é libertada quando o pedido termina. O prompt caching do fornecedor é uma funcionalidade de faturação. Armazena um prefixo estável do prompt na infraestrutura do fornecedor e aplica uma tarifa reduzida quando o envia novamente. Ficar sem cache KV impede o carregamento do modelo. Não encontrar o prompt cache apenas aumenta a fatura e o tempo até ao primeiro token.

Porque é que o meu modelo carrega com um contexto de 2k, mas falha com 32k?

Porque o runtime aloca toda a cache KV no carregamento. O tamanho é calculado com base no comprimento de contexto configurado, não no prompt que envia. Para Llama 3.1 8B em f16, a cache ocupa 128 KiB por token. Assim, um contexto de 2k custa 0.25 GiB e 32k custa 4 GiB. Os pesos cabem nos dois casos. O que falha é a reserva. O vLLM comunica o problema através de um ValueError. Esse erro indica quanta memória de cache KV é necessária e quanta está disponível, apresenta um comprimento máximo estimado para o modelo e sugere aumentar gpu_memory_utilization ou reduzir max_model_len. Num sistema apenas com CPU que execute Ollama ou llama.cpp, o kernel pode terminar o processo através do mecanismo out-of-memory. Pode confirmar isso com dmesg -T | grep -i "killed process".

Como calculo o tamanho da cache KV para o meu modelo?

Multiplique 2 pelo número de camadas, pelo número de cabeças key/value, pela dimensão da cabeça e pelo número de bytes por elemento. O resultado é o número de bytes por token. Depois, multiplique esse valor pelo comprimento do contexto e pelo número de pedidos concorrentes. Consulte o número de camadas e de cabeças no config.json do modelo. Use 2 bytes por elemento para f16 ou bf16. Uma cache q8_0 ocupa aproximadamente metade desse valor. Uma cache q4_0 ocupa aproximadamente um quarto.

O prompt caching reduz a memória necessária no meu próprio servidor?

O prompt caching do fornecedor não tem efeito sobre o seu hardware, porque o armazenamento fica do lado do fornecedor. O equivalente local é o prefix caching, disponibilizado pelo vLLM e pelo servidor llama.cpp. Esta funcionalidade reutiliza os vetores key e value já calculados para um prefixo partilhado. Poupa computação de prefill e reduz o tempo até ao primeiro token. No vLLM, os blocos partilhados são reutilizados em vez de duplicados. Por isso, o consumo de memória também melhora. Nenhuma das funcionalidades reduz a cache necessária para os tokens que estão atualmente em processamento. O seu cálculo de contexto e concorrência continua a definir o mínimo necessário.

Vale a pena colocar em cache um prompt que só envio uma vez?

Não. Escrever na cache custa mais do que usar uma entrada normal. A opção de 5 minutos custa 1.25 vezes a tarifa base em October 2026. Por isso, um prefixo que nunca volte a enviar dentro dessa janela representa uma perda direta. O caching compensa quando o mesmo prefixo se repete. Exemplos incluem um system prompt longo ou um documento sobre o qual fará várias perguntas. Consulte cache_read_input_tokens na resposta da API para confirmar que está a obter cache hits em vez de pagar por operações de escrita.

Este artigo foi útil?