模型别名与映射

把应用发送的模型名解耦为实际调用的上游标识——静态别名（接入密钥级，恒定解析）与动态别名（路由规则级，按作用域条件解析），以及两层组合

模型别名让你把应用发送的模型名与平台实际调用上游时使用的标识解耦。借助别名，你可以：

让应用始终发送 best-model，由平台解析为当前你认定最优的模型——无需改动应用代码；
把一个逻辑名（如 chat-default）映射到某个上游特定的部署名或具体版本标识；
给不同分组、不同子账户在同一个名字背后挂不同的底层模型。

平台提供两种别名机制，作用在不同层次：

	静态别名	动态别名（路由规则）
配置位置	上游接入密钥上	路由规则上，可按全局 / 分组 / 子账户作用域
生效时机	选定接入密钥后、发往上游 API 前	请求时、选定接入密钥前
作用范围	按接入密钥	按全局 / 分组 / 子账户
是否条件触发	否——恒定解析	是——由条件表达式控制何时触发

1. 静态别名

静态别名直接配在某个上游的接入密钥上。凡是由该密钥承接的请求，模型名都会在抵达上游 API 前先经别名表解析一次。

1.1 解析流程

应用发送 model: "best-model"；
平台选定一把支持 best-model 的接入密钥（别名名在准入与密钥选择时被当作模型标识对待）；
调用上游前，平台按该密钥的别名表把 best-model 解析为实际标识；
上游收到实际标识——应用无需感知。

1.2 配置

在登记或变更上游接入时，于接入密钥上附 aliases 映射：

curl https://your-platform/api/v1/providers/<上游标识>/keys \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "name": "<接入密钥显示名>",
    "models": ["*"],
    "aliases": {
      "best-model": "<实际模型标识>",
      "fast-model": "<轻量模型标识>",
      "embedder": "<嵌入模型标识>"
    }
  }'

aliases 是一张扁平的 字符串 → 字符串 映射：键是应用发送的名字，值是转发给上游的实际标识。两侧可以是任意标识——部署名、版本标识、子型号名等，平台不做语义限制。

1.3 校验规则

平台拒绝违反以下任一条的别名表：

规则	说明
不允许空串	别名名与目标标识都不得为空
不允许首尾空白	两侧都不得带前导或尾随空格
不允许重名	同一张表内别名名不得重复（大小写不敏感比较，`Best-Model` 与 `best-model` 不能并存）

别名查找大小写不敏感：若表中有 BEST-MODEL 而请求发 best-model，仍能正确解析。

1.4 响应中的解析痕迹

每条响应都在扩展字段中同时给出原始名与解析后的实际标识，便于客户侧对账核对：

{
  "extra_fields": {
    "original_model_requested": "best-model",
    "resolved_model_used": "<实际模型标识>",
    "routed_provider": "<本次承接的上游>"
  }
}

若没有别名命中，resolved_model_used 等于 original_model_requested。

2. 动态别名

动态别名借助路由规则在请求时按条件表达式改写模型。与恒定解析的静态别名不同，动态别名有条件地触发且带作用域——同一个模型名可以因发起者不同而解析为不同结果。

2.1 作用域使别名"动态"

路由规则按三层作用域、按优先级求值：

子账户作用域  →  分组作用域  →  全局作用域

于是你可以在组织层级的任意一层配别名。例如：

全局作用域把 best-model 解析为某轻量模型（对所有人都成本友好的默认值）；
分组作用域为某高需求分组覆写 best-model 为某旗舰模型（能力更强）；
子账户作用域为某个特定子账户覆写 best-model 为某深度推理档模型（最高能力、专用场景）。

每个发起者在同一个名字背后拿到合适的模型，应用零改动。

2.2 按请求类型改写

{
  "name": "嵌入请求走轻量嵌入模型",
  "expression": "request_type == \"embedding\" && model == \"embedder\"",
  "targets": [
    { "model": "<轻量嵌入模型中性名>", "weight": 1.0 }
  ],
  "scope": "global"
}

凡是 model: "embedder" 的嵌入类请求都被改写到轻量嵌入模型。

2.3 多步改写：规则链

把一条规则设 chain_rule: true，平台会用解析出的上游/模型作为新上下文重新求值整条作用域链。这样可以把"先定上游意图"与"再按子账户定最终模型"分两层组合。下例中所有应用都发送 best-model，按子账户分流到不同模型：

全局规则（chain_rule=true）：best-model → 选定上游 X，重求值
   │
   ▼
子账户A 规则（终止）：在上游 X 上 → 旗舰模型
子账户B 规则（终止）：在上游 X 上 → 标准模型

规则链的终止条件、收敛保护与最佳实践详见路由规则 §6。

3. 两层组合

静态别名与动态别名天然组合——动态别名（路由规则）先在请求路径前段触发，静态别名（接入密钥级）在选定密钥后解析。这让你把两件事分到两层：

层	负责
路由规则（动态别名）	按发起者决定走哪个上游、用哪一档接入密钥
接入密钥别名（静态别名）	决定最终转发给上游的实际模型标识

一个组合解析路径示例：

分组A + 子账户「高档」 → model=best-model
   ↓ 分组规则：选定上游 X（chain）
   ↓ 子账户规则：选定上游 X 的高档接入密钥
   ↓ 静态别名：best-model → 高档模型标识
   → 上游 X 收到 高档模型标识

响应的 extra_fields 中，original_model_requested 始终是应用最初发送的名字，resolved_model_used 是经路由与别名两层解析后最终抵达上游 API 的标识。

别名不改写内容。 别名只解析"模型名 → 上游标识"，生成由解析后选定的上游模型完成；逐条调用记录与计量按解析后的实际模型落账，对外仍以中性名呈现。

下一步

路由规则：动态别名所依赖的条件表达式、作用域优先级与规则链完整说明。
请求选项透传与覆写：通过请求头携带分级与会话信息，作为动态别名条件表达式的输入。
通用接入规则：中性名、一名多源与模型池准入的基础规则。
API 参考：上游接入与路由规则接口的完整端点契约。

On this page