OpenAI-API-compatible(OpenAI API 兼容性)特点

Posted on Views:

在当前的 AI 生态中，OpenAI-API-compatible（OpenAI API 兼容性）已经成为一种事实上的行业标准。它指的是第三方模型提供商或本地推理框架，通过模仿 OpenAI 的接口规范（路径、参数、返回结构），让开发者能够无缝切换模型。

1. 核心特点

  • **标准化的端点 (Endpoints)**：
    通常支持最常用的接口，如 /v1/chat/completions（对话）、/v1/embeddings（向量化）和 /v1/models（模型列表）。
  • 一致的数据结构：
    请求体使用相同的 messages 数组（包含 role 和 content），返回体包含相同的 choices、usage 和 id 字段。
  • 认证模式一致：
    通常使用 Authorization: Bearer YOUR_API_KEY 的 Header 进行身份验证。
  • 流式输出支持：
    普遍支持 stream: true 参数，采用 Server-Sent Events (SSE) 格式。

2. 为什么要使用兼容接口？

低迁移成本（无感替换）

如果你原本的代码是为 GPT-4 写的，只需更改 Base URL 和 API Key，就能直接调用 DeepSeek、Claude（通过中转）、Gemini 或本地的 Llama 3，无需重构逻辑。

生态兼容性

大部分开源工具和框架（如 LangChain, LlamaIndex, Dify, Cursor, AnyType）都默认支持 OpenAI 协议。只要你的接口兼容，这些工具就能“开箱即用”。

本地部署与隐私

通过 Ollama 或 vLLM 在本地部署模型时，开启其兼容模式，可以让你在断网环境下使用那些原本为在线 API 设计的高级客户端。

3. 用法示例

A. Python SDK 用法

你不需要安装新的库，继续使用 openai 官方库即可：

1
2
3
4
5
6
7
8
9
10
11
12
13
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_CUSTOM_KEY",         # 目标平台的 Key
    base_url="https://api.example.com/v1" # 关键：修改为兼容接口的地址
)

response = client.chat.completions.create(
    model="custom-model-name",         # 对应平台的模型名称
    messages=[{"role": "user", "content": "你好！"}]
)

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

B. cURL 调用

直接通过 HTTP 请求访问，结构与 OpenAI 完全一致：

1
2
3
4
5
6
7
8
curl https://api.example.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Hello!"}],
    "temperature": 0.7
  }'

4. 常见的兼容提供商/工具

类型 代表工具/平台
本地推理框架 Ollama, vLLM, LM Studio, LocalAI
云端 API 提供商 DeepSeek, Together AI, Groq, OpenRouter
大厂转换层 Gemini API (已提供官方兼容模式), Azure OpenAI
集成中间件 One API, New API (用于聚合管理多个模型接口)