Vai al contenuto principale
Italiano— Scegli una lingua
Menu

API Responses: l'oggetto reasoning nel dettaglio

Lezione 7 di 12 Aggiornata il 28 luglio 2026 Sviluppatore
In questa pagina
  1. L’oggetto reasoning nell’API Responses
  2. Struttura completa dell’oggetto reasoning
  3. Differenza tra Riepilogo e Ragionamento Cifrato
  4. Combinazioni comuni
  5. Quando omettere l’oggetto reasoning
  6. Punti chiave

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 semplici
  • medium: 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:

AspettoRiepilogo (generate_summary)Cifrato (include)
LeggibilitàTesto semplice, comprensibileCifrato, opaco
Utilizzo principaleVisualizzazione utente, auditRiutilizzo nelle richieste successive
Attivazionereasoning.generate_summary: trueinclude: ["reasoning.encrypted_content"]
DettaglioRiepilogo condensatoRagionamento completo
DisponibilitàSolo API ResponsesSolo 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.

{
  "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
  • effort controlla la profondità (low, medium, high)
  • generate_summary produce 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