Tokens de entrada em cache são baratos: na BroadNet Inference, o DeepSeek V4.1 Flash cobra $0.0055 por 1M em vez de $0.175. O explicador de tokens em cache cobre o preço e como ler o campo usage. Este post é sobre o trabalho de projeto: como organizar um prompt para o cache realmente acertar, e como provar que acerta.
Por que a ordem do prompt decide a taxa de acerto do cache?
Todos os grandes provedores fazem cache por prefixo. O guia da OpenAI diz que o reaproveitamento exige que todo o prefixo renderizado coincida. A documentação da DeepSeek descreve a mesma regra: uma requisição só acerta se corresponder totalmente a um prefixo armazenado, e uma que diverge no meio do caminho não acerta. A Anthropic monta o cache na ordem ferramentas, system, mensagens.
Por baixo dos panos, o servidor reaproveita o KV cache que montou para aquele prefixo. Então o cache é uma linha reta a partir do primeiro token. O primeiro byte diferente da chamada anterior encerra a parte reaproveitável. Um timestamp de uma linha no topo de um prompt de 50.000 tokens custa a você todos os 50.000 tokens pelo preço cheio.
Qual é a ordem certa das camadas?
| Camada | Muda | Exemplo | Regra |
|---|---|---|---|
| 1. Prompt de sistema | A cada deploy | Papel, regras, formato de saída | Sem datas, IDs, nomes de usuário |
| 2. Definições de ferramentas | A cada deploy | Schemas de funções | JSON ordenado e determinístico |
| 3. Material de referência | Por sessão ou tarefa | Arquivos do repositório, contratos, documentação de produto | Ordem fixa, rótulos estáveis |
| 4. Histórico da conversa | A cada turno, só com acréscimos | Turnos anteriores do usuário e do assistente | Nunca edite; só acrescente |
| 5. Mensagem nova | A cada chamada | A pergunta, mais a hora atual se precisar | Dados voláteis vão aqui |
A camada 5 é o lugar de tudo o que é volátil: a data atual, o idioma do usuário, um ID de requisição, trechos recuperados que mudam a cada pergunta.
O que quebra o prefixo sem você perceber?
- Ordem de dicionários. Frameworks costumam montar o array
toolsa partir de um dicionário ou registro. Se os plugins carregarem em outra ordem, os bytes mudam. - Formatação de JSON.
json.dumps(x)ejson.dumps(x, indent=2)são prefixos diferentes. Dois serializadores com ordens de chave diferentes também. - Espaços no template. Um espaço no fim da linha, ou um
\r\nvindo de um caminho do código e um\nde outro. - Listas dinâmicas de ferramentas. Remover as ferramentas que um usuário não pode usar muda o prefixo. O guia da OpenAI recomenda manter as definições estáveis e restringir o uso com
tool_choiceou uma configuração de ferramentas permitidas. - Resumir o histórico no lugar. Reescrever turnos antigos num resumo zera tudo o que vem depois do prompt de sistema. Resuma raramente e em passos grandes.
- Recuperação antes das instruções. Trechos de RAG colocados entre o prompt de sistema e as ferramentas mudam a cada consulta e quebram também a camada de ferramentas.
Como montar uma requisição amigável ao cache no código?
Faça cada camada depender só de entradas estáveis e serialize de forma determinística:
import json, os
from openai import OpenAI
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
SYSTEM = open("prompts/system.md").read() # versioned file, no templating
def stable_tools(registry: dict) -> list:
# Sort by name, sort keys inside each schema.
return [json.loads(json.dumps(registry[name], sort_keys=True)) for name in sorted(registry)]
def docs_block(paths: list[str]) -> str:
parts = [f"=== {p} ===\n{open(p).read()}" for p in sorted(paths)]
return "\n\n".join(parts)
def build_messages(history: list, user_text: str, now_iso: str, doc_paths: list[str]):
return (
[{"role": "system", "content": SYSTEM},
{"role": "user", "content": docs_block(doc_paths)}]
+ history # append-only
+ [{"role": "user", "content": f"(now: {now_iso})\n{user_text}"}]
)
resp = client.chat.completions.create(
model="broadnet/deepseek-v4.1-flash",
messages=build_messages(history, question, now_iso, files),
tools=stable_tools(TOOLS),
)
history += [{"role": "user", "content": question}, resp.choices[0].message.model_dump(exclude_none=True)]
Dois detalhes. A hora atual vai na última mensagem, não no prompt de sistema. E o histórico guarda a mensagem do assistente exatamente como ela voltou, para que a próxima chamada reenvie bytes idênticos.
Como provar que o prefixo está em cache?
Rode um teste de duas chamadas no CI ou num notebook:
- Monte uma requisição com seu prompt de sistema, suas ferramentas e seus documentos reais.
- Envie. Anote
usage.prompt_tokens. - Mude só a mensagem final do usuário e envie de novo.
- Leia
usage.prompt_tokens_details.cached_tokensna segunda chamada. Ele deve cobrir quase todo o prefixo compartilhado. - Se for zero ou pequeno, compare byte a byte os corpos das requisições serializadas. A primeira diferença é o que quebra o seu cache.
Na maioria dos provedores o cache é best-effort, e a documentação da DeepSeek diz isso diretamente, então uma falha isolada não prova um bug. Uma falha constante prova. Acompanhe a razão entre tokens em cache e tokens de prompt por requisição nos seus logs de uso, e use a calculadora de prompt caching para ver quanto uma taxa de acerto maior economiza.
O que muda para agentes e contexto longo?
Os agentes são os que mais ganham, porque reenviam o mesmo prefixo grande dezenas de vezes por tarefa. Dois hábitos importam:
- Uma conversa por tarefa. Começar uma conversa nova a cada subpasso joga o prefixo fora.
- Leia os arquivos uma vez, perto do topo. Se o agente reler um arquivo, acrescente a cópia nova em vez de substituir a antiga, a menos que o arquivo tenha mudado.
Com uma janela de contexto de 1M de tokens, a camada 3 pode guardar um repositório inteiro. Isso só cabe no bolso numa chave por token quando entra em cache, e é por isso que a ordem das camadas importa mais à medida que os prompts crescem. Prefixos em cache também tendem a reduzir o tempo até o primeiro token; veja TTFT vs throughput.
Onde a BroadNet Inference se encaixa
Na BroadNet Inference, o bloco usage informa prompt_tokens_details.cached_tokens quando o modelo informa, e a entrada em cache no DeepSeek V4.1 Flash, no GLM 5.3 e no Qwen3.8 27B é cobrada pela tarifa mais baixa listada na página de preços. A documentação da BroadNet não oferece breakpoints explícitos de cache nem um parâmetro de chave de cache, então o layout acima é a técnica inteira. Num plano ilimitado o cache não muda a conta, porque as sessões não têm medidor de tokens, mas a mesma estrutura ainda ajuda na latência.
