openai-python 快速上手指南官方 SDK 安装、密钥配置与首次模型调用【免费下载链接】openai-pythonThe official Python library for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-pythonopenai-python 是 OpenAI API 的官方 Python 库支持文本生成、流式输出、异步与实时语音对话。跟随本指南操作你可以完成环境预检、SDK 安装并成功发起第一次 API 调用。 能力预览openai-python 能做什么先花 10 秒确认这个库是否覆盖你的需求核心能力说明文本生成通过client.responses.create()或client.chat.completions.create()调用模型流式响应streamTrue后逐块打印模型输出适合聊天界面异步客户端AsyncOpenAI提供与同步版完全相同的接口结构化输出传入 Pydantic 模型自动把模型回答解析为对象实时对话Realtime API 基于 WebSocket 处理文本和音频如果你只需要调用 OpenAI 模型拿结果前两条就够用了。✅ 动手前预检系统与网络要求按顺序确认以下 4 项全部满足再开始安装Python ≥ 3.10本库硬性要求 3.10 及以上版本3.7~3.9 会安装失败pip 可用能正常执行pip --version网络可达本机能够访问 OpenAI API 服务公司内网/代理环境需提前配置API 密钥在 OpenAI 平台的组织设置中获取先放在手边配置环节会用到一键检查前两项python --version pip --version # Linux/Mac 若提示找不到 python改用 python3 --version成功判定输出中 Python 版本号为 3.10 或更高pip 版本行带有 Python 解释器路径。[!TIP] 建议用虚拟环境隔离依赖python -m venv openai-env然后激活Linux/Macsource openai-env/bin/activateWindowsopenai-env\Scripts\activate。后续所有命令都在激活后执行。 SDK 安装PyPI 主路径与备选方式主路径推荐按编号执行激活虚拟环境若上一步已创建安装 SDKpip install openai验证安装结果python -c import openai; print(openai.__version__)成功判定打印出 3.x 版本号且无异常即安装成功。备选方式如下表按场景任选不再展开方式命令何时选用指定镜像源pip install -i 镜像源URL openai国内网络直连 PyPI 速度慢时源码安装git clone https://gitcode.com/GitHub_Trending/op/openai-python后进入目录执行pip install .需要体验未发布的最新开发版本安装实时语音扩展pip install openai[realtime]计划使用 Realtime API 时安装 aiohttp 传输层pip install openai[aiohttp]异步场景下希望用 aiohttp 作为底层传输[!TIP] 源码安装后执行git pull拉取更新再重新pip install .即可同步到最新代码。 密钥配置与首次冒烟验证SDK 默认从环境变量OPENAI_API_KEY读取密钥。先按你的系统设置它# Linux / Mac当前终端临时生效 export OPENAI_API_KEY你的密钥::: PowerShellWindows $env:OPENAI_API_KEY你的密钥::: CMDWindows set OPENAI_API_KEY你的密钥新建一个最小验证脚本smoke_test.pyfrom openai import OpenAI client OpenAI() completion client.chat.completions.create( modelgpt-5.5, messages[{role: user, content: Say: this is a test.}], ) print(completion.choices[0].message.content)运行python smoke_test.py成功判定终端打印出模型返回的文本如this is a test.没有任何异常抛出。看到这一行你的环境就算彻底跑通了。[!TIP] 不要把密钥硬编码进脚本。推荐在项目里放一个.env文件写入OPENAI_API_KEY...配合 python-dotenv 加载避免密钥被提交到代码仓库。⚠️ 避坑清单常见报错速查所有新手期问题集中在这里按症状 → 原因 → 解决格式速查。ModuleNotFoundError: No module named openai→ 原因包装在了另一个 Python 环境里或虚拟环境未激活 → 解决在报错的解释器里执行pip show openai确认确认当前处于激活的 venv 中再安装AuthenticationError401→ 原因OPENAI_API_KEY未设置或密钥错误 → 解决执行echo $OPENAI_API_KEYWindows 用echo %OPENAI_API_KEY%核对值到平台重新复制完整密钥NotFoundError404/ 提示模型不存在→ 原因model参数写了不存在或无权限的模型名 → 解决调用client.models.list()查看当前账号可用的模型列表改用其中的名称APIConnectionError/ 连接超时→ 原因本机无法直连 OpenAI 服务常见于公司网络 → 解决为客户端传入带代理的自定义 HTTP 客户端或放宽超时OpenAI(timeout60.0, max_retries2)pip install openai报requires a different Python→ 原因当前解释器低于 3.10 → 解决升级 Python 或新建 3.10 的虚拟环境不要在旧环境强行降级Windows 上python命令不存在→ 原因Python 未加入 PATH → 解决重装 Python 并勾选 Add Python to PATH或改用py -3调用安装时Permission denied→ 原因直接往系统目录写包 → 解决优先使用虚拟环境不建议日常开发使用 sudo 提权安装 深入方向跑通之后的三条进阶路线流式输出给创建请求加streamTrue然后遍历chunk.choices[0].delta.content逐字打印参考 examples/streaming.py 和 examples/async_demo.py异步版结构化输出调用client.chat.completions.parse()并传入 Pydantic 模型作为response_format模型回答会被自动解析成对象见 helpers.md超时与重试调优默认自动重试 2 次、超时 10 分钟可用max_retries和timeout参数按请求或全局覆盖错误类型对照表401/404/429 等见 README.md 的 Handling errors 一节完整接口索引在 api.md迁移 HTTPX2 传输层的注意事项见 httpx2.md。到这里你已经完成了 openai-python 的环境搭建、安装和首次调用环境算是正式就绪。下一步建议把冒烟脚本改成流式版本体验更接近真实产品的交互效果。【免费下载链接】openai-pythonThe official Python library for the OpenAI API项目地址: https://gitcode.com/GitHub_Trending/op/openai-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考