Python 接入 OpenAI 兼容接口：请求封装、流式输出与重试实战

摘要：

本文以 Python 为例，介绍 OpenAI 兼容接口的基本调用方式，涵盖环境变量配置、普通请求、流式输出、HTTP 调用、客户端封装、超时重试及常见错误处理，帮助开发者理解统一接口的实现思路，降低多模型适配成本。

前言

开发 AI 应用时，我们可能需要根据效果、成本和响应速度选择不同的模型。如果每个模型都使用一套独立 SDK，业务代码很容易与特定服务产生较强耦合。

OpenAI 兼容接口提供了一种相对统一的调用方式。只要服务支持相应协议，开发者通常可以复用消息结构和客户端代码，通过配置 API 地址与模型名称完成切换。

本文将从最小示例开始，逐步完成流式输出、客户端封装以及异常重试。

一、OpenAI 兼容接口是什么？

OpenAI 兼容接口是指服务端沿用 OpenAI SDK 常见的请求和响应结构，例如：

1. 使用 Bearer Token 鉴权
2. 通过 model 指定模型
3. 使用 messages 传递对话上下文
4. 通过 stream 控制是否启用流式输出
5. 从 choices 中读取生成结果

典型调用形式如下：

from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",
    base_url="https://your-api-provider.example/v1"
)

response = client.chat.completions.create(
    model="your-model-name",
    messages=[
        {
            "role": "user",
            "content": "你好，请介绍一下自己"
        }
    ]
)

print(response.choices[0].message.content)

不同服务对模型名称、上下文长度和扩展参数的支持可能不同，因此仍需以所使用服务的接口文档为准。

二、准备 Python 环境

本文建议使用 Python 3.9 或更高版本。

安装 OpenAI Python SDK：

pip install openai

检查安装结果：

python -c "import openai; print(openai.__version__)"

不要将 API 密钥直接写入源代码，可以先配置环境变量。

macOS 或 Linux：

export AI_API_KEY="your-api-key"
export AI_BASE_URL="https://your-api-provider.example/v1"
export AI_MODEL="your-model-name"

Windows PowerShell：

$env:AI_API_KEY="your-api-key"
$env:AI_BASE_URL="https://your-api-provider.example/v1"
$env:AI_MODEL="your-model-name"

生产环境可以使用容器密钥、云平台环境变量或专用密钥管理服务保存凭证。

三、发送第一条请求

创建 main.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:
    raise RuntimeError("请设置 AI_API_KEY 环境变量")

if not base_url:
    raise RuntimeError("请设置 AI_BASE_URL 环境变量")

if not model:
    raise RuntimeError("请设置 AI_MODEL 环境变量")

client = OpenAI(
    api_key=api_key,
    base_url=base_url
)

response = client.chat.completions.create(
    model=model,
    messages=[
        {
            "role": "system",
            "content": "你是一名专业的 Python 开发助手。"
        },
        {
            "role": "user",
            "content": "请用 Python 编写快速排序，并说明时间复杂度。"
        }
    ],
    temperature=0.7
)

print(response.choices[0].message.content)

运行程序：

python main.py

这里有三个关键配置：

1. AI_API_KEY：接口访问凭证
2. AI_BASE_URL：兼容接口的基础地址
3. AI_MODEL：实际调用的模型名称

将这些信息放在环境变量中，可以避免切换服务或模型时反复修改业务代码。

四、实现流式输出

聊天应用通常希望在模型生成过程中逐步展示内容，而不是等待完整响应。此时可以启用流式输出：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AI_API_KEY"],
    base_url=os.environ["AI_BASE_URL"]
)

stream = client.chat.completions.create(
    model=os.environ["AI_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "请解释 Python 装饰器的工作原理，并提供一个例子。"
        }
    ],
    stream=True
)

for chunk in stream:
    if not chunk.choices:
        continue

    content = chunk.choices[0].delta.content

    if content:
        print(content, end="", flush=True)

流式输出适用于：

