OmniRoute 模型字符串冗余路由段剔除机制：Provider-Node 标识符在模型查找前的归一化实践

在 OmniRoute 的网关寻址体系中，模型请求的 model 字段不只承载真实模型名，还经常携带 provider/、connId/、公共前缀（public prefix）等"路由标识符"。当这些标识符因转发、Combo 或别名拼接而出现冗余（例如 <connId>/<connId>/<model>）时，若不做归一化就直接透传，上游厂商将收到一个根本不存在、形如"连接 ID + 模型名"拼缀的伪模型名，进而返回模型不存在的错误。本篇文章围绕 changelog.d/fixes/11557-shed-redundant-routing-segments.md 记录的这一修复展开：讲清路由标识符为什么会出现在 model 字段、修复如何在模型查找（model lookup）之前把已匹配 Provider-Node 的任意路由标识符剔除，并结合仓库源码说明前缀 ↔ 节点映射、模型解析与查找链路的底层实现。

读完你将掌握 OmniRoute 中 provider/model 与 connId/model 两类寻址语法的解析规则、Provider-Node 公共前缀与内部 ID 的关系，以及"查找前先剥离已匹配路由段"这一防透传污染的关键设计思路。

一、背景：为什么聊天请求的 model 字符串会携带"路由标识符"

OmniRoute 是一个多供应商网关，一次请求最终由某个"Provider-Node"（即运营商配置的 openai/anthropic-compatible 兼容节点）或内置供应商接住。为了让请求能够定向到正确的节点，model 字段的书写格式通常是分段的：

• provider/model：以供应商前缀寻址，例如 openai/gpt-4o、anthropic/claude-*；
• alias/model 或裸 alias：命中模型别名，再进行解析；
• 以兼容节点的公共前缀或内部 ID 寻址：例如运营商为节点配置了公共前缀 vibeproxy，则客户端可以用 vibeproxy/<model> 定向到该节点。

关于前缀寻址语法，open-sse/services/model.ts 中 parseModel 的实现与注释可以印证：解析时会先判断 / 属于"供应商前缀还是模型 ID 自身的一部分"，再对 providerOrAlias 做供应商别名解析（见 open-sse/services/model.ts）。注释还明确记录了诸如 xiaomi/、llamacpp/、aq/ 等由内部保留前缀映射到具体供应商的约定（见 open-sse/services/model.ts）。

与此同时，OmniRoute 的聊天入口（src/sse/handlers/chat.ts）在真正执行"模型查找"之前，需要把 model 字符串解析、去重、净化，再交给 getModelInfo/getModelInfoCore 这类函数确定最终的目标供应商与模型。这条解析→归一化→查找的链路，正是本修复的落点所在。

二、问题本质：<connId>/<connId>/<model> 复合串被逐字转发到上游

2.1 Provider-Node 的两种"路由标识符"

从 src/lib/providerNodePrefixes.ts 的文件头注释可以确认，一个兼容的 Provider-Node 在 OmniRoute 中存在两套身份：

1. 内部 ID（internal id）：由系统生成的节点 ID，例如 openai-compatible-chat-<uuid>；
2. 公共前缀（public prefix）：运营商为节点配置的可读前缀（如 vibeproxy），用于在模型覆盖（Model Overrides）、定价目录等表面替代难读的 UUID 内部 ID 进行暴露。

这两者都属于"节点的路由标识符"，都会被用作请求寻址入口，从而可能被拼接进 model 字符串。

2.2 冗余段如何产生：双重作用域叠加

设想客户端已经按某个连接/节点（connId）定向，而该连接的配置、Combo 模板或转发层又把模型的书写形式拼成了"作用域前缀 + 模型"的完整形态。当外层作用域前缀与内层模型自带的作用域前缀恰好命中同一个已匹配 Provider-Node 时，model 就可能变成如下复合形态：

<connId>/<connId>/<model>

即：外层一个 <connId>，随后模型名内部又携带了 <connId>/<model>，结果产生两段重复的同类路由标识符。

2.3 危害：verbatim 透传等于向上游发送"伪模型名"

在修复之前，这段复合字符串会**逐字（verbatim）**进入上游请求。上游厂商只认识真正的模型 ID，<connId>/<connId>/<model> 并不是任何已发布模型，于是请求将以"模型不存在"之类的方式失败。换言之，路由层自己产生的噪音污染了发给上游的语义层字段。

三、修复方案：#11557 —— 模型查找前剔除已匹配节点的路由标识符

针对上述问题，changelog.d/fixes/11557-shed-redundant-routing-segments.md 记录的修复语义如下：

fix(chat)：在模型查找（model lookup）之前，剔除已匹配 Provider-Node 的任意路由标识符（无论是公共前缀 public prefix 还是内部 ID），从而让 <connId>/<connId>/<model> 这类复合串不再逐字到达上游。

这段描述包含三个关键决策点：

1. "已匹配"（matched）是剔除的前置条件：只有当某段前缀被确认指向当前请求实际匹配到的那个 Provider-Node 时，才允许把它从模型字符串中剥掉。这保证不会误删一个恰好与节点前缀同名、但真实模型名的一部分（例如模型 ID 本身含有 vibeproxy/... 子串的合法拼写）。
2. "任意一种路由标识符"都可被剥除：不区分该节点是以公共前缀被寻址，还是以内部 ID（openai-compatible-chat-<uuid> 形式）被寻址，两者都视为该节点的路由标识符，都纳入归一化范围。
3. 剔除时机在"模型查找之前"：先净化和归一化 model，再进入 getModelInfo 一类的查找逻辑，最终向上游暴露的永远只是去掉了路由作用域之后的真实模型名。

从架构视角看，这相当于把"寻址信息"与"语义信息"在到达上游前强制分离：路由段只服务于 OmniRoute 内部把请求送达到正确节点，一旦节点已确定，这些段就对上游失去意义，必须在透传前清除。

四、源码佐证：前缀 ↔ 节点的映射与"保留/唯一/歧义"语义

要理解"哪些段能安全剥除"，先要理解 OmniRoute 如何维护公共前缀与节点之间的映射。src/lib/providerNodePrefixes.ts 是整个仓库中该索引的唯一归属模块，其设计意图在文件头有完整阐述（见 src/lib/providerNodePrefixes.ts）：

• 兼容节点（openai-compatible / anthropic-compatible）可以携带运营商配置的公共 prefix；
• 运行时查找（getModelInfo）会以确定性规则选出"前缀的唯一胜出者"：优先按 ID 升序命中的第一个 openai-compatible 节点，否则取第一个 anthropic-compatible 节点。这一规则被独立成纯函数 selectCompatibleNodeForPrefix，以便目录侧与运行时保持完全一致（见 src/lib/providerNodePrefixes.ts）。

每个配置过的前缀都会被归类为三种状态之一（见 src/lib/providerNodePrefixes.ts 与构建逻辑 src/lib/providerNodePrefixes.ts）：

状态	含义	对路由的影响
reserved	前缀与内置 registry ID/别名（如 cx → codex）冲突	该节点不得作为兼容公开目标对外暴露；请求会被路由到内置供应商
unique	唯一可路由节点独占此前缀	只有该胜出者可被前缀寻址，nodeToPrefix / prefixToNode 双向映射成立，且节点进入 eligibleNodeIds（模型覆盖可用的白名单）
ambiguous	多个节点共享前缀但无运行时胜出者	实际几乎不可达，仅作防御保留

该模块还通过 getReservedProviderPrefixes 同步运行时"保留前缀"的判定，保证用户自定义前缀永远无法遮蔽内置供应商（见 src/lib/providerNodePrefixes.ts）。

这段源码对理解 #11557 的价值在于：所谓"匹配的 Provider-Node 的公共前缀"，指的就是 unique 状态下由 prefixToNode 唯一指向的那个节点所拥有的前缀；而内部 ID 则对应 compatibleNodeIds 中收录的节点 ID。有了这份索引，"某段字符串是否属于当前已匹配节点的路由标识符"就成为一个可以精确判定、可单元测试的纯函数问题，从而让"剔除冗余路由段"具备可靠性基础，不会误伤模型名本身。

五、模型解析链路中的既有归一化防线（#11557 的天然搭档）

在 #11557 之前，OmniRoute 的模型解析已经为"净化 model 字符串"建立了多道防线，修复实际上是嵌入这条链路中、补齐了"去路由作用域"这最后一环。以 parseModel 为例（见 open-sse/services/model.ts），它依次执行：

1. 类型与畸形输入防护：modelStr 非字符串时直接返回空解析结果，避免对象/数组等畸形 Combo 字段在 endsWith("[1m]") 处崩溃（注释中标注了与 #2359 / #2463 同类的缺陷）；
2. 安全校验：拒绝含路径穿越（../、..\）或控制字符的模型字符串，从源头拦截注入式畸形输入；
3. 客户端上下文标签清理：剥离 [1m] 等上下文窗口后缀标记与客户端上下文标签，记录 extendedContext 标志（对应 stripContextWindowSuffix，见 open-sse/services/model.ts）；
4. 跨代理方言归一化：在判断 / 语义之前，先调用 normalizeCrossProxyModelId 把跨代理模型的 provider/model 写法统一，避免把方言化的斜杠误判成前缀分隔符；
5. 精确模型判定：若整个字符串命中精确模型 ID（shouldTreatAsExactModelId），则按"别名/精确 ID"处理，不再按前缀切分；
6. 首斜杠切分：把字符串切为 providerOrAlias + model 两部分，并对前缀做供应商别名解析。

在 parseModel 之上，src/sse/services/model.ts 将本地 DB 能力接入 open-sse 解析核心，并合并 DB 命名空间别名、Settings 精确别名、Settings 通配符别名与自动别名四类数据源（见 src/sse/services/model.ts），最终由 getModelInfoCore 完成供应商与模型的收敛。

可以看到，#11557 所做的"剔除冗余路由段"与上述步骤同处"模型归一化"思想之下：先让 model 字符串收敛成一个无歧义的、仅包含真实供应商前缀与真实模型名的形式，再执行查找；而对那些用于内部寻址、查找结束后便不再需要的作用域段（公共前缀/内部 ID），则不允许其存活到上游请求里。 在解析链路中的精确位置，修复保证了"复合串不再逐字到达上游"这一结果。

六、如何验证与排查此类问题

如果你的部署中出现"上游报 model 不存在，且报错里的模型名带着形如 xxx/xxx/model 或 openai-compatible-chat-.../model 的前缀"，基本可以判定是路由标识符未经归一化便透传。可以按以下思路排查：

1. 确认请求 model 字段的拼写来源：检查是客户端直连、Combo 模板还是反向代理/转发层拼接了 <connId>/ 前缀，避免双重作用域叠加；
2. 检查节点前缀配置：查看兼容节点的 prefix 是否配置、是否与内置保留前缀冲突（对应 src/lib/providerNodePrefixes.ts 的 reserved/unique/ambiguous 分类）；只有 unique 非保留节点的前缀才应作为公开寻址入口；
3. 关注 model 字段的最终形态：OmniRoute 只应把 provider/<真实模型名> 或裸模型名发给上游。若在调用日志里发现带 UUID 内部 ID 或重复连接前缀的模型名进入上游，说明模型查找前的归一化未生效，应回归验证 #11557 所描述的行为；
4. 回归测试：这类修复通常以"构造 X/X/model 复合串 → 断言最终查找到的 provider 与 model、且上游载荷中的 model 字段已被净化"的形式做断言。仓库的 tests/unit 与 tests/integration 目录即用于承载此类模型解析与路由行为的回归用例。

七、小结

#11557 从字面上看只是一个"剪掉多余前缀"的小修复，但它背后是一套清晰的架构原则：

• 寻址层与语义层分离：model 字段中的 Provider-Node 公共前缀、内部 ID、连接 ID 等路由标识符只服务于"把请求送达正确节点"；节点一旦匹配，这些段对上游便失去意义；
• 归一化必须发生在查找之前：任何作用域拼缀都应在模型查找与上游透传前被净化，杜绝 <connId>/<connId>/<model> 这类"路由自指"复合串污染上游请求；
• 剥离必须绑定"已匹配节点"：只有确认段属于当前匹配节点的路由标识符（公共前缀或内部 ID）时才能剥除，从而不误伤模型名本身的合法拼写。

结合 src/lib/providerNodePrefixes.ts 维护的"前缀→唯一胜出节点"索引，以及 open-sse/services/model.ts 的解析/查找链路，OmniRoute 得以在数百供应商的寻址复杂度之上，保证发给上游的永远是干净、真实的模型名。这篇变更记录与源码互相印证，也为排查"上游模型不存在"一类问题提供了一条清晰的诊断路径。