Ascend/msagent / skills/quantizer/msmodelslim-anti-outlier-adapt
msmodelslim-anti-outlier-adapt
Verified在基础模型适配完成后,按算法适配并安装 Adapter 接口,依据目标模型真实 forward 生成并验证 final-logits patch,执行单算法 msModelSlim 离群值抑制变换、官方计算图提取和浮点 logits 门禁。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.4 KB |
| references/architecture-analysis.md | markdown | 1.8 KB |
| references/audit-report.md | markdown | 763 B |
| references/interface-quick-reference.md | markdown | 14.4 KB |
| references/quarot-adaptation.md | markdown | 1.3 KB |
| references/smoothing-adaptation.md | markdown | 1.5 KB |
| references/topology-patterns.md | markdown | 806 B |
| references/validation.md | markdown | 6.0 KB |
| scripts/apply_one_anti_outlier.py | script | 43.5 KB |
| scripts/compare_final_logits.py | script | 31.3 KB |
| scripts/validate_anti_outlier_interfaces.py | script | 8.1 KB |
references/interface-quick-reference.md
View on GitHub# 离群值抑制接口快速参考
本文件是实现新模型离群值抑制 Adapter 的第一参考。它以当前安装的
msModelSlim 接口和目标模型当前的真实 forward 为准,提供一个可以直接改名和删减的
最小实现。不要从历史提交、其它模型的完整 Adapter 或模型名称推断映射;只有在当前
msModelSlim 源码缺少契约信息时才扩大检索范围。
## 先确定读取顺序
按下面的顺序完成适配,通常不需要阅读其它模型提交:
1. 查看当前环境的 `QuaRotInterface`、所选 Smooth 接口、`AdapterConfig` 和处理器的
subgraph dispatch,确认实际签名和当前版本字段。
2. 阅读目标模型的 `config.json`、实际 `modeling_*.py` 和 Adapter 的模型加载/逐层
forward,列出真实的 module path、hidden/head 维度、融合方式和 MoE 本地专家范围。
3. 用真实 forward 或官方 `fast_ops_grapher` 确认数据流,再填写下面的映射。
4. 在 msModelSlim 源码中实现接口,运行 `bash install.sh`,再用本 Skill 的接口检查脚本
验证源码和已安装包一致。
参考的当前源码位置(路径随 msModelSlim checkout 变化时,以实际文件为准):
```text
msmodelslim/processor/quarot/offline_quarot/quarot_interface.py
msmodelslim/processor/anti_outlier/common/subgraph_type.py
msmodelslim/core/graph/adapter_types.py
msmodelslim/processor/anti_outlier/flex_smooth/interface.py
msmodelslim/processor/anti_outlier/iter_smooth/interface.py
msmodelslim/processor/anti_outlier/flex_smooth/processor.py
msmodelslim/processor/anti_outlier/iter_smooth/processor.py
```
## 接口和算法对应关系
| 算法 | Adapter 必须显式继承 | 必须实现的方法 |
| --- | --- | --- |
| `quarot` | `QuaRotInterface` | `get_ln_fuse_map`、`get_bake_names`、`get_rotate_map(block_size)` |
| `flex_smooth_quant` | `FlexSmoothQuantInterface` | `get_adapter_config_for_subgraph()` |
| `flex_awq_ssz` | `FlexSmoothQuantInterface` | `get_adapter_config_for_subgraph()` |
| `iter_smooth` | `IterSmoothInterface` | `get_adapter_config_for_subgraph()` |
| `smooth_quant` | `SmoothQuantInterface` | `get_adapter_config_for_subgraph()` |
| `oasq` | `OASQInterface` | `get_adapter_config_for_subgraph()` |
当前 Skill 的默认门禁只运行前四项。后两项的映射结构相同,但不要因此把它们加入本
Skill 的默认算法列表。
多个 Smooth 算法共用一份映射时,Adapter 需要显式继承每个实际使用的接口。处理器用
`isinstance` 判断能力,不能只靠 `__getattr__` 转发方法:
```python
from msmodelslim.model.interface_hub import (
FlexSmoothQuantInterface,
IterSmoothInterface,
QuaRotInterface,
)
class MyModelAdapter(
ExistingModelAdapter,
QuaRotInterface,
FlexSmoothQuantInterface,
IterSmoothInterface,
):
...
```
如果只验证 `flex_smooth_quant`,就只继承 `FlexSmoothQuantInterface`;不要为了“看起来
完整”继承不需要的接口。
`flex_awq_ssz` 仍然使用 `FlexSmoothQuantInterface` 和同一份拓扑映射;它额外要求处理器
配置中的官方 `qconfig`,这不改变 Adapter 接口。
## Smooth 系列的最小实现
`get_adapter_config_for_subgraph()` 返回 `List[AdapterConfig]`。路径必须是当前模型可以
通过 `model.get_submodule(path)` 找到的完整路径;不能使用只在某个示例模型中成立的
别名。下面是标准 decoder block 的最小结构模板,逐项替换为目标模型真实字段:
```python
from typing import List
from msmodelslim.core.graph.adapter_types import AdapterConfig, MappingConfig
class MyModelAdapter(ExistingModelAdapter, FlexSmoothQuantInterface, IterSmoothInterface):
def get_adapter_config_for_subgraph(self) -> List[AdapterConfig]:
configs: List[AdapterConfig] = []
for layer_idx in range(self.config.num_hidden_layers):
prefix = f"model.layers.{layer_idx}"
# norm(x) -> [q(x), k(x), v(x)]
configs.append(
AdapterConfig(
subgraph_type="norm-linear",
mapping=MappingConfig(
source=f"{prefix}.input_layernorm",
targets=[
f"{prefix}.self_attn.q_proj",
f"{prefix}.self_attn.k_proj",
f"{prefix}.self_attn.v_proj",
],
),
)
)
# post_norm(x) -> [gate(x), up(x)]
configs.append(
AdapterConfig(
subgraph_type="norm-linear",
mapping=MappingConfig(
source=f"{prefix}.post_attention_layernorm",
targets=[
f"{prefix}.mlp.gate_proj",
f"{prefix}.mlp.up_proj",
],
),
)
)
# V -> O;只在真实 forward 中 O 的输入确实来自 V 时添加
configs.append(
AdapterConfig(
subgraph_type="ov",
mapping=MappingConfig(
source=f"{prefix}.self_attn.v_proj",
targets=[f"{prefix}.self_attn.o_proj"],
),
extra_config={"group_method": "max"},
)
)
# up -> down;gate 不放在 up-down mapping 中
configs.append(
AdapterConfig(
subgraph_type="up-down",
mapping=MappingConfig(
source=f"{prefix}.mlp.up_proj",
targets=[f"{prefix}.mlp.down_proj"],
),
)
)
return configs
```
四种 subgraph 的填写规则如下:
| `subgraph_type` | `mapping.source` | `mapping.targets` | 判断依据 |
| --- | --- | --- | --- |
| `norm-linear` | norm | 该 norm 输出直接进入的一个或多个 Linear | 同一归一化输出共同驱动这些 Linear |
| `up-down` | up projection | down projection | 激活函数/门控之后形成 up-down 数据流 |
| `linear-linear` | 第一层 Linear | 第二层 Linear | 第一层输出直接作为第二层输入 |
| `ov` | V 或等价 V 分支 | O projection | attention 中 V 的输出经过 head reshape/聚合进入 O |
不要把整个 block 的所有 Linear 放进一条 mapping。每条 mapping 只表达一个处理器支持
的子图;`targets` 必须非空。`norm-linear`、`linear-linear` 和 `up-down` 的通道维必须
按对应 forward 对齐;`ov` 的 head 分组/扩展由 `num_attention_heads`、
`num_key_value_heads` 和融合元数据共同决定。没有可融合 source
的非融合配置才使用 `source=None`,并把所有直接共享激活的 Linear 放进 `targets`。
### 融合 QKV、KV 或 MLA
当模型把 QKV/KV 融成一个权重时,仍然表达实际的 V→O 关系,并补充融合元数据;不要
把融合权重拆成虚构的 module path:
```python
from msmodelslim.core.graph.adapter_types import FusionConfig
AdapterConfig(
subgraph_type="ov",
mapping=MappingConfig(
source="model.layers.0.self_attn.qkv_proj", # 真实融合模块
targets=["model.layers.0.self_attn.o_proj"],
),
fusion=FusionConfig(
fusion_type="qkv",
num_attention_heads=self.config.num_attention_heads,
num_key_value_heads=self.config.num_key_value_heads,
),
)
```
KV/MLA 只有在当前处理器要求时才使用 `fusion_type="kv"`,并提供真实的
`qk_nope_head_dim`、`v_head_dim` 等字段:
```python
FusionConfig(
fusion_type="kv",
num_attention_heads=self.config.num_attention_heads,
num_key_value_heads=self.config.num_key_value_heads,
custom_config={
"qk_nope_head_dim": self.config.qk_nope_head_dim,
"v_head_dim": self.config.v_head_dim,
},
)
```
GQA/MQA 的 `num_attention_heads`、`num_key_value_heads` 必须来自当前模型配置。不要把
KV head 数当成 query head 数,也不要用字符串名称猜测融合类型。
### MoE 和动态分支
对 dense、shared expert、routed expert、router 分开生成 mapping。EP 场景下 routed
expert 只遍历当前 rank 已 materialize 的 expert 区间;smooth、QuaRot 的 mapping 和
权重加载必须使用同一个本地 expert 集合。未被本次校准输入激活的 expert 可以没有统计,
但不能用一个不存在的路径假装覆盖它。
VLM、MTP 或辅助 decoder 也按实际残差流分别列出路径。视觉 encoder 不自动当成 decoder
layer;只有视觉 merger 输出确实进入语言残差流时,才把它纳入相关 norm/linear 关系。
## QuaRot 的最小实现
QuaRot 的三个返回值含义固定:
```text
get_ln_fuse_map() -> (pre_run_fused_ln, fused_map)
get_bake_names() -> (pre_run_bake_names, bake_names)
get_rotate_map(block_size) -> (pre_run_pairs, rotate_pairs)
```
每个 rotation pair 都是 `RotatePair(left_rot: dict, right_rot: dict)`。字典 key 是
真实 module path,value 是与目标权重通道维相同的旋转矩阵(拼接子空间时也可以是当前
processor 支持的矩阵列表)。一个标准 decoder 的骨架如下:
```python
from msmodelslim.processor.quarot import QuaRotInterface
class MyModelAdapter(ExistingModelAdapter, QuaRotInterface):
def get_ln_fuse_map(self):
fused_map = {}
for layer_idx in range(self.config.num_hidden_layers):
prefix = f"model.layers.{layer_idx}"
fused_map[f"{prefix}.input_layernorm"] = [
f"{prefix}.self_attn.q_proj",
f"{prefix}.self_attn.k_proj",
f"{prefix}.self_attn.v_proj",
]
fused_map[f"{prefix}.post_attention_layernorm"] = [
f"{prefix}.mlp.gate_proj",
f"{prefix}.mlp.up_proj",
]
fused_map["model.norm"] = ["lm_head"]
return {}, fused_map
def get_bake_names(self):
# RMSNorm 通常不需要 mean bake;LayerNorm 要以当前处理器和 forward 证据为准。
return [], []
def get_rotate_map(self, block_size):
hidden_rot = self.get_rotate_command(
mode=self.QuaRotMode.HADAMARD,
size=self.config.hidden_size,
block_size=block_size,
)
head_dim = getattr(self.config, "head_dim", None)
if head_dim is None:
head_dim = self.config.hidden_size // self.config.num_attention_heads
head_rot = self.get_rotate_command(
mode=self.QuaRotMode.HADAMARD,
size=head_dim,
block_size=block_size,
)
pre_run = self.RotatePair(
left_rot={},
right_rot={"model.embed_tokens": hidden_rot},
)
left_rot = {}
right_rot = {"lm_head": hidden_rot}
for layer_idx in range(self.config.num_hidden_layers):
prefix = f"model.layers.{layer_idx}"
right_rot.update(
{
f"{prefix}.self_attn.q_proj": hidden_rot,
f"{prefix}.self_attn.k_proj": hidden_rot,
f"{prefix}.self_attn.v_proj": hidden_rot,
f"{prefix}.mlp.gate_proj": hidden_rot,
f"{prefix}.mlp.up_proj": hidden_rot,
}
)
left_rot.update(
{
f"{prefix}.self_attn.o_proj": hidden_rot,
f"{prefix}.mlp.down_proj": hidden_rot,
}
)
main = self.RotatePair(left_rot=left_rot, right_rot=right_rot)
# 只有 V/O 的 head 子空间确实独立且维度匹配时才保留这一 pair。
ov_left = {}
ov_right = {}
for layer_idx in range(self.config.num_hidden_layers):
prefix = f"model.layers.{layer_idx}"
ov_left[f"{prefix}.self_attn.v_proj"] = head_rot
ov_right[f"{prefix}.self_attn.o_proj"] = head_rot
ov = self.RotatePair(left_rot=ov_left, right_rot=ov_right)
return [pre_run], [main, ov]
```
`left`/`right` 不是可以凭名称猜的装饰项。当前 QuaRot processor 对 Linear 权重分别
沿输出维和输入维执行旋转;应先查看目标权重 shape 和真实 tensor 流,再决定一侧和
矩阵大小。`model.embed_tokens`、`lm_head`、Q/K/V、O、MLP projection 的组合只是标准
decoder 示例。融合 QKV、低秩 MLA、拼接输出、MTP 和专家 projection 必须按实际分块构造
矩阵;不兼容的子空间不旋转。
`get_bake_names()` 只用于 mean bake。没有 LayerNorm/mean 变换证据时保持空列表;不能
把 LayerNorm 的规则套到 RMSNorm。所有 key 都必须能被当前模型解析,重复 key 或同一权重
同时收到冲突旋转应在运行前报错。
## 最小验证闭环
实现后只做以下闭环即可判断接口是否可用:
```bash
bash install.sh
python skills/quantizer/msmodelslim-anti-outlier-adapt/scripts/validate_anti_outlier_interfaces.py \
--model-type <model_type> \
--model-path <checkpoint> \
--source-root <msmodelslim_checkout> \
--output-dir <workdir> \
--algorithm quarot \
--algorithm flex_smooth_quant \
--algorithm iter_smooth
```
检查结果必须同时满足:
- Adapter 显式实现了所选接口,且源码文件 hash 与已安装实现一致;
- Smooth 返回非空 `AdapterConfig`,每条 subgraph 类型受当前 processor 支持,source/target
路径存在且顺序符合 forward;
- QuaRot 三个 map 的返回层级正确,矩阵 shape 与目标权重通道一致;
- 只对当前 checkpoint 和当前输入覆盖的分支报告 PASS;动态分支未覆盖就记录限制;
- 之后再执行本 Skill 的单 processor、before/after final-logits 门禁。
常见错误与修复方向:
| 现象 | 优先检查 |
| --- | --- |
| `isinstance` 失败或处理器回退自动发现 | Adapter 是否显式继承所选 interface |
| Smooth 返回空结果或全部 skip | `AdapterConfig` 是否非空、路径是否真实、目标是否收到校准激活 |
| `norm-linear` shape 错误 | norm 输出维度与每个 target 的输入维度是否一致 |
| `ov` shape/分组错误 | V/O 的 head 数、KV head 数、融合元数据和 head dim |
| QuaRot rotation shape 错误 | left/right 方向、权重布局、block size 和旋转子空间 |
| QuaRot 运行后 logits 大幅漂移 | 漏掉 embedding/head/残差路径,或把不兼容分支强行共用 hidden rotation |
| MoE 只有部分 rank 失败 | mapping、权重加载和 forward 是否使用同一 `local_expert_ids` |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |