DeepSeek Token Usage: guia completo para medir tokens, custos e cache na API

DeepSeek Token Usage é o conjunto de métricas que mostra quantos tokens uma chamada à API da DeepSeek consumiu no prompt, na resposta, no cache e, quando aplicável, no raciocínio do modelo. Isso importa porque tokens são a base de cobrança, controle de custo, limite de contexto, observabilidade e otimização de performance. Em produtos SaaS, chatbots, agentes e pipelines RAG, entender prompt_tokens, completion_tokens, total_tokens, prompt_cache_hit_tokens, prompt_cache_miss_tokens e reasoning_tokens evita surpresas na fatura e ajuda a escalar a aplicação com previsibilidade.

A DeepSeek define tokens como unidades básicas usadas pelos modelos para representar texto e também como unidades de cobrança. A documentação oficial recomenda usar o número real retornado em usage, porque estimativas por caractere, palavra ou idioma podem variar conforme a tokenização do modelo.

Resumo executivo

Para monitorar DeepSeek API Token Usage corretamente, você não deve contar apenas palavras, caracteres ou o tamanho bruto do prompt. O ponto confiável é o objeto usage retornado pela API.

Em uma resposta normal, os campos mais importantes são:

• prompt_tokens: tokens de entrada.
• completion_tokens: tokens gerados na resposta.
• total_tokens: soma de prompt e completion.
• prompt_cache_hit_tokens: tokens de entrada servidos pelo cache.
• prompt_cache_miss_tokens: tokens de entrada não servidos pelo cache.
• completion_tokens_details.reasoning_tokens: tokens usados no raciocínio, quando esse detalhe estiver presente.

A fórmula operacional mais útil é:

prompt_tokens = prompt_cache_hit_tokens + prompt_cache_miss_tokens

quando os campos de cache estiverem disponíveis. Para custo, trate cache hit, cache miss e output separadamente, porque eles podem ter preços diferentes.

O que é DeepSeek Token Usage?

DeepSeek Token Usage é a leitura das estatísticas de consumo de tokens retornadas pela API da DeepSeek após uma requisição. Essas estatísticas mostram quanto do texto enviado foi processado como entrada, quanto texto foi gerado como saída, quanto foi reaproveitado via cache e, em modos de raciocínio, quantos tokens foram usados no processo de reasoning.

Na prática, esse dado responde perguntas como:

• Quanto esta resposta custou?
• Qual cliente, usuário ou feature está consumindo mais tokens?
• O prompt está grande demais?
• O histórico da conversa está ficando caro?
• O cache está funcionando?
• O Thinking Mode está consumindo muitos tokens?
• O limite de contexto está próximo de ser atingido?

Para um protótipo pequeno, olhar apenas a resposta do modelo pode ser suficiente. Para um produto real, especialmente SaaS, chatbot de atendimento, copiloto de código ou RAG corporativo, usage deve entrar em logs, métricas, dashboards e alertas.

A API de Chat Completions da DeepSeek retorna estatísticas de uso no campo usage, incluindo prompt_tokens, completion_tokens, total_tokens, campos de cache e detalhes de tokens de reasoning quando aplicáveis.

O que é um token na DeepSeek API?

Um token é uma unidade de texto usada pelo modelo. Ele pode representar uma palavra, parte de uma palavra, um número, um símbolo ou pontuação. Em português, por exemplo, uma frase curta pode ser dividida em vários tokens, mas a proporção exata não é fixa.

A DeepSeek informa que tokens são as unidades básicas que os modelos usam para representar linguagem natural e também a base de cobrança. A documentação dá proporções aproximadas para caracteres em inglês e chinês, mas reforça que a contagem real deve ser baseada no retorno do modelo em usage.

Isso significa que não é seguro criar billing interno usando apenas uma regra como “1 token = 1 palavra”. Essa aproximação pode funcionar para estimativas rápidas, mas não para cobrança, rate limiting ou auditoria de custo.

Token, palavra, caractere, context length e max_tokens

Um erro comum é misturar conceitos diferentes. Eles se relacionam, mas não são iguais.

