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

# Model Hub

> 一次接入订阅和 API Key，再控制每个 Agent 型号使用哪个来源，以及出错后如何恢复。

Model Hub 是 Avibe 默认的本地模型网关。它把上游凭据和路由留在你的机器上，让多个 Agent 后端共享同一个来源，并在当前来源因可恢复问题无法继续供给时，把请求交给路由链里的下一个来源。

打开 **模型 > 来源与网关**。页面分成两部分：

* **来源**列出你拥有的订阅和 API Key。它是资产清单，不是优先级列表。
* **网关**展示每个 Agent 后端，以及每个型号配置好的精确路由链。

## 选择网关或直连

全新安装默认使用网关模式。已有安装如果还没有 Model Hub 配置，会保持**直连**，直到你在模型页面逐个切换后端。

模式按后端分别设置，并且可以随时切回。切回直连会保留来源和路由链，但该后端会重新使用自己的原生配置。网关路由链里的**原生**跳仍然属于网关模式：这条链的故障切换和恢复仍由 Avibe 管理。

## 添加来源

### 添加订阅

1. 在**来源**里选择**添加订阅**，再选择厂商。
2. 选择凭据保留在哪里。
3. 选择**去登录**，完成厂商登录流程。

推荐选项因厂商而异：

* **Claude：**推荐**原生使用**，由 Claude Code 使用本机登录。你也可以明确选择**登录为网关来源**，把它供给其他 Agent，但 Avibe 会在登录前显示账号可能受限的警告。
* **ChatGPT：**推荐**登录为网关来源**，这样可以看到用量、额度和接管状态。仍然支持 Codex 原生登录，但额度耗尽时不会触发网关接管，用量也不会进入 Model Hub。

每个后端只能有一个原生来源，因为官方 CLI 只暴露一个当前登录。其他账号请添加为网关持有的来源。两种方式可以并存，但需要分两次添加。

### 添加 API Key

1. 选择**添加 API Key**。
2. 输入可选名称、Base URL 和 API Key。自定义 Base URL 可以指向中转、聚合或自建兼容服务。
3. 选择**添加**。保存前，Avibe 会实际连接一次，完成鉴权、识别接口并拉取型号列表。

**拉取型号**会执行同样的检查，但不会保存任何内容。如果 Avibe 已经连通却无法识别接口，请选择一次性的接口提示并重试。这个提示只改变探测顺序；Avibe 仍然要从真实响应中确认接口，才能保存来源。接口一旦保存就固定不变；要更换接口类型，请新建来源。

如果接口已经识别，但型号列表没有返回，你可以重试，或选择**仍要添加**。来源会在没有已发现型号清单的情况下保存，之后可以在来源详情里手动添加型号。

### 维护型号列表

来源添加成功后，Avibe 会打开**来源详情 > 型号**。你可以在这里：

* 选择**重新拉取**，检查已保存的来源、更新健康状态并刷新自动发现的型号。这是已保存来源唯一的刷新动作。
* 在自动发现找不到型号时手动添加。
* 编辑任意自动拉取或手动添加型号所接受的精确推理强度档位。系统不会默认选中或预填任何档位。
* 移除手动添加的型号。上游返回的型号由重新拉取维护。

重新拉取会保留手动型号和你编辑过的推理强度档位。如果新的清单会让已配置的跳失效，Avibe 会先明确列出将被移除的跳和会失去供给的型号，再让你决定是否继续。拉取失败时，页面保留它最后一次真正读到的列表。

## 排列路由链

在**网关**里选择一个后端，再打开要配置的型号。每个型号拥有一条有序路由链。每一跳都是一个精确组合：来源，以及实际要调用的上游型号。

你可以在路由链编辑器里：

* 添加或移除一跳；
* 调整各跳顺序；
* 修改某一跳明确指定的上游型号映射；
* 保存最终路由链。

Avibe 使用第一个当前可运行的跳。如果某一跳已经被阻塞，或在输出开始前遇到允许回退的额度、限流、上游或网络故障，Avibe 才会按你保存的顺序继续尝试后面的跳。被阻塞的跳仍会留在原来的位置并显示为不可用；Avibe 不会悄悄重排，也不会自行替换型号。

添加来源时，Avibe 只会匹配一次已发现的型号，并把每个明确匹配追加到符合条件的路由链末尾。如果找不到唯一明确的匹配，来源仍会保存，但你需要手动把它加入对应路由链。

<Note>
  **来源顺序**和某个型号的路由链不是一回事。修改一个后端的来源顺序，不会改变任何已经配置好的路由链。要改变实际请求顺序，请编辑对应型号的路由链。
</Note>

## 看懂状态

来源行会显示以下状态：

| 页面显示                                    | 含义                                  |
| --------------------------------------- | ----------------------------------- |
| **使用中**                                 | 这个来源已经配置进至少一条路由。                    |
| **备用**                                  | 来源健康，但当前没有供给已配置的路由。                 |
| **暂不可用 · ... 后自动重试**                    | 额度、限流或网络问题让来源进入冷却；Avibe 会在显示的时间后重试。 |
| **需要重新登录**、**余额用完**、**凭据被吊销**或**账号被限制** | 必须由你处理，等待不会让它自行恢复。                  |
| **异常**                                  | Avibe 无法判断具体原因；它不会自动清除。             |

