已合并
[Doc] 补全权重转换 CLI/YAML/多卡说明并纠正知识库结构 #956
chenruijie创建于 9月14日
[Doc] 补全权重转换 CLI/YAML/多卡说明并纠正知识库结构 #956
已合并
共 8 个文件变更+172-98
| @@ -2,7 +2,7 @@ | |||
| 2 | 2 | ||
| 3 | ## 1. 功能说明 | 3 | ## 1. 功能说明 |
| 4 | 4 | ||
| 5 | -`msmodelslim quant` 是一键量化命令，加载原始模型权重并执行权重/激活量化，导出可部署的量化权重与描述文件。配置来源有两种：通过 `--quant_type` 按模型与量化类型自动匹配 `lab_practice` 中的最佳实践 YAML；或通过 `--config` 直接指定用户 YAML（支持 `modelslim_v1`、多模态以及 `modelslim_convert` 纯权重转换等协议，后者的配置可省略 `--model_type`）。两者都不传时按默认量化类型 `w8a8` 匹配最佳实践。 | 5 | +`msmodelslim quant` 是一键量化命令，加载原始模型权重并执行权重/激活量化，导出可部署的量化权重与描述文件。配置来源有两种：通过 `--quant_type` 按模型与量化类型自动匹配 `lab_practice` 中的最佳实践 YAML；或通过 `--config` 直接指定用户 YAML（支持 `modelslim_v1`、多模态以及 `modelslim_convert` 纯权重转换等协议；权重转换不需要 `--model_type`）。两者都不传时按默认量化类型 `w8a8` 匹配最佳实践。 |
| 6 | 6 | ||
| 7 | 命令边界：设备支持 `npu`、`cpu`，多卡通过 `--device_id` 指定索引列表；还支持场景标签匹配与 `--debug` 调试上下文落盘。校准数据准备与部署等操作步骤见《[一键量化完整指南](../../user_guide/usage_quick_quantization.md)》，YAML 字段说明见《[modelslim_v1 配置说明](../config/task/modelslim_v1.md)》等引用的配置文档。 | 7 | 命令边界：设备支持 `npu`、`cpu`，多卡通过 `--device_id` 指定索引列表；还支持场景标签匹配与 `--debug` 调试上下文落盘。校准数据准备与部署等操作步骤见《[一键量化完整指南](../../user_guide/usage_quick_quantization.md)》，YAML 字段说明见《[modelslim_v1 配置说明](../config/task/modelslim_v1.md)》等引用的配置文档。 |
| 8 | 8 | ||
| @@ -25,7 +25,7 @@ msmodelslim quant [--model_type <model_type>] --model_path <model_path> --save_p | |||
| 25 | 25 | ||
| 26 | | 参数 | 别名 | 类型 | 传入形式 | 必选/可选 | 默认值 | 取值范围或格式 | 含义 | | 26 | | 参数 | 别名 | 类型 | 传入形式 | 必选/可选 | 默认值 | 取值范围或格式 | 含义 | |
| 27 | |------|------|------|----------|-----------|--------|----------------|------| | 27 | |------|------|------|----------|-----------|--------|----------------|------| |
| 28 | -| `--model_type` | 无 | `string` | 单值 | 条件必选（普通量化路径必选；`--config` 指向 `apiversion: modelslim_convert` 的配置时可省略） | 无 | 模型类型名称，如 `Qwen2.5-7B-Instruct`、`transformers` | 指定待量化模型类型，用于加载对应模型适配器并匹配最佳实践；`transformers`支持加载基于 transformers 的通用基础模型适配器，当前仅适用于大语言模型量化；仅当 `--config` 指向 `apiversion: modelslim_convert` 的配置时可省略。 | | 28 | +| `--model_type` | 无 | `string` | 单值 | 条件必选（量化路径必选；权重转换不需要） | 无 | 模型类型名称，如 `Qwen2.5-7B-Instruct`、`transformers` | 指定待量化模型类型，用于加载对应模型适配器并匹配最佳实践；`transformers`支持加载基于 transformers 的通用基础模型适配器，当前仅适用于大语言模型量化。权重转换不需要此参数。 | |
| 29 | | `--model_path` | 无 | `string` | 单值 | 必选 | 无 | 原始模型权重目录（需存在且可读） | 待量化模型的权重目录。 | | 29 | | `--model_path` | 无 | `string` | 单值 | 必选 | 无 | 原始模型权重目录（需存在且可读） | 待量化模型的权重目录。 | |
| 30 | | `--save_path` | 无 | `string` | 单值 | 必选 | 无 | 输出目录（需可写） | 量化权重与描述文件的保存目录。 | | 30 | | `--save_path` | 无 | `string` | 单值 | 必选 | 无 | 输出目录（需可写） | 量化权重与描述文件的保存目录。 | |
| 31 | | `--device` | 无 | `string` | 单值 | 可选 | `npu` | `npu`、`cpu` | 运行设备类型；多卡索引请用 `--device_id` 指定。 | | 31 | | `--device` | 无 | `string` | 单值 | 可选 | `npu` | `npu`、`cpu` | 运行设备类型；多卡索引请用 `--device_id` 指定。 | |
| @@ -45,7 +45,7 @@ msmodelslim quant [--model_type <model_type>] --model_path <model_path> --save_p | |||
| 45 | - `--config` 与 `--quant_type` 互斥，同时传入会报错。 | 45 | - `--config` 与 `--quant_type` 互斥，同时传入会报错。 |
| 46 | - 两者都不传时，按默认量化类型 `w8a8` 匹配最佳实践；未匹配到最佳实践时会给出提示并等待确认（输入 `y` 继续，否则退出）。 | 46 | - 两者都不传时，按默认量化类型 `w8a8` 匹配最佳实践；未匹配到最佳实践时会给出提示并等待确认（输入 `y` 继续，否则退出）。 |
| 47 | - 指定 `--config` 后直接采用该配置，`--quant_type` 与 `--tags` 的最佳实践匹配均被忽略。 | 47 | - 指定 `--config` 后直接采用该配置，`--quant_type` 与 `--tags` 的最佳实践匹配均被忽略。 |
| 48 | -- `--model_type` 在普通量化路径下必须提供；仅当 `--config` 指向 `apiversion: modelslim_convert` 的配置时可省略。 | 48 | +- `--model_type`：量化路径必须提供；权重转换不需要。 |
| 49 | - `--model_type` 指定 `transformers` 时，若使用 `--quant_type`， 仅支持 `w8a16`/`w8a8`；若使用 `--config`，当前仅支持大语言模型量化配置（`apiversion: modelslim_v1`）。 | 49 | - `--model_type` 指定 `transformers` 时，若使用 `--quant_type`， 仅支持 `w8a16`/`w8a8`；若使用 `--config`，当前仅支持大语言模型量化配置（`apiversion: modelslim_v1`）。 |
| 50 | - `--tags` 指定多个值时须同时出现在同一已验证场景；未提供硬件类型标签时自动匹配当前设备类型。 | 50 | - `--tags` 指定多个值时须同时出现在同一已验证场景；未提供硬件类型标签时自动匹配当前设备类型。 |
| 51 | - `--debug` 启用后量化上下文写入 `${SAVE_PATH}/debug_info/`。 | 51 | - `--debug` 启用后量化上下文写入 `${SAVE_PATH}/debug_info/`。 |
| @@ -57,7 +57,7 @@ msmodelslim quant [--model_type <model_type>] --model_path <model_path> --save_p | |||
| 57 | | `--config` | `modelslim_v1` | 加载整份量化 YAML | 《[modelslim_v1 配置说明](../config/task/modelslim_v1.md)》 | | 57 | | `--config` | `modelslim_v1` | 加载整份量化 YAML | 《[modelslim_v1 配置说明](../config/task/modelslim_v1.md)》 | |
| 58 | | `--config` | `multimodal_vlm_modelslim_v1` | 多模态理解模型量化 YAML | 《[multimodal_vlm_modelslim_v1 配置说明](../config/task/multimodal_vlm_modelslim_v1.md)》 | | 58 | | `--config` | `multimodal_vlm_modelslim_v1` | 多模态理解模型量化 YAML | 《[multimodal_vlm_modelslim_v1 配置说明](../config/task/multimodal_vlm_modelslim_v1.md)》 | |
| 59 | | `--config` | `multimodal_sd_modelslim_v1` | 多模态生成模型量化 YAML | 《[multimodal_sd_modelslim_v1 配置说明](../config/task/multimodal_sd_modelslim_v1.md)》 | | 59 | | `--config` | `multimodal_sd_modelslim_v1` | 多模态生成模型量化 YAML | 《[multimodal_sd_modelslim_v1 配置说明](../config/task/multimodal_sd_modelslim_v1.md)》 | |
| 60 | -| `--config` | `modelslim_convert` | 纯权重转换协议 YAML，可省略 `--model_type` | 《[modelslim_convert 配置说明](../config/task/modelslim_convert.md)》 | | 60 | +| `--config` | `modelslim_convert` | 权重转换 YAML；不需要 `--model_type` | 《[modelslim_convert 配置说明](../config/task/modelslim_convert.md)》 | |
| 61 | | `--quant_type` | `lab_practice` 最佳实践 YAML | 按模型与量化类型匹配 | 《[一键量化完整指南](../../user_guide/usage_quick_quantization.md)》 | | 61 | | `--quant_type` | `lab_practice` 最佳实践 YAML | 按模型与量化类型匹配 | 《[一键量化完整指南](../../user_guide/usage_quick_quantization.md)》 | |
| 62 | 62 | ||
| 63 | ## 6. 环境变量 | 63 | ## 6. 环境变量 |
| @@ -104,7 +104,7 @@ msmodelslim quant \ | |||
| 104 | --device_id 0 1 2 3 | 104 | --device_id 0 1 2 3 |
| 105 | ``` | 105 | ``` |
| 106 | 106 | ||
| 107 | -`--quant_type w8a8c8` 表示权重8bit、激活8bit、KVCache 8bit 量化；`--device_id 0 1 2 3` 使用4个 NPU 设备（索引列表形式在 `apiversion: modelslim_v1` 配置下受支持）。 | 107 | +`--quant_type w8a8c8` 表示权重8bit、激活8bit、KVCache 8bit 量化；`--device_id 0 1 2 3` 使用 4 个 NPU 设备。权重转换的命令见 [7.6](#76-权重转换不需要-model_type)。 |
| 108 | 108 | ||
| 109 | ### 7.4 使用自定义配置文件 | 109 | ### 7.4 使用自定义配置文件 |
| 110 | 110 | ||
| @@ -116,7 +116,7 @@ msmodelslim quant \ | |||
| 116 | --config "${CONFIG_PATH}" | 116 | --config "${CONFIG_PATH}" |
| 117 | ``` | 117 | ``` |
| 118 | 118 | ||
| 119 | -`${CONFIG_PATH}` 指向符合 V1 等协议的量化 YAML；指定后直接采用该配置，不再做最佳实践匹配。字段说明见引用的配置文档。 | 119 | +`${CONFIG_PATH}` 指向符合 V1 等协议的量化 YAML；指定后直接采用该配置，不再做最佳实践匹配。字段说明见引用的配置文档。权重转换示例见 [7.6](#76-权重转换不需要-model_type)。 |
| 120 | 120 | ||
| 121 | ### 7.5 使用场景标签匹配最佳实践 | 121 | ### 7.5 使用场景标签匹配最佳实践 |
| 122 | 122 | ||
| @@ -131,6 +131,32 @@ msmodelslim quant \ | |||
| 131 | 131 | ||
| 132 | `--tags` 后的多个标签须同时出现在同一已验证场景中；未精确匹配时命令会给出提示并等待确认（输入 `y` 继续，否则退出）；命中备用（standby）配置时提示改用备用配置，仍需用户确认。 | 132 | `--tags` 后的多个标签须同时出现在同一已验证场景中；未精确匹配时命令会给出提示并等待确认（输入 `y` 继续，否则退出）；命中备用（standby）配置时提示改用备用配置，仍需用户确认。 |
| 133 | 133 | ||
| 134 | +<a id="76-权重转换不需要-model_type"></a> | ||
| 135 | + | ||
| 136 | +### 7.6 权重转换（不需要 `--model_type`） | ||
| 137 | + | ||
| 138 | +`--config` 使用 `apiversion: modelslim_convert` 的 YAML。不需要 `--model_type` 和 `--quant_type`： | ||
| 139 | + | ||
| 140 | +```bash | ||
| 141 | +msmodelslim quant \ | ||
| 142 | + --model_path "${MODEL_PATH}" \ | ||
| 143 | + --save_path "${SAVE_PATH}" \ | ||
| 144 | + --config "${CONFIG_PATH}" | ||
| 145 | +``` | ||
| 146 | + | ||
| 147 | +`${MODEL_PATH}` 为源权重目录，`${SAVE_PATH}` 为转换输出目录，`${CONFIG_PATH}` 为转换 YAML。配置协议与字段见《[modelslim_convert 配置说明](../config/task/modelslim_convert.md)》，操作步骤与示例 YAML 见《[权重转换使用指南](../../knowledge_base/ptq/convert/usage_weight_conversion.md)》。 | ||
| 148 | + | ||
| 149 | +NPU 多卡时加上 `--device npu` 和 `--device_id`： | ||
| 150 | + | ||
| 151 | +```bash | ||
| 152 | +msmodelslim quant \ | ||
| 153 | + --model_path "${MODEL_PATH}" \ | ||
| 154 | + --save_path "${SAVE_PATH}" \ | ||
| 155 | + --config "${CONFIG_PATH}" \ | ||
| 156 | + --device npu \ | ||
| 157 | + --device_id 0 1 2 3 | ||
| 158 | +``` | ||
| 159 | + | ||
| 134 | ## 8. 退出码与异常处理 | 160 | ## 8. 退出码与异常处理 |
| 135 | 161 | ||
| 136 | | 退出码或异常 | 含义 | 处理建议 | | 162 | | 退出码或异常 | 含义 | 处理建议 | |
| @@ -10,18 +10,21 @@ | |||
| 10 | | 配置类 | `ModelslimConvertQuantConfig` | | 10 | | 配置类 | `ModelslimConvertQuantConfig` | |
| 11 | | 源码 | [quant_config.py](../../../../../msmodelslim/core/quant_service/modelslim_convert/quant_config.py) | | 11 | | 源码 | [quant_config.py](../../../../../msmodelslim/core/quant_service/modelslim_convert/quant_config.py) | |
| 12 | 12 | ||
| 13 | +执行入口是 `msmodelslim quant --config`，完整命令与操作步骤见《[msmodelslim quant 命令行](../../cli/msmodelslim_quant.md#76-权重转换不需要-model_type)》与《[权重转换使用指南](../../../knowledge_base/ptq/convert/usage_weight_conversion.md)》。 | ||
| 14 | + | ||
| 13 | ## 2. 参数列表 | 15 | ## 2. 参数列表 |
| 14 | 16 | ||
| 15 | <h3 id="2-1-modelslim-convert">2.1 ModelslimConvertQuantConfig</h3> | 17 | <h3 id="2-1-modelslim-convert">2.1 ModelslimConvertQuantConfig</h3> |
| 16 | 18 | ||
| 17 | | 字段路径 | 类型 | 必选/可选 | 默认值 | 取值范围或格式 | 含义 | 引用配置 | | 19 | | 字段路径 | 类型 | 必选/可选 | 默认值 | 取值范围或格式 | 含义 | 引用配置 | |
| 18 | |----------|------|-----------|--------|----------------|------|----------| | 20 | |----------|------|-----------|--------|----------------|------|----------| |
| 19 | -| `apiversion` | `string` | 可选 | Unknown（代码占位；YAML 中须按任务类型显式指定） | `modelslim_v1`、`multimodal_vlm_modelslim_v1`、`multimodal_sd_modelslim_v1`、`modelslim_convert` | API 版本（任务类型），决定 spec 的结构：`modelslim_v1`、`multimodal_vlm_modelslim_v1`、`multimodal_sd_modelslim_v1`、`modelslim_convert`；YAML 中必须显式指定，默认值 `Unknown` 仅为代码内部占位，不可直接使用。 | 无 | | 21 | +| `apiversion` | `string` | 必选 | 无 | `modelslim_convert` | 权重转换任务类型，固定为 `modelslim_convert`。 | 无 | |
| 20 | -| `spec` | `object` | 必选 | 无 | — | `modelslim_convert` 服务的 spec 结构。<br><br>声明权重名重命名/变换（`preprocess`）、线性层转换规则（`linears`）、<br>保存格式（`save`）、并行执行（`parallel`）与默认值（`defaults`）。 | 本页 <a href="#2-2-modelslim-convert-spec">§2.2</a> | | 22 | +| `spec` | `object` | 必选 | 无 | — | `modelslim_convert` 服务的 spec 结构，声明线性层转换规则（`linears`）、保存格式（`save`）与并行（`parallel`）。 | 本页 <a href="#2-2-modelslim-convert-spec">§2.2</a> | |
| 21 | 23 | ||
| 22 | **配置约束** | 24 | **配置约束** |
| 23 | 25 | ||
| 24 | -- 无。 | 26 | +- YAML 须写 `apiversion: modelslim_convert`。 |
| 27 | +- `spec` 为必选；日常至少配置 `linears` 与 `save`。 | ||
| 25 | 28 | ||
| 26 | <h3 id="2-2-modelslim-convert-spec">2.2 ModelslimConvertServiceConfig</h3> | 29 | <h3 id="2-2-modelslim-convert-spec">2.2 ModelslimConvertServiceConfig</h3> |
| 27 | 30 | ||
| @@ -32,12 +35,12 @@ | |||
| 32 | | `preprocess` | `list[object]` | 可选 | `[]` | — | 预处理步骤列表，每项 `type` 为 `rename` 或 `convert`。 | 本页 <a href="#2-3-preprocessconfig">§2.3</a> | | 35 | | `preprocess` | `list[object]` | 可选 | `[]` | — | 预处理步骤列表，每项 `type` 为 `rename` 或 `convert`。 | 本页 <a href="#2-3-preprocessconfig">§2.3</a> | |
| 33 | | `linears` | `list[object]` | 可选 | `[]` | — | 线性层转换规则列表。 | 本页 <a href="#2-8-linear-convert-config">§2.8</a> | | 36 | | `linears` | `list[object]` | 可选 | `[]` | — | 线性层转换规则列表。 | 本页 <a href="#2-8-linear-convert-config">§2.8</a> | |
| 34 | | `save` | `list[object]` | 可选 | `[]` | — | 保存格式配置列表，取首个生效。 | 本页 <a href="#2-9-save-config">§2.9</a> | | 37 | | `save` | `list[object]` | 可选 | `[]` | — | 保存格式配置列表，取首个生效。 | 本页 <a href="#2-9-save-config">§2.9</a> | |
| 35 | -| `parallel` | `object` | 可选 | 见嵌套配置默认值 | — | 并行执行配置。 | 本页 <a href="#2-10-parallel-spec-config">§2.10</a> | | 38 | +| `parallel` | `object` | 可选 | 见嵌套配置默认值 | — | CPU 并行配置。NPU 多卡用命令行 `--device_id`。 | 本页 <a href="#2-10-parallel-spec-config">§2.10</a> | |
| 36 | -| `defaults` | `object` | 可选 | 见嵌套配置默认值 | — | 字段缺省时的全局默认值。 | 本页 <a href="#2-11-convert-defaults">§2.11</a> | | 39 | +| `defaults` | `object` | 可选 | 见嵌套配置默认值 | — | 保底默认值配置。配置了 `save` 时直接按 `save` 执行，不走此处的默认值。 | 本页 <a href="#2-11-convert-defaults">§2.11</a> | |
| 37 | 40 | ||
| 38 | **配置约束** | 41 | **配置约束** |
| 39 | 42 | ||
| 40 | -- 无。 | 43 | +- 日常至少配置 `linears` 与 `save`。配置了 `save` 时以 `save[0].type` 为准，`defaults.dst_format` 会被忽略。 |
| 41 | 44 | ||
| 42 | <h3 id="2-3-preprocessconfig">2.3 PreprocessConfig</h3> | 45 | <h3 id="2-3-preprocessconfig">2.3 PreprocessConfig</h3> |
| 43 | 46 | ||
| @@ -99,21 +102,21 @@ | |||
| 99 | 102 | ||
| 100 | **配置约束** | 103 | **配置约束** |
| 101 | 104 | ||
| 102 | -- 无。 | 105 | +- `type: chunk` 用于拆分 fused 的 `gate_up_proj`。专家数从模型 `config.json` 的 `num_experts` 读取。 |
| 106 | +- 权重已经是独立的 `gate_proj` / `up_proj` 时不要再配 `chunk`，只改 `linears.match`。 | ||
| 103 | 107 | ||
| 104 | <h3 id="2-8-linear-convert-config">2.8 LinearConvertConfig</h3> | 108 | <h3 id="2-8-linear-convert-config">2.8 LinearConvertConfig</h3> |
| 105 | 109 | ||
| 106 | -指定匹配的线性层转换到目标 IR 的规则。 | 110 | +指定匹配的线性层要转到哪种目标格式。 |
| 107 | 111 | ||
| 108 | | 字段路径 | 类型 | 必选/可选 | 默认值 | 取值范围或格式 | 含义 | 引用配置 | | 112 | | 字段路径 | 类型 | 必选/可选 | 默认值 | 取值范围或格式 | 含义 | 引用配置 | |
| 109 | |----------|------|-----------|--------|----------------|------|----------| | 113 | |----------|------|-----------|--------|----------------|------|----------| |
| 110 | | `match` | `list[string]` | 可选 | `[]` | — | 匹配的线性层名称模式列表。 | 无 | | 114 | | `match` | `list[string]` | 可选 | `[]` | — | 匹配的线性层名称模式列表。 | 无 | |
| 111 | -| `target` | `string` | 必选 | 无 | `FLOAT`、`FP8_BLOCK`、`W8A8_MXFP8`、`W4A4_MXFP4`、`W4A8_MXFP8`、`INT4_PACKED`、`NVFP4_MODELOPT`、`HIFP4`、`UNKNOWN` | 转换目标 IR 类型，如 `W8A8_MXFP8`、`INT4_PACKED` 等。 | 无 | | 115 | +| `target` | `string` | 必选 | 无 | `FLOAT`、`W8A8_MXFP8` | 转换目标。常用 `FLOAT`、`W8A8_MXFP8`。 | 无 | |
| 112 | -| `route` | `list[string] / string` | 可选 | `auto` | `FLOAT`、`FP8_BLOCK`、`W8A8_MXFP8`、`W4A4_MXFP4`、`W4A8_MXFP8`、`INT4_PACKED`、`NVFP4_MODELOPT`、`HIFP4`、`UNKNOWN`；`auto` | 转换路径：显式 IR 列表（首元素为源 IR），或 `auto` 由虚拟树按权重 dtype 推断。 | 无 | | ||
| 113 | 116 | ||
| 114 | **配置约束** | 117 | **配置约束** |
| 115 | 118 | ||
| 116 | -- 无。 | 119 | +- `W8A8_MXFP8` 配 `ascend_v1`，`FLOAT` 配 `huggingface`。 |
| 117 | 120 | ||
| 118 | <h3 id="2-9-save-config">2.9 SaveConfig</h3> | 121 | <h3 id="2-9-save-config">2.9 SaveConfig</h3> |
| 119 | 122 | ||
| @@ -121,12 +124,12 @@ | |||
| 121 | 124 | ||
| 122 | | 字段路径 | 类型 | 必选/可选 | 默认值 | 取值范围或格式 | 含义 | 引用配置 | | 125 | | 字段路径 | 类型 | 必选/可选 | 默认值 | 取值范围或格式 | 含义 | 引用配置 | |
| 123 | |----------|------|-----------|--------|----------------|------|----------| | 126 | |----------|------|-----------|--------|----------------|------|----------| |
| 124 | -| `type` | `string` | 可选 | `ascend_v1` | — | 保存格式：`ascend_v1`（昇腾，与 `ConvertDefaults.dst_format` 的 `ascendv1` 等价）；`compressed_tensors`（HF 兼容 safetensors）；`huggingface`/`hf` 是 `compressed_tensors` 的别名。 | 无 | | 127 | +| `type` | `string` | 可选 | `ascend_v1` | — | 保存格式：`ascend_v1`（昇腾 AscendV1）、`huggingface`（HF safetensors）。 | 无 | |
| 125 | | `part_file_size` | `int` | 可选 | `4` | — | 分片文件大小，单位 GB；0 表示不分片。 | 无 | | 128 | | `part_file_size` | `int` | 可选 | `4` | — | 分片文件大小，单位 GB；0 表示不分片。 | 无 | |
| 126 | 129 | ||
| 127 | **配置约束** | 130 | **配置约束** |
| 128 | 131 | ||
| 129 | -- 无。 | 132 | +- `W8A8_MXFP8` 必须用 `ascend_v1`；`FLOAT` 用 `huggingface`。 |
| 130 | 133 | ||
| 131 | <h3 id="2-10-parallel-spec-config">2.10 ParallelSpecConfig</h3> | 134 | <h3 id="2-10-parallel-spec-config">2.10 ParallelSpecConfig</h3> |
| 132 | 135 | ||
| @@ -134,44 +137,58 @@ | |||
| 134 | 137 | ||
| 135 | | 字段路径 | 类型 | 必选/可选 | 默认值 | 取值范围或格式 | 含义 | 引用配置 | | 138 | | 字段路径 | 类型 | 必选/可选 | 默认值 | 取值范围或格式 | 含义 | 引用配置 | |
| 136 | |----------|------|-----------|--------|----------------|------|----------| | 139 | |----------|------|-----------|--------|----------------|------|----------| |
| 137 | -| `workers` | `int` | 可选 | `1` | — | 并行 worker 数：1 表示单进程组内线程（可配 NPU）；大于1 表示组间多进程 + 组内线程（CPU）。 | 无 | | 140 | +| `workers` | `int` | 可选 | `1` | — | CPU 并行 worker 数。 | 无 | |
| 138 | -| `max_group_size` | `int / null` | 可选 | `null` | — | 单个依赖组的最大任务数，超过则拆成多个子组分散到不同进程；不设置表示不拆分。 | 无 | | 141 | +| `max_group_size` | `int / null` | 可选 | `null` | — | 单个依赖组的最大任务数，超过则拆成多个子组分散到不同进程/卡；不设置表示不拆分。 | 无 | |
| 139 | -| `worker_device` | `string` | 可选 | `cpu` | — | worker 运行设备：`cpu` 或 `npu`。 | 无 | | ||
| 140 | -| `npu_max_workers` | `int` | 可选 | `1` | — | 仅 `workers=1` 且 `worker_device=npu` 时生效，限制组内并发以防显存溢出。 | 无 | | ||
| 141 | 142 | ||
| 142 | **配置约束** | 143 | **配置约束** |
| 143 | 144 | ||
| 144 | -- 无。 | 145 | +- `workers` 用于 CPU。NPU 用 `--device npu --device_id ...`。 |
| 146 | +- `max_group_size`：MoE 等含有大量专家任务的模型，可设置为约「每层专家任务数 / 卡数」（如 8 卡设为 96），防止大组单进程/单卡长尾等待。 | ||
| 145 | 147 | ||
| 146 | <h3 id="2-11-convert-defaults">2.11 ConvertDefaults</h3> | 148 | <h3 id="2-11-convert-defaults">2.11 ConvertDefaults</h3> |
| 147 | 149 | ||
| 148 | -转换规则未显式声明字段时的全局默认值。 | 150 | +未显式声明对应配置时的全局保底默认值。 |
| 149 | 151 | ||
| 150 | | 字段路径 | 类型 | 必选/可选 | 默认值 | 取值范围或格式 | 含义 | 引用配置 | | 152 | | 字段路径 | 类型 | 必选/可选 | 默认值 | 取值范围或格式 | 含义 | 引用配置 | |
| 151 | |----------|------|-----------|--------|----------------|------|----------| | 153 | |----------|------|-----------|--------|----------------|------|----------| |
| 152 | -| `src_format` | `string` | 可选 | `auto` | — | 源权重格式；`auto` 由模型适配器/权重目录自动推断。 | 无 | | 154 | +| `src_format` | `string` | 可选 | `auto` | — | 源权重格式；工具按 checkpoint 权重 key 与 dtype 自动推断，日常无需配置。 | 无 | |
| 153 | -| `dst_format` | `string` | 可选 | `ascendv1` | — | 目标保存格式：`ascendv1`（昇腾，与 `SaveConfig.type` 的 `ascend_v1` 等价）；`compressed_tensors`（HF 兼容 safetensors）；`huggingface`/`hf` 是 `compressed_tensors` 的别名。 | 无 | | 155 | +| `dst_format` | `string` | 可选 | `ascendv1` | — | 保底落盘格式。**与 `spec.save` 互斥**：只要配置了 `spec.save`，就直接使用 `save[0].type`，不走本字段；未配置 `spec.save` 时才回退到此默认值。 | 无 | |
| 154 | -| `dst_ir` | `string / null` | 可选 | `null` | `FLOAT`、`FP8_BLOCK`、`W8A8_MXFP8`、`W4A4_MXFP4`、`W4A8_MXFP8`、`INT4_PACKED`、`NVFP4_MODELOPT`、`HIFP4`、`UNKNOWN`；或 null | 目标 IR 类型；不设置时由目标格式决定。 | 无 | | 156 | +| `dst_ir` | `string / null` | 可选 | `null` | `FLOAT`、`W8A8_MXFP8` 等；或 null | 保底目标格式。各层目标格式直接由 `linears[].target` 显式指定，日常无需配置此项。 | 无 | |
| 155 | 157 | ||
| 156 | -**配置约束** | 158 | +**配置约束与互斥说明** |
| 157 | 159 | ||
| 158 | -- 无。 | 160 | +- **与 `spec.save` 互斥/覆盖**：`spec.save` 优先级高于 `defaults.dst_format`。只要在 YAML 中配置了 `spec.save`（如 `type: ascend_v1` 或 `type: huggingface`），系统直接按 `save` 落盘，**完全不走 `defaults.dst_format` 默认值**。 |
| 161 | +- **与 `linears.target` 的关系**：线性层转换目标直接由各条规则的 `linears[].target` 指定，不走 `defaults.dst_ir`。 | ||
| 162 | +- **无需配置**：日常转换推荐显式配置 `linears` 和 `save`，**无需配置 `defaults`**。 | ||
| 159 | 163 | ||
| 160 | ## 3. 完整配置参考 | 164 | ## 3. 完整配置参考 |
| 161 | 165 | ||
| 162 | ```yaml | 166 | ```yaml |
| 163 | apiversion: modelslim_convert | 167 | apiversion: modelslim_convert |
| 164 | spec: | 168 | spec: |
| 165 | - preprocess: [] | ||
| 166 | linears: [] | 169 | linears: [] |
| 167 | save: [] | 170 | save: [] |
| 168 | parallel: | 171 | parallel: |
| 169 | workers: 1 | 172 | workers: 1 |
| 170 | max_group_size: null | 173 | max_group_size: null |
| 171 | - worker_device: cpu | 174 | +``` |
| 172 | - npu_max_workers: 1 | 175 | + |
| 173 | - defaults: | 176 | +可落地的最小命令： |
| 174 | - src_format: auto | 177 | + |
| 175 | - dst_format: ascendv1 | 178 | +```bash |
| 176 | - dst_ir: null | 179 | +msmodelslim quant \ |
| 180 | + --model_path "${MODEL_PATH}" \ | ||
| 181 | + --save_path "${SAVE_PATH}" \ | ||
| 182 | + --config "${CONFIG_PATH}" | ||
| 183 | +``` | ||
| 184 | + | ||
| 185 | +多卡 NPU： | ||
| 186 | + | ||
| 187 | +```bash | ||
| 188 | +msmodelslim quant \ | ||
| 189 | + --model_path "${MODEL_PATH}" \ | ||
| 190 | + --save_path "${SAVE_PATH}" \ | ||
| 191 | + --config "${CONFIG_PATH}" \ | ||
| 192 | + --device npu \ | ||
| 193 | + --device_id 0 1 2 3 | ||
| 177 | ``` | 194 | ``` |
| @@ -8,5 +8,5 @@ | |||
| 8 | | `quantization_mode` | 《[量化模式](quantization_mode/README.md)》 | | 8 | | `quantization_mode` | 《[量化模式](quantization_mode/README.md)》 | |
| 9 | | `tuning_strategies` | 《[调优策略](tuning_strategies/README.md)》 | | 9 | | `tuning_strategies` | 《[调优策略](tuning_strategies/README.md)》 | |
| 10 | | `quantization_format` | 《[量化格式](quantization_format/README.md)》 | | 10 | | `quantization_format` | 《[量化格式](quantization_format/README.md)》 | |
| 11 | -| `ptq` | 《[训练后量化](ptq/convert/usage_weight_conversion.md)》 | | 11 | +| `ptq` | 《[训练后量化](ptq/README.md)》 | |
| 12 | -| `parallel` | 《[多卡并行](parallel/README.md)》| | 12 | +| `parallel` | 《[多卡量化并行](parallel/README.md)》 | |
| @@ -1,14 +1,16 @@ | |||
| 1 | -# 多卡并行 | 1 | +# 多卡量化并行 |
| 2 | + | ||
| 3 | +> **范围说明**：本目录实际内容仅包含多卡量化机制（DP / EP / DTS）。**多卡量化机制不覆盖权重转换（Convert），权重转换走自身独立的转换并行方案**（NPU 多卡使用 `--device npu --device_id` 启动每卡独立计算进程，CPU 并行使用 `parallel.workers`），具体请参阅《[权重转换使用指南](../ptq/convert/usage_weight_conversion.md)》。 | ||
| 2 | 4 | ||
| 3 | ## 1. 并行机制简述 | 5 | ## 1. 并行机制简述 |
| 4 | 6 | ||
| 5 | -msModelSlim 的并行机制以数据并行（Data Parallel, DP）为基础，当一个量化流程中涉及的量化算法均已实现 DP 支持时，则该量化可使用多卡完成，因而我们也称 DP 为多卡量化的完备性支持。专家并行（Expert Parallel, EP）和分布式任务调度器（Distributed Task Scheduler, DTS）均是在完备性支持的基础上，在特定场景下对多卡量化进行的优化。EP 面向 MoE 模型，通过专家分片加载降低单卡显存占用，同时也起到量化提速的作用。DTS 面向计算密集型算法，将复杂流程拆为可调度的原子子任务，用卡间共享任务队列替代各卡重复执行完整任务链，以提升复杂算法的执行效率。 | 7 | +msModelSlim 量化侧的并行机制以数据并行（Data Parallel, DP）为基础，当一个量化流程中涉及的量化算法均已实现 DP 支持时，则该量化可使用多卡完成，因而我们也称 DP 为多卡量化的完备性支持。专家并行（Expert Parallel, EP）和分布式任务调度器（Distributed Task Scheduler, DTS）均是在完备性支持的基础上，在特定场景下对多卡量化进行的优化。EP 面向 MoE 模型，通过专家分片加载降低单卡显存占用，同时也起到量化提速的作用。DTS 面向计算密集型算法，将复杂流程拆为可调度的原子子任务，用卡间共享任务队列替代各卡重复执行完整任务链，以提升复杂算法的执行效率。 |
| 6 | 8 | ||
| 7 | 并行机制的原理决定了它们的适配体现在 msModelSlim 的不同概念域，DP 与 DTS 的适配体现在算法层面，msModelSlim 的算法则以 Processor 承载；EP 的适配体现在模型层面，msModelSlim 通过模型适配器承载对模型的改造与适配。使能一个量化任务的多卡量化的必要条件是完成量化方案中涉及到的算法的 DP 支持，EP 和 DTS 均在此基础上进行优化。由于当前基础模型的演进存在参数量持续上升的趋势，因而对于 MoE 结构的模型，建议在模型适配时完成 EP 支持以防止显存溢出。DTS 的支持则需要结合算法本身进行具体分析，只有对计算密集型的复杂算法它才会带来较为显著的加速效果。 | 9 | 并行机制的原理决定了它们的适配体现在 msModelSlim 的不同概念域，DP 与 DTS 的适配体现在算法层面，msModelSlim 的算法则以 Processor 承载；EP 的适配体现在模型层面，msModelSlim 通过模型适配器承载对模型的改造与适配。使能一个量化任务的多卡量化的必要条件是完成量化方案中涉及到的算法的 DP 支持，EP 和 DTS 均在此基础上进行优化。由于当前基础模型的演进存在参数量持续上升的趋势，因而对于 MoE 结构的模型，建议在模型适配时完成 EP 支持以防止显存溢出。DTS 的支持则需要结合算法本身进行具体分析，只有对计算密集型的复杂算法它才会带来较为显著的加速效果。 |
| 8 | 10 | ||
| 9 | ## 2. 并行机制目录 | 11 | ## 2. 并行机制目录 |
| 10 | 12 | ||
| 11 | -本目录收录 msModelSlim 多卡量化相关的流程指南与术语百科。 | 13 | +本目录收录 msModelSlim **多卡量化**相关的流程指南与术语百科。 |
| 12 | 14 | ||
| 13 | | 文档 | 说明 | | 15 | | 文档 | 说明 | |
| 14 | |------|------| | 16 | |------|------| |
| @@ -61,4 +63,4 @@ msmodelslim quant \ | |||
| 61 | --device_id 0 1 2 3 4 5 6 7 | 63 | --device_id 0 1 2 3 4 5 6 7 |
| 62 | ``` | 64 | ``` |
| 63 | 65 | ||
| 64 | -**说明**：多卡量化启用后会自动调用已适配支持的 DP、EP、DTS 等并行机制。 | 66 | +**说明**：量化路径下会按已适配情况启用 DP、EP、DTS。多卡量化机制不覆盖权重转换（Convert），权重转换走自身方案，具体见《[权重转换使用指南](../ptq/convert/usage_weight_conversion.md)》。 |
| @@ -37,3 +37,4 @@ | |||
| 37 | | LLM 接入 | 新大语言模型（LLM）接入 msModelSlim 量化流程 | [《LLM 模型接入量化流程指南》](llm/integration_guide_large_language_model_quantization.md) | | 37 | | LLM 接入 | 新大语言模型（LLM）接入 msModelSlim 量化流程 | [《LLM 模型接入量化流程指南》](llm/integration_guide_large_language_model_quantization.md) | |
| 38 | | VLM 接入 | 新多模态视觉语言模型（VLM）接入 msModelSlim 量化流程 | [《VLM 模型接入量化流程指南》](vlm/integration_guide_vision_transformer_quantization.md) | | 38 | | VLM 接入 | 新多模态视觉语言模型（VLM）接入 msModelSlim 量化流程 | [《VLM 模型接入量化流程指南》](vlm/integration_guide_vision_transformer_quantization.md) | |
| 39 | | DiT 接入 | 新多模态生成模型（DiT）接入 msModelSlim 量化流程 | [《DiT 模型接入量化流程指南》](dit/integration_guide_diffusion_transformer_quantization.md) | | 39 | | DiT 接入 | 新多模态生成模型（DiT）接入 msModelSlim 量化流程 | [《DiT 模型接入量化流程指南》](dit/integration_guide_diffusion_transformer_quantization.md) | |
| 40 | +| 权重转换 | 纯配置驱动，无需编写模型适配器代码；按新模型权重结构配置 YAML 规则即可完成接入 | [《权重转换使用指南》](convert/usage_weight_conversion.md) | | ||
| @@ -3,7 +3,7 @@ apiversion: modelslim_convert | |||
| 3 | # 权重结构（依据 qwen3-8b-fp8 model.safetensors.index.json 校准）： | 3 | # 权重结构（依据 qwen3-8b-fp8 model.safetensors.index.json 校准）： |
| 4 | # - 与 mxfp8 配置相同的 7×36=252 个 FP8_BLOCK linear | 4 | # - 与 mxfp8 配置相同的 7×36=252 个 FP8_BLOCK linear |
| 5 | # - 仅反量化到 FLOAT(bf16)，不走 MXFP8 量化 | 5 | # - 仅反量化到 FLOAT(bf16)，不走 MXFP8 量化 |
| 6 | -# - 落盘为 HuggingFace / compressed_tensors 格式，供 HF 侧推理 | 6 | +# - 落盘为 huggingface 格式，供 HF 侧推理 |
| 7 | spec: | 7 | spec: |
| 8 | linears: | 8 | linears: |
| 9 | - match: | 9 | - match: |
| @@ -45,13 +45,14 @@ $$ \hat{x} = \text{round}\left(\frac{x}{\Delta_{\text{block}}}\right) $$ | |||
| 45 | - **Data-free 特性**：无需校准数据集，无需加载模型代码，纯权重离线计算。 | 45 | - **Data-free 特性**：无需校准数据集，无需加载模型代码，纯权重离线计算。 |
| 46 | - **无损转换**：`FP8_BLOCK → FLOAT` 和 `INT4_PACKED → FLOAT` 为无损转换（仅反量化）。 | 46 | - **无损转换**：`FP8_BLOCK → FLOAT` 和 `INT4_PACKED → FLOAT` 为无损转换（仅反量化）。 |
| 47 | - **有损转换**：`FLOAT → W8A8_MXFP8` 为有损转换（重新量化引入量化误差）。 | 47 | - **有损转换**：`FLOAT → W8A8_MXFP8` 为有损转换（重新量化引入量化误差）。 |
| 48 | -- **自动路由**：`route: auto` 时自动推断源 IR 并选择最短转换路径，支持多步串联。 | 48 | +- **自动路由**：`route: auto` 时自动推断源 IR 并选择转换路径，支持多步串联。 |
| 49 | - **7 阶段流水线**：从读 catalog 到落盘，全流程无需模型 forward。 | 49 | - **7 阶段流水线**：从读 catalog 到落盘，全流程无需模型 forward。 |
| 50 | -- **多种保存格式**：`ascend_v1`（MXFP8 部署）、`huggingface` / `compressed_tensors`（HF 生态）。 | 50 | +- **多种保存格式**：`ascend_v1`（MXFP8 部署）、`huggingface`（HF 生态）。 |
| 51 | +- **NPU / CPU**：NPU 用 `--device npu --device_id`；CPU 用 `parallel.workers`。 | ||
| 51 | 52 | ||
| 52 | ## 4. 流程示意 | 53 | ## 4. 流程示意 |
| 53 | 54 | ||
| 54 | -> 详细算法步骤与代码级解析，请参阅 [《权重转换完整指南》](./usage_weight_conversion.md)。 | 55 | +> 详细算法步骤与代码级解析，请参阅《[权重转换使用指南](./usage_weight_conversion.md)》。 |
| 55 | 56 | ||
| 56 | ### 4.1 处理流程 | 57 | ### 4.1 处理流程 |
| 57 | 58 | ||
| @@ -73,7 +74,7 @@ flowchart LR | |||
| 73 | 74 | ||
| 74 | ### 4.2 配置示例 | 75 | ### 4.2 配置示例 |
| 75 | 76 | ||
| 76 | -以下为最小可用的 YAML 配置片段（以 FP8 block 转 BF16 为例）。各字段的详细含义与取值范围，请参阅 [《权重转换完整指南》](./usage_weight_conversion.md)。 | 77 | +以下为最小可用的 YAML 配置片段（以 FP8 block 转 BF16 为例）。各字段的详细含义与取值范围，请参阅《[权重转换使用指南](./usage_weight_conversion.md)》。 |
| 77 | 78 | ||
| 78 | ```yaml | 79 | ```yaml |
| 79 | apiversion: modelslim_convert | 80 | apiversion: modelslim_convert |
| @@ -114,8 +115,9 @@ spec: | |||
| 114 | 115 | ||
| 115 | ## 6. 关联流程 | 116 | ## 6. 关联流程 |
| 116 | 117 | ||
| 117 | -- [《权重转换完整指南》](./usage_weight_conversion.md)：权重转换完整的操作流程、命令说明与详细配置协议。 | 118 | +- 《[权重转换使用指南](./usage_weight_conversion.md)》：权重转换完整的操作流程、命令说明与详细配置协议。 |
| 118 | -- [《一键量化完整指南》](../../../user_guide/usage_one_click_quantization.md)：常规一键量化（含校准）的完整流程，权重转换常作为其后续步骤。 | 119 | +- 《[msmodelslim quant 命令行](../../../api_reference/cli/msmodelslim_quant.md)》：含可复制的权重转换命令。 |
| 120 | +- 《[一键量化完整指南](../../../user_guide/usage_one_click_quantization.md)》：常规一键量化（含校准）的完整流程。 | ||
| 119 | 121 | ||
| 120 | ## 7. 关联词条 | 122 | ## 7. 关联词条 |
| 121 | 123 | ||
| @@ -126,6 +128,6 @@ spec: | |||
| 126 | 128 | ||
| 127 | ## 8. 参考文档 | 129 | ## 8. 参考文档 |
| 128 | 130 | ||
| 129 | -1. [《权重转换完整指南》](./usage_weight_conversion.md)：msModelSlim 权重转换详细文档。 | 131 | +1. 《[权重转换使用指南](./usage_weight_conversion.md)》：msModelSlim 权重转换详细文档。 |
| 130 | -2. [《msModelSlim 一键量化完整指南》](../../../user_guide/usage_one_click_quantization.md)：一键量化总体流程。 | 132 | +2. 《[msModelSlim 一键量化完整指南](../../../user_guide/usage_one_click_quantization.md)》：一键量化总体流程。 |
| 131 | -3. [《格式支持矩阵》](../../quantization_format/README.md)：量化格式与存储格式说明。 | 133 | +3. 《[格式支持矩阵](../../quantization_format/README.md)》：量化格式与存储格式说明。 |
| @@ -2,18 +2,18 @@ | |||
| 2 | 2 | ||
| 3 | ## 1. 适用范围 | 3 | ## 1. 适用范围 |
| 4 | 4 | ||
| 5 | -本指南面向需要对**已有量化/浮点权重**进行格式或精度变换的用户（如 FP8 block 反量化到 BF16、BF16 离线量化为 W8A8 MXFP8 等）。**重点不是展开完整配置协议，而是给出可上手的推荐配置，并说明每个配置项的含义（原理）以及何时需要调整、怎么选。** | 5 | +本指南面向需要对**已有量化/浮点权重**进行格式或精度变换的用户（如 FP8 block 反量化到 BF16、BF16 离线量化为 W8A8 MXFP8、INT4 packed 反量化到 BF16 等）。**重点是给出可上手的推荐配置、可复制的执行命令，并说明每个配置项的含义以及何时需要调整。** |
| 6 | 6 | ||
| 7 | 与常规一键量化的区别： | 7 | 与常规一键量化的区别： |
| 8 | 8 | ||
| 9 | | 对比项 | 常规一键量化 | 权重转换（modelslim_convert） | | 9 | | 对比项 | 常规一键量化 | 权重转换（modelslim_convert） | |
| 10 | |--------|--------------|-------------------------------| | 10 | |--------|--------------|-------------------------------| |
| 11 | | 是否需要校准集 | 是（激活值统计等） | **否** | | 11 | | 是否需要校准集 | 是（激活值统计等） | **否** | |
| 12 | -| 是否需要 `model_type` | 必选 | **可选** | | 12 | +| 是否需要 `model_type` | 必选 | **不需要** | |
| 13 | | 是否需要 `quant_type` | 方式 1 需要 | **不需要**（须通过 `--config` 指定转换配置） | | 13 | | 是否需要 `quant_type` | 方式 1 需要 | **不需要**（须通过 `--config` 指定转换配置） | |
| 14 | | 典型场景 | 浮点模型 → W8A8 等 | FP8 → BF16、BF16 → MXFP8、FP8 → MXFP8 等 | | 14 | | 典型场景 | 浮点模型 → W8A8 等 | FP8 → BF16、BF16 → MXFP8、FP8 → MXFP8 等 | |
| 15 | 15 | ||
| 16 | -命令行怎么写不在此展开，完整执行命令见[《一键量化完整指南》](../../../user_guide/usage_one_click_quantization.md)。 | 16 | +命令行书写规范见 [步骤 3](#步骤-3执行转换命令)，参数总表见《[msmodelslim quant 命令行](../../../api_reference/cli/msmodelslim_quant.md)》，字段说明见《[modelslim_convert 配置说明](../../../api_reference/config/task/modelslim_convert.md)》。 |
| 17 | 17 | ||
| 18 | ## 2. 输入和交付件 | 18 | ## 2. 输入和交付件 |
| 19 | 19 | ||
| @@ -21,11 +21,13 @@ | |||
| 21 | | --- | --- | --- | --- | --- | | 21 | | --- | --- | --- | --- | --- | |
| 22 | | 输入 | 源权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被读取，含 `model.safetensors.index.json` 或单文件权重 | | 22 | | 输入 | 源权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被读取，含 `model.safetensors.index.json` 或单文件权重 | |
| 23 | | 输入 | 转换配置 YAML | `--config` 指定 | `apiversion: modelslim_convert`，含 `spec.linears`、`spec.save` 等 | 配置校验通过 | | 23 | | 输入 | 转换配置 YAML | `--config` 指定 | `apiversion: modelslim_convert`，含 `spec.linears`、`spec.save` 等 | 配置校验通过 | |
| 24 | -| 交付件 | 转换后权重目录 | `--save_path` 指定路径 | 目标 IR 对应格式（ascend_v1 / huggingface） | 含完整权重文件，可被目标推理框架加载 | | 24 | +| 交付件 | 转换后权重目录 | `--save_path` 指定路径 | 目标 IR 对应格式（`ascend_v1` / `huggingface`） | 含完整权重文件，可被目标推理框架加载 | |
| 25 | + | ||
| 26 | +`--save_path` 不得指向源模型目录或其子目录，以免覆盖源权重。 | ||
| 25 | 27 | ||
| 26 | ## 3. 流程总览 | 28 | ## 3. 流程总览 |
| 27 | 29 | ||
| 28 | -入门时建议先用一组**推荐配置**建立基线，再根据实际转换场景调整参数。 | 30 | +入门时建议先复用一组**同族示例配置**建立基线，再按层名、目标 IR 与保存格式调整。 |
| 29 | 31 | ||
| 30 | ```mermaid | 32 | ```mermaid |
| 31 | flowchart LR | 33 | flowchart LR |
| @@ -41,18 +43,20 @@ flowchart LR | |||
| 41 | 43 | ||
| 42 | **操作**：先确定三件事——源权重当前是什么格式（FP8 block / BF16 / INT4 packed）、目标输出是什么 IR（`W8A8_MXFP8` / `FLOAT`）、目标部署框架是什么（决定 `save` 格式）。权重转换是**纯离线、data-free** 操作，不需要校准集、不需要 `model_type`、不需要 `quant_type`。 | 44 | **操作**：先确定三件事——源权重当前是什么格式（FP8 block / BF16 / INT4 packed）、目标输出是什么 IR（`W8A8_MXFP8` / `FLOAT`）、目标部署框架是什么（决定 `save` 格式）。权重转换是**纯离线、data-free** 操作，不需要校准集、不需要 `model_type`、不需要 `quant_type`。 |
| 43 | 45 | ||
| 44 | -当前已注册的 IR 转换边： | 46 | +当前支持的转换： |
| 45 | 47 | ||
| 46 | -| 源 IR | 目标 IR | 说明 | 有损/无损 | | 48 | +| 源格式 | 目标 | 说明 | 有损/无损 | |
| 47 | |-------|---------|------|-----------| | 49 | |-------|---------|------|-----------| |
| 48 | | `FP8_BLOCK` | `FLOAT` | FP8 block 权重反量化为 BF16 | 无损 | | 50 | | `FP8_BLOCK` | `FLOAT` | FP8 block 权重反量化为 BF16 | 无损 | |
| 51 | +| `INT4_PACKED` | `FLOAT` | INT4 packed（分组）权重反量化为 BF16 | 无损 | | ||
| 49 | | `FLOAT` | `W8A8_MXFP8` | BF16/FP16 浮点权重离线 MXFP8 量化 | 有损 | | 52 | | `FLOAT` | `W8A8_MXFP8` | BF16/FP16 浮点权重离线 MXFP8 量化 | 有损 | |
| 53 | +| `FP8_BLOCK` | `W8A8_MXFP8` | 先反量化再量化为 MXFP8 | 有损（后半段量化） | | ||
| 50 | 54 | ||
| 51 | -配置 `route: auto` 时，工具会根据 checkpoint 中张量 dtype 与 `weight_scale_inv` 等字段**自动推断源 IR**，并在 IR 图上选择最短转换路径。例如 FP8 block 权重转 MXFP8 时，实际路径为 `FP8_BLOCK → FLOAT → W8A8_MXFP8`。 | 55 | +工具会根据 checkpoint 中的权重自动识别源格式。 |
| 52 | 56 | ||
| 53 | ### 步骤 2：建立推荐配置 | 57 | ### 步骤 2：建立推荐配置 |
| 54 | 58 | ||
| 55 | -**操作**：下面给出三个最常见转换场景的推荐配置。如果目标模型已有同族转换示例（在 `convert/` 目录下），优先复用。 | 59 | +**操作**：下面给出三个最常见转换场景的推荐配置。如果目标模型已有同族转换示例，优先复用。 |
| 56 | 60 | ||
| 57 | **场景 A：FP8 block → BF16（HF 无损反量化）** | 61 | **场景 A：FP8 block → BF16（HF 无损反量化）** |
| 58 | 62 | ||
| @@ -98,7 +102,7 @@ spec: | |||
| 98 | workers: 8 | 102 | workers: 8 |
| 99 | ``` | 103 | ``` |
| 100 | 104 | ||
| 101 | -**场景 C：FP8 block → W8A8_MXFP8（自动路由串联）** | 105 | +**场景 C：FP8 block → W8A8_MXFP8** |
| 102 | 106 | ||
| 103 | ```yaml | 107 | ```yaml |
| 104 | apiversion: modelslim_convert | 108 | apiversion: modelslim_convert |
| @@ -119,48 +123,73 @@ spec: | |||
| 119 | part_file_size: 4 | 123 | part_file_size: 4 |
| 120 | ``` | 124 | ``` |
| 121 | 125 | ||
| 122 | -> 以上三个场景的完整示例配置可在 `convert/` 目录下找到，可直接复用或按需修改。 | 126 | +完整示例配置： |
| 123 | 127 | ||
| 124 | -**参考配置示例**（文档目录下提供的参考配置）： | 128 | +| 转换场景 | 配置 | |
| 129 | +|---------|------| | ||
| 130 | +| BF16 → W8A8_MXFP8 | [qwen3_8b_bf16_to_mxfp8.yaml](./qwen3_8b_bf16_to_mxfp8.yaml) | | ||
| 131 | +| FP8 block → W8A8_MXFP8 | [qwen3_8b_fp8_to_mxfp8.yaml](./qwen3_8b_fp8_to_mxfp8.yaml) | | ||
| 132 | +| FP8 block → BF16（HF 格式） | [qwen3_8b_fp8_to_bf16.yaml](./qwen3_8b_fp8_to_bf16.yaml) | | ||
| 133 | +| INT4 packed → BF16 | [kimi_k2_5_int4_per_group_to_bf16.yaml](./kimi_k2_5_int4_per_group_to_bf16.yaml) | | ||
| 125 | 134 | ||
| 126 | -| 转换场景 | 配置路径 | | 135 | +<a id="步骤-3执行转换命令"></a> |
| 127 | -|---------|---------| | ||
| 128 | -| BF16 → W8A8_MXFP8 | `convert/qwen3_8b_bf16_to_mxfp8.yaml` | | ||
| 129 | -| FP8 block → W8A8_MXFP8 | `convert/qwen3_8b_fp8_to_mxfp8.yaml` | | ||
| 130 | -| FP8 block → BF16（HF 格式） | `convert/qwen3_8b_fp8_to_bf16.yaml` | | ||
| 131 | -| INT4 packed → BF16 | `convert/kimi_k2_5_int4_per_group_to_bf16.yaml` | | ||
| 132 | 136 | ||
| 133 | -### 步骤 3：选择并调整参数 | 137 | +### 步骤 3：执行转换命令 |
| 134 | 138 | ||
| 135 | -**操作**：参数选择按两个层次理解：先确认 `linears.match` 匹配了哪些层、`target` 目标 IR 是否合法；其次调整 `save` 格式、`parallel` 并行度等执行参数。以下列出所有关键配置项。 | 139 | +**操作**：入口与一键量化相同，都是 `msmodelslim quant`，用 `--config` 指定上一步的 YAML。 |
| 136 | 140 | ||
| 137 | -| 配置项 | 含义（原理） | 推荐配置 | 选择与调整建议 | | 141 | +最小可运行命令： |
| 142 | + | ||
| 143 | +```bash | ||
| 144 | +msmodelslim quant \ | ||
| 145 | + --model_path "${MODEL_PATH}" \ | ||
| 146 | + --save_path "${SAVE_PATH}" \ | ||
| 147 | + --config "${CONFIG_PATH}" | ||
| 148 | +``` | ||
| 149 | + | ||
| 150 | +`${MODEL_PATH}` 为源权重目录，`${SAVE_PATH}` 为转换输出目录，`${CONFIG_PATH}` 为上一份 YAML（示例文件或自定义文件均可）。若模型目录含自定义代码且加载时需要执行，再补充 `--trust_remote_code true`。 | ||
| 151 | + | ||
| 152 | +NPU 多卡加速（推荐大模型 / MoE）： | ||
| 153 | + | ||
| 154 | +```bash | ||
| 155 | +msmodelslim quant \ | ||
| 156 | + --model_path "${MODEL_PATH}" \ | ||
| 157 | + --save_path "${SAVE_PATH}" \ | ||
| 158 | + --config "${CONFIG_PATH}" \ | ||
| 159 | + --device npu \ | ||
| 160 | + --device_id 0 1 2 3 | ||
| 161 | +``` | ||
| 162 | + | ||
| 163 | +`--device_id` 指定使用哪些 NPU。CPU 运行时再设 `parallel.workers`。 | ||
| 164 | + | ||
| 165 | +### 步骤 4：选择并调整参数 | ||
| 166 | + | ||
| 167 | +**操作**：先确认转换了哪些层、目标格式和保存格式是否匹配；需要加速时再调并行。 | ||
| 168 | + | ||
| 169 | +`W8A8_MXFP8` 配 `ascend_v1`，`FLOAT` 配 `huggingface`。 | ||
| 170 | + | ||
| 171 | +| 配置项 | 含义 | 推荐配置 | 选择与调整建议 | | ||
| 138 | | --- | --- | --- | --- | | 172 | | --- | --- | --- | --- | |
| 139 | -| `linears.match` | 待转换的线性层模块路径模式，支持 `*` 通配符。仅匹配到的 Linear 权重参与 IR 转换；**未匹配的权重（如 Norm、Embedding、Head 等）会原样拷贝**到输出目录。 | 列出目标模型中所有 Linear 投影层：`q_proj`/`k_proj`/`v_proj`/`o_proj`/`gate_proj`/`up_proj`/`down_proj`。 | 匹配范围过大会尝试转换非 Linear 层（可能失败），过小则某些 Linear 权重保持原格式。建议先查看 checkpoint 的 `model.safetensors.index.json` 确认 key 名，再按层名前缀与投影名写通配符。 | | 173 | +| `linears.match` | 待转换的线性层路径，支持 `*` 通配符。未匹配的权重（Norm、Embedding、Head 等）原样保留。 | 列出目标模型中的 Linear 投影层，如 `q_proj` / `k_proj` / `v_proj` / `o_proj` / `gate_proj` / `up_proj` / `down_proj`。 | 过宽会把 Norm 等也算进去，过窄则部分 Linear 保持原格式。层名以 `model.safetensors.index.json` 为准。 | |
| 140 | -| `linears.target` | 转换目标 IR 类型，决定输出权重的数值格式。当前支持：`FLOAT`（BF16 浮点）、`W8A8_MXFP8`（昇腾 MXFP8）。 | FP8 反量化 → `FLOAT`；昇腾部署 → `W8A8_MXFP8`。 | `target` 必须与 `save.type` 匹配：`W8A8_MXFP8` 必须用 `ascend_v1` 落盘，`FLOAT` 用 `huggingface`。配置校验会检查此项。 | | 174 | +| `linears.target` | 转换目标。常用 `FLOAT`、`W8A8_MXFP8`。 | FP8 / INT4 反量化 → `FLOAT`；昇腾 MXFP8 → `W8A8_MXFP8`。 | `W8A8_MXFP8` 必须配 `ascend_v1`。 | |
| 141 | -| `linears.route` | 源到目标的 IR 转换路径。`auto` 让工具自动推断源 IR 并选择最短路径；显式指定 IR 列表可强制中间步骤（如 `[FP8_BLOCK, FLOAT, W8A8_MXFP8]`）。 | 默认 `auto`，满足绝大多数场景。 | 仅在调试或需要强制中间 IR 时显式指定。显式 route 的每一步都须有已注册的转换边。 | | 175 | +| `save.type` | 保存格式：`ascend_v1`（昇腾）、`huggingface`（HF）。 | `ascend_v1`（MXFP8）；`huggingface`（BF16）。 | 与 `target` 对齐即可。 | |
| 142 | -| `save.type` | 保存格式：`ascend_v1`（昇腾，对应 MXFP8）、`huggingface`/`hf`/`compressed_tensors`（HF 生态，对应 BF16 浮点）。 | `ascend_v1`（目标 IR 为 `W8A8_MXFP8`）；`huggingface`（目标 IR 为 `FLOAT`）。 | 格式与目标 IR 必须严格匹配，配错会导致权重无法被目标框架加载。 | | 176 | +| `save.part_file_size` | 分片大小，单位 GB；`0` 表示不分片。 | 默认 `4`。 | 小模型可设 `0`。 | |
| 143 | -| `save.part_file_size` | 权重分片文件大小，单位 GB；`0` 表示不分片。 | 默认 `4`（4GB 分片）。 | 小模型可设 `0` 不分片，大模型保持 `4` 便于管理超大 checkpoint。 | | 177 | +| `parallel.workers` | CPU 并行 worker 数。NPU 多卡不使用此项。 | 小模型（8B dense）用 `4~8`。 | 越大越快，受内存和磁盘限制。 | |
| 144 | -| `parallel.workers` | 并行 worker 数：`1` 表示单进程组内线程（可配 NPU）；`>1` 表示组间多进程 + 组内线程（CPU，突破 GIL）。 | 小模型（8B dense）用 `4~8`；超大模型或 MoE 可适当增大。 | 此为纯权重离线计算，与校准集/NPU 无关。`workers` 越大，CPU 并行度越高，但受内存带宽和磁盘 I/O 限制。 | | 178 | +| `parallel.max_group_size` | 单个依赖组的最大任务数，超过则拆成多个子组分散到不同进程/卡并行。 | 默认 `null`（不拆分）；MoE 模型可设为约「每层专家任务数 / 卡数」（如 8 卡设为 96 左右）。 | 仅在 MoE 等含大量专家任务的场景下设置，用于缓解大组单进程/单卡计算导致的拖尾与空闲。 | |
| 145 | -| `parallel.worker_device` | worker 运行设备：`cpu` 或 `npu`。 | 默认 `cpu`。 | 纯 CPU 计算即可满足多数场景；仅当权重转换涉及 NPU 算子时才设为 `npu`。 | | ||
| 146 | -| `preprocess` | 权重图预处理，在构建虚拟模块树之前对 checkpoint key 做结构性变换。支持 `rename`（重命名 key）和 `convert`（chunk 拆分 fused 权重 / merge 合并权重）。 | 一般不需要；MoE 模型 fused gate_up_proj 拆分时需配置。 | 仅当 checkpoint 中有 fused 权重（如 `gate_up_proj`）需要拆分为独立投影时才需要。参考 `convert/` 目录下的 MoE 示例。 | | ||
| 147 | -| `defaults.src_format` | 源权重格式；`auto` 由模型适配器/权重目录自动推断。 | 默认 `auto`。 | 一般不需要改。工具会从 checkpoint 中权重 dtype 自动推断。 | | ||
| 148 | -| `defaults.dst_format` | 目标保存格式；与 `save.type` 同义，`save` 为空时回退到此值。 | 默认 `ascendv1`。 | 一般不需要改，直接通过 `save.type` 控制。 | | ||
| 149 | -| `defaults.dst_ir` | 目标 IR 类型；不设置时由目标格式决定。 | 默认 `null`。 | 一般不需要改，直接通过 `linears.target` 控制。 | | ||
| 150 | 179 | ||
| 151 | ### 参数组合与选择顺序 | 180 | ### 参数组合与选择顺序 |
| 152 | 181 | ||
| 153 | -1. **先确定源格式与目标 IR**：`FP8_BLOCK → FLOAT`（无损反量化）还是 `FLOAT → W8A8_MXFP8`（有损量化）或 `FP8_BLOCK → W8A8_MXFP8`（自动路由）。 | 182 | +1. **先确定源格式与目标**：反量化到 `FLOAT`，还是转到 `W8A8_MXFP8`。 |
| 154 | -2. **再固定 `linears.match` 匹配范围**：参考同模型族示例 YAML 的层名模式，通配符写法保持一致。 | 183 | +2. **再写 `linears.match` 和 `save.type`**：层名对齐 checkpoint；MXFP8 用 `ascend_v1`。 |
| 155 | -3. **最后调整并行度和分片大小**：`parallel.workers` 影响转换速度，`part_file_size` 影响输出文件管理。 | 184 | +3. **最后选设备与并行**：NPU 加 `--device npu --device_id ...`；CPU 调 `parallel.workers`；MoE 大模型按需配置 `parallel.max_group_size`。 |
| 156 | 185 | ||
| 157 | -### 步骤 4：根据结果收敛参数方案 | 186 | +### 步骤 5：根据结果收敛参数方案 |
| 158 | 187 | ||
| 159 | **操作**：转换完成后检查输出目录是否包含预期的权重文件，并使用目标推理框架加载进行冒烟测试。 | 188 | **操作**：转换完成后检查输出目录是否包含预期的权重文件，并使用目标推理框架加载进行冒烟测试。 |
| 160 | 189 | ||
| 161 | -- **无损转换**（如 FP8 → BF16）：结果应与原始权重一致，无需精度调优。 | 190 | +- **无损转换**（FP8 / INT4 → BF16）：无需再调转换参数。 |
| 162 | -- **有损转换**（如 BF16 → MXFP8）：若精度不达标，需回到常规量化流程（使用校准集），而非继续调整转换参数。 | 191 | +- **有损转换**（目标为 `W8A8_MXFP8`）：精度不够时应改走带校准集的常规量化。 |
| 163 | -- **MoE 拆分失败**：确认模型 `config.json` 中存在 `num_experts` 字段。 | 192 | +- **MoE 拆分失败**：核对 `config.json` 里的 `num_experts`（也可能在 `text_config` / `language_config` 下）。若权重已经是分开的 `gate_proj` / `up_proj`，不要再配 `preprocess` 拆分，直接写 `match`。 |
| 164 | 193 | ||
| 165 | ## 5. 术语 | 194 | ## 5. 术语 |
| 166 | 195 | ||
| @@ -168,15 +197,12 @@ spec: | |||
| 168 | | --- | --- | --- | | 197 | | --- | --- | --- | |
| 169 | | 权重转换 | 离线、data-free 的权重格式/精度变换 | [权重转换词条](./term_weight_conversion.md) | | 198 | | 权重转换 | 离线、data-free 的权重格式/精度变换 | [权重转换词条](./term_weight_conversion.md) | |
| 170 | | IR | 中间表示，抽象表示张量格式 | [权重转换词条 - 核心原理](./term_weight_conversion.md#3-核心原理) | | 199 | | IR | 中间表示，抽象表示张量格式 | [权重转换词条 - 核心原理](./term_weight_conversion.md#3-核心原理) | |
| 171 | -| PTQ | 训练后量化 | [PTQ 词条](../term_ptq.md) | | ||
| 172 | 200 | ||
| 173 | ## 6. 接口文档列表 | 201 | ## 6. 接口文档列表 |
| 174 | 202 | ||
| 175 | | 接口或能力 | 简述 | 链接 | | 203 | | 接口或能力 | 简述 | 链接 | |
| 176 | | --- | --- | --- | | 204 | | --- | --- | --- | |
| 177 | -| `msmodelslim quant` | 一键量化 CLI 入口与完整命令说明 | [一键量化完整指南](../../../user_guide/usage_one_click_quantization.md) | | 205 | +| `msmodelslim quant` | 命令行入口、参数与权重转换示例 | [msmodelslim quant 命令行](../../../api_reference/cli/msmodelslim_quant.md) | |
| 178 | -| modelslim_convert 配置说明 | `preprocess`/`linears`/`save`/`parallel`/`defaults` 等配置的字段类型、默认值与完整约束 | [modelslim_convert 配置说明](../../../api_reference/config/task/modelslim_convert.md) | | 206 | +| modelslim_convert 配置说明 | `linears` / `save` / `parallel` 等字段说明 | [modelslim_convert 配置说明](../../../api_reference/config/task/modelslim_convert.md) | |
| 179 | | 格式支持矩阵 | 量化格式与存储格式说明 | [格式支持矩阵](../../quantization_format/README.md) | | 207 | | 格式支持矩阵 | 量化格式与存储格式说明 | [格式支持矩阵](../../quantization_format/README.md) | |
| 180 | -| AscendV1 量化结果 | 一键量化生成结果说明 | [一键量化生成结果](../../quantization_format/ascendv1/ascendv1_usage.md) | | 208 | +| AscendV1 量化结果 | AscendV1 落盘结果说明 | [一键量化生成结果](../../quantization_format/ascendv1/ascendv1_usage.md) | |
| 181 | - | ||
| 182 | -> **高阶功能**：如需深度探索 IR 路由、自定义预处理算子、多级串联转换等高级配置，可查阅 [api_reference/config/task 高阶配置文档](https://gitcode.com/Ascend/msmodelslim/blob/master/docs/zh/api_reference/config/task)。入门阶段无需使用这些能力。 | ||