【Bug已解决】Claude/Sonnet Python API - more tokens freezes, less tokens truncates 解决方案一、现象长什么样你用 PythonanthropicSDK调 Claude/Sonnet发现一个矛盾现象把max_tokens设得很大如 4096、8192请求会卡住/冻结freezes——长时间没响应像 hang 住把max_tokens设得很小如 64回答被截断truncates内容不完整你不确定该设多大冻结时程序既不报错也不返回只能等或超时截断时输出到一半就没了没有明显的被截断提示。一句话max_tokens是模型单次最多生成的 token 数——设太小模型没说完就被强行停下截断设太大且未用流式时客户端会一直等模型把额度用满或自然结束长生成期间表现为冻结若再加网络/无超时配置就像 hang 住。二、背景max_tokens不是我要多少就给多少而是上限模型生成到这个上限或自然结束遇到 stop就停。两种极端太小模型内容还没表达完额度耗尽被截断。Sonnet 回答本就可能较长64/128 必然截断太大 非流式模型可能真的生成很多 token 才自然结束尤其开放性提问客户端同步等待整个响应期间没有任何中间输出体感就是冻结。如果同时没设请求超时且模型恰好生成很久看起来就像程序卡死。注意冻结通常不是bug而是你在等一个长生成。用流式stream就能看到逐字输出立刻知道还在跑不会误以为卡住。三、根因根因是对max_tokens语义理解偏差 未用流式导致长生成期间无反馈# 错误 1太小 - 截断 client.messages.create(modelclaude-3-5-sonnet-latest, max_tokens64, messages...) # 错误 2太大 同步等 - 冻结感 client.messages.create(modelclaude-3-5-sonnet-latest, max_tokens8192, messages...) # 模型可能生成几千 token 才停同步客户端一直等 - 像 freeze修复方向设一个合理偏宽松但不过分的max_tokens如 1024~2048并用流式让生成过程可见、可控。四、最小可运行复现import os from anthropic import Anthropic def call_sync(max_tokens: int): client Anthropic(api_keyos.environ[ANTHROPIC_API_KEY]) # 同步等待完整响应max_tokens 大时体感冻结 return client.messages.create( modelclaude-3-5-sonnet-latest, max_tokensmax_tokens, messages[{role: user, content: 写一篇关于秋天的 500 字散文}], ) def call_stream(max_tokens: int): client Anthropic(api_keyos.environ[ANTHROPIC_API_KEY]) # 流式逐块可见不会误以为冻结 with client.messages.stream(modelclaude-3-5-sonnet-latest, max_tokensmax_tokens, messages[{role: user, content: 写一篇关于秋天的散文}]) as stream: for text in stream.text_stream: print(text, end, flushTrue) # 实时输出 print() if __name__ __main__: # call_sync(64) # 截断 # call_stream(2048) # 流式、可见、不冻结 pass运行 streaming 版本你能实时看到文字出现确认没卡住同步大max_tokens则会等较久才有输出体感冻结。五、解决方案第一层最小直接修复最小修复是设合理max_tokens 用流式import os from anthropic import Anthropic client Anthropic(api_keyos.environ[ANTHROPIC_API_KEY]) # 1) 合理上限给足但不夸张Sonnet 一般 1024~4096 够用 MAX 2048 # 2) 用流式生成过程实时可见 with client.messages.stream( modelclaude-3-5-sonnet-latest, max_tokensMAX, messages[{role: user, content: 详细解释一下 X}], ) as stream: for text in stream.text_stream: print(text, end, flushTrue)要点max_tokens设成你预期最长回答的 token 数 余量中文约 1.5 字/token500 字约 750 token永远用流式处理长回答避免等完整响应的冻结感若必须同步配合合理max_tokens与客户端超时。六、解决方案第二层结构化改进把max_tokens取值 流式开关做成策略按任务类型自动选from dataclasses import dataclass, field from typing import Dict, Callable dataclass(frozenTrue) class ClaudeMaxTokensFreezePolicy: max_tokens 策略避免截断与冻结。 规则 - 按任务类型给默认 max_tokens短文/长文/代码 - 长任务默认开启流式 - 提供 估算所需 token 防止过小 presets: Dict[str, int] field(default_factorylambda: { chat: 1024, long_text: 2048, code: 4096, }) def pick(self, task: str) - int: return self.presets.get(task, 1024) def estimate(self, chars: int) - int: # 中文约 1.5 字/token留 1.3 倍余量 return int(chars / 1.5 * 1.3) def should_stream(self, task: str) - bool: return self.pick(task) 2048 def demo() - None: policy ClaudeMaxTokensFreezePolicy() print(长文 max_tokens:, policy.pick(long_text)) # 2048 print(估算 500 字需要:, policy.estimate(500)) # ~433 print(是否流式:, policy.should_stream(long_text)) # True if __name__ __main__: demo()七、解决方案第三层断言 / CI 守护import pytest from your_module import ClaudeMaxTokensFreezePolicy def test_preset_exists(): policy ClaudeMaxTokensFreezePolicy() assert policy.pick(chat) 1024 assert policy.pick(code) 4096 def test_unknown_task_default(): policy ClaudeMaxTokensFreezePolicy() assert policy.pick(weird) 1024 def test_estimate_no_truncate(): policy ClaudeMaxTokensFreezePolicy() # 500 字约需 433 token给的估算应 实际避免截断 assert policy.estimate(500) 400 def test_stream_for_long(): policy ClaudeMaxTokensFreezePolicy() assert policy.should_stream(long_text) is True def test_no_stream_for_chat(): policy ClaudeMaxTokensFreezePolicy() assert policy.should_stream(chat) is False def test_estimate_positive(): policy ClaudeMaxTokensFreezePolicy() assert policy.estimate(100) 0CI 里加一条对所有长回答任务断言默认开启流式、max_tokens 不低于估算值避免截断/冻结回归。八、排查清单max_tokens是否设得太小如 64/128那必然截断调大到任务所需。是否用流式大max_tokens同步等会体感冻结流式可实时看到。是否合理估算回答长度中文约 1.5 字/token给 1.3 倍余量。是否设置了客户端超时避免真卡死无兜底。冻结是长生成中还是真 hang流式能区分有逐字输出在跑。是否把max_tokens当成我要多少给多少它是上限不是目标值。九、小结Claude/Sonnet Python APImax_tokens 大了冻结、小了截断根因是对max_tokens语义理解偏差——它是生成上限太小被截断、太大且同步等待时长生成体感冻结。最小修复是按任务类型设合理max_tokens如长文 2048并改用流式让生成过程实时可见结构化做法是抽成ClaudeMaxTokensFreezePolicy按任务预设上限、估算所需 token、长任务默认流式最后用 pytest 守护长任务流式开启、max_tokens 不低于估算杜绝截断与冻结。