Anthropic Python SDK 中文教程：先跑通 Messages，再补流式、重试和迁移

anthropic-sdk-python 是 Anthropic 官方 Python SDK，包名是 anthropic。截至本次核对，最新正式版本为 v1.8.0，要求 Python 3.10 或更高。

1. 建立独立环境并固定 1.x

python3.10 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "anthropic>=1,<2"

python -c "import anthropic; print(anthropic.__version__)"

不要把 API key 写进源码。官方文档建议从 ANTHROPIC_API_KEY 环境变量读取。团队环境还应使用自己的密钥管理方式和访问控制。

2. 最小 Messages 请求

import os
from anthropic import Anthropic

with Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"]) as client:
    message = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=256,
        messages=[{"role": "user", "content": "用一句话解释幂等。"}],
    )
    for block in message.content:
        if block.type == "text":
            print(block.text)
    print("request_id=", message._request_id)

模型名来自当前官方示例，账户是否有权限仍以控制台和 API 返回为准。_request_id 虽以下划线开头，但官方明确把它列为公开属性，生产日志应记录它。

3. 错误、重试和超时要一起设计

import anthropic

try:
    message = client.with_options(
        max_retries=2,
        timeout=30.0,
    ).messages.create(...)
except anthropic.APIConnectionError as exc:
    print("network", exc.__cause__)
except anthropic.RateLimitError:
    print("rate limited")
except anthropic.APIStatusError as exc:
    print(exc.status_code, exc.response)

官方 SDK 默认对连接错误、408、409、429 和 5xx 重试两次，默认请求超时为 10 分钟。重试会增加实际等待时间；如果你的调用会触发外部写操作，业务层仍要设计幂等键或去重机制。

4. 长请求优先使用流式响应

stream = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=2048,
    messages=[{"role": "user", "content": "解释这份报告。"}],
    stream=True,
)

for event in stream:
    print(event.type)

官方提醒：高 max_tokens 的非流式请求可能被中间网络断开。SDK 在预计非流式请求超过约 10 分钟时会抛出 ValueError。只把 timeout 调得很大，可能让失败更晚发生并触发重复重试。

5. 从 0.x 迁移的检查表

• Python 最低版本从 3.9 升到 3.10。
• 自定义 client、transport、异常类型与类型注解从 httpx 转到 httpx2。
• 检查 OpenTelemetry、Sentry、respx、pytest-httpx、vcrpy 等是否仍能观察请求。
• 旧 Text Completions API 已移除，迁移到 Messages API。
• 异步 raw response 的 parse、read、text、json 需要 await；同步 text/content 也改为方法。
• 用 pyright 或 mypy 扫描迁移分支，再跑集成测试。

完整破坏性变更以官方 MIGRATION.md 为准。

6. 和 OpenAI Python SDK 怎么比较

相比 OpenAI 官方 openai-python，两者都要求 Python 3.10+，都有同步、异步、类型化响应和 HTTPX2。Anthropic SDK 的主要入口是 client.messages.create，并提供 Bedrock、Vertex、Claude Platform on AWS 与 Foundry 客户端；OpenAI SDK 以 Responses API 为主要生成入口，同时保留 Chat Completions。

它们的对象结构、模型、工具事件和托管平台不同。迁移供应商时需要重写适配层与测试，不能只替换包名。

7. v1.8.0 更新了什么

v1.8.0 于 2026-09-22 发布，加入 claude-opus-5-5、inline tool definitions 和 MCP tool-list pinning 的 beta 支持；还修复 Python 3.13 在未关闭 stream 时退出可能崩溃，以及工具和 compaction 相关问题。beta 功能仍需相应 header 与可用权限。

8. 验证状态与验证边界

验证边界：未验证认证、计费、模型权限、网络、流式事件、工具、批处理、文件上传、云平台客户端或任何 0.x 项目的真实迁移。代码片段依据官方接口整理，需要在自己的测试账户和固定版本中运行。

常见问题