# 模型管理指南

本文介绍如何在 AxonHub 中管理模型，以及如何通过“模型关联”决定请求可以走哪些渠道。

## 核心概念

在 AxonHub 中：
- **模型**：对外提供的抽象模型名，如 `gpt-4`
- **渠道**：实际的 AI 服务商连接
- **模型关联**：把“某个模型请求”关联到“哪些渠道和上游模型”
- **开发者规则**：按模型的开发者统一配置可复用的渠道规则，同一开发者下的模型默认继承

## 模型关联在请求流程中的位置

模型关联是三层流水线中的**中间步骤**。完整说明请参阅 [请求处理流程](../getting-started/request-processing.md#核心概念三层模型设置)。

简单来说：**API Key Profile 改模型名 → 模型关联选渠道 → 渠道改模型名 → 发给上游**

## 模型关联是什么

模型关联的作用，是决定一个模型请求可以落到哪些渠道上。

它本质上回答两个问题：
- 哪些渠道可以参与处理
- 这些渠道上的哪个模型可以作为候选

## 开发者规则继承

如果同一开发者的多个模型应该使用相同的渠道规则，可以在模型列表的开发者分组上配置**开发者规则**。开发者规则只选择渠道或渠道标签，不固定具体上游模型；实际路由时，每个模型会自动使用自己的模型 ID 去这些渠道中查找对应模型。

默认情况下，模型会继承同开发者的开发者规则，并与模型自己配置的规则合并：

- `priority` 数值越小越先执行。
- 同一 `priority` 下，模型自己的规则优先于继承的开发者规则。
- 模型规则弹窗中的“不继承开发者配置”开启后，该模型只使用自己的规则，不再继承开发者规则。

## 常见的模型关联方式

### 1. 指定渠道的指定模型

把一个模型明确指向某个渠道里的某个上游模型。

### 2. 指定渠道的正则匹配

在某个指定渠道中匹配一批模型。

### 3. 所有渠道的指定模型

让同一个模型可以在所有支持它的渠道中使用。

### 4. 所有渠道的正则匹配

在所有可用渠道中按规则匹配一批模型。

### 5. 按标签选择渠道

只在带特定标签的渠道中查找模型，常用于区分生产、测试或供应商分组。

## 优先级

`priority` 值越小，优先级越高。

通常会把更稳定、更希望优先使用的渠道设置为更小的值。

## 常见使用方式

- 想固定走某个渠道：用指定渠道的指定模型
- 想让一个模型在多个渠道里都可用：用所有渠道的指定模型
- 想匹配一批模型：用正则匹配
- 想按环境或供应商分组：给渠道打标签，再按标签选择渠道

## 系统设置

在 **系统设置 > 模型设置** 中，有两个常见选项：

| 设置项 | 说明 |
|--------|------|
| 查询所有渠道模型 | 控制 `/v1/models` 是否返回所有渠道中的模型 |
| 模型未找到时回退到渠道 | 控制未命中模型配置时，是否继续尝试按渠道查找 |

## 常见问题

### Q: 为什么请求提示“模型未找到”？

检查顺序：
1. 模型关联是否配置正确
2. 渠道是否已启用
3. 渠道是否支持关联中指定的模型
4. 是否被其他限制条件过滤掉

如果该模型应该继承开发者规则，还需要确认模型没有开启“不继承开发者配置”。

### Q: 如何验证关联是否生效？

1. 发送测试请求
2. 在控制台查看 Trace
3. 确认请求实际走了哪个渠道

### Q: 同一个（渠道，模型）组合会重复吗？

不会，系统会自动去重。

## 最佳实践

1. **模型名保持稳定**：优先使用统一、可长期维护的抽象模型名
2. **优先级保持简单**：先让主路径明确，再补备用路径
3. **使用标签**：给渠道打标签，方便按环境或供应商分组
4. **先测试再启用**：配置后在控制台验证请求路由是否符合预期

## 相关文档

- [渠道管理指南](channel-management.md) - 配置 AI 服务商渠道
- [API Key Profile 指南](api-key-profiles.md) - 配置模型映射
- [负载均衡指南](load-balance.md) - 了解渠道选择和故障转移
- [请求处理流程](../getting-started/request-processing.md) - 查看完整请求链路