Conceito	O que significa	Como usar na prática
Token	Unidade processada pelo modelo	Base para custo e limites
Palavra	Unidade linguística humana	Útil para estimativa editorial, não para billing
Caractere	Letra, número, espaço ou símbolo	Estimativa grosseira de tamanho
Context length	Janela máxima de tokens que o modelo consegue considerar	Limite combinado de entrada e saída
max_tokens	Número máximo de tokens que a resposta pode gerar	Controle de custo e tamanho da saída
total_tokens	Soma de tokens de entrada e saída	Métrica geral de consumo da requisição

A documentação atual da DeepSeek informa que os modelos deepseek-v4-flash e deepseek-v4-pro usam contexto de 1M e saída máxima de 384K, além de suporte a modos com e sem thinking. Esses detalhes podem mudar e devem ser validados antes de produção.

O ponto importante: context length não é a mesma coisa que max_tokens. A janela de contexto define o limite total que envolve prompt, histórico, documentos, tool messages e resposta. Já max_tokens limita apenas a geração da resposta. Se você enviar um prompt enorme e ainda pedir uma resposta longa, a soma pode bater no limite do modelo.

Como ler o objeto usage da resposta da API

Depois de chamar /chat/completions, a API retorna um objeto com a resposta do modelo e, em chamadas não streaming, normalmente inclui usage no corpo final.

Um formato conceitual seria:

{
  "model": "deepseek-v4-pro",
  "usage": {
    "prompt_tokens": 12000,
    "completion_tokens": 850,
    "total_tokens": 12850,
    "prompt_cache_hit_tokens": 9000,
    "prompt_cache_miss_tokens": 3000,
    "completion_tokens_details": {
      "reasoning_tokens": 420
    }
  }
}

Esse objeto deve ser interpretado assim:

• O prompt completo consumiu 12000 tokens.
• Destes, 9000 vieram de cache hit.
• Outros 3000 foram cache miss.
• A resposta gerada consumiu 850 tokens.
• O total da requisição foi 12850.
• Dentro da geração, 420 tokens foram de reasoning.

A própria referência da API informa que prompt_tokens é igual a prompt_cache_hit_tokens + prompt_cache_miss_tokens, quando esses campos estão presentes.

Tabela dos principais campos de token usage

Campo	Significado	Por que importa
prompt_tokens	Número de tokens no prompt	Mede entrada total enviada ao modelo
completion_tokens	Número de tokens gerados na resposta	Afeta custo de output e tamanho da resposta
total_tokens	Soma de entrada e saída	Visão geral do consumo
prompt_cache_hit_tokens	Tokens do prompt que bateram no cache	Normalmente reduzem custo e latência
prompt_cache_miss_tokens	Tokens do prompt que não bateram no cache	Entrada processada sem reaproveitamento
completion_tokens_details.reasoning_tokens	Tokens gerados para raciocínio	Ajuda a monitorar Thinking Mode
stream_options.include_usage	Opção para receber usage em streaming	Permite medir consumo em respostas SSE

A referência de Chat Completion descreve completion_tokens, prompt_tokens, prompt_cache_hit_tokens, prompt_cache_miss_tokens, total_tokens e completion_tokens_details.reasoning_tokens dentro de usage.

Exemplo em Python para extrair usage metrics com segurança

O exemplo abaixo usa o SDK compatível com OpenAI apontando para a base URL da DeepSeek. A própria documentação da DeepSeek mostra compatibilidade com formato OpenAI e uso de base_url="https://api.deepseek.com".

import os
from typing import Any, Dict

from openai import OpenAI

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


def read_field(obj: Any, key: str, default: Any = 0) -> Any:
    """Lê campo de objeto ou dict sem quebrar quando a estrutura muda."""
    if obj is None:
        return default
    if isinstance(obj, dict):
        return obj.get(key, default)
    return getattr(obj, key, default)


