完整文档索引见 llms.txt。在任意 URL 后追加 `.md` 即可查看该页面的 Markdown 版本。

OpenAI-compatible API

一旦 LLM 运行起来，你就需要一种标准方式与它交互。这正是 OpenAI-compatible API 发挥作用的地方。

什么是 OpenAI-compatible API？

OpenAI-compatible API 指的是任何复现 OpenAI 常见接口、请求/响应 schema 以及认证约定的 API。虽然 OpenAI 并未正式将其定义为行业标准，但其 API 已经成为 LLM 领域事实上的标准接口。

ChatGPT 在 2022 年末的崛起展示了这种方式既强大又易于使用：

清晰且文档完善的 API 让开发者能够轻松基于 LLM 构建应用。
像 gpt-4o 这样的模型可以通过简单且一致的 endpoint 访问。

因此，它在各个行业中迅速获得采用，并带动了生态系统增长。

为什么兼容性很重要？

尽管 OpenAI 的 API 帮助启动了 AI 应用开发浪潮，但它们的广泛采用也带来了生态锁定。许多开发者工具、框架和 SDK 现在都是围绕 OpenAI schema 专门构建的。如果你想要做以下事情，这就会成为问题：

切换到不同模型
迁移到 self-hosted 部署
尝试新的 inference provider

在这些情况下，为适配新 API 而重写应用逻辑可能既繁琐又容易出错。

OpenAI-compatible API 通过以下方式解决这些问题：

Drop-in replacement：将 OpenAI 托管 API 替换为你自己的 self-hosted 或 open-source 模型，通常无需修改应用代码。
Seamless migration：在不同 provider 或 self-hosted 部署之间迁移时，尽量减少中断。
Consistent integration：保持与依赖 OpenAI API schema 的工具和框架兼容（例如 chat/completions、embeddings endpoints）。

许多 inference backends （例如 vLLM、SGLang 和 MAX）都开箱即用地提供 OpenAI-compatible endpoints。这使得在不修改客户端代码的前提下切换不同模型变得更容易。

如何调用 OpenAI-compatible API

许多兼容服务器都以 Chat Completions API 为目标，因为它已被现有 SDK 和框架广泛支持。OpenAI 官方文档现在建议新的 OpenAI 托管应用优先使用更新的 Responses API，但不同 serving framework 对 Responses 的兼容覆盖并不一致。

你可以像下面这样，将现有 OpenAI 客户端指向 self-hosted 或其他 provider 的 Chat Completions endpoint：

from openai import OpenAI

# Use your custom endpoint URL and API key
client = OpenAI(
    base_url="https://your-custom-endpoint.com/v1",
    api_key="your-api-key"
)

response = client.chat.completions.create(
    model="your-model-name",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "How can I integrate OpenAI-compatible APIs?"}
    ]
)

print(response.choices[0].message)

请注意，OpenAI API 要求提供 api_key 字段。大多数 inference framework 不会校验这个值，因此你可以传入任意内容，例如 api_key="EMPTY"。

你也可以直接通过简单的 HTTP 请求调用 API。下面是一个使用 curl 的示例：

curl https://your-custom-endpoint.com/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-name",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "How can I integrate OpenAI-compatible APIs?"}
    ]
  }'

如果你已经在使用 OpenAI SDK 或 REST 接口，通常可以直接把它们重定向到你自己的 API endpoint。这样你既能保留对 LLM 部署的控制权，又能降低 vendor lock-in。

流式响应

设置 stream=True，即可在 token 生成过程中逐步接收输出。这对于聊天 UI 以及任何对延迟敏感的应用都很有用。

from openai import OpenAI

client = OpenAI(
    base_url="https://your-custom-endpoint.com/v1",
    api_key="your-api-key"
)

stream = client.chat.completions.create(
    model="your-model-name",
    messages=[
        {"role": "user", "content": "Write a short poem about streaming."}
    ],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

具体的 streaming schema 会因你使用的 framework 而不同。请始终查阅其官方文档。

列出可用模型

大多数 OpenAI-compatible 服务器也实现了 /v1/models endpoint。你可以用它来发现后端接受哪些 model 名称：

from openai import OpenAI

client = OpenAI(
    base_url="https://your-custom-endpoint.com/v1",
    api_key="your-api-key"
)

for model in client.models.list().data:
    print(model.id)

或者使用 curl：

curl https://your-custom-endpoint.com/v1/models \
  -H "Authorization: Bearer your-api-key"

将返回结果中的任意 id 用作 chat completion 请求里的 model 字段即可。请注意，并不是每个 framework 都会暴露这个 endpoint。

大多数兼容 endpoint 也接受常见的 LLM inference parameters，例如 temperature、top_p 和 max_tokens。不同 provider 和 self-hosted backend 的支持情况不同，因此在生产环境使用前，请确认你的服务器实际接受哪些字段。

常见问题