Falhas no cache de prompts: 5 checagens antes de culpar as rotas

Conteúdo
  1. O que verificar primeiro quando os acertos de cache desaparecem?
  2. Quais configurações da aplicação e intervalos verificar?
  3. O que um gateway pode alterar entre o cliente e o provedor?
  4. Como investigar uma regressão de cache no Synthorai?
  5. Uma sessão medida: encontre a regressão e inspecione os spans
  6. Como os diagnósticos nativos ajudam a identificar mudanças na requisição?
  7. Quando investigar o próprio serviço de inferência?
  8. Como comprovar que a correção funcionou?
  9. Perguntas frequentes
  10. Adicionar cache_control garante um acerto?
  11. O roteamento pode causar uma falha de cache mesmo sem mudar o nome do modelo?
  12. Por que o diagnóstico indica mudança na requisição se alguns tokens vieram do cache?

Para diagnosticar falhas no cache de prompts, comece pelo uso reportado. Depois, compare o prefixo reutilizável, a elegibilidade, os intervalos e o destino real no upstream com uma requisição de referência cujo cache já estava aquecido.

TL;DR

  • A ausência de dados de cache deixa o resultado indeterminado; zero tokens lidos do cache não identifica a causa.
  • A taxa de acerto por requisição conta requisições com qualquer reutilização; a proporção de tokens reutilizados mede quanto da entrada foi reaproveitado.
  • Cada estado do diagnóstico nativo exige uma ação diferente: corrigir uma divergência, substituir uma referência ausente ou investigar uma comparação inconclusiva.
  • O DeepSeek exige correspondência com unidades de prefixo persistidas; compartilhar um prefixo de texto pode não bastar.

O que verificar primeiro quando os acertos de cache desaparecem?

Comece verificando se a resposta bruta realmente contém dados de uso do cache. Se o provedor reporta leituras, mas o cliente ou o painel não, investigue primeiro a apresentação desses dados. Caso contrário, preserve a última requisição com cache aquecido confirmado e compare com ela a requisição que apresentou a falha.

Primeira checagemEvidências a coletarPróxima ação mínima útil
A falha de cache é real?Uso bruto do provedor, resposta ao cliente e registro no painelVerifique campos ausentes e a agregação do streaming antes de alterar os prompts
O prefixo mudou?Ferramentas na ordem enviada, texto de sistema e mensagens anterioresCompare os componentes; mova timestamps ou IDs de requisição variáveis para depois do conteúdo reutilizável
O prefixo era elegível e foi gravado?Mínimo do modelo, controles e uso de leitura/gravaçãoConfira o modelo e a API exatos; inspecione o ponto de quebra pretendido
A requisição chegou cedo ou tarde demais?Horário de início da resposta, intervalo entre requisições e tempo de vida do cacheFaça uma chamada sequencial de acompanhamento antes de testar tráfego paralelo
O destino mudou?Modelo efetivo, serviço, escopo da conta e tentativas de fallbackPeça ao operador do gateway para comparar as tentativas reais no upstream

Use duas métricas com nomes explícitos, calculadas sobre requisições com dados completos de entrada e cache:

  • Taxa de acerto por requisição = requisições com mais de zero tokens lidos do cache / requisições com dados completos de uso.
  • Proporção de tokens reutilizados = soma dos tokens lidos do cache / soma de todos os tokens de entrada, incluindo entrada em cache e gravações no cache.

Reporte separadamente as requisições sem dados de uso e inclua as tentativas que falharam no custo do incidente. O crescimento da entrada pode reduzir a proporção de tokens reutilizados sem alterar a taxa de acerto por requisição.

API nativaCampo de leitura do cacheEntrada total usada no denominador da proporção de tokens
OpenAI Responsesusage.input_tokens_details.cached_tokensusage.input_tokens, que já inclui a entrada em cache
Anthropic Messagesusage.cache_read_input_tokensinput_tokens + cache_read_input_tokens + cache_creation_input_tokens dentro de usage
DeepSeekusage.prompt_cache_hit_tokensprompt_cache_hit_tokens + prompt_cache_miss_tokens dentro de usage

