Controle de cache de prompt em um gateway de API multimodelo: prefixos estáveis, isolamento de locatário e análise de acertos de cache
Uma arquitetura de gateway prática para proteger taxas de acertos de cache de prompt em APIs OpenAI, Anthropic e Gemini: regiões de prompt estáveis, normalização de métricas de provedor, isolamento de locatário, atribuição de cobrança e verificações de implementação.
O cache de prompt é fácil de ser desperdiçado. Uma equipe pode ter um prompt de sistema de 40.000 tokens, esquema de ferramenta, bloco de política, mapa de repositório ou memória de agente que deveria ser reutilizável e, em seguida, colocar acidentalmente um carimbo de data/hora, ID de solicitação, nome de usuário, snippet de recuperação ou ordenação aleatória de ferramentas próximo ao topo do prompt. O provedor vê um prefixo diferente, o cache é perdido, a latência aumenta e a conta parece confusa.
Em um aplicativo de provedor único, você pode corrigir isso dentro do modelo de aplicativo. Em um gateway multimodelo, o problema é maior: cada provedor expõe diferentes controles de cache, limites de token, comportamento de tempo de vida, campos de uso e semântica de cobrança. O gateway precisa de um padrão de plano de controle portátil para montar prompts seguros para cache, medir o comportamento do cache, isolar locatários e atribuir custos.
Este artigo descreve uma arquitetura de referência. Não é um estudo de caso de cliente e não reivindica resultados de referência. Os fatos abaixo provêm de documentação do fornecedor e de pesquisas públicas; as recomendações de projeto são orientações operacionais em nível de gateway.
O modo de falha: montagem do prompt de quebra de cache
O cache de prompt geralmente recompensa prefixos de prompt repetidos. A mecânica exata varia de acordo com o fornecedor, mas a implicação prática é consistente: se a frente do prompt mudar, a reutilização será prejudicada.
Os disjuntores de cache comuns incluem:
- Metadados por solicitação na parte superior: carimbos de data/hora, IDs de rastreamento, IDs de sessão, IDs de implantação ou rótulos de solicitação gerados.
- Dados específicos do usuário no prefixo: nomes, atributos de conta, permissões ou preferências privadas colocadas antes de políticas reutilizáveis ou blocos de ferramentas.
- Serialização de ferramentas instável: esquemas de ferramentas emitidos em ordem não determinística, com alteração de espaços em branco ou IDs gerados.
- Snippets de recuperação muito cedo: contexto RAG inserido antes de instruções estáveis do sistema ou contexto de repositório compartilhado.
- Desvio de modelo: pequenas alterações de texto lançadas frequentemente sem controle de versão ou diagnóstico de cache.
Um gateway não pode magicamente tornar um prefixo instável armazenável em cache, mas pode impor um contrato de montagem imediato e tornar visíveis as falhas de cache.
Fatos do provedor para projetar
Os detalhes são importantes porque um gateway deve normalizar o comportamento sem fingir que os provedores são idênticos.
- OpenAI: a OpenAI documentou o cache de prompt para o prefixo de prompt mais longo computado anteriormente. Ele começa com 1.024 tokens, aumenta em incrementos de 128 tokens e expõe contagens de tokens armazenados em cache nos campos de uso. A OpenAI também afirma que os caches de prompt normalmente são limpos após 5 a 10 minutos de inatividade e sempre removidos dentro de uma hora após o último uso do cache.
- Anthropic: o cache de prompt do Antrópico pode ser solicitado com
cache_control. Sua documentação descreve a correspondência de cache em componentes de prompt, como ferramentas, conteúdo do sistema e mensagens até o bloco marcado com controle de cache. Anthropic documenta um cache efêmero, incluindo uma duração de 5 minutos e uma opção de 1 hora com custo adicional. - Gemini: o cache de contexto do Google Gemini expõe contagens de tokens de acertos de cache por meio de metadados de uso, como
total_cached_tokens, e sua documentação lista contagens mínimas de tokens de entrada por modelo. - Implicação de controle de dados: a documentação de controle de dados da API da OpenAI observa que o cache de prompt estendido requer o armazenamento de tensores de chave/valor como estado do aplicativo no armazenamento local da GPU. Mesmo quando os provedores mantêm garantias de isolamento, os gateways devem tratar o comportamento do cache como uma infraestrutura sensível, e não como um armazenamento de dados de aplicativos compartilhado.
- Sinal de pesquisa: A pesquisa pública examinou se as arquiteturas estilo gateway podem introduzir vulnerabilidades de cache imediato que contornam as suposições de isolamento de cache no nível do provedor. Isso não prova que um gateway específico seja vulnerável, mas suporta um design conservador de isolamento de locatário.
Recomendação: implemente o controle de cache como um recurso de gateway com políticas explícitas, e não como um efeito colateral acidental de solicitações repetidas.
Um contrato de montagem imediata em três regiões
A decisão de design mais importante é separar o conteúdo estável do volátil antes que a solicitação chegue ao adaptador do provedor.
Região 1: prefixo estável
Espera-se que o conteúdo do prefixo estável permaneça idêntico em muitas solicitações para o mesmo aplicativo, rota de modelo e versão do modelo de prompt. Os exemplos incluem:
- instruções básicas do sistema;
- bloqueios de segurança e políticas;
- esquemas de ferramentas;
- documentação estática do produto;
- mapas de repositório para agentes de codificação;
- instruções de formato de saída fixas.
Esta região deve ser determinística. O gateway deve ser construído a partir de modelos versionados, JSON canônico e regras de pedido estáveis. Se um registro de ferramenta estiver incluído, classifique as ferramentas por ID de ferramenta estável. Se esquemas JSON forem incluídos, serialize-os com ordem de chave determinística e sem carimbos de data/hora gerados.
Região 2: locatário semiestável ou contexto de espaço de trabalho
A região semiestável muda com menos frequência do que as solicitações individuais, mas não é compartilhada globalmente. Os exemplos incluem:
- substituições de políticas específicas do locatário;
- listas de permissões de ferramentas no nível do espaço de trabalho;
- terminologia específica do cliente;
- convenções de codificação em equipe;
- contexto de projeto de longa duração.
Essa região deve ter como escopo um locatário, um espaço de trabalho ou um limite de aplicativo. Ele ainda pode ser armazenado em cache, mas o gateway nunca deve presumir que outro locatário possa reutilizá-lo com segurança.
Região 3: sufixo volátil
O sufixo volátil é a parte por solicitação:
- mensagem do usuário;
- snippets recuperados para esta consulta;
- carimbo de data e hora atual, se for realmente necessário;
- ID da solicitação e metadados de rastreamento, se incluídos no prompt;
- conversas de curto prazo mudam;
- resultados da ferramenta de tempo de execução.
A maioria das falhas de cache causadas pelo design do aplicativo ocorre porque os dados do sufixo volátil são acidentalmente colocados no prefixo. Um construtor do lado do gateway deve dificultar isso.
Padrão de implementação: construtores de prefixo estável
Uma implementação prática de gateway pode expor uma interface de montagem de prompt em vez de aceitar uma string de prompt opaca de cada aplicativo.
O gateway então renderiza a solicitação específica do provedor. Isso dá ao gateway um local para aplicar regras:
- rejeitar carimbos de data/hora em campos de prefixo estáveis;
- canonizar esquemas de ferramentas;
- hash de cada região separadamente;
- anexar controles de cache onde um provedor os suporta;
- preservar a semântica do prompt ao mover material volátil posteriormente;
- registrar modelo e prefixar impressões digitais para diagnóstico.
Para aplicativos legados que enviam apenas mensagens brutas, o gateway ainda pode fornecer um modo lint: inspecionar a ordem das mensagens, calcular impressões digitais do prefixo e relatar possíveis disjuntores de cache sem reescrever o prompt inicialmente.
Camada adaptadora do provedor: normalize o uso do cache sem ocultar diferenças
Um gateway multimodelo não deve expor três relatórios de cache não relacionados aos desenvolvedores. Também não deve nivelar a economia específica do fornecedor de forma tão agressiva que as faturas se tornem impossíveis de explicar.
Crie um livro-razão de cache normalizado com campos como:
O adaptador mapeia o uso do provedor em categorias normalizadas:
- Tokens de entrada não armazenados em cache: tokens processados sem desconto de leitura de cache ou contabilidade de leitura de cache.
- Tokens de gravação de cache: tokens que criaram ou atualizaram uma entrada de cache do lado do provedor quando o provedor relata essa distinção.
- Tokens de leitura de cache: tokens servidos a partir do cache ou contados como armazenados em cache pelos metadados de uso do provedor.
- Tokens de saída: tokens gerados, que devem permanecer separados da economia de cache imediata.
- Opção TTL: a classe de duração do cache selecionada onde um provedor expõe uma escolha.
Recomendação: armazene o uso bruto do provedor em um formulário redigido e com versão de esquema junto com campos normalizados. A normalização é útil para painéis; campos brutos são necessários para reconciliação quando a semântica do provedor muda.
Observabilidade do cache: painéis que explicam falhas
Um painel de cache útil faz mais do que mostrar o total de tokens armazenados em cache. Isso deve ajudar as equipes a responder: “Qual carga de trabalho está quebrando o prefixo e o que mudou?”
Acompanhe métricas de cache por:
- inquilino;
- espaço de trabalho ou aplicativo;
- rota modelo;
- provedor e modelo;
- versão do modelo de prompt;
- hash de prefixo estável;
- hash de contexto semiestável;
- Chave de API ou conta de serviço, quando apropriado;
- janela de tempo, especialmente porque os TTLs de cache são curtos para muitas cargas de trabalho.
As métricas derivadas úteis incluem:
- Taxa de leitura de cache: tokens de entrada armazenados em cache divididos pelo total de tokens de entrada elegíveis para armazenamento em cache.
- Alteração de prefixos: número de hashes de prefixos estáveis distintos por versão do modelo por hora.
- Desvio do modelo: alterações no cache após o lançamento do modelo.
- Custo de inicialização a frio: gravação em cache ou gasto de entrada não armazenada em cache para a primeira solicitação consecutiva.
- Comparação de rotas: taxas de acerto entre rotas de provedores para a mesma carga de trabalho lógica.
Não use como padrão o armazenamento de prompts brutos para depuração. Prefira hashes, comprimentos de região, IDs de modelo, avisos de canonização e diferenças redigidas. Se uma equipe precisar de uma depuração mais profunda, exija controles de acesso e limites de retenção explícitos.
Política de isolamento de locatário: não projete para reutilização entre locatários
A suposição de gateway mais seguro é simples: o comportamento armazenável em cache deve ter escopo de locatário. Mesmo que dois locatários compartilhem um bloco de política pública idêntico, o gateway não deve rotear ou moldar intencionalmente o tráfego para explorar a reutilização de cache entre locatários.
Uma política conservadora inclui:
- Roteamento com reconhecimento de locatário: roteie o tráfego armazenável em cache usando limites de locatário, espaço de trabalho e aplicativo.
- Nenhum prefixo com segredo compartilhado: nunca coloque segredos de locatário, credenciais, documentos privados ou dados específicos do usuário em um prefixo compartilhado reutilizável.
- Impressões digitais de prefixo separadas: calcula impressões digitais com escopo de locatário incluído no razão do gateway, mesmo que o texto renderizado seja idêntico.
- Controles no nível da organização: permitem que os administradores desativem os recursos de cache do provedor para cargas de trabalho confidenciais.
- O isolamento do provedor não é um recurso do produto para revenda: trate o isolamento do cache do provedor como uma proteção básica, não como uma permissão para criar um pool de cache entre clientes.
Previsão: à medida que os agentes de contexto longo se tornam mais comuns, o comportamento do cache se tornará parte das revisões de segurança, e não apenas das análises de custos. Os gateways que puderem comprovar a política de cache no escopo do locatário serão mais fáceis de controlar.
Atribuição de faturamento: leituras, gravações e tokens normais de cache separados
O cache de prompts pode dificultar a compreensão das faturas se todos os tokens de entrada forem mostrados como um número. O razão de cobrança deve preservar pelo menos cinco categorias:
- tokens de entrada não armazenados em cache;
- tokens de gravação em cache;
- tokens de leitura em cache;
- tokens de saída;
- Taxas de controle de cache ou TTL específicas do provedor.
Isso é importante quando um provedor desconta leituras em cache, outro cobra diferentemente por gravações em cache e outro expõe uma opção de TTL mais longo. Uma fatura do cliente deve ser capaz de explicar por que duas solicitações com tokens de entrada totais semelhantes tiveram custos diferentes.
Para estorno interno, atribua efeitos de cache ao locatário e ao aplicativo que fez a solicitação. Evite alocar um benefício de leitura de cache de um locatário para outro. Se uma equipe de plataforma interna compartilhada possuir o modelo de prompt estável, relate o desempenho do cache no nível do modelo separadamente das faturas do locatário.
Lista de verificação de linting de cache
Antes de ativar a aplicação de cache, execute modelos de prompt por meio de uma lista de verificação de lint:
- Instruções estáveis do sistema aparecem antes da entrada volátil do usuário.
- Os esquemas de ferramentas são classificados por ID ou nome estável.
- JSON é serializado de forma determinística.
- Nenhum carimbo de data/hora, ID aleatório, ID de solicitação ou ID de rastreamento aparece no prefixo estável.
- Nenhum segredo específico do usuário aparece em blocos reutilizáveis compartilhados.
- Os snippets RAG são colocados após as seções reutilizáveis de políticas e ferramentas, a menos que haja um motivo deliberado para não fazê-lo.
- Os modelos de prompt têm versões explícitas.
- As versões de modelos podem ser correlacionadas com alterações na taxa de acertos do cache.
- Os controles de cache do provedor são usados somente por meio do código do adaptador, e não pela lógica dispersa do aplicativo.
- O registro de prompt bruto é desativado por padrão ou protegido por regras rígidas de retenção e acesso.
Plano de implementação
1. Observe antes de alterar os prompts
Comece coletando campos de uso do provedor e métricas de cache normalizadas para o tráfego existente. Calcule impressões digitais de prefixo para os primeiros N tokens ou para regiões de prompt definidas pelo gateway. O objetivo é encontrar rotas de alto volume e contexto longo com alta rotatividade de prefixos.
2. Classificar cargas de trabalho
Agrupe o tráfego em categorias: sessões de agente, assistentes de codificação, RAG, automação de suporte, análise de documentos, trabalhos em lote e chat curto. O trabalho de cache de prompt geralmente presta mais atenção a cargas de trabalho de contexto longo e prefixo repetido. Solicitações curtas abaixo dos limites do provedor podem não ser benéficas.
3. Introduzir construtores de prefixo estável
Mova uma carga de trabalho da construção de prompt bruto para a montagem baseada em região. Mantenha a solicitação do provedor renderizada semanticamente equivalente. Não combine essa mudança com a migração do modelo, o redesenho da ferramenta ou grandes reescritas de prompts, ou você não saberá o que causou as mudanças nas métricas.
4. Canário uma rota
Ative controles de cache para uma pequena parte de um locatário ou aplicativo interno. Compare a taxa de leitura do cache, a rotatividade do prefixo, o tempo até o primeiro token, a taxa de erro e as categorias de custo. Evite reivindicar economias até que as contas do provedor sejam reconciliadas com os registros do gateway.
5. Aplicar gradualmente
Depois do canário, transforme os avisos de lint em verificações de política. Por exemplo, avise primeiro sobre a ordem instável das ferramentas e, em seguida, rejeite novas versões de modelos que incluam metadados voláteis no prefixo estável.
Compensações
- Maior taxa de acertos de cache versus flexibilidade de prompt: prefixos estáveis melhoram a reutilização, mas as equipes podem precisar mover instruções dinâmicas posteriormente ou redesenhar modelos.
- Cache nativo do provedor versus portabilidade: usar os controles de cache de cada provedor pode melhorar a economia, mas os limites, os TTLs, os campos e a semântica de preços são diferentes.
- Observabilidade versus registro confidencial: diferenças de prompt ajudam a depurar falhas, mas hashes e diagnósticos editados são padrões mais seguros.
- Isolamento do locatário versus reutilização máxima: a reutilização ampla pode parecer atraente, mas o comportamento no escopo do locatário é mais seguro e fácil de explicar.
- Retenção mais longa versus complexidade de custos e políticas: opções de TTL mais longas podem ajudar as sessões do agente, mas podem introduzir diferentes considerações sobre preços e controle de dados.
Conclusão acionável
Trate o cache de prompt como um problema do plano de controle do gateway, não como uma caixa de seleção do provedor. O padrão prático é: definir regiões de prompt estáveis, semiestáveis e voláteis; renderizá-los de forma determinística; adaptar controles de cache específicos do provedor por trás de uma interface; normalizar o uso do cache em um livro-razão; expor diagnósticos de ocorrências de cache por inquilino, aplicativo, rota e versão do modelo; e impor suposições no escopo do locatário.
O primeiro passo útil não é reescrever. Adicione observabilidade de cache aos seus prompts mais longos, identifique a rotatividade de prefixos e identifique os modelos que causam mais erros. Depois de explicar o comportamento do cache, você poderá otimizá-lo com segurança.