BroadRouter

finish_reason(종료 이유)

업데이트

finish_reason은 chat completion 응답의 각 choice에 붙는 필드로, 모델이 생성을 멈춘 이유를 알려 줍니다. OpenAI 형식의 값은 stop, length, tool_calls, content_filter, 그리고 deprecated된 function_call입니다. Anthropic Messages API는 같은 개념을 stop_reason으로 보고합니다.

다른 이름: 종료 이유, 중지 이유, finish reason 뜻, finish_reason length, finish reason, stop reason, stop_reason

완성된 것처럼 보이는 응답이 실제로는 아닐 수 있습니다. 모델이 스스로 끝냈는지 알려 주는 필드는 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를 읽는 것.
  • 추론이 예산을 모두 써서 답변이 비었는데 이를 모델 오류로 취급하는 것.

자주 묻는 질문

finish_reason이 "length"면 무슨 뜻인가요?

응답이 설정한 토큰 한도에 도달해 잘렸다는 뜻입니다. OpenAI는 이를 "the maximum number of tokens specified in the request was reached."(번역: 요청에 지정된 최대 토큰 수에 도달했다)라고 설명합니다. max_tokens를 늘리거나 요청량을 줄이세요. 잘린 텍스트를 고쳐 쓰지는 마세요.

중지 시퀀스를 설정했는데 finish_reason이 "stop"인 이유는 무엇인가요?

OpenAI 형식에서 stop은 자연스러운 종료와 중지 시퀀스 일치를 모두 포함합니다. Anthropic은 이를 end_turn과 stop_sequence로 구분합니다.

BroadNet은 finish_reason 값을 문서화하나요?

아니요. BroadNet API 레퍼런스에는 finish_reason 값 목록이 없습니다. 실제 요청에서 이 필드를 로그로 남기고, 이 값에 따라 분기하기 전에 테스트하세요.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기