완성된 것처럼 보이는 응답이 실제로는 아닐 수 있습니다. 모델이 스스로 끝냈는지 알려 주는 필드는 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 |
예전 방식이며 deprecated된 함수 호출 형태 |
Anthropic Messages API는 stop_reason을 쓰며 자체 값이 있습니다. end_turn, max_tokens, stop_sequence, tool_use, pause_turn, refusal, model_context_window_exceeded 등입니다. 중지 시퀀스가 작동하면 Anthropic은 어떤 시퀀스였는지도 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으로 끝난 응답만 캐시하세요. 잘린 답변이 일주일 동안 캐시되면 모델 버그처럼 보입니다.
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를 읽는 것. - 추론이 예산을 모두 써서 답변이 비었는데 이를 모델 오류로 취급하는 것.