调用大模型早已不是大厂专利：一个 Python 脚本、十几行代码，就能把 GPT 模型的能力接进自己的程序。但不少初学者恰恰卡在最起点——环境装不对、密钥配不好、第一次调用报错后不知从何排查。本篇是《OpenAI Python SDK 从入门到实战》系列的第 1 篇，目标很朴素：装好环境，跑通第一次调用，并弄清两条 API 线各自的定位。本文按"能力地图 → 环境搭建 → 第一次调用 → API 选型 → 报错速查 → 总结"组织全文。
1、系列能力地图
这个系列面向零基础读者，只假设你会最基本的 Python 语法，不要求有任何机器学习背景。全系列围绕官方 openai 库（SDK，Software Development Kit）展开，每篇独立成篇、可以中途加入，学习路线分三个阶段，如下图所示：
入门阶段解决"跑不跑得起来"的问题：环境、首次调用与流式输出；核心能力阶段解决"好不好用"：结构化输出让模型稳定返回可解析的 JSON，工具调用让模型去操作外部系统，多轮记忆让对话拥有上下文；工程落地阶段解决"敢不敢上生产"：成本控制与错误重试兜底，最后把全部能力组装成一个实战项目。本篇对应路线图最左边的起点，先把地基打牢。
为什么坚持用官方 SDK，而不是直接发 HTTP 请求？因为 SDK 把鉴权、超时、自动重试、流式解析这些脏活全部封装好了，还带完整的类型提示，编辑器里能自动补全参数名、提前暴露拼写错误；裸写 requests.post 则每一样都要自己处理。全系列每一篇都给出可运行的完整代码，跟着敲就能复现。
2、环境搭建
2.1、Python 与虚拟环境
官方 SDK 要求 Python 3.10 及以上。终端执行 python --version 可确认本机版本，macOS 与部分 Linux 发行版要写 python3 --version，二者只是命令名差异；过低就去 python.org 下载最新安装包，Windows 安装时记得勾选 Add to PATH，省去手动配环境变量的麻烦。接着为项目建一个独立的虚拟环境，命令如下：
python -m venv .venv
.venv\Scripts\activate # Windows
source .venv/bin/activate # macOS 与 Linux
第一条命令在当前目录创建 .venv 文件夹，后两条按系统二选一执行，激活成功后命令行提示符前会出现 (.venv) 字样。虚拟环境的作用是隔离依赖：这个项目装了什么版本的库，都不会影响机器上的其他项目，将来删除项目时整个文件夹一并删掉即可，干净利落。退出时执行 deactivate，下次进入项目目录再激活一次即可。
2.2、安装 SDK 与密钥配置
激活虚拟环境后，一条命令装齐两个包：
pip install --upgrade openai python-dotenv
国内网络下载慢时，在命令末尾追加 -i https://pypi.tuna.tsinghua.edu.cn/simple 改走清华镜像源即可。openai 是官方 SDK，当前处于 3.x 系列，截至 2026 年 10 月最新版本为 3.42.0，发布节奏可在 PyPI 项目页 与 官方仓库 查看；python-dotenv 负责从 .env 文件加载环境变量，管理密钥时会用到。验证安装：
pip show openai
输出前两行应类似：
Name: openai
Version: 3.42.0
接下来申请密钥。登录 OpenAI 开放平台，进入 API Keys 页面，点 Create new secret key 生成一把新密钥。密钥只在创建那一刻完整展示，务必当场复制保存。注意 API 与 ChatGPT 会员是两套计费：新账号通常没有赠送额度，需要在平台 Billing 页面充值后才能调用，预付费、用多少扣多少。
密钥等同于账户密码：不要硬编码进代码，不要提交进 Git 仓库，截图分享前先打码。一旦怀疑泄露，立即回平台吊销重发。
正确姿势是环境变量。在项目根目录新建 .env 文件，写入一行：
OPENAI_API_KEY=sk-你的密钥
SDK 创建客户端时会自动读取名为 OPENAI_API_KEY 的环境变量，python-dotenv 负责在脚本启动时把 .env 的内容注入环境变量，代码里因此看不到密钥明文。最后记得把 .env 加进 .gitignore。至此项目根目录里有三样东西：.venv 虚拟环境、.env 密钥文件和接下来的示例脚本，齐了就能开工。
3、跑通第一次调用
写代码之前先看清调用链路，一共三段，如下所示：
你的代码只和 SDK 对话，SDK 负责拼装 HTTP 请求、附上密钥、解析响应。记住这条链路，后面排查报错时就知道该往哪一段看。下面是完整的最小示例，保存为 first_call.py：
from dotenv import load_dotenv
from openai import OpenAI
load_dotenv() # 把 .env 注入环境变量
client = OpenAI() # 自动读取 OPENAI_API_KEY
response = client.responses.create(
model="gpt-6.1-terra", # 轻量均衡款，练习成本友好
instructions="你是简洁的中文技术助手。",
input="用一句话解释什么是 API。",
)
print(response.output_text) # 直接拿到纯文本回复
逐行拆解：前两行导入 dotenv 与 SDK；load_dotenv() 必须在创建 client 之前执行，否则密钥尚未注入就会初始化失败；responses.create 是 Responses API 的入口，instructions 扮演系统提示的角色、给模型定人设与规则，input 则是这条用户消息，两者分工与 Chat API 的 system 和 user 一一对应；response.output_text 是 SDK 的便捷属性，自动从响应结构里抽取纯文本，不必手动遍历输出列表。运行：
python first_call.py
输出类似：
API 是一个程序通过约定接口调用另一个程序能力的通信方式。
模型输出带有随机性，你的措辞与这句不同属正常。responses.create 还有两个常用参数可自行尝试：max_output_tokens 限制回复长度，temperature 调节输出的随机程度，后续篇章会展开。计费单位是 tokens：模型把文本切分成 tokens 来处理，一个汉字大致折合 1 个 token 上下，想精确看消耗可以打印 response.usage，其中记录了本次输入与输出的 token 数量，系列的后续成本控制篇会反复用到它。费用方面不必担心：以轻量均衡款 gpt-6.1-terra 在 2026 年 10 月的价格为参照，输入每百万 tokens 约 1 美元、输出约 5 美元，旗舰 gpt-6-astra 则为输入约 10 美元、输出约 50 美元，现役模型以官方定价页为准；本例一次调用只消耗几十个 tokens，成本不足一美分的百分之一，尽可反复练习。
4、两条 API 线的选型
翻开官方文档会看到两条并行接口：Responses API 与 Chat Completions API。前者是 2025 年 3 月发布的统一接口，官方现在明确把它当作主线，SDK 文档与示例已转向以它为主，新能力也优先在这条线落地；后者是业界流传最广的"聊天补全"格式，官方口径为长期支持（supported indefinitely），不强制迁移，但基本不再新增特性。两条线对照如下：
| 维度 | Responses API | Chat Completions API |
|---|---|---|
| 官方定位 | 当前主线，新项目首选 | 上一代标准，长期维护 |
| 上下文管理 | 服务端托管，续接对话省心 | 无状态，需自行拼接历史 |
| 内置工具 | 网页搜索等优先支持 | 基本不提供 |
| 缓存效果 | 提示缓存利用率更高 | 常规水平 |
| 适用场景 | 只对接 OpenAI 的新项目 | 兼容多厂商或存量代码 |
给个直观感受，第 3 节的例子换成 Chat Completions 写法如下：
completion = client.chat.completions.create(
model="gpt-6.1-terra",
messages=[
{"role": "system", "content": "你是简洁的中文技术助手。"},
{"role": "user", "content": "用一句话解释什么是 API。"},
],
)
print(completion.choices[0].message.content)
差别在消息组织：messages 列表用 role 显式区分 system 与 user，历史消息也要按这个格式往列表里追加；取文本则要走到 choices[0].message.content。表中"服务端托管"的具体含义是：Responses API 允许把 previous_response_id 传回服务端直接续接上一轮，历史消息的存储与拼接交给 OpenAI 处理，而 Chat Completions 每一轮都要把完整历史重新发一遍。官方测试还显示，Responses 的提示缓存利用率比 Chat Completions 高出四到八成，长对话场景能实打实省下费用。
本系列以 Responses API 为主线，理由是它代表官方推荐方向、参数与错误文档更完整，涉及行为差异时会附上 Chat Completions 的等价写法；若同一套代码还要调用其他厂商的模型，则优先 Chat Completions——它的消息格式已被大多数厂商和网关兼容。一句话记选型：新项目跟着官方走 Responses，多厂商兼容守住 Chat Completions。至于更早的 Assistants API，官方已启动退役流程，新项目不必再选，细节见官方迁移指南。
5、常见报错速查
第一次跑通之前，大概率会撞上下面三种报错之一。SDK 会把 HTTP 状态码翻译成对应的异常类，速查如下：
| 报错类型 | 典型原因 | 处理办法 |
|---|---|---|
AuthenticationError（401） |
密钥拼错或已吊销，密钥未成功加载 | 回平台重发密钥，检查 .env 与加载顺序 |
RateLimitError（429） |
账户额度不足或请求过于密集 | 查看平台余额与用量，降频后重试 |
NotFoundError（404） |
模型名拼写错误或账号无权限 | 对照官方模型列表改用正确名称 |
排查思路是先看异常类定位类别，再读异常 message 里的具体描述——前两类回第 2 节检查密钥与账户，第三类多半是模型名字符串敲错。对照第 3 节的时序图看：401 与 404 在请求发出阶段就能定位，429 则要回到账户层面解决。三种之外若见到 Connection error 或超时，一般是本机到服务端的网络链路问题，检查代理设置后重试即可。
6、总结
本篇完成了三件事：装好环境（Python 3.10+、venv、openai 3.x 与 python-dotenv），用 .env 管住密钥，跑通 responses.create 第一次调用；同时定下选型基调——只对接 OpenAI 的项目走 Responses API，需要多厂商兼容时守住 Chat Completions。留两道练习：
- 把
model换成gpt-6-astra与gpt-6-luna再各跑一次，对比旗舰与轻量的回复风格与速度 - 修改
instructions（例如换成"你是严谨的法律顾问"），观察同一问题下措辞变化
对于刚起步的读者，建议先把本篇示例亲手跑满三遍再进入后续篇章：结构化输出、工具调用、多轮记忆与成本控制，全部建立在这条最小调用链路上。练习中遇到的报错，先回第 5 节对号入座，这本身就是最好的第一课。
