完結しているように見える応答が、本当に完結しているとは限りません。finish_reason は、モデルが自分の意思で書き終えたかどうかを教えてくれる唯一のフィールドです。
しくみ
choices の各要素には finish_reason が付きます。OpenAI のリファレンスには次の値が載っています。
| 値 | 意味(OpenAI) |
|---|---|
stop |
自然な停止点、または指定した停止シーケンスに一致 |
length |
「The maximum number of tokens specified in the request was reached」(訳:リクエストで指定した最大トークン数に達した) |
tool_calls |
モデルがツールを呼び出した |
content_filter |
「Content was omitted due to a flag from our content filters」(訳:コンテンツフィルターのフラグによりコンテンツが省略された) |
function_call |
旧式で非推奨の関数呼び出し |
Anthropic の Messages API は stop_reason を使い、end_turn、max_tokens、stop_sequence、tool_use、pause_turn、refusal、model_context_window_exceeded などの独自の値を返します。停止シーケンスで止まった場合は、どのシーケンスだったかも 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)
なぜ重要か
- 途中で切れた JSON。
lengthの応答は不完全です。括弧を閉じればパースは通りますが、データは失われています。不正な JSON の記事で詳しく扱っています。 - エージェントのループ。
tool_callsは「ツールを実行してからもう一度呼んで」という意味で、「完了」ではありません。 - キャッシュ。 キャッシュするのは
stopで終わった応答だけにしてください。途中で切れた回答を 1 週間キャッシュすると、モデルのバグのように見えます。
BroadNet Inference の場合
BroadNet の API リファレンスには finish_reason の値が記載されていないので、頼る前に実際に返ってくる値をログに残してください。一方で、length が予想外に出る主な原因は記載されています。DeepSeek V4.1 Flash、GLM 5.3、Qwen3.8 27B は回答の前に推論し、その推論トークンは max_tokens に含まれます。BroadNet によると、上限が小さいと「the reasoning can use the whole budget and the answer comes back empty.」(訳:推論が予算をすべて使い切り、回答が空で返ってくることがある)とのことです。1,000 トークン以上の余裕を持たせるか、reasoning_effort を low に設定してください。空の応答ガイドで対処法を順に説明しています。
よくある間違い
- finish_reason を確認せずに
message.contentを読むこと。 - 推論が予算を使い切っただけなのに、空の回答をモデルの不具合と見なすこと。