BroadRouter
Inizia

finish_reason

Aggiornato

finish_reason è un campo di ogni choice nella risposta di una chat completion che dice perché il modello ha smesso di generare. Nel formato OpenAI i valori sono stop, length, tool_calls, content_filter e il deprecato function_call. La Messages API di Anthropic riporta la stessa informazione come stop_reason.

Detto anche: motivo di fine, motivo di arresto, finish reason, stop reason, stop_reason

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_calls significa “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.content senza prima controllare finish_reason.
  • Considerare una risposta vuota un guasto del modello quando il ragionamento ha consumato tutto il budget.

Domande frequenti

Cosa significa finish_reason "length"?

La risposta ha raggiunto il limite di token che hai impostato ed è stata troncata. OpenAI lo descrive come "the maximum number of tokens specified in the request was reached" (è stato raggiunto il numero massimo di token indicato nella richiesta). Alza max_tokens o chiedi meno; non riparare il testo troncato.

Perché finish_reason è "stop" quando imposto una sequenza di stop?

Nel formato OpenAI, stop copre sia una fine naturale sia una sequenza di stop trovata. Anthropic le separa in end_turn e stop_sequence.

BroadNet documenta i valori di finish_reason?

No. Il riferimento API di BroadNet non elenca i valori di finish_reason. Registra il campo nelle tue richieste e fai delle prove prima di basarci la logica.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity