TheRouter.aiTheRouter.ai
← 全部文章

什么是 OpenAI 兼容路由？开发者 AI Gateway 入门指南

OpenAI 兼容路由让你用一个端点把任意 OpenAI SDK 的请求分发到多家模型供应商，同时获得 fallback、计费合并和可观测性。本指南解释它的工作原理、选型标准，以及如何在一分钟内完成首次请求。

· TheRouter

大多数团队刚起步时只用一家 LLM 供应商。OpenAI SDK 加一个 API key，调一次 POST /v1/chat/completions，一切正常。然后需求开始增长，第二家供应商负责降低成本或延迟，第三家当主供应商被限速时兜底。代码库里突然出现供应商专用的客户端、分别处理的错误逻辑和三套账单面板。

OpenAI 兼容路由的做法是把自己放在应用和所有供应商之间。你继续用 OpenAI SDK，只改两行代码，base_url 和 API key。路由把请求翻译给你选的供应商，在模型不可用时自动 fallback，并给你一份账单和一套日志。

这篇指南拆解这个兼容层到底做了什么、选型前要看哪几点、以及怎样在一分钟内发出第一个经过路由的请求。

OpenAI 兼容指供应商提供一个 chat-completions 接口，其请求与响应结构与 OpenAI API 契约足够接近——只需替换三个值（API key、base URL、模型名），原来的 OpenAI SDK 调用即可直接工作。最小实践面是POST /v1/chat/completions 带 messages、model， 并返回 OpenAI 形式的流式响应。

OpenAI 兼容是怎么实现的

OpenAI Chat Completions API 已经成为 LLM 请求的事实标准。约定很简单，向 /v1/chat/completions 端点发送一个包含 model、messages 以及可选参数（temperature、max_tokens、tools、stream）的 JSON body，拿回一个包含 choices、usage 和元数据的 JSON 响应。

OpenAI 兼容路由接受完全相同的约定。它在底层做三件事。

  1. 模型解析。model 字段带着供应商前缀，比如 anthropic/claude-sonnet-4.5 或 deepseek/deepseek-chat。路由把它映射到上游供应商的端点和认证信息。

  2. **请求翻译。**多数供应商接受 OpenAI 格式的请求，但细节有差异，比如推理力度的参数名、thinking token 预算、多模态输入格式、tool calling schema。路由在转发前做好标准化。

  3. **响应归一化。**不管哪家供应商实际服务了请求，返回给你的始终是标准的 choices[0].message.content 结构。供应商特有的字段（比如 DeepSeek 的 reasoning_content）在已验证的情况下会被保留。

最终效果是添加供应商、换模型、配 fallback，应用代码一行都不用改。

路由在兼容之外还提供什么

翻译请求格式只是基本功。路由层的实际价值体现在五个方面。

Fallback 和重试

当供应商返回 429（限速）、503（过载）或超时，路由尝试 fallback 链中的下一个模型。你的应用收到一个正常响应，响应里的 model 字段告诉你到底是哪家供应商接了这个请求。

费用追踪

所有请求走同一个端点。路由按模型、按团队、按 API key 统计 input token、output token 和 cached token。不再需要对账三家供应商的仪表盘，一个成本视图就够了。

可观测性

延迟、错误率、token 计数、fallback 事件，全部记录在一个地方。做监控和告警时不用给每家供应商的客户端分别埋点。

访问控制

每个团队或应用一个 API key，key 级别的模型白名单、限速和花费上限。路由用服务器端保存的供应商凭据完成上游认证，团队成员不接触供应商密钥。

Streaming 兼容

不管供应商如何，SSE streaming 的行为都一样。路由把每家供应商的 chunk 格式翻译成标准的 data: {"choices":[...]} 结构。跨供应商 streaming 的细节可以参考跨供应商 streaming 指南。

选型前要看的五件事

不是所有路由都一样好。在生产环境里，这五件事最重要。

1. 兼容深度。 路由能不能正确处理 tool calling、structured output（response_format）、streaming、vision 输入和 reasoning effort 参数？浅层兼容在基本聊天之外就会出问题。

2. 延迟开销。 任何代理都增加往返时间。在你的流量模式下测量 P50 和 P99 的新增延迟。好的路由只加个位数毫秒，差的加几百毫秒。

3. 定价模型。 有的路由按请求收费，有的在供应商成本上加百分比，有的收固定平台费。按你预期的请求量算总成本，包括路由透传的供应商费用。详细对比见 AI model router 定价对比。

4. 供应商覆盖范围。 检查路由是否支持你今天需要的模型和供应商，以及添加新供应商需要改配置还是改代码。

5. 可观测面。 日志、仪表盘和 webhook 告警比功能列表重要。如果你看不到哪些请求触发了 fallback、哪些模型慢、钱花在了哪里，路由就没发挥作用。

