OpenAI Python SDK 完整指南从第一次对话调用到实时语音交互【免费下载链接】openai-pythonThe official Python library for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-python如果让你直接用 Python 调 OpenAI最痛苦的部分往往不是写提示词而是手工拼 HTTP 请求、解析嵌套 JSON、处理 SSE 流和重试超时。官方维护的openaiPython 库当前版本 3.5.0把这些全部封装好了一条语句完成文本对话与生成streamTrue开启流式输出AsyncOpenAI支持异步并发realtime模块打通 WebSocket 实时语音交互。本文按最小闭环 → 生产可用 → 高级定制三层展开帮你把这条链路一次跑通。一次性的前置准备环境要求与安装先看硬性门槛。根据 pyproject.toml 的requires-python声明本库要求 Python 3.10 及以上3.7、3.9 都无法安装运行这是很多旧教程没写清楚的点# 确认版本 ≥ 3.10再安装主包 python --version pip install openai验证是否装好直接进解释器确认能导入且版本符合预期# 执行 python -c import openai; print(openai.__version__)能打印版本号即安装成功 import openai print(openai.__version__)需要额外能力时按需加装可选依赖extras而不必一次性全装安装命令解锁的能力pip install openai[realtime]Realtime 实时对话引入 websocketspip install openai[aiohttp]异步客户端的 aiohttp 传输层高并发下性能更好pip install openai[bedrock]通过 AWS Bedrock 调用模型pip install openai[datalib]与 numpy / pandas 互转的 DataFrame 支持想直接跟最新代码而不是 PyPI 稳定版也可以克隆仓库后本地安装只读使用即可git clone https://gitcode.com/GitHub_Trending/op/openai-python cd openai-python pip install .第一层跑通最小对话闭环安装完成后只差一个密钥。构造客户端时不传api_key参数它会自动从环境变量OPENAI_API_KEY读取组织、项目 ID 同理走OPENAI_ORG_ID、OPENAI_PROJECT_ID所以推荐把密钥放进.env文件配合 python-dotenv 加载而不是硬编码进代码# 密钥取自环境变量响应文本直接挂在 response.output_text 上拿到非空字符串即闭环成功 import os from openai import OpenAI client OpenAI() # 自动读取 OPENAI_API_KEY response client.responses.create( modelgpt-5.5, input用一句话解释什么是幂等性, ) print(response.output_text)这里用的是 Responses API它是当前官方主推的接口input直接收字符串或消息列表返回对象上output_text就是拼好的完整回复。如果你的项目还在用更早的 Chat Completions 接口它也长期受支持写法略有不同messages数组 choices[0].message.content两条入口在 README.md 里都有完整示例。第二层把单次调用变成稳定应用跑通一次之后真正写产品时最常碰到的四个问题分别是输出太慢、并发不够、网络抖动、列表翻页。流式输出请求加streamTrue返回的不再是一次性结果而是服务端推送的 SSE 事件流逐条消费即可实现打字机效果# 迭代 stream 中的每个事件并打印事件类型齐全输出文本增量、完成、用量等控制台逐字出现即成功 from openai import OpenAI client OpenAI() stream client.responses.create( modelgpt-5.5, input写一句关于独角兽的睡前故事, streamTrue, ) for event in stream: print(event)异步并发把OpenAI换成AsyncOpenAI、调用前加await其余接口完全一致适合 FastAPI 这类异步服务里并发发起多路请求# 在 FastAPI 等异步框架中并发调用多路请求await 后返回的结果结构与同步版一致 import asyncio from openai import AsyncOpenAI client AsyncOpenAI() async def main(): response await client.responses.create( modelgpt-5.5, input解释什么是去教派主义 ) print(response.output_text) asyncio.run(main())超时与重试客户端构造参数里直接给timeout和max_retries默认重试 2 次网络抖动时 SDK 会按指数退避自动重发不用自己写重试循环# 30 秒整体超时、最多重试 3 次超时或限流不再让请求卡死 from openai import OpenAI client OpenAI(timeout30.0, max_retries3)翻页所有 list 接口返回自动分页迭代器for循环会按需拉取后续页无需手工管理游标需要精确控制时再用has_next_page()/get_next_page()。出错时抛出的都是openai模块下的结构化异常认证失败、限流、服务端错误等各有独立类型except时按类型分别处理比统一Exception更好定位问题。第三层高级定制实时语音对话这是最能体现 SDK 价值的场景。client.realtime.connect()通过 WebSocket 建立双向通道文本与音频都能双向收发还支持函数调用# 建立实时连接并消费事件流控制台逐字打印模型输出即表示实时通道打通 # 需先安装 openai[realtime] import asyncio from openai import AsyncOpenAI async def main(): client AsyncOpenAI() async with client.realtime.connect(modelgpt-realtime-2) as connection: await connection.session.update( session{type: realtime, output_modalities: [text]} ) await connection.conversation.item.create( item{ type: message, role: user, content: [{type: input_text, text: Say hello!}], } ) await connection.response.create() async for event in connection: if event.type response.output_text.delta: print(event.delta, end, flushTrue) elif event.type response.done: break asyncio.run(main())注意实时通道的错误不会抛异常而是以error事件送达且连接保持可用需要自己在事件循环里判断。完整的按住说话应用可参考 examples/realtime/push_to_talk_app.py麦克风采集与本地播放的辅助类在 src/openai/helpers/。代理与自定义传输默认底层是 HTTPX2 客户端需要走公司代理或自定义证书时构造客户端传http_client即可接管传输层迁移细节见 httpx2.mdexamples/mtls_httpx.py 等文件里有双向 TLS 的现成写法。工作负载身份认证在 Kubernetes、Azure、GCP 这类环境里可以不使用长期 API 密钥改用云身份提供商签发的短时效令牌openai.auth提供了各平台的 token providerK8s 服务账户令牌、Azure 托管身份、GCP ID 令牌也支持 X.509 双向 TLS 联邦示例见 examples/x509_workload_identity.py。多云部署同一套客户端 API 可以指向 Azure OpenAIexamples/azure.py或 AWS Bedrockbedrock.md对业务代码基本透明。小结与延伸阅读三层走完你已经具备了可对话Responses / Chat 双入口、可流式、可异步、可实时、可上云的完整能力。类型方面值得强调一句——请求参数是 TypedDict、响应是 Pydantic 模型编辑器里有完整自动补全model.to_dict()/model.to_json()可自由转换这比裸 HTTP 调用省掉的大多数就是字段名猜错这类 bug。后续查阅入口全部接口的机器可读清单api.md官方用法示例合集examples/自定义 HTTP 客户端迁移说明httpx2.md行为契约测试想确认某个功能的行为时先翻这里最快tests/【免费下载链接】openai-pythonThe official Python library for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考