DeepSeek Context Caching: como reduzir custos e latência na API

Verificado em 4 de maio de 2026.

DeepSeek Context Caching é um dos recursos mais importantes para quem usa a DeepSeek API com prompts longos, instruções fixas, documentos grandes ou conversas com histórico. Em aplicações reais, é comum enviar o mesmo bloco de contexto repetidas vezes: regras do sistema, políticas internas, exemplos few-shot, documentação de produto, contrato, relatório financeiro ou trechos de código.

Sem cache, cada chamada pode pagar e processar novamente boa parte desses tokens de entrada. Com o cache de contexto da DeepSeek, partes repetidas do início do prompt podem ser reutilizadas em chamadas posteriores, reduzindo o custo dos tokens de entrada que atingem o cache e podendo melhorar a latência em cenários com prefixos repetidos. A documentação oficial descreve esse mecanismo como uma tecnologia de cache em disco ativada por padrão para todos os usuários da DeepSeek API.

Este guia foca no uso via API, não no aplicativo DeepSeek nem na interface pública de chat. A ideia é mostrar como o cache funciona, como medir cache hit e cache miss, como estruturar prompts para melhorar o reaproveitamento e quais cuidados considerar antes de levar isso para produção.

---

---

TL;DR

• DeepSeek Context Caching é o cache de contexto da DeepSeek API para reutilizar partes repetidas do início do prompt.
• O recurso está habilitado por padrão para todos os usuários da API, sem exigir mudança de código para começar a se beneficiar.
• A economia vem dos tokens de entrada que geram cache hit, cobrados a um preço menor do que tokens com cache miss.
• Você pode monitorar o comportamento do cache pelos campos prompt_cache_hit_tokens e prompt_cache_miss_tokens na resposta da API.
• O cache ajuda mais quando há prompts longos, instruções fixas, documentos repetidos ou conversas multi-turn com prefixos estáveis.
• Não é memória, RAG nem cache de resposta: ele reaproveita prefixos de entrada, mas a saída continua sendo gerada pelo modelo.

O que é DeepSeek Context Caching?

DeepSeek Context Caching é o mecanismo da DeepSeek API que tenta reutilizar partes repetidas do começo da entrada enviada ao modelo. Em vez de tratar cada prompt longo como algo totalmente novo, a API pode buscar prefixos já persistidos no cache e contar esses tokens como cache hit.

A própria DeepSeek informa que o Context Caching em disco está habilitado por padrão para todos os usuários, permitindo benefício sem modificação obrigatória no código. Cada requisição pode acionar a construção de cache em disco; se requisições seguintes tiverem prefixos sobrepostos com requisições anteriores, a parte sobreposta pode ser recuperada do cache.

A distinção mais importante é esta: Context Caching não salva respostas prontas. Ele não é um cache de output. A resposta continua sendo gerada pelo modelo por inferência, e parâmetros como temperature ainda podem influenciar a variação da saída. O cache corresponde ao prefixo da entrada do usuário, não ao texto final produzido pelo modelo.

Na prática, pense nele como um acelerador e redutor de custo para partes estáveis do prompt. Se você envia sempre o mesmo conjunto de instruções e muda apenas a pergunta final, a parte fixa tem maior chance de virar tokens em cache.

---

Como o Context Caching funciona na prática

O conceito central é o prefixo. Em modelos de linguagem, o começo do prompt costuma conter instruções, contexto, exemplos e documentos. O DeepSeek Context Caching tenta aproveitar justamente essas partes iniciais quando elas se repetem entre chamadas.

Segundo a documentação, um cache hit exige que o prefixo correspondente já tenha sido persistido no cache em disco. Por causa do mecanismo de atenção usado pela DeepSeek, os prefixos em cache são tratados como unidades independentes e completas; uma chamada posterior só atinge o cache quando reutiliza completamente uma dessas unidades de prefixo.

A DeepSeek descreve três formas principais de persistência de prefixos:

• Persistência nos limites da requisição, como o fim da entrada do usuário e o fim da saída do modelo.
• Persistência por detecção de prefixo comum entre múltiplas requisições.
• Persistência em intervalos fixos de tokens para entradas ou saídas longas, evitando que textos muito extensos fiquem totalmente sem cache.

Um exemplo simples:

