Anthropic Python SDK 1.0 迁移指南：升级 httpx2

Anthropic 正式发布了 Python SDK 1.0，这是该库的一次重大版本跃迁。核心变化包括底层 HTTP 客户端从 httpx 切换为 httpx2、最低 Python 版本提升至 3.10，以及移除 temperature 参数和 Text Completions 接口。对于正在使用 Anthropic API 构建应用的开发者来说，这次升级既带来性能与类型安全上的收益，也意味着需要主动调整现有代码。

为什么要关注这次升级

SDK 1.0 并不是一次简单的版本号跳动。httpx2 的引入替换了原有的网络请求层，官方给出的理由是更好的异步支持与连接管理。另一边，Python 3.10+ 的要求让 SDK 可以使用更现代的类型标注和语法特性。代价是旧项目若仍停留在 Python 3.9 或更早版本，必须先升级运行环境。

另一个需要正视的破坏性变更是 Text Completions 接口被移除。Anthropic 已将对话能力全面收敛到 Messages API，旧的文本补全端点不再受支持。同时 temperature 参数也被删除，这意味着依赖该参数调节输出随机性的调用需要重新设计提示词策略。

Messages API 与 Text Completions 的区别

Text Completions 是 Anthropic 早期提供的文本补全接口，接受单段 prompt 并返回续写内容，类似于传统的语言模型调用方式。Messages API 则是为对话场景设计的接口，请求体由 system 提示和 messages 数组构成，每条消息包含 role（user 或 assistant）与 content。这种结构天然支持多轮对话、系统提示分离以及工具调用等高级能力。Anthropic 将对话能力收敛到 Messages API，意味着开发者需要将旧的单段 prompt 拆解为系统指令与用户消息，并考虑是否需要保留 assistant 轮次来引导模型行为。

temperature 参数的作用与移除背景

temperature 是控制模型输出随机性的采样参数，值越低输出越确定，值越高越多样。许多团队用它来稳定摘要、分类等任务。Anthropic 移除该参数，可能与模型本身的对齐策略和输出稳定性优化有关，引导开发者通过提示词工程（如明确指令、few-shot 示例、输出格式约束）来控制输出方差，而非依赖采样参数。

迁移前的环境检查

在改动任何代码之前，先确认三件事：Python 版本是否达到 3.10、项目是否直接或间接依赖 httpx 的旧版本、以及是否有代码调用了 Text Completions。

可以通过 python --version 快速核对解释器版本。对于依赖树，建议使用 pip list | grep httpx 或 pipdeptree 检查是否存在版本冲突。如果项目中其他库锁定了旧版 httpx，升级 Anthropic SDK 可能引发依赖解析失败，需要在虚拟环境中单独验证。

依赖与客户端的替换步骤

升级 SDK 本身只需一条命令，但真正的工作在于替换直接引用。首先执行 pip install --upgrade anthropic，将包更新到 1.0 版本。随后在代码中检索所有 import httpx 的调用点——如果这些调用是为了给 Anthropic 客户端配置超时、代理或自定义传输层，需要改为使用 httpx2 对应的接口。

Anthropic 客户端本身的构造方式保持了较高的一致性，但底层 transport 的类型已经改变。自定义 http_client 的场景是迁移中最容易出问题的地方，建议对照官方迁移文档逐项核对参数名称与类型签名。

httpx 与 httpx2 的关系

httpx 是 Python 生态中广泛使用的同步/异步 HTTP 客户端，支持 HTTP/2、连接池和自定义传输层。httpx2 是其后续演进版本，在异步支持、连接管理和类型标注上有所改进。Anthropic SDK 1.0 将底层网络层切换到 httpx2，意味着自定义 http_client 时传入的 transport 类型、超时配置和代理设置需要对应 httpx2 的接口。如果项目中其他库仍锁定旧版 httpx，可能出现两个包共存或依赖解析冲突，建议在虚拟环境中单独验证。

移除 temperature 与 Text Completions 的影响

temperature 的移除影响面比想象中更广。许多团队在生成摘要、分类或结构化输出时会调低 temperature 以获得更稳定的结果。SDK 不再接受该参数后，这类控制需要转移到提示词层面，例如通过更明确的指令、few-shot 示例或输出格式约束来降低方差。

Text Completions 的移除则要求将旧调用整体改写为 Messages API。两者在消息结构上有本质差异：前者是单段 prompt 补全，后者基于 role/content 的消息列表。迁移时不要把旧 prompt 直接塞进单条 user 消息了事，而应重新设计系统提示与对话结构的划分。

升级后的验证清单

完成代码修改后，建议按以下顺序验证：先在隔离环境跑通单元测试，重点覆盖所有发起 API 请求的路径；再检查超时与重试逻辑是否仍然生效，因为 httpx2 的默认行为可能与旧版不同；最后在预发布环境用小流量请求验证真实响应，确认没有因参数移除而静默降级。

对于生产系统，建议保留旧版本 SDK 的回滚路径，直到新版本稳定运行一段时间。版本锁定文件应当明确记录 anthropic 的版本号，避免 CI 环境出现不一致。

超时与重试逻辑的变化

httpx2 的默认超时行为和重试策略可能与旧版 httpx 不同。例如连接超时、读取超时的默认值可能调整，自动重试的条件也可能变化。升级后应显式检查客户端构造时的 timeout 参数是否仍然生效，以及自定义重试逻辑是否依赖了旧版行为。建议在预发布环境用小流量请求验证真实响应，确认没有因参数移除而静默降级。

是否值得现在升级

如果项目刚刚起步，直接采用 1.0 是合理选择，可以避免后续二次迁移。对于已经稳定运行的系统，升级的紧迫性取决于是否依赖被移除的功能：若大量使用 Text Completions 或 temperature，迁移成本较高，可以等待更完整的过渡方案；若只是标准 Messages API 调用，升级路径相对平滑，主要工作是环境与依赖的适配。

无论哪种情况，提前在分支上做一次试迁移，都比在生产环境被动应对更稳妥。