Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Formato della risposta: id, choices e finish_reason

Lezione 8 di 12 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Anatomia di una risposta Chat Completions
  2. Struttura completa della risposta
  3. L’array choices
  4. Valori di finish_reason
  5. Gestione dei diversi casi
  6. Punti chiave

Aggiornato il 3 novembre 2026 in base al riferimento dell’API Chat Completions di xAI: per finish_reason sono documentati solo stop, length e, nello streaming, end_turn o null; i valori tool_calls e content_filter della versione precedente non sono elencati e le chiamate agli strumenti vengono rilevate tramite message.tool_calls. max_tokens è deprecato a favore di max_completion_tokens. Fonte: Chat Completions.

Anatomia di una risposta Chat Completions

Ogni chiamata all’endpoint Chat Completions restituisce un oggetto JSON strutturato con campi standardizzati. Comprendere questa struttura è essenziale per estrarre correttamente i dati, gestire i casi limite ed eseguire il debug delle tue integrazioni.

id
Identificatore univoco
choices
Array di risposte
usage
Contatori di token
system_fingerprint
Impronta digitale del sistema

Struttura completa della risposta

Ecco un esempio di una risposta tipica restituita dall’API:

{
  "id": "chatcmpl-abc123xyz",
  "object": "chat.completion",
  "created": 1712345678,
  "model": "grok-4.20-0309-reasoning",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Deep learning is a branch of machine learning..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 156,
    "total_tokens": 198
  },
  "system_fingerprint": "fp_abc123"
}

Campi di primo livello

  • id: Identificatore univoco per il completamento (formato chatcmpl-...). Utile per il tracciamento e il debug.
  • object: Sempre "chat.completion". Ti permette di distinguere questo tipo di risposta da altri endpoint.
  • created: Timestamp Unix del momento in cui è stata creata la risposta.
  • model: Il modello che ha generato la risposta. Potrebbe differire leggermente dal modello richiesto se utilizzi un alias.
  • choices: Array contenente la risposta o le risposte generate.
  • usage: Contatori di token per la fatturazione.
  • system_fingerprint: Impronta digitale della configurazione di sistema utilizzata.

L’array choices

Il campo choices è un array che solitamente contiene un singolo elemento (indice 0). Ogni elemento contiene:

  • index: Posizione nell’array (inizia da 0)
  • message: Oggetto con role (sempre "assistant") e content (il testo generato)
  • finish_reason: Il motivo per cui la generazione si è interrotta

Per estrarre la risposta testuale:

# Python
response_text = response.choices[0].message.content
// JavaScript
const responseText = response.choices[0].message.content;

Valori di finish_reason

Il campo finish_reason indica perché il modello ha smesso di generare testo:

stop

"finish_reason": "stop"

Il modello ha terminato la sua risposta naturalmente. Questo è il caso più comune e desiderabile: il modello ha detto tutto ciò che doveva dire.

length

"finish_reason": "length"

La generazione si è interrotta perché è stato raggiunto il limite di output: max_completion_tokens, che sostituisce il deprecato max_tokens, e conta solo la risposta visibile. La risposta è quindi troncata: aumenta il limite o riavvia una richiesta di continuazione.

end_turn o null nello streaming

Nello streaming, ogni chunk intermedio riporta "end_turn" o null in finish_reason; solo il chunk finale indica il motivo dell’arresto.

Cosa non documenta il riferimento

Il riferimento API di xAI documenta solo questi valori. Non menziona né content_filter né il valore restituito durante una chiamata a uno strumento: per sapere se il modello richiede uno strumento, controlla la presenza di message.tool_calls piuttosto che il valore di finish_reason.

Gestione dei diversi casi

In produzione, devi controllare finish_reason per adattare il tuo comportamento:

choice = response.choices[0]

if choice.message.tool_calls:
    # Il modello vuole chiamare uno o più strumenti
    for tool_call in choice.message.tool_calls:
        print(f"Tool requested: {tool_call.function.name}")

elif choice.finish_reason == "length":
    # Risposta troncata: notifica l'utente o continua
    print(choice.message.content)
    print("[Risposta troncata: aumenta max_completion_tokens]")

else:
    # Risposta completa
    print(choice.message.content)

Punti chiave

  • La risposta contiene un id univoco, un array choices e un oggetto usage
  • Il testo generato si trova in choices[0].message.content
  • finish_reason indica perché la generazione si è interrotta: il riferimento documenta stop e length (e end_turn o null nello streaming)
  • Controlla finish_reason per individuare risposte troncate e message.tool_calls per le chiamate agli strumenti
  • Il system_fingerprint identifica la configurazione di sistema utilizzata per la generazione