Prefixo estável:
Você é um assistente técnico especializado na documentação da Empresa X.
Siga estas regras:
1. Responda em português.
2. Cite limitações quando houver incerteza.
3. Use exemplos de API quando forem úteis.

Documentação fixa:
[bloco longo de documentação do produto]

Parte variável:
Pergunta do usuário: Como configurar autenticação via API key?

Se chamadas seguintes mantiverem o mesmo prefixo estável e mudarem apenas a pergunta final, a chance de cache hit aumenta. O ponto crítico é que a parte repetida precisa estar no início e precisa corresponder a uma unidade de prefixo persistida. Texto parecido no meio do prompt pode não gerar o benefício esperado.

A documentação oficial também mostra um caso de perguntas sobre um relatório financeiro longo. Nas primeiras requisições, o cache pode ainda não ser atingido; depois que o sistema detecta e persiste o prefixo comum, uma terceira requisição que reutiliza o mesmo bloco inicial pode atingir o cache.

---

Cache hit vs cache miss

Termo	Significado	Impacto no custo	Exemplo
cache hit	Tokens de entrada que correspondem a um prefixo já persistido no cache	Tendem a custar menos do que tokens sem cache, conforme a tabela oficial de preços	O mesmo bloco de documentação enviado no começo de várias chamadas
cache miss	Tokens de entrada que não encontraram correspondência no cache	São cobrados como input sem cache	Um prompt novo, uma pergunta única ou um prefixo que mudou
prompt_cache_hit_tokens	Quantidade de tokens do prompt que atingiram o cache	Ajuda a medir reaproveitamento real	12.000 tokens em cache
prompt_cache_miss_tokens	Quantidade de tokens do prompt que não atingiram o cache	Ajuda a identificar desperdício ou instabilidade do prompt	3.000 tokens sem cache

Na resposta da API, a DeepSeek adiciona os campos prompt_cache_hit_tokens e prompt_cache_miss_tokens dentro de usage. A referência oficial também informa que prompt_tokens é igual à soma de prompt_cache_hit_tokens e prompt_cache_miss_tokens.

Uma forma simples de acompanhar a eficiência é calcular:

cache_hit_rate = prompt_cache_hit_tokens / prompt_tokens

Exemplo:

prompt_tokens = 20.000
prompt_cache_hit_tokens = 15.000
prompt_cache_miss_tokens = 5.000

cache_hit_rate = 15.000 / 20.000 = 0,75

Nesse caso, 75% dos tokens de entrada atingiram o cache. Isso não significa que o custo total caiu 75%, porque ainda existem tokens sem cache, tokens de saída e possíveis tokens de raciocínio dependendo do modo usado. Mas é um bom indicador para comparar versões de prompt, templates e fluxos de produto.

---

Preços atuais e impacto no custo

Verificado em 4 de maio de 2026. A página oficial de preços da DeepSeek lista os modelos deepseek-v4-flash e deepseek-v4-pro, ambos com contexto de 1M tokens e saída máxima de 384K tokens. A mesma página informa preços separados para input com cache hit, input com cache miss e output.

Modelo	Input cache hit	Input cache miss	Output	Observações
deepseek-v4-flash	US$ 0,0028 / 1M tokens	US$ 0,14 / 1M tokens	US$ 0,28 / 1M tokens	Modelo mais econômico da linha V4
deepseek-v4-pro	US$ 0,003625 / 1M tokens	US$ 0,435 / 1M tokens	US$ 0,87 / 1M tokens	Preço exibido com desconto de 75% até 31/05/2026, segundo a página oficial

A página de preços também observa que o preço de input com cache hit foi reduzido para 1/10 do preço de lançamento a partir de 26 de abril de 2026, 12:15 UTC. Além disso, a DeepSeek recomenda verificar regularmente a página de preços porque os valores podem variar.

A fórmula prática para estimar o custo dos tokens de entrada é:

custo_input =
  hit_tokens  × preço_cache_hit
+ miss_tokens × preço_cache_miss

Como os preços oficiais são por 1 milhão de tokens, use:

custo_input =
  (hit_tokens / 1.000.000)  × preço_cache_hit_por_1M
+ (miss_tokens / 1.000.000) × preço_cache_miss_por_1M

Exemplo com deepseek-v4-flash:

prompt_cache_hit_tokens = 800.000
prompt_cache_miss_tokens = 200.000

custo_input =
  (800.000 / 1.000.000) × 0,0028
