简短答案
max_tokens 用来限制模型单次最多输出多少 token。不同 API 和模型对这个字段的名称、必填要求和默认行为不同。
为了获得稳定输出，建议在长回复、代码生成、文档生成等任务中显式设置输出上限。对于 Claude / Anthropic-compatible API，通常需要显式传入 max_tokens。
核心概念
| 概念 | 说明 |
|---|---|
| Input tokens | 你的消息、上下文、文件内容、工具结果等输入 |
| Output tokens | 模型生成的可见回复 |
| Reasoning tokens | 部分推理模型内部使用的隐藏推理 token |
| Context window | 输入、输出和部分内部 token 可共同占用的上下文窗口 |
| Output limit | 单次响应最多生成多少输出 token |
max_tokens 设置得太小，回复可能被截断。设置得很大，不代表模型一定会输出那么多内容，但可能让长输出任务消耗更多费用。
不同参数名
| 参数 | 常见场景 |
|---|---|
max_tokens | Claude / Anthropic Messages API，以及部分 Chat Completions 场景 |
max_completion_tokens | 部分 OpenAI 推理模型的 Chat Completions 参数 |
max_output_tokens | OpenAI Responses API 常见输出上限字段 |
不设置会怎样
不同厂商和 API 的行为不完全一样：| 场景 | 可能结果 |
|---|---|
| Claude / Anthropic-compatible API | 可能要求显式设置 max_tokens |
| OpenAI-compatible Chat Completions | 可能使用模型默认行为 |
| OpenAI Responses API | 可能使用 max_output_tokens 或工具默认值 |
| 其他模型 | 可能有自己的默认输出上限 |
推荐设置
| 任务 | 建议范围 |
|---|---|
| 普通问答 | 1024 - 4096 |
| 代码解释 / 小型修改 | 4096 - 8192 |
| 长文生成 / 复杂代码任务 | 8192 以上，按模型上限调整 |
| 批量任务 | 尽量设置较小上限，避免单条请求意外生成过长 |
输出被截断怎么办
如果响应里出现finish_reason: "length"，通常表示模型达到输出上限。
可以按这个顺序排查：
- 提高当前 API 支持的输出上限字段。
- 检查是否使用了正确的参数名。
- 让 prompt 更聚焦，减少不必要的输出。
- 换用支持更大输出窗口的模型。
- 把长任务拆成多个步骤。
常见误区
- 以为
max_tokens越大，模型就一定输出越长。 - 输出被截断后只重试，不检查
finish_reason。 - 对推理模型仍使用旧字段名。
- 忽略 hidden reasoning tokens 对上下文和成本的影响。
- 不看模型自身最大输出上限。