> ## Documentation Index
> Fetch the complete documentation index at: https://vibex.peatboy.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 供应商、路由组与本地网关

> 把模型供应商配置一次，在多个 Agent 之间共享，并用路由组和本地网关管理故障转移。

Vibex 把模型接入拆成四层。先分清它们，配置时就不会迷路：

| 层 | 回答的问题 | 在哪里 |
| - | - | - |
| **Agent** | 谁来做？ | 配置中心 → Agent |
| **模型供应商配置** | 这个 Agent 用哪个供应商、哪套凭据、哪些模型？ | 配置中心 → Agent → 所选 Agent 的详情 |
| **共享供应商（Provider）** | 一套地址、Key 和模型，能被哪些 Agent 和路由组使用？ | 配置中心 → 供应商 |
| **路由组与本地网关** | 多个供应商或模型之间如何排序、失败转移和转换协议？ | 配置中心 → 供应商 → 网关 / 路由组 |

一个 Agent 仍然可以只用一套自己的模型供应商配置，不碰共享供应商。共享供应商和路由组是给“同一套 Key 要服务多个 Agent”和“需要故障转移”的场景用的。

## 配置中心 → 供应商

**供应商**页把每个共享 Provider 只列一次，并显示哪些 Agent 正在使用它。顶部有两个侧栏标签：

* **供应商**：共享的地址、凭据、模型和 Key。
* **路由组**：把多个 Provider 或模型组合成一个 Agent 可请求的名字。

**网关**是供应商页顶部固定的一行，不是独立分区。它显示监听状态、地址、可用 Key、路由组和请求量；点进去管理 Key、路由和超时。

### 新建供应商

点 **新建供应商**，可以：

1. 从内置预设开始。预设覆盖 Anthropic、OpenAI、Google Gemini、DeepSeek、Moonshot Kimi、Zhipu GLM、OpenRouter 等常见厂商，以及官方、中转、本机三类来源。
2. 选择 **自定义**，手动填写名称、API 地址和模型。
3. 从已有 CLI 配置导入：Codex、Claude 或 CC Switch。导入前会显示将要读取的文件和将要创建的 Provider，不会静默覆盖。

新建流程会先问来源，再问字段。预设会预填协议、地址、Key 提示和常用模型；你可以改，也可以从 `models.dev` 目录补充图标和模型信息。

### 供应商设置

| 分组 | 字段 |
| - | - |
| **基本信息** | 名称、类型（官方 / 中转 / 本机）、图标、官网、备注。 |
| **连接** | API 地址、模型列表地址、认证地址、代理、请求头、models.dev ID、自签 TLS。 |
| **模型** | 启用的模型、默认模型、模型接口协议、推理档位、上下文窗口、最大输出 Token。 |
| **行为** | 认证头、是否只通过路由组使用、请求体字段。 |

* **API 地址**是 Agent 或网关真正请求的地址。部分 Agent 会锁定这一项。
* **请求头**支持字面值和内置 `session_id` 变量；`session_id` 会在每次会话启动时填入，适合需要稳定会话头的供应商。
* **请求体字段**以行编辑，不要求你手写 JSON；未知字段不会悄悄覆盖已有配置。
* **只通过路由组使用**会让这个 Provider 不出现在普通模型选择器里，只能作为路由组成员。

### 模型

每个 Provider 有自己的模型列表：

* **拉取模型**从供应商的模型列表地址读取，不写入配置。
* 勾选模型即启用；取消勾选会保留已声明的能力，重新勾选即可恢复。
* 每个模型可以单独声明 **接口协议**（继承、OpenAI Chat、OpenAI Responses、Anthropic Messages、Gemini、Mistral 等）、**推理档位**、**上下文窗口** 和 **最大输出 Token**。
* **默认模型**是这个 Provider 在没有指定模型时使用的模型。
* 模型 id 可以手动添加；预设的模型列表可能过期，但不会被网络静默改写。

> [!NOTE]
>
> 推理档位和上下文窗口是**声明数据**，不会从模型 id 猜测。声明错误会让 Agent 收到它不支持的选项；不确定时留空，让 Agent 使用自己的目录。

### Key

一个 Provider 可以保存多把 Key：

* 默认掩码显示，点眼睛图标可以临时查看。
* **优先** Key 会先被网关使用；失败后按冷却策略切换。
* 每把 Key 可以单独设置模型范围、代理和 token 上限。
* **测试**会真实请求一次供应商接口；**批量添加**一次写入多把 Key。
* Key 失效、冷却中或额度不足时，列表会显示状态，而不是只报一个笼统的错误。

> [!WARNING]
>
> 测试连接、拉取模型和真实会话都会访问供应商网络并可能产生费用。确认地址、Key 和模型后再运行。

## 路由组

路由组把多个成员组合成一个 Agent 可请求的模型名。成员可以是：

* 整个 Provider（供应商组），对外提供成员目录的交集。
* 一个 `(Provider, 模型)` 对（模型组），对外提供一个稳定的模型名。

打开 **供应商 → 路由组 → 新建路由组**：

1. 填写 **名称** 和 **对外模型名**。对外模型名不能包含 `/`。
2. 从下方模型面板添加成员，每个成员选择 Provider 和模型。
3. 调整 **尝试顺序**；网关从上往下尝试。
4. 选择 **策略**（见下表）。
5. 按需设置 **固定对话成员**、**失败时自动切换**、**耐心等待**、**首 Token 超时**、**上下文 Token** 和 **Token 上限**。
6. 在 **Agent** 区域点选允许使用该路由组的 Agent。
7. 用 **试运行** 查看某个请求会落到哪个成员，不会真的发送请求。
8. 保存。

### 策略

