
Anthropic Python SDK:安装、设置 base_url、流式传输和错误处理
该 anthropic 包是 Anthropic 为 Claude API 提供的官方 Python 客户端。它负责身份验证、重试、流式传输和类型化错误处理,并且无需修改即可用于任何兼容 Anthropic 的端点:设置 base_url (或 ANTHROPIC_BASE_URL),其余代码保持不变。
安装
pip install anthropic1.x 版本基于 httpx2 运行,并且需要 Python 3.10 或更新版本。如果传入自己的 HTTP 客户端,请使用 SDK 的 DefaultHttpxClient 以保留其默认超时和连接数限制。
创建客户端
import anthropic
client = anthropic.Anthropic(
api_key="your_key", # default: ANTHROPIC_API_KEY
base_url="https://aiprimetech.io", # default: ANTHROPIC_BASE_URL, else https://api.anthropic.com
)base_url 是主机根地址。SDK 会自行追加 /v1/messages ,因此 https://aiprimetech.io/v1 会生成 /v1/v1/messages 以及一个 404 page not found。在环境中设置这两个变量后, anthropic.Anthropic() 无需传入任何参数:
export ANTHROPIC_API_KEY=your_key
export ANTHROPIC_BASE_URL=https://aiprimetech.io发送消息
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Summarise TCP slow start in two sentences."}],
)
for block in message.content:
if block.type == "text":
print(block.text)
print(message.usage.input_tokens, message.usage.output_tokens)
print(message._request_id) # log this with any failure reportcontent 是一个内容块列表(文本、思考、工具使用),因此请检查 block.type ,而不是盲目读取 content[0].text 。
流式接收响应
with client.messages.stream(
model="claude-sonnet-5",
max_tokens=16000,
messages=[{"role": "user", "content": "Write a short story about a lighthouse."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
final = stream.get_final_message()对于输入较长、输出较长或较大的 max_tokens,请使用流式传输:单个非流式请求必须在超时时限内完成,流式请求则不受此限制。 messages.create(..., stream=True) 会提供原始事件迭代器,适用于不需要辅助工具的情况。
异步客户端
import asyncio, anthropic
client = anthropic.AsyncAnthropic(base_url="https://aiprimetech.io")
limit = asyncio.Semaphore(3) # stay within your key's concurrency
async def ask(question: str) -> str:
async with limit:
msg = await client.messages.create(
model="claude-haiku-4-5",
max_tokens=512,
messages=[{"role": "user", "content": question}],
)
return next(b.text for b in msg.content if b.type == "text")
async def main():
answers = await asyncio.gather(*(ask(q) for q in ["What is DNS?", "What is BGP?"]))
print(answers)
asyncio.run(main())信号量很重要。使用 asyncio.gather 同时发起数百个请求,是我们在 Python 客户端中最常见的 Concurrency limit exceeded 错误原因。
超时与重试
默认设置:每个请求的超时时间为 10 分钟,并进行 2 次采用指数退避的自动重试。SDK 会重试连接错误、408、409、429 和 5xx 响应。由于超时也会触发重试,最坏情况下的实际总耗时为超时时间乘以尝试次数。
client = anthropic.Anthropic(base_url="https://aiprimetech.io", timeout=60.0, max_retries=4)
# override for one call only
client.with_options(timeout=300.0).messages.create(
model="claude-opus-5-5",
max_tokens=4000,
messages=[{"role": "user", "content": "Review this design doc..."}],
)错误处理
| 状态 | 异常 | 是否重试? |
|---|---|---|
| 400 | anthropic.BadRequestError | 否:修正请求 |
| 401 | anthropic.AuthenticationError | 否:密钥错误或缺失 |
| 403 | anthropic.PermissionDeniedError | 否 |
| 404 | anthropic.NotFoundError | 否:检查模型 ID 或 URL |
| 429 | anthropic.RateLimitError | 是,稍等后重试 |
| 5xx,包括 529 过载 | anthropic.InternalServerError | 是 |
| 网络故障 | anthropic.APIConnectionError | 是 |
| 超时 | anthropic.APITimeoutError | 是,或使用流式传输 |
try:
message = client.messages.create(model="claude-sonnet-5", max_tokens=1024,
messages=[{"role": "user", "content": "Hi"}])
except anthropic.NotFoundError as e:
print("Bad model ID or URL:", e.message)
except anthropic.RateLimitError as e:
print("Rate limited, retry after", e.response.headers.get("retry-after"))
except anthropic.APIStatusError as e:
print(e.status_code, e.type, e.message)
except anthropic.APIConnectionError:
print("Network problem")先捕获具体的异常类,最后再捕获 APIStatusError ;一个宽泛的 except 会掩盖值得重试的错误与需要修改代码的错误之间的区别。 e.type 会提供 API 的错误类型字符串,例如 rate_limit_error 或 overloaded_error.
模型 ID
| 模型 ID | 适用场景 |
|---|---|
claude-sonnet-5 | 编程和智能体任务的默认选择:速度快、能力强、价格适中。 |
claude-opus-5-5 | 更复杂的推理、大规模重构、长时间运行的智能体任务。 |
claude-fable-5-1 | 能力最强,价格也最高;留给最困难的任务使用。 |
claude-haiku-4-5 | 价格低、速度快:标题、摘要、分类和小步骤。 |
client.models.list() 会返回端点提供的模型,因此可以在使用前检查 ID。请严格按原样使用 ID,不要添加日期后缀。
网关故障排查
| 你会看到什么 | 原因 | 解决方法 |
|---|---|---|
NotFoundError 替换为 404 page not found | /v1 在 base_url | 使用主机根地址 |
AuthenticationError | 进程中未设置密钥,或粘贴时带入了空白字符 | 打印 len(os.environ["ANTHROPIC_API_KEY"]) |
RateLimitError: Concurrency limit exceeded for user | 正在处理的请求过多 | 一个 asyncio.Semaphore ,如上所示 |
APITimeoutError 发生在耗时较长的任务中 | 非流式请求的运行时间超过了超时时限 | 使用流式传输,或增大 timeout |
InternalServerError: No available accounts | 上游容量暂时不足 | 让 SDK 重试;增大 max_retries |
Insufficient account balance | 余额已用尽 | 充值 |
有关模型侧错误的更多信息,请参阅 Claude API 错误指南.
常见问题
如何安装 Anthropic Python SDK?
如何在 Anthropic Python SDK 中设置自定义基础 URL?
默认超时时间和重试次数是多少?
如何使用 Python SDK 进行流式传输?
获取 API 密钥,无需 Anthropic 账户,也无需加入候补名单。
获取你的 API 密钥AI Prime Tech 是独立的 API 网关,与 Anthropic 无关联,未获得其背书,也不是其经销商。Claude 及相关模型名称是其各自所有者的商标。