1. 聊天网页
2. 命令行助手
3. 代码生成工具
4. 长文本写作应用
5. 智能客服系统

需要注意，不同兼容服务的流式结束标记和用量统计方式可能存在细微差异，接入时应进行实际测试。

五、不使用 SDK，直接发送 HTTP 请求

如果项目不希望引入 OpenAI SDK，也可以使用 requests 发送标准 HTTP 请求。

安装依赖：

pip install requests

调用示例：

import os
import requests

base_url = os.environ["AI_BASE_URL"].rstrip("/")
url = f"{base_url}/chat/completions"

headers = {
    "Authorization": f"Bearer {os.environ['AI_API_KEY']}",
    "Content-Type": "application/json"
}

payload = {
    "model": os.environ["AI_MODEL"],
    "messages": [
        {
            "role": "user",
            "content": "请用简单的语言解释什么是向量数据库。"
        }
    ],
    "stream": False,
    "temperature": 0.7
}

response = requests.post(
    url,
    headers=headers,
    json=payload,
    timeout=120
)

response.raise_for_status()

data = response.json()
print(data["choices"][0]["message"]["content"])

对应的 cURL 请求形式如下：

curl -X POST "$AI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$AI_MODEL\",
    \"messages\": [
      {
        \"role\": \"user\",
        \"content\": \"请介绍统一模型接口的作用\"
      }
    ],
    \"stream\": false,
    \"temperature\": 0.7
  }"

六、封装可复用的客户端

实际项目中，可以把配置检查和请求逻辑封装起来：

import os
from openai import OpenAI


class AIClient:
    def __init__(self):
        api_key = os.getenv("AI_API_KEY")
        base_url = os.getenv("AI_BASE_URL")
        self.default_model = os.getenv("AI_MODEL")

        if not api_key or not base_url or not self.default_model:
            raise RuntimeError(
                "请设置 AI_API_KEY、AI_BASE_URL 和 AI_MODEL"
            )

        self.client = OpenAI(
            api_key=api_key,
            base_url=base_url,
            timeout=120.0
        )

    def chat(
        self,
        prompt: str,
        model: str | None = None,
        system_prompt: str = "你是一名专业的 AI 助手。",
        temperature: float = 0.7
    ) -> str:
        response = self.client.chat.completions.create(
            model=model or self.default_model,
            messages=[
                {
                    "role": "system",
                    "content": system_prompt
                },
                {
                    "role": "user",
                    "content": prompt
                }
            ],
            temperature=temperature
        )

        return response.choices[0].message.content or ""


if __name__ == "__main__":
    ai = AIClient()

    result = ai.chat(
        prompt="使用 FastAPI 编写一个健康检查接口。"
    )

    print(result)

这样设计后，模型名称和接口地址都由配置控制，调用方只需要关心输入内容。

如果需要切换模型，可以在调用时传入新的模型名称：

result = ai.chat(
    prompt="分析下面这段代码的性能问题。",
    model="another-model-name"
)

七、添加超时、重试和错误处理

网络请求可能因为连接失败、限流或服务端异常而失败。生产环境应设置超时，并对适合重试的错误进行有限次数的重试。

import os
import random
import time
from openai import (
    OpenAI,
    APIConnectionError,
    APIStatusError,
    RateLimitError
)

client = OpenAI(
    api_key=os.environ["AI_API_KEY"],
    base_url=os.environ["AI_BASE_URL"],
    timeout=120.0
)


def chat_with_retry(prompt: str, max_retries: int = 3) -> str:
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model=os.environ["AI_MODEL"],
                messages=[
                    {
                        "role": "user",
                        "content": prompt
                    }
                ]
            )

            return response.choices[0].message.content or ""

        except (RateLimitError, APIConnectionError) as error:
            if attempt == max_retries - 1:
                raise

            wait_seconds = (2 ** attempt) + random.uniform(0, 0.5)

            print(f"请求暂时失败：{error}")
            print(f"等待 {wait_seconds:.1f} 秒后重试")

            time.sleep(wait_seconds)

        except APIStatusError as error:
            # 参数错误、鉴权失败等 4xx 错误通常不应直接重试
            if 400 <= error.status_code < 500:
                raise

            if attempt == max_retries - 1:
                raise

            wait_seconds = (2 ** attempt) + random.uniform(0, 0.5)
            time.sleep(wait_seconds)

    raise RuntimeError("请求失败")