每个网关后端都会针对当前选中的型号显示一种供给状态：

| 页面显示             | 含义                             |
| ---------------- | ------------------------------ |
| **网关 · 正常**      | 预期的第一跳正在供给。                    |
| **网关 · 降级**      | 后面的跳正在供给，或链里有部分来源被阻塞；请求仍然可以完成。 |
| **网关 · 暂时全部在冷却** | 当前没有跳可运行，但所有阻塞都会自动重试。          |
| **网关 · 无可用来源**   | 路由链为空，或至少有一个阻塞需要人工处理。          |
| **网关 · 未选型号**    | 后端处于网关模式，但还没有选中的型号可供汇总。        |

只有当第一跳因可恢复问题不可用、请求交给后面的跳时，页面才会显示**接管中**。成功接管不会在对话里插入通知。模型页面会展示当前来源、暂停的原路径和临时替代来源；第一跳恢复后，下一个回合会自动回到它，而且不会改变你保存的顺序。

## 理解报错并恢复

### 模型页面上的提示

| 提示                                   | 处理方式                                  |
| ------------------------------------ | ------------------------------------- |
| **网关组件未安装 · 点击安装**                   | 打开确认框，再安装并启动组件。除非你另行切换，否则不会改变任何后端的模式。 |
| **网关未启动 · 点击启动**或**网关未运行**           | 启动网关，再重试刚才的操作。网关重新响应前，路由派生信息会保持未知。    |
| **来源列表没读到 · 网关本身正常**                 | 选择**重试**。只有来源列表读取失败，其他网关状态仍然有效。       |
| **后端供给情况没读到 · 网关本身正常**               | 对这个后端选择**重试**。不要仅仅因为这次读取失败就去添加来源。     |
| **鉴权失败：401 Unauthorized**            | 检查或替换 API Key，再重试。                    |
| **地址不对：404 Not Found**或**网络不通：连接超时** | 修正 Base URL 或网络路径，再重试。                |
| **连上了、也通过了鉴权 —— 但认不出它说哪种接口**         | 选择一个接口提示并重试。在真实响应证明接口前，不会保存任何内容。      |
| **接口已经认出来了 —— 但这次没拿到它的型号清单**         | 重试，或选择**仍要添加**并手动维护清单。                |
| **登录没有完成。可以重试。**                     | 重试厂商登录。关闭弹窗会取消 Avibe 正在跟踪的登录流程。       |
| **拉取没有回来，下面是这一页最后一次真的读到的列表**         | 继续使用保留的列表，或选择**重试**。                  |

### 回合里的提示

| 情况                 | Avibe 会说什么                                             | 如何恢复                                  |
| ------------------ | ------------------------------------------------------ | ------------------------------------- |
| 路由链为空              | 提示请求的型号还没有配置路由，并把你引到模型页面。                              | 给该型号的路由链添加一跳。                         |
| 所有跳都在冷却            | 显示等待提示和下一次恢复时间。                                        | 等待即可，Avibe 会自动重试。                     |
| 没有跳可运行，且至少一个阻塞需要处理 | 显示中断提示和已经分类的阻塞原因。                                      | 修复指定来源，或编辑路由链。                        |
| 请求本身不兼容            | **这个请求不兼容；切换来源也无济于事。**                                 | 调整请求、工具、参数或型号，不要通过重排来源解决。             |
| 本地网关在请求过程中停止       | 显示网关故障；如果已经开始输出，还会说明本回合输出可能不完整。                        | 恢复网关后重试。Avibe 不会重放部分输出，也不会把问题归咎于某个来源。 |
| 已经开始输出后来源失败        | 如果另一跳已经成为当前来源：**下一回合已切换来源，请重试。** 否则显示与路由链耗尽相同的等待或中断结果。 | 新开一个回合重试。Avibe 绝不会重放已经部分流式输出的回合。      |
| 你取消回合              | 使用原有的回合取消提示，不附加 Model Hub 供给信息。                        | 准备好后再开始新回合。                           |

### 按原因恢复

* \*\*冷却或接管：\*\*等待页面显示的重试时间。恢复以及回到第一跳都会自动发生，不会改变路由链。
* **订阅登录过期：**按该来源的**需要重新登录**操作处理。
* **余额耗尽：**到厂商处充值，然后打开来源详情并选择**重新拉取**。
* \*\*API Key 被吊销：\*\*在现有来源上替换 Key，再重新拉取。来源身份和所有路由位置都会保留。
* \*\*账号受限：\*\*按厂商给出的方式处理，或把受影响型号移到其他来源。
* **未分类异常：**修复可能的上游问题，再使用**重新拉取**。当前检查成功后会清除阻塞。
* \*\*型号不再受支持：\*\*如果上游仍应提供它，请重新拉取；否则编辑或移除对应的精确跳。
* \*\*来源已不存在：\*\*编辑路由链。重新添加一个来源不会修复仍指向已删除来源的跳。
* \*\*原生 CLI 不可用：\*\*恢复对应后端的本地 CLI 和登录，再重试。
* **需要立即绕开问题：**只把受影响的后端切换到**直连**。来源和路由链会保留，之后切回时仍可继续使用。