def extract_deepseek_usage(response: Any) -> Dict[str, int]:
    usage = read_field(response, "usage", {}) or {}
    details = read_field(usage, "completion_tokens_details", {}) or {}

    prompt_tokens = int(read_field(usage, "prompt_tokens", 0) or 0)
    completion_tokens = int(read_field(usage, "completion_tokens", 0) or 0)
    total_tokens = int(read_field(usage, "total_tokens", 0) or 0)

    cache_hit = int(read_field(usage, "prompt_cache_hit_tokens", 0) or 0)
    cache_miss = int(read_field(usage, "prompt_cache_miss_tokens", 0) or 0)

    reasoning_tokens = int(read_field(details, "reasoning_tokens", 0) or 0)

    cache_sum = cache_hit + cache_miss
    cache_fields_available = cache_sum > 0

    return {
        "prompt_tokens": prompt_tokens,
        "completion_tokens": completion_tokens,
        "total_tokens": total_tokens,
        "prompt_cache_hit_tokens": cache_hit,
        "prompt_cache_miss_tokens": cache_miss,
        "reasoning_tokens": reasoning_tokens,
        "cache_fields_available": int(cache_fields_available),
        "cache_sum_matches_prompt": int(
            not cache_fields_available or cache_sum == prompt_tokens
        ),
    }


response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "Você é um assistente técnico objetivo."},
        {"role": "user", "content": "Explique como monitorar token usage na API."},
    ],
    stream=False,
    extra_body={"thinking": {"type": "disabled"}},
)

metrics = extract_deepseek_usage(response)
print(metrics)

Esse padrão é melhor do que acessar campos diretamente sem validação, porque APIs evoluem. Em produção, salve essas métricas com request_id, user_id, customer_id, nome do modelo, endpoint, feature e timestamp.

Exemplo em Node.js/TypeScript para monitorar DeepSeek API Token Usage

import OpenAI from "openai";

type DeepSeekUsage = {
  prompt_tokens?: number;
  completion_tokens?: number;
  total_tokens?: number;
  prompt_cache_hit_tokens?: number;
  prompt_cache_miss_tokens?: number;
  completion_tokens_details?: {
    reasoning_tokens?: number;
  };
};

const client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com",
});

function extractUsage(completion: any) {
  const usage: DeepSeekUsage = completion.usage ?? {};
  const details = usage.completion_tokens_details ?? {};

  const promptTokens = usage.prompt_tokens ?? 0;
  const completionTokens = usage.completion_tokens ?? 0;
  const totalTokens = usage.total_tokens ?? 0;

  const cacheHit = usage.prompt_cache_hit_tokens ?? 0;
  const cacheMiss = usage.prompt_cache_miss_tokens ?? 0;
  const reasoningTokens = details.reasoning_tokens ?? 0;

  return {
    prompt_tokens: promptTokens,
    completion_tokens: completionTokens,
    total_tokens: totalTokens,
    prompt_cache_hit_tokens: cacheHit,
    prompt_cache_miss_tokens: cacheMiss,
    reasoning_tokens: reasoningTokens,
    cache_sum_matches_prompt:
      cacheHit + cacheMiss === 0 || cacheHit + cacheMiss === promptTokens,
  };
}

async function main() {
  const completion = await client.chat.completions.create({
    model: "deepseek-v4-flash",
    messages: [
      {
        role: "system",
        content: "Você é um assistente técnico para documentação de APIs.",
      },
      {
        role: "user",
        content: "Liste boas práticas para reduzir uso de tokens em um chatbot.",
      },
    ],
    stream: false,
    thinking: { type: "disabled" },
  } as any);

  const usage = extractUsage(completion);

  console.log("Resposta:", completion.choices[0]?.message?.content);
  console.log("Usage:", usage);
}

main().catch(console.error);

Em TypeScript, o as any pode ser necessário quando o SDK ainda não tipa parâmetros específicos da DeepSeek, como thinking. Para aplicações maiores, crie um wrapper próprio para padronizar modelo, modo, custo e logs.

Como medir token usage em streaming

Quando stream: true, a resposta chega em chunks via SSE. Nesse caso, você precisa pedir explicitamente o usage final usando:

{
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}

A documentação informa que, com stream_options.include_usage, um chunk adicional é enviado antes de data: [DONE]; esse chunk contém usage para a requisição inteira, enquanto outros chunks podem trazer usage nulo.