快速上手：60 秒内发出第一个路由请求

下面的示例用 TheRouter 做 gateway。TheRouter 把 OpenAI 兼容请求路由到已配置的供应商，支持供应商/模型级别的 fallback。

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.therouter.ai/v1",
    api_key="<THEROUTER_API_KEY>",
)

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.5",
    messages=[{"role": "user", "content": "用两句话解释 LLM 路由是什么。"}],
)
print(response.choices[0].message.content)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.therouter.ai/v1",
  apiKey: "<THEROUTER_API_KEY>",
});

const completion = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4.5",
  messages: [{ role: "user", content: "用两句话解释 LLM 路由是什么。" }],
});
console.log(completion.choices[0].message.content);

cURL

curl https://api.therouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $THEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-chat",
    "messages": [{"role": "user", "content": "LLM 路由是什么？"}]
  }'

和直接调 OpenAI 相比只改了两样东西，base URL 和 API key。SDK、请求结构、响应格式全部不变。

添加 fallback 链

路由的意义在于可靠性。传一个 models 数组来定义 fallback 链，TheRouter 按顺序尝试模型，第一个成功的就返回。

const completion = await client.chat.completions.create({
  model: "openai/gpt-5",
  extra_body: {
    models: ["anthropic/claude-sonnet-4.5", "deepseek/deepseek-chat"],
  },
  messages: [{ role: "user", content: "对这个工单做分类。" }],
});

如果 gpt-5 返回限速错误，路由会尝试 claude-sonnet-4.5；如果也失败，再 fallback 到 deepseek-chat。响应的 model 字段告诉你最终是哪个模型完成了请求。完整 fallback API 见模型 fallback 指南。

常见使用场景

多供应商容灾

用路由最常见的理由。供应商宕机、限速、审核拒绝不是假设，几乎每周都会遇到。Fallback 链把用户面的错误变成透明的重试。

成本优化

低复杂度请求走便宜模型，高复杂度请求用贵的前沿模型。具体的分桶策略见成本优化路由指南。

Coding agent 路由

Cursor、Claude Code、Windsurf 都支持自定义 base_url。把它们指向路由就能控制模型选择、给每个开发者设花费上限、记录每一次请求。逐工具的配置方法见 coding agent API 路由对比。

模型 A/B 测试

按请求属性把流量分给两个模型，比较输出质量、延迟和成本。路由会记录两条路径，应用代码完全不变。

TheRouter 作为 OpenAI 兼容路由

TheRouter 把 OpenAI 兼容请求路由到已配置的供应商，支持供应商/模型级别的路由和 fallback，提供统一的计费和账务面板，支持通过 /v1/jobs/:id 处理异步 media 任务。

它不是唯一选择。OpenRouter、LiteLLM、Portkey 和 Cloudflare AI Gateway 都提供 OpenAI 兼容路由，各有取舍。详细对比见 gateway 横评。

TheRouter 具体做了这些事。

  • 单一端点 https://api.therouter.ai/v1 接受任意 OpenAI SDK 调用
  • 供应商前缀模型 anthropic/claude-sonnet-4.5、deepseek/deepseek-chat、openai/gpt-5、dashscope/qwen3.8-max
  • Fallback 链 通过 models 数组按优先级定义备选
  • Streaming 跨所有路由供应商的 SSE 兼容 streaming
  • Tool calling 转发给支持的供应商，必要时做格式翻译

FAQ

Streaming 经过路由后行为一样吗？ 一样。路由把每家供应商的 SSE chunk 格式翻译成标准的 OpenAI streaming 结构。你的 stream: true 代码不需要任何改动。

Tool calling 和 function calling 支持吗？ Tool calling 会被转发给上游供应商。当供应商的格式不同时，路由负责翻译 tool schema。各供应商的差异见function calling 横评。

供应商特有的响应字段能保留吗？ 已验证的字段（比如 DeepSeek 的 reasoning_content）会被保留。路由不会剥离供应商扩展字段，但也不保证每一个未文档化的字段都能透传。

如果 fallback 链里所有模型都失败了怎么办？ 路由返回最后一个尝试的模型的错误。你的应用收到标准的错误响应，处理方式和直接调供应商一样。

会增加延迟吗？ 任何代理都会增加一些延迟。实现良好的路由在路由决策上增加个位数毫秒。真正决定总延迟的还是供应商的推理时间，通常在几百毫秒到数秒之间。

能用在 Cursor、Claude Code 这类 coding agent 上吗？ 可以。这两个工具都接受自定义 base URL。把它们指向路由端点，请求就走路由层了。逐步配置方法见 coding tools 设置指南。

来源 OpenAI API 文档、OpenRouter, LLM Gateway 解读、TheRouter 快速上手、TheRouter 模型 fallback、LiteLLM GitHub、Cloudflare AI Gateway 文档

帮助与联系