配置身份作用域模型映射

当你希望不同客户请求同一个客户端模型名时被路由到不同上游时，用身份作用域模型映射：在访问密钥或密钥组上声明 from → to 规则，网关会在入口闸之后、路由之前自动重写模型名，随后由出口闸校验目标。例如让 team-a 组的 claude-opus-5 实际走通义千问 qwen3.7-max，而没有该规则的客户照常走原路由。规则还可按请求头分流：带 X-Tenant: vip 的 claude-opus-5 走优质线路，不带走普通线路。

入口：控制台 → 访问密钥（Access Keys / Key Groups 页签，仅 admin 可改映射）。

它和 switch-route / 脚本 useModel 的区别

机制	作用范围	配置方式	触发依据	目标过访问控制？
switch-route	全局	声明式	请求体内容	否（管理员改路）
脚本 context.useModel()	全局	编程式	脚本逻辑	否（管理员改路）
身份模型映射	按 key / group	声明式	请求身份 + 请求头	是（出口闸）

三者都是「模型名交换」，但只有身份映射按租户生效、且目标必须在该客户端的权限白名单里——配一条映射规则不等于发放权限。switch-route / useModel 的目标是管理员强制改路，不受客户端权限约束（二者签名也不接身份上下文）。

配置步骤

1. 打开 访问密钥 页，编辑目标访问密钥或访问密钥组。
2. 在表单底部找到 模型映射（Model Mappings） 区域，点 添加规则。
3. 每行选两个字段：源模型（from，客户端请求的名字）与 目标模型（to，实际路由的名字）。to 下拉只列出该身份出口闸有权到达的名字；from 是可输入下拉——网关里真实存在的模型/负载均衡/别名可下拉选，虚构接入名（access label，网关里不存在、客户端习惯发的标签）靠输入。group 级输入的 from 保存时自动并入该组 models 清单（入口闸放行）；key 级 from 若不在该 key 所属任何组清单，行内会警告「入口闸将拒」。UI 里能配出来的规则，运行时出口闸一定放行。可加多行，点行尾删除图标移除。
4. （可选）点 添加请求头条件，给规则加一个 when：请求头名可输入或下拉选、操作符下拉选，按操作符决定是否填条件值（输入框）。详见下文「头条件」。
5. 保存。规则即时热重载生效，无需重启。

没碰过映射区域就保存，等于「保留现有规则」；只有在该区域做过增删改，才会把当前列表写回（清空所有行 = 显式清空映射）。新身份（尚未保存）的下拉为空——先保存身份及其模型 / 负载均衡白名单，再回来配映射，下拉才会填充。

通配符

from 与 to 各至多一个 *。from 的 * 捕获中间片段，to 的 * 回填它：

• claude-opus-5 → qwen3.7-max：精确匹配，整名替换。
• claude-* → qwen-*：claude-opus-5 变成 qwen-opus-5，claude-sonnet-4 变成 qwen-sonnet-4。
• to 含 * 时 from 必须含 *；from 与 to 都不能有两个 *。否则保存时报 422。

from 可输入任意值（具体名、通配符模式如 claude-*、虚构接入名）；to 只能从下拉选（该身份出口闸有权到达的具体名字，不含通配符）。若需 to 含通配符的规则，经配置文件 / API 直接配置——会正常生效与回显，但无法在控制台 to 下拉里新建。

两套通配符方言（注意区分）：

写在哪	* 的含义	例子
映射规则 from	中间片段捕获	claude-*-5 匹配 claude-opus-5（捕获 opus）
密钥组白名单 models / load_balancers	仅精确名、"*" 全选、尾部 * 前缀匹配；不支持中间 *	claude-* 匹配所有 claude- 开头；claude-*-5 只当字面量

故 from = "claude-*-5" 的规则，要让入口闸放行，白名单里须写具体名（如 claude-opus-5）或尾部通配（claude-*）。白名单写 claude-*-5 会被当字面量、只精确匹配字符串本身。这是 fail-closed：写不进白名单的 from 名会在入口闸 403。

头条件（按请求头分流）

给规则加 when 即可让同一个 from 按请求头走不同目标。操作符五选一：

操作符	语义	是否填条件值
exact	头值精确相等	是
prefix	头值以该前缀开头	是
regex	头值匹配正则	是
exists	该头存在（不看值）	否
absent	该头不存在	否

头名大小写不敏感，条件值大小写敏感。条件不满足时跳过这条规则，继续在同一个桶里找下一条 from 匹配的规则——所以把带条件的规则放前面、无条件规则兜底：

1. claude-opus-5 → glm-4.6        when X-Tenant exact vip      # 带头条件的具体规则放前
2. claude-opus-5 → qwen3.7-max                                 # 无条件兜底

带 X-Tenant: vip 的请求命中规则 1 → glm-4.6；不带的跳过规则 1、命中规则 2 → qwen3.7-max。

