짧은 답변
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를 명시적으로 보내야 합니다.
핵심 개념
output limit가 너무 작으면 response가 잘릴 수 있습니다. 매우 크게 설정해도 model이 항상 그만큼의 tokens를 생성하는 것은 아니지만 long-output tasks의 cost가 더 커질 수 있습니다.
parameter name 차이
Codex CLI 또는 Responses API based tool을 사용한다면 해당 tool 또는 provider가 currently 지원하는 field를 따르세요. 모든 model에 같은 parameter name을 hard-code하지 마세요.
설정하지 않으면 어떻게 되나요?
behavior는 provider와 API에 따라 다릅니다.
같은 code도 models를 switch하면 output lengths가 달라질 수 있습니다. production에서 unexpected results를 줄이려면 explicit output limit를 설정하세요.
권장 범위
actual maximum은 모델 광장과 upstream model docs에서 확인하세요. Model output limits는 version별로 달라질 수 있습니다.
output이 잘렸을 때 할 일
response에finish_reason: "length"가 있다면 model이 보통 output limit에 도달한 것입니다.
다음 순서로 troubleshoot하세요.
- current API가 지원하는 output limit field를 늘립니다.
- correct parameter name을 사용했는지 확인합니다.
- unnecessary output을 줄이도록 prompt를 더 focused하게 만듭니다.
- larger output window를 가진 model을 사용합니다.
- task를 여러 steps로 나눕니다.
일반적인 실수
- 더 큰
max_tokensvalue가 항상 model의 writing length를 늘린다고 가정함 finish_reason를 확인하지 않고 truncation 후 retry함- reasoning model에 old field name을 사용함
- context와 cost를 estimate할 때 hidden reasoning tokens를 무시함
- model 자체의 maximum output limit를 무시함