Use o schema normalizado do gateway quando os campos nativos tiverem sido convertidos; a fórmula do Synthorai aparece abaixo.

Quais configurações da aplicação e intervalos verificar?

Verifique se houve mudança no conteúdo antes do fim do prefixo que deveria ser reutilizado: timestamps no sistema, ordem das ferramentas e histórico reescrito são bons pontos de partida.

Alteração do prefixo. Capture fingerprints separados (hashes usados para detectar mudanças) das definições de ferramentas na ordem enviada, do texto de sistema estável e dos blocos de mensagens anteriores. Mantenha no final um marcador específico da requisição. O hash da requisição inteira muda durante o crescimento normal de uma conversa que apenas acrescenta mensagens e não permite localizar a primeira diferença. Espaços em branco no JSON fora do texto também são diferentes de espaços dentro de uma string visível ao modelo.

Inspecione onde o conteúdo recuperado é inserido, as mudanças de modo, a compactação e a requisição final gerada pelo framework. Para entradas multimodais, compare o pré-processamento e as referências a arquivos.

Elegibilidade e controles. Um ponto de quebra marca o fim do prefixo que se deseja armazenar em cache. O tempo de vida (TTL) é a duração configurada para a entrada no cache.

Uma requisição longa no total não garante que o prefixo reutilizável selecionado atenda ao mínimo do modelo. Para pontos de quebra explícitos, verifique o conteúdo anterior ao ponto de quebra. Adicionar cache_control não torna reutilizável um prefixo que não atende aos requisitos. Na Anthropic, inspecione os controles automáticos e os definidos por bloco, os conflitos de TTL e os limites de pontos de quebra; uma combinação inválida pode gerar HTTP 400, ou seja, rejeição da requisição, em vez de uma resposta bem-sucedida com zero leituras do cache. Cache de prompts da Anthropic.

Disponibilidade e expiração. Enviar uma rajada de requisições idênticas antes de a primeira gravação ficar disponível pode gerar várias requisições com cache frio. A Anthropic documenta que o cache fica disponível após o início da primeira resposta. Envie uma requisição de acompanhamento depois que a primeira resposta começar para estabelecer uma referência com cache aquecido. Depois, compare as requisições paralelas pelos horários de início das respostas. Em conversas ociosas, compare o intervalo com o tempo de vida configurado e com o comportamento de renovação documentado. Disponibilidade do cache da Anthropic.

Unidades persistidas do DeepSeek. O DeepSeek compara unidades completas de prefixo persistidas, que são trechos salvos do contexto anterior. O exemplo documentado começa com A+B, seguido de A+C: a segunda requisição não consegue reutilizar a unidade completa A+B. Depois que o serviço detecta e persiste o prefixo comum A, uma terceira requisição A+D pode reutilizar essa unidade. Aqui, A é o contexto estável, e B, C e D são sufixos diferentes. Esse mecanismo está documentado pelo fornecedor; não é uma medição nossa.

Nesse padrão, preserve A exatamente, conclua as duas primeiras requisições em sequência, considere que a persistência pode levar segundos e então inspecione os campos de tokens com e sem acerto de cache da terceira requisição. Apenas esperar não garante que a unidade de prefixo comum desejada tenha sido criada, e o cache continua sem garantia de acerto. Regras de persistência do DeepSeek.

O que um gateway pode alterar entre o cliente e o provedor?

Um gateway pode alterar tanto a requisição efetiva quanto as evidências devolvidas ao cliente. Verifique essas duas coisas separadamente antes de atribuir uma regressão ao roteamento.

Verifique aliases de modelo, escopo das credenciais, sobrescritas por políticas e tentativas de fallback. Na conversão de protocolo, inspecione os controles enviados e os campos nativos retornados; no streaming, compare os eventos de uso do upstream com o uso final entregue ao cliente.

Mudança de fornecedor no roteamento. O balanceamento ou o failover pode encaminhar o mesmo modelo público para fornecedores de inferência com caches separados. Um prefixo aquecido no fornecedor A fica indisponível no fornecedor B. Nosso estudo sobre mudanças de provedor observou nove upstreams e 4/20 acertos por requisição, contra 19/20 na comparação com um único backend. Esses resultados descrevem aquela configuração histórica.