Exemplo em Node.js/TypeScript:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com",
});

async function streamWithUsage() {
  const stream = await client.chat.completions.create({
    model: "deepseek-v4-flash",
    messages: [
      { role: "user", content: "Crie um resumo técnico sobre context caching." },
    ],
    stream: true,
    stream_options: { include_usage: true },
    thinking: { type: "disabled" },
  } as any);

  let finalText = "";
  let finalUsage: any = null;

  for await (const chunk of stream) {
    const delta = chunk.choices?.[0]?.delta?.content;
    if (delta) {
      finalText += delta;
    }

    if ((chunk as any).usage) {
      finalUsage = (chunk as any).usage;
    }
  }

  console.log("Texto final:", finalText);
  console.log("Usage final:", finalUsage);
}

streamWithUsage().catch(console.error);

Essa abordagem é essencial para interfaces em tempo real. Sem o usage final, você pode até exibir a resposta ao usuário, mas perde a medição correta de custo.

Como calcular o custo da DeepSeek API por request

A maneira mais robusta de calcular custo é separar três componentes:

1. Entrada com cache hit.
2. Entrada com cache miss.
3. Saída gerada pelo modelo.

Use esta fórmula:

custo =
(prompt_cache_hit_tokens / 1_000_000) * preço_input_cache_hit
+
(prompt_cache_miss_tokens / 1_000_000) * preço_input_cache_miss
+
(completion_tokens / 1_000_000) * preço_output

Essa separação importa porque a página de pricing da DeepSeek lista preços por 1 milhão de tokens e diferencia input com cache hit, input com cache miss e output. A mesma página informa que os preços podem variar e recomenda verificar a página de pricing regularmente.

Exemplo numérico

Suponha uma chamada com:

prompt_cache_hit_tokens = 90_000
prompt_cache_miss_tokens = 10_000
completion_tokens = 4_000

E suponha, apenas para exemplo, estes preços por 1M tokens:

preço_input_cache_hit = 0.0028
preço_input_cache_miss = 0.14
preço_output = 0.28

O cálculo fica:

custo =
(90_000 / 1_000_000) * 0.0028
+
(10_000 / 1_000_000) * 0.14
+
(4_000 / 1_000_000) * 0.28

custo =
0.000252
+
0.0014
+
0.00112

custo = 0.002772

Nesse exemplo, a request custaria aproximadamente US$ 0,002772, considerando os preços usados no cálculo. Antes de usar em produção, atualize os valores com a página oficial da DeepSeek, porque modelos, descontos e preços podem mudar.

Função de custo em Python

def calculate_deepseek_cost(
    usage: dict,
    price_input_cache_hit: float,
    price_input_cache_miss: float,
    price_output: float,
) -> float:
    cache_hit = usage.get("prompt_cache_hit_tokens", 0) or 0
    cache_miss = usage.get("prompt_cache_miss_tokens", 0) or 0
    completion = usage.get("completion_tokens", 0) or 0

    return (
        (cache_hit / 1_000_000) * price_input_cache_hit
        + (cache_miss / 1_000_000) * price_input_cache_miss
        + (completion / 1_000_000) * price_output
    )

Evite calcular custo usando apenas total_tokens, porque isso ignora a diferença entre cache hit, cache miss e output.

Cache hit vs cache miss no context caching

O context caching da DeepSeek é um mecanismo que reaproveita prefixos de contexto entre requisições. Segundo a documentação, o Context Caching on Disk é habilitado por padrão para todos os usuários, sem necessidade de alterar o código. Quando requisições posteriores têm prefixos sobrepostos com requisições anteriores, a parte sobreposta pode ser buscada no cache e contada como cache hit.

O que é cache hit?

Cache hit ocorre quando uma parte inicial do prompt coincide com um prefixo que já foi persistido no cache. Isso é comum em casos como:

• Prompts de sistema repetidos.
• Conversas multi-turn.
• Análise de documentos longos com perguntas diferentes.
• RAG que envia o mesmo bloco de contexto em múltiplas chamadas.
• Agentes que mantêm instruções fixas e ferramentas recorrentes.

O que é cache miss?

