Una risposta che sembra completa potrebbe non esserlo. finish_reason è l’unico campo che ti dice se il modello ha chiuso di sua iniziativa.
Come funziona
Ogni elemento di choices ha un finish_reason. Il riferimento di OpenAI elenca questi valori:
| Valore | Significato (OpenAI) |
|---|---|
stop |
Punto di arresto naturale, oppure è stata raggiunta una sequenza di stop fornita |
length |
“The maximum number of tokens specified in the request was reached” (è stato raggiunto il numero massimo di token indicato nella richiesta) |
tool_calls |
Il modello ha chiamato un tool |
content_filter |
“Content was omitted due to a flag from our content filters” (contenuto omesso per una segnalazione dei filtri dei contenuti) |
function_call |
Forma più vecchia e deprecata di chiamata a funzione |
La Messages API di Anthropic usa stop_reason con valori propri, tra cui end_turn, max_tokens, stop_sequence, tool_use, pause_turn, refusal e model_context_window_exceeded. Quando scatta una sequenza di stop, Anthropic restituisce anche quale in stop_sequence.
choice = r.choices[0]
if choice.finish_reason == "length":
raise RuntimeError("cut off: raise max_tokens and resend")
if choice.finish_reason == "tool_calls":
run_tools(choice.message.tool_calls)
Perché è importante
- JSON troncato. Una risposta
lengthè incompleta. Chiudere le parentesi la rende analizzabile ma perde dati. L’articolo sul JSON non valido tratta questo caso. - Loop degli agenti.
tool_callssignifica “esegui i tool e richiamami”, non “ho finito”. - Cache. Metti in cache solo le risposte terminate con
stop. Una risposta troncata tenuta in cache per una settimana sembra un bug del modello.
Su BroadNet Inference
Il riferimento API di BroadNet non documenta i valori di finish_reason, quindi registra ciò che ricevi prima di farci affidamento. Documenta però la causa principale delle sorprese con length: DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere, e i token di ragionamento contano in max_tokens. BroadNet dice che con un limite basso “the reasoning can use the whole budget and the answer comes back empty” (traduzione: il ragionamento può consumare tutto il budget e la risposta torna vuota). Lascia almeno 1.000 token, oppure imposta reasoning_effort su low. La guida alla risposta vuota spiega passo passo la soluzione.
Errori comuni
- Leggere
message.contentsenza prima controllare finish_reason. - Considerare una risposta vuota un guasto del modello quando il ragionamento ha consumato tutto il budget.