Star207
186
代码
代码
Issues118
Pull Requests100
项目讨论
Wiki
分析
Star207
186
已合并
[Doc] [bugfix]文档 CLI 参数规范化：统一为新命令行规范并补充 --version 参考 #887
chenruijie创建于 7 天前
[Doc] [bugfix]文档 CLI 参数规范化：统一为新命令行规范并补充 --version 参考 #887
已合并
chenruijie创建于 7 天前
从Rigel_Chen/msmodelslimdocs-fix合入到Ascend/msmodelslimmaster
共 39 个文件变更+91-88
Mdocs/en/developer_guide/integrating_models.md+1-1
@@ -177,7 +177,7 @@ msmodelslim quant --model_path ${MODEL_PATH} \
177 --device npu \177 --device npu \
178 --model_type ${MODEL_TYPE} \178 --model_type ${MODEL_TYPE} \
179 --config ${CONFIG_PATH} \179 --config ${CONFIG_PATH} \
180- --trust_remote_code False180+ --trust_remote_code false
181```181```
182 182 
183- For details about the usage and parameters, see [Quick Quantization Guide](../feature_guide/quick_quantization_v1/usage.md).183- For details about the usage and parameters, see [Quick Quantization Guide](../feature_guide/quick_quantization_v1/usage.md).
Mdocs/en/developer_guide/integrating_multimodal_understanding_model.md+1-1
@@ -547,7 +547,7 @@ msmodelslim quant --model_path ${MODEL_PATH} \
547 --device npu \547 --device npu \
548 --model_type ${MODEL_TYPE} \548 --model_type ${MODEL_TYPE} \
549 --config ${CONFIG_PATH} \549 --config ${CONFIG_PATH} \
550- --trust_remote_code True550+ --trust_remote_code true
551```551```
552 552 
553**Parameter remarks:**553**Parameter remarks:**
Mdocs/en/feature_guide/auto_precision_tuning/usage.md+3-3
@@ -109,9 +109,9 @@ To control the log level or configure the storage path for the "best practice li
109| model_path | Specifies the model path. | Yes | Type: `str`. |109| model_path | Specifies the model path. | Yes | Type: `str`. |
110| save_path | Specifies the storage path for the tuning results. | Yes | Type: `str`. |110| save_path | Specifies the storage path for the tuning results. | Yes | Type: `str`. |
111| config | Specifies the path to the tuning configuration file. | Yes | 1. Type: `str`.<br>2. The path must be a complete file path.<br>3. The configuration file must be in YAML format. For details about the configuration protocol, see Automatic Tuning Configuration Protocols. For a sample configuration, see [example](example).|111| config | Specifies the path to the tuning configuration file. | Yes | 1. Type: `str`.<br>2. The path must be a complete file path.<br>3. The configuration file must be in YAML format. For details about the configuration protocol, see Automatic Tuning Configuration Protocols. For a sample configuration, see [example](example).|
112-| device | Specifies the quantization device. | No | 1. Type: `str`.<br>2. Example values: `'npu'`, `'npu:0,1,2,3'`, `'cpu'`<br>3. Default value: `'npu'` (single device).<br>4. When multiple devices are specified (such as, `'npu:0,1,2,3'`), the system can start distributed layer-wise quantization (DP layer-wise). For details about the algorithm support scope and configuration method, see [Layer-wise and DP Layer-wise Quantization](../quick_quantization_v1/usage.md#layer-wise-and-dp-layer-wise-quantization).|112+| device | Specifies the quantization device. | No | 1. Type: `str`.<br>2. Example values: `'npu'`, `'npu --device_id 0 1 2 3'`, `'cpu'`<br>3. Default value: `'npu'` (single device).<br>4. When multiple devices are specified (such as, `'npu --device_id 0 1 2 3'`), the system can start distributed layer-wise quantization (DP layer-wise). For details about the algorithm support scope and configuration method, see [Layer-wise and DP Layer-wise Quantization](../quick_quantization_v1/usage.md#layer-wise-and-dp-layer-wise-quantization).|
113| model_type | Specifies the model name. | No | 1. Type: `str`.<br>2. Default value: `default`.<br>3. The value is case-sensitive. For details, see [Foundation Model Support Matrix](../../model_support/foundation_model_support_matrix.md).|113| model_type | Specifies the model name. | No | 1. Type: `str`.<br>2. Default value: `default`.<br>3. The value is case-sensitive. For details, see [Foundation Model Support Matrix](../../model_support/foundation_model_support_matrix.md).|
114-| timeout | Specifies the tuning timeout duration. | No | 1. Type: `str`.<br>2. Format: `D`, `H`, or `DH`.<br>3. Examples: `'1D'`, `'2H'`, and `'3D4H'`.<br>4. Default value: `None` (no timeout limit).|114+| timeout | Specifies the tuning timeout duration. | No | 1. Type: `int` (seconds).<br>2. Examples: `7200` (2 hours), `3600` (1 hour).<br>3. Legacy duration strings such as `'1D'`, `'2H'`, and `'3D4H'` are also accepted.<br>4. Default value: `None` (no timeout limit).|
115| trust_remote_code | Specifies whether to trust custom code.| No | 1. Type: `bool`. Default value: `False`.<br>2. Setting this parameter to `True` enables the execution of custom code, which may pose security risks. Ensure the loaded custom code file is secure. |115| trust_remote_code | Specifies whether to trust custom code.| No | 1. Type: `bool`. Default value: `False`.<br>2. Setting this parameter to `True` enables the execution of custom code, which may pose security risks. Ensure the loaded custom code file is secure. |
116| h, help | Displays help information for command-line options.| No | - |116| h, help | Displays help information for command-line options.| No | - |
117 117 
@@ -120,7 +120,7 @@ To control the log level or configure the storage path for the "best practice li
120The following example shows how to use the automatic tuning feature to tune the Qwen3-32B model:120The following example shows how to use the automatic tuning feature to tune the Qwen3-32B model:
121 121 
122``` bash122``` bash
123-msmodelslim tune --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --config ${CONFIG} --device npu --model_type Qwen3-32B --trust_remote_code True123+msmodelslim tune --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --config ${CONFIG} --device npu --model_type Qwen3-32B --trust_remote_code true
124```124```
125 125 
126After you run the command, the system automatically attempts different quantization configurations based on the accuracy requirements specified in the configuration file, and evaluates the quantized model until a quantization solution that meets the accuracy requirements is found or the maximum number of iterations or timeout duration is reached.126After you run the command, the system automatically attempts different quantization configurations based on the accuracy requirements specified in the configuration file, and evaluates the quantized model until a quantization solution that meets the accuracy requirements is found or the maximum number of iterations or timeout duration is reached.
Mdocs/en/feature_guide/quick_quantization_v1/debug_mode.md+3-3
@@ -35,7 +35,7 @@ msmodelslim quant \
35 --device npu \35 --device npu \
36 --model_type Qwen2.5-7B-Instruct \36 --model_type Qwen2.5-7B-Instruct \
37 --quant_type w8a8 \37 --quant_type w8a8 \
38- --trust_remote_code True \38+ --trust_remote_code true \
39 --debug39 --debug
40```40```
41 41 
@@ -50,7 +50,7 @@ msmodelslim quant \
50 --device npu --device_id 0 1 2 3 \50 --device npu --device_id 0 1 2 3 \
51 --model_type Qwen2.5-7B-Instruct \51 --model_type Qwen2.5-7B-Instruct \
52 --quant_type w8a8 \52 --quant_type w8a8 \
53- --trust_remote_code True \53+ --trust_remote_code true \
54 --debug54 --debug
55```55```
56 56 
@@ -65,7 +65,7 @@ msmodelslim quant \
65 --device npu \65 --device npu \
66 --model_type ${MODEL_TYPE} \66 --model_type ${MODEL_TYPE} \
67 --config ${CONFIG_PATH} \67 --config ${CONFIG_PATH} \
68- --trust_remote_code True \68+ --trust_remote_code true \
69 --debug69 --debug
70```70```
71 71 
Mdocs/en/feature_guide/quick_quantization_v1/usage.md+6-6
@@ -28,7 +28,7 @@ Quick quantization is designed for users of all experience levels. It integrates
28There are two ways to perform quick quantization:28There are two ways to perform quick quantization:
29 29 
301. **Method 1 (recommended)**: Use this method for mainstream models already supported by the tool where no special quantization requirements exist. After you specify the `quant_type` parameter, the tool automatically applies the optimal configuration from the best practices library. For details, see [Quantization Configuration Protocol](#quantization-configuration-protocol).301. **Method 1 (recommended)**: Use this method for mainstream models already supported by the tool where no special quantization requirements exist. After you specify the `quant_type` parameter, the tool automatically applies the optimal configuration from the best practices library. For details, see [Quantization Configuration Protocol](#quantization-configuration-protocol).
31-2. **Method 2**: Use this method if a model or quantization strategy is not yet in the best practices library, or if you have specific custom requirements. After you specify the `config_path` parameter, the tool applies the custom quantization settings in your configuration file. For details, see [Quantization Configuration Protocol](#quantization-configuration-protocol).31+2. **Method 2**: Use this method if a model or quantization strategy is not yet in the best practices library, or if you have specific custom requirements. After you specify the `config` parameter, the tool applies the custom quantization settings in your configuration file. For details, see [Quantization Configuration Protocol](#quantization-configuration-protocol).
32 32 
33## Preparations33## Preparations
34 34 
@@ -71,10 +71,10 @@ After the command is executed, the system matches the optimal configuration from
71|-------------------|-----------|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|71|-------------------|-----------|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
72| model_path | Specifies the model path. | Yes | Type: `str`. |72| model_path | Specifies the model path. | Yes | Type: `str`. |
73| save_path | Specifies the save path for quantized weights. | Yes | Type: `str`. |73| save_path | Specifies the save path for quantized weights. | Yes | Type: `str`. |
74-| device | Specifies the quantization device. | No | 1. Type: `str`.<br>2. Example values: `'npu'`, `'npu:0,1,2,3'`, `'cpu'`<br>3. Default value: `'npu'` (single device).<br>4. If distributed layer-wise quantization is enabled and multiple devices are specified (such as `'npu:0,1,2,3'`), the system initiates data parallelism (DP) layer-wise quantization. Ensure the specified algorithm supports distributed execution. For details, see [Layer-wise and DP Layer-wise Quantization](#layer-wise-and-dp-layer-wise-quantization). |74+| device | Specifies the quantization device. | No | 1. Type: `str`.<br>2. Example values: `'npu'`, `'npu --device_id 0 1 2 3'`, `'cpu'`<br>3. Default value: `'npu'` (single device).<br>4. If distributed layer-wise quantization is enabled and multiple devices are specified (such as `'npu --device_id 0 1 2 3'`), the system initiates data parallelism (DP) layer-wise quantization. Ensure the specified algorithm supports distributed execution. For details, see [Layer-wise and DP Layer-wise Quantization](#layer-wise-and-dp-layer-wise-quantization). |
75| model_type | Specifies the model name. | Yes | 1. Type: `str`.<br>2. The value is case-sensitive. For details, see [Foundation Model Support Matrix](../../model_support/foundation_model_support_matrix.md). |75| model_type | Specifies the model name. | Yes | 1. Type: `str`.<br>2. The value is case-sensitive. For details, see [Foundation Model Support Matrix](../../model_support/foundation_model_support_matrix.md). |
76-| config_path | Specifies the configuration path. | Mutually exclusive with `quant_type` | 1. Type: `str`.<br>2. Configuration file format: YAML.<br>3. msModelSlim supports only verified configurations from the best practices library. Users are responsible for the results of custom configurations. For details, see [Quantization Configuration Protocol](#quantization-configuration-protocol).<br> 4. After `config_path` is specified, the `tag` parameter becomes invalid. |76+| config | Specifies the configuration path. | Mutually exclusive with `quant_type` | 1. Type: `str`.<br>2. Configuration file format: YAML.<br>3. msModelSlim supports only verified configurations from the best practices library. Users are responsible for the results of custom configurations. For details, see [Quantization Configuration Protocol](#quantization-configuration-protocol).<br> 4. After `config` is specified, the `tag` parameter becomes invalid. |
77-| quant_type | Specifies the quantization type. | Mutually exclusive with `config_path`| Valid values: `w4a8`, `w4a8c8`, `w8a8`, `w8a8s`, `w8a8c8`, `w8a16`, and `w16a16s`. For details, see [Foundation Model Support Matrix](../../model_support/foundation_model_support_matrix.md). |77+| quant_type | Specifies the quantization type. | Mutually exclusive with `config`| Valid values: `w4a8`, `w4a8c8`, `w8a8`, `w8a8s`, `w8a8c8`, `w8a16`, and `w16a16s`. For details, see [Foundation Model Support Matrix](../../model_support/foundation_model_support_matrix.md). |
78| tag | Specifies the scenario tag for verification. | No | 1. Type: `str`.<br> 2. The value is case-insensitive. Multiple tags are supported and must be separated by spaces. This allows you to explicitly specify a scenario.<br> 3. Currently, two types of tags are supported, and one scenario can be specified for each type: inference engine (such as `MindIE`, `vLLM-Ascend`, and `SGLang`) and hardware form (such as `Atlas_A2_Inference`, `Atlas_A3_Inference`, `Atlas_A2_Training`, `Atlas_A3_Training`, `Atlas_300I_Duo`, `Ascend_950`, and `CPU`).<br> 4. If no verified configuration for the current scenario is found, the system interacts with you to confirm whether to use the quantization configuration that matches the `quant_type` or `model_type`. |78| tag | Specifies the scenario tag for verification. | No | 1. Type: `str`.<br> 2. The value is case-insensitive. Multiple tags are supported and must be separated by spaces. This allows you to explicitly specify a scenario.<br> 3. Currently, two types of tags are supported, and one scenario can be specified for each type: inference engine (such as `MindIE`, `vLLM-Ascend`, and `SGLang`) and hardware form (such as `Atlas_A2_Inference`, `Atlas_A3_Inference`, `Atlas_A2_Training`, `Atlas_A3_Training`, `Atlas_300I_Duo`, `Ascend_950`, and `CPU`).<br> 4. If no verified configuration for the current scenario is found, the system interacts with you to confirm whether to use the quantization configuration that matches the `quant_type` or `model_type`. |
79| debug | Specifies whether to enable the debug mode.| No| 1. Type: Boolean. Default value: `False`.<br>2. After this mode is enabled, the quantization context is automatically saved to the `save_path/debug_info` directory for troubleshooting and algorithm analysis. For details, see the [Debug Mode User Guide](debug_mode.md). |79| debug | Specifies whether to enable the debug mode.| No| 1. Type: Boolean. Default value: `False`.<br>2. After this mode is enabled, the quantization context is automatically saved to the `save_path/debug_info` directory for troubleshooting and algorithm analysis. For details, see the [Debug Mode User Guide](debug_mode.md). |
80| trust_remote_code | Specifies whether to trust custom code.| No | 1. Type: Boolean. Default value: `False`.<br>2. Setting this parameter to `True` enables the execution of custom code, which may pose security risks. Ensure the loaded custom code file is secure. |80| trust_remote_code | Specifies whether to trust custom code.| No | 1. Type: Boolean. Default value: `False`.<br>2. Setting this parameter to `True` enables the execution of custom code, which may pose security risks. Ensure the loaded custom code file is secure. |
@@ -93,7 +93,7 @@ msmodelslim quant \
93 --device npu \93 --device npu \
94 --model_type Qwen2.5-7B-Instruct \94 --model_type Qwen2.5-7B-Instruct \
95 --quant_type w8a8 \95 --quant_type w8a8 \
96- --trust_remote_code True96+ --trust_remote_code true
97```97```
98 98 
99where99where
@@ -126,7 +126,7 @@ msmodelslim quant \
126 --device npu --device_id 0 1 2 3 \126 --device npu --device_id 0 1 2 3 \
127 --model_type ${MODEL_TYPE} \127 --model_type ${MODEL_TYPE} \
128 --quant_type w8a8 \128 --quant_type w8a8 \
129- --trust_remote_code True129+ --trust_remote_code true
130```130```
131 131 
132**Note**: Before configuring DP layer-wise quantization, ensure the specified algorithm supports distributed execution. For details, see [Layer-wise and DP Layer-wise Quantization](#layer-wise-and-dp-layer-wise-quantization).132**Note**: Before configuring DP layer-wise quantization, ensure the specified algorithm supports distributed execution. For details, see [Layer-wise and DP Layer-wise Quantization](#layer-wise-and-dp-layer-wise-quantization).
Mdocs/en/feature_guide/sensitive_layer_analysis/analyze_api_usage.md+1-1
@@ -244,7 +244,7 @@ msmodelslim analyze \
244 --metrics kurtosis \244 --metrics kurtosis \
245 --calibration_dataset ${calib_dataset} \245 --calibration_dataset ${calib_dataset} \
246 --top_k 15 \246 --top_k 15 \
247- --trust_remote_code False247+ --trust_remote_code false
248```248```
249 249 
250### Output Description250### Output Description
Mdocs/en/getting_started/quantization_quick_start.md+2-2
@@ -60,7 +60,7 @@ For details about the parameters, see [Quick Quantization Parameters](../feature
60Quantize the Qwen2.5-7B-Instruct model in w8a8 mode by using the quick quantization feature:60Quantize the Qwen2.5-7B-Instruct model in w8a8 mode by using the quick quantization feature:
61 61 
62```bash62```bash
63-msmodelslim quant --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --device npu --device_id 0 1 --model_type Qwen2.5-7B-Instruct --quant_type w8a8 --trust_remote_code True63+msmodelslim quant --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --device npu --device_id 0 1 --model_type Qwen2.5-7B-Instruct --quant_type w8a8 --trust_remote_code true
64```64```
65 65 
66where66where
@@ -110,7 +110,7 @@ python3 example/Qwen/quant_qwen.py \
110 --w_bit 8 \110 --w_bit 8 \
111 --a_bit 8 \111 --a_bit 8 \
112 --device_type npu \112 --device_type npu \
113- --trust_remote_code True113+ --trust_remote_code true
114```114```
115 115 
116**Notes**:116**Notes**:
Mdocs/en/model_support/foundation_model_support_matrix.md+1-1
@@ -9,7 +9,7 @@
9- Because newer versions of the Qwen series have been released with more powerful capabilities, the Qwen1.5-14B/32B/72B models have exceeded the maintenance period. Old models in this series will be sunset, and maintenance support for the quantization modes of their live-network versions will be discontinued.9- Because newer versions of the Qwen series have been released with more powerful capabilities, the Qwen1.5-14B/32B/72B models have exceeded the maintenance period. Old models in this series will be sunset, and maintenance support for the quantization modes of their live-network versions will be discontinued.
10 10 
11```bash11```bash
12-msmodelslim quant --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --device npu --model_type ${MODEL_TYPE} --quant_type ${QUANT_TYPE} --trust_remote_code True12+msmodelslim quant --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --device npu --model_type ${MODEL_TYPE} --quant_type ${QUANT_TYPE} --trust_remote_code true
13```13```
14 14 
15- For best practices not marked with "quick quantization", read the best practices page of the corresponding model type. Execute the command in the subdirectory of the model type within the [example](https://gitcode.com/Ascend/msmodelslim/tree/master/example) directory, such as [DeepSeek](https://gitcode.com/Ascend/msmodelslim/tree/master/example/DeepSeek) or [Qwen3](https://gitcode.com/Ascend/msmodelslim/tree/master/example/Qwen).15- For best practices not marked with "quick quantization", read the best practices page of the corresponding model type. Execute the command in the subdirectory of the model type within the [example](https://gitcode.com/Ascend/msmodelslim/tree/master/example) directory, such as [DeepSeek](https://gitcode.com/Ascend/msmodelslim/tree/master/example/DeepSeek) or [Qwen3](https://gitcode.com/Ascend/msmodelslim/tree/master/example/Qwen).
Mdocs/zh/api_reference/cli/msmodelslim_analyze.md+1-0
@@ -43,6 +43,7 @@ msmodelslim analyze attn_head --model_type <model_type> --model_path <model_path
43| `--log_level` | 无 | `string` | 单值 | 可选 | `info` | `debug`、`info`、`warning`、`error` | 日志级别。 |43| `--log_level` | 无 | `string` | 单值 | 可选 | `info` | `debug`、`info`、`warning`、`error` | 日志级别。 |
44| `-v` / `--verbose` | 无 | `bool` | 不带值开关 | 可选 | 关闭 | 传入即启用 | 提高输出详细程度（等价 `--log_level debug`）。 |44| `-v` / `--verbose` | 无 | `bool` | 不带值开关 | 可选 | 关闭 | 传入即启用 | 提高输出详细程度（等价 `--log_level debug`）。 |
45| `-q` / `--quiet` | 无 | `bool` | 不带值开关 | 可选 | 关闭 | 传入即启用 | 抑制非错误输出（等价 `--log_level error`）。 |45| `-q` / `--quiet` | 无 | `bool` | 不带值开关 | 可选 | 关闭 | 传入即启用 | 抑制非错误输出（等价 `--log_level error`）。 |
46+| `-V` / `--version` | 无 | `bool` | 不带值开关 | 可选 | 关闭 | 传入即启用 | 显示版本信息后退出（顶层全局参数，可在任意子命令后使用，如 `msmodelslim analyze --version`）。 |
46 47 
47位置参数：48位置参数：
48 49 
Mdocs/zh/api_reference/cli/msmodelslim_quant.md+1-0
@@ -38,6 +38,7 @@ msmodelslim quant [--model_type <model_type>] --model_path <model_path> --save_p
38| `--log_level` | 无 | `string` | 单值 | 可选 | `info` | `debug`、`info`、`warning`、`error` | 日志级别。 |38| `--log_level` | 无 | `string` | 单值 | 可选 | `info` | `debug`、`info`、`warning`、`error` | 日志级别。 |
39| `-v` / `--verbose` | 无 | `bool` | 不带值开关 | 可选 | 关闭 | 传入即启用 | 提高输出详细程度（等价 `--log_level debug`）。 |39| `-v` / `--verbose` | 无 | `bool` | 不带值开关 | 可选 | 关闭 | 传入即启用 | 提高输出详细程度（等价 `--log_level debug`）。 |
40| `-q` / `--quiet` | 无 | `bool` | 不带值开关 | 可选 | 关闭 | 传入即启用 | 抑制非错误输出（等价 `--log_level error`）。 |40| `-q` / `--quiet` | 无 | `bool` | 不带值开关 | 可选 | 关闭 | 传入即启用 | 抑制非错误输出（等价 `--log_level error`）。 |
41+| `-V` / `--version` | 无 | `bool` | 不带值开关 | 可选 | 关闭 | 传入即启用 | 显示版本信息后退出（顶层全局参数，可在任意子命令后使用，如 `msmodelslim quant --version`）。 |
41 42 
42## 4. 参数关系43## 4. 参数关系
43 44 
Mdocs/zh/api_reference/cli/msmodelslim_tune.md+5-4
@@ -17,7 +17,7 @@ msmodelslim tune --model_path <model_path> --save_path <save_path> --config <con
17- 尖括号内为需替换的值，方括号内为可选参数。17- 尖括号内为需替换的值，方括号内为可选参数。
18- `--model_path`、`--save_path`、`--config` 为必选参数。18- `--model_path`、`--save_path`、`--config` 为必选参数。
19- `--config` 是必选的调优 YAML 路径；与一键量化命令的 `--config` 同名，但语义不同（一键量化的 `--config` 可选）。19- `--config` 是必选的调优 YAML 路径；与一键量化命令的 `--config` 同名，但语义不同（一键量化的 `--config` 可选）。
20-- `--timeout` 为时长字符串，如 `2H`、`3D4H`。20+- `--timeout` 为整数秒（如 `7200` 表示 2 小时）；兼容遗留时长字符串如 `2H`、`3D4H`。
21- `--trust_remote_code` 是可选值布尔参数：不带值传入即开启（等价 `true`），或跟 `true`/`false`（大小写不敏感，兼容遗留 `True`/`False`、`yes`/`no`、`on`/`off`）。21- `--trust_remote_code` 是可选值布尔参数：不带值传入即开启（等价 `true`），或跟 `true`/`false`（大小写不敏感，兼容遗留 `True`/`False`、`yes`/`no`、`on`/`off`）。
22- 本命令无位置参数。本语法摘要用于说明参数结构，不作为可复制命令；可复制命令见「使用示例」。22- 本命令无位置参数。本语法摘要用于说明参数结构，不作为可复制命令；可复制命令见「使用示例」。
23 23 
@@ -31,11 +31,12 @@ msmodelslim tune --model_path <model_path> --save_path <save_path> --config <con
31| `--config` | 无 | `string` | 单值 | 必选 | 无 | 可读 YAML 文件路径 | 调优配置 YAML，含 `strategy` 与 `evaluation` 字段。 |31| `--config` | 无 | `string` | 单值 | 必选 | 无 | 可读 YAML 文件路径 | 调优配置 YAML，含 `strategy` 与 `evaluation` 字段。 |
32| `--device` | 无 | `string` | 单值 | 可选 | `npu` | `npu`、`cpu` | 运行设备类型；多卡索引请用 `--device_id` 指定。 |32| `--device` | 无 | `string` | 单值 | 可选 | `npu` | `npu`、`cpu` | 运行设备类型；多卡索引请用 `--device_id` 指定。 |
33| `--device_id` | 无 | `list` | 一次接收多个值，空格分隔 | 可选 | 无 | 非负整数列表，如 `0` 或 `0 1 2 3` | 设备索引，用于指定多个 NPU 设备。 |33| `--device_id` | 无 | `list` | 一次接收多个值，空格分隔 | 可选 | 无 | 非负整数列表，如 `0` 或 `0 1 2 3` | 设备索引，用于指定多个 NPU 设备。 |
34-| `--timeout` | 无 | `string` | 单值 | 可选 | 无（不限时） | 形如 `1D2H30M15S`，单位固定顺序 D/H/M/S，可省略任意一段（如 `1D2H`、`30M`、`10S`），至少含一个单位，字母大写 | 调优墙钟超时；到达超时时间后停止本次调优。 |34+| `--timeout` | 无 | `int`（秒） | 单值 | 可选 | 无（不限时） | 整数秒，如 `7200`（2 小时）、`3600`（1 小时）；兼容遗留时长字符串（如 `1D2H30M15S`，单位固定顺序 D/H/M/S） | 调优墙钟超时；到达超时时间后停止本次调优。 |
35| `--trust_remote_code` | 无 | `bool` | 可选值（不带值传入即开启，或跟 `true`/`false`） | 可选 | `false` | `true`/`false`（大小写不敏感；兼容 `True`/`False`、`yes`/`no`、`on`/`off`） | 是否信任并执行模型目录中的自定义 Python 代码；仅在确认代码来源可信时开启。 |35| `--trust_remote_code` | 无 | `bool` | 可选值（不带值传入即开启，或跟 `true`/`false`） | 可选 | `false` | `true`/`false`（大小写不敏感；兼容 `True`/`False`、`yes`/`no`、`on`/`off`） | 是否信任并执行模型目录中的自定义 Python 代码；仅在确认代码来源可信时开启。 |
36| `--log_level` | 无 | `string` | 单值 | 可选 | `info` | `debug`、`info`、`warning`、`error` | 日志级别。 |36| `--log_level` | 无 | `string` | 单值 | 可选 | `info` | `debug`、`info`、`warning`、`error` | 日志级别。 |
37| `-v` / `--verbose` | 无 | `bool` | 不带值开关 | 可选 | 关闭 | 传入即启用 | 提高输出详细程度（等价 `--log_level debug`）。 |37| `-v` / `--verbose` | 无 | `bool` | 不带值开关 | 可选 | 关闭 | 传入即启用 | 提高输出详细程度（等价 `--log_level debug`）。 |
38| `-q` / `--quiet` | 无 | `bool` | 不带值开关 | 可选 | 关闭 | 传入即启用 | 抑制非错误输出（等价 `--log_level error`）。 |38| `-q` / `--quiet` | 无 | `bool` | 不带值开关 | 可选 | 关闭 | 传入即启用 | 抑制非错误输出（等价 `--log_level error`）。 |
39+| `-V` / `--version` | 无 | `bool` | 不带值开关 | 可选 | 关闭 | 传入即启用 | 显示版本信息后退出（顶层全局参数，可在任意子命令后使用，如 `msmodelslim tune --version`）。 |
39 40 
40## 4. 参数关系41## 4. 参数关系
41 42 
@@ -80,12 +81,12 @@ msmodelslim tune \
80 --model_path "${MODEL_PATH}" \81 --model_path "${MODEL_PATH}" \
81 --save_path "${SAVE_PATH}" \82 --save_path "${SAVE_PATH}" \
82 --config "${CONFIG_PATH}" \83 --config "${CONFIG_PATH}" \
83- --timeout 2H \84+ --timeout 7200 \
84 --device npu \85 --device npu \
85 --device_id 0 1 2 386 --device_id 0 1 2 3
86```87```
87 88 
88-`--timeout 2H` 表示最多运行2H；`--device_id 0 1 2 3` 使用4个 NPU 设备。89+`--timeout 7200` 表示最多运行2H；`--device_id 0 1 2 3` 使用4个 NPU 设备。
89 90 
90## 8. 退出码与异常处理91## 8. 退出码与异常处理
91 92 
Mdocs/zh/best_practices/deepseek_v4_pro_w4a8_new_llm_quantization_case.md+2-2
@@ -266,8 +266,8 @@ msmodelslim quant \
266- `--model_path`：原始浮点模型权重目录路径。266- `--model_path`：原始浮点模型权重目录路径。
267- `--save_path`：量化权重保存目录路径。267- `--save_path`：量化权重保存目录路径。
268- `--model_type`：模型类型，固定为 `DeepSeek-V4-Pro`。268- `--model_type`：模型类型，固定为 `DeepSeek-V4-Pro`。
269-- `--config`：量化配置文件路径，直接指定 [deepseek_v4_pro_w4a8.yaml](../../../lab_practice/deepseek_v4/deepseek_v4_pro_w4a8.yaml)，需要根据实际 msmodelslim 的安装路径填写。269+- `--quant_type`：量化策略类型，`w4a8` 表示权重 INT4 + 激活 INT8。
270-- `--device npu --device_id 0 1 2 3 4 5 6 7`：指定 8 张 NPU（`--device` 指定设备类型，`--device_id` 指定设备编号列表）；W4A8 量化算法较复杂，使用多卡可缩短量化耗时。270+- `--device`：指定量化使用的 NPU 设备，W4A8 量化算法较复杂，单卡量化耗时较长，建议使用 8 卡（`npu --device_id 0 1 2 3 4 5 6 7`）进行多卡量化以缩短耗时。
271- `--trust_remote_code`：信任自定义模型代码（请确保代码来源可靠）。271- `--trust_remote_code`：信任自定义模型代码（请确保代码来源可靠）。
272 272 
273DeepSeek-V4-Pro 已在 `model.py` 中设置 `USE_DP_MODE=True`，并在 `model_adapter.py` 中实现分布式同步和 EP 本地专家范围处理，因此无需额外适配即可按上述命令启动多卡量化。量化日志需进一步确认实际出现多卡分布式启动和各 rank 初始化信息。273DeepSeek-V4-Pro 已在 `model.py` 中设置 `USE_DP_MODE=True`，并在 `model_adapter.py` 中实现分布式同步和 EP 本地专家范围处理，因此无需额外适配即可按上述命令启动多卡量化。量化日志需进一步确认实际出现多卡分布式启动和各 rank 初始化信息。
Mdocs/zh/best_practices/kimi_k3_adaptation_case.md+2-2
@@ -34,7 +34,7 @@
34| --- | --- | --- | --- | --- |34| --- | --- | --- | --- | --- |
35| 输入 | 浮点权重 | [Kimi-K3](https://huggingface.co/moonshotai/Kimi-K3) | 权重文件完整 | 下载完成且哈希值匹配 |35| 输入 | 浮点权重 | [Kimi-K3](https://huggingface.co/moonshotai/Kimi-K3) | 权重文件完整 | 下载完成且哈希值匹配 |
36| 交付件 | 模型适配器代码 | [`msmodelslim/model/kimi_k3/`](../../../msmodelslim/model/kimi_k3/) | 适配器需实现量化流水线所需接口 | 命令行指定 `--model_type Kimi-K3` 可命中适配器 |36| 交付件 | 模型适配器代码 | [`msmodelslim/model/kimi_k3/`](../../../msmodelslim/model/kimi_k3/) | 适配器需实现量化流水线所需接口 | 命令行指定 `--model_type Kimi-K3` 可命中适配器 |
37-| 交付件 | 量化最佳实践 | [`lab_practice/kimi_k3/kimi_k3_w4a8.yaml`](../../../lab_practice/kimi_k3/kimi_k3_w4a8.yaml) | 遵循[量化配置协议](../user_guide/usage_quick_quantization.md#5-量化配置协议详解) | 命令行参数 `--config_path` 指定量化配置文件 |37+| 交付件 | 量化最佳实践 | [`lab_practice/kimi_k3/kimi_k3_w4a8.yaml`](../../../lab_practice/kimi_k3/kimi_k3_w4a8.yaml) | 遵循[量化配置协议](../user_guide/usage_quick_quantization.md#5-量化配置协议详解) | 命令行参数 `--config` 指定量化配置文件 |
38| 交付件 | 量化权重目录 | 命令行参数 `--save_path` 指定保存位置 | 遵循[AscendV1 格式](../knowledge_base/quantization_format/ascendv1/ascendv1_usage.md) | 量化权重精度测试达标 |38| 交付件 | 量化权重目录 | 命令行参数 `--save_path` 指定保存位置 | 遵循[AscendV1 格式](../knowledge_base/quantization_format/ascendv1/ascendv1_usage.md) | 量化权重精度测试达标 |
39 39 
40## 4. 操作步骤40## 4. 操作步骤
@@ -130,7 +130,7 @@
130 --device npu --device_id 0 1 2 3 4 5 6 7 \130 --device npu --device_id 0 1 2 3 4 5 6 7 \
131 --model_type Kimi-K3 \131 --model_type Kimi-K3 \
132 --config ${YAML_PATH} \132 --config ${YAML_PATH} \
133- --trust_remote_code True133+ --trust_remote_code true
134 ```134 ```
135 135 
136**输出**：136**输出**：
Mdocs/zh/best_practices/qwen3_32b_w8a8_precision_tuning_case.md+1-1
@@ -57,7 +57,7 @@ msmodelslim quant \
57 --save_path ${SAVE_PATH} \57 --save_path ${SAVE_PATH} \
58 --device npu \58 --device npu \
59 --config ${CONFIG_PATH} \59 --config ${CONFIG_PATH} \
60- --trust_remote_code True60+ --trust_remote_code true
61```61```
62 62 
63**测评命令**：精度测评使用 AISBench 工具完成，使用方法见[AISBench 快速入门](https://github.com/AISBench/benchmark/blob/master/docs/source_zh_cn/get_started/quick_start.md)。本案例使用数据集配置 `aime2025_gen_0_shot_chat_prompt`（AIME25）、`gpqa_gen_0_shot_cot_chat_prompt`（GPQA），数据集说明见 [AIME25](https://github.com/AISBench/benchmark/blob/master/ais_bench/benchmark/configs/datasets/aime2025/README.md)、[GPQA](https://github.com/AISBench/benchmark/blob/master/ais_bench/benchmark/configs/datasets/gpqa/README.md)。63**测评命令**：精度测评使用 AISBench 工具完成，使用方法见[AISBench 快速入门](https://github.com/AISBench/benchmark/blob/master/docs/source_zh_cn/get_started/quick_start.md)。本案例使用数据集配置 `aime2025_gen_0_shot_chat_prompt`（AIME25）、`gpqa_gen_0_shot_cot_chat_prompt`（GPQA），数据集说明见 [AIME25](https://github.com/AISBench/benchmark/blob/master/ais_bench/benchmark/configs/datasets/aime2025/README.md)、[GPQA](https://github.com/AISBench/benchmark/blob/master/ais_bench/benchmark/configs/datasets/gpqa/README.md)。
Mdocs/zh/best_practices/wan2_2_w4a4f4_new_dit_quantization_case.md+1-1
@@ -231,7 +231,7 @@ msmodelslim quant \
231 --device npu \231 --device npu \
232 --model_type Wan2.2-T2V-A14B \232 --model_type Wan2.2-T2V-A14B \
233 --config ${YAML_PATH} \233 --config ${YAML_PATH} \
234- --trust_remote_code True234+ --trust_remote_code true
235```235```
236 236 
237**输出**：量化权重保存至`${SAVE_PATH}`目录，包含双专家量化权重与描述文件。 237**输出**：量化权重保存至`${SAVE_PATH}`目录，包含双专家量化权重与描述文件。
Mdocs/zh/contributing/design/典型模型量化支持特性设计说明书.md+2-2
@@ -991,7 +991,7 @@ GLM-4.7是智谱AI开发的大语言模型，采用Transformer架构。本Use Ca
991 991 
992### 4.7系统外部接口992### 4.7系统外部接口
993 993 
994-**命令行接口**：新增命令行参数支持GLM-4.7模型量化，命令格式：`msmodelslim quant --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --device npu --model_type glm-4.7 --quant_type w8a8 --trust_remote_code True`994+**命令行接口**：新增命令行参数支持GLM-4.7模型量化，命令格式：`msmodelslim quant --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --device npu --model_type glm-4.7 --quant_type w8a8 --trust_remote_code true`
995 995 
996**Python API接口**：新增`quantize_glm47_w8a8()`函数，函数签名：`quantize_glm47_w8a8(model_path: str, config_path: str, output_path: str) -> None`996**Python API接口**：新增`quantize_glm47_w8a8()`函数，函数签名：`quantize_glm47_w8a8(model_path: str, config_path: str, output_path: str) -> None`
997 997 
@@ -1185,7 +1185,7 @@ Qwen2.5-VL模型量化流程包括：配置解析、多模态模型加载、多
1185 1185 
1186### 5.7系统外部接口1186### 5.7系统外部接口
1187 1187 
1188-**命令行接口**：新增命令行参数支持Qwen2.5-VL模型量化，命令格式：`msmodelslim quant --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --device npu --model_type Qwen2.5-VL-7B-Instruct --quant_type w8a8 --trust_remote_code True`1188+**命令行接口**：新增命令行参数支持Qwen2.5-VL模型量化，命令格式：`msmodelslim quant --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --device npu --model_type Qwen2.5-VL-7B-Instruct --quant_type w8a8 --trust_remote_code true`
1189 1189 
1190**Python API接口**：新增`quantize_qwen25vl_7b_w8a8()`函数1190**Python API接口**：新增`quantize_qwen25vl_7b_w8a8()`函数
1191 1191 
Mdocs/zh/knowledge_base/model/README.md+1-1
@@ -9,7 +9,7 @@
9- 因 Qwen 系列推出能力更强的新版本，Qwen1.5-14B/32B/72B 模型已超出维护周期，后续将对该系列老模型实施日落处理，其现网版本量化模式不再提供维护支持。9- 因 Qwen 系列推出能力更强的新版本，Qwen1.5-14B/32B/72B 模型已超出维护周期，后续将对该系列老模型实施日落处理，其现网版本量化模式不再提供维护支持。
10 10 
11```bash11```bash
12-msmodelslim quant --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --device npu --model_type ${MODEL_TYPE} --quant_type ${QUANT_TYPE} --trust_remote_code True12+msmodelslim quant --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --device npu --model_type ${MODEL_TYPE} --quant_type ${QUANT_TYPE} --trust_remote_code true
13```13```
14 14 
15- 未标记“一键量化”的最佳实践请阅读对应模型类别的最佳实践页面并在 [example](https://gitcode.com/Ascend/msmodelslim/tree/master/example) 目录下对应模型类别的子目录中执行命令，如 [DeepSeek](https://gitcode.com/Ascend/msmodelslim/tree/master/example/DeepSeek)、[Qwen3](https://gitcode.com/Ascend/msmodelslim/tree/master/example/Qwen)。15- 未标记“一键量化”的最佳实践请阅读对应模型类别的最佳实践页面并在 [example](https://gitcode.com/Ascend/msmodelslim/tree/master/example) 目录下对应模型类别的子目录中执行命令，如 [DeepSeek](https://gitcode.com/Ascend/msmodelslim/tree/master/example/DeepSeek)、[Qwen3](https://gitcode.com/Ascend/msmodelslim/tree/master/example/Qwen)。
Mdocs/zh/knowledge_base/model/integrating_models.md+1-1
@@ -178,7 +178,7 @@ msmodelslim quant --model_path ${MODEL_PATH} \
178 --device npu \178 --device npu \
179 --model_type ${MODEL_TYPE} \179 --model_type ${MODEL_TYPE} \
180 --config ${CONFIG_PATH} \180 --config ${CONFIG_PATH} \
181- --trust_remote_code False181+ --trust_remote_code false
182```182```
183 183 
184- 详细用法与参数说明请参阅：《[一键量化使用说明](../../user_guide/usage_quick_quantization.md)》184- 详细用法与参数说明请参阅：《[一键量化使用说明](../../user_guide/usage_quick_quantization.md)》
Mdocs/zh/knowledge_base/model/integrating_multimodal_generation_model.md+2-2
@@ -1375,7 +1375,7 @@ msmodelslim quant \
1375 --device npu \1375 --device npu \
1376 --model_type Wan2.2-T2V-A14B \1376 --model_type Wan2.2-T2V-A14B \
1377 --quant_type w8a8f8 \1377 --quant_type w8a8f8 \
1378- --trust_remote_code True1378+ --trust_remote_code true
1379```1379```
1380 1380 
1381**方式二：使用自定义 YAML**：1381**方式二：使用自定义 YAML**：
@@ -1387,7 +1387,7 @@ msmodelslim quant \
1387 --device npu \1387 --device npu \
1388 --model_type Wan2.2-T2V-A14B \1388 --model_type Wan2.2-T2V-A14B \
1389 --config ${CONFIG_PATH} \1389 --config ${CONFIG_PATH} \
1390- --trust_remote_code True1390+ --trust_remote_code true
1391```1391```
1392 1392 
1393请注意`trust_remote_code`为`True`时可能执行浮点模型权重中的代码文件，请确保浮点模型来源安全可靠。其中 `${MODEL_PATH}` 为原始浮点权重路径，`${SAVE_PATH}` 为用户自定义的量化权重保存路径，model_type对应配置为注册的模型名称，`${CONFIG_PATH}` 为YAML配置文件路径。1393请注意`trust_remote_code`为`True`时可能执行浮点模型权重中的代码文件，请确保浮点模型来源安全可靠。其中 `${MODEL_PATH}` 为原始浮点权重路径，`${SAVE_PATH}` 为用户自定义的量化权重保存路径，model_type对应配置为注册的模型名称，`${CONFIG_PATH}` 为YAML配置文件路径。
Mdocs/zh/knowledge_base/model/integrating_multimodal_understanding_model.md+1-1
@@ -547,7 +547,7 @@ msmodelslim quant --model_path ${MODEL_PATH} \
547 --device npu \547 --device npu \
548 --model_type ${MODEL_TYPE} \548 --model_type ${MODEL_TYPE} \
549 --config ${CONFIG_PATH} \549 --config ${CONFIG_PATH} \
550- --trust_remote_code True550+ --trust_remote_code true
551```551```
552 552 
553**参数说明**：553**参数说明**：
Mdocs/zh/knowledge_base/parallel/data_parallelism/data_parallelism_guide.md+1-1
@@ -214,7 +214,7 @@ flowchart LR
214 214 
215**通过条件**：日志出现 `Starting distributed execution with N devices`（N ≥ 2），各 rank 打印 `Rank i/N initialized on device ...`。215**通过条件**：日志出现 `Starting distributed execution with N devices`（N ≥ 2），各 rank 打印 `Rank i/N initialized on device ...`。
216 216 
217-**异常处置**：若日志显示回退单卡（`Number of devices <= 1, falling back to single-device execution`），检查是否用 `--device_id` 传入了多个索引（如 `--device_id 0 1 2 3 4 5 6 7`）。217+**异常处置**：若日志显示回退单卡（`Number of devices <= 1, falling back to single-device execution`），检查是否用 `--device_id` 传入了多个索引（如 `--device_id 0 1 2 3 4 5 6 7`）；多模态 VLM 服务不支持多卡（见适用范围），请确认目标服务为 `modelslim_v1`。
218 218 
219## 6. 验收条件219## 6. 验收条件
220 220 
Mdocs/zh/knowledge_base/ptq/dit/integration_guide_diffusion_transformer_quantization.md+1-1
@@ -544,7 +544,7 @@ msmodelslim quant \
544 --device npu \544 --device npu \
545 --model_type ${MODEL_TYPE} \545 --model_type ${MODEL_TYPE} \
546 --config ${CONFIG_PATH} \546 --config ${CONFIG_PATH} \
547- --trust_remote_code True547+ --trust_remote_code true
548```548```
549 549 
550**验证要点**：550**验证要点**：
Mdocs/zh/knowledge_base/ptq/llm/integration_guide_large_language_model_quantization.md+1-1
@@ -415,7 +415,7 @@ msmodelslim quant \
415 --device npu \415 --device npu \
416 --model_type ${MODEL_TYPE} \416 --model_type ${MODEL_TYPE} \
417 --config ${CONFIG_PATH} \417 --config ${CONFIG_PATH} \
418- --trust_remote_code False418+ --trust_remote_code false
419```419```
420 420 
421**验证要点**：421**验证要点**：
Mdocs/zh/knowledge_base/ptq/vlm/integration_guide_vision_transformer_quantization.md+1-1
@@ -555,7 +555,7 @@ msmodelslim quant \
555 --device npu \555 --device npu \
556 --model_type ${MODEL_TYPE} \556 --model_type ${MODEL_TYPE} \
557 --config ${CONFIG_PATH} \557 --config ${CONFIG_PATH} \
558- --trust_remote_code True558+ --trust_remote_code true
559```559```
560 560 
561**验证要点**：561**验证要点**：
Mdocs/zh/knowledge_base/quantization_algorithms/ra_compress/term_ra_compress.md+4-4
@@ -54,7 +54,7 @@ $$
54### 3.3 关键性质54### 3.3 关键性质
55 55 
56- **仅支持 LLM**：不支持多模态理解（VLM）与多模态生成（文生图 / 文生视频等）模型；请仅对大语言模型使用 `analyze attn_head --metrics ra_compress`。56- **仅支持 LLM**：不支持多模态理解（VLM）与多模态生成（文生图 / 文生视频等）模型；请仅对大语言模型使用 `analyze attn_head --metrics ra_compress`。
57-- **必须使用 `calib_dummy.jsonl`**：须通过 `--calib_dataset calib_dummy.jsonl` 显式指定内置合成校准集（`attn_head` 不再设置默认值）；该文件经 tokenizer 后严格对齐到 2500×4 段边界。使用其他校准集不保证筛选效果。57+- **必须使用 `calib_dummy.jsonl`**：须通过 `--calibration_dataset calib_dummy.jsonl` 显式指定内置合成校准集（`attn_head` 不再设置默认值）；该文件经 tokenizer 后严格对齐到 2500×4 段边界。使用其他校准集不保证筛选效果。
58- **attn_head 粒度**：输出 KV head 粒度的入选列表（每层若干 head 索引），而非层粒度排序。58- **attn_head 粒度**：输出 KV head 粒度的入选列表（每层若干 head 索引），而非层粒度排序。
59- **数据依赖强**：内置 `calib_dummy.jsonl` 满足 tokenize 后总长度 ≥ 10000 tokens；长度不足时段位置偏移无意义、得分被置空。59- **数据依赖强**：内置 `calib_dummy.jsonl` 满足 tokenize 后总长度 ≥ 10000 tokens；长度不足时段位置偏移无意义、得分被置空。
60- **适配器接口可选依赖**：默认匹配 `q_proj` / `k_proj` / `qkv_proj` 命名，若模型命名不同，需在适配器实现 `RaCompressAnalysisInterface`。60- **适配器接口可选依赖**：默认匹配 `q_proj` / `k_proj` / `qkv_proj` 命名，若模型命名不同，需在适配器实现 `RaCompressAnalysisInterface`。
@@ -109,9 +109,9 @@ msmodelslim analyze attn_head \
109 --model_type Qwen2.5-7B-Instruct \109 --model_type Qwen2.5-7B-Instruct \
110 --model_path ${model_path} \110 --model_path ${model_path} \
111 --metrics ra_compress \111 --metrics ra_compress \
112- --calib_dataset calib_dummy.jsonl \112+ --calibration_dataset calib_dummy.jsonl \
113 --device npu \113 --device npu \
114- --trust_remote_code True \114+ --trust_remote_code true \
115 --save_path ./head_result115 --save_path ./head_result
116```116```
117 117 
@@ -177,7 +177,7 @@ class XxxAdapter(RaCompressAnalysisInterface):
177 177 
178### 6.2 使用限制178### 6.2 使用限制
179 179 
180-- **必须**通过 `--calib_dataset calib_dummy.jsonl` 显式指定内置合成校准集；使用其他校准集不保证筛选效果。180+- **必须**通过 `--calibration_dataset calib_dummy.jsonl` 显式指定内置合成校准集；使用其他校准集不保证筛选效果。
181- 目前仅分析 Transformer 自注意力的 Q / K 投影层（或 QKV 融合层）；其他结构不在范围内。181- 目前仅分析 Transformer 自注意力的 Q / K 投影层（或 QKV 融合层）；其他结构不在范围内。
182- 结果不输出敏感度 Score 排序，只输出入选的 head 索引；ratio 目前使用默认常量（14% / 1%），不通过 YAML 配置。182- 结果不输出敏感度 Score 排序，只输出入选的 head 索引；ratio 目前使用默认常量（14% / 1%），不通过 YAML 配置。
183- 仅支持 LLM；不支持多模态理解与多模态生成模型。183- 仅支持 LLM；不支持多模态理解与多模态生成模型。
Mdocs/zh/knowledge_base/quantization_algorithms/ra_compress/usage_ra_compress.md+9-9
@@ -15,7 +15,7 @@
15不适用场景：15不适用场景：
16 16 
17- **多模态理解模型（VLM）** 与 **多模态生成模型**（文生图 / 文生视频等）：`ra_compress` / `analyze attn_head` 当前仅支持大语言模型（LLM）。17- **多模态理解模型（VLM）** 与 **多模态生成模型**（文生图 / 文生视频等）：`ra_compress` / `analyze attn_head` 当前仅支持大语言模型（LLM）。
18-- 未指定或未使用 `--calib_dataset calib_dummy.jsonl`：须显式指定该内置合成校准集；使用其他校准集不保证筛选效果。18+- 未指定或未使用 `--calibration_dataset calib_dummy.jsonl`：须显式指定该内置合成校准集；使用其他校准集不保证筛选效果。
19- 目标 `model_type` 的适配器未实现 `RaCompressAnalysisInterface` 且 Q/K 投影层命名与默认模式不匹配。19- 目标 `model_type` 的适配器未实现 `RaCompressAnalysisInterface` 且 Q/K 投影层命名与默认模式不匹配。
20 20 
21## 2. 流程关系与前置条件21## 2. 流程关系与前置条件
@@ -25,7 +25,7 @@
25**前置条件**：25**前置条件**：
26 26 
27- 已安装兼容版本的 msModelSlim 工具（详见《[msModelSlim 工具安装指南](../../../install_guide/install_guide.md)》）。27- 已安装兼容版本的 msModelSlim 工具（详见《[msModelSlim 工具安装指南](../../../install_guide/install_guide.md)》）。
28-- 命令行须显式指定 `--calib_dataset calib_dummy.jsonl`（`attn_head` 子命令不再为此场景设置默认值）；使用其他校准集不保证效果。28+- 命令行须显式指定 `--calibration_dataset calib_dummy.jsonl`（`attn_head` 子命令不再为此场景设置默认值）；使用其他校准集不保证效果。
29- 若目标模型 Q/K 投影层命名非 `q_proj` / `k_proj` / `qkv_proj`，需在适配器中实现 `RaCompressAnalysisInterface`。29- 若目标模型 Q/K 投影层命名非 `q_proj` / `k_proj` / `qkv_proj`，需在适配器中实现 `RaCompressAnalysisInterface`。
30 30 
31**后续操作**：将产出的 `head.pt` 送入 RA Compress KV cache 压缩量化流程，生成压缩后的模型。31**后续操作**：将产出的 `head.pt` 送入 RA Compress KV cache 压缩量化流程，生成压缩后的模型。
@@ -35,7 +35,7 @@
35| 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 |35| 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 |
36| --- | --- | --- | --- | --- |36| --- | --- | --- | --- | --- |
37| 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被目标 Transformers 版本加载 |37| 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被目标 Transformers 版本加载 |
38-| 输入 | 校准数据集 | 工具内置 `calib_dummy.jsonl` | 须通过 `--calib_dataset calib_dummy.jsonl` 显式指定；使用其他校准集不保证效果 | 命令行已指定且可被加载 |38+| 输入 | 校准数据集 | 工具内置 `calib_dummy.jsonl` | 须通过 `--calibration_dataset calib_dummy.jsonl` 显式指定；使用其他校准集不保证效果 | 命令行已指定且可被加载 |
39| 交付件 | `head.pt` | `--save_path` 指定目录 | dict 序列化 `.pt` 文件，含 `prefix_matching` 与 `copying` 字段 | 文件存在且可被 torch.load 读取 |39| 交付件 | `head.pt` | `--save_path` 指定目录 | dict 序列化 `.pt` 文件，含 `prefix_matching` 与 `copying` 字段 | 文件存在且可被 torch.load 读取 |
40| 交付件 | 入选 head 列表 | 命令行输出 | 每层 KV head 索引列表 | 可读且包含入选 head |40| 交付件 | 入选 head 列表 | 命令行输出 | 每层 KV head 索引列表 | 可读且包含入选 head |
41 41 
@@ -58,7 +58,7 @@ flowchart LR
58**操作**：58**操作**：
59 59 
601. 检查 Q/K 投影层命名：默认匹配 `q_proj`、`k_proj`、`qkv_proj`，若命名不一致，需在模型适配器中实现 `RaCompressAnalysisInterface.get_ra_compress_proj_patterns()`，返回 `{"q": "...", "k": "...", "qkv": "..."}`。601. 检查 Q/K 投影层命名：默认匹配 `q_proj`、`k_proj`、`qkv_proj`，若命名不一致，需在模型适配器中实现 `RaCompressAnalysisInterface.get_ra_compress_proj_patterns()`，返回 `{"q": "...", "k": "...", "qkv": "..."}`。
61-2. **必须**在命令行通过 `--calib_dataset calib_dummy.jsonl` 显式指定内置合成校准集（`attn_head` 子命令不再为此场景设置默认值）。该文件经 tokenizer 后严格对齐到 2500×4 段边界；使用其他校准集不保证筛选效果。61+2. **必须**在命令行通过 `--calibration_dataset calib_dummy.jsonl` 显式指定内置合成校准集（`attn_head` 子命令不再为此场景设置默认值）。该文件经 tokenizer 后严格对齐到 2500×4 段边界；使用其他校准集不保证筛选效果。
62 62 
63接口约定详见《[RA Compress 词条](./term_ra_compress.md)》。63接口约定详见《[RA Compress 词条](./term_ra_compress.md)》。
64 64 
@@ -75,9 +75,9 @@ msmodelslim analyze attn_head \
75 --model_type Qwen2.5-7B-Instruct \75 --model_type Qwen2.5-7B-Instruct \
76 --model_path ${model_path} \76 --model_path ${model_path} \
77 --metrics ra_compress \77 --metrics ra_compress \
78- --calib_dataset calib_dummy.jsonl \78+ --calibration_dataset calib_dummy.jsonl \
79 --device npu \79 --device npu \
80- --trust_remote_code True \80+ --trust_remote_code true \
81 --save_path ./head_result81 --save_path ./head_result
82```82```
83 83 
@@ -88,7 +88,7 @@ msmodelslim analyze attn_head \
88| `attn_head` | KV 注意力头粒度分析（`ra_compress` 为默认 metrics） |88| `attn_head` | KV 注意力头粒度分析（`ra_compress` 为默认 metrics） |
89| `--metrics` | 指定分析算法，取值为 `ra_compress` 时使用本算法 |89| `--metrics` | 指定分析算法，取值为 `ra_compress` 时使用本算法 |
90| `--save_path` | `head.pt` 与结果文件保存目录 |90| `--save_path` | `head.pt` 与结果文件保存目录 |
91-| `--calib_dataset` | **必须**显式指定为 `calib_dummy.jsonl`；使用其他校准集不保证筛选效果 |91+| `--calibration_dataset` | **必须**显式指定为 `calib_dummy.jsonl`；使用其他校准集不保证筛选效果 |
92 92 
93完整参数见《[Attention Head 筛选分析使用指南](../../../user_guide/usage_sensitive_attn_head_analysis.md)》。93完整参数见《[Attention Head 筛选分析使用指南](../../../user_guide/usage_sensitive_attn_head_analysis.md)》。
94 94 
@@ -109,12 +109,12 @@ msmodelslim analyze attn_head \
109## 6. 验收条件109## 6. 验收条件
110 110 
111- 分析命令执行成功，`head.pt` 已生成在 `--save_path` 目录下。111- 分析命令执行成功，`head.pt` 已生成在 `--save_path` 目录下。
112-- 命令行已指定 `--calib_dataset calib_dummy.jsonl`，且 induction heads / echo heads 列表非空。112+- 命令行已指定 `--calibration_dataset calib_dummy.jsonl`，且 induction heads / echo heads 列表非空。
113- `head.pt` 可被后续 RA Compress 压缩量化流程正确读取。113- `head.pt` 可被后续 RA Compress 压缩量化流程正确读取。
114 114 
115## 7. 异常处置115## 7. 异常处置
116 116 
117-- **得分或 head 列表为空**：确认已指定 `--calib_dataset calib_dummy.jsonl`；未使用该内置校准集时效果不保证。117+- **得分或 head 列表为空**：确认已指定 `--calibration_dataset calib_dummy.jsonl`；未使用该内置校准集时效果不保证。
118- **未命中 Q/K 投影层**：目标模型 Q/K 命名与默认模式不匹配。在适配器中实现 `RaCompressAnalysisInterface.get_ra_compress_proj_patterns()`，返回正确的模块名模式。118- **未命中 Q/K 投影层**：目标模型 Q/K 命名与默认模式不匹配。在适配器中实现 `RaCompressAnalysisInterface.get_ra_compress_proj_patterns()`，返回正确的模块名模式。
119- **GQA 分组相关报错**：确认模型 `config.json` 中 `num_attention_heads` 与 `num_key_value_heads` 字段正确，工具会自动按组取 max。119- **GQA 分组相关报错**：确认模型 `config.json` 中 `num_attention_heads` 与 `num_key_value_heads` 字段正确，工具会自动按组取 max。
120 120 
Mdocs/zh/knowledge_base/quantization_format/ascendv1/ascendv1_usage.md+3-3
@@ -23,8 +23,8 @@
23 23 
24| 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 |24| 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 |
25| --- | --- | --- | --- | --- |25| --- | --- | --- | --- | --- |
26-| 输入 | 浮点模型目录 | 本地或 ModelScope/HF | 可被目标 Transformers 版本加载 | `from_pretrained` 可成功加载 |26+| 输入 | 浮点模型目录 | 本地或 ModelScope/HF | 可被目标 Transformers 版本加载 | `from_pretrained` 冒烟通过 |
27-| 输入 | 量化 YAML / 最佳实践 | 最佳实践库或自定义`--config`| 含 `spec.save` 且 `type` 为 `ascendv1_saver` | 字段通过配置协议校验 |27+| 输入 | 量化 YAML / 最佳实践 | 最佳实践库或自定义 `config` | 含 `spec.save` 且 `type` 为 `ascendv1_saver` | 字段通过配置协议校验 |
28| 交付件 | AscendV1 量化权重目录 | `${SAVE_PATH}` | 含 `quant_model_description.json` 与权重 safetensors | 见《[AscendV1](term_ascendv1.md#export-artifacts)》导出产物 |28| 交付件 | AscendV1 量化权重目录 | `${SAVE_PATH}` | 含 `quant_model_description.json` 与权重 safetensors | 见《[AscendV1](term_ascendv1.md#export-artifacts)》导出产物 |
29 29 
30## 4. 流程总览30## 4. 流程总览
@@ -139,7 +139,7 @@ spec:
139 --device npu \139 --device npu \
140 --model_type ${MODEL_TYPE} \140 --model_type ${MODEL_TYPE} \
141 --config ${CONFIG_PATH} \141 --config ${CONFIG_PATH} \
142- --trust_remote_code False142+ --trust_remote_code true
143 ```143 ```
144 144 
1453. 核对 `${SAVE_PATH}` 中至少存在：1453. 核对 `${SAVE_PATH}` 中至少存在：
Mdocs/zh/knowledge_base/quantization_format/compressed_tensors/compressed_tensors_usage.md+3-3
@@ -24,8 +24,8 @@
24 24 
25| 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 |25| 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 |
26| --- | --- | --- | --- | --- |26| --- | --- | --- | --- | --- |
27-| 输入 | 浮点模型目录 | 本地或 ModelScope/HF | 可被目标 Transformers 版本加载 | `from_pretrained` 可成功加载 |27+| 输入 | 浮点模型目录 | 本地或 ModelScope/HF | 可被目标 Transformers 版本加载 | `from_pretrained` 冒烟通过 |
28-| 输入 | 量化 YAML / 最佳实践 | 最佳实践库或自定义 `--config` | 含 `spec.save` 且 `type` 为 `compressed_tensors` | 字段通过配置协议校验 |28+| 输入 | 量化 YAML / 最佳实践 | 最佳实践库或自定义 `config` | 含 `spec.save` 且 `type` 为 `compressed_tensors` | 字段通过配置协议校验 |
29| 交付件 | compressed-tensors 权重目录 | `${SAVE_PATH}` | 含注入 `quantization_config` 的 `config.json` 与 `model*.safetensors` | 见《[compressed-tensors](term_compressed_tensors.md#export-artifacts)》导出产物 |29| 交付件 | compressed-tensors 权重目录 | `${SAVE_PATH}` | 含注入 `quantization_config` 的 `config.json` 与 `model*.safetensors` | 见《[compressed-tensors](term_compressed_tensors.md#export-artifacts)》导出产物 |
30 30 
31## 4. 流程总览31## 4. 流程总览
@@ -114,7 +114,7 @@ spec:
114 --device npu \114 --device npu \
115 --model_type ${MODEL_TYPE} \115 --model_type ${MODEL_TYPE} \
116 --config ${CONFIG_PATH} \116 --config ${CONFIG_PATH} \
117- --trust_remote_code False117+ --trust_remote_code true
118 ```118 ```
119 119 
1203. 核对 `${SAVE_PATH}` 中至少存在：1203. 核对 `${SAVE_PATH}` 中至少存在：
Mdocs/zh/knowledge_base/quantization_format/mindie_sd/mindie_sd_usage.md+1-1
@@ -129,7 +129,7 @@ spec:
129 --device npu \129 --device npu \
130 --model_type ${MODEL_TYPE} \130 --model_type ${MODEL_TYPE} \
131 --config ${CONFIG_PATH} \131 --config ${CONFIG_PATH} \
132- --trust_remote_code False132+ --trust_remote_code true
133 ```133 ```
134 134 
1353. 核对 `${SAVE_PATH}` 中至少存在：1353. 核对 `${SAVE_PATH}` 中至少存在：
Mdocs/zh/quick_start/quantization_quick_start.md+1-1
@@ -189,7 +189,7 @@ fi
189执行以下命令，使用一键量化功能。系统将自动匹配该模型的最佳实践配置，以 W8A8（将模型权重和激活均量化为 8-bit）模式完成量化：189执行以下命令，使用一键量化功能。系统将自动匹配该模型的最佳实践配置，以 W8A8（将模型权重和激活均量化为 8-bit）模式完成量化：
190 190 
191```bash191```bash
192-msmodelslim quant --model_path ~/qwen36_27b_base --save_path ~/qwen36_27b_w8a8 --device npu --model_type Qwen3.6-27B --quant_type w8a8 --trust_remote_code True192+msmodelslim quant --model_path ~/qwen36_27b_base --save_path ~/qwen36_27b_w8a8 --device npu --model_type Qwen3.6-27B --quant_type w8a8 --trust_remote_code true
193```193```
194 194 
195量化耗时约 4 分钟，出现如下输出即表示完成：195量化耗时约 4 分钟，出现如下输出即表示完成：
Mdocs/zh/user_guide/usage_auto_precision_tuning.md+3-3
@@ -109,9 +109,9 @@ msmodelslim tune --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --config ${
109| model_path | 模型路径 | 必选 | 类型：Str |109| model_path | 模型路径 | 必选 | 类型：Str |
110| save_path | 调优结果保存路径 | 必选 | 类型：Str |110| save_path | 调优结果保存路径 | 必选 | 类型：Str |
111| config | 调优配置文件路径 | 必选 | 1. 类型：Str <br>2. 配置文件路径，必须为完整的文件路径 <br>3. 配置文件格式为 YAML，配置协议说明见 《[自动调优配置协议说明](usage_auto_precision_tuning.md)》，示例配置见各策略目录（如 《[Standing High 示例](../knowledge_base/tuning_strategies/standing_high/standing_high.yaml)》） |111| config | 调优配置文件路径 | 必选 | 1. 类型：Str <br>2. 配置文件路径，必须为完整的文件路径 <br>3. 配置文件格式为 YAML，配置协议说明见 《[自动调优配置协议说明](usage_auto_precision_tuning.md)》，示例配置见各策略目录（如 《[Standing High 示例](../knowledge_base/tuning_strategies/standing_high/standing_high.yaml)》） |
112-| device | 量化设备 | 可选 | 1. 类型：Str <br>2. 参考值：'npu','npu:0,1,2,3','cpu' <br>3. 默认值为"npu"（单设备）<br>4. 指定多个设备时（如：'npu:0,1,2,3'），系统可启动分布式逐层量化（DP）。算法支持范围与配置方式详见《[一键量化使用说明](usage_quick_quantization.md#41-逐层量化及分布式逐层量化)》 |112+| device | 量化设备 | 可选 | 1. 类型：Str <br>2. 参考值：'npu','npu --device_id 0 1 2 3','cpu' <br>3. 默认值为"npu"（单设备）<br>4. 指定多个设备时（如：'npu --device_id 0 1 2 3'），系统可启动分布式逐层量化（DP）。算法支持范围与配置方式详见《[一键量化使用说明](usage_quick_quantization.md#41-逐层量化及分布式逐层量化)》 |
113| model_type | 模型名称 | 可选 | 1. 类型：Str <br>2. 默认值为"default" <br>3. 大小写敏感，请参考《[大模型支持矩阵](../knowledge_base/model/README.md)》 |113| model_type | 模型名称 | 可选 | 1. 类型：Str <br>2. 默认值为"default" <br>3. 大小写敏感，请参考《[大模型支持矩阵](../knowledge_base/model/README.md)》 |
114-| timeout | 调优超时时间 | 可选 | 1. 类型：Str <br>2. 格式：`<天数>D`、`<小时数>H` 或 `<天数>D<小时数>H` <br>3. 示例：'1D'、'2H'、'3D4H' <br>4. 默认值：None（无超时限制） |114+| timeout | 调优超时时间 | 可选 | 1. 类型：Int（秒） <br>2. 示例：'7200'（2小时）、'3600'（1小时） <br>3. 兼容遗留时长字符串：'1D'、'2H'、'3D4H' <br>4. 默认值：None（无超时限制） |
115| trust_remote_code | 是否信任自定义代码 | 可选 | 1. 类型：Bool，默认值：False <br>2. 请确保加载的自定义代码文件的安全性，设置为True有安全风险。 |115| trust_remote_code | 是否信任自定义代码 | 可选 | 1. 类型：Bool，默认值：False <br>2. 请确保加载的自定义代码文件的安全性，设置为True有安全风险。 |
116| h, help | 命令行参数帮助信息 | 可选 | - |116| h, help | 命令行参数帮助信息 | 可选 | - |
117 117 
@@ -120,7 +120,7 @@ msmodelslim tune --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --config ${
120例如，使用自动调优功能对 Qwen3-32B 模型进行调优，调优命令如下。120例如，使用自动调优功能对 Qwen3-32B 模型进行调优，调优命令如下。
121 121 
122``` bash122``` bash
123-msmodelslim tune --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --config ${CONFIG} --device npu --model_type Qwen3-32B --trust_remote_code True123+msmodelslim tune --model_path ${MODEL_PATH} --save_path ${SAVE_PATH} --config ${CONFIG} --device npu --model_type Qwen3-32B --trust_remote_code true
124```124```
125 125 
126用户输入命令后，系统将根据配置文件中指定的精度需求，自动尝试不同的量化配置，并对量化后的模型进行评估，直到找到满足精度要求的量化方案或达到最大迭代次数/超时时间。126用户输入命令后，系统将根据配置文件中指定的精度需求，自动尝试不同的量化配置，并对量化后的模型进行评估，直到找到满足精度要求的量化方案或达到最大迭代次数/超时时间。
Mdocs/zh/user_guide/usage_debug_mode.md+3-3
@@ -35,7 +35,7 @@ msmodelslim quant \
35 --device npu \35 --device npu \
36 --model_type Qwen2.5-7B-Instruct \36 --model_type Qwen2.5-7B-Instruct \
37 --quant_type w8a8 \37 --quant_type w8a8 \
38- --trust_remote_code True \38+ --trust_remote_code true \
39 --debug39 --debug
40```40```
41 41 
@@ -50,7 +50,7 @@ msmodelslim quant \
50 --device npu --device_id 0 1 2 3 \50 --device npu --device_id 0 1 2 3 \
51 --model_type Qwen2.5-7B-Instruct \51 --model_type Qwen2.5-7B-Instruct \
52 --quant_type w8a8 \52 --quant_type w8a8 \
53- --trust_remote_code True \53+ --trust_remote_code true \
54 --debug54 --debug
55```55```
56 56 
@@ -65,7 +65,7 @@ msmodelslim quant \
65 --device npu \65 --device npu \
66 --model_type ${MODEL_TYPE} \66 --model_type ${MODEL_TYPE} \
67 --config ${CONFIG_PATH} \67 --config ${CONFIG_PATH} \
68- --trust_remote_code True \68+ --trust_remote_code true \
69 --debug69 --debug
70```70```
71 71 
Mdocs/zh/user_guide/usage_one_click_quantization.md+3-3
@@ -61,7 +61,7 @@ msmodelslim quant \
61 --model_type ${MODEL_TYPE} \ # 已注册或支持矩阵中的模型名，大小写敏感61 --model_type ${MODEL_TYPE} \ # 已注册或支持矩阵中的模型名，大小写敏感
62 --quant_type ${QUANT_TYPE} \ # 量化类型，如 w8a862 --quant_type ${QUANT_TYPE} \ # 量化类型，如 w8a8
63 --tags ${TAG} \ # 场景标签，如 vLLM-Ascend Atlas_A2_Inference63 --tags ${TAG} \ # 场景标签，如 vLLM-Ascend Atlas_A2_Inference
64- --trust_remote_code False # 仅可信模型必要时设为 True64+ --trust_remote_code false # 仅可信模型必要时设为 True
65```65```
66 66 
67### 执行前预检67### 执行前预检
@@ -158,7 +158,7 @@ msmodelslim quant \
158 158 
159在命令中添加 `--device` 参数：159在命令中添加 `--device` 参数：
160 160 
161-- **填写**：`npu`（默认，单卡）、`npu:0,1,2,3`（多卡）、`cpu`。161+- **填写**：`npu`（默认，单卡）、`npu --device_id 0 1 2 3`（多卡）、`cpu`。
162- **注意**：指定多张卡时自动启用分布式逐层量化，详见下方"可选：多卡分布式量化"。162- **注意**：指定多张卡时自动启用分布式逐层量化，详见下方"可选：多卡分布式量化"。
163 163 
164**输出**：已指定量化设备的命令。164**输出**：已指定量化设备的命令。
@@ -226,7 +226,7 @@ msmodelslim quant \
226 226 
227- **交互询问场景**：`--tags` 或 `--quant_type` 未命中已验证配置时，工具会询问是否采用推荐配置，确认场景与推荐配置匹配后按提示执行；227- **交互询问场景**：`--tags` 或 `--quant_type` 未命中已验证配置时，工具会询问是否采用推荐配置，确认场景与推荐配置匹配后按提示执行；
228- **量化失败或 OOM**：先排查 NPU 状态（`npu-smi info`）与环境变量 `ASCEND_RT_VISIBLE_DEVICES` 是否指向有效空闲卡；显存不足（OOM）时改用空闲卡，或开启逐层量化、分布式逐层量化；228- **量化失败或 OOM**：先排查 NPU 状态（`npu-smi info`）与环境变量 `ASCEND_RT_VISIBLE_DEVICES` 是否指向有效空闲卡；显存不足（OOM）时改用空闲卡，或开启逐层量化、分布式逐层量化；
229-- **模型加载报错**：确认 transformers 等依赖库版本与支持矩阵要求一致，必要时补充 `--trust_remote_code True`（仅限可信模型）；229+- **模型加载报错**：确认 transformers 等依赖库版本与支持矩阵要求一致，必要时补充 `--trust_remote_code true`（仅限可信模型）；
230- **部署测评后精度异常**：量化权重已完成交付，但部署测评出现 badcase 或输出异常时，进入《[量化推理精度异常定位流程指南](process_quantization_accuracy_anomaly_locating.md)》定位异常位点，并按《[量化精度调优指南](process_quantization_precision_tuning.md)》调优后重新量化。230- **部署测评后精度异常**：量化权重已完成交付，但部署测评出现 badcase 或输出异常时，进入《[量化推理精度异常定位流程指南](process_quantization_accuracy_anomaly_locating.md)》定位异常位点，并按《[量化精度调优指南](process_quantization_precision_tuning.md)》调优后重新量化。
231 231 
232## 8. 案例列表232## 8. 案例列表
Mdocs/zh/user_guide/usage_quick_quantization.md+8-8
@@ -11,7 +11,7 @@ toc_depth: 3
11一键量化提供了两种使用方式：11一键量化提供了两种使用方式：
12 12 
131. **方式1（推荐）**：适用于工具已经支持且用户无特殊量化诉求的主流模型量化场景，可通过指定 `quant_type` 参数，工具在最佳实践库中自动匹配最适合的量化配置进行量化。量化配置请参考[量化配置协议详解](#5-量化配置协议详解)。131. **方式1（推荐）**：适用于工具已经支持且用户无特殊量化诉求的主流模型量化场景，可通过指定 `quant_type` 参数，工具在最佳实践库中自动匹配最适合的量化配置进行量化。量化配置请参考[量化配置协议详解](#5-量化配置协议详解)。
14-2. **方式2**：适用于模型或模型量化方式未收录最佳实践库或用户有特殊量化诉求场景，可通过指定 `config_path` 参数，工具直接使用用户指定的自定义量化配置进行量化。量化配置请参考[量化配置协议详解](#5-量化配置协议详解)。14+2. **方式2**：适用于模型或模型量化方式未收录最佳实践库或用户有特殊量化诉求场景，可通过指定 `config` 参数，工具直接使用用户指定的自定义量化配置进行量化。量化配置请参考[量化配置协议详解](#5-量化配置协议详解)。
15 15 
16## 2. 使用前准备16## 2. 使用前准备
17 17 
@@ -54,10 +54,10 @@ msmodelslim quant [ARGS]
54|-------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|54|-------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
55|model_path|必选| 模型路径。<br>类型：Str。 |55|model_path|必选| 模型路径。<br>类型：Str。 |
56|save_path|必选| 量化权重保存路径。<br>类型：Str。 |56|save_path|必选| 量化权重保存路径。<br>类型：Str。 |
57-|device|可选| 量化设备。<br>1. 类型：Str。 <br>2. 参考值：'npu','npu:0,1,2,3','cpu'。 <br>3. 默认值为"npu"（单设备）。<br>4. 当配置文件启用分布式逐层量化，且指定多个设备时（如：'npu:0,1,2,3'），系统启动DP逐层量化，请确定配置的算法是否支持分布式执行，配置方式及算法支持详见[逐层量化及分布式逐层量化](#41-逐层量化及分布式逐层量化)。 |57+|device|可选| 量化设备。<br>1. 类型：Str。 <br>2. 参考值：'npu','npu --device_id 0 1 2 3','cpu'。 <br>3. 默认值为"npu"（单设备）。<br>4. 当配置文件启用分布式逐层量化，且指定多个设备时（如：'npu --device_id 0 1 2 3'），系统启动DP逐层量化，请确定配置的算法是否支持分布式执行，配置方式及算法支持详见[逐层量化及分布式逐层量化](#41-逐层量化及分布式逐层量化)。 |
58|model_type|必选| 模型名称。<br>1. 类型：Str。 <br>2. 大小写敏感，请参考《[大模型支持矩阵](../knowledge_base/model/README.md)》。 |58|model_type|必选| 模型名称。<br>1. 类型：Str。 <br>2. 大小写敏感，请参考《[大模型支持矩阵](../knowledge_base/model/README.md)》。 |
59-|config_path|与"quant_type"不共存。| 指定配置路径。<br>1. 类型：Str。 <br>2. 配置文件格式为yaml。<br>3. 当前只支持最佳实践库中已验证的配置，若自定义配置，msModelSlim不为量化结果负责。配置指导可参考[量化配置协议详解](#5-量化配置协议详解)。 <br> 4. 用户选用config_path后，tag参数无效。 |59+|config|与"quant_type"不共存。| 指定配置路径。<br>1. 类型：Str。 <br>2. 配置文件格式为yaml。<br>3. 当前只支持最佳实践库中已验证的配置，若自定义配置，msModelSlim不为量化结果负责。配置指导可参考[量化配置协议详解](#5-量化配置协议详解)。 <br> 4. 用户选用config后，tag参数无效。 |
60-|quant_type|与"config_path"不共存| 量化类型。<br>w4a4, w4a8, w4a4c8, w4a4f8, w4a8c8, w8a16, w8a8, w8a8s, w8a8c8, w8a8f8, w4a4f4, w16a16s，请参考《[大模型支持矩阵](../knowledge_base/model/README.md)》。若未找到匹配的最佳实践配置，将与用户交互，询问是否采用推荐配置，详见[命令格式搜索优先级](#31-命令格式)。 |60+|quant_type|与"config"不共存| 量化类型。<br>w4a4, w4a8, w4a4c8, w4a4f8, w4a8c8, w8a16, w8a8, w8a8s, w8a8c8, w8a8f8, w4a4f4, w16a16s，请参考《[大模型支持矩阵](../knowledge_base/model/README.md)》。若未找到匹配的最佳实践配置，将与用户交互，询问是否采用推荐配置，详见[命令格式搜索优先级](#31-命令格式)。 |
61|tag|可选| 校验指定场景标签。<br>1. 类型：Str。<br> 2. 大小写不敏感，支持多个标签，用空格分割；支持用户确定地指定一种场景。<br> 3. 当前支持两类标签，每一类别可指定一种场景：指定使用的推理引擎，包含MindIE、vLLM-Ascend、SGLang等；指定推理用的硬件形态，包含Atlas_A2_Inference、Atlas_A3_Inference、Atlas_A2_Training、Atlas_A3_Training、Atlas_300I_Duo、Ascend_950、CPU等。 <br> 4. 如果未找到已验证当前场景的配置，则与用户交互，询问是否采用匹配 quant_type 或 model_type 的量化配置。 |61|tag|可选| 校验指定场景标签。<br>1. 类型：Str。<br> 2. 大小写不敏感，支持多个标签，用空格分割；支持用户确定地指定一种场景。<br> 3. 当前支持两类标签，每一类别可指定一种场景：指定使用的推理引擎，包含MindIE、vLLM-Ascend、SGLang等；指定推理用的硬件形态，包含Atlas_A2_Inference、Atlas_A3_Inference、Atlas_A2_Training、Atlas_A3_Training、Atlas_300I_Duo、Ascend_950、CPU等。 <br> 4. 如果未找到已验证当前场景的配置，则与用户交互，询问是否采用匹配 quant_type 或 model_type 的量化配置。 |
62|debug|可选| 启用调试模式。<br>1. 类型：Bool，默认值：False。 <br>2. 启用后会在量化完成时自动保存量化过程中的上下文信息到 `save_path/debug_info` 目录，用于问题排查和算法分析，详见《[调试模式使用指南](usage_debug_mode.md)》。 |62|debug|可选| 启用调试模式。<br>1. 类型：Bool，默认值：False。 <br>2. 启用后会在量化完成时自动保存量化过程中的上下文信息到 `save_path/debug_info` 目录，用于问题排查和算法分析，详见《[调试模式使用指南](usage_debug_mode.md)》。 |
63|trust_remote_code|可选| 是否信任自定义代码。<br>1. 类型：Bool，默认值：False。 <br>2. 请确保加载的自定义代码文件的安全性，设置为True有安全风险。 |63|trust_remote_code|可选| 是否信任自定义代码。<br>1. 类型：Bool，默认值：False。 <br>2. 请确保加载的自定义代码文件的安全性，设置为True有安全风险。 |
@@ -76,7 +76,7 @@ msmodelslim quant \
76 --device npu \76 --device npu \
77 --model_type Qwen2.5-7B-Instruct \77 --model_type Qwen2.5-7B-Instruct \
78 --quant_type w8a8 \78 --quant_type w8a8 \
79- --trust_remote_code True79+ --trust_remote_code true
80```80```
81 81 
82其中：82其中：
@@ -86,7 +86,7 @@ msmodelslim quant \
86- `--device npu` 指定使用单卡NPU进行量化86- `--device npu` 指定使用单卡NPU进行量化
87- `--model_type Qwen2.5-7B-Instruct` 指定模型类型，需与支持矩阵中的名称一致87- `--model_type Qwen2.5-7B-Instruct` 指定模型类型，需与支持矩阵中的名称一致
88- `--quant_type w8a8` 指定量化类型为W8A888- `--quant_type w8a8` 指定量化类型为W8A8
89-- `--trust_remote_code True` 信任远程代码，部分模型需要开启此选项89+- `--trust_remote_code true` 信任远程代码，部分模型需要开启此选项
90 90 
91#### 3.3.2 示例2：使用配置文件参数91#### 3.3.2 示例2：使用配置文件参数
92 92 
@@ -122,7 +122,7 @@ msmodelslim quant \
122 --device npu --device_id 0 1 2 3 \122 --device npu --device_id 0 1 2 3 \
123 --model_type ${MODEL_TYPE} \123 --model_type ${MODEL_TYPE} \
124 --quant_type w8a8 \124 --quant_type w8a8 \
125- --trust_remote_code True125+ --trust_remote_code true
126```126```
127 127 
128其中：128其中：
@@ -132,7 +132,7 @@ msmodelslim quant \
132- `--device npu --device_id 0 1 2 3` 指定使用4张NPU卡进行分布式量化132- `--device npu --device_id 0 1 2 3` 指定使用4张NPU卡进行分布式量化
133- `${MODEL_TYPE}` 为模型类型，需与支持矩阵中的名称一致133- `${MODEL_TYPE}` 为模型类型，需与支持矩阵中的名称一致
134- `--quant_type w8a8` 指定量化类型为W8A8134- `--quant_type w8a8` 指定量化类型为W8A8
135-- `--trust_remote_code True` 信任远程代码135+- `--trust_remote_code true` 信任远程代码
136 136 
137>[!NOTE]137>[!NOTE]
138>138>
Mdocs/zh/user_guide/usage_sensitive_attn_analysis.md+1-1
@@ -65,7 +65,7 @@ msmodelslim analyze attn \
65 --calibration_dataset ${CALIB_DATASET} \ # LLM：.json/.jsonl；VLM：图文目录如 calibImages65 --calibration_dataset ${CALIB_DATASET} \ # LLM：.json/.jsonl；VLM：图文目录如 calibImages
66 --top_k ${TOPK} \ # TopK 数量，默认 1566 --top_k ${TOPK} \ # TopK 数量，默认 15
67 --device npu \ # 分析设备：npu、cpu；多卡另加 --device_id 0 1 2 367 --device npu \ # 分析设备：npu、cpu；多卡另加 --device_id 0 1 2 3
68- --trust_remote_code False # 默认 False；仅可信模型必要时设为 True68+ --trust_remote_code false # 默认 false；仅可信模型必要时设为 true
69```69```
70 70 
71### 步骤 1：确认推荐指标71### 步骤 1：确认推荐指标
Mdocs/zh/user_guide/usage_sensitive_attn_head_analysis.md+6-6
@@ -63,9 +63,9 @@ msmodelslim analyze attn_head \
63 --model_type ${MODEL_TYPE} \ # 已注册或支持矩阵中的模型名，大小写敏感63 --model_type ${MODEL_TYPE} \ # 已注册或支持矩阵中的模型名，大小写敏感
64 --model_path ${MODEL_PATH} \ # 浮点权重目录64 --model_path ${MODEL_PATH} \ # 浮点权重目录
65 --metrics ra_compress \ # 分析指标，固定为 ra_compress65 --metrics ra_compress \ # 分析指标，固定为 ra_compress
66- --calib_dataset calib_dummy.jsonl \ # 须显式指定为 calib_dummy.jsonl（合成重复段校准集，tokenize 后总长度 ≥ 10000）66+ --calibration_dataset calib_dummy.jsonl \ # 须显式指定为 calib_dummy.jsonl（合成重复段校准集，tokenize 后总长度 ≥ 10000）
67 --device npu \ # 分析设备：npu、cpu；多卡另加 --device_id 0 1 2 367 --device npu \ # 分析设备：npu、cpu；多卡另加 --device_id 0 1 2 3
68- --trust_remote_code False \ # 默认 False；仅可信模型必要时设为 True68+ --trust_remote_code false \ # 默认 false；仅可信模型必要时设为 true
69 --save_path ${SAVE_PATH} # 可选；指定则保存 head.pt，不指定仅打印到控制台69 --save_path ${SAVE_PATH} # 可选；指定则保存 head.pt，不指定仅打印到控制台
70```70```
71 71 
@@ -93,7 +93,7 @@ msmodelslim analyze attn_head \
93 93 
941. 从 [ModelScope](https://www.modelscope.cn/)、[Hugging Face](https://huggingface.co/) 或团队内部模型存放位置获取完整权重到本地目录；具体下载方式以对应社区或仓库文档为准。941. 从 [ModelScope](https://www.modelscope.cn/)、[Hugging Face](https://huggingface.co/) 或团队内部模型存放位置获取完整权重到本地目录；具体下载方式以对应社区或仓库文档为准。
952. 核对目录含配置、权重分片及 tokenizer 等附属文件。若官方页面提供文件校验值（如 MD5/SHA256）或明确的版本号/提交号，与本地下载结果比对一致即可。952. 核对目录含配置、权重分片及 tokenizer 等附属文件。若官方页面提供文件校验值（如 MD5/SHA256）或明确的版本号/提交号，与本地下载结果比对一致即可。
96-3. 准备校准集：`ra_compress` 算法要求校准数据 tokenize 后总长度 ≥ **10000 tokens**（即 `DUMMY_INPUT_LENGTH=2500` × `REPET_TIMES=4` 段重复）。工具内置 [`calib_dummy.jsonl`](../../../lab_calib/) 已满足此要求，`attn_head` 子命令须在命令行显式指定 `--calib_dataset calib_dummy.jsonl`（该子命令不再为此场景设置默认值）。也可使用自有校准集，但须确保 tokenize 后的 token 总数 ≥ 10000，否则分析将跳过分数计算并返回空结果。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**输出**：浮点模型目录与校准集路径（或工具内置校准集短名称）。
99 99 
@@ -122,7 +122,7 @@ msmodelslim analyze attn_head \
122 122 
123- 已完成步骤 1～3 的指标、权重与模型适配确认。123- 已完成步骤 1～3 的指标、权重与模型适配确认。
124- `trust_remote_code` 默认 `False`；仅当模型必须执行仓库内自定义代码且来源可信时设为 `True`。124- `trust_remote_code` 默认 `False`；仅当模型必须执行仓库内自定义代码且来源可信时设为 `True`。
125-- `--calib_dataset` 须显式指定为 `calib_dummy.jsonl`（`attn_head` 子命令不再为此场景设置默认值）；如使用自定义校准集，请确认 token 长度满足要求（见步骤 2）。125+- `--calibration_dataset` 须显式指定为 `calib_dummy.jsonl`（`attn_head` 子命令不再为此场景设置默认值）；如使用自定义校准集，请确认 token 长度满足要求（见步骤 2）。
126 126 
127**操作**：127**操作**：
128 128 
@@ -133,9 +133,9 @@ msmodelslim analyze attn_head \
133 --model_type Qwen2.5-7B-Instruct \133 --model_type Qwen2.5-7B-Instruct \
134 --model_path /data/models/Qwen/Qwen2.5-7B-Instruct/ \134 --model_path /data/models/Qwen/Qwen2.5-7B-Instruct/ \
135 --metrics ra_compress \135 --metrics ra_compress \
136- --calib_dataset calib_dummy.jsonl \136+ --calibration_dataset calib_dummy.jsonl \
137 --device npu \137 --device npu \
138- --trust_remote_code True \138+ --trust_remote_code true \
139 --save_path ./head_result139 --save_path ./head_result
140```140```
141 141 
Mdocs/zh/user_guide/usage_sensitive_layer_analysis.md+1-1
@@ -65,7 +65,7 @@ msmodelslim analyze layer \
65 --calibration_dataset ${CALIB_DATASET} \ # LLM：.json/.jsonl；VLM：图文目录如 calibImages65 --calibration_dataset ${CALIB_DATASET} \ # LLM：.json/.jsonl；VLM：图文目录如 calibImages
66 --top_k ${TOPK} \ # TopK 数量，默认 1566 --top_k ${TOPK} \ # TopK 数量，默认 15
67 --device npu \ # 分析设备：npu、cpu；多卡另加 --device_id 0 1 2 367 --device npu \ # 分析设备：npu、cpu；多卡另加 --device_id 0 1 2 3
68- --trust_remote_code False # 默认 False；仅可信模型必要时设为 True68+ --trust_remote_code false # 默认 false；仅可信模型必要时设为 true
69```69```
70 70 
71### 步骤 1：确认推荐指标71### 步骤 1：确认推荐指标
Mdocs/zh/user_guide/usage_sensitive_linear_analysis.md+1-1
@@ -66,7 +66,7 @@ msmodelslim analyze linear \
66 --calibration_dataset ${CALIB_DATASET} \ # LLM：.json/.jsonl；VLM：图文目录如 calibImages66 --calibration_dataset ${CALIB_DATASET} \ # LLM：.json/.jsonl；VLM：图文目录如 calibImages
67 --top_k ${TOPK} \ # TopK 数量，默认 15；成组模块一并输出时实际条数可能 ≥ top_k67 --top_k ${TOPK} \ # TopK 数量，默认 15；成组模块一并输出时实际条数可能 ≥ top_k
68 --device npu \ # 分析设备：npu、cpu；多卡另加 --device_id 0 1 2 368 --device npu \ # 分析设备：npu、cpu；多卡另加 --device_id 0 1 2 3
69- --trust_remote_code False # 默认 False；仅可信模型必要时设为 True69+ --trust_remote_code false # 默认 false；仅可信模型必要时设为 true
70```70```
71 71 
72### 步骤 1：确认推荐指标72### 步骤 1：确认推荐指标
Mdocs/zh/user_guide/usage_weight_quantization.md+2-2
@@ -69,7 +69,7 @@ msmodelslim quant \
69 --device_id 0 \ # 设备索引；多卡示例：--device_id 0 1 2 369 --device_id 0 \ # 设备索引；多卡示例：--device_id 0 1 2 3
70 --model_type ${MODEL_TYPE} \ # 已注册或支持矩阵中的模型名，大小写敏感70 --model_type ${MODEL_TYPE} \ # 已注册或支持矩阵中的模型名，大小写敏感
71 --config ${CONFIG_PATH} \ # 本指南步骤 3 编写的量化配置 YAML71 --config ${CONFIG_PATH} \ # 本指南步骤 3 编写的量化配置 YAML
72- --trust_remote_code False # 仅可信模型必要时设为 True72+ --trust_remote_code false # 仅可信模型必要时设为 true
73```73```
74 74 
75### 执行前预检75### 执行前预检
@@ -195,7 +195,7 @@ msmodelslim quant \
195 --device_id 0 \195 --device_id 0 \
196 --model_type ${MODEL_TYPE} \196 --model_type ${MODEL_TYPE} \
197 --config ${CONFIG_PATH} \197 --config ${CONFIG_PATH} \
198- --trust_remote_code False198+ --trust_remote_code false
199```199```
200 200 
201参数说明：201参数说明：