+ (200.000 / 1.000.000) × 0,14

custo_input =
  0,00224 + 0,028
= US$ 0,03024

Esse exemplo considera apenas input tokens. O custo final também inclui output tokens e, quando aplicável, outros detalhes de uso do modelo. Antes de usar esses valores em produção, revise a página oficial de Models & Pricing.

---

Exemplo prático com Python

A DeepSeek API oferece formato compatível com OpenAI e Anthropic. Na documentação de primeira chamada, a DeepSeek mostra o uso do OpenAI SDK com base_url="https://api.deepseek.com" e modelos como deepseek-v4-pro e deepseek-v4-flash.

O exemplo abaixo usa o OpenAI SDK para enviar uma chamada e imprimir os campos de uso relacionados ao Context Caching.

import os
from openai import OpenAI

# Nunca coloque sua API key diretamente no código.
# Defina a variável de ambiente antes de executar:
# export DEEPSEEK_API_KEY="sua_chave_aqui"

client = OpenAI(
    api_key=os.environ.get("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"
)

messages = [
    {
        "role": "system",
        "content": (
            "Você é um assistente técnico especializado em APIs. "
            "Responda em português do Brasil, com explicações curtas, "
            "exemplos práticos e limitações quando necessário."
        )
    },
    {
        "role": "user",
        "content": (
            "Documentação fixa do produto:\n"
            "[cole aqui um bloco estável de documentação, política ou exemplos]\n\n"
            "Pergunta variável: como eu devo monitorar cache hit e cache miss?"
        )
    }
]

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=messages,
    stream=False
)

usage = response.usage

prompt_tokens = getattr(usage, "prompt_tokens", 0) or 0
hit_tokens = getattr(usage, "prompt_cache_hit_tokens", 0) or 0
miss_tokens = getattr(usage, "prompt_cache_miss_tokens", 0) or 0
completion_tokens = getattr(usage, "completion_tokens", 0) or 0

cache_hit_rate = hit_tokens / prompt_tokens if prompt_tokens else 0

print("Resposta:")
print(response.choices[0].message.content)

print("\nUso:")
print(f"prompt_tokens: {prompt_tokens}")
print(f"prompt_cache_hit_tokens: {hit_tokens}")
print(f"prompt_cache_miss_tokens: {miss_tokens}")
print(f"completion_tokens: {completion_tokens}")
print(f"cache_hit_rate: {cache_hit_rate:.2%}")

Para testar o cache, rode chamadas com o mesmo bloco inicial e mude apenas a pergunta final. Em fluxos reais, registre esses campos em logs ou métricas para comparar templates, versões de prompt e tipos de requisição.

Observação importante: os nomes deepseek-chat e deepseek-reasoner ainda aparecem por compatibilidade, mas a documentação atual informa que eles serão descontinuados em 24 de julho de 2026 e, durante o período atual, apontam para modos do deepseek-v4-flash. Em novos projetos, prefira usar explicitamente deepseek-v4-flash ou deepseek-v4-pro.

---

Como estruturar prompts para melhorar cache hit

A melhor estratégia é separar claramente o que é fixo do que é variável. O cache de contexto depende de prefixos repetidos; portanto, mudanças no início do prompt podem transformar tokens que antes eram cache hit em cache miss.

Boas práticas:

1. Coloque instruções fixas primeiro Comece com regras estáveis: tom, idioma, formato de resposta, restrições e papel do assistente. Evite reescrever essas instruções a cada deploy sem necessidade.
2. Inclua documentos repetidos no começo Se você envia sempre a mesma política, documentação, contrato, manual ou base de exemplos, coloque esse bloco antes da pergunta variável.
3. Mantenha exemplos few-shot em ordem estável Em prompts com exemplos, não altere a ordem a cada chamada. Mesmo pequenas mudanças podem reduzir o reaproveitamento do prefixo.
4. Coloque a pergunta variável no final O padrão ideal é: Instruções fixas
+ contexto fixo
+ exemplos fixos
+ dados variáveis
+ pergunta final
5. Não coloque timestamps, UUIDs ou session IDs no início Dados como 2026-05-04T12:31:09Z, request_id, user_id, session_id ou metadados aleatórios no começo do prompt quebram a estabilidade do prefixo. Envie metadados variáveis no final ou fora do texto do prompt quando a arquitetura permitir.
6. Evite reformatar o prefixo sem necessidade Espaços, quebras de linha, títulos e ordem dos blocos podem afetar a correspondência. Defina um template estável.
7. Versione mudanças grandes no prompt Quando alterar o template, registre a versão: prompt_template_v3, prompt_template_v4. Assim fica mais fácil comparar custo, qualidade e taxa de cache hit.
8. Monitore depois de cada alteração Não assuma que o cache melhorou. Calcule cache_hit_rate, custo por requisição e latência média antes e depois.

