API de Respostas: O Objeto reasoning em Detalhe
Nesta página
O Objeto reasoning na API de Respostas
A API de Respostas da xAI oferece um controlo granular sobre o raciocínio através do objeto reasoning. Este parâmetro está disponível apenas na API de Respostas (não nas Chat Completions) e permite configurar três aspetos do raciocínio: esforço, geração de resumo e formato do resumo.
Estrutura Completa do Objeto reasoning
{
"model": "grok-4.20-0309-reasoning",
"input": "Your question here",
"reasoning": {
"effort": "medium",
"generate_summary": true,
"summary": "auto"
}
}
effort
Controla a profundidade de pensamento do modelo. Existem três valores possíveis:
low: pensamento mínimo, adequado para tarefas simplesmedium: equilíbrio entre profundidade e velocidadehigh: pensamento máximo para problemas complexos
Este parâmetro é o equivalente na API de Respostas ao reasoning_effort nas Chat Completions, mas com um valor adicional medium.
generate_summary
Um booleano que indica se o modelo deve produzir um resumo do seu raciocínio, para além da resposta final.
{
"model": "grok-4.20-0309-reasoning",
"input": "Compare the advantages of quicksort and mergesort.",
"reasoning": {
"effort": "high",
"generate_summary": true
}
}
Quando generate_summary está definido como true, a resposta contém um elemento adicional com um resumo conciso do processo de raciocínio. Este resumo está em texto simples (não encriptado), o que o distingue do reasoning.encrypted_content.
summary
Controla o formato do resumo gerado. Por enquanto, o único valor documentado é "auto", que permite ao modelo escolher o formato mais adequado.
{
"reasoning": {
"effort": "high",
"generate_summary": true,
"summary": "auto"
}
}
Diferença Entre Resumo e Raciocínio Encriptado
Estes dois mecanismos são complementares, mas distintos:
| Aspeto | Resumo (generate_summary) | Encriptado (include) |
|---|---|---|
| Legibilidade | Texto simples, compreensível | Encriptado, opaco |
| Utilização principal | Exibição ao utilizador, auditoria | Reutilização em pedidos subsequentes |
| Ativação | reasoning.generate_summary: true | include: ["reasoning.encrypted_content"] |
| Detalhe | Resumo condensado | Raciocínio completo |
| Disponibilidade | Apenas API de Respostas | Apenas API de Respostas |
Pode ativar ambos simultaneamente para obter tanto um resumo legível como o raciocínio encriptado completo:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Demonstrate the infinitude of prime numbers.",
reasoning={
"effort": "high",
"generate_summary": True,
"summary": "auto"
},
include=["reasoning.encrypted_content"]
)
Combinações Comuns
Utilização Mínima: Apenas Esforço
{
"reasoning": {
"effort": "low"
}
}
O modelo raciocina com esforço mínimo. Não é devolvido nenhum resumo nem raciocínio encriptado.
Utilização Intermédia: Esforço + Resumo
{
"reasoning": {
"effort": "medium",
"generate_summary": true,
"summary": "auto"
}
}
O modelo raciocina e fornece um resumo legível. Ideal para aplicações que pretendem mostrar o processo de pensamento ao utilizador.
Utilização Completa: Esforço + Resumo + Encriptado
{
"reasoning": {
"effort": "high",
"generate_summary": true,
"summary": "auto"
},
"include": ["reasoning.encrypted_content"]
}
Configuração máxima: raciocínio profundo, resumo legível e conteúdo encriptado para reutilização. Reserve esta opção para casos em que necessita de tudo.
Quando Omitir o Objeto reasoning
Se não precisar de controlar o raciocínio, pode simplesmente omitir o parâmetro reasoning. O modelo utilizará as suas definições padrão. Isto permanece válido e o modelo continuará a raciocinar (uma vez que o grok-4.20-0309-reasoning é, por natureza, um modelo de raciocínio).
Pontos-chave
- O objeto
reasoningestá disponível apenas na API de Respostas effortcontrola a profundidade (low,medium,high)generate_summaryproduz um resumo legível do raciocínio (texto simples)summary: "auto"permite ao modelo escolher o formato do resumo- Pode combinar resumo e raciocínio encriptado no mesmo pedido
- Omitir
reasoningé válido: o modelo raciocina com as definições padrão