Uma resposta que parece completa pode não estar. O finish_reason é o único campo que diz se o modelo terminou por conta própria.
Como funciona
Cada item de choices traz um finish_reason. A referência da OpenAI lista estes valores:
| Valor | Significado (OpenAI) |
|---|---|
stop |
Ponto de parada natural, ou uma sequência de parada fornecida foi encontrada |
length |
“The maximum number of tokens specified in the request was reached” (o número máximo de tokens especificado na requisição foi atingido) |
tool_calls |
O modelo chamou uma tool |
content_filter |
“Content was omitted due to a flag from our content filters” (conteúdo omitido por um alerta dos filtros de conteúdo) |
function_call |
Forma antiga e obsoleta de chamada de função |
A Messages API da Anthropic usa stop_reason com valores próprios, entre eles end_turn, max_tokens, stop_sequence, tool_use, pause_turn, refusal e model_context_window_exceeded. Quando uma sequência de parada é acionada, a Anthropic também informa qual foi em 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)
Por que isso importa
- JSON truncado. Uma resposta
lengthestá incompleta. Fechar as chaves faz o parsing funcionar, mas perde dados. O post sobre JSON inválido trata disso. - Loops de agentes.
tool_callssignifica “execute as tools e me chame de novo”, não “terminei”. - Cache. Só guarde em cache respostas que terminaram com
stop. Uma resposta cortada guardada em cache por uma semana parece um bug do modelo.
Na BroadNet Inference
A referência da API da BroadNet não documenta os valores de finish_reason, então registre o que você recebe antes de depender deles. Ela documenta, porém, a principal causa das surpresas com length: DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B raciocinam antes de responder, e os tokens de raciocínio contam para max_tokens. A BroadNet diz que, com um limite pequeno, “the reasoning can use the whole budget and the answer comes back empty” (tradução: o raciocínio pode usar todo o orçamento e a resposta volta vazia). Deixe 1.000 tokens ou mais, ou defina reasoning_effort como low. O guia de resposta vazia mostra a correção passo a passo.
Erros comuns
- Ler
message.contentsem conferir o finish_reason antes. - Tratar uma resposta vazia como falha do modelo quando o raciocínio usou todo o orçamento.