API Responses: l'oggetto reasoning nel dettaglio
In questa pagina
L’oggetto reasoning nell’API Responses
L’API Responses di xAI offre un controllo granulare sul ragionamento tramite l’oggetto reasoning. Questo parametro è disponibile esclusivamente nell’API Responses (non nelle Chat Completions) e ti permette di configurare tre aspetti del ragionamento: lo sforzo, la generazione di un riepilogo e il formato di tale riepilogo.
Struttura completa dell’oggetto reasoning
{
"model": "grok-4.20-0309-reasoning",
"input": "Your question here",
"reasoning": {
"effort": "medium",
"generate_summary": true,
"summary": "auto"
}
}
effort
Controlla la profondità di pensiero del modello. Sono possibili tre valori:
low: pensiero minimo, adatto a compiti semplicimedium: equilibrio tra profondità e velocitàhigh: pensiero massimo per problemi complessi
Questo parametro è l’equivalente nell’API Responses di reasoning_effort nelle Chat Completions, ma con l’aggiunta del valore medium.
generate_summary
Un booleano che indica se il modello deve produrre un riepilogo del suo ragionamento oltre alla risposta finale.
{
"model": "grok-4.20-0309-reasoning",
"input": "Compare the advantages of quicksort and mergesort.",
"reasoning": {
"effort": "high",
"generate_summary": true
}
}
Quando generate_summary è impostato su true, la risposta contiene un elemento aggiuntivo con un riepilogo conciso del processo di ragionamento. Questo riepilogo è in testo semplice (non cifrato), il che lo distingue da reasoning.encrypted_content.
summary
Controlla il formato del riepilogo generato. Al momento, l’unico valore documentato è "auto", che lascia al modello la scelta del formato più appropriato.
{
"reasoning": {
"effort": "high",
"generate_summary": true,
"summary": "auto"
}
}
Differenza tra Riepilogo e Ragionamento Cifrato
Questi due meccanismi sono complementari ma distinti:
| Aspetto | Riepilogo (generate_summary) | Cifrato (include) |
|---|---|---|
| Leggibilità | Testo semplice, comprensibile | Cifrato, opaco |
| Utilizzo principale | Visualizzazione utente, audit | Riutilizzo nelle richieste successive |
| Attivazione | reasoning.generate_summary: true | include: ["reasoning.encrypted_content"] |
| Dettaglio | Riepilogo condensato | Ragionamento completo |
| Disponibilità | Solo API Responses | Solo API Responses |
Puoi abilitarli entrambi simultaneamente per ottenere sia un riepilogo leggibile sia il ragionamento cifrato 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"]
)
Combinazioni comuni
Utilizzo minimo: solo Effort
{
"reasoning": {
"effort": "low"
}
}
Il modello ragiona con il minimo sforzo. Nessun riepilogo, nessun ragionamento cifrato restituito.
Utilizzo intermedio: Effort + Riepilogo
{
"reasoning": {
"effort": "medium",
"generate_summary": true,
"summary": "auto"
}
}
Il modello ragiona e fornisce un riepilogo leggibile. Ideale per le applicazioni che vogliono mostrare il processo di pensiero all’utente.
Utilizzo completo: Effort + Riepilogo + Cifrato
{
"reasoning": {
"effort": "high",
"generate_summary": true,
"summary": "auto"
},
"include": ["reasoning.encrypted_content"]
}
Configurazione massima: ragionamento profondo, riepilogo leggibile e contenuto cifrato per il riutilizzo. Riserva questa opzione ai casi in cui hai bisogno di tutto.
Quando omettere l’oggetto reasoning
Se non hai bisogno di controllare il ragionamento, puoi semplicemente omettere il parametro reasoning. Il modello utilizzerà le sue impostazioni predefinite. Questo rimane valido e il modello continuerà a ragionare (poiché grok-4.20-0309-reasoning è per sua natura un modello di ragionamento).
Punti chiave
- L’oggetto
reasoningè disponibile solo nell’API Responses effortcontrolla la profondità (low,medium,high)generate_summaryproduce un riepilogo leggibile del ragionamento (testo semplice)summary: "auto"lascia al modello la scelta del formato del riepilogo- Puoi combinare riepilogo e ragionamento cifrato nella stessa richiesta
- Omettere
reasoningè valido: il modello ragiona con le impostazioni predefinite