首页 / AI Trending / openai/openai-python

openai-python 是什么？

openai-python 是 OpenAI 官方生成的 Python 3.10+ SDK，为 OpenAI REST API 提供同步和异步客户端、类型定义、流式与 Realtime 连接、文件上传、webhook 校验、错误与重试处理。

⭐ 30,364 Stars 🍴 4,689 Forks Python Apache-2.0 作者: openai
来源：github.com/openai/openai-python 查看 GitHub 仓库 → 📘 使用教程 →

为什么值得关注

仓库是官方 Apache-2.0 SDK，调用 OpenAI API 需要用户自己的凭据并按官方账户计费，但 README 没有项目内充值、额度转售或订阅分发流程，因此不按严重商业漏斗隔离。

来源：github.com/openai/openai-python

核心功能

Responses 与 Chat 客户端

同步 OpenAI 和异步 AsyncOpenAI 客户端覆盖 Responses API 与长期支持的 Chat Completions，类型由官方 OpenAPI 规范生成。

来源：github.com/openai/openai-python
流式、Realtime 与文件

SDK 支持 SSE 流式响应、Realtime WebSocket、PathLike/bytes 文件上传和异步文件读取。

来源：github.com/openai/openai-python
生产错误处理

统一 APIError 层级、请求 ID、可配置重试和超时，并提供 webhook 签名校验与 workload identity。

来源：github.com/openai/openai-python

技术架构

库由 OpenAPI 规范生成 Pydantic 请求/响应类型，通过 HTTPX2 提供同步和异步传输。OpenAI/AsyncOpenAI 客户端持有认证、base URL、重试、超时与资源命名空间；流式与 Realtime 返回事件迭代器，webhook helper 在解析前校验原始请求体签名。

来源：github.com/openai/openai-python

项目知识图谱

知识图谱：项目核心节点（中心）+ 核心功能（内环六边形）+ 关键技术依赖（外环 chip） httpx2 >=2.12,<3httpx2 >=2.12,… pydantic >=1.10.13,<3（排除 2.0–2.3）pydantic >=1.1… anyio >=4.10,<5 typing-extensionstyping-extensi… jiter >=0.16,<1 Responses 与 Chat 客户端Responses 与 Chat… 流式、Realtime 与文件 生产错误处理 openai-python 项目本体 核心功能 关键依赖

技术栈

语言Python >=3.10框架OpenAPI 生成客户端 + HTTPX2 + Pydantic
关键依赖
httpx2 >=2.12,<3pydantic >=1.10.13,<3（排除 2.0–2.3）anyio >=4.10,<5typing-extensionsjiter >=0.16,<1
基础设施 / 部署
默认访问 OpenAI API；凭据可用环境变量或 workload identity，Realtime 使用 WebSocket，文件接口会上传内容
来源：github.com/openai/openai-python/blob/main/pyproject.toml

快速上手

在 Python 3.10+ 虚拟环境中固定安装 openai==3.17.0，把 OPENAI_API_KEY 放进环境变量或密钥管理系统，不写进代码和仓库。先用 OpenAI() 调用一个最小 Responses 请求，记录 _request_id；生产前设置明确 timeout、max_retries 和应用级幂等策略。
来源：github.com/openai/openai-python

使用场景

适合从 Python 调用 OpenAI 的文本、视觉、音频、文件、工具、流式和 Realtime API，也适合云上用短期 workload identity。它只是客户端库，不负责业务授权、提示注入防护、预算上限或应用级幂等。

来源：github.com/openai/openai-python

优势与局限

优势

  • OpenAI 官方维护并由 OpenAPI 生成类型
  • 同步、异步、SSE 与 Realtime 接口齐全
  • 请求 ID、错误类型、重试和 webhook 校验可用于生产诊断
  • 支持 Kubernetes、Azure 与 GCP 的短期身份路径

局限

  • 调用远端 API 会传输输入数据并产生账户用量
  • 默认超时长达 10 分钟，且特定错误默认重试 2 次
  • 流已产生部分输出后不会自动重试，应用需处理半完成状态
  • minor 版本可能包含类型或内部接口的不兼容变化
  • main 的 3.18.0 比最新 release 3.17.0 更新，不能混为同一版本
来源：github.com/openai/openai-python

最新版本

截至 2026-09-23，最新公开 GitHub release 是 v3.17.0，发布于 2026-09-22；main 的 pyproject.toml 已是 3.18.0。教程以 3.17.0 为可安装基线，并把 main 视为下一版本开发状态。

来源：github.com/openai/openai-python/releases/tag/v3.17.0

实测与证据

status: docs-only  |  checked_at: 2026-09-23  |  environment: 核对 OpenAI 官方 README、pyproject.toml、API 文档链接、版本策略和 GitHub Releases  |  limitations: 未安装 SDK，未配置或读取 API key，未发送任何 API、文件、Realtime 或 webhook 请求，也未产生模型费用  |  observed_output: 最新公开 release 为 v3.17.0（2026-09-22）；main 的 pyproject 已写 3.18.0；Python 下限为 3.10，默认重试 2 次、默认超时 10 分钟

来源：github.com/openai/openai-python/releases/tag/v3.17.0

同类项目对比

Anthropic 官方 Python SDK 同样提供同步/异步客户端、流式和错误处理，但请求资源、模型命名与认证面向 Anthropic API；openai-python 面向 OpenAI Responses、Realtime、webhook 和 workload identity。应按实际服务端 API 选 SDK，不能只替换 base URL 就假设全部语义兼容。

来源：github.com/anthropics/anthropic-sdk-python

总结评价

保留。它是官方开源 SDK，不包含额度转售或项目内充值漏斗；页面应聚焦版本固定、密钥管理、数据外发、默认重试和超时，而不是泛泛罗列 API。

来源：github.com/openai/openai-python

常见问题

openai-python 3.17.0 需要哪个 Python 版本？

官方 README 和 pyproject.toml 要求 Python 3.10+。本轮核对的最新公开 release 是 3.17.0；main 已写 3.18.0，若要复现应固定 PyPI/release 版本。

OPENAI_API_KEY 应该写进 Python 文件吗？

不应该。官方建议从环境变量或 .env 加载，并确保 .env 不进入版本控制；生产环境可评估短期 workload identity，减少长期静态 key 的暴露。

openai-python 为什么可能重复一次请求？

连接错误、408、409、429 和 5xx 默认会重试 2 次。对有外部副作用的工具或业务操作，要设置应用级幂等键、记录 request ID，并按需要调整 max_retries。

openai-python 默认超时是多少？

官方 README 当前写的是 10 分钟，超时请求还可能按默认策略重试。在线服务通常应显式设置更短的整体、连接和读取超时。

webhook 可以先解析 JSON 再验签吗？

不建议。client.webhooks.unwrap 和 verify_signature 需要原始 JSON 字符串；先解析或改写 body 可能破坏签名验证，应先保留原始请求体并完成校验。

资料与核验范围
本文依据项目公开资料整理。版本、安装命令和功能边界可能随上游更新，请以所列来源和项目当前版本为准。 资料核对时间: 2026-09-23 13:55.

参考材料：README、GitHub API、依赖文件