DeepSeek Context Caching é o cache em disco da API que reaproveita prefixos de entrada processados anteriormente. O recurso está ativado por padrão, não exige uma chamada especial e pode reduzir o custo de prompts repetidos quando ocorre cache hit.
Atualização documental — 23 de agosto de 2026. O Context Caching continua ativado automaticamente e opera em melhor esforço. Os três IDs atuais possuem tarifas separadas de cache hit e cache miss. O teste de texto com V4 Flash abaixo permanece datado de 29/07; seus números, latência e custo não foram recalculados.
Preços atuais: o pico ocorre das 01:00 às 04:00 UTC e das 06:00 às 10:00 UTC, de segunda a sexta-feira; todos os demais horários são fora de pico.
Teste ao vivo: cache hit em requisições idênticas
Fizemos uma sequência controlada com V4 Flash, Thinking desativado, resposta não streaming e dois corpos JSON idênticos. O texto continha 60 linhas sintéticas e nenhum dado pessoal.
| Métrica | 1ª chamada | 2ª chamada |
|---|---|---|
| HTTP | 200 | 200 |
| Latência observada | 340 ms | 330 ms |
prompt_tokens | 1.294 | 1.294 |
prompt_cache_hit_tokens | 0 | 1.280 |
prompt_cache_miss_tokens | 1.294 | 14 |
completion_tokens | 1 | 1 |
| Taxa de hit | 0% | 98,92% |
- Corpo: 4.699 bytes; 60 linhas sintéticas; intervalo de 15 segundos.
- SHA-256 do corpo:
5d8d53512b6d0dee35b44a59489f9e5fcfb42baf5e21bddd8e24b00a57f2ce7d. - Na tarifa vigente em 29/07/2026, o custo histórico calculado caiu de US$ 0,00018144 para US$ 0,000005824 nesta amostra.
Limite: uma única sequência não garante acerto futuro. A diferença de 10 ms não é benchmark de latência; seriam necessárias repetições e controle de rede.
Veja a memória de cálculo, Token Usage e a documentação oficial de Context Caching.
Atualização verificada em 29 de julho de 2026: o cache não guarda a resposta pronta. O modelo gera uma nova saída. Em Non-Thinking Mode, parâmetros de amostragem podem influenciar essa saída; no Thinking Mode atual,
temperature,top_p,presence_penaltyefrequency_penaltysão ignorados.
Este guia é independente e trata apenas do cache da API hospedada, não do histórico do aplicativo ou do chat público da DeepSeek.
Resumo em 30 segundos
- O Context Caching está habilitado automaticamente para usuários da API.
- Ele reutiliza unidades persistidas do prefixo da entrada, não respostas prontas.
- O benefício aparece em
usage.prompt_cache_hit_tokens. - Tokens sem reaproveitamento aparecem em
usage.prompt_cache_miss_tokens. - O sistema funciona em regime de melhor esforço e não garante 100% de acerto.
- Para texto, use
deepseek-v4-flashoudeepseek-v4-pro; quando a entrada tiver imagem, use o experimentaldeepseek-v4-flash-vision-exp. - No Thinking Mode, os parâmetros de temperatura e penalidade não produzem efeito.
O que é DeepSeek Context Caching?
Quando várias requisições começam com o mesmo conteúdo — instruções de sistema, documentos, exemplos ou histórico — a DeepSeek pode persistir unidades desse prefixo em cache. Uma chamada posterior que corresponda integralmente a uma dessas unidades pode buscar essa parte do cache em vez de processá-la como cache miss.
A economia é aplicada aos tokens de entrada com cache hit. O recurso não substitui memória de conversa, RAG ou um cache de respostas criado pela sua aplicação.
| Recurso | O que reutiliza | Quem controla | Gera nova resposta? |
|---|---|---|---|
| DeepSeek Context Caching | Prefixos de entrada persistidos | DeepSeek, automaticamente | Sim |
| Memória da aplicação | Histórico ou fatos salvos | Seu backend | Sim, após reenviar contexto |
| RAG | Trechos recuperados de uma base | Sua aplicação e banco vetorial | Sim |
| Cache de resposta | Uma saída já pronta | Seu backend ou CDN | Não, quando há hit |
Como o cache funciona
A documentação oficial descreve três formas de persistência de unidades de prefixo:
- Limites da requisição: são criadas unidades no fim da entrada do usuário e no fim da saída do modelo.
- Detecção de prefixo comum: o sistema pode identificar a parte inicial compartilhada por várias requisições e persistir essa unidade.
- Intervalos fixos de tokens: entradas ou saídas longas podem ser divididas em unidades, evitando que um prefixo longo dependa apenas do ponto final.
Exemplo 1: continuação direta
Primeira requisição: A + B Segunda requisição: A + B + C Possível hit na segunda requisição: A + BExemplo 2: prefixo comum descoberto
Primeira requisição: A + B Segunda requisição: A + C Terceira requisição: A + D As duas primeiras podem não ter hit entre si. Depois de detectar e persistir o prefixo A, a terceira pode gerar hit em A.Por isso, duas entradas apenas “parecidas” não garantem acerto imediato. A correspondência precisa reutilizar integralmente uma unidade de prefixo que já tenha sido persistida.
Como verificar cache hit e cache miss
A resposta da API inclui métricas na seção usage. Os campos centrais são:
| Campo | Significado |
|---|---|
prompt_cache_hit_tokens | Tokens de entrada atendidos pelo cache |
prompt_cache_miss_tokens | Tokens de entrada processados sem acerto |
prompt_tokens | Total de tokens de entrada contabilizados |
completion_tokens | Tokens gerados na saída; não são reduzidos pelo cache de entrada |
{ "usage": { "prompt_tokens": 10000, "prompt_cache_hit_tokens": 8000, "prompt_cache_miss_tokens": 2000, "completion_tokens": 500, "total_tokens": 10500 } }Uma métrica simples para acompanhar é:
taxa_de_hit = prompt_cache_hit_tokens / prompt_tokens Exemplo: 8.000 / 10.000 = 0,80 = 80%Meça por template, versão, rota e caso de uso. Uma média global pode esconder que apenas um fluxo específico está aproveitando o cache. Para aprofundar a leitura de usage, consulte o guia de tokens e custos da DeepSeek API.
Quanto o cache pode economizar hoje?
O ganho depende do modelo, do período de cobrança, da proporção repetida e da taxa real de hit. Valores em dólares por 1 milhão de tokens, reconferidos em 23/08/2026:
| Modelo e período | Entrada com hit | Entrada com miss | Saída |
|---|---|---|---|
| Flash — fora de pico | US$ 0,007 | US$ 0,22 | US$ 0,66 |
| Flash — pico | US$ 0,014 | US$ 0,44 | US$ 1,32 |
| Pro — fora de pico | US$ 0,022 | US$ 0,66 | US$ 1,98 |
| Pro — pico | US$ 0,044 | US$ 1,32 | US$ 3,96 |
| Vision Exp — fora de pico | US$ 0,007 | US$ 0,22 | US$ 0,66 |
| Vision Exp — pico | US$ 0,014 | US$ 0,44 | US$ 1,32 |
Exemplo atual de custo de entrada com 800 mil tokens em hit e 200 mil em miss:
| Modelo | Fora de pico | Pico |
|---|---|---|
| Flash ou Vision Exp | US$ 0,04960 | US$ 0,09920 |
| Pro | US$ 0,14960 | US$ 0,29920 |
O cálculo não inclui saída. Confirme o período e a tabela oficial antes de fechar orçamento.
Vision Exp e Context Caching
A tabela oficial publica tarifas de cache hit e miss para deepseek-v4-flash-vision-exp; portanto, a fórmula de custo usa os campos de usage do mesmo modo. Imagens são convertidas em tokens de entrada e cobradas junto com o texto.
A documentação de Vision não promete que repetir uma imagem idêntica produzirá um hit específico. O cache continua best effort e depende de unidades de prefixo persistidas. Meça prompt_cache_hit_tokens e prompt_cache_miss_tokens em cada chamada. O teste de 29/07 desta página usou apenas texto com V4 Flash e não valida reaproveitamento de imagens.
Como organizar prompts para aumentar a chance de hit
1. Instruções fixas 2. Contexto ou documento repetido 3. Exemplos fixos 4. Dados variáveis 5. Pergunta final- Coloque instruções estáveis e documentos reutilizados no início.
- Mantenha a mesma ordem de mensagens e exemplos.
- Mova timestamp, UUID, nonce e metadados voláteis para o final.
- Não altere espaços, marcação ou cabeçalhos do prefixo sem necessidade.
- Versione o template; quando ele mudar, espere uma nova fase de aquecimento.
- Evite enviar contexto que não será usado apenas para perseguir cache hit.
- Compare custo e qualidade antes e depois com tráfego representativo.
Context Caching e Thinking Mode
O cache corresponde apenas ao prefixo da entrada; a resposta continua sendo gerada novamente. A documentação genérica do cache observa que a saída pode variar com parâmetros de amostragem. A regra específica e atual do Thinking Mode, porém, cria uma exceção essencial:
| Modo | temperature, top_p e penalidades | Controle recomendado |
|---|---|---|
| Non-Thinking | Podem influenciar a amostragem da nova saída | Use apenas quando o caso exigir variação controlada |
| Thinking | São aceitos por compatibilidade, mas não produzem efeito | thinking.type e reasoning_effort |
O Thinking Mode vem ativado por padrão. Para desativar, envie {"thinking":{"type":"disabled"}}. Para raciocínio, use enabled e escolha low, high ou max; o padrão é high, e medium e xhigh são mapeados para high. Não tente aumentar ou reduzir o raciocínio ajustando temperature. Veja o guia do DeepSeek Thinking Mode.
Isolamento com user_id
A API aceita user_id para isolamento de KVCache, segurança de conteúdo e agendamento entre usuários do seu produto. Isso é útil quando várias pessoas compartilham a mesma conta de API.
- Use um identificador opaco ou pseudônimo gerado pelo backend.
- Não envie nome, e-mail, telefone, CPF ou outro dado pessoal.
- O valor deve corresponder a
[a-zA-Z0-9\-_]+. - O tamanho máximo documentado é 512 caracteres.
- Várias API keys não separam o limite de concorrência, que continua sendo calculado por conta.
{ "model": "deepseek-v4-flash", "messages": [ {"role": "user", "content": "Resuma o documento."} ], "user_id": "usr_8f2c7a1d", "thinking": {"type": "disabled"} }Limites do Context Caching
- Melhor esforço: não existe garantia de cache hit.
- Aquecimento: a construção pode levar alguns segundos.
- Expiração: cache sem uso costuma ser removido em algumas horas ou dias.
- Correspondência: um texto parecido pode não corresponder a uma unidade persistida.
- Somente entrada: o recurso não reduz diretamente os tokens de saída.
- Não é armazenamento: não use o cache para preservar fatos, arquivos ou histórico permanente. A Files API armazena imagens para referência por
file_id; é um recurso separado e não garante cache hit.
Erros comuns e correções
| Problema | Causa provável | Correção |
|---|---|---|
| Taxa de hit baixa | O prefixo muda entre requisições | Fixe o bloco inicial e mova variáveis para o final |
| Timestamp logo no início | Os primeiros tokens nunca correspondem | Mova dados voláteis para depois do conteúdo estável |
| Esperar resposta idêntica | Confusão com cache de output | Implemente cache de resposta no seu backend |
| Contexto cruzado entre usuários | Ausência de isolamento fino | Use user_id opaco e valide sessões |
| Ajustar temperature em Thinking | Parâmetro ignorado nesse modo | Use toggle de Thinking e reasoning_effort |
| Usar aliases antigos | Código não migrado | Use IDs V4 explícitos |
Privacidade e dados sensíveis
O cache ser automático não autoriza o envio de dados desnecessários. Minimize ou redija dados pessoais, não envie segredos e explique aos usuários como seu aplicativo processa prompts. Não afirme “zero retention”, “sem logs” ou “não usado para treinamento” sem uma base contratual específica e verificável.
Context Caching também não substitui controles do seu lado: autenticação, autorização, criptografia, retenção de histórico, acesso interno e política de privacidade continuam sob responsabilidade do operador da aplicação.
Checklist para produção
- Use um ID V4 atual e modo Thinking explícito.
- Versione o system prompt e o template.
- Coloque conteúdo estável antes do conteúdo variável.
- Monitore hit, miss, saída, latência e custo.
- Use
user_idpseudônimo quando houver múltiplos usuários. - Planeje custo e latência mesmo quando ocorrer cache miss.
- Não use cache como banco de dados ou memória permanente.
- Revise preços e documentação antes de mudanças importantes.
Perguntas frequentes
Preciso ativar o Context Caching?
Não. Ele é ativado automaticamente na API hospedada da DeepSeek.
O cache guarda a resposta do modelo?
Não. Ele reaproveita prefixos de entrada; o modelo gera uma nova resposta.
Como sei se ocorreu cache hit?
Leia usage.prompt_cache_hit_tokens. Tokens sem hit aparecem em prompt_cache_miss_tokens.
Temperature altera a saída no Thinking Mode?
Não. No Thinking Mode atual, temperature, top_p, presence_penalty e frequency_penalty são ignorados.
O cache substitui RAG?
Não. RAG recupera conhecimento relevante; Context Caching reduz o reprocessamento de prefixos repetidos. Os dois podem ser usados juntos.
O cache é permanente?
Não. A documentação informa limpeza automática de entradas sem uso, normalmente depois de algumas horas a alguns dias.
Fontes oficiais consultadas
- DeepSeek Context Caching
- Thinking Mode e parâmetros não suportados
- Vision e tokens de imagem
- Models & Pricing
- Rate Limit & Isolation
Última verificação editorial: 23 de agosto de 2026. O teste funcional permanece datado de 29 de julho de 2026; cache, preços e parâmetros podem mudar.