【Bug已解决】Claude/Sonnet Python API - more tokens freezes, less tokens truncates 解决方案.md一、现象长什么样你用 PythonanthropicSDK 调 Claude/Sonnet观察到这个矛盾与 939 同源但本篇从诊断冻结真因切入max_tokens调大后代码长时间无输出像冻结freezes疑似 hang调小后回答被截断truncates你加了超时冻结变成超时报错但不知道到底是模型慢还是配置错你用print调试发现冻结期间 CPU/网络其实有活动只是没 token 回传你怀疑是 SDK bug但其实是在等一个长生成 没流式 没合理超时。一句话本篇把冻结进一步拆穿——它通常不是 SDK 故障而是① 未用流式导致同步等待整段响应② 没有设客户端超时长生成期间无任何反馈③ 偶尔真的是请求构造有问题如max_tokens超大 模型被要求生成到上限。诊断清楚冻结 vs 真 hang才能对症下药。二、背景max_tokens是生成上限见 939。本篇补充两个诊断维度流式缺失的代价同步client.messages.create要等模型完整生成完才返回。若回答本就长如 2000 token等待数秒到数十秒期间没有任何回调体感冻结。流式则每 token 立即可见。超时缺失的代价若因网络慢或模型异常迟迟不返回且没有timeout配置进程会无限等——这就是真 hang错觉。设了timeout至少能在 N 秒后拿到明确错误区分慢与死。所以诊断清单流式输出在动 在生成慢但活流式也无输出且超时才报错 真问题网络/鉴权/请求构造。三、根因根因是同步等待 无超时 max_tokens不当使长生成被误判为冻结# 既无流式、又无超时 - 长生成期间完全黑屏 client Anthropic(api_keyKEY) # 默认无 timeout client.messages.create(modelclaude-3-5-sonnet-latest, max_tokens8192, # 上限很高 messages[{...}]) # 同步等完整响应 - 冻结感修复方向开流式 设timeout 给合理max_tokens三者缺一不可。四、最小可运行复现import os, time from anthropic import Anthropic KEY os.environ[ANTHROPIC_API_KEY] def diagnose(max_tokens, use_stream, timeout): client Anthropic(api_keyKEY, timeouttimeout) # 显式超时 t0 time.time() if use_stream: # 流式可见逐字能判断在生成 with client.messages.stream(modelclaude-3-5-sonnet-latest, max_tokensmax_tokens, messages[{role: user, content: 写一首关于大海的诗}]) as s: for _ in s.text_stream: pass print(fstream 完成, 用时 {time.time()-t0:.1f}s) else: client.messages.create(modelclaude-3-5-sonnet-latest, max_tokensmax_tokens, messages[{role: user, content: 写一首关于大海的诗}]) print(fsync 完成, 用时 {time.time()-t0:.1f}s) # diagnose(max_tokens64, use_streamFalse, timeout30) # 截断且黑屏等 # diagnose(max_tokens2048, use_streamTrue, timeout60) # 流式可见不冻结运行流式版本你能看到文字逐渐出现确认在生成同步大max_tokens则等较久才有输出。五、解决方案第一层最小直接修复最小修复是流式 超时 合理上限三者并用import os from anthropic import Anthropic client Anthropic( api_keyos.environ[ANTHROPIC_API_KEY], timeout60, # 关键避免无限等待区分慢与死 ) # 合理上限诗约 300 字 - ~200 token给 512 余量不必 8192 with client.messages.stream( modelclaude-3-5-sonnet-latest, max_tokens512, messages[{role: user, content: 写一首关于大海的诗}], ) as stream: for text in stream.text_stream: print(text, end, flushTrue)这样超时能在 60s 后给出明确错误不再是无限冻结流式让生成过程可见合理max_tokens既不截断也不逼迫模型生成到上限。六、解决方案第二层结构化改进把流式 超时 上限做成诊断策略集中管理并能在冻结时自动判定from dataclasses import dataclass, field from typing import Callable, Optional dataclass(frozenTrue) class ClaudeMaxTokensFreezeV2Policy: 冻结诊断策略流式 超时 上限区分慢与死。 规则 - 默认开启流式可见生成 - 设默认超时避免无限冻结 - max_tokens 按任务估算不过分大 default_timeout: float 60.0 default_max_tokens: int 1024 def build_client_kwargs(self) - dict: return {timeout: self.default_timeout} def classify(self, *, streamed: bool, elapsed: float, timeout: float) - str: if not streamed and elapsed timeout: return 可能真 hang同步且无流式且超时被触发 if streamed and elapsed timeout: return 正常流式可见模型在生成 return 观察中 def demo() - None: policy ClaudeMaxTokensFreezeV2Policy() print(client kwargs:, policy.build_client_kwargs()) print(policy.classify(streamedTrue, elapsed3.0, timeout60)) print(policy.classify(streamedFalse, elapsed61, timeout60)) if __name__ __main__: demo()七、解决方案第三层断言 / CI 守护import pytest from your_module import ClaudeMaxTokensFreezeV2Policy def test_client_kwargs_has_timeout(): policy ClaudeMaxTokensFreezeV2Policy() assert policy.build_client_kwargs()[timeout] 60.0 def test_classify_streaming_ok(): policy ClaudeMaxTokensFreezeV2Policy() assert 正常 in policy.classify(streamedTrue, elapsed3, timeout60) def test_classify_hang(): policy ClaudeMaxTokensFreezeV2Policy() assert hang in policy.classify(streamedFalse, elapsed61, timeout60) def test_default_max_tokens_reasonable(): policy ClaudeMaxTokensFreezeV2Policy() assert 0 policy.default_max_tokens 4096 def test_classify_observing(): policy ClaudeMaxTokensFreezeV2Policy() assert policy.classify(streamedTrue, elapsed61, timeout60) 观察中 def test_timeout_configurable(): policy ClaudeMaxTokensFreezeV2Policy(default_timeout30) assert policy.build_client_kwargs()[timeout] 30.0CI 里加一条对长回答任务断言默认开启流式、设有超时、max_tokens 合理避免冻结/截断回归。八、排查清单是否开了流式没流式同步等整段体感必冻结。是否设了timeout没超时则无法区分慢与真死。冻结时流式有输出吗有在生成慢无超时错真问题。max_tokens是否过大逼迫模型生成到上限会拖长。是否把超时报错当 bug它其实在帮你定位网络/鉴权/请求构造。是否用print/日志确认生成在动先诊断再改配置。九、小结Claude/Sonnet Python APImax_tokens 大冻结、小截断本篇从诊断角度拆穿冻结几乎都是未流式 无超时 上限不当导致的长生成等待而非 SDK 故障。最小修复是流式 显式timeout 合理max_tokens三者并用结构化做法是抽成ClaudeMaxTokensFreezeV2Policy集中管理并提供慢 vs 死的分类诊断最后用 pytest 守护默认流式、有超时、上限合理让冻结现象可诊断、可消除。