Cache miss ocorre quando os tokens de entrada não são encontrados no cache. Isso pode acontecer porque:

• A requisição é a primeira daquele contexto.
• O prefixo mudou.
• O conteúdo comum ainda não foi persistido.
• O cache foi limpo.
• A estrutura do prompt foi reorganizada.
• O trecho repetido não aparece como prefixo compatível.

A DeepSeek informa que os campos prompt_cache_hit_tokens e prompt_cache_miss_tokens existem justamente para refletir o status de cache da request.

Por que a prefixação importa?

O cache trabalha principalmente com prefixos. Em termos práticos, isso significa que você deve colocar conteúdo estável no começo do prompt:

1. System prompt fixo.
2. Regras permanentes.
3. Contexto reutilizável.
4. Documentos longos recorrentes.
5. Instruções específicas da tarefa por último.

Em vez de montar o prompt assim:

Pergunta nova do usuário
Regras fixas
Documento longo

prefira:

Regras fixas
Documento longo
Pergunta nova do usuário

Essa organização aumenta a chance de reaproveitamento de prefixos.

Por que o cache não garante 100% de hit rate?

A documentação da DeepSeek afirma que o cache funciona em regime de “best effort” e não garante taxa de hit de 100%. Também informa que a construção do cache pode levar segundos e que caches sem uso são limpos automaticamente após algum tempo.

Por isso, não trate cache hit como garantia contratual para custo. Trate como otimização. Seu sistema de billing deve funcionar mesmo quando todo o prompt vira cache miss.

Thinking Mode e reasoning_tokens

Os modelos atuais da DeepSeek podem operar com Thinking Mode habilitado ou desabilitado, e a referência de Chat Completion mostra o parâmetro thinking com type: enabled ou disabled. A documentação também descreve reasoning_effort, com valores como high e max.

Quando o modelo usa raciocínio, parte da geração pode aparecer como reasoning_tokens dentro de completion_tokens_details. Esses tokens não são necessariamente texto final visível para o usuário, mas indicam esforço interno de raciocínio.

Monitore reasoning_tokens principalmente quando:

• Você usa agentes autônomos.
• O produto faz análise complexa.
• Há prompts longos com múltiplas restrições.
• O usuário pode pedir respostas muito detalhadas.
• Você usa reasoning_effort alto.
• O custo por request precisa ser previsível.

Uma regra prática: se a feature não precisa de raciocínio profundo, teste thinking: { "type": "disabled" }. Se a qualidade cair muito, reative Thinking Mode apenas nas rotas onde ele realmente agrega valor.

Como reduzir token usage sem perder qualidade

Reduzir uso de tokens não significa apenas “encurtar tudo”. Significa enviar ao modelo o contexto certo, na ordem certa, com o nível certo de detalhe.

1. Encurte o system prompt

System prompts crescem com o tempo. Times adicionam regras, exceções, estilo, políticas internas e exemplos. Depois de algumas semanas, o prompt vira um documento inchado.

Revise periodicamente:

• Quais instruções são realmente usadas?
• Há regras duplicadas?
• O mesmo conceito aparece em palavras diferentes?
• Exemplos antigos ainda ajudam?
• O prompt precisa ser igual para todas as features?

Um system prompt menor reduz prompt_tokens em todas as chamadas.

2. Resuma o histórico da conversa

Em chatbots multi-turn, reenviar toda a conversa é caro. Depois de certo ponto, use resumo de estado:

Resumo da conversa até agora:
- O usuário quer integrar DeepSeek em um SaaS.
- Já escolheu deepseek-v4-flash para respostas rápidas.
- Precisa monitorar custo por customer_id.

Mantenha as últimas mensagens brutas e substitua mensagens antigas por um resumo fiel.

3. Otimize RAG e envie apenas trechos necessários

Em RAG, o erro clássico é enviar documentos demais. Em vez de mandar 20 chunks, envie os 3 a 6 mais relevantes, com metadados mínimos e instrução clara.

Também vale deduplicar trechos parecidos e limitar tamanho por fonte. Se o usuário pergunta sobre política de reembolso, não envie todo o contrato.

4. Use max_tokens com inteligência

