Toda requisição de LLM idêntica que você envia duas vezes é paga duas vezes. Um cache de respostas guarda a resposta da primeira vez e a devolve da próxima, sem tokens cobrados e sem espera. A ideia é simples. As partes difíceis são decidir o que torna duas requisições “idênticas”, quais requisições nunca devem ser servidas a partir do armazenamento e se o seu tráfego se repete o bastante para fazer diferença.
Este post monta um pequeno cache exato em Python sobre SQLite, testado contra um servidor mock compatível com a OpenAI, e mostra como medir a taxa de acerto a partir dos seus logs antes de escrever qualquer linha dele.
Cache de respostas é o mesmo que prompt caching?
Não. Eles economizam coisas diferentes, e você pode usar os dois.
| Prompt caching (provedor) | Cache de respostas (você) | |
|---|---|---|
| O que é reaproveitado | O início repetido do prompt | A resposta inteira |
| Quem opera | O provedor da API | O seu código |
| O modelo ainda roda? | Sim, escreve uma resposta nova | Não |
| O que economiza | Parte do custo de entrada | Tokens de entrada, saída e raciocínio, além de latência |
| Quando acerta | Prefixo compartilhado, perguntas diferentes | Exatamente a mesma requisição |
Tokens de entrada em cache explica o lado do provedor, e estrutura de prompt para cache mostra como organizar um prompt para o prefixo ser reaproveitado. A calculadora de prompt caching calcula o preço. Um cache de respostas fica na frente de tudo isso: num acerto, nenhuma requisição sai do seu servidor.
Um cache vai mesmo economizar dinheiro?
Meça antes de construir. As porcentagens de economia de muitos tutoriais de cache vêm do tráfego de outra pessoa. O seu número depende de uma coisa só: com que frequência a mesma requisição chega de novo dentro da sua janela de validade.
Se você já registra cada chamada, como em registro de uso de API de LLM, acrescente um campo: request_hash, a chave de cache descrita abaixo. Ele não guarda texto de prompt, então cabe num log que mantém o conteúdo de fora. Depois conte as repetições:
import json
from collections import Counter
def potential_hit_rate(log_path: str) -> float:
"""Share of calls whose request_hash was already seen: an upper bound for an exact cache."""
hashes = [json.loads(line)["request_hash"] for line in open(log_path)]
seen, repeats = set(), 0
for h in hashes:
repeats += h in seen
seen.add(h)
print("top repeated requests:", Counter(hashes).most_common(3))
return repeats / len(hashes) if hashes else 0.0
print(f"potential hit rate: {potential_hit_rate('calls.jsonl'):.1%}")
Num log sintético de 20 chamadas, com uma requisição repetida cinco vezes, outra três vezes e doze únicas, ele imprimiu uma taxa de acerto potencial de 30,0%. Isso é um limite superior: ignora a validade e supõe que toda repetição pode ser servida do armazenamento com segurança.
Depois transforme a taxa em dinheiro:
monthly saving = hit rate × requests per month
× (input tokens × input price + output tokens × output price) ÷ 1,000,000
Ou seja: economia mensal = taxa de acerto × requisições por mês × (tokens de entrada × preço de entrada + tokens de saída × preço de saída) ÷ 1.000.000.
Os tokens de saída incluem o raciocínio. A documentação da BroadNet diz que o DeepSeek V4.1 Flash, o GLM 5.3 e o Qwen3.8 27B raciocinam antes de responder e que o raciocínio conta em max_tokens, então um acerto economiza tokens que você nunca vê na resposta. Pegue completion_tokens do usage registrado, não do tamanho da resposta.
Um exemplo em tokens: 100.000 requisições por mês com 1.200 tokens de entrada e 150 de saída cada, com taxa de acerto de 30%, evitam 36 milhões de tokens de entrada e 4,5 milhões de tokens de saída. No DeepSeek V4.1 Flash eles são cobrados a $0.175 e $0.52 por 1M, respectivamente; coloque os seus números na calculadora de custo de API de LLM. Se a maior parte dessa entrada já era acerto do cache do provedor, a economia de entrada é pela tarifa mais baixa de entrada em cache ($0.0055 por 1M no mesmo modelo), então muitas vezes é o lado da saída que importa.
O que vai na chave do cache?
Tudo o que pode mudar a resposta, e nada mais.
- Inclua:
model, a listamessagescompleta (com o prompt de sistema),temperature,top_p,max_tokens,seed,response_format,tools,tool_choiceereasoning_effort. - Acrescente uma versão do prompt controlada por você, como
faq-v3. Aumente a versão quando mudar templates de prompt, dados de recuperação ou pós-processamento que o corpo da requisição não mostra. - Deixe de fora tudo o que varia a cada chamada sem mudar a resposta: IDs de requisição, timestamps, headers de tracing, um campo
userque você só envia para monitorar abuso.
Serialize o material da chave sempre do mesmo jeito. O json.dumps do Python com sort_keys=True e separators=(",", ":") gera uma única string canônica, independentemente da ordem do dicionário; ensure_ascii=False mantém árabe e outros textos não latinos em UTF-8 em vez de sequências de escape. Gere o hash com SHA-256.
O erro perigoso é um campo faltando. Se max_tokens não estiver na chave, uma resposta cortada com um limite baixo vai ser servida para uma requisição que permitia uma longa.
O cache: SQLite, TTL e uma política de exclusão
import hashlib, json, sqlite3, time
# Every field that changes the answer belongs in the key.
KEY_FIELDS = ("model", "messages", "temperature", "top_p", "max_tokens", "seed",
"response_format", "tools", "tool_choice", "reasoning_effort")
def cache_key(params: dict, prompt_version: str) -> str:
material = {k: params[k] for k in KEY_FIELDS if k in params}
material["prompt_version"] = prompt_version
canon = json.dumps(material, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
return hashlib.sha256(canon.encode("utf-8")).hexdigest()
class ResponseCache:
def __init__(self, path="llm_cache.sqlite", ttl_s=7 * 86400):
self.db, self.ttl = sqlite3.connect(path), ttl_s
self.db.execute("CREATE TABLE IF NOT EXISTS cache (k TEXT PRIMARY KEY, created REAL,"
" body TEXT, prompt_tokens INT, completion_tokens INT)")
self.hits = self.misses = self.skips = self.saved_in = self.saved_out = 0
def create(self, client, prompt_version: str, **params):
if params.get("stream") or params.get("temperature", 1) > 0:
self.skips += 1 # not cacheable: call the model directly
return client.chat.completions.create(**params)
k = cache_key(params, prompt_version)
row = self.db.execute("SELECT body, created, prompt_tokens, completion_tokens"
" FROM cache WHERE k = ?", (k,)).fetchone()
if row and time.time() - row[1] < self.ttl:
self.hits += 1; self.saved_in += row[2]; self.saved_out += row[3]
return json.loads(row[0]) # a plain dict, not an SDK object
self.misses += 1
r = client.chat.completions.create(**params)
choice = r.choices[0]
if choice.finish_reason == "stop" and not choice.message.tool_calls:
self.db.execute("INSERT OR REPLACE INTO cache VALUES (?, ?, ?, ?, ?)",
(k, time.time(), r.model_dump_json(),
r.usage.prompt_tokens, r.usage.completion_tokens))
self.db.commit()
return r.model_dump()
E uma execução com ele:
import os
from openai import OpenAI
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
cache = ResponseCache("demo.sqlite", ttl_s=86400)
SYSTEM = {"role": "system", "content": "Answer questions about our refund policy in one sentence."}
questions = ["How long do refunds take?", "Can I refund a gift card?",
"How long do refunds take?", "How long do refunds take?", "Can I refund a gift card?"]
for q in questions:
r = cache.create(client, "faq-v3", model="broadnet/deepseek-v4.1-flash", temperature=0,
max_tokens=1200, messages=[SYSTEM, {"role": "user", "content": q}])
print(r["choices"][0]["message"]["content"])
# a personalised, sampled request is never cached
cache.create(client, "faq-v3", model="broadnet/deepseek-v4.1-flash", temperature=0.7,
messages=[SYSTEM, {"role": "user", "content": "Write me a friendly reminder"}])
# a new prompt version is a new key
cache.create(client, "faq-v4", model="broadnet/deepseek-v4.1-flash", temperature=0,
max_tokens=1200, messages=[SYSTEM, {"role": "user", "content": "How long do refunds take?"}])
print(f"hits={cache.hits} misses={cache.misses} skipped={cache.skips} "
f"saved_input={cache.saved_in} saved_output={cache.saved_out}")
Rodamos isso com o SDK Python da OpenAI 3.51.0 contra um servidor mock local que contava as chamadas upstream e informava 1.200 tokens de prompt e 150 de completion por resposta (sem chamada à API real). Sete requisições geraram quatro chamadas upstream. O script imprimiu hits=3 misses=3 skipped=1 saved_input=3600 saved_output=450. Rodando de novo no mesmo arquivo de banco, as seis requisições cacheáveis foram acertos (hits=6 misses=0): o SQLite mantém o cache entre reinícios. Chaves montadas com os mesmos campos em outra ordem coincidiram.
Notas sobre o código:
max_tokens=1200deixa espaço para o raciocínio antes da resposta. Com um limite baixo, um modelo que raciocina pode devolver uma resposta vazia (por quê). Essas respostas não são guardadas, porquefinish_reasonélength, nãostop.- Acertos devolvem um dict. Erros de cache também devolvem
model_dump(), então quem chama vê um formato só. Se o seu código espera objetos do SDK, embrulhe os dois. - Uma
temperatureausente conta como amostrada. O servidor então aplica o próprio padrão, que pode ser maior que 0, então o wrapper pula o cache a menos que você defina 0 explicitamente. - SQLite serve para um processo ou poucos. Para vários servidores, coloque a mesma lógica de chave e TTL no Redis ou no seu banco de dados.
O que nunca deve ser servido de um cache?
- Respostas amostradas (temperature acima de 0). Você escolheu variedade. O cache a elimina, e um usuário que aperta “gerar de novo” recebe o mesmo texto.
- Respostas personalizadas, a menos que o ID do usuário esteja na chave. Dois usuários que enviam “resuma a minha conta” têm contas diferentes. Melhor ainda: guarde em cache só requisições cujas mensagens não tenham dados de um usuário específico.
- Chamadas de ferramenta. Uma chamada de ferramenta é uma instrução para agir. Repetir “reembolse o pedido 1182” a partir do armazenamento pode repetir um efeito colateral, e o próximo passo certo depende do estado atual. O wrapper se recusa a guardar qualquer resposta com
tool_calls. - Respostas em streaming. O wrapper ignora o cache para
stream=True. Guardar um stream em cache significa bufferizá-lo, conferir que terminou e reproduzi-lo, o que raramente compensa em interfaces de chat. - Respostas cortadas ou com falha. Guarde só
finish_reason == "stop". Uma resposta cortada ou um erro em cache por uma semana é um bug que parece problema do modelo. - Respostas que dependem do tempo. “Qual é a cotação do câmbio hoje?” precisa de um TTL curto ou de nenhum cache.
O que funciona bem em cache: classificação de um conjunto fixo de entradas, extração de documentos que você reprocessa, respostas de FAQ a partir de um prompt fixo, suítes de teste e avaliações que você roda de novo, e ciclos de desenvolvimento em que você envia a mesma requisição várias vezes.
Quando as respostas em cache devem expirar?
Use três tipos de invalidação:
- TTL. Um limite de tempo por entrada: dias para respostas de FAQ estáveis, minutos para qualquer coisa que leia dados ao vivo.
- Versão na chave. Mude a versão do prompt quando o prompt de sistema, o índice de recuperação ou o schema de saída mudarem. As entradas antigas deixam de coincidir e expiram.
- Modelo na chave. Ele já está lá, então trocar de modelo começa um cache novo, que é o que você quer enquanto avalia uma troca.
Apague as linhas expiradas periodicamente (DELETE FROM cache WHERE created < ?). Senão o arquivo só cresce.
Há um benefício extra. Motores de serving não prometem saída idêntica para entrada idêntica: a documentação do vLLM diz que ele “does not guarantee the reproducibility of the results by default” (tradução: não garante a reprodutibilidade dos resultados por padrão). Um cache dá a todo usuário a mesma resposta para a mesma pergunta durante a vida da entrada.
E o cache semântico?
Um cache semântico gera o embedding de cada pergunta e devolve uma resposta guardada quando uma pergunta nova é parecida o bastante, então “quanto tempo leva um reembolso?” pode acertar “quanto tempo os reembolsos demoram?”. O GPTCache é o exemplo open source mais conhecido. O README dele diz que usa um banco vetorial para busca por similaridade e um avaliador de similaridade para decidir um acerto, avisa que “you may encounter false positives during cache hits and false negatives during cache misses” (tradução: você pode encontrar falsos positivos nos acertos de cache e falsos negativos nas falhas) e observa que desativar os embeddings o transforma num cache por palavras-chave.
Dois pontos práticos. Primeiro, ele precisa de um modelo de embeddings e de um banco vetorial. A BroadNet Inference não oferece embeddings, então você usaria outro provedor ou um modelo local nessa camada; a calculadora de custo de embeddings compara as opções. Segundo, um acerto falso devolve uma resposta confiante para outra pergunta. Use um limiar de similaridade rígido, teste com pares reais de quase-acertos e reserve o cache semântico para respostas de baixo risco. De qualquer forma, coloque o cache exato na frente: ele não custa nada para consultar e nunca erra sobre o que foi perguntado.
O que um cache significa para a privacidade?
Um cache é um depósito de prompts e respostas. Isso muda onde os seus dados ficam.
A declaração de privacidade de inferência da BroadNet, verificada em 2026-11-15, diz que o gateway dela não guarda prompts, mensagens, respostas ou transcrições, enquanto registros de tráfego e de uso sem conteúdo (contagens de tokens, custo, tempos) são mantidos. O conteúdo de inferência não é retido. Os metadados necessários de conta, cobrança e segurança são mantidos conforme descrito nessa declaração. Quando você adiciona um cache de respostas, o seu sistema guarda o conteúdo que o provedor não guarda. Trate-o como qualquer outro depósito de dados de usuários:
- Sempre que puder, guarde em cache só requisições sem dados pessoais, o que também aumenta a taxa de acerto.
- Defina um TTL curto o bastante para a sua política de retenção e apague periodicamente.
- Criptografe o arquivo ou a tabela em repouso e limite quem pode ler.
- Inclua o cache nos pedidos de exclusão de dados se ele puder guardar texto de usuários.
Enviar dados sensíveis para uma API de LLM cobre o resto desse checklist.
Como o cache se encaixa com outros controles de custo?
O cache elimina chamadas repetidas. Ele não faz nada pelas únicas, então fica ao lado dos outros controles em vez de substituí-los: prompts mais curtos, prompt caching do provedor, um limite de max_tokens por requisição e orçamentos e limites de loop do controle de gastos com API de LLM. Para jobs grandes e pontuais, elimine entradas duplicadas antes de enviá-las; é a mesma ideia de um cache, feita uma vez só. Processar um job grande sem uma Batch API mostra o lado do job.
Num plano de preço fixo a conta muda. As sessões do DeepSeek da BroadNet não têm medidor de tokens, então ali um acerto de cache não economiza dinheiro. Ele ainda economiza tempo: uma sessão roda uma requisição por vez, então cada repetição que você pula libera a sessão para trabalho novo.
Onde a BroadNet Inference se encaixa
O BroadRouter é o site da própria BroadNet. A BroadNet Inference oferece o DeepSeek V4.1 Flash, o GLM 5.3, o Qwen3.8 27B e o Gemma 4 VL 26B atrás de um endpoint /v1/chat/completions compatível com a OpenAI, então o wrapper acima funciona com o SDK Python da OpenAI trocando a base URL. Ela não tem um recurso próprio de cache de respostas; o cache deste post é seu. Acertos do cache do lado do provedor aparecem em usage.prompt_tokens_details.cached_tokens e são cobrados pelo preço de entrada em cache, segundo a referência da API. Os preços por modelo estão na página de preços.