| 策略 | 如何选择成员 |
| - | - |
| **按顺序** | 按配置顺序尝试。 |
| **轮询** | 每个请求前进一个成员。 |
| **最少使用** | 选择本地观测到 token 用量最少的成员。 |
| **智能** | 先排除冷却中的成员，再按 p50 延迟、进行中请求数和用量排序。 |
| **最低延迟** | 按 p50，再按 p95。 |
| **加权** | 按权重交错轮转，而不是连续发完一个成员。 |
| **手动** | 只使用你指定的成员，不自动回退。 |

权重在 1–100 之间；切换策略时权重会保留。

### 限制与可见性

* **固定对话成员**：同一对话尽量留在同一个成员上，保住供应商的提示缓存。
* **失败时自动切换**：当前成员失败时直接换下一个；关闭则先询问。
* **首 Token 超时**：流式请求在收到第一个字节前等待多久；超时会尝试下一个成员。
* **耐心等待**：成员冷却时最多等多久再放弃。
* **上下文 Token**：留空时使用最小成员的窗口。
* **Token 上限**：按本地观测的 token 计数，可设每天、每周或每月。
* **不在选择器中显示**：名字仍可调用，但不出现在模型选择器里。
* **作为兜底组合**：隐藏的组合，供其他路由组回退使用。

路由组只拥有路由策略，不拥有 Key。删除一个 Provider 会让引用它的成员显示为缺失，但不会静默删除整个路由组。

## 本地网关

网关是一个只监听 `127.0.0.1` 的 HTTP 端点。使用路由组的 Agent 会指向它，而不是直接指向厂商。它负责：

* 在成员之间排序、冷却、重试和故障转移。
* 在 OpenAI Chat、OpenAI Responses、Anthropic Messages 和 Gemini 之间转换请求与流式响应。
* 按对话保持 Key 和成员选择，尽量不丢提示缓存。
* 记录只含 token、延迟、状态和路由决策的请求台账；不保存提示词、响应正文或 Key。

网关页有四个标签：

| 标签 | 内容 |
| - | - |
| **概览** | 状态、地址、可用 Key、路由组、请求量、成功率、p50/p95、输入/输出/缓存 token、故障转移、进行中请求、请求最多的供应商和模型。 |
| **Key** | 每个上游 Provider 的 Key、优先 Key、启用/停用、替换、批量添加、token 上限和冷却状态。 |
| **路由** | 实时路由图、请求记录、筛选、分页、重放一次请求的路径。 |
| **设置** | Token 上限、协议转换、错误率/延迟告警、连接/请求/流空闲超时、各类冷却时间。 |

### 网关状态

| 状态 | 含义 |
| - | - |
| **运行中** | 端口已绑定，至少一个路由组可服务。 |
| **降级** | 端口仍在监听，但某些路由组在连续失败后暂时退让；其他路由组继续服务。 |
| **不可用** | 端口绑定失败或服务已停止；直接 Provider 不受影响。 |
| **已停用** | 你关闭了网关；所有路由组暂时不可用，但配置保留。 |

关闭网关不会删除 Provider、路由组或 Key；重新打开后会重新绑定端口并恢复路由组。

### 请求台账与重放

**路由**标签记录最近的请求：时间、请求的模型、命中的路由组、实际成员、状态、延迟、token 和错误。可以按时间范围、状态和路由组筛选，也可以打开一次请求查看它的路由路径。

**重放**只重建当时的候选顺序和决策，不会再次向上游发送请求。实时路由图只显示网关当前处理的请求；直接 Provider 不经过网关，所以不会出现在图里。

## 在会话中使用

发送消息前，在输入框顶部选择：

* **Agent**：谁来做。
* **供应商配置**：这个 Agent 用哪套配置。
* **模型**：具体的模型或路由组对外模型名。
* **思考深度**：由 Agent 和模型声明决定。

如果 Agent 绑定的是路由组，请求会经过本地网关；如果绑定的是直接 Provider，请求不经过网关。切换只影响后续运行，已有时间线保留原来的运行身份。

## 安全与限制

* 网关只绑定回环地址，不监听局域网或公网；需要远程使用时，让运行时跑在远程机器上，通过 SSH 隧道或 Remote v2 访问。
* 网关不保存提示词、响应正文、Key 或账号密码；台账只记录 token 和路由元数据。
* 路由组不拥有 Key，删除 Provider 不会删除 Key 本身。
* 没有成本、余额、预算或配额管理；token 上限是本地观测计数，不是供应商账单。
* 路由组只能在桌面端或 TUI 的管理页编辑，移动端只读。
* 协议转换覆盖文本、图片、工具调用和流式响应；供应商特有的非标准字段可能被丢弃，遇到问题时先用 **测试** 和请求台账确认。

## 故障排查

| 现象 | 处理 |
| - | - |
| 模型选择器里看不到共享 Provider | 检查它是否勾选了 **只通过路由组使用**，以及当前 Agent 是否绑定了它。 |
| 路由组显示“没有可用 Key” | 到网关 → Key 检查成员 Provider 的 Key 是否启用、是否在冷却。 |
| 网关显示“不可用” | 检查端口是否被占用；关闭网关再打开会重新绑定。直接 Provider 仍可使用。 |
| 请求总是落到同一个成员 | 检查策略是否为 **手动** 或 **按顺序**，以及是否开启了 **固定对话成员**。 |
| 首 Token 很慢 | 调整首 Token 超时和耐心等待；查看请求台账里的 p50/p95。 |
| 协议错误或工具调用失败 | 确认模型的接口协议声明正确；必要时在 Provider 设置里改为继承或指定协议。 |
| 删除 Provider 后路由组报错 | 路由组成员引用了已删除的 Provider；编辑路由组，移除或替换该成员。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.