Agrupe as tentativas por fornecedor, modelo e escopo da conta. Compare as leituras do cache dentro de cada grupo com prefixos e intervalos estáveis, incluindo falhas e destinos de fallback. Peça ao operador para verificar a afinidade (encaminhamento consistente de requisições relacionadas) e o failover. Repita após um ajuste aprovado. A troca de fornecedor confirma a mudança de destino; falhas individuais ainda exigem checagens de intervalo e elegibilidade.

As requisições do Synthorai não têm seletor de provedor/canal.

Como investigar uma regressão de cache no Synthorai?

Use Analytics para tendências da carga e Logs para requisições. Os rótulos foram conferidos no ambiente em execução em 6 de novembro de 2026.

  1. Delimite a carga. Em Analytics, selecione Time range e All keys · all models. Em Logs, use Add filter com model ou key. Mantenha as mesmas seleções nos intervalos normal e afetado. CACHE HIT é uma proporção de tokens reutilizados, não uma taxa de acerto por requisição.
  2. Inspecione a requisição. Em Overview, compare Input, Cache read, Output e as gravações aplicáveis em Cost at your rate. Leituras estáveis com aumento da entrada sugerem crescimento do contexto; queda nas leituras e aumento nas gravações sugerem verificar o prefixo e os intervalos. Raw contém os campos armazenados, não a resposta original do provedor.
  3. Acompanhe o trace e a sessão. Na requisição afetada em Logs, selecione Open trace e depois Open session. Em Traces in this session, compare as tarefas e abra o trace sem reutilização. Clique em cada span (operação individual) para inspecionar leituras/gravações do cache e cobranças; o waterfall sozinho não mostra a reutilização do cache. Use os filtros session ou trace de Logs para acessar os registros correspondentes. Preserve links, timestamps e IDs de resposta nativos para escalar a investigação.

Envie X-Session-Id por conversa, X-Trace-Id por tarefa e X-Span-Id por operação. Agrupe por modelo e pelo prefixo que deveria ser compartilhado antes de interpretar as tendências do cache.

Correlação e roteamento são coisas distintas: X-Session-Id também tem precedência sobre a chave de cache no corpo para a afinidade do gateway; X-Trace-Id apenas agrupa observações. Mantenha a identidade da sessão estável nas comparações. Nenhum deles garante cache compartilhado ou destino fixo; não agrupe conversas sem relação para tentar aumentar os acertos.

Para registros completos armazenados pelo Synthorai, calcule a reutilização de tokens assim:

cache reads = cached_tokens + explicit_cached_tokens
input total = prompt_tokens + explicit_cached_tokens + cache_write_tokens
reuse ratio = sum(cache reads) / sum(input total)

Aqui, cached_tokens já está incluído em prompt_tokens; somá-lo novamente contaria a entrada duas vezes. As gravações no cache entram no denominador, não no numerador. Exclua os registros sem dados de uso e reporte a quantidade separadamente; um zero armazenado, por si só, não prova que o upstream informou um zero medido.

Uma sessão medida: encontre a regressão e inspecione os spans

Seguindo nossa investigação de custos de agentes, enviamos seis requisições sequenciais à API Responses pelo Synthorai em 6 de novembro de 2026, usando GPT-6.1 Sol. Uma sessão continha três traces, cada um com duas chamadas rotuladas lookup-1 e lookup-2. Esses rótulos identificam chamadas sintéticas ao modelo; nenhuma ferramenta de consulta foi executada. Modelo, ferramentas e ID de sessão permaneceram fixos. A regressão inseria um novo valor semelhante a um timestamp no início de cada requisição; a correção restaurou o prefixo original. Os marcadores de requisição permaneceram no final.

TraceTokens de entradaLeituras do cacheReutilizaçãoCusto reportado
referência4,7292,27348.1%$0.0063923
regressão4,76400%$0.0119350
correção4,7324,54696.1%$0.0009446

