Em aplicativos com agentes de IA e em conversas com vários turnos, nossos modelos funcionam melhor quando você preserva o raciocínio entre as solicitações à API e sempre acrescenta novas ações e instruções ao final do contexto do modelo. Manter o prefixo intacto é uma prática recomendada há muito tempo para o cache de prompts. O cache compara as solicitações desde o início. Por isso, uma alteração no prefixo pode impedir a reutilização do cache a partir do ponto alterado. Quando você acrescenta as mudanças ao final, o cache pode reutilizar uma parte maior da conversa, o que pode reduzir bastante os custos de entrada e acelerar as respostas.
A partir dos modelos de fronteira mais recentes, a API descarta os itens de raciocínio que vêm depois do ponto alterado no prefixo. Essa medida faz parte das nossas proteções contra a destilação de modelos. Quando a API descarta esses itens, o modelo pode precisar refazer parte do raciocínio, o que pode aumentar o consumo de tokens, o custo e a latência. Se o modelo não conseguir recuperar o raciocínio perdido, a qualidade da resposta também pode cair.
Para obter o melhor desempenho dos nossos modelos, recomendamos evitar alterações no prefixo e, sempre que possível, configurar a integração para acrescentar novos itens apenas ao final do contexto.
O que é uma alteração no prefixo?
O prefixo de um item de raciocínio é o trecho do histórico da conversa que antecede esse item. Você altera o prefixo, por exemplo, quando encurta um resultado de ferramenta nesse trecho, reescreve uma mensagem do desenvolvedor ou substitui turnos anteriores por um resumo.
| Original conversation | Next request and API handling |
|---|---|
| User messageCheck the ledger total. | Same message |
| Reasoning before the tool call | Reusable |
Tool calllookup_ledger() | Same call |
Tool result[{"amount": 40}, {"amount": 50}] | Same rows |
| Reasoning after the tool result | Reusable |
Como atualizar integrações para evitar alterações no prefixo
Você pode alterar o prefixo sem perceber ao atualizar parâmetros da Responses API, como tools, instructions ou text.format, ou ao editar itens anteriores de input. Verifique se a sua integração faz alguma dessas alterações.
A tabela a seguir mostra situações comuns em que uma integração altera o prefixo e como atingir os mesmos objetivos acrescentando itens ao final do contexto, quando possível.
| Motivo para alterar o prefixo | Como evitar a alteração no prefixo |
|---|---|
| Alterar o esforço de raciocínio | Mantenha o parâmetro reasoning.effort da Responses API e acrescente um item configuration_update com o novo esforço de raciocínio ao final da lista de itens de entrada. Preserve a configuração original no nível da solicitação. |
| Alterar os schemas de saídas estruturadas | Mantenha o parâmetro text.format da Responses API e acrescente um item configuration_update com o novo schema ao final da lista de itens de entrada. Preserve a configuração original no nível da solicitação. |
| Alterar as ferramentas disponíveis para o agente | Mantenha o parâmetro tools da Responses API. Use um item additional_tools para adicionar ferramentas ou use tool_choice com allowed_tools para restringir quais ferramentas o modelo pode chamar em um turno. Mantenha as definições de ferramentas existentes na ordem original. Acrescente o item additional_tools ao final, com o papel developer e um array tools. Ao reenviar esse item, mantenha-o na posição original. |
| Atualizar as instruções do desenvolvedor | Mantenha a mensagem original do desenvolvedor e acrescente ao final uma nova mensagem developer pedindo ao modelo que ignore as instruções anteriores e siga as novas instruções que você fornecer. Para instruções que se aplicam a um único turno, coloque um ponto de interrupção explícito do cache imediatamente antes da mensagem mais recente do desenvolvedor. Assim, o prefixo reutilizável termina antes dessa mensagem. |
| Compactar o contexto | A compactação altera o prefixo, por isso é difícil evitar situações em que o cache não encontra uma correspondência. Compactação da OpenAI: Se você usa a compactação da OpenAI via /responses/compact ou context_management, nossos sistemas preservam os itens de raciocínio subsequentes mesmo com a alteração no prefixo. Um item de compactação da OpenAI pode aparecer em qualquer posição do contexto. Ao chamar /responses/compact, omita instructions e envie a janela de contexto retornada na próxima solicitação, mantendo os itens na ordem original. Se o histórico contiver itens configuration_update, siga os requisitos de compactação para atualizações de configuração.Compactação personalizada: Se você usa outra estratégia de compactação, inclusive uma que você mesmo desenvolveu, coloque o item compactado no final do contexto do modelo. Você também pode colocá-lo antes dos turnos recentes se aceitar que a API descarte os itens de raciocínio do histórico original que vêm depois dele. |
| Encurtar saídas de ferramentas ou reduzir o tamanho de arquivos ou imagens já enviados | Algumas integrações truncam itens anteriores, como saídas de ferramentas, arquivos ou imagens, em vez de usar a compactação. Essas modificações alteram o prefixo. Recomendamos enfaticamente que você use a compactação ou que encurte as saídas longas das ferramentas e reduza o tamanho das imagens ou dos arquivos antes de enviá-los ao modelo pela primeira vez. |
Como identificar alterações no prefixo na sua integração
Use o diagnóstico de cache de prompts para identificar quando o cache não encontra uma correspondência e investigar alterações no prefixo. Para comparar uma solicitação com uma resposta anterior, defina prompt_cache_options.comparison_response_id com o ID dessa resposta. Em seguida, verifique o motivo indicado pelo diagnóstico e a contagem de tokens em cache. Use essas informações para reduzir as alterações no prefixo na sua integração. Quando consegue identificar diferenças, o diagnóstico informa a primeira que encontra. Ele não consegue verificar se o modelo reutilizou o raciocínio.