모델 호출

max_tokens의 역할과 기본 동작

max_tokens, max_completion_tokens, max_output_tokens의 의미와 모델 호출 시 출력 token limit를 설정하는 방법을 알아보세요.

짧은 답변

max_tokens는 model이 한 response에서 생성할 수 있는 tokens 수를 제한합니다. API와 model마다 field name, required settings, default behavior가 다릅니다.

stable output을 위해 long answers, code generation, documentation tasks에는 explicit output limit를 설정하세요. Claude / Anthropic-compatible API calls에서는 보통 max_tokens를 명시적으로 보내야 합니다.

핵심 개념

개념	의미
Input tokens	messages, context, file content, tool results 및 기타 input
Output tokens	model이 생성하는 visible response
Reasoning tokens	일부 reasoning models가 internally 사용하는 hidden reasoning tokens
Context window	input, output 및 일부 internal tokens가 함께 사용하는 limit
Output limit	한 response에서 생성되는 maximum visible output

output limit가 너무 작으면 response가 잘릴 수 있습니다. 매우 크게 설정해도 model이 항상 그만큼의 tokens를 생성하는 것은 아니지만 long-output tasks의 cost가 더 커질 수 있습니다.

parameter name 차이

Parameter	일반적인 use case
`max_tokens`	Claude / Anthropic Messages API 및 일부 Chat Completions setups
`max_completion_tokens`	Chat Completions를 통한 일부 OpenAI reasoning models
`max_output_tokens`	OpenAI Responses API의 일반적인 output limit field

Codex CLI 또는 Responses API based tool을 사용한다면 해당 tool 또는 provider가 currently 지원하는 field를 따르세요. 모든 model에 같은 parameter name을 hard-code하지 마세요.

설정하지 않으면 어떻게 되나요?

behavior는 provider와 API에 따라 다릅니다.

상황	가능한 결과
Claude / Anthropic-compatible API	explicit `max_tokens` value가 필요할 수 있음
OpenAI-compatible Chat Completions	model의 default behavior를 사용할 수 있음
OpenAI Responses API	`max_output_tokens` 또는 tool의 default를 사용할 수 있음
Other models	자체 default output limits가 있을 수 있음

같은 code도 models를 switch하면 output lengths가 달라질 수 있습니다. production에서 unexpected results를 줄이려면 explicit output limit를 설정하세요.

권장 범위

Task	권장 범위
General Q&A	`1024` - `4096`
Code explanation / small edits	`4096` - `8192`
Long-form writing / complex coding tasks	model limit에 따라 `8192` 이상
Batch tasks	unexpectedly long responses를 피하려면 smaller limit 사용