在开发 AI 应用时，很多人会遇到这样的问题：
- 已经拿到了 API Key，但不知道如何在 Python 项目中调用
- 原来的代码使用 OpenAI SDK，想切换到其他兼容接口
- 修改了
base_url，请求却一直返回 401、404 或 429 - 本地测试能够运行，换到服务器后却出现连接超时
如果你也遇到过这些问题，本文会从一个最小可运行的 Python 示例开始，逐步介绍 API 接入、参数配置和常见错误排查。
本文使用 OpenAI Python SDK 演示。示例适用于提供 OpenAI 兼容 Chat Completions 接口的服务，具体支持的模型和接口路径需要以服务商文档为准。
一、先理解三个核心参数
在调用 API 之前，需要准备好三个信息。
| 参数 | 作用 | 示例 |
|---|---|---|
api_key | 请求鉴权 | 你的 API Key |
base_url | API 服务的基础地址 | https://api.example.com/v1 |
model | 指定要调用的模型 | 文档中列出的模型 ID |
这里需要特别注意 base_url。
如果你使用的是 OpenAI 官方接口，通常可以使用 SDK 默认地址；如果使用其他提供 OpenAI 兼容接口的服务，则需要按照服务商的接入文档填写对应地址。
兼容接口不等于所有功能完全一致。 不同服务对模型名称、流式输出、工具调用和多模态参数的支持可能有所区别。
二、安装 Python SDK
首先，确认本地已经安装 Python，然后执行：
python -m pip install --upgrade openai
可以使用下面的命令检查 Python 版本：
python --version
本文使用 openai Python SDK 的客户端调用方式。旧版示例中可能出现 openai.ChatCompletion.create()，而新版本推荐通过 OpenAI() 创建客户端。
三、配置 API Key 和接口地址
不建议把 API Key 直接写进代码，更不要将真实密钥提交到公开代码仓库。
可以通过环境变量管理配置信息。
macOS 或 Linux 终端中执行：
export AI_API_KEY="替换成你的API密钥"
export AI_BASE_URL="https://api.example.com/v1"
export AI_MODEL="替换成服务商支持的模型ID"
以上地址和模型名均为示例，请替换成实际服务商提供的信息。
Windows PowerShell 可以使用：
$env:AI_API_KEY="替换成你的API密钥"
$env:AI_BASE_URL="https://api.example.com/v1"
$env:AI_MODEL="替换成服务商支持的模型ID"
这些设置只对当前终端会话生效。若重新打开终端，需要重新设置，或采用适合自己项目的环境变量管理方式。
四、编写第一个 Python 请求
新建 test_api.py，写入以下代码：
import os
from openai import OpenAI
api_key = os.getenv("AI_API_KEY")
base_url = os.getenv("AI_BASE_URL")
model = os.getenv("AI_MODEL")
if not api_key or not base_url or not model:
raise RuntimeError(
"请先设置 AI_API_KEY、AI_BASE_URL 和 AI_MODEL"
)
client = OpenAI(
api_key=api_key,
base_url=base_url,
timeout=30.0,
max_retries=2,
)
response = client.chat.completions.create(
model=model,
messages=[
{
"role": "system",
"content": "你是一个简洁、准确的 AI 助手。",
},
{
"role": "user",
"content": "请用一句话解释什么是 Python。",
},
],
)
print("模型回复：")
print(response.choices[0].message.content)
if response.usage:
print("Token 用量：", response.usage.total_tokens)
运行程序：
python test_api.py
如果终端能够正常输出模型回复，就说明最基本的调用链路已经跑通。
这里有几个值得注意的地方：
api_key用于请求鉴权。base_url决定请求发送到哪个服务地址。model必须是服务端支持的模型标识。timeout用于设置请求超时时间。max_retries让 SDK 对部分可重试错误进行有限次数的重试，但并不意味着所有错误都能自动解决。
如果服务商要求不同的基础地址、请求路径或参数格式，应优先按照其官方接入文档调整代码。
五、常见报错如何排查？
第一次接入 API 时，建议先从请求配置入手，而不是马上怀疑 Python 环境。
| 错误表现 | 常见原因 | 排查方向 |
|---|---|---|
401 Unauthorized | Key 缺失、错误或失效 | 检查密钥是否正确、是否有多余空格 |
403 Forbidden | 权限、账户状态或访问策略限制 | 检查账户权限、模型授权及服务端策略 |
404 Not Found | 地址、路径或模型标识不正确 | 检查 base_url 和接口文档 |
429 Too Many Requests | 请求频率或额度限制 | 查看限流规则、账户余额和配额 |
5xx | 服务端或上游服务异常 | 查看状态信息，适当退避后重试 |
| 连接超时 | 网络、DNS、代理或服务响应问题 | 检查网络连通性和超时设置 |
1. 遇到 401，先检查密钥
确认环境变量已正确设置，并且使用的是对应服务签发的 Key。
不要把密钥直接打印到日志中，也不要在公开帖子里上传包含真实 Key 的截图。
2. 遇到 404，重点检查 base_url
假设服务商文档要求的基础地址是：
https://api.example.com/v1
就不要未经确认地改成：
https://api.example.com/v1/chat/completions
对于使用标准 OpenAI SDK 的 Chat Completions 调用，SDK 通常会根据基础地址拼接相应接口路径。提前把完整接口路径填进 base_url，可能造成重复路径。
当然，不同服务商的地址规范并不完全相同，最终应以对应的接入文档为准。
3. 遇到 429，不要无限重试
429 可能意味着请求频率超过限制，也可能与账户额度或服务商策略有关。
可以先检查：
- 当前账户是否有可用额度
- 模型是否有独立的速率限制
- 是否有多个任务同时发起请求
- 响应中是否包含限流相关信息
如果需要自行实现重试，建议采用指数退避，并设置最大重试次数。对于不确定是否已经执行成功的请求，也要注意重复提交可能带来的成本问题。
六、生产环境还需要注意什么？
上面的代码适合完成第一次调用，但如果准备将其用于真实项目，还需要考虑以下问题。
1. 不要泄露 API Key
不要把密钥写进公开仓库、前端代码或客户端应用。生产环境应使用合适的密钥管理方案，并限制密钥权限。
2. 设置超时和重试策略
网络请求可能失败，但不能无限等待或无限重试。应结合错误类型、请求成本和业务要求制定策略。
3. 记录必要的请求日志
建议记录请求时间、模型标识、耗时、错误类型和可用的 Token 用量信息。不要将 API Key 或不必要的用户敏感内容写入日志。
4. 不要默认所有模型完全兼容
即使两个服务都宣称兼容 OpenAI API，也可能在工具调用、结构化输出、图片输入、流式响应等能力上存在差异。迁移前最好针对实际使用的功能编写测试。
5. 留意实际调用成本
除了单次请求价格，还应考虑输入与输出 Token 计费规则、上下文长度、失败请求处理方式，以及业务代码是否会重复调用模型。
七、如果需要切换 API 服务，代码要改多少？
如果新服务提供兼容的 Chat Completions 接口，并且支持当前使用的模型和参数，通常可以保留大部分业务代码，只调整客户端配置：
client = OpenAI(
api_key=os.environ["AI_API_KEY"],
base_url=os.environ["AI_BASE_URL"],
)
但这并不意味着只改一个地址就一定能够迁移成功。还需要确认：
- 新服务支持的模型 ID
- 接口协议与路径
- 参数和返回格式
- 限流、额度及计费规则
- 超时、稳定性和错误处理要求
对于已有项目，建议先用一个最小测试程序验证，再逐步迁移到实际业务代码中。
总结
通过 Python 接入 OpenAI 兼容 API，核心流程并不复杂：
- 安装对应的 SDK。
- 获取正确的 API Key、Base URL 和模型 ID。
- 使用客户端发起一次最小请求。
- 根据 HTTP 错误信息排查配置、权限、额度或网络问题。
- 在生产环境中补充密钥保护、超时、重试和日志管理。
如果你正在开发 AI 工具、自动化脚本或需要调用多种模型，可以先用这种最小示例验证接入方案，再根据项目需求扩展流式输出、异步请求和工具调用等功能。
如果你希望快速测试不同的模型接入方式，也可以了解支持 OpenAI 兼容接口的 API 服务，例如 [省省Token] 中转。实际使用前，建议先查看平台的接口文档、模型列表、计费规则及服务条款，并用小额请求验证兼容性与响应情况。
欢迎在评论区交流：你在接入大模型 API 时，最常遇到的是 401、404，还是 429？
