BroadRouter

max_tokens(최대 출력 토큰)

업데이트

max_tokens는 모델이 응답 하나에서 생성할 수 있는 최대 토큰 수를 정하는 LLM API 파라미터입니다. 생성이 이 한도에 닿으면 멈추고, 응답에는 잘렸다는 표시가 붙습니다. 예를 들어 finish_reason이 "length"로 설정됩니다.

다른 이름: 최대 토큰, 최대 출력 토큰, 출력 토큰 한도, 출력 길이 제한, max_completion_tokens, max_output_tokens, output token limit, maximum output length

max_tokens는 응답 한 번의 출력 예산입니다. 끝없이 길어지는 답변을 막아 주지만, 너무 낮게 잡으면 답이 잘리거나 아무것도 돌아오지 않습니다.

작동 방식

모델은 토큰을 하나씩 생성합니다. 개수가 max_tokens에 닿으면 문장 중간이라도 생성이 멈춥니다. 그러면 응답에 끝난 이유가 표시됩니다.

finish_reason 의미
stop 모델이 스스로 답을 마침
length max_tokens 한도에 도달함
tool_calls 모델이 도구 호출을 요청함

이 파라미터에는 이름이 여럿 있습니다. OpenAI Chat Completions API는 이제 max_tokens를 deprecated로 표시하고 max_completion_tokens를 쓰도록 하는데, 이 값은 보이는 출력과 추론 토큰을 모두 포함하는 상한입니다. OpenAI Responses API는 max_output_tokens를 씁니다. Anthropic Messages API는 max_tokens를 씁니다. 많은 OpenAI 호환 제공업체는 max_tokens를 받습니다.

프롬프트와 출력은 하나의 컨텍스트 윈도우를 함께 씁니다. 윈도우가 32,768토큰이고 프롬프트가 30,000토큰이면, max_tokens를 얼마로 정하든 돌아올 수 있는 출력은 최대 2,768토큰입니다.

왜 중요한가

  • 비용 관리. 토큰당 과금 키에서 max_tokens는 응답 하나의 출력 비용 상한입니다.
  • 빈 답변. 추론 모델에서는 생각하는 과정도 같은 예산에서 나갑니다. 한도가 100이면 전부 추론 토큰에 쓰여, 보이는 답변은 비어 있고 finish_reason은 length가 될 수 있습니다.
  • 깨진 JSON. 잘린 응답은 구조화된 출력을 불완전하고 파싱할 수 없는 상태로 남깁니다. 파싱하기 전에 finish_reason을 확인하세요.

BroadNet Inference에서는

DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B는 답하기 전에 추론하며, BroadNet 문서에 따르면 추론도 max_tokens에 포함됩니다. 1,000토큰 이상을 주거나, 설정하지 않거나, reasoning_effort를 낮추세요.

response = client.chat.completions.create(
    model="broadnet/glm-5.3",
    max_tokens=2000,
    messages=[{"role": "user", "content": "Summarize this contract clause."}],
)
if response.choices[0].finish_reason == "length":
    print("Cut off: raise max_tokens or lower reasoning_effort")

위 코드는 응답이 잘렸으면 max_tokens를 늘리거나 reasoning_effort를 낮추라는 메시지를 출력합니다.

컨텍스트 크기는 모델마다 다릅니다. DeepSeek V4.1 Flash와 GLM 5.3은 1,048,576토큰, Qwen3.8 27B는 262,144토큰, BroadNet Gemma 4 VL 26B는 32,768토큰입니다. 모델 페이지와 추론 모델이 빈 답변을 반환하는 이유를 참고하세요.

흔한 실수

  • 마이그레이션하면서 추론하지 않는 모델에 쓰던 작은 한도를 그대로 복사하는 것. 마이그레이션 체크리스트를 참고하세요.
  • length를 성공으로 처리하는 것. 로그에 남기고 여유를 늘려 재시도하세요.

자주 묻는 질문

max_tokens와 컨텍스트 윈도우는 같은 건가요?

아닙니다. 컨텍스트 윈도우는 모델이 다룰 수 있는 전체 분량으로, 프롬프트와 출력을 합친 것입니다. max_tokens는 출력만 제한하며, 프롬프트와 max_tokens를 더한 값도 여전히 윈도우 안에 들어가야 합니다.

max_tokens는 항상 설정해야 하나요?

비용이나 길이에 확실한 상한이 필요할 때 설정하세요. 추론 모델에는 여유를 넉넉히 주거나, 제공업체의 기본값이 충분히 크다면 설정하지 않아도 됩니다.

max_tokens와 max_completion_tokens는 어떻게 다른가요?

OpenAI는 Chat Completions에서 max_tokens를 deprecated로 지정하고, 추론 토큰을 명시적으로 포함하는 max_completion_tokens를 쓰도록 했습니다. 많은 OpenAI 호환 제공업체는 여전히 max_tokens를 받습니다.

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