【Docs】Qwen3-32B W8A8精度调优案例按通用案例模板重构-MindStudio-ModelSlim-AtomGit

已合并

【Docs】Qwen3-32B W8A8精度调优案例按通用案例模板重构 #807

tanxiangyuu创建于 14 天前从tanxiangyuu/msmodelslim： master 合入到 Ascend/msmodelslim： master

【Docs】Qwen3-32B W8A8精度调优案例按通用案例模板重构 #807

已合并

tanxiangyuu创建于 14 天前

从tanxiangyuu/msmodelslim master合入到Ascend/msmodelslim master

共 2 个文件变更+252-202

Mdocs/zh/best_practices/qwen3_32b_w8a8_precision_tuning_case.md+252-200

	@@ -1,288 +1,340 @@
1	-# Qwen3-32B W8A8精度调优案例	1	+# Qwen3-32B W8A8精度调优案例
2		2
3	-## 概述	3	+## 1. 案例背景
4		4
5	-### 案例目标	5	+本案例针对 Qwen3-32B 模型的 W8A8 量化场景：初始采用全静态量化（per-channel/per-tensor）搭配 Smooth Quant 离群值抑制算法，量化后模型对话出现乱码、无法正常使用。通过系统化调优，将量化模型在 AIME25 数据集上的精度从不可用提升至 70.00%，并分别在 GPQA 数据集上验证了校准集调整与量化回退两类备选优化手段的效果。
6		6
7	-目标：对Qwen3-32B模型进行W8A8量化，使量化模型相比浮点模型的精度损失控制在可控范围以内。	7	+本案例实际覆盖[《量化精度调优指南》](../user_guide/process_quantization_precision_tuning.md)的全部 5 个步骤：确认精度问题可信 → 调整离群值抑制算法 → 调整量化策略 → 调整校准集 → 量化回退。
8		8
9	-初始状态：使用全静态量化（per-channel/per-tensor）搭配Smooth Quant离群值抑制算法，量化后模型对话出现乱码，无法正常使用。	9	+关联流程：[《量化精度调优指南》](../user_guide/process_quantization_precision_tuning.md)
10		10
11	-## 前期准备	11	+## 2. 环境与版本
12		12
13	-安装 msModelSlim 工具，详情请参见[《msModelSlim工具安装指南》](../install_guide/install_guide.md)。	13	+\| 项 \| 版本或配置 \|
		14	+\| --- \| --- \|
		15	+\| 产品形态 \| A3（Atlas A3 系列推理产品，不限定：调优方法与结论不限硬件形态，本案例中的精度与量化时间数据在该形态上实测获得） \|
		16	+\| CANN \| 9.0.0 \|
		17	+\| PyTorch \| 2.10 \|
		18	+\| TorchNPU \| 2.10（与 CANN、PyTorch 配套） \|
		19	+\| vLLM Ascend \| 0.22.1rc1（推理部署环境） \|
		20	+\| transformers \| 4.51.0 \|
		21	+\| 运行镜像 \| `m.daocloud.io/quay.io/ascend/vllm-ascend:v0.22.1rc1-a3` \|
		22	+\| 其他依赖 \| msModelSlim（本案例工具，安装见《[msModelSlim工具安装指南](../install_guide/install_guide.md)》）；AISBench（精度测评）；Qwen3-32B 模型权重与 tokenizer \|
14		23
15	-## 调优过程	24	+本次前置事实：
		25	+
		26	+- msModelSlim 已安装，`msmodelslim` 命令可执行。
		27	+- Qwen3-32B 浮点模型已准备，可在目标推理引擎上加载并复现原始精度。
		28	+- AIME25、GPQA 测评数据集已就绪，可在 AISBench 上完成测评。
		29	+- 已预设量化精度要求，本案例以量化模型 AIME25 精度达到 70.00% 作为达成标准。
		30	+
		31	+## 3. 输入和交付件
		32	+
		33	+\| 类型 \| 名称 \| 来源或保存位置 \| 格式或约束 \| 验收方式 \|
		34	+\| --- \| --- \| --- \| --- \| --- \|
		35	+\| 输入 \| Qwen3-32B 浮点模型 \| 本地保存的模型权重目录 \| 含模型配置、权重分片及类别所需附属文件（如 tokenizer、config 等） \| 文件齐全；若官方提供校验值或版本号，与本地一致 \|
		36	+\| 输入 \| 量化配置 YAML \| 本案例各步骤给出的配置文件（每组实验一个） \| modelslim_v1 协议 YAML \| 可被 `msmodelslim quant` 加载执行 \|
		37	+\| 输入 \| 校准集 \| 仓库内置校准集目录，格式参考[`msmodelslim/lab_calib/mix_calib.jsonl`](../../../lab_calib/mix_calib.jsonl)、[`qwen3_cot_w4a4.json`](../../../lab_calib/qwen3_cot_w4a4.json) \| JSON/JSONL，样本与任务、语言匹配 \| 样本可被模型 tokenizer 预处理，量化流程可正常读取 \|
		38	+\| 输入 \| 测评集与 badcase \| AIME25、GPQA 测评集及 AISBench 测评结果 \| 与任务匹配的问答格式 \| 浮点模型在测评集上可复现原始精度 \|
		39	+\| 交付件 \| 最终量化权重目录 \| 用户指定的输出目录 \| 符合所选导出格式 \| 文件齐全；符合所选导出格式约定 \|
		40	+\| 交付件 \| 精度测评报告 \| AISBench 测评结果目录（按时间戳自动生成） \| 浮点与量化对比结果 \| 与预设精度要求逐项比对 \|
		41	+
		42	+## 4. 操作步骤
		43	+
		44	+### 命令约定
		45	+
		46	+量化命令：本案例所有量化实验统一使用以下命令执行，路径参数按实际环境填写：
		47	+
		48	+```bash
		49	+# 按实际环境填写以下路径
		50	+MODEL_PATH=/path/to/qwen3-32b # 浮点模型权重目录
		51	+SAVE_PATH=/path/to/save # 量化产物输出目录
		52	+CONFIG_PATH=/path/to/config.yaml # 量化配置 YAML
		53	+
		54	+msmodelslim quant \
		55	+ --model_type Qwen3-32B \
		56	+ --model_path ${MODEL_PATH} \
		57	+ --save_path ${SAVE_PATH} \
		58	+ --device npu \
		59	+ --config_path ${CONFIG_PATH} \
		60	+ --trust_remote_code True
		61	+```
		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)。
16		64
17	### 步骤1：确认精度问题可信	65	### 步骤1：确认精度问题可信
18		66
19	-在开始调优前，首先排除环境干扰，确保问题真实存在：	67	+目标：排除环境干扰，确认精度问题真实存在。
20		68
21	-- 推理引擎验证：浮点模型在目标推理引擎上能正常复现原始精度。	69	+输入：浮点模型、初始配置量化权重、AIME25 测评数据集、目标推理引擎（如 vLLM Ascend）及指向其服务的 AISBench 模型配置。
22	-- 测评结果检查：量化模型测评输出存在明显异常（对话乱码），确认为量化精度问题。
23	-- 确定波动范围：AIME25评测数据集当前精度损失异常。
24		70
25	-### 步骤2：调整离群值抑制算法（首要步骤）	71	+操作：
26		72
27	-初始配置使用Smooth Quant算法导致对话中出现乱码，按照调优策略，依次尝试不同的离群值抑制算法：	73	+1. 将浮点模型部署到目标推理引擎，按命令约定使用 AISBench 完成 AIME25 基线测评（工作目录与后续实验区分），确认可复现原始精度。
		74	+2. 将初始量化模型（Smooth Quant 产物）部署后执行同样的 AIME25 测评，检查输出：确认乱码不是上下文截断、超时等非量化问题导致（必要时抽查推理日志中的生成内容）。
		75	+3. 结合 AIME25 数据集精度波动范围，判断当前精度损失异常，确认为量化引入。
		76	+
		77	+输出：浮点模型 AIME25 基线测评报告；确认精度问题由量化引入，量化模型乱码输出样例。
		78	+
		79	+记录：浮点模型 AIME25 基线精度、量化模型乱码输出日志路径。
		80	+
		81	+下一步：步骤1 确认浮点基线正常、乱码问题由量化引入（Smooth Quant 初始配置精度远未达标），进入步骤2 调整离群值抑制算法。
		82	+
		83	+### 步骤2：调整离群值抑制算法（关键步骤）
		tanxiangyuu9 天前配置给出链接，不用写的太细，具体算法链接
		84	+
		85	+目标：通过切换离群值抑制算法消除对话乱码并提升精度。
		86	+
		87	+输入：5 组离群值抑制算法配置、浮点模型、AIME25 测评数据集。
		88	+
		89	+操作：
		90	+
		91	+1. 生成配置并量化：在量化配置 YAML 的 `process` 中依次替换离群值抑制处理器（算法、对称性、`alpha` 参数），得到 5 组实验配置（均搭配相同的 `linear_quant` 静态量化与 `save` 段），逐一执行量化命令（`--config_path` 与 `--save_path` 按算法区分）。各组算法配置要点如下（完整参数见算法文档）：
		92	+
		93	+ a. Smooth Quant（初始配置）：alpha 0.5、对称。详见[《Smooth Quant 算法》](../knowledge_base/quantization_algorithms/smooth_quant/smooth_quant.md)。
		94	+
		95	+ b. Iterative Smooth（对称）：对称/alpha:0.5 与对称/alpha:0.9 两组仅 `alpha` 参数不同，其余配置相同（4 类子图）。详见[《Iterative Smooth 算法》](../knowledge_base/quantization_algorithms/iterative_smooth/iterative_smooth.md)。
		96	+
		97	+ c. Iterative Smooth（非对称/alpha:0.5）：非对称仅支持 `norm-linear` 子图。
		98	+
		99	+ d. Flex Smooth Quant：alpha/beta 缺省自动搜索。详见[《Flex Smooth Quant 算法》](../knowledge_base/quantization_algorithms/flex_smooth_quant/flex_smooth_quant.md)。
		100	+
		101	+ 算法对比见[离群值抑制算法](../knowledge_base/quantization_algorithms/README.md#离群值抑制算法)。
		102	+
		103	+2. 部署测评：将每组量化产物部署到目标推理引擎，执行测评命令（AIME25数据集），记录精度与量化耗时。
		104	+3. 汇总对比：汇总各算法的精度与量化时间，选择综合最优方案。
28		105
29	\| 离群值抑制算法 \| AIME25 精度（%） \| 量化时间（s） \| 备注 \|	106	\| 离群值抑制算法 \| AIME25 精度（%） \| 量化时间（s） \| 备注 \|
30	\|---------------\|-----------------\|--------------\|------\|	107	\|---------------\|-----------------\|--------------\|------\|
31	\| Smooth Quant \| 对话乱码 \| 326 \| 初始配置，精度下降明显 \|	108	\| Smooth Quant \| 对话乱码 \| 326 \| 初始配置，精度下降明显 \|
32	-\| Iterative Smooth（对称/alpha:0.5） \| 53.33 \| 324 \| 相比Smooth Quant有改善，但精度仍不足 \|	109	+\| Iterative Smooth（对称/alpha:0.5） \| 3.33 \| 324 \| 存在重复token输出 \|
33	-\| Iterative Smooth（非对称/alpha:0.5） \| 63.33 \| 305 \| 非对称方案精度提升10%，符合预期 \|	110	+\| Iterative Smooth（非对称/alpha:0.5） \| 0 \| 305 \| 输出乱码 \|
34	-\| Iterative Smooth（对称/alpha:0.9） \| 66.67 \| 319 \| 调整alpha参数后精度进一步提升 \|	111	+\| Iterative Smooth（对称/alpha:0.9） \| 63.33 \| 319 \| 精度正常 \|
35	-\| Flex Smooth Quant \| 63.33 \| 1380 \| 精度与Iterative Smooth（非对称/alpha:0.5）相当，但所需时间更长 \|	112	+\| Flex Smooth Quant \| 13.33 \| 1380 \| 存在重复token输出；所需时间明显更长 \|
36		113
37	-调优结果：	114	+输出：5 组量化权重及对应 AIME25 测评报告；确定离群值抑制算法为 Iterative Smooth（对称/alpha:0.9）。
38		115
39	-综合考虑精度和量化时间，最终选择 Iterative Smooth（对称/alpha:0.9）算法，具体分析如下：	116	+记录：上表 5 组配置的精度与量化时间实测数据。对比分析：对称/alpha:0.5（3.33%）、非对称/alpha:0.5（0%）、Flex Smooth Quant（13.33%）在 per-tensor 静态激活量化下均出现重复 token/乱码的严重退化，仅对称/alpha:0.9 精度正常（63.33%），量化时间 319秒，较 Flex Smooth Quant 节省 76.9%。
40		117
41	-1. 精度对比分析：	118	+下一步：步骤2 最优配置（Iterative Smooth 对称/alpha:0.9）AIME25 精度 63.33%，未达到预设精度要求（70.00%），进入步骤3 在固定离群值抑制算法下调整量化策略。
42		119
43	-- Iterative Smooth（对称/alpha:0.9）精度为66.67%，在对称方案中最高。	120	+### 步骤3：调整量化策略（量化算法选择）
		tanxiangyuu9 天前说明步骤之间的衔接原因
44	-- 相比Iterative Smooth（对称/alpha:0.5）的53.33%，精度提升13.34个百分点。
45	-- 虽然Iterative Smooth（非对称/alpha:0.5）精度为63.33%，但对称方案（alpha:0.9）精度为66.67%，已超过非对称方案。
46	-- 相比Flex Smooth Quant的63.33%，精度提升3.34个百分点。
47		121
48	-2. 量化时间对比分析：	122	+目标：在离群值抑制算法确定后，通过切换权重量化方法、激活量化粒度进一步提升精度。
49		123
50	-- Iterative Smooth（对称/alpha:0.9）量化时间为319秒，与Iterative Smooth（对称/alpha:0.5）的324秒相当。	124	+输入：步骤2确定的基础配置（Iterative Smooth（对称/alpha:0.9））、4 组量化策略配置（组合 `minmax`/`ssz` × `per_tensor`/`per_token`）、AIME25 测评数据集。
51	-- 相比Flex Smooth Quant的1380秒，量化时间节省76.9%，效率明显提升。
52		125
53	-最终决策：	126	+操作：
54		127
55	-综合以上分析，Iterative Smooth（对称/alpha:0.9）是当前场景下的最佳选择。	128	+1. 生成配置并量化：在量化配置 YAML 的 `linear_quant` 处理器中，分别修改 `qconfig.act.scope`（`per_tensor`/`per_token`）与 `qconfig.weight.method`（`minmax`/`ssz`），组合出 4 组配置并逐一执行量化命令。`linear_quant` 处理器参数详见[《Linear Quant 算法》](../knowledge_base/quantization_algorithms/linear_quant/linear_quant.md)，量化方法参数详见[MinMax](../knowledge_base/quantization_algorithms/minmax/minmax.md)、[SSZ](../knowledge_base/quantization_algorithms/ssz/ssz.md)。
56		129
57	-### 步骤3：量化算法选择	130	+2. 部署测评：将每组量化产物部署后执行测评命令（AIME25），记录精度与量化耗时。
58	-	131	+3. 汇总对比：对比精度与量化时间，选择综合最优配置。
59	-在确定离群值抑制算法后，优化量化算法配置：
60	-
61	-#### 量化方法对比
62		132
63	\| 权重量化方法 \| 激活量化粒度 \| AIME25 精度（%） \| 量化时间（s） \| 备注 \|	133	\| 权重量化方法 \| 激活量化粒度 \| AIME25 精度（%） \| 量化时间（s） \| 备注 \|
64	\|-------------\|-------------\|----------------\|-------------\|------\|	134	\|-------------\|-------------\|----------------\|-------------\|------\|
65	-\| minmax \| per-tensor（静态量化） \| 66.67 \|319 \| 基础配置（基于步骤2结果） \|	135	+\| minmax \| per-tensor（静态量化） \| 63.33 \| 319 \| 基础配置（基于步骤2结果） \|
66	-\| minmax \| per-token（动态量化） \|80.00 \| 289 \| 激活使用per-token后精度提升13.33个百分点 \|	136	+\| minmax \| per-token（动态量化） \| 70.00 \| 289 \| 激活使用per-token后精度提升6.67个百分点 \|
67	-\| ssz \| per-tensor（静态量化） \| 63.33 \| 408 \| 权重量化使用ssz方法，但静态量化精度下降 \|	137	+\| ssz \| per-tensor（静态量化） \| 66.67 \| 408 \| 静态量化下 ssz 优于 minmax \|
68	-\| ssz \| per-token（动态量化） \| 70.00 \| 348 \| ssz + per-token精度低于minmax+per-token \|	138	+\| ssz \| per-token（动态量化） \| 76.67 \| 348 \| 动态量化下 ssz 优于 minmax，为本次实测最高 \|
69		139
70	-#### 调优结果	140	+输出：4 组量化权重及对应 AIME25 测评报告；确定量化策略为 minmax + per-token（动态量化）。
71		141
72	-综合考虑精度和量化时间，最终选择 minmax + per-token（动态量化）配置，具体分析如下：	142	+记录：上表 4 组配置的精度与量化时间实测数据。对比分析：动态量化整体优于静态量化（minmax 70.00% vs 63.33%，ssz 76.67% vs 66.67%）；ssz + per-token 精度上限最高（76.67%），minmax + per-token（70.00%）达到预设精度要求（70.00%）；量化时间方面 minmax + per-token 最短（289秒，较 ssz + per-token 节省 59 秒，较 minmax + per-tensor 节省 30秒），综合精度与效率选择 minmax + per-token。
73		143
74	-1. 精度对比分析：	144	+下一步：步骤3 达到预设精度要求（70.00%），为展示完整的调优流程并验证校准集调整的效果，进入步骤4。
75		145
76	-- minmax + per-token（动态量化）精度为80.00%，相比minmax + per-tensor（静态量化）的66.67%，精度提升13.33个百分点。	146	+### 步骤4：调整校准集
77	-- ssz + per-tensor（静态量化）精度为63.33%，相比minmax + per-tensor（静态量化）配置下降3.34个百分点，说明ssz方法在该INT8量化场景下效果不如minmax方法。
78	-- ssz + per-token（动态量化）精度为70.00%，低于minmax + per-token（80.00%）10个百分点，说明ssz方法在该INT8动态量化场景下也不如minmax方法。
79		147
80	-2. 量化时间对比分析：	148	+目标：通过校准集优化（加入 badcase 样本）验证对量化精度的提升效果。GPQA 数据集题目数量更多，能够更清晰地展现不同配置间的精度差异。
81		149
82	-- minmax + per-token量化时间为289秒，相比minmax + per-tensor（319秒）节省30秒（9.4%），量化效率提升。	150	+输入：步骤3达到精度要求后的量化配置（本节以 Iterative Smooth + 静态量化作为基准配置，在 GPQA 数据集上验证）、该基准配置的 GPQA 测评结果（含 badcase 样本）、校准集文件、GPQA 测评数据集。
83	-- ssz + per-token量化时间为348秒，比minmax + per-token多59秒（20.4%），量化效率较低。
84		151
85	-3. 综合对比分析：	152	+操作：
86		153
87	-- 精度方面：minmax + per-token精度最高（80.00%），优于ssz + per-token（70.00%）和所有静态量化方案。	154	+1. 校准集优化策略对比：校准集的质量直接影响量化参数的准确性，可按以下策略调整校准集（本案例执行的是最后一行「加入 badcase」策略）：
88	-- 量化时间方面：minmax + per-token量化时间最短（289秒），相比ssz + per-token（348秒）节省59秒（17.0%），相比minmax + per-tensor（319秒）也节省30秒。
89	-- 方法复杂度：minmax方法实现简单，计算速度快；ssz方法通过迭代搜索，计算更复杂，INT8量化优先选择minmax算法。
90		155
91	-最终决策：	156	+ \| 调整策略 \| 具体操作 \| 校准集变化 \| 优化目的 \|
92	-综合以上分析，minmax + per-token（动态量化）在精度和量化时间两个方面达到最佳平衡。minmax + per-token不仅精度最高（80.00%），比ssz + per-token高10个百分点，而且量化时间最短（289秒），比ssz + per-token节省59秒，实现更简单，是当前场景下的最佳选择。相比步骤2的配置（66.67%），精度提升了13.33个百分点（相对提升20%），为后续调优奠定了良好基础。	157	+ \|---------\|---------\|-----------\|---------\|
		158	+ \| 初始校准集 \| 随机样本 \| 少量样本 \| 建立基准配置 \|
		159	+ \| 增加数据量 \| 适当增加样本数量 \| 数量增加 \| 提升量化参数估计的准确性 \|
		160	+ \| 匹配应用场景 \| 使用与任务、语言匹配的数据替换 \| 构成变化 \| 使校准数据更贴近实际应用场景 \|
		161	+ \| 平衡数据分布 \| 从多个数据集抽取样本混合 \| 构成变化 \| 提升数据分布的多样性和均衡性 \|
		162	+ \| 剔除异常数据 \| 移除导致精度下降的异常样本 \| 数量减少 \| 减少异常样本对量化参数的干扰 \|
		163	+ \| 加入badcase \| 加入模型在该数据集上的badcase样本 \| 数量增加 \| 帮助量化模型学习困难样本，提升精度 \|
93		164
94	-### 步骤4：校准集调整	165	+ 本案例使用默认校准集 `mix_calib.jsonl`（48 条），加入 5 条 badcase 后为 53 条。
95		166
96	-步骤3达到80.00%精度后，已满足预设精度要求。为展示完整的调优流程并验证校准集调整的效果，本节在GPQA数据集上进行测试验证。GPQA数据集题目数量更多，能够更清晰地展现不同配置间的精度差异。本节以Iterative Smooth配合静态量化策略作为基准配置。	167	+2. 获取 badcase 样本：从 AISBench 测评结果文件中筛选「模型输出（`prediction` 字段）与参考答案（`gold` 字段）不一致」的样本，提取少量 badcase。例如，一个 badcase 样本为：
97		168
98	-#### 校准集优化策略	169	+ ```text
		170	+ What is the correct answer to this question: Two quantum states with energies E1 and E2 have a lifetime of 10^-9 sec and 10^-8 sec, respectively. We want to clearly distinguish these two energy levels. Which one of the following options could be their energy difference so that they can be clearly resolved?
99		171
100	-校准集的质量直接影响量化参数的准确性：	172	+ Choices:
		173	+ (A)10^-11 eV
		174	+ (B)10^-8 eV
		175	+ (C)10^-9 eV
		176	+ (D)10^-4 eV
		177	+ Format your response as follows: "The correct answer is (insert answer here)"
		178	+ ```
101		179
102	-\| 调整策略 \| 具体操作 \| 校准集变化 \| 优化目的 \|	180	+3. 格式转换：
103	-\|---------\|---------\|-----------\|---------\|
104	-\| 初始校准集 \| 10条随机样本 \| 10条 \| 建立基准配置 \|
105	-\| 增加数据量 \| 从10条增加到30条样本 \| 10→30条 \| 提升量化参数估计的准确性 \|
106	-\| 匹配应用场景 \| 使用中文对话数据替换随机数据 \| 30条（中文对话） \| 使校准数据更贴近实际应用场景 \|
107	-\| 平衡数据分布 \| 从GPQA、C-Eval、MMLU等多个数据集抽取样本混合 \| 30条（多数据集混合） \| 提升数据分布的多样性和均衡性 \|
108	-\| 剔除异常数据 \| 移除导致量化精度下降的3条异常样本 \| 30→27条 \| 减少异常样本对量化参数的干扰 \|
109	-\| 加入badcase \| 加入浮点模型在GPQA上的5个badcase样本 \| 27→32条 \| 帮助量化模型学习困难样本，提升精度 \|
110		181
111	-#### 调优过程	182	+ - JSONL格式：参考校准集文件 `mix_calib.jsonl` 的 JSONL 格式（格式说明见输入和交付件），将文本放在`"inputs_pretokenized"`字段后，格式如下：
112	-
113	-将AISBench测评结果中的badcase样本加入量化校准集，重新生成量化权重。具体操作如下：
114	-
115	-1.获取badcase样本：从AISBench测评结果中提取少量badcase样本。例如，一个badcase样本为：
116	-
117	-```text
118	-What is the correct answer to this question: Two quantum states with energies E1 and E2 have a lifetime of 10^-9 sec and 10^-8 sec, respectively. We want to clearly distinguish these two energy levels. Which one of the following options could be their energy difference so that they can be clearly resolved?
119	-
120	-Choices:
121	-(A)10^-11 eV
122	-(B)10^-8 eV
123	-(C)10^-9 eV
124	-(D)10^-4 eV
125	-Format your response as follows: "The correct answer is (insert answer here)"
126	-```
127	-
128	-2.格式转换：
129	-
130	- - JSONL格式：参考 `msmodelslim/lab_calib/mix_calib.jsonl`，将文本放在`"inputs_pretokenized"`字段后，格式如下：
131		183
132	```json	184	```json
133	{"inputs_pretokenized":"What is the correct answer to this question: Two quantum states with energies E1 and E2 have a lifetime of 10^-9 sec and 10^-8 sec, respectively. We want to clearly distinguish these two energy levels. Which one of the following options could be their energy difference so that they can be clearly resolved?\n\nChoices:\n(A)10^-11 eV\n(B)10^-8 eV\n\n(C)10^-9 eV\n(D)10^-4 eV\nFormat your response as follows: \"The correct answer is (insert answer here)\""}	185	{"inputs_pretokenized":"What is the correct answer to this question: Two quantum states with energies E1 and E2 have a lifetime of 10^-9 sec and 10^-8 sec, respectively. We want to clearly distinguish these two energy levels. Which one of the following options could be their energy difference so that they can be clearly resolved?\n\nChoices:\n(A)10^-11 eV\n(B)10^-8 eV\n\n(C)10^-9 eV\n(D)10^-4 eV\nFormat your response as follows: \"The correct answer is (insert answer here)\""}
134	```	186	```
135		187
136	- - JSON格式：参考 `msmodelslim/lab_calib/qwen3_cot_w4a4.json`，直接将文本加入字符串列表中即可。	188	+ - JSON格式：参考[`msmodelslim/lab_calib/qwen3_cot_w4a4.json`](../../../lab_calib/qwen3_cot_w4a4.json)，直接将文本加入字符串列表中即可。
137		189
138	-3.重新量化：将调整后的校准集用于量化，重新生成量化权重。	190	+ 将 badcase 样本与原校准集样本合并，生成新的校准集文件（本案例为 48→53 条）。
139		191
140	-#### 调优结果	192	+4. 重新量化：在量化配置 YAML 的 `spec` 下通过 `dataset` 字段指定加入 badcase 后的校准集文件（无需改动仓库默认校准集），其余处理器与 `save` 配置同步骤5 的完整 YAML 示例（`iter_smooth` 对称/alpha:0.9、`linear_quant` 静态量化），使用命令约定的量化命令重新生成量化权重。
		193	+
		194	+5. 测评验证：将新量化产物部署后执行测评命令（GPQA 数据集）。
		195	+
		196	+输出：badcase 校准集与重新生成的量化权重。GPQA 精度从基准的 48.98% 提升至 57.07%（提升 8.09 个百分点）。
141		197
142	\| 量化策略 \| GPQA 精度（%） \| 备注 \|	198	\| 量化策略 \| GPQA 精度（%） \| 备注 \|
143	\|-------------\|---------------\|------\|	199	\|-------------\|---------------\|------\|
144	-\| Iterative Smooth + 静态量化 \| 46.97 \| 基准配置 \|	200	+\| Iterative Smooth + 静态量化 \| 48.98 \| 基准配置 \|
145	-\| Iterative Smooth + 静态量化 + badcase调整校准集 \| 55.56 \| 相比基准配置精度提升8.59个百分点，说明badcase样本有助于量化模型学习困难样本，提升量化精度 \|	201	+\| Iterative Smooth + 静态量化 + badcase调整校准集 \| 57.07 \| 相比基准配置精度提升8.09个百分点，说明badcase样本有助于量化模型学习困难样本，提升量化精度 \|
		202	+
		203	+记录：上表 2 组配置的 GPQA 精度实测数据。
		204	+
		205	+下一步：为展示完整的调优流程并验证量化回退的效果，进入步骤5。
146		206
147	### 步骤5：量化回退（备选方案）	207	### 步骤5：量化回退（备选方案）
		Z Z zzm3014 天前备选方案理论上跟主方案不是步骤的先后关系，建议和主方案放在一起，用无需列表或者次级标题进行区分。
148		208
149	-量化回退是指将量化敏感层保持为原始浮点精度，以提升量化模型精度。当通过步骤1-4调整后精度仍无法满足要求时，可通过量化回退策略进一步优化。本节在GPQA数据集上验证量化回退的效果，展示完整的调优流程。	209	+目标：验证将量化敏感层回退为浮点精度对量化精度的提升效果。
		tanxiangyuu9 天前步骤5 和步骤4一样，说明做的原因
150		210
151	-#### 使用场景	211	+输入：步骤4的量化配置（Iterative Smooth + 静态量化）、GPQA 测评数据集、校准数据集。
152		212
153	-量化回退适用于以下情况：	213	+操作：
154		214
155	-- 通过步骤1-4调整后，精度仍无法满足精度要求。	215	+1. 敏感层分析：使用 msModelSlim 的敏感层分析工具识别量化敏感层，详细使用方法请参考[《量化敏感层分析使用指南》](../user_guide/usage_sensitive_linear_analysis.md)。
156	-- 需要在精度和性能之间寻求更精细的平衡。
157	-- 某些特定层对量化极度敏感，需要保持高精度。
158		216
159	-#### 调优过程	217	+ ```bash
		218	+ # 按实际环境填写以下路径
		219	+ MODEL_PATH=/path/to/qwen3-32b # 浮点模型权重目录
160		220
161	-1. 敏感层分析	221	+ msmodelslim analyze linear \
		222	+ --model_type Qwen3-32B \
		223	+ --model_path ${MODEL_PATH} \
		224	+ --device npu \
		225	+ --topk 20 \
		226	+ --metrics kurtosis
		227	+ ```
162		228
163	-使用msModelSlim提供的敏感层分析工具识别量化敏感层。详细使用方法请参考《[线性层敏感层分析使用指南](../user_guide/usage_sensitive_linear_analysis.md)》。	229	+ 根据量化敏感度得分从高到低排序，Top敏感层结果如下：
164		230
165	-执行分析命令：	231	+ ```text
		232	+ layers.3.mlp.down_proj
		233	+ layers.63.mlp.down_proj
		234	+ layers.2.mlp.down_proj
		235	+ layers.1.mlp.down_proj
		236	+ layers.4.mlp.down_proj
		237	+ layers.6.mlp.down_proj
		238	+ layers.7.mlp.down_proj
		239	+ layers.5.mlp.down_proj
		240	+ layers.0.mlp.down_proj
		241	+ layers.31.mlp.down_proj
		242	+ layers.62.mlp.down_proj
		243	+ layers.5.mlp.gate_proj
		244	+ layers.5.mlp.up_proj
		245	+ layers.32.mlp.down_proj
		246	+ layers.8.mlp.gate_proj
		247	+ layers.8.mlp.up_proj
		248	+ layers.6.mlp.gate_proj
		249	+ layers.6.mlp.up_proj
		250	+ ```
166		251
167	-```bash	252	+ 分析结果显示 `mlp.down_proj` 层敏感度排名靠前，是量化难度较大的层类型，应优先考虑回退。
168	-msmodelslim analyze \
169	- --model_type Qwen3-32B \
170	- --model_path ${model_path}
171	-```
172		253
173	-根据量化敏感度得分从高到低排序，Top敏感层结果如下：	254	+2. 修改量化配置：在量化配置 YAML 中，通过 `exclude` 字段回退最为敏感的前9层（均为 `mlp.down_proj` 层）：
174		255
175	-```text	256	+ ```yaml
176	-layers.3.mlp.down_proj	257	+ apiversion: modelslim_v1
177	-layers.63.mlp.down_proj	258	+ spec:
178	-layers.2.mlp.down_proj	259	+ process:
179	-layers.1.mlp.down_proj	260	+ - type: "iter_smooth" # 参数同步骤2（对称/alpha:0.9）
180	-layers.4.mlp.down_proj	261	+ - type: "linear_quant"
181	-layers.6.mlp.down_proj	262	+ qconfig:
182	-layers.7.mlp.down_proj	263	+ act:
183	-layers.5.mlp.down_proj	264	+ scope: "per_tensor"
184	-layers.0.mlp.down_proj	265	+ dtype: "int8"
185	-layers.31.mlp.down_proj	266	+ symmetric: false
186	-layers.62.mlp.down_proj	267	+ method: "minmax"
187	-layers.5.mlp.gate_proj	268	+ weight:
188	-layers.5.mlp.up_proj	269	+ scope: "per_channel"
189	-layers.32.mlp.down_proj	270	+ dtype: "int8"
190	-layers.8.mlp.gate_proj	271	+ symmetric: true
191	-layers.8.mlp.up_proj	272	+ method: "minmax"
192	-layers.6.mlp.gate_proj	273	+ include:
193	-layers.6.mlp.up_proj	274	+ - "*"
194	-```	275	+ exclude:
		276	+ - 'model.layers.3.mlp.down_proj'
		277	+ - 'model.layers.63.mlp.down_proj'
		278	+ - 'model.layers.2.mlp.down_proj'
		279	+ - 'model.layers.1.mlp.down_proj'
		280	+ - 'model.layers.4.mlp.down_proj'
		281	+ - 'model.layers.6.mlp.down_proj'
		282	+ - 'model.layers.7.mlp.down_proj'
		283	+ - 'model.layers.5.mlp.down_proj'
		284	+ - 'model.layers.0.mlp.down_proj'
		285	+ save:
		286	+ - type: "ascendv1_saver"
		287	+ part_file_size: 4
		288	+ ```
195		289
196	-分析结果：`mlp.down_proj` 层敏感度排名靠前，是量化难度较大的层类型，应优先考虑回退。	290	+3. 重新生成量化权重：使用修改后的配置执行量化命令，生成包含回退层的量化模型。
197		291
198	-2. 修改量化配置	292	+4. 测评验证：将新量化产物部署后执行测评命令（GPQA 数据集）。
199		293
200	-在量化配置YAML中，通过`exclude`字段回退最为敏感的前9层（均为`mlp.down_proj`层）：	294	+输出：含 9 个回退层的量化模型。GPQA 精度从基准的 48.98% 提升至 49.49%（提升 0.51 个百分点）。
201	-
202	-```yaml
203	-apiversion: modelslim_v1
204	-spec:
205	- process:
206	- - type: "iter_smooth"
207	- alpha: 0.9
208	- scale_min: 1e-5
209	- symmetric: True
210	- enable_subgraph_type:
211	- - 'norm-linear'
212	- - 'linear-linear'
213	- - 'ov'
214	- - 'up-down'
215	- include:
216	- - "*"
217	- - type: "linear_quant"
218	- qconfig:
219	- act:
220	- scope: "per_tensor"
221	- dtype: "int8"
222	- symmetric: false
223	- method: "minmax"
224	- weight:
225	- scope: "per_channel"
226	- dtype: "int8"
227	- symmetric: true
228	- method: "minmax"
229	- include:
230	- - "*"
231	- exclude:
232	- - 'model.layers.3.mlp.down_proj'
233	- - 'model.layers.63.mlp.down_proj'
234	- - 'model.layers.2.mlp.down_proj'
235	- - 'model.layers.1.mlp.down_proj'
236	- - 'model.layers.4.mlp.down_proj'
237	- - 'model.layers.6.mlp.down_proj'
238	- - 'model.layers.7.mlp.down_proj'
239	- - 'model.layers.5.mlp.down_proj'
240	- - 'model.layers.0.mlp.down_proj'
241	- save:
242	- - type: "ascendv1_saver"
243	- part_file_size: 4
244	-```
245	-
246	-3. 重新生成量化权重
247	-
248	-使用修改后的配置重新进行量化，生成包含回退层的量化模型。
249	-
250	-#### 调优结果
251		295
252	\| 量化策略 \| GPQA 精度（%） \| 备注 \|	296	\| 量化策略 \| GPQA 精度（%） \| 备注 \|
253	\|-------------\|---------------\|------\|	297	\|-------------\|---------------\|------\|
254	-\| Iterative Smooth + 静态量化 \| 46.97 \| 基准配置 \|	298	+\| Iterative Smooth + 静态量化 \| 48.98 \| 基准配置 \|
255	-\| Iterative Smooth + 静态量化 + 回退前9层 \| 51.51 \| 相比基准配置精度提升4.54个百分点，说明回退量化敏感层能有效提升量化精度，但会带来一定的性能开销和模型大小增加 \|	299	+\| Iterative Smooth + 静态量化 + 回退前9层 \| 49.49 \| 相比基准配置精度提升0.51个百分点，说明回退量化敏感层能有效提升量化精度，但会带来一定的性能开销和模型大小增加 \|
256		300
257	-## 最终配置总结	301	+记录：上表 2 组配置的 GPQA 精度实测数据。
258		302
259	-### 调优路径回顾	303	+下一步：调优结束。
260		304
261	-\| 步骤 \| 关键操作 \| AIME25 精度（%） \| 精度提升 \| 备注 \|	305	+## 5. 结果与经验
262	-\|------\|---------\|-----------------\|---------\|------\|
263	-\| 初始状态 \| Smooth Quant + minmax + 静态量化 \| 乱码 \| - \| 初始配置，无法正常使用 \|
264	-\| 步骤2 \| Iterative Smooth（对称/alpha:0.9） \| 66.67% \| +66.67% \| 离群值抑制算法优化，解决乱码问题 \|
265	-\| 步骤3 \| minmax + per-token（动态量化） \| 80.00% \| +13.33% \| 激活量化粒度优化，达到精度要求 \|
266		306
267	-说明：步骤3达到80.00%精度后，已满足预设精度要求。步骤4和步骤5在GPQA数据集上进行验证，展示校准集调整和量化回退的调优效果。	307	+### 5.1 关键结果汇总
268		308
269	-### 最终配置	309	+\| 步骤 \| 关键操作 \| 指标 \| 变化 \| 备注 \|
		310	+\|------\|---------\|------\|------\|------\|
		311	+\| 初始状态 \| Smooth Quant + minmax 静态量化 \| AIME25 精度：对话乱码 \| — \| 初始配置，量化模型不可用 \|
		312	+\| 步骤2 \| 切换 Iterative Smooth（对称/alpha:0.9） \| AIME25 精度：63.33% \| 乱码 → 63.33% \| 解决乱码问题，模型可用 \|
		313	+\| 步骤3 \| 激活量化切换为 per-token（动态量化） \| AIME25 精度：70.00% \| +6.67 个百分点 \| 达到预设精度要求（70.00%） \|
		314	+\| 步骤4 \| badcase 样本加入校准集 \| GPQA 精度：57.07% \| +8.09 个百分点 \| 相对 GPQA 基准（48.98%），备选验证 \|
		315	+\| 步骤5 \| 回退前 9 个敏感层（mlp.down_proj） \| GPQA 精度：49.49% \| +0.51 个百分点 \| 相对 GPQA 基准（48.98%），备选验证 \|
270		316
271	-离群值抑制算法：Iterative Smooth（对称/alpha:0.9）	317	+说明：步骤3达到 70.00% 精度后已满足预设精度要求；步骤4和步骤5在 GPQA 数据集上验证校准集调整与量化回退两类备选手段的效果，展示完整调优路径。
272		318
273	-量化配置：	319	+最终配置：
274		320
		321	+- 离群值抑制算法：Iterative Smooth（对称/alpha:0.9）。
275	- 权重量化：`minmax` 方法，`per_channel` 粒度，`int8` 数据类型，对称量化。	322	- 权重量化：`minmax` 方法，`per_channel` 粒度，`int8` 数据类型，对称量化。
276	-- 激活量化：`minmax` 方法，`per_token` 粒度（动态量化），`int8` 数据类型，对称量化。	323	+- 激活量化：`minmax` 方法，`per_token` 粒度（动态量化），`int8` 数据类型。
277		324
278	-### 调优经验总结	325	+### 5.2 经验总结
279		326
280	-1. 离群值抑制算法是关键：从Smooth Quant切换到Iterative Smooth（对称/alpha:0.9），精度从乱码提升至66.67%，使量化模型具备可用性。	327	+1. 离群值抑制算法是关键：从Smooth Quant切换到Iterative Smooth（对称/alpha:0.9），AIME25 精度从乱码提升至 63.33%，使量化模型具备可用性。适用边界：优先选用 Iterative Smooth，非对称方案通常优于对称方案但需推理引擎适配支持，量化前需确认推理引擎对离群值抑制算法的适配情况。
281		328
282	-2. 激活量化粒度影响显著：从per-tensor（静态量化）切换到per-token（动态量化），精度从66.67%提升至80.00%，提升13.33个百分点（相对提升20%），但需要注意动态量化可能带来一定的推理性能损失。	329	+2. 激活量化粒度影响显著：从 per-tensor（静态量化）切换到 per-token（动态量化），AIME25 精度从 63.33% 提升至 70.00%（+6.67 个百分点）。适用边界：per-token 动态量化计算更复杂，可能带来一定的推理性能损失，追求性能时可改用 `pd_mix` 混合策略。
283		330
284	-3. 量化方法选择很重要：minmax方法在INT8量化场景下表现优于ssz方法，不仅精度更高（80.00% vs 70.00%），而且量化时间更短（289秒 vs 348秒），实现更简单，是当前场景下的最佳选择。	331	+3. 量化方法选择需权衡精度与效率：实测 ssz 精度上限更高（ssz + per-token 76.67% vs minmax + per-token 70.00%），但 minmax 量化时间更短（289秒 vs 348秒）、实现更简单，且在满足预设精度要求（70.00%）的前提下综合更优，故本案例选择 minmax + per-token。适用边界：追求极限精度时可选用 ssz，追求效率时优先 minmax；INT4 等低比特场景建议优先选择 ssz 方法。
285		332
286	-4. 校准集质量影响精度：在GPQA数据集上验证，通过加入badcase样本优化校准集，精度从46.97%提升至55.56%，提升8.59个百分点，说明场景匹配数据和困难样本对量化精度提升有显著作用。	333	+4. 校准集质量影响精度：在 GPQA 数据集上，将 badcase 样本加入校准集后精度从 48.98% 提升至 57.07%（+8.09 个百分点）。适用边界：数据量建议 10-50条，需与任务、语言匹配（中文模型用中文数据），badcase 需来自同一测评集才能稳定复现收益。
287		334
288	-5. 量化回退是最后手段：在GPQA数据集上验证，通过回退9个量化敏感层，精度从46.97%提升至51.51%，提升4.54个百分点。量化回退能有效提升精度，但会带来性能开销和模型大小增加，应在其他优化手段无法满足要求时使用。	335	+5. 量化回退是最后手段：在 GPQA 数据集上，回退 9 个量化敏感层后精度从 48.98% 提升至 49.49%（+0.51 个百分点）。适用边界：回退会带来性能开销和模型大小增加，应在其他手段无法满足要求时使用；`mlp.down_proj` 通常为敏感层，可优先回退。
		336	+
		337	+## 6. 附录
		338	+
		339	+- 相关指南：[《量化敏感层分析使用指南》](../user_guide/usage_sensitive_linear_analysis.md)
		340	+- 测评数据：[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/user_guide/traditional_quantization_v0/foundation_model_quantization_and_calibration.md+0-2

	@@ -593,8 +593,6 @@ from transformers.models.qwen2.configuration_qwen2 import Qwen2Config
593	\| [quant_qwen.py](../../../../example/Qwen/quant_qwen.py) \| [Qwen2.5-72B 支持Attention量化](../../../../example/Qwen/README.md#qwen25-72b-支持attention量化) \|	593	\| [quant_qwen.py](../../../../example/Qwen/quant_qwen.py) \| [Qwen2.5-72B 支持Attention量化](../../../../example/Qwen/README.md#qwen25-72b-支持attention量化) \|
594	\| [quant_llama.py](../../../../example/Llama/quant_llama.py) \| [Llama3.1-70B W8A8量化搭配Attention量化](../../../../example/Llama/README.md#llama31-70b-w8a8量化搭配attention量化) \|	594	\| [quant_llama.py](../../../../example/Llama/quant_llama.py) \| [Llama3.1-70B W8A8量化搭配Attention量化](../../../../example/Llama/README.md#llama31-70b-w8a8量化搭配attention量化) \|
595		595
596	-#### 本文仅给出FA3场景下Llama3.1-70B和Qwen2.5-72B的量化推荐配置，可按实际情况进行参数调整，详见《[精度调优策略](../process_quantization_precision_tuning.md)》
597	-
598	#### 3.6.2 Llama3.1-70B 量化参数设置	596	#### 3.6.2 Llama3.1-70B 量化参数设置
599		597
600	- 离群值抑制(AntiOutlier) ：anti_method = "m3"	598	- 离群值抑制(AntiOutlier) ：anti_method = "m3"