Em aplicativos com agentes de IA e em aplicativos com vários turnos, nossos modelos funcionam melhor quando o raciocínio é preservado entre solicitações à API. Para isso, acrescente sempre as novas ações e instruções ao final do contexto do modelo. Manter o prefixo intacto já é uma prática recomendada há tempos para o cache de prompts. O cache compara as solicitações desde o início. Uma alteração no prefixo pode impedir o reaproveitamento do cache a partir do ponto em que ela ocorre. Ao acrescentar as mudanças ao final, você permite que uma parte maior da conversa seja reaproveitada do cache, o que pode reduzir consideravelmente 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 de uma alteração no prefixo como parte das nossas medidas de proteção. Quando isso acontece, 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 saída também poderá 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 as mudanças apenas ao final do contexto.
O que é uma alteração no prefixo?
O prefixo de um item de raciocínio é o histórico da conversa que vem antes dele. Uma alteração no prefixo modifica esse histórico. Isso acontece, por exemplo, ao encurtar o resultado de uma ferramenta, reescrever uma mensagem de desenvolvedor ou substituir turnos anteriores por um resumo.
| Conversa original | Próxima solicitação e como a API a processa |
|---|---|
| Mensagem do usuárioConfira o total do livro-razão. | Mesma mensagem |
| Raciocínio antes da chamada da ferramenta | Reutilizável |
Chamada da ferramentalookup_ledger() | Mesma chamada |
Resultado da ferramenta[{"amount": 40}, {"amount": 50}] | Mesmas linhas |
| Raciocínio após o resultado da ferramenta | Reutilizável |
Como atualizar integrações para evitar alterações no prefixo
Você pode alterar o prefixo sem querer ao atualizar parâmetros da API Responses, como tools ou text.format, ao modificar instructions em modelos anteriores ao GPT-6.2 ou ao editar itens anteriores de input. Audite sua integração para identificar essas alterações.
A tabela a seguir mostra como as integrações costumam alterar o prefixo e como alcançar os mesmos objetivos acrescentando itens ao final do contexto, quando possível.
| Motivo comum para alterar o prefixo | Como evitar alterações no prefixo |
|---|---|
| Alterar o esforço de raciocínio | Mantenha o parâmetro reasoning.effort da API Responses com o valor original da solicitação. Acrescente um item configuration_update com o novo esforço de raciocínio ao final da lista de itens de entrada. |
| Alterar schemas de saídas estruturadas | Mantenha o parâmetro text.format da API Responses com o valor original da solicitação. Acrescente um item configuration_update com o novo schema ao final da lista de itens de entrada. |
| Alterar as ferramentas disponíveis para o agente | Mantenha o parâmetro tools da API Responses com o valor original. Use um item additional_tools para adicionar ferramentas ou use tool_choice com allowed_tools para restringir as ferramentas que o modelo pode chamar em um turno. Preserve a ordem das definições das ferramentas existentes. Acrescente o item additional_tools ao final com a função developer e um array tools. Nas solicitações seguintes, reenvie o item na posição original. |
| Atualizar as instruções do desenvolvedor | Coloque as instruções reutilizáveis na primeira mensagem developer de input. Para atualizar essas instruções, acrescente uma nova mensagem developer ao final do contexto do modelo, sem alterar a mensagem inicial do desenvolvedor.A partir do GPT-6.2, use o parâmetro instructions no nível superior da solicitação para mensagens do desenvolvedor que se aplicam a um único turno. A API acrescenta essas mensagens após input e cobra pelos tokens dessas mensagens a tarifa de entrada sem cache. |
| Compactação | A compactação altera o prefixo, por isso é difícil evitar falhas de cache nesses casos. Compactação da OpenAI. Se você usar a compactação da OpenAI via /responses/compact ou context_management, nossos sistemas preservarão os itens de raciocínio que vêm depois da alteração no prefixo. Um item de compactação da OpenAI pode aparecer em qualquer posição no contexto. Ao chamar /responses/compact, omita instructions e passe a janela retornada para a próxima solicitação na ordem original. O mecanismo context_management mantém as atualizações de configuração e as ferramentas adicionadas pelo desenvolvedor. Se você fizer a compactação explícita, restaure esses itens na próxima solicitação.Compactação personalizada. Se você usar outra estratégia de compactação, inclusive uma desenvolvida por você, coloque o item compactado ao final do contexto do modelo, depois dos turnos recentes. Se optar por colocá-lo antes dos turnos recentes, considere que os itens de raciocínio posteriores a ele no histórico original serão descartados. |
| Encurtar saídas anteriores 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, sem usar a compactação. Essas modificações alteram o prefixo. Recomendamos enfaticamente usar a compactação ou encurtar as saídas longas de ferramentas e reduzir o tamanho de imagens ou arquivos antes de enviá-los ao modelo pela primeira vez. |
Como auditar sua integração para identificar alterações no prefixo
Use os diagnósticos do cache de prompts para identificar quando ocorrem falhas de cache 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 da resposta anterior e verifique o motivo indicado no diagnóstico e a quantidade de tokens em cache. Use essas informações para reduzir as alterações no prefixo na sua integração. Os diagnósticos informam a primeira diferença que conseguirem identificar. Eles não conseguem verificar se o modelo reaproveitou o raciocínio.
Use input_transformations na resposta da API Responses para verificar quais itens de raciocínio a API removeu da entrada e por quê. Para investigar a remoção de um item de raciocínio pelo motivo prefix_mismatch, procure o item com o mesmo id no campo output de uma resposta anterior. Se a sua integração tiver modificado uma entrada anterior, aplique as mudanças recomendadas acima para preservar o raciocínio.