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를 성공으로 처리하는 것. 로그에 남기고 여유를 늘려 재시도하세요.