请求头名是可输入下拉：内置常见头 ∪ 现有请求头访问规则用过的头 ∪ 本身份已用过的头作为候选建议，也可直接键入候选里没有的任意头名。运行时对头名没有白名单——某条规则引用的头在请求里缺失时，该规则被跳过（不会 403），继续看同桶下一条规则。

when 针对的是发起请求那一刻携带的请求头。少数反向推断落点（DashScope 异步任务状态查询 GET /v1/services/{model}/tasks/{task_id}）在映射处拿不到原始请求头，传空查询——此时只有无条件规则会匹配，带头条件的规则被跳过。这是 fail-closed：若唯一匹配的规则带了 when 且未被满足，模型名不重写、按原名解析（可能 404）。出口闸照常运行。

优先级

键级规则 > 组级规则（按该访问密钥 groups 列表的顺序）> 透传。访问密钥自身的规则先看；没命中再依次看它所属各组的规则；都没命中则模型名不变。桶内顺序优先：第一条 from 匹配且头条件满足的规则胜出（first-match-wins），故带条件的规则须放在无条件规则之前。

组与组之间的顺序 = 该访问密钥 groups 列表的顺序，且这一顺序在两次保存之间恒定。 多个组都对同一个源名（from）配了映射时，列表里靠前的组胜出——网关不会把各组的规则合并成一张大表，而是逐组尝试、第一个产生匹配的组即返回、后面的组整组不看。由于「逐组串行、首匹配组即返回」，组的顺序优先于桶内顺序：例如组 A 的规则是 [m→X（仅 vip）, m→Y（无条件）]、组 B 是 [m→Z（无条件）]，当请求不带 vip 时结果是 Y 而非 Z（A 桶内跳过第一条后命中第二条，整组返回，B 轮不到）。

这一顺序在配置不变时是确定的（每次请求命中的都是同一个组）。但当前没有针对「多个组（或键与组之间）对同一 from 配了规则」的冲突校验或告警——谁先生效完全由 groups 列表顺序这一隐含约定决定。需要确定性时，最稳的做法是让同一个 from 只在一个地方配规则（或直接配在访问密钥上，键级永远最先、最明确）；若必须分散在多个组，就把应优先的组放在该键 groups 列表更靠前的位置。

三条必须知道的运维契约

1. 映射目标必须在白名单，且按真实种类写对清单。出口闸在映射原语内部对真实目标名判型：目标是普通模型查组的 models、目标是负载均衡查组的 load_balancers。目标不在对应清单里 → 403。故配 claude-opus-5 → my-lb（my-lb 是负载均衡）时，把 my-lb 写进组的 load_balancers。

2. 源名（from）必须在白名单。入口闸对路由表里存在的名字按种类查对应清单（load_balancers = ["*"] 只放行负载均衡名，不顺带放行普通模型名）；对虚构客户端名（网关里不存在的接入标签）两张清单取并集回退，故虚构名写 models 或 load_balancers 均可。在 group 级配映射规则时，输入的虚构 from 保存时自动并入该组 models 清单（入口闸放行）；在 key 级配规则时，key 无独立清单，虚构 from 须手动写进该 key 所属某组的 models 或 load_balancers（写哪张均可），控制台会在 from 不在所属组清单时警告。这是显式授权动作，不是绕过。

3. /v1/models 列表不反映映射。列表只列配置里真实存在的模型，映射的源名（如 claude-opus-5、gpt-4o）通常不在其中，所以下拉框里看不到它——但客户端直接请求该名字能成功。这是预期行为。

统计与计费看到的是哪个名字？

映射后的最终模型名。映射对统计与计费完全透明——日志、统计页、账单里记录的是目标模型（如 qwen3.7-max），不会出现源名行。若你需要按客户视角的源名做归因，请在客户端侧自行记录。

如何在日志里确认映射生效

看日志页模型列的 MM 标签：命中映射规则的请求模型名前会挂 MM，鼠标悬停显示 原名 → 映射名（如 gpt-4o → glm-4.6），日志详情页「概览」区同处可见映射来源条。无需翻请求体——标签即凭证。映射目标是负载均衡名时，同一行 MM + LB 两标签都在；同时被脚本 useModel 改路则 MM + SW 都在。

排错

• 保存报 422「invalid model mapping rule」：检查该行 from/to 是否为空、from 是否多于一个 *、to 有 * 而 from 没有；若带 when，检查头名是否为空、exact/prefix/regex 是否填了值、exists/absent 是否误填了值、regex 能否编译。
• 请求 403：要么是源名（from）不在该身份任一清单里（入口闸拒），要么是目标（to）不在对应种类的清单里（出口闸拒）。403 错误体里写的是客户端原名。
• 请求 404 但服务端 warn 了真实目标名：映射目标模型 / 负载均衡不存在或已禁用；返回给客户端的消息已脱敏回源名。
• 头条件没分流：确认带条件的规则排在无条件规则之前；确认客户端确实带了那个头且值匹配。
• 映射没生效：确认规则配在正确的身份上（键级 vs 组级），且客户端确实以该身份认证；优先级被更高优先级的规则覆盖时也会「看起来没生效」。