Tabela da sessão real comparando os traces de referência, regressão e correção

Em Traces in this session, abra a linha da regressão sem reutilização. A referência inclui uma primeira chamada com cache frio; a correção reutiliza um prefixo já aquecido. Essa demonstração com seis chamadas mostra a falha introduzida e a recuperação, não uma taxa de economia esperada em produção. A reutilização na sessão inteira é 6,819 / 14,225 = 47.9%; essa média esconde a regressão.

Waterfall do trace de regressão com dois spans de consulta

Selecione lookup-1 no waterfall. Os detalhes mostram 2,306 tokens gravados no cache de um total de 2,381 tokens de entrada, compatível com a reconstrução do prefixo alterado. As requisições sintéticas armazenadas comprovam a diferença introduzida; a linha do tempo sozinha não consegue identificá-la. Use Open in Logs para acessar o registro da requisição e compare os fingerprints do prefixo capturados na aplicação.

Detalhes do span da regressão mostrando a cobrança de gravação no cache

Essa demonstração não solicitou comparações de diagnóstico nativas. A mudança de prefixo introduzida e o uso reportado comprovam a regressão e a recuperação observadas; a continuidade do fornecedor real não foi verificada de forma independente. A identidade da sessão permaneceu fixa, portanto o experimento não mede um benefício de afinidade.

Para BYOK, diferencie o custo reportado pelo provedor do custo estimado antes de conciliar a fatura. Obtenha evidências do operador para detalhes de destino/fallback que não estejam disponíveis.

Como os diagnósticos nativos ajudam a identificar mudanças na requisição?

Os diagnósticos nativos identificam diferenças entre requisições; os dados de uso medem a reutilização reportada. Leia os dois em conjunto. O caminho selecionado no gateway precisa oferecer suporte aos campos nativos e preservá-los. Nosso teste anterior de comparação no Synthorai não retornou diagnósticos, portanto a documentação do fornecedor, sozinha, não comprova a disponibilidade no gateway.

A API OpenAI Responses aceita prompt_cache_options.comparison_response_id nos modelos compatíveis. Guarde o ID da resposta de referência concluída e envie o conteúdo real da requisição seguinte; a referência de comparação não carrega o histórico da conversa. Os resultados aparecem em prompt_cache_diagnostics, inclusive no evento response.completed durante o streaming. Use os estados abaixo para escolher a próxima ação. As estimativas de tokens do diagnóstico são separadas do uso faturado. Diagnósticos de cache da OpenAI.

A API Anthropic Messages usa diagnostics: {"previous_message_id": null} para a ativação inicial, seguido do ID nativo da mensagem anterior nas requisições seguintes com diagnóstico ativado. No streaming, o resultado aparece em message_start. Só interprete um resultado nulo depois de verificar que ambas as requisições ativaram o diagnóstico e que a seguinte forneceu uma referência real. A Anthropic documenta os diagnósticos para a Claude API, excluindo Amazon Bedrock e Claude gerenciado pelo Google. Diagnósticos de cache da Anthropic.

API e estado retornadoSignificadoPróxima ação
OpenAI cache_hitA comparação não detectou falha de cacheLeia os dados de uso para quantificar a reutilização; novos tokens de sufixo ainda podem exigir processamento
OpenAI cache_missUma diferença classificada afetou a reutilização esperadaInspecione reason, corrija o componente indicado e compare novamente
OpenAI comparison_response_not_foundRegistro de referência ausente ou expiradoEscolha uma resposta recente e concluída da mesma organização
OpenAI unavailableComparação não suportada ou inconclusivaVerifique o suporte do modelo; tente uma referência recente e, se persistir, faça checagens manuais
Anthropic diagnostics: nullAusência de divergência apenas quando houve uma comparação válida com diagnóstico ativado; também é retornado sem ativação ou no primeiro turnoVerifique primeiro a ativação e a referência; com correspondência válida e poucas leituras, verifique a disponibilidade do cache
Anthropic cache_miss_reason: null dentro de um objeto de diagnósticoComparação pendenteVerifique o próximo turno com diagnóstico ativado; não classifique o resultado pendente como falha de cache
Anthropic motivo do tipo *_changedPrimeiro componente divergente identificadoCorrija esse componente e compare novamente; diferenças posteriores podem continuar existindo
Anthropic previous_message_not_foundNenhum fingerprint de referência retidoVerifique a ativação na requisição anterior, a organização/workspace e o tempo decorrido; estabeleça uma nova referência
Anthropic unavailableComparação inconclusiva, inclusive por algumas mudanças em outros parâmetros ou limites de comparaçãoCompare o tool_choice efetivo, as configurações de raciocínio/saída e os headers beta; se persistir, faça checagens manuais
Campo de diagnóstico ausente em qualquer uma das APIsEvidência ausenteVerifique o suporte da API/modelo, as opções da requisição, a conversão e a captura de eventos do streaming

O prompt_cache_key_changed da OpenAI exige atenção especial: o uso pode reportar uma falha sem que tenha ocorrido uma falha física no cache. Antes de atribuir o resultado à disponibilidade do cache, verifique se a chave foi alterada intencionalmente para separar a contabilização. Mantenha a chave estável dentro do grupo de contabilização pretendido e verifique também seu papel na afinidade do gateway. Motivos de diagnóstico da OpenAI.

Quando investigar o próprio serviço de inferência?

Investigue a disponibilidade do cache depois de confirmar conteúdo elegível, intervalos válidos, escopos de destino comparáveis e dados de uso confiáveis. Mesmo assim, uma entrada idêntica não garante que exista uma entrada reutilizável no cache.

As possíveis explicações incluem expiração, persistência incompleta, pressão de capacidade e agendamento no serviço. A OpenAI documenta restrições de roteamento e disponibilidade do cache; um rótulo de sessão não garante acesso a um worker específico. Um acerto parcial também pode significar que um prefixo anterior continua reutilizável, mas o conteúdo posterior precisa ser processado. Cache de prompts da OpenAI.

Demora no primeiro token ou zero leituras não comprovam uma troca de cluster. Ao escalar o caso, envie IDs de resposta nativos, timestamps, intervalos e rótulos de destino; sem evidências do provedor, mantenha o mecanismo como indeterminado.

Recursos explícitos de cache exigem outra checagem: inspecione a existência, a expiração e o escopo do objeto referenciado. Não diagnostique um ID de recurso explícito obsoleto com as mesmas premissas usadas para cache automático de prefixos.

Como comprovar que a correção funcionou?

Compare o tráfego normal, afetado e corrigido usando dados de uso, diagnósticos e destinos.

Inclua novas tentativas no custo. Uma correção nos relatórios deve reconciliar o uso nativo com o uso apresentado ao cliente. Uma correção no prefixo deve eliminar a diferença e restaurar uma reutilização comparável. Uma correção de roteamento deve confirmar o destino pretendido e a recuperação dentro desse escopo. Se a condição relevante não for atendida, mantenha a classificação como não resolvida e continue a partir das evidências restantes.

Perguntas frequentes

Adicionar cache_control garante um acerto?

Os controles de cache continuam sujeitos ao tamanho e à posição do prefixo, à disponibilidade e ao tempo de vida. Verifique os requisitos do modelo e os dados brutos de uso.

O roteamento pode causar uma falha de cache mesmo sem mudar o nome do modelo?

Um nome de modelo estável no cliente pode ser resolvido para diferentes fornecedores, modelos ou escopos de conta. Compare as tentativas reais com o operador do gateway usando o roteiro para investigar mudanças de provedor.

Por que o diagnóstico indica mudança na requisição se alguns tokens vieram do cache?

Uma mudança perto do final da requisição pode manter um prefixo anterior reutilizável. Analise o componente alterado junto com a quantidade absoluta de tokens lidos do cache. A comparação de diagnóstico e a contabilização do cache descrevem aspectos diferentes da requisição.

Para investigações relacionadas, consulte a auditoria de cache do gateway, a análise de custos de gravação no cache e os intervalos de compactação.

← Voltar ao blog