OpenRIG 开源AI网关实战：多模型统一接入、路由与故障转移

1. 先搞清楚：OpenRIG 是做什么的

这两年做 AI 应用，最让人头大的不是模型能力不够，而是模型太多了。今天用 OpenAI，明天想换 Anthropic，后天客户要求必须走国产模型。每个供应商一套 SDK、一套鉴权、一套计费逻辑，业务代码里全是 if-else 和重复的网络重试代码。我把这个状态叫"裸连时代"。OpenRIG 就是在这个背景下出现的开源方案。

OpenRIG，全称 Remote Inference Gateway，远程推理网关。你可以把它理解成 AI 模型接入层的"路由器"：业务侧只管按照 OpenAI 兼容格式发请求，OpenRIG 在中间负责把请求分发到真正的模型供应商那里，再把结果统一拿回来。后端接的是 OpenAI、Anthropic、DeepSeek、通义千问还是本地 vLLM，对业务侧完全透明。它要解决的核心问题就三个：多模型统一接入、故障自动转移、成本与用量集中统计。

这篇文章的目标读者很明确：正在做 AI 应用开发的工程师、在搭建企业内部 AI 中台的技术负责人、以及手上同时握着好几个模型供应商 API 的个人开发者。哪怕你现在只需要一家供应商，我也建议你看完后面的路由和故障转移部分——因为接入第二家、第三家供应商时的痛苦，从第一天起就该被设计掉。

下面不聊虚的，从设计思路到配置参数，再到我实际跑起来踩过的坑，都会给你一份可以直接抄作业的参考。不同版本的配置写法可能有细微差异，但核心思路是通用的。

2. 核心设计拆解：为什么需要网关这一层

2.1 裸连 API 到底有多痛

先说清楚没有网关时的状态。假设你的业务要支持 GPT-4o、Claude Sonnet 和国产的 Qwen-Max 三个模型，裸连的话，你需要写三套客户端：三个供应商的 API 格式不一样，认证方式不一样（有的用 Bearer Token，有的把 API-Key 放在自定义 Header 里）；超时重试逻辑要写三遍，每个供应商的限流阈值还不一样；报错格式五花八门，有的返回 429 限流，有的返回 500 内部错误，还有的直接挂起不响应。

更头疼的是统计。想算"今天每个模型花了多少钱"，你得自己拼三个账单，而且各家 token 计数口径还不统一，对账对到怀疑人生。这还没完：某一天供应商 A 故障了，你想切到供应商 B，需要改配置、发版本，运气好是十分钟，运气不好是重新部署、排队审批。

这些问题不是靠写代码"认真一点"就能解决的，它们本质上是架构问题。业务层需要的是一个抽象的模型接口，而不是绑定任何一家供应商。OpenRIG 这一层的价值就在这里：把变化挡在网关外面，让业务代码始终保持稳定。我经常跟同事打比方，这就是"插座思维"——你家的电器只需要认准插座规格，至于背后是水电还是核电，电器不关心。

2.2 OpenRIG 的设计原则

我自己拆解过这类网关的设计，核心原则其实就这几条。

第一条是协议去供应商化。不管后端接的是什么，对前端只暴露一套 OpenAI 兼容的/v1/chat/completions接口。现在这套格式基本是事实标准了，SDK 生态直接复用，业务代码不需要为了接入 OpenRIG 而引入新依赖。这也是它能做到"改一行 base_url 就接入"的前提。

第二条是路由与治理分离。路由规则、权重、优先级都是配置项，不是代码逻辑。这意味着调整某个模型的流量比例，改 YAML 就能实现，不用重新编译、不用发版本、不用半夜起来改代码。跑在网关上的规则，就应该像交换机上的路由表一样，是热更新、可审计的。

第三条是可观测性内建。网关层是唯一的流量出入口，在这个位置做 token 计量、耗时统计、错误率统计，成本极低，效果却是业务侧无法做到的。这也是网关区别于普通反向代理的关键点——代理只看请求转发没转发，网关要管"转发得好不好、花了多少钱、慢在哪一段"。

2.3 和同类方案的简单对比

OpenRIG 不是唯一的方案，市面上常见的还有 one-api、LiteLLM 这类项目，各有侧重。我在选型的时候做过一轮对比，整理了一张表：

我没有说哪个绝对好，关键是看你要什么。如果你要的是"给团队内部做一个统一模型入口，要稳定、要能写进基础设施即代码的配置仓库里"，OpenRIG 这种配置驱动、没有重后台的设计会舒服很多。如果你要做的是对外分发 token 的运营系统，那 one-api 的管理后台更成熟。我选 OpenRIG 就是因为它"安静"——不抢业务视线，默默把流量管好。

3. 关键功能与配置实操

3.1 多供应商接入配置

OpenRIG 的配置主体是供应商（provider）和路由（route）。先看最基础的供应商配置。我实际使用的配置大概是这样的：

# config.yaml server: listen: ":8080" api_key: "sk-openrig-master-key" # 网关对外统一鉴权 providers: openai: type: openai base_url: "https://api.openai.com" api_key: "${OPENAI_API_KEY}" # 支持环境变量注入 models: [gpt-4o, gpt-4o-mini] anthropic: type: anthropic base_url: "https://api.anthropic.com" api_key: "${ANTHROPIC_API_KEY}" models: [claude-sonnet-4-20250514, claude-haiku-4-20250514] qwen: type: openai-compatible # 国产模型多数走这个类型 base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1" api_key: "${DASHSCOPE_API_KEY}" models: [qwen-max, qwen-plus]

这里有三个细节值得注意。

第一，type字段很关键。OpenAI 原生用type: openai，而走 OpenAI 兼容协议的服务（现在绝大多数第三方和国产模型都兼容了）统一用type: openai-compatible，只需要改base_url。这样新接入一个供应商的成本，从写一套客户端降低到改几行配置，整个流程几分钟搞定。

第二，密钥不要直接写在配置文件里。${OPENAI_API_KEY}这种环境变量引用是基本操作，因为配置大多会进 Git，密钥一旦入库，泄露只是时间问题。我在团队里强制要求：仓库里只能出现 placeholder，真密钥走 CI 变量或部署环境的 secret 管理，这个习惯救过我们好几次。

第三，模型列表建议显式声明，不要用models: "*"这种通配符。显式声明的好处是网关可以做模型白名单校验，避免有人在你网关里调用你没开通的模型。我遇到过一次同事误配导致调用了一个价格极高的模型，月底账单出来的时候，大家表情都凝固了。

3.2 路由策略：流量是怎么分发的

接入多个供应商之后，最常问的问题是：同一个模型在两家都能用，我到底调谁？OpenRIG 的路由规则支持按模型名、按权重、按优先级、按成本排序这几类策略。我实际用下来最顺手的配置是这种：

routes: - model: "gpt-4o" strategy: type: weight targets: - provider: openai weight: 80 - provider: azure-openai # 在 Azure 也配一套同模型做分流 weight: 20 fallback: - provider: qwen model: qwen-max

这段配置的意思很直白：gpt-4o的流量默认 80% 走 OpenAI 官方、20% 走 Azure 上的同模型；如果这两条路都不可用，自动降级到 Qwen 的qwen-max。

我当时在设计路由时最看重的是可解释性。流量为什么走到某个供应商，必须能从配置里直接看出来。所以策略字段我坚持用显式声明而不是写代码分支——权重、优先级、成本目标都是配置项，哪天老板说"把便宜的模型流量调大一点"，改个数字就行，不需要重新发版本。

还有一个常用策略是按成本优先：strategy: { type: cost, order: asc }，网关会按各供应商的单价，自动把请求发到最便宜的那家。这个我没当默认策略用，因为"最便宜"不等于"最稳定"。我一般在生产环境用权重策略，在预算敏感的内部工具上用成本策略。生产求稳，内部求省，这是两个不同的场景。

3.3 故障转移与重试：稳定性是怎么保证的

网关存在的另一个重大意义是故障转移。我经历过一次某主流供应商大面积超时的故障，当时如果没有 OpenRIG 这层自动切换，业务就是全站瘫痪。OpenRIG 里控制故障转移的核心参数是这几组：

route_defaults: timeout: 60s # 单次请求总超时 connect_timeout: 5s # 建连超时，快速失败用 max_retries: 2 # 同一目标的最大重试次数 retry_backoff: 500ms # 重试退避 retry_on_status: [429, 500, 502, 503, 504] circuit_breaker: failure_threshold: 5 # 连续 5 次失败则熔断 cooldown: 30s # 熔断冷却 30 秒

重点说两个容易被忽略的细节。

一是超时要分两层。connect_timeout短，是为了在建连阶段快速失败，不把时间耗在黑洞网络上；timeout才是业务认可的整体耗时上限。我之前见过有人只配了总超时 60 秒，结果某个供应商的连接过程就卡了 55 秒，业务端看起来就像"网关很慢"。把建连超时单独压到 5 秒以内，问题立刻暴露。

二是熔断必须配合冷却时间。如果没有熔断，A 供应商已经持续返回 503 了，网关还是每次都"勇敢地"重试它，每个请求都白白等一次超时。熔断相当于给故障供应商一个"隔离期"，冷却 30 秒后再试探恢复。这个值不能太小，否则刚熔断就放流量，还是会被打挂；也不能太大，否则供应商恢复后不能及时接回来。我目前用 30 秒是比较均衡的经验值。

3.4 缓存策略：省钱的一层

OpenRIG 还内置了一个经常被低估的模块——响应缓存。LLM 的响应能不能缓存？能，但有讲究。

我踩过的第一个坑是把所有请求都默认开了缓存，结果发现流式输出的对话应用，缓存根本起不了作用。每次对话上下文都不同，key 不命中，反而因为缓存的读写增加了延迟。后来我总结出了适用缓存的三类场景：

• 参数固定的模板化请求：比如产品文案生成的固定 prompt，输入基本不变；
• Embedding 向量请求：同一段文本的 embedding 具有确定性，非常适合缓存；
• 评测与回归测试：跑模型评测时，相同输入重复打分，缓存后结果一致且快速。

OpenRIG 缓存配置是按模型和参数维度控制的：

cache: enabled: true backend: redis # 支持内存和 Redis 两种后端 ttl: 3600s rules: - models: [text-embedding-3-small] ttl: 86400s conditions: temperature: 0 # 只有 temperature=0 才走缓存

这几个字段背后是实打实的经验。temperature=0条件非常重要：大模型在 temperature 大于 0 时是概率采样，同样的输入可能产生不同输出，缓存这种结果会给用户一种"模型抽风了"的奇怪体验。只有确定性的输出（temperature=0 或模型本身是确定性的）才值得缓存。

另外生产环境缓存后端一定要用 Redis。用内存缓存的话，网关一重启缓存全没，高峰期等于缓存穿透，所有请求一起打向上游，开销和延迟立刻上来。别看这是小细节，线上出过一次事你就记住了。

3.5 观测与计量：网关必须自带的眼睛

最后说说可观测性。OpenRIG 会在每个请求完成后记录一条结构化访问日志，关键字段包括：上游供应商、模型名、首 token 延迟、总耗时、输入/输出 token 数、成本估算、状态码。我把它接到 Prometheus 和 Grafana 之后，日常盯的就三块面板：

• 错误率按供应商维度：哪个上游最近 5 分钟错误率超过阈值，立刻告警；
• 成本按模型维度：哪个模型一个月烧掉了团队预算的 60%，一眼就看出来；
• 延迟分布：P50/P95 首 token 延迟，判断是不是某个供应商的冷启动把体验拖垮了。

这一层为什么必须在网关做？因为业务侧各自打点，口径统一不了。比如 A 业务算了重试后的总耗时，B 业务只算第一次请求，那你们在复盘时根本对不上数据。请求从网关进入开始计时，一个请求只在网关记录一笔，这个口径是全公司通用的。我见过太多团队连"模型调用到底花了多少钱"这个数都说不清，最后全凭各业务自己报数，那个画面真是太熟悉了。

4. 从零部署：环境准备到发出第一个请求

4.1 部署方式怎么选

OpenRIG 提供了三种部署方式：Docker 镜像、单一二进制、源码编译。我的建议很简单：有 Docker 环境就无脑用 Docker，没有就下单一二进制。源码编译我只在需要给项目提代码的时候才用，日常使用完全没必要，省得给自己找事。

用 Docker 启动的命令大概是这样的：

mkdir -p /opt/openrig && cd /opt/openrig export OPENAI_API_KEY=sk-xxx export DASHSCOPE_API_KEY=sk-yyy docker run -d --name openrig \ -p 8080:8080 \ -v $(pwd)/config.yaml:/etc/openrig/config.yaml \ -e OPENAI_API_KEY=$OPENAI_API_KEY \ -e DASHSCOPE_API_KEY=$DASHSCOPE_API_KEY \ openrig/openrig:latest

这里有个我实际踩过的坑：配置文件一定要以挂载卷的方式传入，而不是重新 build 镜像。把配置做进镜像虽然"省事"，但你每次改供应商、改路由都得重新打镜像，CI 时间直接翻倍，而且容易出现"开发环境配置混进生产镜像"的事故。挂载卷是配置和镜像解耦的最简单方式，一旦习惯了，你会觉得所有配置都应该这么管理。

4.2 一份能跑通的最小配置

很多人第一次配置容易贪多，上来就配一堆模型和路由。我给的建议是第一版只配两家供应商、一个路由、一条 fallback，跑通了再加。这是最小可用配置的思路，任何复杂系统都该用这种方式起步。

这是我验证过的最简配置：

server: listen: ":8080" api_key: "sk-local-test" providers: openai: type: openai base_url: "https://api.openai.com" api_key: "${OPENAI_API_KEY}" models: [gpt-4o-mini] qwen: type: openai-compatible base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1" api_key: "${DASHSCOPE_API_KEY}" models: [qwen-plus] routes: - model: "gpt-4o-mini" strategy: type: priority targets: - provider: openai priority: 1 fallback: - provider: qwen model: qwen-plus

启动成功后，用 curl 先验证一下网关本身是否通的：

curl -s http://localhost:8080/v1/models \ -H "Authorization: Bearer sk-local-test"

注意这个请求打的是网关，不是 OpenAI。网关这时候应该返回它内部管理的模型列表——也就是gpt-4o-mini和qwen-plus的并集。看到这个响应，说明配置加载和鉴权都正常了。这一步如果失败了，先检查配置文件挂载路径和密钥环境变量，别急着往下走。

4.3 第一个真实请求

验证模型列表之后，发一个真实的对话请求。为了排除流式的干扰，先关掉流式：

curl -s http://localhost:8080/v1/chat/completions \ -H "Authorization: Bearer sk-local-test" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "用一句话介绍你自己"}], "stream": false }'

如果配置没问题，你会得到一个标准的 OpenAI 格式响应。这里有个小技巧：先看响应的外层字段是不是id、object、choices、usage都齐全，再用usage.total_tokens的值去和上游供应商账单对比，确认计量口径没跑偏。

还有一个实用的排查点：如果响应里出现model字段为你配置的 fallback 目标（比如qwen-plus），别惊讶，说明主供应商当前不可用，网关自动走了降级。这其实是网关在干活，你应该感到欣慰，而不是以为配置写错了。我第一次遇到的时候还以为是 bug，查了半天日志才发现是上游限流触发了降级。

4.4 业务侧怎么接入

业务侧的接入方式，一句话总结：把 base_url 改掉，其他什么都别动。无论你用的是 OpenAI 官方 Python SDK、Node.js SDK 还是 HTTP 客户端直连，只需要把 base_url 指到 OpenRIG 的地址，把 api_key 换成网关的 key。

以 Python 的 openai SDK 为例：

from openai import OpenAI client = OpenAI( base_url="http://openrig.example.com:8080/v1", api_key="sk-openrig-master-key", ) resp = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "你好"}], ) print(resp.choices[0].message.content)

注意 base_url 末尾的/v1不能省。OpenAI SDK 会在你给的 base_url 后面直接拼接路径，写少了会导致 404。这个是我见到最多人翻车的地方之一，十个人里至少有三个人会在这一步卡一下。

5. 实战中踩过的坑与排查实录

5.1 流式响应半路断开

症状：stream: true的请求，前端收到的内容是残缺的，断到一半就没了。

排查思路：先判断是网关断的还是上游断的。在 OpenRIG 的访问日志里看该请求的上游耗时和错误码。如果上游耗时短、但状态是 200，而流内容不完整，多半是上游和网关之间的超时设置不一致——上游的 EOF 处理比网关的超时晚到。

我的解决办法是把流式场景下的单块读取超时单独调大，并确认上游的max_tokens没有设得太小导致生成中途就停止。还有一点：不要对 SSE 流做缓冲，网关层如果开启了"攒一批再往下游推"的优化，流式的首 token 延迟会肉眼可见地变差。把流式请求的缓冲关掉，数据到了直接转发，体验会好很多。

5.2 鉴权老是 401

症状：业务侧明明把 key 配置正确了，但请求还是返回 401。

这个坑非常隐蔽。OpenRIG 的 master key 是网关全局鉴权的，但如果你在供应商配置里没有声明models列表，或者请求里的模型名不在对应白名单里，网关在校验时会返回类似 404 或 401 的错误。所以遇到 401，先别怀疑 key，先看请求里的model字段是不是你配置的模型之一。

另外注意api_key在不同层的语义：业务侧发请求用的是网关 master key，网关转发给上游时用的是每个 provider 自己的 key。曾经有同事把这两个 key 搞混了，给网关配了上游的 key，结果前端一直 401，折腾了半天才意识到是配置层级搞错了。

5.3 缓存把动态请求"吞"了

症状：业务侧改了 prompt 里的一个变量，结果返回的还是旧结果。

原因：命中缓存了。缓存的 key 默认包含模型名和消息内容，如果你的业务在系统指令里塞了时间戳、随机数这类"每次都变"的内容，那缓存自然一直不命中，这不是问题；反过来，如果你没告诉业务"这个模型开了缓存"，那业务可能把本该动态生成的请求发过来，然后被缓存策略判定为"相同请求"，返回了陈旧结果。

我的处理方式是：在网关配置里明确哪些模型走缓存、哪些模型禁缓存（用cache.enabled: false按模型覆盖），并且在上游响应里加上自定义响应头，比如X-OpenRIG-Cache: HIT。这样前端或者业务侧调试时一眼就能看出结果是不是缓存返回的，不用靠猜。

5.4 熔断误伤导致流量"饿死"

症状：主供应商明明恢复了，但流量还是一直被切到备用供应商，业务方抱怨模型效果变了。

原因：熔断的冷却时间设得太长了。我起初把冷却时间设成 300 秒，5 分钟的冷却期对故障隔离来说绰绰有余，但如果上游在 1 分钟就恢复了，后面 4 分钟就全在"误伤"。后来我把冷却时间下调到 30 秒，并加了一个"探测请求"机制——冷却结束后放 1% 的流量过去试探，恢复稳定再逐步放大比例。这个策略比单纯的冷却时间控制要平滑得多。

另外不要把熔断阈值设得太低。3 次连续失败这个阈值就意味着一次小抖动就熔断，生产环境会非常敏感。我建议至少是 5 到 10 次连续失败才触发熔断，把偶发的单次超时排除在触发条件之外。

5.5 排查日志的几个实用命令

排查问题时我最常用的手段是实时看网关日志。OpenRIG 支持结构化日志输出到 stdout，本地调试时直接用 grep 过滤就够了：

# 只看某个供应商的所有请求 docker logs -f openrig | grep '"provider":"openai"' # 只看 5xx 错误 docker logs -f openrig | grep '"status":5[0-9]' # 只看某个业务方的请求（按 api_key 前缀过滤） docker logs -f openrig | grep 'apikey_1492'

日志字段里的request_id是排查链路问题的关键。业务侧如果发现了异常请求，把request_id发给网关管理员，用这一条 ID 就能串起"业务请求 → 路由决策 → 上游调用 → 返回"的完整链路。我在团队内部定了规矩：所有涉及模型问题的工单，必须附带request_id，否则不给排查。这个规矩执行一个月之后，大家提工单的质量明显高了，因为人都被逼着自己先看一遍日志了。

6. 根据我的使用经验，最后说几句

上面这些配置和排查方法，都是我在真实项目里跑过、验证过、也翻过车的。如果说有什么最值得强调的体会，那就是：网关不是搭完就结束的东西，它是 AI 基础设施的一部分，要像对待数据库中间件一样对待它。路由策略要随业务调整，熔断阈值要根据实际流量画像修正，缓存规则要跟着模型使用场景变化去做迭代。别指望一套配置用一年，它跟你的业务一样在变。

另外一个对个人开发者很有用的建议：哪怕是单人项目，也建议在本地把 OpenRIG 跑起来，哪怕只接一家供应商。不是因为你需要路由，而是因为这一层给你留了一个"将来接第二家、第三家不用改业务代码"的后路。技术债这东西，提早还的利息低，事后还得非常贵。用 OpenRIG 做统一入口，就是给未来的自己留的一扇侧门，等真正需要开第二扇门的时候，你只需要推一下就行。

如果你自己也遇到过类似的坑，欢迎在评论区聊聊你的排查过程，我猜大概率能互相补上几个盲区。