Claude学院

Anthropic Python SDK 安装与配置完整教程

安装 Anthropic 官方 Python SDK 只需一条命令 pip install anthropic，然后把密钥写入环境变量 ANTHROPIC_API_KEY，就能用几行代码调用 Claude。SDK 封装了 Messages API 的鉴权、重试、流式解析和类型提示，比手写 HTTP 请求省心得多。下面从安装到首次调用，再到流式输出和工具调用，一步步带你跑通。

第一步：安装 anthropic SDK

SDK 要求 Python 3.8 及以上版本，建议用 3.10+。强烈建议先建一个虚拟环境，避免污染全局依赖：

python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\Activate.ps1

pip install anthropic

验证安装是否成功，并查看版本号：

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

如果你在国内安装速度慢，可以临时指定镜像源，例如 pip install anthropic -i https://pypi.tuna.tsinghua.edu.cn/simple。需要异步支持时，SDK 自带 AsyncAnthropic 类，无需额外安装；如果要做图片输入等多模态调用，也不需要装额外依赖，base64 编码用标准库即可。

第二步：配置 API Key

调用前必须有一个有效的 API Key。如果还没有，可以先看Claude API Key 怎么获取这篇拿到密钥。拿到后，最佳实践是写入环境变量，而不是硬编码在代码里：

# macOS / Linux（写入 ~/.zshrc 或 ~/.bashrc 可永久生效）
export ANTHROPIC_API_KEY="sk-ant-你的密钥"

# Windows PowerShell（当前会话）
$env:ANTHROPIC_API_KEY="sk-ant-你的密钥"

SDK 在初始化时会自动读取这个环境变量，所以代码里只要写 client = anthropic.Anthropic() 即可。如果你确实想在代码里显式传入（比如多账号切换），可以用 anthropic.Anthropic(api_key="sk-ant-...")，但切记不要把密钥提交到 Git 仓库。团队协作推荐用 python-dotenv 把密钥放进 .env 文件并加入 .gitignore。

第三步：第一次调用 Messages API

SDK 的核心入口是 client.messages.create()，对应底层的 POST /v1/messages 接口，鉴权头 x-api-key 和 anthropic-version 由 SDK 自动注入。下面是一个最小可运行示例：

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "用一句话解释什么是 MCP"}
    ],
)

print(message.content[0].text)

几个必填与常用参数说明：

参数说明
model模型 ID，如 claude-opus-4-8、claude-sonnet-4-6、claude-haiku-4-5
max_tokens本次回复最多生成的 token 数，必填
messages对话历史数组，每项含 role（user/assistant）与 content
system系统提示词，独立顶层参数（不放进 messages）
temperature采样温度，0-1，控制随机性

模型选型上，追求最强推理用 Opus 4.8，日常对话和大批量任务用 Sonnet 4.6，对延迟和成本敏感的轻量场景用 Haiku 4.5，详细可参考Opus / Sonnet / Haiku 选型指南。全部参数的含义和取值可查阅Messages API 全部参数说明。如果你想要更详细的从注册到首请求的流程，10 分钟跑通第一个 Python 程序讲得更细。

第四步：流式输出（SSE）

对话类应用通常要边生成边显示，这时用流式接口体验更好。SDK 提供了 client.messages.stream() 上下文管理器，底层走 SSE，自动帮你解析事件：

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "写一首关于秋天的短诗"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

final = stream.get_final_message()
print("\n用量：", final.usage)

循环结束后可以用 get_final_message() 拿到完整消息和 token 用量。流式输出的原理与底层事件类型，可深入阅读流式输出 Python 实现教程（SSE 详解）。

第五步：工具调用（Tool Use）

让 Claude 调用你的函数或 API，需要在请求里声明 tools。模型会返回 stop_reason="tool_use" 和工具入参，你执行后把结果以 tool_result 回传：

tools = [{
    "name": "get_weather",
    "description": "查询指定城市的当前天气",
    "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}]

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "北京今天天气怎么样？"}],
)
print(resp.stop_reason)  # tool_use

完整的多轮回传流程和实战代码，见Tool Use 工具调用完整代码实战。

进阶配置：超时、重试与代理

SDK 内置自动重试（默认对部分错误重试），也可在初始化时自定义：

client = anthropic.Anthropic(
    max_retries=4,
    timeout=60.0,  # 秒
)

国内网络环境如需走代理，可通过自定义 httpx 客户端注入，或设置标准的 HTTPS_PROXY 环境变量。异步场景把 Anthropic 换成 AsyncAnthropic，调用前加 await 即可，接口形态完全一致。关于价格和限额，具体以 Anthropic 官网为准。

常见问题

报错 401 authentication_error 怎么办？

说明密钥无效或未正确传入。先确认 ANTHROPIC_API_KEY 是否真的在当前 shell 生效（用 echo $ANTHROPIC_API_KEY 检查），注意环境变量改完要重开终端或重启 IDE。密钥不要带多余空格或引号。详细排查见401 认证失败排查指南。

遇到 429 限流报错如何处理？

SDK 默认会对限流做指数退避重试，但高并发下仍可能触发。建议降低并发、增大 max_retries，或在业务层加排队。具体方案参考429 限流报错的 3 种重试方案。

SDK 和直接发 HTTP 请求有什么区别？

本质都是调用同一个 Messages API。SDK 的优势是自动处理鉴权头、自动重试、流式 SSE 解析、完整类型提示和异常分类，开发效率高很多。如果只是想了解原始接口怎么调，可以看Claude API 怎么调用的完整教程。

← Claude API 开发