openai-python 3.17 教程：默认重试和超时要主动改

openai-python 是 OpenAI 官方 Python 3.10+ SDK。它由 OpenAPI 规范生成类型，通过 HTTPX2 提供同步、异步、SSE 流式、Realtime、文件上传、webhook 校验和统一错误处理。

1. 安装与最小 Responses 请求

python -m venv .venv
source .venv/bin/activate
pip install 'openai==3.17.0'
export OPENAI_API_KEY='从密钥管理系统注入'

from openai import OpenAI

client = OpenAI(timeout=20.0, max_retries=1)
response = client.responses.create(
    model="你的可用模型",
    input="Reply with OK"
)
print(response.output_text)
print(response._request_id)

不要把 key 写入 Python 文件。官方建议用环境变量或不入库的 .env；Kubernetes、Azure 和 GCP 的自动化环境还可评估短期 workload identity。

2. 默认重试会影响成本和副作用

连接错误、408、409、429 和 5xx 默认重试 2 次，并采用短指数退避。纯生成请求通常可以接受，但模型随后调用支付、发信或写数据库工具时，应用必须提供幂等键和业务状态检查。

官方当前默认超时是 10 分钟，超时仍可能触发重试。面向在线用户时应显式配置整体、连接、读取和写入超时，并记录 _request_id；失败请求从 APIStatusError.request_id 取得 ID。

3. 异步、流式与 Realtime

AsyncOpenAI 和同步客户端使用同一资源结构。SSE 流在已经交付部分输出后不会自动重放，以免重复内容；应用需要处理断流后的半完成状态。Realtime 则通过 WebSocket 持续接收事件，连接生命周期和取消逻辑要单独测试。

文件上传会把内容发送到远端 API。传 PathLike 时异步客户端会异步读取文件；音频等接口应提供带扩展名的文件名，避免 multipart 使用无法判断格式的通用名称。

4. webhook 先验签再解析

client.webhooks.unwrap() 可以同时验签和解析，verify_signature() 只验签；二者都需要服务器收到的原始 JSON 字符串。先把 body 解析、重排或重新编码，可能导致签名验证失败。

该仓库是 Apache-2.0 官方 SDK，调用远端 API 使用用户自己的账户。README 没有额度转售、订阅分发或项目内充值流程，因此不命中严重商业隔离规则；

5. 与 Anthropic Python SDK 对比

Anthropic 官方 Python SDK同样提供同步/异步客户端、流式与错误处理，但资源、模型名和认证面向 Anthropic API。openai-python 提供 OpenAI Responses、Realtime、webhook 与 workload identity。

按实际服务端 API 选择 SDK。自定义 base URL 不代表两个平台的请求结构、事件和错误语义自动兼容。

常见问题