max_tokens é uma trava de saída. Se a feature precisa apenas de uma classificação, não deixe a resposta gerar milhares de tokens.

Exemplos:

• Classificação: max_tokens baixo.
• Resumo curto: limite moderado.
• Relatório detalhado: limite maior.
• Agente de código: limite ajustado ao fluxo.

A referência da DeepSeek descreve max_tokens como o número máximo de tokens que podem ser gerados na chat completion, e lembra que entrada mais geração ficam limitadas pelo context length do modelo.

5. Fixe prefixos recorrentes para melhorar cache

Como o context caching depende de prefixos compatíveis, não reordene blocos fixos sem necessidade. Mantenha uma estrutura estável:

[system prompt fixo]
[política fixa]
[documento recorrente]
[histórico resumido]
[pergunta atual]

Pequenas mudanças no começo do prompt podem reduzir cache hit.

6. Separe custo por feature, usuário e customer

Não basta saber o custo total da API. Registre:

• model
• feature
• user_id
• customer_id
• prompt_tokens
• completion_tokens
• prompt_cache_hit_tokens
• prompt_cache_miss_tokens
• reasoning_tokens
• custo estimado
• latência
• status da request

Assim, você consegue identificar clientes caros, features mal otimizadas e prompts que precisam ser revistos.

7. Monitore p95 e p99 de tokens

Médias escondem problemas. Uma feature pode ter média de 2.000 tokens, mas p99 de 120.000 tokens. Isso significa que uma pequena parcela das chamadas pode estar gerando custo desproporcional.

Acompanhe:

• p50, p95 e p99 de prompt_tokens.
• p50, p95 e p99 de completion_tokens.
• p95 de reasoning_tokens.
• cache hit ratio por feature.
• custo por 1.000 requests.
• custo por customer.

Erros comuns ao interpretar DeepSeek Token Usage

1. Achar que token é igual a palavra

Token pode ser palavra, parte de palavra, número, símbolo ou pontuação. Use estimativas apenas para planejamento, não para faturamento.

2. Ignorar output tokens

Muitos times otimizam o prompt e esquecem que respostas longas também custam. completion_tokens deve ser monitorado com o mesmo cuidado.

3. Calcular custo usando apenas total_tokens

total_tokens é útil, mas não captura preços diferentes para cache hit, cache miss e output. Para custo realista, separe os componentes.

4. Ignorar reasoning_tokens

Em Thinking Mode, raciocínio pode aumentar consumo. Se você não registra reasoning_tokens, pode não entender por que algumas chamadas ficam mais caras.

5. Usar preços antigos

Preços, descontos e modelos podem mudar. A página oficial de pricing da DeepSeek informa que produtos e preços podem variar, e recomenda verificação regular da página.

6. Confundir context length com max_tokens

Context length é a janela total. max_tokens é o limite de geração. Uma chamada pode falhar ou ser truncada se a soma de entrada e saída exceder o limite aplicável.

7. Não registrar usage nos logs

Sem usage, você não consegue auditar custo, criar alertas, comparar modelos ou provar consumo por cliente.

8. Colocar API key no frontend

Nunca exponha DEEPSEEK_API_KEY no navegador. Faça chamadas pelo backend, aplique autenticação, rate limit e controle por usuário.

Checklist prático para produção

Antes de lançar DeepSeek em produção, valide esta lista:

• O backend registra usage em todas as chamadas.
• Chamadas streaming usam stream_options.include_usage.
• O custo é calculado separando cache hit, cache miss e output.
• O sistema registra model, feature, user_id e customer_id.
• Há alertas para p95/p99 de tokens.
• Há limite por usuário, cliente ou plano.
• O histórico de conversa é resumido.
• RAG envia apenas chunks relevantes.
• max_tokens é definido por feature.
• System prompts são revisados periodicamente.
• API keys ficam apenas no backend.
• Preços são atualizados a partir da documentação oficial.
• Thinking Mode é usado apenas onde melhora o resultado.
• Dashboards mostram cache hit ratio.
• Erros e requests interrompidas também são monitorados.

FAQ sobre DeepSeek Token Usage