2026年OpenAI SDK 国内API 教程：Python 接入步骤与 Base URL 配置思路
2026年OpenAI SDK 国内API 教程：Python 接入步骤与 Base URL 配置思路
用 Python 调 OpenAI SDK，代码本身只有几行，真正卡住大多数人的是两件事：Base URL 该填什么，以及环境变量到底有没有生效。把这两处理顺，接入通常十几分钟就能跑通。
这篇教程按「准备 → 配置 → 首次请求 → 排查」的顺序展开。所有接口地址、模型名称与计费规则，请以你所用平台控制台和文档显示的信息为准，不同服务商的命名可能并不相同。
一、接入前的准备清单
在写代码之前，先确认下面几项已经拿到手，否则后面报错时很难判断是配置问题还是权限问题。
- API Key：一串以固定前缀开头的密钥，注意区分测试用与生产用，不要把 Key 直接写进代码仓库。
- Base URL：也就是接口根地址，SDK 会在这个地址后面拼接具体路径。
- 模型名称：必须是服务端实际存在的名称，大小写和连字符都不能想当然。
- Python 环境：建议 3.9 以上，并用虚拟环境隔离依赖，避免污染全局包。
安装与最小配置
安装官方 SDK 后，用环境变量承载密钥是最省事的做法，也方便后续在服务器上切换配置。
pip install openai
export OPENAI_API_KEY="你的 API Key"
export OPENAI_BASE_URL="控制台给出的接口根地址"写完这几行，先别急着跑业务代码，用一条最短的请求验证连通性，成功率会高很多。
from openai import OpenAI
client = OpenAI() # 默认读取上面的环境变量
resp = client.chat.completions.create(
model="控制台显示的模型名称",
messages=[{"role": "user", "content": "你好，请回复一句确认信息"}],
)
print(resp.choices[0].message.content)二、Base URL 配置的三种思路
Base URL 是这类接入里最容易出错的配置项，因为它不是「随便填个域名」，而是要和服务端实际的路由结构对上。常见的三种写法各有适用场景：
- 根地址直填：把控制台给出的根地址直接交给 SDK，由 SDK 负责拼接后续路径。这是最推荐的方式，改动最少。
- 带版本路径：部分服务要求地址里包含版本段，此时需要完整复制控制台给出的地址，不要自己截断或补全。
- 自建网关转发：企业内部统一走网关时，网关需要把认证头和路径原样透传，否则容易出现 401 或 404 混在报错里。
需要强调的一点是：如果 SDK 内部已经默认带上了某段路径，而你又在 Base URL 里重复了一次，就会出现路径叠加。这类问题表现为「地址看着没错，但一直 404」，排查时优先核对完整请求地址。
配置项与检查方法对照
| 配置项 | 作用 | 检查方法 |
|---|---|---|
| API Key | 身份认证，决定可用模型范围与额度 | 在控制台重新复制一次，确认前后无空格 |
| Base URL | 请求根地址，决定路由是否正确 | 打印完整请求 URL，与文档示例逐段比对 |
| 模型名称 | 指定实际调用的模型 | 从模型列表页复制，避免手写拼错 |
| 超时与重试 | 控制长请求稳定性与失败恢复 | 设置合理超时，对 5xx 做指数退避重试 |
接入失败时，先确认「认证是否通过」再确认「路由是否命中」。这两个问题在报错信息里经常长得像，但处理方式完全不同。
三、常见报错与排查顺序
401 与 403
401 通常指 Key 无效或未正确读取，403 多与权限或额度有关。先确认环境变量是否真的被进程读到——在容器里运行时，宿主机导出的变量不会自动进容器，这一点非常容易忽略。
404 与连接超时
404 优先怀疑 Base URL 拼写和路径重复；连接超时则要看网络出口、代理设置以及是否需要放行特定域名。如果公司网络有统一出口策略，记得把接口域名加入白名单。
模型不存在
这类报错几乎都是名称不匹配。建议把可用模型名称从控制台复制下来存进配置文件，而不是散落在代码各处。如果你希望在一个地方统一查看多家模型的名称、兼容协议与 Key 管理，可以了解 通联AI中转站，它提供 OpenAI 兼容方向的接入方式与统一的 API Key 管理入口，适合需要在多个模型之间做对比测试的开发者先从控制台核对 Base URL 和模型名称，再逐步替换原有配置。
跑通第一条请求之后，建议按这个顺序推进：把密钥改为服务器端注入、加上超时与重试、记录每次调用的模型与用量、最后再接入业务逻辑。这样做的好处是，后面即使更换模型或调整接口地址，改动也集中在配置层，不需要翻遍整个项目。
代码已经跑通的话，下一步就是把配置固定下来。你可以到通联注册账号，进入控制台获取 API Key、查看文档中给出的 Base URL 与模型名称，再用同一个 SDK 完成一次最小请求验证，确认无误后再接入生产流程。