---
title: "Estrutura de prompt para cache: prefixo estável | BroadRouter"
description: "Como organizar prompts de LLM para o prefixo em cache ficar idêntico: prompt de sistema, schemas de ferramentas, documentos, histórico só com acréscimos e um teste."
url: https://broadrouter.com/pt/blog/prompt-structure-for-caching/
lang: pt-BR
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Traduzido do inglês com ajuda de IA. [Leia o original em inglês](https://broadrouter.com/blog/prompt-structure-for-caching/) (atualizado em 2026-11-16).

# Como estruturar prompts para o prefixo entrar em cache

Pela equipe da BroadNet Inference · 4 min de leitura · Publicado em 2026-11-14 · Atualizado em 2026-11-16

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.

## Pontos principais

-   Os caches comparam um prefixo exato. Um único byte alterado invalida tudo o que vem depois, então a ordem das camadas importa mais que o tamanho delas.
-   Quatro camadas, da mais estável para a menos: prompt de sistema, ferramentas, documentos, histórico. O novo turno do usuário vem por último.
-   Serialize ferramentas e documentos JSON com chaves ordenadas e separadores fixos; a ordem de dicionários quebra o cache em silêncio.
-   Restrinja as ferramentas de cada chamada com tool\_choice em vez de remover definições de ferramentas.
-   Teste: envie o mesmo prefixo duas vezes e confira se prompt\_tokens\_details.cached\_tokens sobe na segunda chamada.

**Nesta página**

1.  Por que a ordem do prompt decide a taxa de acerto do cache?
2.  Qual é a ordem certa das camadas?
3.  O que quebra o prefixo sem você perceber?
4.  Como montar uma requisição amigável ao cache no código?
5.  Como provar que o prefixo está em cache?
6.  O que muda para agentes e contexto longo?
7.  Onde a BroadNet Inference se encaixa

[Tokens de entrada em cache](https://broadrouter.com/pt/glossary/cached-input-tokens/) 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](https://broadrouter.com/pt/blog/cached-input-tokens-explained/) 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](https://broadrouter.com/pt/glossary/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:

```python
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](https://broadrouter.com/pt/blog/llm-api-usage-logging/), e use a [calculadora de prompt caching](https://broadrouter.com/tools/prompt-caching-calculator/) 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](https://broadrouter.com/pt/blog/million-token-context-window-guide/), 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](https://broadrouter.com/pt/blog/llm-latency-ttft-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](https://broadrouter.com/pt/models/deepseek-v4.1-flash/), no [GLM 5.3](https://broadrouter.com/pt/models/glm-5.3/) e no [Qwen3.8 27B](https://broadrouter.com/pt/models/qwen3.8-27b/) é cobrada pela tarifa mais baixa listada na [página de preços](https://broadrouter.com/pt/pricing/). 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.

Ferramentas gratuitas sobre o tema (em inglês)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[Ferramentas gratuitas (em inglês)](https://broadrouter.com/tools/)

## Termos neste artigo

[Token](https://broadrouter.com/pt/glossary/token/)

Um token é a unidade de texto que um modelo de linguagem lê e escreve: uma palavra, parte de uma palavra, um sinal de pontuação ou uma sequência de bytes gerada pelo tokenizador do modelo. As APIs de LLM contam, limitam e normalmente cobram o uso em tokens.

[Tool calling (chamada de ferramentas)](https://broadrouter.com/pt/glossary/tool-calling/)

Tool calling, também chamado de function calling ou chamada de ferramentas, é um recurso de APIs de LLM em que o modelo devolve um pedido estruturado para executar uma função definida pelo desenvolvedor, com argumentos JSON. A aplicação executa a função e devolve o resultado; o modelo nunca executa código sozinho.

[Prompt de sistema (system prompt)](https://broadrouter.com/pt/glossary/system-prompt/)

O system prompt, ou prompt de sistema, é o texto de instruções que uma aplicação envia a um modelo de linguagem antes da conversa, em geral como mensagem com o papel system ou developer. Ele define o papel, as regras, o tom e o formato de saída do modelo, que deve segui-lo mesmo quando mensagens do usuário o contradizem.

[Tokens de entrada em cache (cached input)](https://broadrouter.com/pt/glossary/cached-input-tokens/)

Tokens de entrada em cache são tokens do prompt que um provedor de LLM processou há pouco e pode reaproveitar de um cache em vez de calcular de novo, normalmente um prefixo repetido, como um system prompt ou um documento. Os provedores os cobram com uma tarifa menor que a dos tokens de entrada novos.

[Throughput (vazão)](https://broadrouter.com/pt/glossary/throughput/)

Throughput, ou vazão, no serving de LLMs, é a quantidade total de trabalho que um sistema conclui por unidade de tempo em todas as requisições simultâneas, geralmente medida em tokens de saída ou requisições por segundo. É diferente da velocidade por stream, que é a rapidez com que uma única requisição recebe seus tokens.

[Time to first token (TTFT)](https://broadrouter.com/pt/glossary/time-to-first-token/)

Time to first token (TTFT) é o tempo entre o envio de uma requisição a um modelo de linguagem e a chegada do primeiro token de saída. Inclui o tempo de rede, a fila no servidor e o prefill, etapa em que o modelo lê o prompt inteiro, então cresce com o tamanho do prompt e a carga.

[Janela de contexto (context window)](https://broadrouter.com/pt/glossary/context-window/)

A janela de contexto é o número máximo de tokens com que um modelo de linguagem consegue trabalhar em uma única requisição. Ela abrange o prompt, o histórico da conversa, as definições de ferramentas, as imagens e a saída gerada, incluindo os tokens de raciocínio. O que não couber precisa ser cortado, resumido ou dividido em várias requisições.

[KV cache (cache de chave-valor)](https://broadrouter.com/pt/glossary/kv-cache/)

KV cache é a memória em que um modelo de linguagem transformer guarda as chaves e os valores de atenção calculados para cada token já processado, de modo que cada novo token os reutiliza em vez de recalcular a sequência inteira. Ele cresce com o tamanho do contexto e muitas vezes limita quantas requisições uma GPU consegue atender.

## 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.

## Continue lendo

-   [Tokens de entrada em cache: como reduzir a conta de API de LLM](https://broadrouter.com/pt/blog/cached-input-tokens-explained/)
-   [Quando vale a pena uma janela de contexto de 1M de tokens (ou não)](https://broadrouter.com/pt/blog/million-token-context-window-guide/)
-   [API de LLM com preço fixo ou por token: a conta do ponto de equilíbrio](https://broadrouter.com/pt/blog/flat-rate-vs-pay-per-token-llm-api/)
-   [Hardware de GPU e serving da BroadNet, segundo a própria BroadNet](https://broadrouter.com/pt/blog/broadnet-gpu-fleet-and-serving/)
-   [Cache de respostas de LLM para cortar custo: um cache exato em Python](https://broadrouter.com/pt/blog/cache-llm-responses-cut-cost/)
-   [Guia: Streaming de chat completions e conexões que caem](https://broadrouter.com/pt/guides/streaming-chat-completions/)
-   [Guia: Como usar o SDK Python da OpenAI com a BroadNet Inference](https://broadrouter.com/pt/guides/openai-python-sdk/)

Teste com a sua carga de trabalho real. Contas novas começam com US$ 5 de crédito para Gemma e transcrição. DeepSeek, GLM e Qwen3.8 exigem uma recarga.

[Começar](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-blog-prompt-structure-for-caching&utm_content=page-cta) ·

**Fontes**

-   [Referência da API da BroadNet Inference, tokens em cache no usage (consultado em 2026-11-16) (em inglês)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-blog-prompt-structure-for-caching&utm_content=sources)
-   [Guia de prompt caching da OpenAI, correspondência de prefixo e recomendações de estrutura (consultado em 2026-11-14)](https://developers.openai.com/api/docs/guides/prompt-caching)
-   [Documentação de prompt caching da Anthropic, ordem do cache: ferramentas, depois system, depois mensagens (consultado em 2026-11-16)](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
-   [Documentação da API da DeepSeek, context caching (consultada em 2026-11-14)](https://api-docs.deepseek.com/guides/kv_cache)
