BroadRouter

Como estruturar prompts para o prefixo entrar em cache

Pela equipe da BroadNet Inference · 4 min de leitura · Publicado em · Atualizado em

Ordene cada requisição da parte mais estável para a menos estável: prompt de sistema, definições de ferramentas, documentos de referência, histórico da conversa e, por fim, a mensagem nova. Deixe cada camada idêntica byte a byte entre as chamadas: sem timestamps ou IDs no topo, ferramentas ordenadas, JSON serializado de forma determinística e histórico que só recebe acréscimos. Depois meça cached_tokens para confirmar que o prefixo é mesmo reaproveitado.

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?

  1. Ordem de dicionários. Frameworks costumam montar o array tools a partir de um dicionário ou registro. Se os plugins carregarem em outra ordem, os bytes mudam.
  2. Formatação de JSON. json.dumps(x) e json.dumps(x, indent=2) são prefixos diferentes. Dois serializadores com ordens de chave diferentes também.
  3. Espaços no template. Um espaço no fim da linha, ou um \r\n vindo de um caminho do código e um \n de outro.
  4. 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_choice ou uma configuração de ferramentas permitidas.
  5. 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.
  6. 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:

  1. Monte uma requisição com seu prompt de sistema, suas ferramentas e seus documentos reais.
  2. Envie. Anote usage.prompt_tokens.
  3. Mude só a mensagem final do usuário e envie de novo.
  4. Leia usage.prompt_tokens_details.cached_tokens na segunda chamada. Ele deve cobrir quase todo o prefixo compartilhado.
  5. 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.

Perguntas frequentes

Por que a taxa de acerto de cache do meu prompt está baixa?

Alguma coisa perto do início do prompt muda a cada chamada. As causas comuns são um timestamp ou ID de requisição no prompt de sistema, ferramentas serializadas em outra ordem, documentos recuperados colocados antes das instruções, ou um histórico que é resumido e reescrito.

A pergunta do usuário vai antes ou depois dos documentos longos?

Depois. Coloque os documentos primeiro e a pergunta por último. Assim os documentos formam um prefixo reaproveitável, e muitos modelos também respondem melhor quando a pergunta vem depois do material.

Definições de ferramentas quebram o prompt caching?

Só se mudarem. As ferramentas fazem parte do prefixo, então mantenha o mesmo conjunto, na mesma ordem, com o mesmo JSON. Para limitar as ferramentas numa chamada, use tool_choice em vez de editar a lista.

A ordem dos exemplos few-shot importa para o cache?

Sim. Exemplos embaralhados geram um prefixo diferente a cada vez. Fixe a ordem, ou coloque depois da parte estável os exemplos que mudam a cada requisição.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity