路由实战

这篇教程假设你已经完成第一个模型供应商，并能让至少一个工具通过 OcHub 发出请求。下面每个场景只增加一层规则，便于在请求日志中判断是哪一步改变了结果。

先理解请求顺序

一次转发请求会经过以下决策：

1. 识别客户端使用的接口：Anthropic Messages、OpenAI Chat 或 OpenAI Responses。
2. 查找当前应用所连接的模型供应商。
3. 用客户端模型名匹配第一条模型例外。
4. 决定发送给上游的模型名。
5. 在该模型供应商已启用的接口中选择候选。
6. 优先使用客户端原生接口；不可用时尝试可转换的其他接口。
7. 映射或移除思考参数。
8. 记录请求模型、上游模型、计价模型、Token、状态和延迟。

模型供应商 API 地址应填写上游 origin 或自定义前缀，不要包含标准推理终点。例如上游最终接口是 https://api.example.com/v1/messages，通常填写 https://api.example.com。OcHub 会根据 已选择接口拼接 /v1/messages、/v1/chat/completions 或 /v1/responses。

模型名的优先级

默认模型和模型例外同时存在时，使用以下规则：

这意味着一条“只指定接口、模型名留空”的例外会保留客户端模型，而不会继续套用默认模型。 它适合限制协议，但也可能让原本想统一到默认模型的请求绕过覆盖。

模型模式支持 * 通配符，例如 claude-*、*-reasoning 或 gpt-*-mini。多条规则可能命中 时，先匹配列表中靠前的规则，因此把精确模型放在通配规则之前。

场景一：把客户端别名改成上游模型

目标：客户端继续请求熟悉的 claude-sonnet-current，上游实际使用 anthropic/claude-sonnet-4-6。

1. 编辑目标模型供应商。

2. 展开“模型例外”。

3. 点击“添加例外”。

4. “模型或模式”填写 claude-sonnet-current。

5. “上游模型名”填写 anthropic/claude-sonnet-4-6。

6. “指定接口”先保持“自动选择”。

7. 保存后发起一条使用别名的请求。

8. 在请求详情中确认：

   • 请求模型是 claude-sonnet-current。
   • 实际模型或响应模型是上游 ID。
   • 计价模型符合你的定价来源设置。

如果上游返回的模型名仍是别名，不一定代表改写失败；部分上游会回显客户端名称。最终以 供应商后台日志和 OcHub 的请求详情共同判断。

场景二：让 Codex 使用 Chat-only 上游

目标：Codex 发出 OpenAI Responses 请求，但商业模型供应商只提供 Chat Completions。

1. 新增或编辑模型供应商。
2. API 地址填写 Chat 上游的基础地址，不包含 /v1/chat/completions。
3. 在“可用接口”中只启用 OpenAI Chat。
4. 保存模型供应商，并在 Codex 页面切换到它。
5. 不添加模型例外，先让自动路由完成 Responses → Chat 转换。
6. 重开 Codex，发起不依赖特殊 Responses 能力的短请求。
7. 在请求日志中核对状态、模型与输出。

普通模型请求可以转换，但以下能力不能假定可用：

• Codex 远程压缩要求 OpenAI Responses 上游。
• 上游不认识的 Responses 专属字段可能被移除或无法等价转换。
• 工具调用、结构化输出和推理参数是否等价取决于上游实现。

如果上游后来提供 Responses，重新检测并同时启用 OpenAI Responses。自动路由会优先选择 Codex 原生的 Responses 接口。

场景三：按模型族固定接口

目标：同一个上游同时开放多个协议，Claude 模型走 Messages，GPT 模型走 Responses。

先在模型供应商里检测并启用两个真实可用接口，然后添加：

保存后分别发起两个请求。因为上游模型名留空，OcHub 只固定接口，不改写模型。

适合固定接口的情况：

• 上游同一模型只在某个终点开放。
• 自动检测认为多个接口可用，但供应商文档明确推荐其中一个。
• 某个接口能回复普通文本，却无法正确处理工具调用。

指定接口后，如果该接口被停用，规则会变成无效配置。编辑模型供应商时 OcHub 会要求规则引用的 接口保持启用。

场景四：上游只允许一个模型

目标：无论客户端请求什么模型，都统一发送到 company-model-v2。

最简单的方法是在“高级设置”填写：

默认模型：company-model-v2

不要同时创建宽泛的 * 例外。默认模型只在没有命中例外时生效，已经足够覆盖普通请求。

适合默认模型的情况：

• 内部网关只暴露一个模型。
• 客户端默认模型名称无法修改。
• 临时把多种客户端配置汇总到一个测试模型。

不适合的情况：

• 需要按任务选择不同模型。
• 想发现客户端传错模型名。
• 供应商按模型价格差异很大，却没有同步调整计价模型。

验证时同时检查请求模型与实际模型，避免用量页面看起来全部是客户端别名。

场景五：同时改模型和接口

目标：所有 claude-* 别名都发送到一个 OpenAI Chat 兼容模型 company-reasoner。

添加一条例外：

这条规则同时完成模型改写和 Messages → Chat 转换。保存后用最简单的文本请求验证，再测试 工具调用。出现问题时分两步定位：

1. 暂时把指定接口改为“自动选择”，判断模型名是否可用。
2. 模型可用后再固定 OpenAI Chat，判断协议转换是否有问题。

场景六：统一思考强度

不同 CLI 可能用强度枚举，也可能直接发送 Token 预算。模型供应商提供三种处理方式：

自动映射的四档必须是从低到高递增的正整数。配置方法：

1. 查上游允许的最小、常用和最大预算。
2. 给“低”分配能产生有效结果的最小值。
3. “中”“高”“最大”逐级增加，且不要超过上游限制。
4. 先用中档完成一次请求。
5. 在请求延迟、输出质量和 Token 之间比较，再调整其他档位。

不要只为了获得更长回答而持续提高思考预算。上游可能将推理 Token 计入输出成本，且过高 预算会增加首 Token 等待。

场景七：准备备用模型供应商

OcHub 会在同一个模型供应商的已启用接口之间自动选择和重试，但不会把一个模型供应商的故障 自动切换到另一张模型供应商卡片。

为上游故障准备备用方案：

1. 分别建立“主用”和“备用”两个模型供应商。
2. 两者都完成接口检测和真实请求。
3. 给相同客户端别名配置等价模型映射。
4. 平时把应用连接到主用供应商。
5. 主用供应商异常时，在应用页手动切换到备用供应商。
6. 发起一条短请求并查看日志。
7. 主用供应商恢复后再切回。

故障期间不要同时修改接口、模型例外、思考预算和定价。先恢复可用路径，再逐项修正根因。

用请求日志验收

每次新增规则后，打开用量 → 请求日志，选择刚才的请求：

一次测试只改一个变量，并给请求使用容易识别的短提示。这样日志中即使有多条相近记录，也能 快速定位刚才的验证请求。

故障定位表

规则稳定后，再把同一模型供应商应用到其他工具。每个新客户端都应重新做真实请求，因为“上游 可用”不代表所有客户端协议都能无损转换。