已合并
[Doc] RA Compress 文档更新 #991
zhangwl创建于 9月17日
[Doc] RA Compress 文档更新 #991
已合并
共 6 个文件变更+182-249
| @@ -2,20 +2,20 @@ | |||
| 2 | 2 | ||
| 3 | ## 1. 功能说明 | 3 | ## 1. 功能说明 |
| 4 | 4 | ||
| 5 | -`msmodelslim analyze` 在量化前对模型做敏感层分析，输出建议回退或重点关注的层名列表，供后续写入量化配置的 `exclude` 等字段。按分析粒度分为四个 scope：`linear`（逐个线性层）、`layer`（按层/块分组）、`attn`（Attention 模块）、`attn_head`（Attention Head / `ra_compress`）。分析使用校准数据集在目标设备上计算敏感度指标，并按 `--top_k` 输出敏感度最高的层名（`disable_names`；`attn_head` 输出 `head.pt`）。 | 5 | +`msmodelslim analyze` 在量化前对模型做敏感层分析，输出建议回退或重点关注的层名列表，供后续写入量化配置的 `exclude` 等字段。按分析粒度分为四个 scope：`linear`（逐个线性层）、`layer`（按层/块分组）、`attn`（Attention 模块）、`attn_head`（Attention Head / `ra_compress`）。分析在目标设备上计算敏感度指标，并按 `--top_k` 输出敏感度最高的层名（`disable_names`；`attn_head` 输出 `head.pt`）。默认只把结果打印到日志；指定 `--save_path` 后结果落盘为文件（`linear`/`layer`/`attn` 为 YAML，`attn_head` 为 `head.pt`）。其中 `linear`/`layer`/`attn` 使用 `--calibration_dataset` 指定的校准数据集；`attn_head`（`ra_compress`）不读取外部校准集，其校准输入由算法在运行时自行构造（首 token + 随机重复段）。 |
| 6 | 6 | ||
| 7 | 命令边界：本命令只做分析与结果输出，不执行量化，且需要模型适配器实现分析接口。支持单卡与多卡（DP）分析：多卡时使用 `--device npu --device_id 0 1 ...`（或兼容写法 `--device npu:0,1,...`），由 `DPLayerWiseRunner` 执行。操作步骤见《[线性层敏感层分析使用指南](../../user_guide/usage_sensitive_linear_analysis.md)》、《[层级敏感层分析使用指南](../../user_guide/usage_sensitive_layer_analysis.md)》、《[Attention 敏感层分析使用指南](../../user_guide/usage_sensitive_attn_analysis.md)》、《[Attention Head 筛选分析使用指南](../../user_guide/usage_sensitive_attn_head_analysis.md)》。 | 7 | 命令边界：本命令只做分析与结果输出，不执行量化，且需要模型适配器实现分析接口。支持单卡与多卡（DP）分析：多卡时使用 `--device npu --device_id 0 1 ...`（或兼容写法 `--device npu:0,1,...`），由 `DPLayerWiseRunner` 执行。操作步骤见《[线性层敏感层分析使用指南](../../user_guide/usage_sensitive_linear_analysis.md)》、《[层级敏感层分析使用指南](../../user_guide/usage_sensitive_layer_analysis.md)》、《[Attention 敏感层分析使用指南](../../user_guide/usage_sensitive_attn_analysis.md)》、《[Attention Head 筛选分析使用指南](../../user_guide/usage_sensitive_attn_head_analysis.md)》。 |
| 8 | 8 | ||
| 9 | ## 2. 命令格式 | 9 | ## 2. 命令格式 |
| 10 | 10 | ||
| 11 | ```text | 11 | ```text |
| 12 | -msmodelslim analyze linear --model_type <model_type> --model_path <model_path> [--device <device>] [--device_id <id> ...] [--calibration_dataset <file>] [--top_k <n>] [--trust_remote_code [<BOOL>]] [--log_level <level>] [-v] [-q] [--metrics <metrics>] [--patterns <pattern> ...] | 12 | +msmodelslim analyze linear --model_type <model_type> --model_path <model_path> [--device <device>] [--device_id <id> ...] [--calibration_dataset <file>] [--top_k <n>] [--trust_remote_code [<BOOL>]] [--log_level <level>] [-v] [-q] [--metrics <metrics>] [--patterns <pattern> ...] [--save_path <path>] |
| 13 | 13 | ||
| 14 | -msmodelslim analyze layer --model_type <model_type> --model_path <model_path> [--device <device>] [--device_id <id> ...] [--calibration_dataset <file>] [--top_k <n>] [--trust_remote_code [<BOOL>]] [--log_level <level>] [-v] [-q] [--metrics <metrics>] [--quant_modules <module> ...] | 14 | +msmodelslim analyze layer --model_type <model_type> --model_path <model_path> [--device <device>] [--device_id <id> ...] [--calibration_dataset <file>] [--top_k <n>] [--trust_remote_code [<BOOL>]] [--log_level <level>] [-v] [-q] [--metrics <metrics>] [--quant_modules <module> ...] [--save_path <path>] |
| 15 | 15 | ||
| 16 | -msmodelslim analyze attn --model_type <model_type> --model_path <model_path> [--device <device>] [--device_id <id> ...] [--calibration_dataset <file>] [--top_k <n>] [--trust_remote_code [<BOOL>]] [--log_level <level>] [-v] [-q] [--metrics <metrics>] | 16 | +msmodelslim analyze attn --model_type <model_type> --model_path <model_path> [--device <device>] [--device_id <id> ...] [--calibration_dataset <file>] [--top_k <n>] [--trust_remote_code [<BOOL>]] [--log_level <level>] [-v] [-q] [--metrics <metrics>] [--save_path <path>] |
| 17 | 17 | ||
| 18 | -msmodelslim analyze attn_head --model_type <model_type> --model_path <model_path> [--device <device>] [--device_id <id> ...] [--calibration_dataset <file>] [--trust_remote_code [<BOOL>]] [--log_level <level>] [-v] [-q] [--metrics <metrics>] [--save_path <path>] | 18 | +msmodelslim analyze attn_head --model_type <model_type> --model_path <model_path> [--device <device>] [--device_id <id> ...] [--trust_remote_code [<BOOL>]] [--log_level <level>] [-v] [-q] [--metrics <metrics>] [--save_path <path>] |
| 19 | ``` | 19 | ``` |
| 20 | 20 | ||
| 21 | 符号说明： | 21 | 符号说明： |
| @@ -24,7 +24,8 @@ msmodelslim analyze attn_head --model_type <model_type> --model_path <model_path | |||
| 24 | - 尖括号内为需替换的值，方括号内为可选参数。 | 24 | - 尖括号内为需替换的值，方括号内为可选参数。 |
| 25 | - `--trust_remote_code` 是可选值布尔参数：不带值传入即开启（等价 `true`），或跟 `true`/`false`（大小写不敏感，兼容遗留 `True`/`False`、`yes`/`no`、`on`/`off`）。 | 25 | - `--trust_remote_code` 是可选值布尔参数：不带值传入即开启（等价 `true`），或跟 `true`/`false`（大小写不敏感，兼容遗留 `True`/`False`、`yes`/`no`、`on`/`off`）。 |
| 26 | - `--patterns`、`--quant_modules`、`--device_id` 一次接收多个值，`...` 表示可跟多个以空格分隔的值。 | 26 | - `--patterns`、`--quant_modules`、`--device_id` 一次接收多个值，`...` 表示可跟多个以空格分隔的值。 |
| 27 | -- 各 scope 的专有选项不同：`linear` 有 `--metrics`、`--patterns`；`layer` 有 `--metrics`、`--quant_modules`；`attn` 只有 `--metrics`；`attn_head` 有 `--metrics`（仅 `ra_compress`）与 `--save_path`。 | 27 | +- 各 scope 的专有选项不同：`linear` 有 `--metrics`、`--patterns`；`layer` 有 `--metrics`、`--quant_modules`；`attn` 只有 `--metrics`；`attn_head` 有 `--metrics`（仅 `ra_compress`）。`--save_path` 为四个 scope 通用的落盘选项，但落盘格式不同：`linear`/`layer`/`attn` 写 YAML，`attn_head` 写 `head.pt`。 |
| 28 | +- `--calibration_dataset` 对 `attn_head` 不生效：该场景的校准输入由算法在运行时自行构造，传入的校准集仅参与格式与安全检查，不影响分析结果。 | ||
| 28 | - 省略 `<scope>` 时（非帮助请求）自动按 `linear` 执行；本命令无其他位置参数。本语法摘要用于说明参数结构，不作为可复制命令；可复制命令见「使用示例」。 | 29 | - 省略 `<scope>` 时（非帮助请求）自动按 `linear` 执行；本命令无其他位置参数。本语法摘要用于说明参数结构，不作为可复制命令；可复制命令见「使用示例」。 |
| 29 | 30 | ||
| 30 | ## 3. 参数列表 | 31 | ## 3. 参数列表 |
| @@ -37,8 +38,9 @@ msmodelslim analyze attn_head --model_type <model_type> --model_path <model_path | |||
| 37 | | `--model_path` | 无 | `string` | 单值 | 必选 | 无 | 原始模型权重目录（需存在且可读） | 待分析模型的权重目录。 | | 38 | | `--model_path` | 无 | `string` | 单值 | 必选 | 无 | 原始模型权重目录（需存在且可读） | 待分析模型的权重目录。 | |
| 38 | | `--device` | 无 | `string` | 单值 | 可选 | `npu` | `npu`、`cpu`；兼容遗留写法 `npu:0,1,...` | 运行设备类型。推荐写法为 `--device npu` 再配合 `--device_id`；遗留 `npu:0,1` 会自动拆分为 `--device npu --device_id 0 1`。 | | 39 | | `--device` | 无 | `string` | 单值 | 可选 | `npu` | `npu`、`cpu`；兼容遗留写法 `npu:0,1,...` | 运行设备类型。推荐写法为 `--device npu` 再配合 `--device_id`；遗留 `npu:0,1` 会自动拆分为 `--device npu --device_id 0 1`。 | |
| 39 | | `--device_id` | 无 | `list[int]` | 一次接收多个值，空格分隔 | 可选 | 无 | 非负整数索引，如 `0 1 2 3` | 分析所用 NPU 索引；长度 > 1 时启用多卡 DP（`DPLayerWiseRunner`）。CPU 场景不可指定多个索引。 | | 40 | | `--device_id` | 无 | `list[int]` | 一次接收多个值，空格分隔 | 可选 | 无 | 非负整数索引，如 `0 1 2 3` | 分析所用 NPU 索引；长度 > 1 时启用多卡 DP（`DPLayerWiseRunner`）。CPU 场景不可指定多个索引。 | |
| 40 | -| `--calibration_dataset` | `--calib_dataset`（遗留别名） | `string` | 单值 | 可选 | `mix_calib.jsonl` | LLM：`.json` / `.jsonl`；VLM：图文目录名（如 `calibImages`）或路径 | 校准数据集。 | | 41 | +| `--calibration_dataset` | `--calib_dataset`（遗留别名） | `string` | 单值 | 可选 | `mix_calib.jsonl` | LLM：`.json` / `.jsonl`；VLM：图文目录名（如 `calibImages`）或路径 | 校准数据集，用于 `linear`/`layer`/`attn` 的指标计算；`attn_head`（`ra_compress`）不读取该校准集（内部构造随机校准输入），此时仅参与格式与安全检查。 | |
| 41 | | `--top_k` | `--topk`（遗留别名） | `int` | 单值 | 可选 | `15` | 大于0的整数 | 输出到 `disable_names` 的最高敏感层数（经验值，仅供参考；`attn_head` 无此参数）。 | | 42 | | `--top_k` | `--topk`（遗留别名） | `int` | 单值 | 可选 | `15` | 大于0的整数 | 输出到 `disable_names` 的最高敏感层数（经验值，仅供参考；`attn_head` 无此参数）。 | |
| 43 | +| `--save_path` | 无 | `string` | 单值 | 可选 | 无（仅打印到日志） | 可写目录或文件路径：`linear`/`layer`/`attn` 为 `.yaml`/`.yml` 或目录；`attn_head` 为 `.pt` 或目录 | 分析结果的落盘路径。`linear`/`layer`/`attn`：路径以 `.yaml`/`.yml` 结尾时按该文件名写入，否则视为目录并按 `<model_type>-<metrics>.yaml` 命名；`attn_head`：路径以 `.pt` 结尾时按该文件名写入，否则写入目录下的 `head.pt`。不指定时结果仅打印到日志（控制台）。 | | ||
| 42 | | `--trust_remote_code` | 无 | `bool` | 可选值（不带值传入即开启，或跟 `true`/`false`） | 可选 | `false` | `true`/`false`（大小写不敏感；兼容 `True`/`False`、`yes`/`no`、`on`/`off`） | 是否信任并执行模型目录中的自定义 Python 代码；仅在确认代码来源可信时开启。 | | 44 | | `--trust_remote_code` | 无 | `bool` | 可选值（不带值传入即开启，或跟 `true`/`false`） | 可选 | `false` | `true`/`false`（大小写不敏感；兼容 `True`/`False`、`yes`/`no`、`on`/`off`） | 是否信任并执行模型目录中的自定义 Python 代码；仅在确认代码来源可信时开启。 | |
| 43 | | `--log_level` | 无 | `string` | 单值 | 可选 | `info` | `debug`、`info`、`warning`、`error` | 日志级别。 | | 45 | | `--log_level` | 无 | `string` | 单值 | 可选 | `info` | `debug`、`info`、`warning`、`error` | 日志级别。 | |
| 44 | | `-v` / `--verbose` | 无 | `bool` | 不带值开关 | 可选 | 关闭 | 传入即启用 | 提高输出详细程度（等价 `--log_level debug`）。 | | 46 | | `-v` / `--verbose` | 无 | `bool` | 不带值开关 | 可选 | 关闭 | 传入即启用 | 提高输出详细程度（等价 `--log_level debug`）。 | |
| @@ -76,7 +78,6 @@ msmodelslim analyze attn_head --model_type <model_type> --model_path <model_path | |||
| 76 | | 参数 | 别名 | 类型 | 传入形式 | 必选/可选 | 默认值 | 取值范围或格式 | 含义 | | 78 | | 参数 | 别名 | 类型 | 传入形式 | 必选/可选 | 默认值 | 取值范围或格式 | 含义 | |
| 77 | |------|------|------|----------|-----------|--------|----------------|------| | 79 | |------|------|------|----------|-----------|--------|----------------|------| |
| 78 | | `--metrics` | 无 | `string` | 单值 | 可选 | `ra_compress` | `ra_compress` | Attention Head 筛选指标，仅支持 `ra_compress`；仅适用于 LLM，不支持多模态理解 / 多模态生成。 | | 80 | | `--metrics` | 无 | `string` | 单值 | 可选 | `ra_compress` | `ra_compress` | Attention Head 筛选指标，仅支持 `ra_compress`；仅适用于 LLM，不支持多模态理解 / 多模态生成。 | |
| 79 | -| `--save_path` | 无 | `string` | 单值 | 可选 | 无 | 可写目录或文件路径 | 保存 `head.pt` 的路径。 | | ||
| 80 | 81 | ||
| 81 | ## 4. 参数关系 | 82 | ## 4. 参数关系 |
| 82 | 83 | ||
| @@ -84,8 +85,9 @@ msmodelslim analyze attn_head --model_type <model_type> --model_path <model_path | |||
| 84 | - 省略 `scope` 时默认按 `linear` 执行；`msmodelslim analyze -h`/`--help` 时不注入 scope，展示 scope 帮助。 | 85 | - 省略 `scope` 时默认按 `linear` 执行；`msmodelslim analyze -h`/`--help` 时不注入 scope，展示 scope 帮助。 |
| 85 | - `--device` 接受 `npu`/`cpu`；多卡分析使用 `--device npu --device_id 0 1 ...`（长度 > 1 启用 `DPLayerWiseRunner`）。兼容遗留写法 `--device npu:0,1`，会自动转换为上述推荐形式。 | 86 | - `--device` 接受 `npu`/`cpu`；多卡分析使用 `--device npu --device_id 0 1 ...`（长度 > 1 启用 `DPLayerWiseRunner`）。兼容遗留写法 `--device npu:0,1`，会自动转换为上述推荐形式。 |
| 86 | - 历史用法 `--metrics attention_mse`（省略 scope 时）会转换为 `analyze attn --metrics mse` 并丢弃 `--patterns`；该行为仅为向后兼容，命令会给出废弃提示，不推荐作为正式用法。 | 87 | - 历史用法 `--metrics attention_mse`（省略 scope 时）会转换为 `analyze attn --metrics mse` 并丢弃 `--patterns`；该行为仅为向后兼容，命令会给出废弃提示，不推荐作为正式用法。 |
| 87 | -- `--top_k` 必须为大于0的整数；`--calibration_dataset`：LLM 须为 `.json`/`.jsonl`，VLM 可为图文目录名（如 `calibImages`）。 | 88 | +- `--top_k` 必须为大于0的整数；`--calibration_dataset`：LLM 为 `.json`/`.jsonl`，VLM 可为图文目录名（如 `calibImages`）；对 `attn_head` 不生效。 |
| 88 | -- `attn_head` / `ra_compress` 仅支持 LLM；多模态理解与多模态生成模型不适用。校准集约定详见《[RA Compress 使用指南](../../knowledge_base/quantization_algorithms/ra_compress/usage_ra_compress.md)》。 | 89 | +- `--save_path` 对四个 scope 均可用，落盘内容随 scope 不同：`linear`/`layer`/`attn` 输出量化 YAML（`top <n>:` 加 `disable_names` 列表，`layer` scope 的整块回退名为 `<block>.*`），指定目录时文件名为 `<model_type>-<metrics>.yaml`；`attn_head` 输出 `head.pt`（含 `prefix_matching`/`copying` 两个字典），交付给后续 MindIE 推理框架的长序列 KV Cache 压缩能力使用，不写入量化配置。目录不存在时会自动创建；不指定该参数时结果只打印到日志。 |
| 90 | +- `attn_head` / `ra_compress` 仅支持 LLM；多模态理解与多模态生成模型不适用。该场景不使用外部校准集，校准输入由算法在运行时自行构造，详见《[RA Compress 使用指南](../../knowledge_base/quantization_algorithms/ra_compress/usage_ra_compress.md)》。 | ||
| 89 | 91 | ||
| 90 | ## 5. 使用示例 | 92 | ## 5. 使用示例 |
| 91 | 93 | ||
| @@ -150,25 +152,24 @@ msmodelslim analyze layer \ | |||
| 150 | 152 | ||
| 151 | `--device_id` 指定多个 NPU 索引时启用 `DPLayerWiseRunner` 做多卡敏感层分析。兼容写法：`--device npu:0,1,2,3`（会自动拆分为 `--device npu --device_id 0 1 2 3`）。 | 153 | `--device_id` 指定多个 NPU 索引时启用 `DPLayerWiseRunner` 做多卡敏感层分析。兼容写法：`--device npu:0,1,2,3`（会自动拆分为 `--device npu --device_id 0 1 2 3`）。 |
| 152 | 154 | ||
| 153 | -### 5.6 Attention Head / ra_compress（仅 LLM） | 155 | +### 5.6 注意力头分析 |
| 154 | 156 | ||
| 155 | ```bash | 157 | ```bash |
| 156 | msmodelslim analyze attn_head \ | 158 | msmodelslim analyze attn_head \ |
| 157 | --model_type "${MODEL_TYPE}" \ | 159 | --model_type "${MODEL_TYPE}" \ |
| 158 | --model_path "${MODEL_PATH}" \ | 160 | --model_path "${MODEL_PATH}" \ |
| 159 | --metrics ra_compress \ | 161 | --metrics ra_compress \ |
| 160 | - --calibration_dataset calib_dummy.jsonl \ | ||
| 161 | --device npu \ | 162 | --device npu \ |
| 162 | --save_path ./head_result | 163 | --save_path ./head_result |
| 163 | ``` | 164 | ``` |
| 164 | 165 | ||
| 165 | -仅适用于大语言模型；多模态理解与多模态生成模型不支持。校准集约定详见《[RA Compress 使用指南](../../knowledge_base/quantization_algorithms/ra_compress/usage_ra_compress.md)》。 | 166 | +仅适用于大语言模型；多模态理解与多模态生成模型不支持。该场景无需指定 `--calibration_dataset`：算法会在运行时自行构造受控的随机校准输入（首 token + 随机重复段），外部校准集不参与计算。产出的 `head.pt` 交付给 MindIE 推理框架用于长序列 KV Cache 压缩：用户可据此完成长序列压缩，压缩后的模型可用于后续推理部署；具体已适配的量化模型列表，请参见《[MindIE 是什么](https://www.hiascend.com/document/detail/zh/mindie/10RC3/whatismindie/mindie_what_0001.html)》的“MindIE 支持模型列表”章节。该产物不写入量化配置。校准输入约定详见《[RA Compress 注意力头分析使用指南](../../knowledge_base/quantization_algorithms/ra_compress/usage_ra_compress.md)》。 |
| 166 | 167 | ||
| 167 | ## 6. 退出码与异常处理 | 168 | ## 6. 退出码与异常处理 |
| 168 | 169 | ||
| 169 | | 退出码或异常 | 含义 | 处理建议 | | 170 | | 退出码或异常 | 含义 | 处理建议 | |
| 170 | |--------------|------|----------| | 171 | |--------------|------|----------| |
| 171 | -| `0` | 分析成功 | 按输出的层名更新量化配置（如写入 `exclude`）；`attn_head` 场景检查 `head.pt`。 | | 172 | +| `0` | 分析成功 | 按输出的层名更新量化配置（如写入 `exclude`）；指定 `--save_path` 时确认结果文件已生成（`linear`/`layer`/`attn` 为 YAML，`attn_head` 为 `head.pt`）。`attn_head` 场景将 `head.pt` 交付给 MindIE 推理框架用于长序列 KV Cache 压缩，用户可据此完成长序列压缩，压缩后的模型可用于后续推理部署；具体已适配的量化模型列表，请参见《[MindIE 是什么](https://www.hiascend.com/document/detail/zh/mindie/10RC3/whatismindie/mindie_what_0001.html)》的“MindIE 支持模型列表”章节。 | |
| 172 | | 非 `0` | 失败 | 查看错误日志。常见原因：scope 与 `--metrics` 取值不匹配、`--device`/`--device_id` 取值非法、校准集格式不符、`--top_k` 非大于0的整数、模型适配器未实现分析接口、多模态生成模型被拦截、`ra_compress` 用于非 LLM。 | | 173 | | 非 `0` | 失败 | 查看错误日志。常见原因：scope 与 `--metrics` 取值不匹配、`--device`/`--device_id` 取值非法、校准集格式不符、`--top_k` 非大于0的整数、模型适配器未实现分析接口、多模态生成模型被拦截、`ra_compress` 用于非 LLM。 | |
| 173 | 174 | ||
| 174 | ## 7. 安全说明 | 175 | ## 7. 安全说明 |
| @@ -17,12 +17,13 @@ | |||
| 17 | | 字段路径 | 类型 | 必选/可选 | 默认值 | 取值范围或格式 | 含义 | 引用配置 | | 17 | | 字段路径 | 类型 | 必选/可选 | 默认值 | 取值范围或格式 | 含义 | 引用配置 | |
| 18 | |----------|------|-----------|--------|----------------|------|----------| | 18 | |----------|------|-----------|--------|----------------|------|----------| |
| 19 | | `type` | `string` | 可选 | `unary_analysis` | `unary_analysis` | 处理器类型，固定为 `unary_analysis`。 | 无 | | 19 | | `type` | `string` | 可选 | `unary_analysis` | `unary_analysis` | 处理器类型，固定为 `unary_analysis`。 | 无 | |
| 20 | -| `metrics` | `string` | 可选 | `kurtosis` | — | 分析指标：`quantile`（分位数）、`std`（标准差）、`kurtosis`（峰度） | 无 | | 20 | +| `metrics` | `string` | 可选 | `kurtosis` | — | 分析指标：`quantile`（分位数）、`std`（标准差）、`kurtosis`（峰度）、`ra_compress`（RA Compress 长序列压缩头筛选） | 无 | |
| 21 | | `patterns` | `list[string]` | 可选 | `['*']` | — | 待分析的层名模式列表，默认 `*` 匹配全部 | 无 | | 21 | | `patterns` | `list[string]` | 可选 | `['*']` | — | 待分析的层名模式列表，默认 `*` 匹配全部 | 无 | |
| 22 | +| `metric_params` | `object` | 可选 | `{}` | — | 指标专属超参，仅由 `metrics` 指定的分析方法解析。当前仅 `metrics=ra_compress` 支持：`induction_head_ratio`（默认 0.14）、`echo_head_ratio`（默认 0.01），取值范围均为 [0, 1]。 | 无 | | ||
| 22 | 23 | ||
| 23 | **配置约束** | 24 | **配置约束** |
| 24 | 25 | ||
| 25 | -- 无。 | 26 | +- 校验指标专属超参，非法使用直接报错。 |
| 26 | 27 | ||
| 27 | ## 3. 完整配置参考 | 28 | ## 3. 完整配置参考 |
| 28 | 29 | ||
| @@ -34,4 +35,22 @@ spec: | |||
| 34 | metrics: kurtosis | 35 | metrics: kurtosis |
| 35 | patterns: | 36 | patterns: |
| 36 | - '*' | 37 | - '*' |
| 38 | + metric_params: {} | ||
| 39 | +``` | ||
| 40 | + | ||
| 41 | +## 4. 注意事项 | ||
| 42 | + | ||
| 43 | +- `metric_params` 仅对 `metrics=ra_compress` 生效，其它指标传入会直接报错；该字段只在配置中设置，CLI 不暴露对应参数，`msmodelslim analyze attn_head` 按默认值（`induction_head_ratio=0.14`、`echo_head_ratio=0.01`）执行。 | ||
| 44 | +- 比例越大，入选（保留）的 KV head 越多，KV Cache 压缩强度越低、精度风险越小、显存收益越小；比例越小则相反，建议按筛选头数与下游压缩比实测评估。 | ||
| 45 | +- 命令行流程读取随包安装的模板 `msmodelslim/core/analysis_service/pipeline_analysis/pipeline_template/ra_compress.yaml`；修改该 YAML 后，需在仓库根目录重新执行 `bash install.sh` 才会生效。 | ||
| 46 | + | ||
| 47 | +`ra_compress` 覆盖默认比例： | ||
| 48 | + | ||
| 49 | +```yaml | ||
| 50 | +process: | ||
| 51 | +- type: unary_analysis | ||
| 52 | + metrics: ra_compress | ||
| 53 | + metric_params: | ||
| 54 | + induction_head_ratio: 0.14 | ||
| 55 | + echo_head_ratio: 0.01 | ||
| 37 | ``` | 56 | ``` |
| @@ -83,9 +83,9 @@ msModelSlim 支持多种先进的量化算法，涵盖了从离群值抑制到 | |||
| 83 | 83 | ||
| 84 | ### 4.3 敏感层分析 | 84 | ### 4.3 敏感层分析 |
| 85 | 85 | ||
| 86 | -当前敏感层分析支持按不同范围（`linear` / `layer` / `attn` / `attn_head`）度量敏感度，并据此做对应粒度的回退、混精调参或 KV Cache 压缩配置。使用指南：《[线性层](../../user_guide/usage_sensitive_linear_analysis.md)》、《[层级](../../user_guide/usage_sensitive_layer_analysis.md)》、《[Attention](../../user_guide/usage_sensitive_attn_analysis.md)》、《[Attention Head](../../user_guide/usage_sensitive_attn_head_analysis.md)》。 | 86 | +当前敏感层分析支持按不同范围（`linear` / `layer` / `attn` / `attn_head`）度量敏感度，并据此做对应粒度的回退、混精调参；其中 `attn_head` 范围产出的是交付给后续 MindIE 推理框架用于长序列 KV Cache 压缩的关键头清单（`head.pt`），不写入量化配置。使用指南：《[线性层](../../user_guide/usage_sensitive_linear_analysis.md)》、《[层级](../../user_guide/usage_sensitive_layer_analysis.md)》、《[Attention](../../user_guide/usage_sensitive_attn_analysis.md)》、《[Attention Head](../../user_guide/usage_sensitive_attn_head_analysis.md)》。 |
| 87 | 87 | ||
| 88 | - **linear**（线性层）：首选 **Kurtosis**，用激活峰度刻画尖峰与尾部影响，辅助识别需回退或提升位宽的线性层。 | 88 | - **linear**（线性层）：首选 **Kurtosis**，用激活峰度刻画尖峰与尾部影响，辅助识别需回退或提升位宽的线性层。 |
| 89 | - **layer**（Decoder 块）：首选 **mse_layer_wise**，适合整层 / 整块（如 MLP、Attention 段）回退。 | 89 | - **layer**（Decoder 块）：首选 **mse_layer_wise**，适合整层 / 整块（如 MLP、Attention 段）回退。 |
| 90 | - **attn**（Attention 结构）：首选 **Attention MSE（mse）**，主要用于配合 **FA3 Quant** 识别需回退的 Attention 模块（需适配器接口）。 | 90 | - **attn**（Attention 结构）：首选 **Attention MSE（mse）**，主要用于配合 **FA3 Quant** 识别需回退的 Attention 模块（需适配器接口）。 |
| 91 | -- **attn_head**（注意力头）：首选 **RA Compress**，基于重复段结构筛选归纳头 / 回声头，用于长序列 KV Cache 压缩配置（仅支持 LLM，须使用 `calib_dummy.jsonl`）。 | 91 | +- **attn_head**（注意力头）：首选 **RA Compress**，基于重复段结构筛选归纳头 / 回声头，产出交付给后续 MindIE 推理框架的 `head.pt` 关键头清单，供 MindIE 做长序列 KV Cache 压缩（仅支持 LLM，校准输入由算法在运行时自行构造，无需 `--calibration_dataset`）。 |
| @@ -1,198 +1,101 @@ | |||
| 1 | -# RA Compress 长序列压缩算法词条 | 1 | +# RA Compress 长序列压缩算法 量化术语百科词条 |
| 2 | 2 | ||
| 3 | -> **词条类别**：敏感层分析算法（长序列 KV cache 压缩） | 3 | +> **词条类别**：[敏感层分析算法](../README.md#3-敏感层分析算法)<br> |
| 4 | -> **英文名称**：RazorAttention Compress | 4 | +> **英文名称**：RazorAttention Compress（`ra_compress`）<br> |
| 5 | -> **英文缩写**：ra_compress | 5 | +> **应用领域**：长序列推理、KV cache 压缩、注意力头筛选<br> |
| 6 | -> **应用领域**：长序列推理、KV cache 压缩、注意力头筛选 | ||
| 7 | -> **msModelSlim 实现**：[`msmodelslim/processor/analysis/unary_operator/metrics/ra_compress/`](../../../../../msmodelslim/processor/analysis/unary_operator/metrics/ra_compress/) | ||
| 8 | 6 | ||
| 9 | --- | 7 | --- |
| 10 | 8 | ||
| 11 | ## 1. 概述 | 9 | ## 1. 概述 |
| 12 | 10 | ||
| 13 | -RA Compress（`ra_compress`）是 `msmodelslim analyze` 中 `attn_head` 范围分析的一种度量算法。它基于 Transformer 中注意力头的跨段（segment-spanning）注意力行为，识别具有 prefix matching（归纳头）和 copying matching（回声头）能力的关键 KV head，用于后续 KV cache 压缩配置。其核心特征是：依赖合成的重复段校准数据、分析 Q@K^T 注意力分数在段间偏移位置的聚合统计、按固定 ratio 选择 top heads、输出 `head.pt` 文件供后续压缩流程使用。 | 11 | +RA Compress（`ra_compress`）是一种注意力头（KV head）粒度的长序列压缩筛选算法。它基于 Transformer 中注意力头的跨段（segment-spanning）注意力行为，识别具备 prefix matching（归纳头）与 copying matching（回声头）能力的关键 KV head，作为长序列推理时 KV cache 压缩的保留依据；核心特征是用等长重复段构造受控输入，把“跨段检索能力”本身变成可度量的分数，可与同样位于 attn 范围的 [Attention MSE](../attention_mse/term_attention_mse.md) 等敏感层分析指标互补。 |
| 14 | 12 | ||
| 15 | --- | 13 | --- |
| 16 | 14 | ||
| 17 | ## 2. 词条介绍 | 15 | ## 2. 词条介绍 |
| 18 | 16 | ||
| 19 | -长文本（长序列）推理时，KV cache 随序列长度线性增长，是端侧和大模型推理时显存的主要瓶颈。RA Compress 观察到：并非所有 KV head 对长上下文质量的贡献都是均等的——具有强归纳（induction）和复制（copying）能力的注意力头是跨段信息传递的关键锚点，在 KV cache 压缩时应优先保留。RA Compress 通过构造**等长重复段**（`DUMMY_INPUT_LENGTH=2500` × `REPET_TIMES=4`，总计 ≥ 10000 tokens）的合成校准数据，在段间特定偏移位置度量注意力强度，从而为每层、每个 head 计算 prefix matching / copying matching 得分，再按预设 ratio 选 top heads 作为压缩保留目标。 | 17 | +长文本（长序列）推理时，KV cache 随序列长度线性增长，是端侧和大模型推理时显存的主要瓶颈。RA Compress 观察到：并非所有 KV head 对长上下文质量的贡献都是均等的——具有强归纳（induction）和复制（copying）能力的注意力头是跨段信息传递的关键锚点，在 KV cache 压缩时应优先保留。因此它不从任务数据反推重要性，而是直接构造重复段输入，在段间固定偏移位置度量注意力强度，把“是否具备跨段检索能力”作为筛选依据。 |
| 20 | 18 | ||
| 21 | ---- | 19 | +### 2.1 核心思想 |
| 22 | 20 | ||
| 23 | -## 3. 原理 | 21 | +RA Compress 的核心思想是“利用重复段结构定位跨段关键头”。输入被设计为若干段**完全相同的 token 序列**；在这种结构下，真正承担跨段信息传递的头会表现出可预测的注意力落点：归纳头在当前段某位置会关注上一段中紧邻其前一位的 token（prefix matching），回声头则直接复制上一段相同位置的信息（copying matching）。 |
| 24 | 22 | ||
| 25 | -### 3.1 核心思想 | 23 | +这些落点在普通文本上受语义与位置分布干扰、难以稳定观测；而在重复段结构下会以集中的注意力峰值出现，于是“某头是否具备跨段检索能力”就转化为一个在受控条件下可复现的分数。 |
| 26 | 24 | ||
| 27 | -RA Compress 的核心思想是“利用重复段结构定位跨段关键头”：构造 4 段完全相同的 2500 tokens 重复序列（共 10000 tokens）。在段边界处，具有归纳能力的头会在当前段的 prefix 位置关注前一段对应位置 + 1（prefix matching，`offset = -SEG + 1`），而具有复制能力的头会在当前段位置关注前一段对应位置（copying matching，`offset = -SEG`）。对每一层，在重复的段对上取该偏移位置的注意力分数作逐段平均，得到每个 head 的 prefix / copying 得分；得分 top ratio 的 head 入选为 KV cache 压缩时需要保留的 KV head 索引。 | 25 | +### 2.2 工作机制 |
| 28 | 26 | ||
| 29 | -### 3.2 数学描述 | 27 | +RA Compress 的工作机制可以分为三步： |
| 28 | + | ||
| 29 | +1. **构造重复段校准输入**：由首 token 与若干段等长随机 token 组成，段长与段数为算法内建常量——首 token 提供可复用的起始条件，段长 `2500`、重复 `4` 段，总长 `1 + 2500 × 4`；段内内容完全相同，整体不依赖任何外部数据。 | ||
| 30 | +2. **计算段间偏移注意力**：在自注意力的 Q / K 投影上采集输出，对每一层计算 $QK^\top$ 并 softmax 得到注意力矩阵；再在每个段对上读取两个固定偏移位置——`-SEG + 1` 对应 prefix matching、`-SEG` 对应 copying matching，对该偏移位置在重复段对上取平均，即得到该层每个 head 的两类得分。 | ||
| 31 | +3. **分组与选择**：若模型使用 GQA / MQA，先在每个 KV head 对应的 query head 组内取最大得分作为该 KV head 的代表分；再把所有层、所有 KV head 的得分整体排序，按比例选出 top KV head 作为保留对象，输出为 KV head 索引列表。 | ||
| 32 | + | ||
| 33 | +整个过程中被评估的不是“模型在某份数据上的表现”，而是注意力结构本身在受控重复条件下是否具备跨段检索能力，因此不需要用户准备校准集。 | ||
| 34 | + | ||
| 35 | +### 2.3 数学描述 | ||
| 30 | 36 | ||
| 31 | 设 $A \in \mathbb{R}^{L \times L}$ 为某一层在重复段校准数据上的注意力矩阵（对 Q 与 K 的 outer product 做 softmax 后）。对所有满足 $i \in [(k+1) \cdot SEG, (k+2) \cdot SEG]$ 的位置 $i$（第 $k+1$ 段），分别考察以下两个偏移量位置： | 37 | 设 $A \in \mathbb{R}^{L \times L}$ 为某一层在重复段校准数据上的注意力矩阵（对 Q 与 K 的 outer product 做 softmax 后）。对所有满足 $i \in [(k+1) \cdot SEG, (k+2) \cdot SEG]$ 的位置 $i$（第 $k+1$ 段），分别考察以下两个偏移量位置： |
| 32 | 38 | ||
| 33 | **Prefix matching 得分（归纳头）**： | 39 | **Prefix matching 得分（归纳头）**： |
| 40 | + | ||
| 34 | $$ | 41 | $$ |
| 35 | \text{prefix\_score}_h = \text{mean}_{k, i} A_h[i, i - k \cdot SEG + 1] | 42 | \text{prefix\_score}_h = \text{mean}_{k, i} A_h[i, i - k \cdot SEG + 1] |
| 36 | $$ | 43 | $$ |
| 37 | -（在第 $k+1$ 段的位置 $i$ 上，注意力落在第 $k$ 段的 $i - SEG + 1$ 处的概率，即“前一段 prefix 位置 + 1”，对应归纳头的典型行为。） | 44 | + |
| 45 | +即第 $k+1$ 段的位置 $i$ 上，注意力落在第 $k$ 段的 $i - SEG + 1$ 处（前一段 prefix 位置 + 1）的概率，对应归纳头的典型行为。 | ||
| 38 | 46 | ||
| 39 | **Copying matching 得分（回声头）**： | 47 | **Copying matching 得分（回声头）**： |
| 48 | + | ||
| 40 | $$ | 49 | $$ |
| 41 | \text{copying\_score}_h = \text{mean}_{k, i} A_h[i, i - (k+1) \cdot SEG] | 50 | \text{copying\_score}_h = \text{mean}_{k, i} A_h[i, i - (k+1) \cdot SEG] |
| 42 | $$ | 51 | $$ |
| 43 | -（在第 $k+1$ 段的位置 $i$ 上，注意力落在第 $k$ 段相同偏移 $i - SEG$ 处的概率，对应“复制前一段对应位置”的回声头行为。） | ||
| 44 | 52 | ||
| 45 | -其中 $SEG = \text{DUMMY\_INPUT\_LENGTH} = 2500$，$k \in \{0, 1, 2\}$（共 3 个段对），head $h$ 为 GQA 分组前的 attention head。 | 53 | +即第 $k+1$ 段的位置 $i$ 上，注意力落在第 $k$ 段相同偏移 $i - SEG$ 处的概率，对应“复制前一段对应位置”的回声头行为。 |
| 54 | + | ||
| 55 | +其中 $SEG = 2500$（段长），$k \in \{0, 1, 2\}$（共 3 个段对），head $h$ 为 GQA 分组前的 attention head。 | ||
| 56 | + | ||
| 57 | +**GQA 分组合并**：若模型使用 GQA / MQA（$num\_kv\_heads < num\_attention\_heads$），则在每个 KV head 对应的 query head 组内取最大得分作为该 KV head 的代表分： | ||
| 46 | 58 | ||
| 47 | -**GQA 分组合并**：若模型使用 GQA / MQA（`num_kv_heads < num_attention_heads`），则在每个 KV head 对应的 query head 组内取最大得分作为该 KV head 的代表分： | ||
| 48 | $$ | 59 | $$ |
| 49 | \text{grouped\_score}[g] = \max_{h \in \text{group}[g]} \text{score}_h | 60 | \text{grouped\_score}[g] = \max_{h \in \text{group}[g]} \text{score}_h |
| 50 | $$ | 61 | $$ |
| 51 | 62 | ||
| 52 | -**Top ratio 选择**：对所有层、所有 KV head 的得分整体排序，取前 `induction_head_ratio`（默认 14%）的 KV head 作为 prefix matching 入选（induction heads），取前 `echo_head_ratio`（默认 1%）的 KV head 作为 copying matching 入选（echo heads）。 | 63 | +**Top ratio 选择**：对所有层、所有 KV head 的得分整体排序，取前 `induction_head_ratio`（默认 14%）的 KV head 作为 prefix matching 入选（induction heads），取前 `echo_head_ratio`（默认 1%）的 KV head 作为 copying matching 入选（echo heads）。两个比例合法取值范围为 $[0, 1]$。 |
| 53 | 64 | ||
| 54 | -### 3.3 关键性质 | 65 | +### 2.4 关键性质 |
| 55 | 66 | ||
| 56 | -- **仅支持 LLM**：不支持多模态理解（VLM）与多模态生成（文生图 / 文生视频等）模型；请仅对大语言模型使用 `analyze attn_head --metrics ra_compress`。 | ||
| 57 | -- **必须使用 `calib_dummy.jsonl`**：须通过 `--calibration_dataset calib_dummy.jsonl` 显式指定内置合成校准集（`attn_head` 不再设置默认值）；该文件经 tokenizer 后严格对齐到 2500×4 段边界。使用其他校准集不保证筛选效果。 | ||
| 58 | - **attn_head 粒度**：输出 KV head 粒度的入选列表（每层若干 head 索引），而非层粒度排序。 | 67 | - **attn_head 粒度**：输出 KV head 粒度的入选列表（每层若干 head 索引），而非层粒度排序。 |
| 59 | -- **数据依赖强**：内置 `calib_dummy.jsonl` 满足 tokenize 后总长度 ≥ 10000 tokens；长度不足时段位置偏移无意义、得分被置空。 | 68 | +- **双通道筛选**：归纳头（prefix matching）与回声头（copying matching）分别按比例独立选出，二者对应不同的跨段信息传递机制。 |
| 60 | -- **适配器接口可选依赖**：默认匹配 `q_proj` / `k_proj` / `qkv_proj` 命名，若模型命名不同，需在适配器实现 `RaCompressAnalysisInterface`。 | 69 | +- **受控合成输入**：校准输入由算法内部按固定配方构造，不读取外部校准集，因此结果与用户业务语料无关，可复现性强。 |
| 61 | -- **结果用于压缩而非回退**：输出为 `head.pt`（dict 序列化的 `.pt` 文件），供 RA Compress KV cache 压缩流程读取，而非用于量化 YAML 的 exclude / include 配置。 | 70 | +- **比例决定入选规模**：保留多少个 head 不由分数阈值决定，而由 top ratio 决定，比例设置直接决定入选集合大小。 |
| 71 | +- **位置编码一致性**：计算得分前对注入的 Q / K 施加位置编码，使度量条件与真实推理时的注意力形态保持一致。 | ||
| 72 | +- **输出为离散集合**：只输出入选 head 索引，不输出敏感度分数排序，因此不能用于连续阈值的回退决策。 | ||
| 73 | +- **结果用于压缩而非回退**：输出为 `head.pt`（dict 序列化的 `.pt` 文件），交付给 MindIE 推理框架用于长序列 KV cache 压缩。用户可根据 `head.pt` 完成长序列压缩，压缩后的模型可用于后续推理部署；具体已适配的量化模型列表，请参见《[MindIE 是什么](https://www.hiascend.com/document/detail/zh/mindie/10RC3/whatismindie/mindie_what_0001.html)》的“MindIE 支持模型列表”章节。该产物不用于量化 YAML 的 exclude / include 配置，也不用于层回退决策。 | ||
| 74 | + | ||
| 75 | +### 2.5 适用场景 | ||
| 76 | + | ||
| 77 | +- 长序列推理场景下，需要了解模型中哪些 KV head 承担了跨段信息传递（归纳 / 复制头）的场景。 | ||
| 78 | +- 需要为 KV cache 压缩确定“应保留哪些 KV head”的保留集合的场景。 | ||
| 79 | +- 无需准备外部校准集，希望快速对模型注意力头能力做筛选的分析场景。 | ||
| 80 | + | ||
| 81 | +### 2.6 使用限制 | ||
| 82 | + | ||
| 83 | +- 目前仅支持大语言模型（LLM）；不支持多模态理解模型（VLM）与多模态生成模型（文生图 / 文生视频等）。 | ||
| 84 | +- 仅分析 Transformer 自注意力的 Q / K 投影层（或 QKV 融合层），其他结构不在分析范围内；投影层命名不符合默认模式的模型，需由模型适配器通过 `RaCompressAnalysisInterface.get_proj_names` 提供命名信息。 | ||
| 85 | +- 结果依赖重复段这一受控输入结构，反映的是注意力头的跨段检索能力，不能直接等同于模型在真实长文本任务上的质量表现。 | ||
| 86 | +- 输出为离散入选集合而非连续分数，入选比例的变化会整体改变结果，不同比例下的结果之间不具备“分数大小”意义上的可比性。 | ||
| 87 | +- `model_type` 支持范围参见《[大模型支持矩阵](../../model/README.md)》及对应的适配器实现情况。 | ||
| 62 | 88 | ||
| 63 | --- | 89 | --- |
| 64 | 90 | ||
| 65 | -## 4. 流程示意 | 91 | +## 3. 关联流程 |
| 66 | 92 | ||
| 67 | -> 以下为本算法在 msModelSlim 中的简化流程概览。 | 93 | +- 《[Attention Head 筛选分析使用指南](../../../user_guide/usage_sensitive_attn_head_analysis.md)》：本算法作为 `attn_head` 范围分析的 metrics 使用。 |
| 68 | - | 94 | +- MindIE 推理框架侧（交付件消费方）：分析产出的 `head.pt` 交付给 MindIE 推理框架，用户可据此完成长序列压缩，压缩后的模型可用于后续推理部署；具体已适配的量化模型列表，请参见《[MindIE 是什么](https://www.hiascend.com/document/detail/zh/mindie/10RC3/whatismindie/mindie_what_0001.html)》的“MindIE 支持模型列表”章节。 |
| 69 | -```mermaid | ||
| 70 | -flowchart LR | ||
| 71 | - A[calib_dummy.jsonl<br/>合成校准集] --> B[Q_proj / K_proj hook<br/>采集输出] | ||
| 72 | - B --> C[逐段计算<br/>Q @ K^T] | ||
| 73 | - C --> D[段间偏移<br/>位置取注意力] | ||
| 74 | - D --> E[逐段平均<br/>得到 head 得分] | ||
| 75 | - E --> F[GQA 分组<br/>取 max] | ||
| 76 | - F --> G[按 ratio<br/>选 top heads] | ||
| 77 | - G --> H[写入 layer_scores<br/>(enrich)] | ||
| 78 | - H --> I[保存<br/>head.pt] | ||
| 79 | -``` | ||
| 80 | 95 | ||
| 81 | --- | 96 | --- |
| 82 | 97 | ||
| 83 | -## 5. 在 msModelSlim 中的实现 | 98 | +## 4. 关联词条 |
| 84 | - | ||
| 85 | -### 5.1 实现位置 | ||
| 86 | - | ||
| 87 | -RA Compress 作为 `msmodelslim analyze` 命令的 `attn_head` 范围分析指标实现，位于 [`msmodelslim/processor/analysis/unary_operator/metrics/ra_compress/`](../../../../../msmodelslim/processor/analysis/unary_operator/metrics/ra_compress/)。 | ||
| 88 | - | ||
| 89 | -模块结构： | ||
| 90 | - | ||
| 91 | -- `interface.py`：定义 `RaCompressAnalysisInterface`，在模型适配器侧提供 Q / K / QKV 投影层名称模式。 | ||
| 92 | -- `__init__.py`：`RaCompressAnalysisMethod` 主实现（hook、得分计算、分组、head 选择、layer_scores enrich）。 | ||
| 93 | - | ||
| 94 | -### 5.2 处理流程 | ||
| 95 | - | ||
| 96 | -通过 `msmodelslim analyze attn_head --metrics ra_compress` 命令执行（`attn_head` 默认 metrics）： | ||
| 97 | - | ||
| 98 | -1. 在 Q / K（或 QKV 融合）投影层上注册 forward hook，在 `outputs` 位置保存该层的输出张量。 | ||
| 99 | -2. 每层计算得分时，若为 Q 层则取出该层对应 K 层的输出（反之亦然），计算 `Q @ K^T` 并按 head 拆分。 | ||
| 100 | -3. 对每个 head 的注意力矩阵，分别计算段间 `offset = -SEG + 1`（prefix）与 `offset = -SEG`（copying）位置的逐段平均得分。 | ||
| 101 | -4. 经过 `_max_every_group`（GQA 分组 max）后，按 `_select_top_heads` 取 14% / 1% top heads。 | ||
| 102 | -5. `enrich_layer_scores` 将入选的 `induction_heads` / `echo_heads`（KV head 索引列表）挂到 `layer_scores` 条目里。 | ||
| 103 | -6. 结果展示器遍历 `layer_scores` 重建 head_dict，打印入选列表并保存 `head.pt`（结构为 `{"prefix_matching": {layer_idx: [kv_head_idx, ...]}, "copying": {...}}`）。 | ||
| 104 | - | ||
| 105 | -### 5.3 命令行示例 | ||
| 106 | - | ||
| 107 | -```bash | ||
| 108 | -msmodelslim analyze attn_head \ | ||
| 109 | - --model_type Qwen2.5-7B-Instruct \ | ||
| 110 | - --model_path ${model_path} \ | ||
| 111 | - --metrics ra_compress \ | ||
| 112 | - --calibration_dataset calib_dummy.jsonl \ | ||
| 113 | - --device npu \ | ||
| 114 | - --trust_remote_code true \ | ||
| 115 | - --save_path ./head_result | ||
| 116 | -``` | ||
| 117 | - | ||
| 118 | -### 5.4 模型适配接口 | ||
| 119 | - | ||
| 120 | -RA Compress 分析需要定位 Transformer 自注意力的 Q / K（或 QKV 融合）投影层以挂载 hook 采集输出。不同模型的投影层命名可能不一致，因此通过模型适配器接口 `RaCompressAnalysisInterface` 暴露名称模式，由分析方法据此匹配目标层。当适配器未实现该接口时，方法回退到默认名称（`q_proj` / `k_proj` / `qkv_proj`），仅适用于遵循该命名约定的模型。 | ||
| 121 | - | ||
| 122 | -**接口定义**：[`RaCompressAnalysisInterface`](../../../../../msmodelslim/processor/analysis/unary_operator/metrics/ra_compress/interface.py) | ||
| 123 | - | ||
| 124 | -**接口方法**： | ||
| 125 | - | ||
| 126 | -| 方法 | 返回类型 | 说明 | | ||
| 127 | -| --- | --- | --- | | ||
| 128 | -| `get_ra_compress_proj_patterns()` | `Dict[str, str]` | 返回 Q / K / QKV 投影层名称模式字典 | | ||
| 129 | - | ||
| 130 | -返回值格式： | ||
| 131 | - | ||
| 132 | -```python | ||
| 133 | -{ | ||
| 134 | - "q": "q_proj", # Q 投影层名称模式 | ||
| 135 | - "k": "k_proj", # K 投影层名称模式 | ||
| 136 | - "qkv": "qkv_proj", # QKV 融合投影层名称模式（无融合时留空字符串） | ||
| 137 | -} | ||
| 138 | -``` | ||
| 139 | - | ||
| 140 | -**名称匹配规则**（见 [`RaCompressAnalysisMethod._is_target_layer`](../../../../../msmodelslim/processor/analysis/unary_operator/metrics/ra_compress/__init__.py)）：分析方法对 `model.named_modules()` 中每个 `nn.Linear`，判断其层名是否包含上述任一模式字符串，命中即作为目标层挂载 hook。 | ||
| 141 | - | ||
| 142 | -**默认回退**：适配器未实现 `RaCompressAnalysisInterface` 时，使用以下默认模式（见 [`__init__.py`](../../../../../msmodelslim/processor/analysis/unary_operator/metrics/ra_compress/__init__.py) 顶部常量）： | ||
| 143 | - | ||
| 144 | -| 键 | 默认值 | 常量 | | ||
| 145 | -| --- | --- | --- | | ||
| 146 | -| `q` | `q_proj` | `_DEFAULT_Q_NAME_PATTERN` | | ||
| 147 | -| `k` | `k_proj` | `_DEFAULT_K_NAME_PATTERN` | | ||
| 148 | -| `qkv` | `qkv_proj` | `_DEFAULT_QKV_NAME_PATTERN` | | ||
| 149 | - | ||
| 150 | -**适配器实现示例**： | ||
| 151 | - | ||
| 152 | -当模型投影层命名与默认值不一致时（例如使用 `query_proj` / `key_proj`），在模型适配器中实现接口并覆盖名称模式： | ||
| 153 | - | ||
| 154 | -```python | ||
| 155 | -from msmodelslim.processor.analysis.unary_operator.metrics.ra_compress.interface import ( | ||
| 156 | - RaCompressAnalysisInterface, | ||
| 157 | -) | ||
| 158 | - | ||
| 159 | -class XxxAdapter(RaCompressAnalysisInterface): | ||
| 160 | - def get_ra_compress_proj_patterns(self): | ||
| 161 | - return { | ||
| 162 | - "q": "query_proj", | ||
| 163 | - "k": "key_proj", | ||
| 164 | - "qkv": "", # 该模型无 QKV 融合层 | ||
| 165 | - } | ||
| 166 | -``` | ||
| 167 | - | ||
| 168 | ---- | ||
| 169 | - | ||
| 170 | -## 6. 适用场景与限制 | ||
| 171 | - | ||
| 172 | -### 6.1 适用场景 | ||
| 173 | - | ||
| 174 | -- 需要为 KV cache 压缩（RA Compress）方案生成 `head.pt` 的场景。 | ||
| 175 | -- 长序列推理场景下，需要了解模型中哪些 KV head 承担了跨段信息传递（归纳 / 复制头）。 | ||
| 176 | -- 使用内置合成校准集 `calib_dummy.jsonl` 的注意力头能力分析。 | ||
| 177 | - | ||
| 178 | -### 6.2 使用限制 | ||
| 179 | - | ||
| 180 | -- **必须**通过 `--calibration_dataset calib_dummy.jsonl` 显式指定内置合成校准集；使用其他校准集不保证筛选效果。 | ||
| 181 | -- 目前仅分析 Transformer 自注意力的 Q / K 投影层（或 QKV 融合层）；其他结构不在范围内。 | ||
| 182 | -- 结果不输出敏感度 Score 排序，只输出入选的 head 索引；ratio 目前使用默认常量（14% / 1%），不通过 YAML 配置。 | ||
| 183 | -- 仅支持 LLM；不支持多模态理解与多模态生成模型。 | ||
| 184 | -- `model_type` 支持范围参见《[大模型支持矩阵](../../model/README.md)》及适配器对 `RaCompressAnalysisInterface` 的实现情况。 | ||
| 185 | - | ||
| 186 | ---- | ||
| 187 | - | ||
| 188 | -## 7. 关联流程 | ||
| 189 | - | ||
| 190 | -- 《[Attention Head 筛选分析使用指南](../../../user_guide/usage_sensitive_attn_head_analysis.md)》：本算法作为 `attn_head` 分析的 metrics 使用。 | ||
| 191 | -- 《[一键量化 (V1)](../../../user_guide/usage_quick_quantization.md)》：分析产出的 `head.pt` 可在 RA Compress 相关量化流程中使用。 | ||
| 192 | - | ||
| 193 | ---- | ||
| 194 | - | ||
| 195 | -## 8. 关联词条 | ||
| 196 | 99 | ||
| 197 | - [KVCache Quant](../kvcache_quant/term_kvcache_quant.md)：配套术语，KV cache 的量化方案，与 RA Compress 同属长序列显存优化范畴。 | 100 | - [KVCache Quant](../kvcache_quant/term_kvcache_quant.md)：配套术语，KV cache 的量化方案，与 RA Compress 同属长序列显存优化范畴。 |
| 198 | - [KV Smooth](../kv_smooth/term_kv_smooth.md)：配套术语，针对 KV cache 的离群值抑制算法。 | 101 | - [KV Smooth](../kv_smooth/term_kv_smooth.md)：配套术语，针对 KV cache 的离群值抑制算法。 |
| @@ -201,7 +104,6 @@ class XxxAdapter(RaCompressAnalysisInterface): | |||
| 201 | 104 | ||
| 202 | --- | 105 | --- |
| 203 | 106 | ||
| 204 | -## 9. 参考资料 | 107 | +## 5. 参考文档 |
| 205 | 108 | ||
| 206 | -1. 《RA Compress 使用指南》([./usage_ra_compress.md](./usage_ra_compress.md)) | 109 | +1. 论文：*RazorAttention: Efficient KV Cache Compression Through Retrieval Heads*（induction / copying head 相关背景） |
| 207 | -2. 论文：*RazorAttention: Efficient KV Cache Compression Through Retrieval Heads*（induction / copying head 相关背景） | ||
| @@ -1,18 +1,18 @@ | |||
| 1 | -# RA Compress 注意力头分析配置使用指南 | 1 | +# RA Compress 注意力头分析使用指南 |
| 2 | 2 | ||
| 3 | ## 1. 适用范围 | 3 | ## 1. 适用范围 |
| 4 | 4 | ||
| 5 | -本指南面向需要使用 [RA Compress 注意力头分析算法](./term_ra_compress.md) 的用户。RA Compress（`ra_compress`）作为 `msmodelslim analyze attn_head` 的 metrics 指标，用于 KV 注意力头粒度的筛选，输出归纳头（induction heads）与回声头（echo heads）的入选索引，供后续 KV cache 压缩流程使用。 | 5 | +本指南面向需要使用 [RA Compress 注意力头分析算法](./term_ra_compress.md) 的用户。RA Compress（`ra_compress`）作为 `msmodelslim analyze attn_head` 的 metrics 指标，用于 KV 注意力头粒度的筛选，输出归纳头（induction heads）与回声头（echo heads）的入选索引，交付给 MindIE 推理框架用于长序列 KV cache 压缩：用户可据此完成长序列压缩，压缩后的模型可用于后续推理部署；具体已适配的量化模型列表，请参见《[MindIE 是什么](https://www.hiascend.com/document/detail/zh/mindie/10RC3/whatismindie/mindie_what_0001.html)》的“MindIE 支持模型列表”章节。该产物不写入量化配置。 |
| 6 | 6 | ||
| 7 | 适用场景： | 7 | 适用场景： |
| 8 | 8 | ||
| 9 | -- 需要为长序列推理生成 KV cache 压缩配置（`head.pt`）的场景； | 9 | +- 需要为长序列推理生成 KV Cache 压缩所需关键头清单（`head.pt`）的场景； |
| 10 | - 需要了解模型中哪些 KV head 承担跨段信息传递（归纳 / 复制头）的场景。 | 10 | - 需要了解模型中哪些 KV head 承担跨段信息传递（归纳 / 复制头）的场景。 |
| 11 | 11 | ||
| 12 | 不适用场景： | 12 | 不适用场景： |
| 13 | 13 | ||
| 14 | - **多模态理解模型（VLM）** 与 **多模态生成模型**（文生图 / 文生视频等）：`ra_compress` / `analyze attn_head` 当前仅支持大语言模型（LLM）； | 14 | - **多模态理解模型（VLM）** 与 **多模态生成模型**（文生图 / 文生视频等）：`ra_compress` / `analyze attn_head` 当前仅支持大语言模型（LLM）； |
| 15 | -- 目标 `model_type` 的适配器未实现 `RaCompressAnalysisInterface` 且 Q/K 投影层命名与默认模式不匹配。 | 15 | +- 目标 `model_type` 的适配器既未实现 `RaCompressAnalysisInterface`，Q/K 投影层命名也不符合默认模式（`q_proj` / `k_proj` / `qkv_proj`）。 |
| 16 | 16 | ||
| 17 | 模型是否在官方预验证列表中请参考[《大模型支持矩阵》](../../model/README.md)；如需快速了解 CLI 基础用法可参阅[《一键量化完整指南》](../../../user_guide/usage_one_click_quantization.md)。 | 17 | 模型是否在官方预验证列表中请参考[《大模型支持矩阵》](../../model/README.md)；如需快速了解 CLI 基础用法可参阅[《一键量化完整指南》](../../../user_guide/usage_one_click_quantization.md)。 |
| 18 | 18 | ||
| @@ -21,10 +21,10 @@ | |||
| 21 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | | 21 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | |
| 22 | | --- | --- | --- | --- | --- | | 22 | | --- | --- | --- | --- | --- | |
| 23 | | 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` 分片 | 可被目标 Transformers 版本正常加载 | | 23 | | 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` 分片 | 可被目标 Transformers 版本正常加载 | |
| 24 | -| 输入 | 模型适配器 | 用户适配代码，通过 `--model_type` 调用 | 实现 `PipelineInterface` 及对应的 `RaCompressAnalysisInterface` 专用接口 | 能被调度器（Runner）与处理器（Processor）正常驱动 | | 24 | +| 输入 | 模型适配器 | 用户适配代码，通过 `--model_type` 调用 | 实现 `PipelineInterface` 及 `RaCompressAnalysisInterface`（`get_proj_names`、`get_tokenizer` 均需实现） | 能被调度器（Runner）与处理器（Processor）正常驱动 | |
| 25 | -| 输入 | 校准数据集 | 工具内置 `calib_dummy.jsonl`（本算法须显式指定） | JSONL 格式文本 Prompt，推荐 50 条；经 tokenizer 后严格对齐到 2500×4 段边界 | 命令行已通过 `--calibration_dataset calib_dummy.jsonl` 指定且可被加载 | | 25 | +| 输入 | 校准输入 | 算法在运行时自行构造的受控输入 | 首 token + 2500 个随机 token × 4 段重复，总长 `1 + 2500 × 4` | 无需用户指定；不受 `--calibration_dataset` 影响 | |
| 26 | | 输入 | 量化配置文件 | 本地 YAML 文件 | 符合 `modelslim_v1` 协议规范 | 通过模式校验（Schema Validation） | | 26 | | 输入 | 量化配置文件 | 本地 YAML 文件 | 符合 `modelslim_v1` 协议规范 | 通过模式校验（Schema Validation） | |
| 27 | -| 交付件 | `head.pt` | `--save_path` 指定路径 | dict 序列化 `.pt` 文件，含 `prefix_matching` 与 `copying` 字段 | 文件存在且可被 `torch.load` 读取，可被后续 KV cache 压缩流程消费 | | 27 | +| 交付件 | `head.pt` | `--save_path` 指定路径 | dict 序列化 `.pt` 文件，含 `prefix_matching` 与 `copying` 字段 | 文件存在且可被 `torch.load` 读取，交付给 MindIE 推理框架用于长序列 KV Cache 压缩，不写入量化配置 | |
| 28 | 28 | ||
| 29 | ## 3. 流程总览 | 29 | ## 3. 流程总览 |
| 30 | 30 | ||
| @@ -32,21 +32,21 @@ RA Compress 的整体使用流程如下： | |||
| 32 | 32 | ||
| 33 | ```mermaid | 33 | ```mermaid |
| 34 | flowchart LR | 34 | flowchart LR |
| 35 | - A[适配模型<br/>流水线/算法接口] --> B[确认投影层命名<br/>与校准数据] | 35 | + A[适配模型<br/>流水线/算法接口] --> B[确认投影层命名] |
| 36 | B --> C[执行<br/>analyze attn_head 命令] | 36 | B --> C[执行<br/>analyze attn_head 命令] |
| 37 | C --> D[Q@K^T 段间偏移<br/>注意力聚合] | 37 | C --> D[Q@K^T 段间偏移<br/>注意力聚合] |
| 38 | - D --> E[按 ratio<br/>选 induction/echo heads] | 38 | + D --> E[按比例<br/>选 induction/echo heads] |
| 39 | - E --> F[输出 head.pt<br/>并衔接压缩流程] | 39 | + E --> F[输出 head.pt<br/>交付 MindIE 推理框架使用] |
| 40 | ``` | 40 | ``` |
| 41 | 41 | ||
| 42 | 各阶段的关键细节如下： | 42 | 各阶段的关键细节如下： |
| 43 | 43 | ||
| 44 | -- **适配模型流水线/算法接口**：适配器需实现 `PipelineInterface` 基础流水线接口；当 Q/K 投影层命名与默认模式不匹配时，需实现 `RaCompressAnalysisInterface` 提供投影层命名模式。 | 44 | +- **适配模型流水线/算法接口**：适配器需实现 `PipelineInterface` 基础流水线接口，并实现 `RaCompressAnalysisInterface`：`get_proj_names` 提供 Q/K/QKV 投影层的名称片段，`get_tokenizer` 返回模型自己的 tokenizer。 |
| 45 | -- **确认投影层命名与校准数据**：默认匹配 `q_proj`、`k_proj`、`qkv_proj`；校准数据须显式指定内置合成校准集 `calib_dummy.jsonl`，使用其他校准集不保证筛选效果。 | 45 | +- **确认投影层命名**：`get_proj_names()` 返回的模式中，空串表示该投影不存在；未接入该接口时按默认模式 `q_proj`、`k_proj`、`qkv_proj` 匹配。 |
| 46 | - **执行 analyze attn_head 命令**：以 `--metrics ra_compress` 启动 KV 注意力头粒度分析。 | 46 | - **执行 analyze attn_head 命令**：以 `--metrics ra_compress` 启动 KV 注意力头粒度分析。 |
| 47 | - **Q@K^T 段间偏移注意力聚合**：在段边界处计算偏移注意力，度量各 KV head 的跨段信息传递能力。 | 47 | - **Q@K^T 段间偏移注意力聚合**：在段边界处计算偏移注意力，度量各 KV head 的跨段信息传递能力。 |
| 48 | -- **按 ratio 选 induction/echo heads**：归纳头（prefix matching）与回声头（copying matching）按比例形成入选索引。 | 48 | +- **按比例选 induction/echo heads**：归纳头（prefix matching）与回声头（copying matching）按比例（`induction_head_ratio` 默认 0.14、`echo_head_ratio` 默认 0.01）形成入选索引。 |
| 49 | -- **输出 head.pt 并衔接压缩流程**：`head.pt` 送入 RA Compress KV cache 压缩量化流程，生成压缩后的模型。 | 49 | +- **输出 head.pt 并交付 MindIE 推理框架**：`head.pt` 交付给 MindIE 推理框架，在 MindIE 中把该文件路径配置到长序列 KV Cache 压缩相关参数中，由 MindIE 在长序列推理时按该关键头清单执行 KV Cache 压缩；用户可据此完成长序列压缩，压缩后的模型可用于后续推理部署；该产物不写入量化配置。 |
| 50 | 50 | ||
| 51 | ## 4. 操作步骤 | 51 | ## 4. 操作步骤 |
| 52 | 52 | ||
| @@ -57,38 +57,49 @@ flowchart LR | |||
| 57 | **操作**：模型适配代码需实现以下接口，相关接口均由 `msmodelslim.model.interface_hub` 汇总导出： | 57 | **操作**：模型适配代码需实现以下接口，相关接口均由 `msmodelslim.model.interface_hub` 汇总导出： |
| 58 | 58 | ||
| 59 | 1. **`PipelineInterface`**（`ModelSlimPipelineInterfaceV1`）：基础流水线接口，负责模型加载（`init_model`）、数据预处理（`handle_dataset`）、逐层遍历（`generate_model_visit`）、逐层前向（`generate_model_forward`）等。 | 59 | 1. **`PipelineInterface`**（`ModelSlimPipelineInterfaceV1`）：基础流水线接口，负责模型加载（`init_model`）、数据预处理（`handle_dataset`）、逐层遍历（`generate_model_visit`）、逐层前向（`generate_model_forward`）等。 |
| 60 | -2. **`RaCompressAnalysisInterface`**（位于 `msmodelslim.processor.analysis.unary_operator.metrics.ra_compress.interface`）：RA Compress 分析专用接口（按需实现）。 | 60 | +2. **`RaCompressAnalysisInterface`**（位于 `msmodelslim.processor.analysis.unary_operator.metrics.ra_compress.interface`）：RA Compress 分析接口，`get_proj_names` 与 `get_tokenizer` 两个方法均为必需实现。 |
| 61 | 61 | ||
| 62 | ```python | 62 | ```python |
| 63 | from abc import ABC, abstractmethod | 63 | from abc import ABC, abstractmethod |
| 64 | -from typing import Dict | 64 | +from typing import Any, Dict |
| 65 | 65 | ||
| 66 | class RaCompressAnalysisInterface(ABC): | 66 | class RaCompressAnalysisInterface(ABC): |
| 67 | @abstractmethod | 67 | @abstractmethod |
| 68 | - def get_ra_compress_proj_patterns(self) -> Dict[str, str]: | 68 | + def get_proj_names(self) -> Dict[str, str]: |
| 69 | - """返回 Q/K/QKV 投影层名称模式字典。""" | 69 | + """返回 Q/K/QKV 投影层的名称片段。""" |
| 70 | + ... | ||
| 71 | + | ||
| 72 | + @abstractmethod | ||
| 73 | + def get_tokenizer(self) -> Any: | ||
| 74 | + """返回模型实际使用的 tokenizer。""" | ||
| 70 | ... | 75 | ... |
| 71 | ``` | 76 | ``` |
| 72 | 77 | ||
| 73 | -- **`get_ra_compress_proj_patterns`**：返回 `{"q": "...", "k": "...", "qkv": "..."}` 字典，描述 Q 投影层、K 投影层与 QKV 融合投影层的名称模式；未使用的模式可以留空字符串（如无 QKV 融合时 `qkv=""`）。 | 78 | +- **`get_proj_names`**：返回 `{"q": "...", "k": "...", "qkv": "..."}` 字典，描述 Q 投影层、K 投影层与 QKV 融合投影层的名称片段；分析方法按子串匹配模型中的 `nn.Linear` 层名，给名字里的一段即可，不用给完整层名。空字符串表示该投影不存在（不会被当作“匹配全部 Linear”），如无 QKV 融合时 `qkv=""`。 |
| 79 | +- **`get_tokenizer`**：返回模型实际使用的 tokenizer，通常是 `AutoTokenizer.from_pretrained(model_path)`；分析方法用它取校准输入中“重复段”的首 token，返回 `None` 或抛异常时指标侧回落到兜底取值并告警，分析不中断。 | ||
| 74 | - 模型 Q/K 投影层命名为 `q_proj` / `k_proj` / `qkv_proj` 时可省略该接口，工具按默认模式匹配。 | 80 | - 模型 Q/K 投影层命名为 `q_proj` / `k_proj` / `qkv_proj` 时可省略该接口，工具按默认模式匹配。 |
| 75 | 81 | ||
| 76 | 对于基于 HuggingFace Transformers 实现的标准开源 LLM，建议通过组合继承快速构建适配器： | 82 | 对于基于 HuggingFace Transformers 实现的标准开源 LLM，建议通过组合继承快速构建适配器： |
| 77 | 83 | ||
| 78 | ```python | 84 | ```python |
| 85 | +from transformers import AutoTokenizer | ||
| 79 | from msmodelslim.model.interface_hub import ( | 86 | from msmodelslim.model.interface_hub import ( |
| 80 | IModel, | 87 | IModel, |
| 81 | ModelInfoInterface, | 88 | ModelInfoInterface, |
| 82 | ModelSlimPipelineInterfaceV1 as PipelineInterface, | 89 | ModelSlimPipelineInterfaceV1 as PipelineInterface, |
| 83 | # ---- RA Compress 算法适配接口（本步骤重点）---- | 90 | # ---- RA Compress 算法适配接口（本步骤重点）---- |
| 84 | - RACompressAnalysisInterface, # 算法适配：get_ra_compress_proj_patterns 返回模型 Q/K/QKV 投影层名称模式 | 91 | + RaCompressAnalysisInterface, # 算法适配：提供 Q/K/QKV 投影层名称片段与模型 tokenizer |
| 85 | ) | 92 | ) |
| 86 | 93 | ||
| 87 | class MyModelAdapter(TransformersModel, ModelInfoInterface, PipelineInterface, | 94 | class MyModelAdapter(TransformersModel, ModelInfoInterface, PipelineInterface, |
| 88 | - RACompressAnalysisInterface): | 95 | + RaCompressAnalysisInterface): |
| 89 | - def get_ra_compress_proj_patterns(self): | 96 | + def get_proj_names(self): |
| 90 | - # 返回模型实际的 Q/K/QKV 投影层名称模式 | 97 | + # 返回模型实际的 Q/K/QKV 投影层名称片段 |
| 91 | return {"q": "q_proj", "k": "k_proj", "qkv": "qkv_proj"} | 98 | return {"q": "q_proj", "k": "k_proj", "qkv": "qkv_proj"} |
| 99 | + | ||
| 100 | + def get_tokenizer(self): | ||
| 101 | + # 返回模型实际使用的 tokenizer，通常与加载模型时使用的一致 | ||
| 102 | + return AutoTokenizer.from_pretrained(model_path) | ||
| 92 | ``` | 103 | ``` |
| 93 | 104 | ||
| 94 | 之后分析命令中通过 `--model_type MyModelAdapter` 引用该适配器。 | 105 | 之后分析命令中通过 `--model_type MyModelAdapter` 引用该适配器。 |
| @@ -104,9 +115,9 @@ class MyModelAdapter(TransformersModel, ModelInfoInterface, PipelineInterface, | |||
| 104 | 下面参数用于建立**第一版可比较基线**。 | 115 | 下面参数用于建立**第一版可比较基线**。 |
| 105 | 116 | ||
| 106 | - `--metrics`：`ra_compress`； | 117 | - `--metrics`：`ra_compress`； |
| 107 | -- `--calibration_dataset`：**必须**显式指定为内置合成校准集 `calib_dummy.jsonl`（`attn_head` 子命令不再为此场景设置默认值），使用其他校准集不保证筛选效果； | 118 | +- 校准输入：无需指定 `--calibration_dataset`，`ra_compress` 的校准输入由算法在运行时自行构造； |
| 108 | -- top heads 选取比例（ratio）：使用实现内部默认值（induction head `0.14`、echo head `0.01`），CLI 不提供 `--ratio` 参数； | 119 | +- top heads 选取比例（ratio）：使用实现内部默认值（induction head `0.14`、echo head `0.01`），CLI 不提供相关参数，保持默认即可；确需调整时，请参见《[unary_analysis 配置说明](../../../api_reference/config/processor/unary_analysis.md)》； |
| 109 | -- `--save_path`：指定 `head.pt` 与结果文件保存目录。 | 120 | +- `--save_path`：指定 `head.pt` 保存目录。 |
| 110 | 121 | ||
| 111 | **输出**：一组可复现的注意力头分析基线参数，用于生成第一版 induction/echo heads 排序。 | 122 | **输出**：一组可复现的注意力头分析基线参数，用于生成第一版 induction/echo heads 排序。 |
| 112 | 123 | ||
| @@ -114,16 +125,17 @@ class MyModelAdapter(TransformersModel, ModelInfoInterface, PipelineInterface, | |||
| 114 | 125 | ||
| 115 | **操作**： | 126 | **操作**： |
| 116 | 127 | ||
| 117 | -每轮只调一个变量，并保持同一校准数据与模型版本。 | 128 | +每轮只调一个变量，并保持同一模型版本。 |
| 118 | 129 | ||
| 119 | | 配置项 | 含义（原理） | 推荐配置 | 选择与调整建议 | | 130 | | 配置项 | 含义（原理） | 推荐配置 | 选择与调整建议 | |
| 120 | | --- | --- | --- | --- | | 131 | | --- | --- | --- | --- | |
| 121 | | `attn_head` | KV 注意力头粒度分析子命令。 | 固定。 | 不调。 | | 132 | | `attn_head` | KV 注意力头粒度分析子命令。 | 固定。 | 不调。 | |
| 122 | | `--metrics` | 指定分析算法，取值为 `ra_compress` 时使用本算法。 | 固定 `ra_compress`。 | 不调。 | | 133 | | `--metrics` | 指定分析算法，取值为 `ra_compress` 时使用本算法。 | 固定 `ra_compress`。 | 不调。 | |
| 123 | -| `--calibration_dataset` | 用于段边界对齐的校准数据；本算法须使用内置合成校准集。 | **必须** `calib_dummy.jsonl`。 | 不建议更换；使用其他校准集不保证筛选效果。 | | 134 | +| `--save_path` | `head.pt` 保存目录。 | 按需指定。 | 保证目录存在且有写权限。 | |
| 124 | -| `--save_path` | `head.pt` 与结果文件保存目录。 | 按需指定。 | 保证目录存在且有写权限。 | | ||
| 125 | | `--trust_remote_code` | 是否信任模型远程代码。 | 模型含自定义代码时设 `true`。 | 按模型要求设置。 | | 135 | | `--trust_remote_code` | 是否信任模型远程代码。 | 模型含自定义代码时设 `true`。 | 按模型要求设置。 | |
| 126 | 136 | ||
| 137 | +> 上表只列出本指南涉及的 CLI 参数。归纳头 / 回声头的入选比例（`induction_head_ratio`、`echo_head_ratio`）不是 CLI 参数，命令行流程按实现内部默认值执行；该比例对应的配置项为配置侧 `unary_analysis` 处理器的 `metric_params` 字段，字段含义、默认值与调整方法见《[unary_analysis 配置说明](../../../api_reference/config/processor/unary_analysis.md)》。 | ||
| 138 | + | ||
| 127 | **输出**：一份参数含义和调整方向明确的分析配置。 | 139 | **输出**：一份参数含义和调整方向明确的分析配置。 |
| 128 | 140 | ||
| 129 | ### 步骤 4：编写量化配置并执行命令 | 141 | ### 步骤 4：编写量化配置并执行命令 |
| @@ -139,7 +151,6 @@ msmodelslim analyze attn_head \ | |||
| 139 | --model_path <浮点模型目录> \ | 151 | --model_path <浮点模型目录> \ |
| 140 | --model_type <模型适配器名称> \ | 152 | --model_type <模型适配器名称> \ |
| 141 | --metrics ra_compress \ | 153 | --metrics ra_compress \ |
| 142 | - --calibration_dataset calib_dummy.jsonl \ | ||
| 143 | --trust_remote_code true \ | 154 | --trust_remote_code true \ |
| 144 | --save_path ./head_result \ | 155 | --save_path ./head_result \ |
| 145 | --device npu \ | 156 | --device npu \ |
| @@ -152,25 +163,25 @@ msmodelslim analyze attn_head \ | |||
| 152 | | --- | --- | | 163 | | --- | --- | |
| 153 | | `attn_head` | KV 注意力头粒度分析 | | 164 | | `attn_head` | KV 注意力头粒度分析 | |
| 154 | | `--metrics` | 指定分析算法，取值为 `ra_compress` 时使用本算法 | | 165 | | `--metrics` | 指定分析算法，取值为 `ra_compress` 时使用本算法 | |
| 155 | -| `--calibration_dataset` | **必须**显式指定为 `calib_dummy.jsonl`；使用其他校准集不保证筛选效果 | | 166 | +| `--device` | 分析设备，取值 `npu`、`cpu` | |
| 156 | -| `--save_path` | `head.pt` 与结果文件保存目录 | | 167 | +| `--device_id` | 卡号，如 `0`；多卡传入多个卡号（如 `0 1 2 3`）时启用多卡分析 | |
| 168 | +| `--save_path` | `head.pt` 保存目录 | | ||
| 157 | 169 | ||
| 158 | -**输出**：命令行打印入选的 induction heads / echo heads 列表；`--save_path` 目录下生成 `head.pt`（含 `prefix_matching` 与 `copying` 字段），供后续 RA Compress KV cache 压缩量化流程使用。 | 170 | +> 无需指定 `--calibration_dataset`：`ra_compress` 的校准输入（首 token + 随机重复段）由算法在运行时自行构造，该参数不参与计算。 |
| 171 | + | ||
| 172 | +**输出**：命令行打印入选的 induction heads / echo heads 列表；`--save_path` 目录下生成 `head.pt`（含 `prefix_matching` 与 `copying` 字段），交付给 MindIE 推理框架用于长序列 KV Cache 压缩，不写入量化配置。 | ||
| 173 | + | ||
| 174 | +将 `head.pt` 结构确认为 `{"prefix_matching": {layer_idx: [kv_head_idx, ...]}, "copying": {layer_idx: [kv_head_idx, ...]}}`，并在 MindIE 中把该文件路径配置到长序列 KV Cache 压缩相关参数中，即可用压缩配置完成长序列推理部署；具体已适配的量化模型列表，请参见《[MindIE 是什么](https://www.hiascend.com/document/detail/zh/mindie/10RC3/whatismindie/mindie_what_0001.html)》的“MindIE 支持模型列表”章节。 | ||
| 159 | 175 | ||
| 160 | ## 5. 术语 | 176 | ## 5. 术语 |
| 161 | 177 | ||
| 162 | | 术语 | 简述 | 链接 | | 178 | | 术语 | 简述 | 链接 | |
| 163 | | --- | --- | --- | | 179 | | --- | --- | --- | |
| 164 | | RA Compress 注意力头分析算法 | 说明该算法的定义、核心原理、关键性质、适用场景与限制。 | [《RA Compress 量化术语百科词条》](./term_ra_compress.md) | | 180 | | RA Compress 注意力头分析算法 | 说明该算法的定义、核心原理、关键性质、适用场景与限制。 | [《RA Compress 量化术语百科词条》](./term_ra_compress.md) | |
| 165 | -| Induction Head | 归纳头，在段边界处体现 prefix matching 行为的关键 KV head。 | [《RA Compress 量化术语百科词条》](./term_ra_compress.md) | | ||
| 166 | -| Echo Head | 回声头，在段边界处体现 copying matching 行为的关键 KV head。 | [《RA Compress 量化术语百科词条》](./term_ra_compress.md) | | ||
| 167 | 181 | ||
| 168 | ## 6. 相关文档 | 182 | ## 6. 相关文档 |
| 169 | 183 | ||
| 170 | | 接口或文档 | 简述 | 链接 | | 184 | | 接口或文档 | 简述 | 链接 | |
| 171 | | --- | --- | --- | | 185 | | --- | --- | --- | |
| 172 | -| `PipelineInterface` | 模型流水线适配接口（数据预处理、模型加载、模块遍历）。 | [《LLM 量化使用指南·步骤 1》](../../ptq/llm/usage_large_language_model_quantization.md) | | 186 | +| `RaCompressAnalysisInterface` | RA Compress 分析模型适配接口（需实现 `get_proj_names` 与 `get_tokenizer`），由 `msmodelslim.model.interface_hub` 汇总导出。 | [接口汇总模块](../../../../../msmodelslim/model/interface_hub.py) | |
| 173 | -| `RaCompressAnalysisInterface` | RA Compress 分析模型适配接口，由 `msmodelslim.model.interface_hub` 汇总导出。 | [接口汇总模块](../../../../../msmodelslim/model/interface_hub.py) | | ||
| 174 | | unary_analysis 配置说明 | 字段类型、默认值、合法取值与完整配置约束。 | [《unary_analysis 配置说明》](../../../api_reference/config/processor/unary_analysis.md) | | 187 | | unary_analysis 配置说明 | 字段类型、默认值、合法取值与完整配置约束。 | [《unary_analysis 配置说明》](../../../api_reference/config/processor/unary_analysis.md) | |
| 175 | -| modelslim_v1 配置说明 | 需要继续探索 runner、prior、save、dataset 等任务级高级配置时查阅。 | [《modelslim_v1 配置说明》](../../../api_reference/config/task/modelslim_v1.md) | | ||
| 176 | -| 权重量化使用指南 | 用户指南：量化命令参数与完整使用说明。 | [《权重量化使用指南》](https://gitcode.com/Ascend/msmodelslim/blob/master/docs/zh/user_guide/usage_weight_quantization.md) | | ||
| @@ -2,13 +2,15 @@ | |||
| 2 | 2 | ||
| 3 | ## 1. 适用范围 | 3 | ## 1. 适用范围 |
| 4 | 4 | ||
| 5 | -本指南面向需要通过 `msmodelslim analyze attn_head` 命令行，按 **Attention Head** 粒度识别关键注意力头（induction heads 与 echo heads），并据此生成 `head.pt` 文件用于 RA Compress 压缩的开发者与算法工程师。 | 5 | +本指南面向需要通过 `msmodelslim analyze attn_head` 命令行，按 **Attention Head** 粒度识别关键注意力头（induction heads 与 echo heads），并据此生成 `head.pt` 文件交付给后续 MindIE 推理框架（用于长序列 KV Cache 压缩）的开发者与算法工程师。 |
| 6 | 6 | ||
| 7 | **适用场景**： | 7 | **适用场景**： |
| 8 | 8 | ||
| 9 | - **LLM 模型**：当前 `attn_head` 分析仅支持大语言模型。 | 9 | - **LLM 模型**：当前 `attn_head` 分析仅支持大语言模型。 |
| 10 | -- RA Compress 压缩方案设计：识别具有 prefix matching（归纳头）和 copying matching（回声头）能力的 KV Cache 头，用于后续 KV Cache 压缩配置。 | 10 | +- RA Compress 压缩方案设计：识别具有 prefix matching（归纳头）和 copying matching（回声头）能力的 KV Cache 头，形成 MindIE 长序列 KV Cache 压缩需要保留的关键头清单。 |
| 11 | -- 精度不达标时，结合 head 筛选结果迭代 RA Compress 相关配置。 | 11 | +- 精度不达标时，调整 `induction_head_ratio` / `echo_head_ratio` 重新筛选 head 清单，或调整 MindIE 的 KV Cache 压缩策略。 |
| 12 | + | ||
| 13 | +> **产物用途**：本指南产出的 `head.pt` 是交付给**MindIE 推理框架**使用的关键头清单：在 MindIE 中把该文件路径配置到长序列 KV Cache 压缩相关参数中，即可完成长序列压缩，压缩后的模型可用于后续推理部署；具体已适配的量化模型列表，请参见《[MindIE 是什么](https://www.hiascend.com/document/detail/zh/mindie/10RC3/whatismindie/mindie_what_0001.html)》的“MindIE 支持模型列表”章节。该产物不写入量化配置（不参与量化 YAML 的 `exclude` / `include` 等字段）。 | ||
| 12 | 14 | ||
| 13 | **不适用场景**： | 15 | **不适用场景**： |
| 14 | 16 | ||
| @@ -27,27 +29,27 @@ | |||
| 27 | - 已安装 msModelSlim（详见《[安装指南](../install_guide/install_guide.md)》）。 | 29 | - 已安装 msModelSlim（详见《[安装指南](../install_guide/install_guide.md)》）。 |
| 28 | - 目标模型为 LLM，且已确定可用的 `--model_type`（与支持矩阵或适配器注册名一致，大小写敏感；通常已在上级流程或权重量化流程中完成适配）。 | 30 | - 目标模型为 LLM，且已确定可用的 `--model_type`（与支持矩阵或适配器注册名一致，大小写敏感；通常已在上级流程或权重量化流程中完成适配）。 |
| 29 | - 已具备可用的昇腾 NPU（单卡 `--device npu`，或多卡 `--device npu --device_id 0 1 ...`；仅做小规模调试时使用 `--device cpu`）。 | 31 | - 已具备可用的昇腾 NPU（单卡 `--device npu`，或多卡 `--device npu --device_id 0 1 ...`；仅做小规模调试时使用 `--device cpu`）。 |
| 30 | -- 目标适配器已实现 `RaCompressAnalysisInterface` 接口（提供 Q、K、QKV 投影层名称模式），或使用默认模式（`q_proj`、`k_proj`、`qkv_proj`）。 | 32 | +- 目标适配器已实现 `RaCompressAnalysisInterface`（`get_proj_names` 提供 Q、K、QKV 投影层名称片段，`get_tokenizer` 返回模型自身的 tokenizer，二者均为必需方法），或使用默认模式（`q_proj`、`k_proj`、`qkv_proj`）与兜底首 token。 |
| 31 | 33 | ||
| 32 | **后续操作**： | 34 | **后续操作**： |
| 33 | 35 | ||
| 34 | -- 将生成的 `head.pt` 文件提供给 RA Compress 量化流程，或在量化配置中引用 head 筛选结果。 | 36 | +- 将生成的 `head.pt` 文件提供给 MindIE 推理框架使用（在 MindIE 中把该文件路径配置到长序列 KV Cache 压缩相关参数中），用户可据此完成长序列压缩，压缩后的模型可用于后续推理部署；具体已适配的量化模型列表，请参见《[MindIE 是什么](https://www.hiascend.com/document/detail/zh/mindie/10RC3/whatismindie/mindie_what_0001.html)》的“MindIE 支持模型列表”章节。该产物不写入量化配置。 |
| 35 | 37 | ||
| 36 | ## 3. 输入和交付件 | 38 | ## 3. 输入和交付件 |
| 37 | 39 | ||
| 38 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | | 40 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | |
| 39 | | --- | --- | --- | --- | --- | | 41 | | --- | --- | --- | --- | --- | |
| 40 | | 输入 | 浮点模型目录 | 用户本地路径；一般自 ModelScope / Hugging Face 获取 | 含模型配置、权重分片及 tokenizer 等 | 路径有效，可被目标 `model_type` 加载 | | 42 | | 输入 | 浮点模型目录 | 用户本地路径；一般自 ModelScope / Hugging Face 获取 | 含模型配置、权重分片及 tokenizer 等 | 路径有效，可被目标 `model_type` 加载 | |
| 41 | -| 输入 | 校准集 | 工具内置 [`calib_dummy.jsonl`](../../../lab_calib/) 短名称或用户本地路径 | `.json` / `.jsonl`；tokenize 后总长度须 ≥ 10000（2500 × 4 段重复） | 可被 `msmodelslim analyze` 解析且 token 长度满足要求 | | 43 | +| 输入 | 校准输入（算法内建） | 由算法在运行时自行构造的受控输入，无需用户提供 | 首 token + 2500 个随机 token × 4 段重复，总长 `1 + 2500 × 4` | 无需校验；不受 `--calibration_dataset` 影响 | |
| 42 | -| 交付件 | head 筛选结果 | 标准输出（induction 与 echo head 列表）及可选 `head.pt` 文件 | `head.pt` 为 Python dict 序列化的 `.pt` 文件 | 能识别预期 layer 与 head 范围，`head.pt` 可被后续量化流程加载 | | 44 | +| 交付件 | head 筛选结果 | 标准输出（induction 与 echo head 列表）及可选 `head.pt` 文件 | `head.pt` 为 Python dict 序列化的 `.pt` 文件，交付给 MindIE 推理框架用于长序列 KV Cache 压缩 | 能识别预期 layer 与 head 范围，`head.pt` 可被 MindIE 的长序列 KV Cache 压缩能力加载 | |
| 43 | 45 | ||
| 44 | ## 4. 流程总览 | 46 | ## 4. 流程总览 |
| 45 | 47 | ||
| 46 | -确认 `attn_head` 场景与 `ra_compress` 指标后，准备浮点权重与专用校准集，按需完成模型适配（含 RA Compress 接口），再执行分析命令并解读结果，用于生成 `head.pt` 或调整压缩配置。 | 48 | +确认 `attn_head` 场景与 `ra_compress` 指标后，准备浮点权重，按需完成模型适配（含 RA Compress 接口），再执行分析命令并解读结果，生成交付给 MindIE 推理框架使用的 `head.pt` 关键头清单。校准输入（首 token + 随机重复段）由算法在运行时自动构造，无需另行准备校准集。 |
| 47 | 49 | ||
| 48 | ```mermaid | 50 | ```mermaid |
| 49 | flowchart LR | 51 | flowchart LR |
| 50 | - scene[确认指标] --> prepare[获取浮点权重与校准集] | 52 | + scene[确认指标] --> prepare[获取浮点权重] |
| 51 | prepare --> adapt[完成模型适配] | 53 | prepare --> adapt[完成模型适配] |
| 52 | prepare -->|已接入且接口齐全可跳过| run[执行分析命令] | 54 | prepare -->|已接入且接口齐全可跳过| run[执行分析命令] |
| 53 | adapt --> run | 55 | adapt --> run |
| @@ -62,8 +64,7 @@ flowchart LR | |||
| 62 | msmodelslim analyze attn_head \ | 64 | msmodelslim analyze attn_head \ |
| 63 | --model_type ${MODEL_TYPE} \ # 已注册或支持矩阵中的模型名，大小写敏感 | 65 | --model_type ${MODEL_TYPE} \ # 已注册或支持矩阵中的模型名，大小写敏感 |
| 64 | --model_path ${MODEL_PATH} \ # 浮点权重目录 | 66 | --model_path ${MODEL_PATH} \ # 浮点权重目录 |
| 65 | - --metrics ra_compress \ # 分析指标，固定为 ra_compress | 67 | + --metrics ${METRICS} \ # 分析指标，固定为 ra_compress |
| 66 | - --calibration_dataset calib_dummy.jsonl \ # 须显式指定为 calib_dummy.jsonl（合成重复段校准集，tokenize 后总长度 ≥ 10000） | ||
| 67 | --device npu \ # 分析设备：npu、cpu；多卡另加 --device_id 0 1 2 3 | 68 | --device npu \ # 分析设备：npu、cpu；多卡另加 --device_id 0 1 2 3 |
| 68 | --trust_remote_code false \ # 默认 false；仅可信模型必要时设为 true | 69 | --trust_remote_code false \ # 默认 false；仅可信模型必要时设为 true |
| 69 | --save_path ${SAVE_PATH} # 可选；指定则保存 head.pt，不指定仅打印到控制台 | 70 | --save_path ${SAVE_PATH} # 可选；指定则保存 head.pt，不指定仅打印到控制台 |
| @@ -79,39 +80,40 @@ msmodelslim analyze attn_head \ | |||
| 79 | 80 | ||
| 80 | | 可选指标 | 适用说明 | 算法说明 | 推荐 | | 81 | | 可选指标 | 适用说明 | 算法说明 | 推荐 | |
| 81 | | --- | --- | --- | --- | | 82 | | --- | --- | --- | --- | |
| 82 | -| `ra_compress` | 识别具有 prefix matching 和 copying matching 能力的注意力头，用于 KV Cache 压缩 | RA Compress 算法：对 Q@K^T 注意力分数在特定段偏移位置取均值，按 ratio 选 top heads | 当前唯一可选指标，直接选用 | | 83 | +| `ra_compress` | 识别具有 prefix matching 和 copying matching 能力的注意力头，用于 KV Cache 压缩 | RA Compress 算法：对 Q@K^T 注意力分数在特定段偏移位置取均值，按比例选 top heads（`induction_head_ratio` 默认 0.14、`echo_head_ratio` 默认 0.01，可在 `unary_analysis` 配置的 `metric_params` 中调整） | 当前唯一可选指标，直接选用 | |
| 83 | 84 | ||
| 84 | **输出**：已选定的 `${METRICS}`。 | 85 | **输出**：已选定的 `${METRICS}`。 |
| 85 | 86 | ||
| 86 | **通过条件**：`${METRICS}` 属于上表可选值。 | 87 | **通过条件**：`${METRICS}` 属于上表可选值。 |
| 87 | 88 | ||
| 88 | -### 步骤 2：获取浮点权重与校准数据 | 89 | +### 步骤 2：获取浮点权重 |
| 89 | 90 | ||
| 90 | -**目标**：准备可加载的浮点模型目录与满足 token 长度要求的校准集。 | 91 | +**目标**：准备可加载的浮点模型目录。 |
| 91 | 92 | ||
| 92 | **操作**： | 93 | **操作**： |
| 93 | 94 | ||
| 94 | 1. 从 [ModelScope](https://www.modelscope.cn/)、[Hugging Face](https://huggingface.co/) 或团队内部模型存放位置获取完整权重到本地目录；具体下载方式以对应社区或仓库文档为准。 | 95 | 1. 从 [ModelScope](https://www.modelscope.cn/)、[Hugging Face](https://huggingface.co/) 或团队内部模型存放位置获取完整权重到本地目录；具体下载方式以对应社区或仓库文档为准。 |
| 95 | 2. 核对目录含配置、权重分片及 tokenizer 等附属文件。若官方页面提供文件校验值（如 MD5/SHA256）或明确的版本号/提交号，与本地下载结果比对一致即可。 | 96 | 2. 核对目录含配置、权重分片及 tokenizer 等附属文件。若官方页面提供文件校验值（如 MD5/SHA256）或明确的版本号/提交号，与本地下载结果比对一致即可。 |
| 96 | -3. 准备校准集：`ra_compress` 算法要求校准数据 tokenize 后总长度 ≥ **10000 tokens**（即 `DUMMY_INPUT_LENGTH=2500` × `REPET_TIMES=4` 段重复）。工具内置 [`calib_dummy.jsonl`](../../../lab_calib/) 已满足此要求，`attn_head` 子命令须在命令行显式指定 `--calibration_dataset calib_dummy.jsonl`（该子命令不再为此场景设置默认值）。也可使用自有校准集，但须确保 tokenize 后的 token 总数 ≥ 10000，否则分析将跳过分数计算并返回空结果。 | ||
| 97 | 97 | ||
| 98 | -**输出**：浮点模型目录与校准集路径（或工具内置校准集短名称）。 | 98 | +> `ra_compress` 不需要用户提供校准集：校准输入是算法内建的受控输入，由算法在运行时自动构造（首 token + 2500 个随机 token × 4 段重复，总长 `1 + 2500 × 4`）。命令行的 `--calibration_dataset` 对该场景不参与计算；模型目录中的 tokenizer 会被用于解析首 token，若缺失则回落到兜底 token id 并告警。 |
| 99 | 99 | ||
| 100 | -**通过条件**：模型目录可加载；校准集 tokenize 后 token 总数 ≥ 10000。 | 100 | +**输出**：可加载的浮点模型目录。 |
| 101 | + | ||
| 102 | +**通过条件**：模型目录可加载，且含 tokenizer 等附属文件。 | ||
| 101 | 103 | ||
| 102 | ### 步骤 3：完成模型适配 | 104 | ### 步骤 3：完成模型适配 |
| 103 | 105 | ||
| 104 | -**目标**：确保存在可被 `msmodelslim analyze --model_type <模型名>` 命中的模型适配器；适配器已实现 `RaCompressAnalysisInterface` 接口或使用默认投影层名称模式。 | 106 | +**目标**：确保存在可被 `msmodelslim analyze --model_type <模型名>` 命中的模型适配器；适配器已实现 `RaCompressAnalysisInterface` 接口的必需方法或使用默认投影层名称模式。 |
| 105 | 107 | ||
| 106 | **操作**： | 108 | **操作**： |
| 107 | 109 | ||
| 108 | - **尚未接入的模型**：须先完成适配器开发与注册，再进入步骤 4。通用适配要求见《[LLM 大模型接入指南](../knowledge_base/ptq/llm/integration_guide_large_language_model_quantization.md)》。 | 110 | - **尚未接入的模型**：须先完成适配器开发与注册，再进入步骤 4。通用适配要求见《[LLM 大模型接入指南](../knowledge_base/ptq/llm/integration_guide_large_language_model_quantization.md)》。 |
| 109 | - **支持矩阵中已接入的模型**：可跳过通用适配，确认所用 `--model_type` 名称即可。 | 111 | - **支持矩阵中已接入的模型**：可跳过通用适配，确认所用 `--model_type` 名称即可。 |
| 110 | -- **算法侧额外接口**：`ra_compress` 要求适配器实现 `RaCompressAnalysisInterface` 接口，提供 Q、K、QKV 投影层名称模式。若适配器未实现该接口，将使用默认模式（`q_proj`、`k_proj`、`qkv_proj`）。若模型投影层命名与默认模式不同，须按接口文档补齐。接口定义见 [ra_compress/interface.py](../../../msmodelslim/processor/analysis/unary_operator/metrics/ra_compress/interface.py)。 | 112 | +- **算法侧额外接口**：`RaCompressAnalysisInterface` 以类型判定接入——适配器实现该接口才会被指标侧识别。其中 `get_proj_names()` 返回 Q、K、QKV 三路投影层名称片段（如 `q_proj`、`k_proj`、`qkv_proj`）；空串表示该投影不存在，不会被当作"匹配全部 Linear"。`get_tokenizer()` 返回模型实际使用的 tokenizer（通常是 `AutoTokenizer.from_pretrained(model_path)`）。二者均为必需方法，缺一个适配器无法实例化；未提供 tokenizer（返回 `None` 或抛异常）时，指标侧按内置兜底路径取校准输入首 token 并告警。若适配器未实现该接口，则使用默认模式（`q_proj`、`k_proj`、`qkv_proj`）。接口定义见 [ra_compress/interface.py](../../../msmodelslim/processor/analysis/unary_operator/metrics/ra_compress/interface.py)。 |
| 111 | 113 | ||
| 112 | 完成或修改适配器后，在仓库根目录重新执行 `bash install.sh`，使注册生效。 | 114 | 完成或修改适配器后，在仓库根目录重新执行 `bash install.sh`，使注册生效。 |
| 113 | 115 | ||
| 114 | -**输出**：已注册且可被 CLI 命中的模型适配器（对应 `--model_type`）；适配器已具备 `RaCompressAnalysisInterface` 能力或使用默认模式可正确匹配投影层。 | 116 | +**输出**：已注册且可被 CLI 命中的模型适配器（对应 `--model_type`）；适配器已具备 `RaCompressAnalysisInterface` 能力（实现 `get_proj_names` 与 `get_tokenizer`）或使用默认模式可正确匹配投影层。 |
| 115 | 117 | ||
| 116 | **通过条件**：使用该 `model_type` 启动分析时能正确命中适配器；能正确识别 Q、K、QKV 投影层并采集输出。 | 118 | **通过条件**：使用该 `model_type` 启动分析时能正确命中适配器；能正确识别 Q、K、QKV 投影层并采集输出。 |
| 117 | 119 | ||
| @@ -122,7 +124,7 @@ msmodelslim analyze attn_head \ | |||
| 122 | 124 | ||
| 123 | - 已完成步骤 1～3 的指标、权重与模型适配确认。 | 125 | - 已完成步骤 1～3 的指标、权重与模型适配确认。 |
| 124 | - `trust_remote_code` 默认 `false`；仅当模型必须执行仓库内自定义代码且来源可信时设为 `true`。 | 126 | - `trust_remote_code` 默认 `false`；仅当模型必须执行仓库内自定义代码且来源可信时设为 `true`。 |
| 125 | -- `--calibration_dataset` 须显式指定为 `calib_dummy.jsonl`（`attn_head` 子命令不再为此场景设置默认值）；如使用自定义校准集，请确认 token 长度满足要求（见步骤 2）。 | 127 | +- 无需指定 `--calibration_dataset`：`ra_compress` 的校准输入由算法在运行时自行构造（见步骤 2），该参数不参与计算。 |
| 126 | 128 | ||
| 127 | **操作**： | 129 | **操作**： |
| 128 | 130 | ||
| @@ -133,7 +135,6 @@ msmodelslim analyze attn_head \ | |||
| 133 | --model_type Qwen2.5-7B-Instruct \ | 135 | --model_type Qwen2.5-7B-Instruct \ |
| 134 | --model_path /data/models/Qwen/Qwen2.5-7B-Instruct/ \ | 136 | --model_path /data/models/Qwen/Qwen2.5-7B-Instruct/ \ |
| 135 | --metrics ra_compress \ | 137 | --metrics ra_compress \ |
| 136 | - --calibration_dataset calib_dummy.jsonl \ | ||
| 137 | --device npu \ | 138 | --device npu \ |
| 138 | --trust_remote_code true \ | 139 | --trust_remote_code true \ |
| 139 | --save_path ./head_result | 140 | --save_path ./head_result |
| @@ -143,11 +144,11 @@ msmodelslim analyze attn_head \ | |||
| 143 | 144 | ||
| 144 | **通过条件**：命令正常结束；输出含 induction heads 和 echo heads 列表；若指定 `--save_path`，`head.pt` 文件成功生成。 | 145 | **通过条件**：命令正常结束；输出含 induction heads 和 echo heads 列表；若指定 `--save_path`，`head.pt` 文件成功生成。 |
| 145 | 146 | ||
| 146 | -**审计记录**：实际命令行、`${MODEL_TYPE}`、`${METRICS}`、校准集路径、标准输出结果摘要（或保存的日志路径）、`head.pt` 文件路径（如指定）。 | 147 | +**审计记录**：实际命令行、`${MODEL_TYPE}`、`${METRICS}`、标准输出结果摘要（或保存的日志路径）、`head.pt` 文件路径（如指定）。 |
| 147 | 148 | ||
| 148 | -### 步骤 5：解读分析结果并用于配置 | 149 | +### 步骤 5：解读分析结果并交付 MindIE 推理框架 |
| 149 | 150 | ||
| 150 | -**目标**：读懂标准输出中的 induction 与 echo head 筛选结果，并将 `head.pt` 用于后续 RA Compress 量化流程。 | 151 | +**目标**：读懂标准输出中的 induction 与 echo head 筛选结果，并将 `head.pt` 交付给 MindIE 推理框架用于长序列 KV Cache 压缩：用户可据此完成长序列压缩，压缩后的模型可用于后续推理部署。 |
| 151 | 152 | ||
| 152 | **操作**： | 153 | **操作**： |
| 153 | 154 | ||
| @@ -190,17 +191,16 @@ msmodelslim analyze attn_head \ | |||
| 190 | - `prefix_matching` 的 key 为 layer 索引（int），value 为该层被选中的 KV head 索引列表。 | 191 | - `prefix_matching` 的 key 为 layer 索引（int），value 为该层被选中的 KV head 索引列表。 |
| 191 | - `copying` 的 key 为 layer 索引（int），value 为该层被选中的 KV head 索引列表。 | 192 | - `copying` 的 key 为 layer 索引（int），value 为该层被选中的 KV head 索引列表。 |
| 192 | 193 | ||
| 193 | -4. 将 `head.pt` 文件路径提供给后续 RA Compress 量化流程，或在量化配置中引用 head 筛选结果。 | 194 | +4. 将 `head.pt` 文件交付给 MindIE 推理框架，用于长序列 KV Cache 压缩配置：在 MindIE 中把该文件路径配置到长序列 KV Cache 压缩相关参数中。用户可据此完成长序列压缩，压缩后的模型可用于后续推理部署；具体已适配的量化模型列表，请参见《[MindIE 是什么](https://www.hiascend.com/document/detail/zh/mindie/10RC3/whatismindie/mindie_what_0001.html)》的“MindIE 支持模型列表”章节。该产物不写入量化配置（不参与量化 YAML 的 `exclude` / `include` 等字段）。 |
| 194 | 195 | ||
| 195 | **输出**：`head.pt` 文件路径（如指定 `--save_path`）及控制台输出的 head 列表。 | 196 | **输出**：`head.pt` 文件路径（如指定 `--save_path`）及控制台输出的 head 列表。 |
| 196 | 197 | ||
| 197 | -**通过条件**：筛选结果中的 layer 与 head 索引在模型实际结构范围内；`head.pt` 可被后续量化流程正确加载。 | 198 | +**通过条件**：筛选结果中的 layer 与 head 索引在模型实际结构范围内；`head.pt` 可被 MindIE 的 KV Cache 压缩能力正确加载。 |
| 198 | 199 | ||
| 199 | ## 6. 验收条件 | 200 | ## 6. 验收条件 |
| 200 | 201 | ||
| 201 | - 已选用 `attn_head` scope 与 `ra_compress` 指标。 | 202 | - 已选用 `attn_head` scope 与 `ra_compress` 指标。 |
| 202 | -- 适配器已满足 `RaCompressAnalysisInterface` 接口要求或使用默认模式可正确匹配投影层。 | 203 | +- 适配器已满足 `RaCompressAnalysisInterface` 接口要求（实现 `get_proj_names` 与 `get_tokenizer`）或使用默认模式可正确匹配投影层。 |
| 203 | -- 校准集 tokenize 后 token 总数 ≥ 10000。 | ||
| 204 | - 分析命令成功产出 induction 与 echo head 列表；若指定 `--save_path`，`head.pt` 文件成功生成。 | 204 | - 分析命令成功产出 induction 与 echo head 列表；若指定 `--save_path`，`head.pt` 文件成功生成。 |
| 205 | - head 索引经人工核对在模型实际结构范围内。 | 205 | - head 索引经人工核对在模型实际结构范围内。 |
| 206 | 206 | ||
| @@ -208,12 +208,12 @@ msmodelslim analyze attn_head \ | |||
| 208 | 208 | ||
| 209 | | 现象 | 处理方向 | | 209 | | 现象 | 处理方向 | |
| 210 | | --- | --- | | 210 | | --- | --- | |
| 211 | -| 校准集 token 长度不足（< 10000） | 使用工具内置 `calib_dummy.jsonl`，或确保自定义校准集 tokenize 后总长度 ≥ 10000 后，再执行分析命令 | | 211 | +| 校准输入 tokenizer 缺失或首 token 解析失败 | 确认模型目录内 tokenizer 完整；`get_tokenizer()` 返回 `None` 或抛异常时指标侧会回落到兜底 token 并告警，正常返回模型自身的 tokenizer 即可消除告警 | |
| 212 | -| 校准集格式错误或无法读取 | 按步骤 2 核对 `.json` 或 `.jsonl` 格式、路径与权限及解析规则后，再执行分析命令 | | 212 | +| RoPE 取值不可用（维度不匹配 / 序列过短） | 该取值由指标侧内置兜底完成，会依次回落到前向 kwargs（`position_embeddings`）、注意力模块与 `rope_theta` 推导；持续告警时检查模型 `config.json` 的 `rope_theta` 与 head_dim | |
| 213 | | `model_type` 未命中或告警走默认模型 | 按步骤 3 完成模型适配与 `--model_type` 注册，重新执行 `bash install.sh` 使注册生效后，再执行分析命令 | | 213 | | `model_type` 未命中或告警走默认模型 | 按步骤 3 完成模型适配与 `--model_type` 注册，重新执行 `bash install.sh` 使注册生效后，再执行分析命令 | |
| 214 | -| 分析报缺少接口或不支持 | 按步骤 3 与接口文档补齐 `RaCompressAnalysisInterface`，或改用已支持该指标的 `model_type` 后，再执行分析命令 | | 214 | +| 分析报缺少接口或不支持 | 按步骤 3 与接口文档补齐 `RaCompressAnalysisInterface`（`get_proj_names` 与 `get_tokenizer`），或改用已支持该指标的 `model_type` 后，再执行分析命令 | |
| 215 | -| 未识别到任何 induction 或 echo heads | 检查校准集 token 长度是否满足要求，以及模型投影层命名是否与适配器配置一致；修正后重新执行分析命令 | | 215 | +| 未识别到任何 induction 或 echo heads | 检查模型投影层命名是否与 `get_proj_names()` 返回的名称片段一致；确认其返回值非空（空串表示该投影不存在，不会匹配任何层），修正后重新执行分析命令 | |
| 216 | -| 显存不足或运行失败 | 缩小校准集，或换更大显存设备后，再执行分析命令 | | 216 | +| 显存不足或运行失败 | 换更大显存设备，或减少 `--device_id` 指定的卡数后，再执行分析命令 | |
| 217 | | `head.pt` 加载失败 | 确认保存路径权限，并确认使用 `torch.load()` 加载 | | 217 | | `head.pt` 加载失败 | 确认保存路径权限，并确认使用 `torch.load()` 加载 | |
| 218 | 218 | ||
| 219 | ## 8. 术语 | 219 | ## 8. 术语 |
| @@ -222,16 +222,16 @@ msmodelslim analyze attn_head \ | |||
| 222 | | --- | --- | --- | | 222 | | --- | --- | --- | |
| 223 | | 模型适配 | 新模型接入与注册 | 《[LLM 大模型接入指南](../knowledge_base/ptq/llm/integration_guide_large_language_model_quantization.md)》 | | 223 | | 模型适配 | 新模型接入与注册 | 《[LLM 大模型接入指南](../knowledge_base/ptq/llm/integration_guide_large_language_model_quantization.md)》 | |
| 224 | | RA Compress | 基于注意力头筛选的 KV Cache 压缩算法 | 本指南 [步骤 1](#步骤-1确认推荐指标) | | 224 | | RA Compress | 基于注意力头筛选的 KV Cache 压缩算法 | 本指南 [步骤 1](#步骤-1确认推荐指标) | |
| 225 | -| Induction Head | 具有 prefix matching 能力的注意力头，擅长捕获跨段重复模式 | 本指南 [步骤 5](#步骤-5解读分析结果并用于配置) | | 225 | +| Induction Head | 具有 prefix matching 能力的注意力头，擅长捕获跨段重复模式 | 本指南 [步骤 5](#步骤-5解读分析结果并交付-mindie-推理框架) | |
| 226 | -| Echo Head | 具有 copying matching 能力的注意力头，倾向于复制前一段对应位置信息 | 本指南 [步骤 5](#步骤-5解读分析结果并用于配置) | | 226 | +| Echo Head | 具有 copying matching 能力的注意力头，倾向于复制前一段对应位置信息 | 本指南 [步骤 5](#步骤-5解读分析结果并交付-mindie-推理框架) | |
| 227 | -| `RaCompressAnalysisInterface` | 模型适配器需实现的接口，提供 Q、K、QKV 投影层名称模式 | [接口定义](../../../msmodelslim/processor/analysis/unary_operator/metrics/ra_compress/interface.py) | | 227 | +| `RaCompressAnalysisInterface` | 模型适配器可选实现的接口：`get_proj_names` 与 `get_tokenizer` 均需实现 | [接口定义](../../../msmodelslim/processor/analysis/unary_operator/metrics/ra_compress/interface.py) | |
| 228 | 228 | ||
| 229 | ## 9. 接口文档列表 | 229 | ## 9. 接口文档列表 |
| 230 | 230 | ||
| 231 | | 接口或能力 | 简述 | 链接 | | 231 | | 接口或能力 | 简述 | 链接 | |
| 232 | | --- | --- | --- | | 232 | | --- | --- | --- | |
| 233 | | `msmodelslim analyze attn_head` | Attention Head 筛选分析命令行入口 | 《[msmodelslim analyze 命令行 API](../api_reference/cli/msmodelslim_analyze.md)》；本指南 [命令行预览](#命令行预览) | | 233 | | `msmodelslim analyze attn_head` | Attention Head 筛选分析命令行入口 | 《[msmodelslim analyze 命令行 API](../api_reference/cli/msmodelslim_analyze.md)》；本指南 [命令行预览](#命令行预览) | |
| 234 | -| `RaCompressAnalysisInterface` | 模型适配器 RA Compress 接口 | [接口定义](../../../msmodelslim/processor/analysis/unary_operator/metrics/ra_compress/interface.py) | | 234 | +| `RaCompressAnalysisInterface` | 模型适配器 RA Compress 接口（`get_proj_names` / `get_tokenizer`） | [接口定义](../../../msmodelslim/processor/analysis/unary_operator/metrics/ra_compress/interface.py) | |
| 235 | 235 | ||
| 236 | ## 10. 安全说明 | 236 | ## 10. 安全说明 |
| 237 | 237 | ||