第三十一轮: 虚拟模型 id(别名 wjd)—— 客户端固定模型名,映射到哪个真实模型由管理员在页面上选

- config: AliasSpec{enabled,target,note} + GatewayConfig.aliases + resolve_alias/alias_of;
  保存期四条硬规则(目标存在 / 必须是文本模型且支持 chat/completions / 不得与真实模型 id 重名 /
  启用却没写 target);停用时跳过 target 校验。别名不进 _model_index —— 必须显式 resolve_alias()。
- main: chat 线(含 batch)入口换 id 转发;messages/responses 打别名 400 指路(不打上游);
  images/videos 明确 400 拒绝;/v1/models 注入别名条目(alias_of + 继承目标能力);
  流式 chunk 统一回显请求名(非别名调用零变化);_log_alias_changes 记指向变更(含谁改的)。
- settings: 面板 aliases 段(按段合并,不提交则沿用原文)+ 渲染 yaml 时带说明注释。
- web: Models 页「虚拟模型 id(别名)」卡片(admin 开关 + 目标下拉,非 chat/completions 置灰;
  member 只读一行);别名不进模型计数/测速列表/模型表;i18n 中英 753/753。
- tests: +8 条(规则与解析/目录继承/chat 端到端/另两线 400 且不打上游/媒体拒绝/测速说明/
  流式唯一模型名/面板往返 + 非法目标 400 不写盘)→ 187 passed / 0 failed。
- 生产: wjd → agnes-3.0-flash;后端 pid 1872300、前端 index-BJNJXWEY.js。
This commit is contained in:
小银 committed 2026-09-18 23:42:34 +08:00
1 parent 0bf607e35f
commit 73dd2053e6
10 files changed
+1251 -321

No files matched your search

+42
View File
@@ -81,6 +81,48 @@ api-gateway/
> Agnes 的图像/视频走自有端点,通过供应商配置里的 `media` 段指定。
## 虚拟模型 id(别名 `wjd`,第三十一轮)
给客户端一个**名字固定**的入口:客户端永远只写 `model: wjd`,实际转发到你选的哪个真实模型
由管理员在网页上决定 —— 上游模型换名字、换版本、换供应商,客户端一行代码都不用改。
**怎么配**:网页「供应商与模型」页有一张「虚拟模型 id(别名)」卡片 → 下拉选目标模型 → 「保存映射」。
**保存即生效**(走 `PUT /config`,不重启网关)。也可以直接改配置文件的 `aliases` 段:
```yaml
aliases:
wjd:
enabled: true # false = 这个 id 不存在(客户端调用得到「未知模型」)
target: opencode/deepseek-v4.1-flash # 必须是已配置的**文本**模型且支持 chat/completions
note: "给客户用的固定入口" # 备注,只给人看;简写 `wjd: opencode/deepseek-v4.1-flash` 亦可
```
**四条边界**(都在保存期校验,手改 YAML 同样拦,不靠前端自觉):
1. **只走 `chat/completions`(OpenAI)格式** —— 用 `/v1/messages`、`/v1/responses` 打 `wjd`
会在入口 **400** 并把目标模型名一并告诉你(网关不做跨格式转换,与三线直传的边界一致)。
因此**目标模型必须支持 `chat/completions`**:页面上其余模型置灰不可选,服务端同样拒绝。
2. **目标必须是存在的文本模型** —— 图像/视频模型在 yaml 里没写 `protocols`、看着像 OpenAI 线,
但真正的调用端点是 `/v1/images/generations` 之类,拿别名去聊天只会把上游 400 转给用户,
所以直接拦掉。别名 id 也不得与真实模型 id 重名。
3. **别名不复制目标的配置** —— 协议线、视觉能力、强制参数(`params`)、定价全部**继承 target**,
只有一份事实来源,改目标就整体切换;别名自己只有 `enabled` / `target` / `note` 三个字段。
4. **别名不是模型** —— 它出现在 `GET /v1/models`(带 `alias_of` 指向真实目标,方便客户端发现),
但不进 `/v1/models/speedtest`(测速请测它的目标模型)、不进模型计数、也不进成本/指标口径
(那些一律记在**真实模型**上)。
**看到的现象**:响应里 `model` 回显客户端请求的名字(`wjd`)、`served_model` 是真实目标
(流式同样口径:元信息帧与每个 chunk 都只报 `wjd`,真实目标只在 `served_model`);
访问日志 `model` / `served` 两列分别记请求名与真实模型,改指向的每次变更都会写一条
`虚拟模型 id 改指向(页面保存(<账号>)/配置热重载): wjd → …` 的日志。
**权限**:读靠登录凭据即可(普通账号在页面上只看到一行只读的映射);**改**只有 `admin` 用
**网页会话**能改(API Key 改不了)—— 沿用 `PUT /config` 既有的 `_require_admin + _require_session`。
> 与第二十七轮删掉的「路由链 / `routes`」无关:那套是**按 API Key 选链路、可多跳**;别名是
> **一对一指针**("这个名字转发给谁")。二者混在一起后没人看得懂配置,所以 `routes` 不会复活,
> 配置里残留的 `routes` 段依旧只告警不解析。
## 配置
所有数据从 yaml 读取,改供应商/模型/端点/熔断/限流只改配置文件,不改代码。