别名是调用方与后端之间的解耦层
调用方请求里的模型名不应该是某个具体权重目录或实例地址，而是一个稳定的别名，比如对话用途叫 llm-chat、快速响应用途叫 llm-fast。别名到真实后端的映射放在网关的配置里，换模型、换量化版本、换实例组都只改这一处。这样升级对调用方完全透明，回滚也只是把映射改回去，不需要所有接入方配合发版。
基本信息
| 所属层 | 网关的模型路由配置 |
|---|---|
| 别名命名 | 按用途命名（对话、总结、快速），不要按版本号命名 |
| 映射内容 | 别名指向具体后端、模型名与可选参数 |
| 变更方式 | 修改映射表并重载网关配置 |
| 管理要求 | 映射表纳入版本管理与评审，变更留记录 |
典型使用场景
- 模型升级：新版本验证通过后把别名指向新后端，调用方零改动
- 灰度发布：新增一个临时别名指向新版本，小范围流量验证后再切换主别名
- 快速回滚：映射表保留上一个版本，出问题时改一行即可恢复
- 多环境隔离：同一套调用代码在测试与生产通过不同映射指向不同后端
- 混合路由：同一别名背后挂多个后端，按权重或来源做分流
别名映射示意
别名映射示意
# 网关配置：对外别名到内部后端的映射
aliases:
llm-chat: local-32b@v3 # 对外主用对话模型
llm-fast: local-8b@v2 # 低延迟轻量用途
llm-chat-canary: local-32b@v4 # 灰度别名，验证通过后再切主别名
backends:
local-32b@v3: { upstream: http://127.0.0.1:8000, model: "<权重名>" }
local-32b@v4: { upstream: http://127.0.0.1:8001, model: "<权重名>" }命名与管理要点
| 要点 | 做法 | 避免的后果 |
|---|---|---|
| 按用途命名 | llm-chat、llm-summary 这类语义名 | 别名与版本耦合，每次升级都要改调用方 |
| 保留上一个版本 | 映射表中保留可回退的条目 | 出问题只能重建旧实例，恢复时间被拉长 |
| 变更走评审 | 映射修改纳入变更记录 | 一次手改影响所有调用方，无人知道是谁改的 |
| 灰度用独立别名 | 新增别名而非直接改主别名 | 新版本问题直接暴露给全部流量 |
| 注明参数差异 | 映射中标注上下文长度与限流差异 | 调用方按旧假设传参，出现截断或报错 |
映射表要纳入版本管理与评审：改一行就影响所有调用方，变更必须留下时间与原因，出现问题才能快速定位到是哪次调整引入的。
演进用法：灰度时新增别名指向新版本，验证通过后再把主别名切过去，回滚只需改回一行映射，不必重启引擎。