---

Casos de uso ideais

O DeepSeek Context Caching tende a ser mais útil quando a aplicação envia muito texto repetido no começo das requisições.

Chatbots multi-turn

Conversas com histórico podem reutilizar prefixos anteriores, especialmente quando novas mensagens são acrescentadas ao final. A documentação da DeepSeek mostra um exemplo em que uma segunda requisição reutiliza o prefixo da primeira em uma conversa multi-turn.

Análise de documentos longos

Relatórios financeiros, contratos, políticas internas, documentos jurídicos e manuais técnicos costumam ser consultados com várias perguntas diferentes. Se o documento permanece igual e apenas a pergunta muda, o cache pode ser valioso.

Análise de código e repositórios

Ferramentas de engenharia podem enviar instruções fixas, árvore de arquivos, padrões de arquitetura ou trechos relevantes do repositório. Quando o prefixo se repete, o cache pode reduzir o custo dos tokens de entrada.

Agentes com instruções fixas

Agentes de atendimento, vendas, suporte, QA ou operações costumam ter regras longas: permissões, políticas, estilo de resposta, ferramentas disponíveis e critérios de escalonamento. Esses blocos devem ficar no início e permanecer estáveis.

Few-shot prompting

Se o prompt usa muitos exemplos antes da pergunta, mantenha esses exemplos fixos. Isso é especialmente útil quando a aplicação precisa de consistência de formato, classificação ou extração.

RAG com blocos fixos ou documentação repetida

Em RAG, o contexto recuperado pode mudar a cada consulta. Ainda assim, partes fixas — instruções, schema de resposta, políticas e documentação comum — podem se beneficiar do cache.

Atendimento ao cliente com políticas fixas

Produtos SaaS, fintechs, edtechs e plataformas B2B muitas vezes repetem termos de uso, regras de reembolso, SLAs ou documentação de produto. Esses blocos são bons candidatos a prefixos estáveis.

---

Quando Context Caching não ajuda muito

Context Caching não é uma solução mágica para todo tipo de chamada.

Ele tende a ajudar menos quando:

• O prompt é curto.
• Cada requisição é completamente diferente.
• A parte inicial do prompt muda sempre.
• O texto repetido aparece apenas no meio ou no fim do prompt.
• A maior parte do custo vem de output tokens, não de input tokens.
• O sistema ainda não persistiu o prefixo comum.
• O fluxo tem baixa repetição entre usuários ou sessões.

Também é importante lembrar que o cache funciona em base best-effort. A DeepSeek afirma que o sistema não garante 100% de cache hit e que a construção do cache pode levar segundos. Quando o cache deixa de ser usado, ele pode ser limpo automaticamente, geralmente em algumas horas a alguns dias.

Por isso, a estratégia correta não é “ativar e esquecer”. A estratégia correta é medir.

---

Context Caching não é memória, RAG nem cache de resposta

Recurso	O que faz	O que não faz	Quem gerencia
Context Caching	Reutiliza prefixos de entrada repetidos na DeepSeek API	Não salva automaticamente fatos sobre o usuário nem retorna respostas prontas	DeepSeek API, com monitoramento pelo desenvolvedor
Memória de conversa	Guarda informações ou preferências entre interações	Não reduz necessariamente o custo de tokens de entrada	Aplicação, banco de dados ou camada de memória
RAG	Recupera documentos relevantes de uma base externa	Não garante cache hit se o contexto muda a cada consulta	Aplicação, vector database e pipeline de recuperação
Cache de resposta no backend	Salva uma resposta pronta para uma mesma pergunta ou chave	Não executa nova inferência nem adapta a resposta	Backend da aplicação

Essa distinção evita decisões ruins de arquitetura.

Se você precisa que o sistema lembre preferências do usuário, use uma camada de memória. Se precisa buscar documentos atualizados, use RAG. Se a mesma pergunta deve retornar exatamente a mesma resposta sem nova chamada ao modelo, use cache de resposta no seu backend. Se o problema é repetir um prompt longo na DeepSeek API, use Context Caching como parte da otimização.

