---
title: "路由实战"
description: "用模型例外、接口转换、默认模型和思考映射解决常见路由需求。"
version: "zh"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ochub.org/zh/llms.txt
> Use this file to discover all available pages before exploring further.

# 路由实战

这篇教程假设你已经完成[第一个模型供应商](/zh/getting-started/relay)，并能让至少一个工具通过
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。

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

| 模型或模式 | 上游模型名 | 指定接口 |
| --- | --- | --- |
| `claude-*` | 留空 | Anthropic Messages |
| `gpt-*` | 留空 | OpenAI Responses |

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

适合固定接口的情况：

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

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

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

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

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

```text
默认模型：company-model-v2
```

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

适合默认模型的情况：

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

不适合的情况：

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

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

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

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

添加一条例外：

| 字段 | 值 |
| --- | --- |
| 模型或模式 | `claude-*` |
| 上游模型名 | `company-reasoner` |
| 指定接口 | OpenAI Chat |

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

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

## 场景六：统一思考强度

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

| 模式 | 行为 | 建议 |
| --- | --- | --- |
| 自动映射 | 在低、中、高、最大档位与 Token 预算间转换 | 多 CLI 共用上游时优先 |
| 原样传递 | 不改客户端思考参数 | 客户端与上游协议完全一致时 |
| 关闭思考 | 移除或关闭相关参数 | 上游拒绝思考字段时 |

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

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

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

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

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

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

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

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

## 用请求日志验收

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

| 字段 | 用来确认 |
| --- | --- |
| 应用 | 请求是否归到正确客户端 |
| Provider | 是否经过预期模型供应商 |
| 请求模型 | 客户端原始模型或别名 |
| 模型 | 上游返回或实际处理模型 |
| 计价模型 | 当前价格表套用的模型 |
| 状态 | HTTP 请求是否成功 |
| 首 Token | 开始产生内容前的等待 |
| 持续时间 | 完整请求耗时 |
| 错误信息 | 鉴权、路由、模型或上游错误 |

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

## 故障定位表

| 现象 | 可能原因 | 下一步 |
| --- | --- | --- |
| 404 且所有接口检测失败 | Base URL 包含了完整终点或多余 `/v1` | 改为上游 origin / 前缀后重测 |
| `no gateway channel serves model` | 模型例外、接口或模型匹配后无候选 | 检查规则模式和启用接口 |
| 模型未改写 | 没命中规则或规则顺序不对 | 用精确模型测试，并把精确项放前面 |
| 默认模型未生效 | 请求命中了另一条例外 | 检查该例外是否应删除或填写上游模型 |
| 普通文本成功、工具调用失败 | 协议转换或上游能力不完整 | 优先启用客户端原生接口 |
| Codex 压缩失败 | 没有 Responses 上游 | 启用 Responses 或关闭相关能力 |
| 延迟突然升高 | 接口转换、思考预算或上游状态 | 对比请求详情与备用模型供应商 |
| 成本为 0 | 计价模型没有价格 | 按[计费配置](/zh/advanced/pricing)补齐 |

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

Source: https://docs.ochub.org/zh/advanced/routing-recipes/index.mdx