增加少量随机抖动，可以减少大量客户端在同一时间重新发送请求的概率。

不要无限重试，否则可能造成：

1. 请求堆积
2. 重复计费
3. 用户等待时间过长
4. 上游服务压力进一步增加

对于可能产生副作用的任务，还应配合幂等键或业务状态检查。

八、常见问题

1. 返回 401 Unauthorized

一般表示 API 密钥缺失、无效或没有访问权限。

可以检查环境变量是否存在，但不要在日志中输出完整密钥：

import os

api_key = os.getenv("AI_API_KEY")
print("API Key 是否已配置：", bool(api_key))

1. 返回 400 Bad Request

常见原因包括：

1. 模型名称填写错误
2. 必填参数缺失
3. 参数类型不正确
4. 消息结构不符合要求
5. 当前模型不支持某个扩展参数

排查时可以先保留 model 和 messages 两个核心参数，再逐个加入其他配置。

1. 请求长时间没有返回

首先设置合理的连接和请求超时。对于生成时间较长的任务，还需要确认接口采用同步响应还是异步任务模式。

文本对话通常可以使用同步或流式接口；图片、音频和视频生成服务则可能先返回任务编号，再通过查询接口获取结果。

1. 如何切换模型？

模型名称应通过配置传入：

model = os.getenv("AI_MODEL", "your-model-name")

部署时修改环境变量即可，不需要重新修改和打包业务代码。

1. 所有兼容接口都完全一致吗？

不一定，常见差异包括：

1. 模型命名规则
2. 最大上下文长度
3. Token 用量字段
4. 工具调用支持程度
5. 多模态消息格式
6. 流式响应的附加字段

因此，兼容接口可以降低迁移成本，但正式上线前仍需针对目标模型进行测试。

九、生产环境建议

将示例代码用于正式项目时，建议补充以下能力：

1. 使用安全的密钥管理方案，避免密钥进入代码仓库。
2. 设置连接超时、总超时和最大重试次数。
3. 记录请求编号、模型名称、耗时和错误类型。
4. 不在普通日志中记录密钥和用户敏感内容。
5. 根据业务需求限制输入长度和最大输出量。
6. 对不同模型进行成功率、延迟和输出质量测试。
7. 为服务异常准备降级模型或友好的错误提示。

十、为什么要使用统一接口？

如果一个项目只需要调用单一模型，直接使用相应服务的接口通常已经足够。

当项目需要测试或接入多个模型时，统一接口可以减少重复工作：

1. 降低不同 SDK 的学习成本
2. 统一鉴权和消息格式
3. 减少业务代码修改
4. 方便通过配置切换模型
5. 便于集中记录请求耗时和错误
6. 降低业务逻辑与模型服务的耦合程度

需要注意的是，协议兼容并不意味着能力完全相同。

例如，有的模型支持工具调用，有的模型支持图片输入，有的模型支持结构化输出，还有的模型仅支持部分参数。开发者应根据实际业务进行兼容性测试。

总结

本文完成了以下内容：

1. 使用 Python SDK 调用 OpenAI 兼容接口
2. 通过环境变量管理密钥、接口地址和模型名称
3. 实现普通请求与流式输出
4. 使用原生 HTTP 请求完成调用
5. 封装可复用的客户端
6. 添加超时、有限重试和错误处理

统一接口能够减少多模型接入时的重复工作，但“协议兼容”并不代表所有模型的功能和参数完全一致。生产环境仍需根据实际接口文档，完成兼容性、稳定性和数据安全测试。