---

Limitações, segurança e privacidade

O cache de contexto da DeepSeek é útil, mas tem limites claros.

Primeiro, ele é best-effort. A documentação oficial diz que o sistema não garante 100% de cache hit. Isso significa que sua aplicação deve continuar funcionando corretamente mesmo quando uma chamada tiver cache miss.

Segundo, o cache não dura para sempre. A DeepSeek informa que, quando o cache não está mais em uso, ele é limpo automaticamente, geralmente em algumas horas a alguns dias. Portanto, não trate o Context Caching como armazenamento persistente de longo prazo.

Terceiro, ele não remove a necessidade de governança de dados. Se você envia dados sensíveis para uma API externa, aplique as mesmas políticas de segurança, privacidade, retenção, anonimização e controle de acesso que usaria em qualquer integração com IA. Evite enviar segredos, credenciais, dados pessoais desnecessários ou informações contratuais sem base legal e sem revisão de segurança.

Quarto, o cache não elimina variação na saída. A própria DeepSeek esclarece que a saída ainda é gerada por computação e inferência, podendo ser influenciada por parâmetros como temperatura.

---

Erros comuns e como corrigir

Erro	Causa provável	Como corrigir
Baixo cache_hit_rate mesmo com prompts longos	O início do prompt muda a cada chamada	Separe prefixo fixo e parte variável; mova metadados dinâmicos para o final
Inserir timestamp no começo	Cada chamada começa com texto diferente	Remova timestamps do prefixo ou coloque depois do bloco cacheável
Esperar cache hit de texto no meio do prompt	O mecanismo depende de prefixos persistidos	Coloque blocos repetidos no início
Confundir cache com memória	O cache não salva preferências nem fatos de usuário	Use banco de dados, perfil do usuário ou camada de memória
Ignorar output tokens	Context Caching afeta principalmente input tokens	Monitore custo total, incluindo completion_tokens
Não registrar campos de uso	Sem logs, não há como provar economia	Salve prompt_cache_hit_tokens, prompt_cache_miss_tokens e prompt_tokens
Trocar ordem de exemplos few-shot	O prefixo deixa de ser idêntico	Congele a ordem dos exemplos no template
Usar aliases antigos em novo projeto	deepseek-chat e deepseek-reasoner estão em rota de descontinuação	Use deepseek-v4-flash ou deepseek-v4-pro diretamente
Esperar 100% de hit	O cache é best-effort	Trabalhe com médias e fallback de custo
Reescrever o template a cada release	Mudanças quebram comparabilidade	Versione templates e compare métricas por versão

---

Checklist rápido para produção

Antes de depender do DeepSeek Context Caching em produção, valide:

• Registrar prompt_tokens.
• Registrar prompt_cache_hit_tokens.
• Registrar prompt_cache_miss_tokens.
• Calcular cache_hit_rate.
• Monitorar custo por requisição.
• Monitorar latência por tipo de prompt.
• Separar prefixo estável e parte variável.
• Manter instruções fixas no início.
• Evitar timestamp, UUID, session_id e metadados voláteis no começo.
• Testar templates estáveis com volume realista.
• Controlar max_tokens e tamanho de saída.
• Revisar preços oficiais antes de estimar orçamento.
• Validar políticas de segurança e privacidade.
• Documentar versão do prompt.
• Comparar custo antes e depois de mudanças no template.

---

Conclusão

DeepSeek Context Caching é uma otimização prática para aplicações que repetem grandes blocos de contexto na DeepSeek API. Ele funciona melhor quando o prompt tem um prefixo estável: instruções fixas, documentação repetida, exemplos few-shot, histórico de conversa ou documentos longos usados em várias perguntas.

O ponto principal é simples: não tente adivinhar a economia. Meça. Registre prompt_cache_hit_tokens, prompt_cache_miss_tokens, prompt_tokens, custo por chamada e latência. Depois, ajuste seus templates para manter a parte fixa no início e empurrar a parte variável para o final.

Comece registrando os campos de uso da API e estabilizando seus prompts mais repetidos. Em muitos fluxos com input longo, essa é uma das formas mais diretas de reduzir custo da API DeepSeek sem mudar a experiência final do usuário.

---

FAQ