更新于

Anthropic Extended Output 用法与限制

ClaudeAnthropic API技术深度

生成长代码文件、完整报告、批量翻译这类任务，经常撞到 Claude 默认 max_tokens 上限——输出写到一半被截断，还得手动拼接续写。Anthropic 提供的 Extended Output（长输出）能力就是为了解决这个问题：通过 beta header 把单次调用的输出上限抬高到远超默认值。本文讲清楚它的开启方式、限制条件，以及实际生产中该怎么用。

一、Extended Output 解决什么问题

Claude API 的 max_tokens 参数默认上限因模型而异，早期模型普遍在 4096–8192 token 左右，对完整生成一篇长报告、一个中大型代码文件、一份多语言批量翻译结果来说往往不够用。常见的应对办法有两种：

  1. 分段生成再拼接：把任务拆成多轮对话，每轮生成一部分，最后手动/程序化拼接
  2. 续写：输出被截断后，把已有内容作为上下文再问一次”接着写”

这两种办法都能用，但都有代价：分段生成容易在段落衔接处出现风格不一致或重复；续写会额外消耗输入 token（因为要把之前的内容重新传入），拉长总耗时。Extended Output 的思路是直接把单次调用的输出上限抬高，减少对这两种变通方案的依赖。

二、如何开启

Extended Output 是通过在请求头里加 beta 标记来启用的，不是新增的独立接口：

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=64000,
    messages=[{"role": "user", "content": "把这份 300 页 PDF 的要点整理成结构化长文档"}],
    extra_headers={
        "anthropic-beta": "output-128k-2025-02-19"
    }
)

关键点：

  • beta header 的具体值随模型和版本变化，务必以官方文档当前列出的 beta flag 为准，不要生搬硬套旧版本号
  • 加了 header 之后，max_tokens 才允许设置到远超默认值的区间；不加 header 直接传超大 max_tokens 会被拒绝或截断到默认上限
  • 这是一个 beta 能力，意味着接口细节、限制值可能随官方迭代调整，生产环境建议做好降级处理（beta header 失效时自动回退到分段生成）

三、必须搭配流式传输

长输出请求几乎总是需要配合 streaming 使用，原因是：

  • 非流式请求有整体超时限制，生成几万 token 的内容如果一次性等待返回，很容易超时
  • 流式传输可以边生成边落盘/边展示，即使耗时较长也不会因为客户端超时而丢失已生成的内容
with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=64000,
    messages=[{"role": "user", "content": "生成一份完整的技术方案文档"}],
    extra_headers={"anthropic-beta": "output-128k-2025-02-19"},
) as stream:
    with open("output.md", "w", encoding="utf-8") as f:
        for text in stream.text_stream:
            f.write(text)
            f.flush()

注意：即使用了流式传输，网络连接中断依然会导致内容丢失。生成超长内容时，建议边收边写入磁盘（如上例），而不是全部收完再统一处理，这样即使中途断连也能保留已生成的部分。

四、限制与边界情况

限制项说明
上限并非无限即使开启 Extended Output，仍有一个更高但有限的硬上限，具体数值以官方文档为准
计费方式不变输出 token 依然按标准输出单价计费，长输出意味着更高的单次成本
延迟显著增加生成量越大，总耗时越长，需要相应调整客户端超时设置
速率限制交互长输出请求消耗的 token 配额更多，更容易撞到组织级的 TPM（每分钟 token）限速
模型支持范围并非所有模型都支持同样的扩展上限，新旗舰模型通常支持更高的输出上限

组织级速率限制的具体档位和申请提升的方法，可以参考 Anthropic 官方分级限速说明——长输出场景下 TPM 限速比 RPM（每分钟请求数）更容易先被打满，规划配额时要按 token 总量而不是请求次数估算。

五、典型使用场景

场景一：长代码文件一次性生成。生成一个包含完整测试用例的中大型模块，避免因为截断导致语法结构不完整（比如函数定义到一半被切断）。

场景二：批量翻译/改写。把多篇文档合并成一次请求，让模型在同一个上下文里保持术语和风格一致，比逐篇分别调用效果更连贯。

场景三：长报告/文档生成。技术方案、研究报告、产品需求文档这类天然需要几千到上万字的输出，用 Extended Output 可以避免手动拼接多轮生成结果。

不适合的场景：如果任务本身输出量不大（比如问答、摘要、短代码片段），没必要开启 Extended Output，标准 max_tokens 已经够用，开启额外 beta header 除了增加一次配置复杂度之外没有收益。

六、成本估算示例

以 Claude Sonnet 5 为例（价格为近似值，实际以官方定价页为准）：

标准输出单价：约 $15 / 1M output tokens

生成一份 6 万 token 的完整技术文档：
60000 tokens × $15 / 1,000,000 = 约 $0.9 / 次

对比分 8 轮、每轮续写生成同等内容：
- 每轮都要重新传入之前生成的内容作为上下文
- 假设平均每轮重传 3 万 token 输入
- 额外输入成本：8 × 30000 tokens × $3/1M ≈ $0.72

可以看到，续写方案的额外输入成本几乎抵消了一次性长输出节省下来的复杂度收益。对于确实需要超长输出的场景，Extended Output 通常比”多轮续写拼接”更划算，也更省心。

七、生产环境的实践建议

  1. 设置合理的客户端超时：长输出请求耗时可能是普通请求的数十倍，超时时间要按预估 token 量动态调整，而不是用固定的短超时
  2. 边生成边持久化：流式接收内容时立刻写入存储，不要等全部生成完再处理，防止中途异常导致全部丢失
  3. 监控实际输出量：记录每次调用的 output_tokens，用于成本核算和判断是否真的需要 Extended Output（如果实际输出远小于预期，可能不需要开启）
  4. beta header 做降级兜底：beta 能力随时可能变化，代码里对 beta 请求失败做好 fallback 到标准分段生成的逻辑

八、相关阅读

需要在国内稳定调用 Claude 的 Extended Output 能力时，网络链路的稳定性直接影响长时间流式连接是否会中途断开，YoTradeApi 提供优化过的国内直连线路和 OpenAI 兼容格式，长输出场景下的连接稳定性经过实测验证。

相关阅读