Para ver o índice completo da documentação, consulte llms.txt. Para acessar a versão em Markdown de uma página da documentação, acrescente .md ao final da URL da página.
Navegação principal
Tema

Mantenha o prefixo inalterado

Evite alterar o prefixo para aumentar o reaproveitamento do cache e manter o raciocínio disponível entre turnos.

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.

Alterar o histórico da conversa
Conversa originalPró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 ferramentaReutilizável
Both reasoning items have the same history before them as in the original conversation.

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.