Star205
184
代码
代码
Issues113
Pull Requests88
项目讨论
Wiki
分析
Star205
184
已合并
[docs] 分解量化算法文档 #833
wanlongze123创建于 22 天前
[docs] 分解量化算法文档 #833
已合并
wanlongze123创建于 22 天前
从qq_46439621/msmodelslimalog_ziliao_0813合入到Ascend/msmodelslimmaster
共 101 个文件变更+9443-5801
Mdocs/zh/knowledge_base/model/integrating_multimodal_understanding_model.md+2-2
@@ -646,7 +646,7 @@ class Qwen3VLMoeModelAdapter(VlmBaseModelAdapter,
646 return adapter_config646 return adapter_config
647```647```
648 648 
649-详见：[Iterative Smooth 适配](../quantization_algorithms/iterative_smooth/iterative_smooth.md#模型适配)649+详见：[Iterative Smooth 适配](../quantization_algorithms/iterative_smooth/term_iterative_smooth.md#4-模型适配接口)
650 650 
651#### 支持QuaRot旋转离群值抑制算法651#### 支持QuaRot旋转离群值抑制算法
652 652 
@@ -681,7 +681,7 @@ class Qwen3VLMoeModelAdapter(VlmBaseModelAdapter,
681 pass681 pass
682```682```
683 683 
684-详见：[QuaRot 适配](../quantization_algorithms/quarot/quarot.md#模型适配)684+详见：[QuaRot 适配](../quantization_algorithms/quarot/term_quarot.md#4-模型适配接口)
685 685 
686### 参考资料686### 参考资料
687 687 
Mdocs/zh/knowledge_base/quantization_algorithms/README.md+65-65
@@ -1,65 +1,65 @@
1----1+---
2-toc_depth: 32+toc_depth: 3
3----3+---
4-# 量化算法总览4+# 量化算法总览
5- 5+ 
6-msModelSlim 支持多种先进的量化算法，涵盖了从离群值抑制到低比特优化的各个环节。下表按类别总结了目前支持的核心算法及其主要特性。6+msModelSlim 支持多种先进的量化算法，涵盖了从离群值抑制到低比特优化的各个环节。下表按类别总结了目前支持的核心算法及其主要特性。
7- 7+ 
8-## 离群值抑制算法8+## 离群值抑制算法
9- 9+ 
10-离群值抑制算法旨在平滑激活值的分布，减少量化带来的精度损失。10+离群值抑制算法旨在平滑激活值的分布，减少量化带来的精度损失。
11- 11+ 
12-| 算法名称 | 核心思想 | 适用场景 | 详细说明 |12+| 算法名称 | 核心思想 | 适用场景 | 词条 | 使用指南 |
13-| :--- | :--- | :--- | :--- |13+| :--- | :--- | :--- | :--- | :--- |
14-| **QuaRot** | 应用正交旋转矩阵平滑激活值分布 | 抑制激活离群值，提升精度 | [查看详情](quarot/quarot.md) |14+| **QuaRot** | 应用正交旋转矩阵平滑激活值分布 | 抑制激活离群值，提升精度 | [词条](quarot/term_quarot.md) | [使用指南](quarot/usage_quarot.md) |
15-| **Adapt Rotation** | 在QuaRot基础上使用基于校准数据迭代优化 Hadamard 旋转矩阵 | 优化旋转矩阵，进一步提升低比特量化精度 | [查看详情](adapt_rotation/adapt_rotation.md) |15+| **Adapt Rotation** | 在QuaRot基础上使用基于校准数据迭代优化 Hadamard 旋转矩阵 | 优化旋转矩阵，进一步提升低比特量化精度 | [词条](adapt_rotation/term_adapt_rotation.md) | [使用指南](adapt_rotation/usage_adapt_rotation.md) |
16-| **SmoothQuant** | 协同缩放激活与权重，平滑离群值 | 抑制激活离群值 | [查看详情](smooth_quant/smooth_quant.md) |16+| **SmoothQuant** | 协同缩放激活与权重，平滑离群值 | 抑制激活离群值 | [词条](smooth_quant/term_smooth_quant.md) | [使用指南](smooth_quant/usage_smooth_quant.md) |
17-| **Iterative Smooth** | 迭代式平滑缩放，更精细的分布调整 | 复杂分布下的精度优化 | [查看详情](iterative_smooth/iterative_smooth.md) |17+| **Iterative Smooth** | 迭代式平滑缩放，更精细的分布调整 | 复杂分布下的精度优化 | [词条](iterative_smooth/term_iterative_smooth.md) | [使用指南](iterative_smooth/usage_iterative_smooth.md) |
18-| **Flex Smooth Quant** | 二阶段网格搜索自动寻找最优 alpha/beta | 灵活适配不同架构 | [查看详情](flex_smooth_quant/flex_smooth_quant.md) |18+| **Flex Smooth Quant** | 二阶段网格搜索自动寻找最优 alpha/beta | 灵活适配不同架构 | [词条](flex_smooth_quant/term_flex_smooth_quant.md) | [使用指南](flex_smooth_quant/usage_flex_smooth_quant.md) |
19-| **Flex AWQ SSZ** | 结合 AWQ 与 SSZ，使用真实量化器评估误差 | 自动搜索最优平滑参数 | [查看详情](flex_awq_ssz/flex_awq_ssz.md) |19+| **Flex AWQ SSZ** | 结合 AWQ 与 SSZ，使用真实量化器评估误差 | 自动搜索最优平滑参数 | [词条](flex_awq_ssz/term_flex_awq_ssz.md) | [使用指南](flex_awq_ssz/usage_flex_awq_ssz.md) |
20-| **KV Smooth** | 针对 KV Cache 的平滑抑制算法 | 降低 KV Cache 显存占用 | [查看详情](kv_smooth/kv_smooth.md) |20+| **KV Smooth** | 针对 KV Cache 的平滑抑制算法 | 降低 KV Cache 显存占用 | [词条](kv_smooth/term_kv_smooth.md) | [使用指南](kv_smooth/usage_kv_smooth.md) |
21-| **AWQ** | 基于激活值统计特征网格搜索最优缩放因子 | 自动搜索最优平滑参数 | [查看详情](awq_smooth/awq_smooth.md) |21+| **AWQ** | 基于激活值统计特征网格搜索最优缩放因子 | 自动搜索最优平滑参数 | [词条](awq_smooth/term_awq_smooth.md) | [使用指南](awq_smooth/usage_awq_smooth.md) |
22- 22+ 
23-## 量化算法23+## 量化算法
24- 24+ 
25-包含权重量化、激活量化以及针对特定结构的量化方案。25+包含权重量化、激活量化以及针对特定结构的量化方案。
26- 26+ 
27-| 算法名称 | 类型 | 核心思想 | 适用场景 | 详细说明 |27+| 算法名称 | 类型 | 核心思想 | 适用场景 | 词条 | 使用指南 |
28-| :--- | :--- | :--- | :--- | :--- |28+| :--- | :--- | :--- | :--- | :--- | :--- |
29-| **AutoRound** | 权重量化优化 | 基于 SignSGD 优化舍入偏移，降低重构误差 | 4bit 等超低比特量化 | [查看详情](autoround/autoround.md) |29+| **AutoRound** | 权重量化优化 | 基于 SignSGD 优化舍入偏移，降低重构误差 | 4bit 等超低比特量化 | [词条](autoround/term_autoround.md) | [使用指南](autoround/usage_autoround.md) |
30-| **FA3 Quant** | 激活量化 | 针对 Attention 激活的 per-head INT8 量化 | 长序列、MLA 架构模型 | [查看详情](fa3_quant/fa3_quant.md) |30+| **FA3 Quant** | 激活量化 | 针对 Attention 激活的 per-head INT8 量化 | 长序列、MLA 架构模型 | [词条](fa3_quant/term_fa3_quant.md) | [使用指南](fa3_quant/usage_fa3_quant.md) |
31-| **GPTQ** | 权重量化优化 | 通过逐列优化和误差补偿最小化量化误差 | 高精度权重量化需求 | [查看详情](gptq/gptq.md) |31+| **GPTQ** | 权重量化优化 | 通过逐列优化和误差补偿最小化量化误差 | 高精度权重量化需求 | [词条](gptq/term_gptq.md) | [使用指南](gptq/usage_gptq.md) |
32-| **KVCache Quant** | KV Cache 量化 | 针对 KV Cache 的量化方案 | 提升长序列推理效率 | [查看详情](kvcache_quant/kvcache_quant.md) |32+| **KVCache Quant** | KV Cache 量化 | 针对 KV Cache 的量化方案 | 提升长序列推理效率 | [词条](kvcache_quant/term_kvcache_quant.md) | [使用指南](kvcache_quant/usage_kvcache_quant.md) |
33-| **Linear Quant** | 基础量化 | 对线性层进行权重量化和激活量化 | 基础量化场景 | [查看详情](linear_quant/linear_quant.md) |33+| **Linear Quant** | 基础量化 | 对线性层进行权重量化和激活量化 | 基础量化场景 | [词条](linear_quant/term_linear_quant.md) | [使用指南](linear_quant/usage_linear_quant.md) |
34-| **PDMIX** | 混合阶段量化 | Prefilling 使用动态量化，Decoding 使用静态量化 | 大模型推理加速，平衡精度与性能 | [查看详情](pdmix/pdmix.md) |34+| **PDMIX** | 混合阶段量化 | Prefilling 使用动态量化，Decoding 使用静态量化 | 大模型推理加速，平衡精度与性能 | [词条](pdmix/term_pdmix.md) | [使用指南](pdmix/usage_pdmix.md) |
35-| **Histogram** | 激活量化 | 分析直方图分布，搜索最优截断区间 | 过滤离群值，提高精度 | [查看详情](histogram_activation_quantization/histogram_activation_quantization.md) |35+| **Histogram** | 激活量化 | 分析直方图分布，搜索最优截断区间 | 过滤离群值，提高精度 | [词条](histogram_activation_quantization/term_histogram_activation_quantization.md) | [使用指南](histogram_activation_quantization/usage_histogram_activation_quantization.md) |
36-| **MinMax** | 基础量化 | 统计最大最小值确定量化范围 | 基础量化场景，计算开销低 | [查看详情](minmax/minmax.md) |36+| **MinMax** | 基础量化 | 统计最大最小值确定量化范围 | 基础量化场景，计算开销低 | [词条](minmax/term_minmax.md) | [使用指南](minmax/usage_minmax.md) |
37-| **SSZ** | 权重量化 | 迭代搜索最优缩放因子和偏移量 | 权重分布不均的精度优化 | [查看详情](ssz/ssz.md) |37+| **SSZ** | 权重量化 | 迭代搜索最优缩放因子和偏移量 | 权重分布不均的精度优化 | [词条](ssz/term_ssz.md) | [使用指南](ssz/usage_ssz.md) |
38-| **LAOS** | 低比特量化 | 针对 W4A4 等极低比特场景的优化 | 极致压缩需求 | [查看详情](laos/laos.md) |38+| **LAOS** | 低比特量化 | 针对 W4A4 等极低比特场景的优化 | 极致压缩需求 | [词条](laos/term_laos.md) | [使用指南](laos/usage_laos.md) |
39-| **Float Sparse** | 稀疏化 | 基于 ADMM 算法实现模型浮点 sparse | 高压缩率需求 | [查看详情](float_sparse/float_sparse.md) |39+| **Float Sparse** | 稀疏化 | 基于 ADMM 算法实现模型浮点 sparse | 高压缩率需求 | [词条](float_sparse/term_float_sparse.md) | [使用指南](float_sparse/usage_float_sparse.md) |
40-| **SVDQuant** | 综合方案 | 离群值迁移 + SVD 低秩残差 + 残差量化 | 扩散模型等低比特量化 | [查看详情](svdquant/svdquant.md) |40+| **SVDQuant** | 综合方案 | 离群值迁移 + SVD 低秩残差 + 残差量化 | 扩散模型等低比特量化 | [词条](svdquant/term_svdquant.md) | [使用指南](svdquant/usage_svdquant.md) |
41-| **MSE_Round** | 权重量化 | 按 block 在 ceil/floor shared exponent 间按 MSE 择优 | MXFP8 权重量化精度优化 | [查看详情](mse_round/mse_round.md) |41+| **MSE_Round** | 权重量化 | 按 block 在 ceil/floor shared exponent 间按 MSE 择优 | MXFP8 权重量化精度优化 | [词条](mse_round/term_mse_round.md) | [使用指南](mse_round/usage_mse_round.md) |
42-| **FouroverSix** | 权重量化 | 自适应选择块缩放（Scale-to-6 / Scale-to-4） | mxFP4 量化误差优化 | [查看详情](fouroversix/fouroversix.md) |42+| **FouroverSix** | 权重量化 | 自适应选择块缩放（Scale-to-6 / Scale-to-4） | mxFP4 量化误差优化 | [词条](fouroversix/term_fouroversix.md) | [使用指南](fouroversix/usage_fouroversix.md) |
43-| **Ceil_X** | 权重量化 | ceil + 可配置除数计算 shared exponent | MXFP4 大值截断抑制 | [查看详情](ceil_x/ceil_x.md) |43+| **Ceil_X** | 权重量化 | ceil + 可配置除数计算 shared exponent | MXFP4 大值截断抑制 | [词条](ceil_x/term_ceil_x.md) | [使用指南](ceil_x/usage_ceil_x.md) |
44-| **DualScale** | 权重量化 | 两级粒度递进缩放，缓解异常通道 | W4A4 等低比特场景 | [查看详情](dual_scale/dual_scale.md) |44+| **DualScale** | 权重量化 | 两级粒度递进缩放，缓解异常通道 | W4A4 等低比特场景 | [词条](dual_scale/term_dual_scale.md) | [使用指南](dual_scale/usage_dual_scale.md) |
45- 45+ 
46-## 敏感层分析算法46+## 敏感层分析算法
47- 47+ 
48-敏感层分析通过`msmodelslim analyze`在校准数据上度量各层或子结构对量化的敏感程度，得到排序结果以辅助回退与 YAML 调参。48+敏感层分析通过`msmodelslim analyze`在校准数据上度量各层或子结构对量化的敏感程度，得到排序结果以辅助回退与 YAML 调参。
49- 49+ 
50-| 算法名称 | 分析范围 | 核心思想 | 适用场景 | 详细说明 |50+| 算法名称 | 分析范围 | 核心思想 | 适用场景 | 词条 | 使用指南 |
51-| :--- | :--- | :--- | :--- | :--- |51+| :--- | :--- | :--- | :--- | :--- | :--- |
52-| **Std** | linear（线性层） | 用激活动态范围与标准差的比值刻画敏感度 | 量化前线性层粗筛、默认策略之一 | [查看详情](std/std.md) |52+| **Std** | linear（线性层） | 用激活动态范围与标准差的比值刻画敏感度 | 量化前线性层粗筛、默认策略之一 | [词条](std/term_std.md) | [使用指南](std/usage_std.md) |
53-| **Quantile** | linear（线性层） | 基于分位数与 IQR 构造 score，对离群点相对稳健 | 激活尾部重、希望降低离群主导 | [查看详情](quantile/quantile.md) |53+| **Quantile** | linear（线性层） | 基于分位数与 IQR 构造 score，对离群点相对稳健 | 激活尾部重、希望降低离群主导 | [词条](quantile/term_quantile.md) | [使用指南](quantile/usage_quantile.md) |
54-| **Kurtosis** | linear（线性层） | 估计激活峰度，识别尖峰与极端值影响 | 关注尖峰分布、配合回退或混精 | [查看详情](kurtosis/kurtosis.md) |54+| **Kurtosis** | linear（线性层） | 估计激活峰度，识别尖峰与极端值影响 | 关注尖峰分布、配合回退或混精 | [词条](kurtosis/term_kurtosis.md) | [使用指南](kurtosis/usage_kurtosis.md) |
55-| **Attention MSE（mse）** | attn（attention 结构） | 浮点与量化权重下 attention 输出的 MSE | Attention 权重量化敏感度（需适配器接口） | [查看详情](attention_mse/attention_mse.md) |55+| **Attention MSE（mse）** | attn（attention 结构） | 浮点与量化权重下 attention 输出的 MSE | Attention 权重量化敏感度（需适配器接口） | [词条](attention_mse/term_attention_mse.md) | [使用指南](attention_mse/usage_attention_mse.md) |
56-| **层级 MSE（mse_layer_wise）** | layer（Decoder 块） | 块内选中子模块输出上 MSE 的块内均值 | 整层或整块（如 MLP / attention 段）回退 | [查看详情](mse_layer_wise/mse_layer_wise.md) |56+| **层级 MSE（mse_layer_wise）** | layer（Decoder 块） | 块内选中子模块输出上 MSE 的块内均值 | 整层或整块（如 MLP / attention 段）回退 | [词条](mse_layer_wise/term_mse_layer_wise.md) | [使用指南](mse_layer_wise/usage_mse_layer_wise.md) |
57-| **模型级 MSE（mse_model_wise）** | layer（链式前向） | 逐层量化扰动对**模型最终输出**的 MSE | 从最终隐藏状态视角看层敏感度 | [查看详情](mse_model_wise/mse_model_wise.md) |57+| **模型级 MSE（mse_model_wise）** | layer（链式前向） | 逐层量化扰动对**模型最终输出**的 MSE | 从最终隐藏状态视角看层敏感度 | [词条](mse_model_wise/term_mse_model_wise.md) | [使用指南](mse_model_wise/usage_mse_model_wise.md) |
58- 58+ 
59-## 算法选择建议59+## 算法选择建议
60- 60+ 
61-- **初学者**：建议优先使用《[一键量化 (V1)](../../user_guide/usage_quick_quantization.md)》，它会自动集成合适的算法组合。61+- **初学者**：建议优先使用《[一键量化 (V1)](../../user_guide/usage_quick_quantization.md)》，它会自动集成合适的算法组合。
62-- **敏感层与回退**：在定稿 YAML 前可按 scope 选用《[线性层敏感层分析使用指南](../../user_guide/usage_sensitive_linear_analysis.md)》、《[层级敏感层分析使用指南](../../user_guide/usage_sensitive_layer_wise_analysis.md)》或《[Attention 敏感层分析使用指南](../../user_guide/usage_sensitive_attn_analysis.md)》，结合上表 metrics 做层/结构排序；`linear`可首选**Kurtosis**，`layer`可优先**mse_layer_wise**。62+- **敏感层与回退**：在定稿 YAML 前可按 scope 选用《[线性层敏感层分析使用指南](../../user_guide/usage_sensitive_linear_analysis.md)》、《[层级敏感层分析使用指南](../../user_guide/usage_sensitive_layer_wise_analysis.md)》或《[Attention 敏感层分析使用指南](../../user_guide/usage_sensitive_attn_analysis.md)》，结合上表 metrics 做层/结构排序；`linear`可首选**Kurtosis**，`layer`可优先**mse_layer_wise**。
63-- **自动调优**：精度不达标且希望自动搜索配置时，参见《[自动调优策略总览](../tuning_strategies/README.md)》。63+- **自动调优**：精度不达标且希望自动搜索配置时，参见《[自动调优策略总览](../tuning_strategies/README.md)》。
64-- **追求极致精度**：可以尝试组合使用 **QuaRot** + **AutoRound**。64+- **追求极致精度**：可以尝试组合使用 **QuaRot** + **AutoRound**。
65-- **长序列推理**：推荐开启 **FA3 Quant** 和 **KVCache Quant**。65+- **长序列推理**：推荐开启 **FA3 Quant** 和 **KVCache Quant**。
Ddocs/zh/knowledge_base/quantization_algorithms/adapt_rotation/adapt_rotation.md+0-241
@@ -1,241 +0,0 @@
1-# Adapt Rotation：自适应旋转优化算法说明
2- 
3-## 简介
4- 
5-- **概述**：Adapt Rotation（自适应旋转优化）是一种用于大语言模型量化的离群值抑制算法，在 QuaRot 的基础上进一步优化旋转矩阵。该算法通过校准数据驱动的方式，迭代优化 Hadamard 旋转矩阵，使变换后的激活值在量化时具有更小的重构误差，从而有效抑制激活离群值，提升低比特量化精度。
6-- **核心思想**：在固定 Hadamard 矩阵的基础上，通过 Newton-Schulz 迭代求解正交极因子，学习了一个可优化的正交矩阵，使得在给定激活数据上，经过量化-反量化后的重构误差最小。
7-- **与 QuaRot 的关系**：使用 Adapt Rotation 的前提是模型适配 `AdaptRotationInterface`（它继承 `QuaRotInterface`，并额外提供 `get_hidden_dim()`）。Stage1 负责基于校准数据优化旋转矩阵；Stage2 将优化后的矩阵应用到 QuaRot 中，替代默认的 Hadamard 矩阵。
8- 
9-## 使用前准备
10- 
11-安装 msModelSlim 工具，详情请参见 [msModelSlim 工具安装指南](../../../install_guide/install_guide.md)。
12- 
13-## 原理和实现
14- 
15-### 原理
16- 
17-1. **核心概念**：
18- - 给定初始 Hadamard 矩阵 H 和校准激活数据，通过迭代优化学习正交旋转 R。
19- - 变换后的旋转矩阵为 `H_adapted = H @ R`，满足正交性，保持计算等价。
20- - 优化目标：最小化变换后激活值经 per-token 对称量化-反量化后的重构损失。
21- 
22-2. **迭代 Hadamard 优化**：
23- - 使用 Newton-Schulz 迭代求解 `A.T @ B` 的正交极因子，得到正交矩阵 R_step。
24- - 累积旋转：`R_acc = R_acc @ R_step`。
25- - 每步对激活做旋转变换，对变换结果做 per-token 量化-反量化，计算归一化重构误差。
26- 
27-3. **两阶段流程**：
28- - **Stage1**：收集指定层（如 `up_proj`）的激活，运行 Hadamard 优化，得到优化后的旋转矩阵，存入上下文机制中。
29- - **Stage2**：从上下文机制读取优化后的旋转矩阵，覆盖 QuaRot 中对应维度的旋转矩阵，执行与 QuaRot 相同的层融合、插入旋转等流程。
30- 
31-### 实现
32- 
33-#### 代码实现
34- 
35-算法在 [msmodelslim/processor/adapt_rotation/](../../../../../msmodelslim/processor/adapt_rotation) 中实现，核心类包括：
36- 
37-- `AdaptRotationProcessor`：顶层处理器，根据 `stage` 分发到 Stage1 或 Stage2。
38-- `AdaptRotationStage1Processor`：Stage1，收集激活并优化旋转矩阵。
39-- `AdaptRotationStage2Processor`：Stage2，继承 `QuaRotProcessor`，使用 Stage1 优化后的旋转矩阵覆盖原始旋转。
40-- `HadamardOptimizer`：用于迭代优化 Hadamard 旋转以获得正交极因子。
41- 
42-#### 处理流程时序图
43- 
44-```mermaid
45-sequenceDiagram
46- participant User
47- participant MultiStageQuantServer
48- participant AdaptRotationStage1
49- participant AdaptRotationStage2
50- participant QuaRotInterface
51- participant HadamardOptimizer
52- participant Context
53- 
54- User->>MultiStageQuantServer: 启动多阶段量化服务<br>apiversion: modelslim_v1_multi_stage
55- 
56- Note over MultiStageQuantServer,QuantProcessor: =========== Stage1：旋转矩阵优化 ===========
57- MultiStageQuantServer->>AdaptRotationStage1: 执行 Stage1
58- 
59- Note over AdaptRotationStage1: pre_run
60- AdaptRotationStage1->>QuaRotInterface: 获取融合与维度信息
61- QuaRotInterface-->>AdaptRotationStage1: 融合映射、隐藏层维度
62- AdaptRotationStage1->>AdaptRotationStage1: 初始化初始旋转并融合归一化
63- 
64- Note over AdaptRotationStage1: process
65- loop 逐层调度
66- AdaptRotationStage1->>AdaptRotationStage1: 注册前向钩子并收集激活
67- end
68- 
69- Note over AdaptRotationStage1: post_run
70- AdaptRotationStage1->>AdaptRotationStage1: 汇总激活并按采样数得到激活矩阵
71- AdaptRotationStage1->>HadamardOptimizer: 基于激活矩阵与初始旋转求解最优正交矩阵
72- HadamardOptimizer->>HadamardOptimizer: 基于 SVD/正交普鲁克迭代求解
73- HadamardOptimizer-->>AdaptRotationStage1: 优化后的旋转矩阵
74- AdaptRotationStage1->>Context: 写入优化后的旋转矩阵
75- AdaptRotationStage1-->>MultiStageQuantServer: Stage1 完成
76- 
77- Note over MultiStageQuantServer,QuantProcessor: =========== Stage2：应用优化旋转 ===========
78- MultiStageQuantServer->>AdaptRotationStage2: 执行 Stage2
79- 
80- Note over AdaptRotationStage2: pre_run
81- AdaptRotationStage2->>Context: 读取优化后的旋转矩阵
82- Context-->>AdaptRotationStage2:
83- AdaptRotationStage2->>QuaRotInterface: 获取旋转相关信息
84- QuaRotInterface-->>AdaptRotationStage2:
85- AdaptRotationStage2->>AdaptRotationStage2: 用优化后旋转矩阵覆盖原始旋转并执行层融合与旋转操作
86- 
87- Note over AdaptRotationStage2: process
88- loop 逐层
89- AdaptRotationStage2->>AdaptRotationStage2: 执行 QuaRotProcessor 逻辑
90- end
91- Note over AdaptRotationStage2: post_run
92- AdaptRotationStage2->>AdaptRotationStage2: 执行 QuaRotProcessor 逻辑
93- 
94- 
95- AdaptRotationStage2-->>MultiStageQuantServer: Stage2 完成
96- 
97- MultiStageQuantServer-->>User: 多阶段量化服务完成
98-```
99- 
100-#### Stage1 处理流程
101- 
102-Stage1 在 prior 阶段运行，整体流程为：
103- 
104-- **准备与融合**：从适配器获取 LayerNorm 与 Linear 融合映射，创建初始 Hadamard 旋转矩阵，并执行 LayerNorm 与 Linear 的融合。
105-- **激活收集**：为匹配 `layer_type` 的 Linear 层注册前向钩子，在 Runner 调度前向传播时收集校准数据上的激活。
106-- **优化与传递**：汇总各层激活并按 `max_samples` 采样，运行 Hadamard 优化得到优化后的旋转矩阵，将结果写入 Context，供 Stage2 使用。
107- 
108-#### Stage2 处理流程
109- 
110-Stage2 在主阶段运行，与 QuaRot 共用同一套层融合、旋转流程：
111- 
112-- **读取与覆盖**：从 Context 读取 Stage1 得到的优化旋转矩阵，覆盖 QuaRot 中对应维度的旋转矩阵（替代默认 Hadamard）。
113-- **执行旋转**：按 QuaRot 的 preprocess / post_run 等流程，逐层执行层融合与旋转，完成模型旋转矩阵插入操作。
114- 
115-## 适用要求
116- 
117-- **模型架构要求**：模型必须支持 `AdaptRotationInterface`（继承 `QuaRotInterface`，并实现 `get_hidden_dim()`）。
118-- **多阶段配置**：算法配置时需注意 Stage1 通常在 prior 阶段运行，Stage2 通常在主阶段配合量化处理器执行。
119-- **Context 要求**：Stage1 必须在 ContextManager 下运行，以便将 `adapted_matrix` 传递给 Stage2。
120-- **量化配置要求**：`quant_dtype` 应与下游量化（如 linear_quant/autoround_quant）的激活值类型一致（w4a4 用 `int4`，w8a8 用 `int8`）。
121- 
122-## 功能介绍
123- 
124-### YAML 配置示例
125- 
126-作为 Processor 使用，需配置 `type: "adapt_rotation"` 和 `stage: 1` 或 `stage: 2`，不同阶段的配置参数有所差异。Stage1 置于 `spec.prior` 的 process 列表中并配置该阶段的 dataset；Stage2 置于 `spec.process` 主流程列表中。YAML配置示例如下：
127- 
128-**多阶段示例（prior + 主阶段）**：
129- 
130-```yaml
131-apiversion: modelslim_v1
132- 
133-default_w4a4_dynamic: &default_w4a4_dynamic
134- weight:
135- scope: "per_group"
136- dtype: "int4"
137- symmetric: True
138- method: "autoround"
139- ext:
140- group_size: 256
141- scale_dtype: "bfloat16"
142- act:
143- scope: "per_token"
144- dtype: "int4"
145- symmetric: True
146- method: "minmax"
147- 
148-spec:
149- prior:
150- - process:
151- - type: "adapt_rotation"
152- stage: 1
153- layer_type: ["up_proj"] # 根据模型需要进行选择，需考虑旋转影响的线性层
154- steps: 20
155- quant_dtype: "int4"
156- block_size: -1
157- max_samples: 2048
158- dataset: boolq.jsonl
159- 
160- process:
161- - type: "adapt_rotation"
162- stage: 2
163- online: False
164- block_size: -1
165- max_tp_size: 1
166- 
167- - type: "autoround_quant"
168- iters: 400
169- enable_round_tuning: true
170- strategies:
171- - qconfig: *default_w4a4_dynamic
172- include:
173- - "*.up_proj"
174- - "*.gate_proj"
175- 
176- save:
177- - type: "ascendv1_saver"
178- part_file_size: 4
179- 
180- dataset: mix_calib.jsonl
181-```
182- 
183-### YAML 配置字段详解
184- 
185-#### Stage1 字段
186- 
187-| 字段名 | 作用 | 类型 | 说明 | 默认值 |
188-|--------|------|------|------|--------|
189-| type | 处理器类型标识 | `string` | 固定为 `"adapt_rotation"` | - |
190-| stage | 阶段标识 | `int` | 固定为 `1` | - |
191-| steps | 迭代优化步数 | `int` | Hadamard 优化最大迭代次数 | `20` |
192-| quant_dtype | 量化激活类型 | `string` | `"int4"` 或 `"int8"`，应与下游量化中的 act.dtype 一致 | `"int4"` |
193-| layer_type | 收集激活的层名子串 | `array[string]` | 用于匹配 Linear 层名称，如 `["up_proj"]` | `["up_proj"]` |
194-| block_size | 块大小 | `int` | 旋转矩阵块大小，取值为大于 0 的 2 的幂或 -1；当设置为 -1 时表示 hidden_dim（不分块） | `-1` |
195-| max_samples | 每层最大采样数 | `int` | 控制激活采样数量 | `2048` |
196- 
197-#### Stage2 字段
198- 
199-| 字段名 | 作用 | 类型 | 说明 | 默认值 |
200-|--------|------|------|------|--------|
201-| type | 处理器类型标识 | `string` | 固定为 `"adapt_rotation"` | - |
202-| stage | 阶段标识 | `int` | 固定为 `2` | - |
203-| online | 是否启用“在线旋转” | `bool` | 当为 `True` 时，在量化过程动态注入旋转计算 | `False` |
204-| block_size | 块大小 | `int` | 旋转矩阵块大小，取值为大于 0 的 2 的幂或 -1；当设置为 -1 时表示 hidden_dim（不分块） | `-1` |
205-| down_proj_online_layers | 应用在线旋转的 down 层索引 | `array[int]` | 应用在线旋转的 down 层索引，仅当 `online=True` 时生效 | `[]` |
206-| max_tp_size | 最大张量并行度（在线旋转分块规模） | `int` | 仅当 `online=True` 时生效，用于在线旋转矩阵构造与并行相关的分块参数，需为 `1` 或正的 2 的幂 | `4` |
207- 
208-## 模型适配
209- 
210-Adapt Rotation 的模型适配要求：
211- 
212-- **AdaptRotationInterface**：必须实现（继承 `QuaRotInterface`，并实现 `get_hidden_dim()`）。Stage1 会生成并优化 `hidden_dim` 维度的旋转矩阵，把结果写入 `ctx["adapt_rotation"].state["adapted_matrix"]`；Stage2 复用 QuaRot 的融合/旋转流程，并用该矩阵覆盖对应维度的默认旋转。
213-- **LAOSOnlineRotationInterface**：仅在 Stage2 配置 `online: True` 时需要实现。
214- 
215-其中与 `QuaRotInterface` 相关的通用适配步骤，可参考 [QuaRot 模型适配](../quarot/quarot.md#模型适配)。
216- 
217-## FAQ
218- 
219-### Stage1 未收集到激活
220- 
221-**现象**：`act_dict is empty`，AdaptRotation stage1 未收集到任何激活。
222- 
223-**解决方案**：检查 `layer_type` 是否与模型中的 Linear 层名称匹配，例如 `up_proj`、`gate_proj` 等。
224- 
225-### Context 为空
226- 
227-**现象**：Stage2 无法获取 `adapted_matrix`，日志提示 `context is None` 或 `no adapted_matrix in context`。
228- 
229-**解决方案**：确保 Stage1 在 prior 阶段运行，且配置了 `ContextManager`。Stage1 与 Stage2 必须在同一量化流程中按顺序执行。
230- 
231-### quant_dtype 与下游量化不一致
232- 
233-**现象**：旋转优化使用的量化类型与下游量化阶段不同，导致精度下降。
234- 
235-**解决方案**：将 Stage1 的 `quant_dtype` 设置为与下游 `qconfig.act.dtype` 一致，如 w4a4 用 `int4`，w8a8 用 `int8`。
236- 
237-### MoE 模型执行该算法速度很慢
238- 
239-**现象**：当模型为 MoE 结构时，运行该处理器后速度明显变慢，Stage1 的激活收集与 Hadamard 优化耗时显著增加。
240- 
241-**解决方案**：MoE 的专家通常包含大量“非共享”的线性层参数；如果 `layer_type` 的匹配范围落到了专家非共享部分，就会导致需要收集激活并进行旋转优化的线性层数量急剧上升，从而显著拉长优化时间。检查并调整 `layer_type`，尽量只选择共享层而不是专家非共享线性层。
Adocs/zh/knowledge_base/quantization_algorithms/adapt_rotation/term_adapt_rotation.md+164-0
@@ -0,0 +1,164 @@
1+# Adapt Rotation 自适应旋转优化算法词条
2+ 
3+> **词条类别**：离群值抑制算法
4+> **英文名称**：Adapt Rotation
5+> **英文缩写**：AdaptRotation
6+> **应用领域**：大语言模型量化压缩、低比特量化精度优化
7+> **msModelSlim 实现**：`msmodelslim/processor/adapt_rotation/`
8+ 
9+---
10+ 
11+## 1. 概述
12+ 
13+Adapt Rotation（自适应旋转优化）是一种用于大语言模型量化的离群值抑制算法，属于 [QuaRot](../quarot/term_quarot.md) 的扩展。它以校准数据驱动的方式，在固定 Hadamard 矩阵的基础上通过迭代优化学习正交旋转矩阵，使变换后的激活值在量化时具有更小的重构误差，从而进一步抑制激活离群值、提升低比特量化精度。其核心特征是：正交变换保证计算等价、数据驱动优化、采用两阶段（Stage1 优化 / Stage2 应用）流程。
14+ 
15+---
16+ 
17+## 2. 词条介绍
18+ 
19+[QuaRot](../quarot/term_quarot.md) 使用固定的 Hadamard 矩阵对权重与激活施加正交旋转以均衡各通道数值范围，但固定的 Hadamard 矩阵未必与特定模型的激活分布最匹配。Adapt Rotation 观察到，若旋转矩阵能针对校准数据迭代优化，则变换后的激活在量化-反量化后的重构误差更小。因此它在 QuaRot 基础上引入数据驱动的旋转优化，为解决固定旋转矩阵与目标模型激活分布不匹配的问题提供了更优选择。
20+ 
21+---
22+ 
23+## 3. 原理
24+ 
25+### 1. 核心思想
26+ 
27+Adapt Rotation 的核心思想是“用数据驱动的方式优化正交旋转”：给定初始 Hadamard 矩阵 $H$ 与校准激活数据，通过迭代优化学习一个可优化的正交矩阵 $R$，使变换后的旋转矩阵 $H_{\text{adapted}} = H \cdot R$ 在给定激活数据上的量化-反量化重构误差最小。由于 $R$ 为正交矩阵，变换前后模型计算等价。
28+ 
29+### 2. 数学描述
30+ 
31+设初始 Hadamard 矩阵为 $H$，学习得到的正交旋转为 $R$，则变换后的旋转矩阵为：
32+ 
33+$$
34+H_{\text{adapted}} = H \cdot R
35+$$
36+ 
37+其中 $R$ 为正交矩阵（满足 $R^T R = I$），通过 Newton-Schulz 迭代对 $A^T B$ 求正交极因子得到，累积旋转记为 $R_{\text{acc}} = R_{\text{acc}} \cdot R_{\text{step}}$。优化目标为最小化变换后激活值经 per-token 对称量化-反量化后的重构损失。
38+ 
39+- $H$：初始 Hadamard 矩阵
40+- $R$：迭代学习得到的正交旋转矩阵
41+- $H_{\text{adapted}}$：优化后的旋转矩阵，满足正交性，保持计算等价
42+- $A$、$B$：Newton-Schulz 迭代中用于求解正交极因子的矩阵
43+- $R_{\text{acc}}$：累积旋转矩阵
44+ 
45+### 3. 关键性质
46+ 
47+- **计算等价性**：正交旋转不改变矩阵乘法的数学结果，不引入额外推理误差。
48+- **数据驱动优化**：旋转矩阵针对校准数据迭代优化，而非固定 Hadamard。
49+- **两阶段流程**：Stage1 优化旋转矩阵，Stage2 将优化结果应用到 QuaRot 流程。
50+- **适配器依赖**：依赖 `AdaptRotationInterface`（继承 `QuaRotInterface` 并实现 `get_hidden_dim()`）。
51+ 
52+---
53+ 
54+## 4. 流程示意
55+ 
56+> 以下为本算法在 msModelSlim 中的简化流程概览。
57+ 
58+```mermaid
59+flowchart LR
60+ A[校准数据] --> B[Stage1 收集激活]
61+ B --> C[Hadamard 优化求正交极因子]
62+ C --> D[写入 Context 传递旋转矩阵]
63+ D --> E[Stage2 应用优化旋转]
64+ E --> F[层融合与旋转]
65+```
66+ 
67+---
68+ 
69+## 5. 在 msModelSlim 中的实现
70+ 
71+### 1. 实现位置
72+ 
73+算法在 `msmodelslim/processor/adapt_rotation/` 目录下实现，核心类包括：`AdaptRotationProcessor`（顶层处理器，按 `stage` 分发）、`AdaptRotationStage1Processor`（收集激活并优化旋转矩阵）、`AdaptRotationStage2Processor`（继承 `QuaRotProcessor`，应用优化后的旋转矩阵）与 `HadamardOptimizer`（迭代优化 Hadamard 旋转以求正交极因子）。
74+ 
75+### 2. 处理流程
76+ 
77+- **Stage1（prior 阶段）**：从适配器获取 LayerNorm 与 Linear 融合映射，创建初始 Hadamard 旋转矩阵并执行融合；为匹配 `layer_type` 的 Linear 层注册前向钩子收集激活；按 `max_samples` 采样后运行 Hadamard 优化得到优化后的旋转矩阵，写入 Context 供 Stage2 使用。
78+- **Stage2（主阶段）**：从 Context 读取 Stage1 得到的优化旋转矩阵，覆盖 QuaRot 中对应维度的旋转矩阵（替代默认 Hadamard），复用 QuaRot 的层融合与旋转流程逐层执行。
79+ 
80+### 3. 配置示例
81+ 
82+> 以下为多阶段 YAML 配置片段，Stage1 置于 `spec.prior`、Stage2 置于 `spec.process`。
83+ 
84+```yaml
85+spec:
86+ prior:
87+ - process:
88+ - type: "adapt_rotation"
89+ stage: 1
90+ layer_type: ["up_proj"]
91+ steps: 20
92+ quant_dtype: "int4"
93+ block_size: -1
94+ max_samples: 2048
95+ dataset: boolq.jsonl
96+ 
97+ process:
98+ - type: "adapt_rotation"
99+ stage: 2
100+ online: False
101+ block_size: -1
102+ max_tp_size: 1
103+```
104+ 
105+**字段说明**：
106+ 
107+| 字段名 | 作用 | 说明 |
108+| --- | --- | --- |
109+| type | 处理器类型标识 | 固定为 `"adapt_rotation"`。 |
110+| stage | 阶段标识 | Stage1 固定为 `1`，Stage2 固定为 `2`。 |
111+| steps | 迭代优化步数 | Hadamard 优化最大迭代次数，默认 `20`。 |
112+| quant_dtype | 量化激活类型 | `"int4"` 或 `"int8"`，应与下游量化的 `act.dtype` 一致。 |
113+| layer_type | 收集激活的层名子串 | 用于匹配 Linear 层名称，如 `["up_proj"]`。 |
114+| block_size | 旋转矩阵块大小 | 大于 0 的 2 的幂或 `-1`（表示 hidden_dim，不分块）。 |
115+| max_samples | 每层最大采样数 | 控制激活采样数量，默认 `2048`。 |
116+| online | 在线旋转开关 | 仅 Stage2 生效，`True` 时在量化过程动态注入旋转计算。 |
117+| max_tp_size | 最大张量并行度 | 仅 Stage2 在线旋转时生效，需为 `1` 或正的 2 的幂。 |
118+ 
119+### 4. 模型适配接口
120+ 
121+模型适配需实现 `AdaptRotationInterface`（继承 `QuaRotInterface`，并额外实现 `get_hidden_dim()`）：
122+ 
123+- **Stage1**：生成并优化 `hidden_dim` 维度的旋转矩阵，写入 `ctx["adapt_rotation"].state["adapted_matrix"]`。
124+- **Stage2**：复用 QuaRot 的融合/旋转流程，从 Context 读取该矩阵覆盖对应维度的默认旋转。
125+- **在线旋转**：仅在 Stage2 配置 `online: True` 时需额外实现 `LAOSOnlineRotationInterface`。
126+- **通用适配**：与 `QuaRotInterface` 相关的通用适配步骤参考《[QuaRot 词条](../quarot/term_quarot.md)》。
127+ 
128+---
129+ 
130+## 6. 适用场景与限制
131+ 
132+### 1. 适用场景
133+ 
134+- 需要比固定 Hadamard 旋转更优的离群值抑制效果、低比特量化的场景。
135+- 作为 [AutoRound](../autoround/term_autoround.md) 等低比特量化算法的前置离群值抑制步骤。
136+ 
137+### 2. 使用限制
138+ 
139+- 模型必须实现 `AdaptRotationInterface`（依赖 `QuaRotInterface` 并实现 `get_hidden_dim()`）。
140+- Stage1 必须在 ContextManager 下运行，以便将 `adapted_matrix` 传递给 Stage2。
141+- Stage1 的 `quant_dtype` 应与下游量化（如 `linear_quant`/`autoround_quant`）的激活值类型一致（w4a4 用 `int4`，w8a8 用 `int8`）。
142+- MoE 模型若 `layer_type` 匹配范围落入专家非共享线性层，激活收集与优化耗时会显著增加。
143+ 
144+---
145+ 
146+## 7. 关联流程
147+ 
148+- 《[一键量化 (V1)](../../../user_guide/usage_quick_quantization.md)》：可集成离群值抑制前置步骤。
149+- 《[量化精度调优指南](../../../user_guide/process_quantization_precision_tuning.md)》：精度不达标时可考虑启用本算法。
150+ 
151+---
152+ 
153+## 8. 关联词条
154+ 
155+- [QuaRot](../quarot/term_quarot.md)：上位概念，本算法在 QuaRot 基础上优化旋转矩阵。
156+- [SmoothQuant](../smooth_quant/term_smooth_quant.md)：对比算法，采用通道级缩放而非正交旋转抑制离群值。
157+- [AutoRound](../autoround/term_autoround.md)：配套术语，常在本算法处理后接 AutoRound 权重量化。
158+- [MinMax](../minmax/term_minmax.md)：应用对象，旋转后的激活值更易于 MinMax 量化。
159+ 
160+---
161+ 
162+## 9. 参考资料
163+ 
164+1. 《Adapt Rotation 使用指南》([./usage_adapt_rotation.md](./usage_adapt_rotation.md))
Adocs/zh/knowledge_base/quantization_algorithms/adapt_rotation/usage_adapt_rotation.md+152-0
@@ -0,0 +1,152 @@
1+# Adapt Rotation 使用指南
2+ 
3+## 1. 适用范围
4+ 
5+本流程适用于在 msModelSlim 中使用 Adapt Rotation（自适应旋转优化）离群值抑制算法。Adapt Rotation 作为 `type: "adapt_rotation"` 处理器，在 [QuaRot](../quarot/term_quarot.md) 基础上通过数据驱动优化旋转矩阵，用于提升低比特（如 W4A4）量化精度。
6+ 
7+适用角色：算法工程师、模型部署工程师
8+ 
9+适用场景：
10+ 
11+- 需要对激活离群值做更精细抑制、进一步提升低比特量化精度的场景。
12+- 需要以两阶段流程（Stage1 优化 / Stage2 应用）完成旋转配置的场景。
13+ 
14+不适用场景：
15+ 
16+- 目标模型未实现 `AdaptRotationInterface`（无法收集激活或应用优化旋转）。
17+ 
18+## 2. 流程关系与前置条件
19+ 
20+**上级流程**：模型适配与验证通过后、配置量化 YAML 阶段，作为离群值抑制前置处理器集成。
21+ 
22+**前置条件**：
23+ 
24+- 已安装兼容版本的 msModelSlim 工具（详见《[msModelSlim 工具安装指南](../../../install_guide/install_guide.md)》）。
25+- 目标 `model_type` 的适配器已实现 `AdaptRotationInterface`（含 `get_hidden_dim()`）。
26+- 已准备好 Stage1 所需的校准数据集。
27+ 
28+**后续操作**：Stage2 应用优化旋转后，继续执行下游量化（如 `autoround_quant`）、保存与部署。
29+ 
30+## 3. 输入和交付件
31+ 
32+| 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 |
33+| --- | --- | --- | --- | --- |
34+| 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被目标 Transformers 版本加载 |
35+| 输入 | 校准数据集 | 工具默认或用户指定 | JSONL 格式，每条含文本 prompt | 可被工具加载并完成前向推理 |
36+| 交付件 | 优化后的旋转矩阵 | 上下文机制（Context） | Stage1 写入 `ctx["adapt_rotation"].state["adapted_matrix"]` | 可被 Stage2 读取并覆盖默认旋转 |
37+| 交付件 | 应用旋转后的模型 | 量化流程输出 | 完成层融合与旋转的模型 | 可继续执行下游量化 |
38+ 
39+## 4. 流程总览
40+ 
41+```mermaid
42+flowchart LR
43+ A[准备模型与校准集] --> B[Stage1 收集激活并优化]
44+ B --> C[写入 Context 传递旋转矩阵]
45+ C --> D[Stage2 应用优化旋转]
46+ D --> E[下游量化与保存]
47+```
48+ 
49+## 5. 操作步骤
50+ 
51+### 步骤 1：确认适配器实现分析接口
52+ 
53+**目标**：确认目标 `model_type` 的适配器支持 Adapt Rotation 两阶段流程。
54+ 
55+**操作**：
56+ 
57+1. 确认适配器实现了 `AdaptRotationInterface`（继承 `QuaRotInterface` 并实现 `get_hidden_dim()`）。
58+2. 若需要在线旋转，确认适配器实现了 `LAOSOnlineRotationInterface`。
59+3. 确认 Stage1 在 `ContextManager` 下运行，以便将 `adapted_matrix` 传递给 Stage2。
60+ 
61+各接口的具体约定，请参阅《[Adapt Rotation 词条](./term_adapt_rotation.md)》。
62+ 
63+**输出**：适配器接口确认。
64+ 
65+### 步骤 2：配置并执行 Stage1 旋转优化
66+ 
67+**目标**：基于校准数据优化旋转矩阵。
68+ 
69+**操作**：
70+ 
71+1. 在 YAML 的 `spec.prior` 中配置 `type: "adapt_rotation"`、`stage: 1` 及该阶段的 `dataset`。
72+2. 按需设置 `layer_type`、`steps`、`quant_dtype`、`block_size`、`max_samples` 等参数。
73+3. 确保 Stage1 的 `quant_dtype` 与下游量化的 `act.dtype` 一致（w4a4 用 `int4`，w8a8 用 `int8`）。
74+ 
75+```yaml
76+spec:
77+ prior:
78+ - process:
79+ - type: "adapt_rotation"
80+ stage: 1
81+ layer_type: ["up_proj"]
82+ steps: 20
83+ quant_dtype: "int4"
84+ block_size: -1
85+ max_samples: 2048
86+ dataset: boolq.jsonl
87+```
88+ 
89+**输出**：优化后的旋转矩阵写入 Context。
90+ 
91+### 步骤 3：配置并执行 Stage2 应用旋转
92+ 
93+**目标**：将优化后的旋转矩阵应用到模型并继续量化流程。
94+ 
95+**操作**：
96+ 
97+1. 在 YAML 的 `spec.process` 中配置 `type: "adapt_rotation"`、`stage: 2`。
98+2. 按需设置 `online`、`block_size`、`max_tp_size` 等参数。
99+3. 确认 Stage1 与 Stage2 在同一量化流程中按顺序执行。
100+ 
101+```yaml
102+ process:
103+ - type: "adapt_rotation"
104+ stage: 2
105+ online: False
106+ block_size: -1
107+ max_tp_size: 1
108+```
109+ 
110+**输出**：完成层融合与旋转的模型。
111+ 
112+### 步骤 4：执行下游量化并验收
113+ 
114+**目标**：完成量化、保存并验证精度。
115+ 
116+**操作**：
117+ 
118+1. 在 Stage2 之后接下游量化处理器（如 `autoround_quant`）。
119+2. 配置 `save` 阶段保存量化模型。
120+3. 在验证集上评估量化精度，若不达标则调整 `layer_type`、`steps` 等参数后重跑。
121+ 
122+**输出**：量化模型及精度验收结果。
123+ 
124+## 6. 验收条件
125+ 
126+- Stage1 能收集到非空激活并成功输出优化旋转矩阵。
127+- Stage2 能读取 `adapted_matrix` 并完成层融合与旋转。
128+- 量化流程执行成功，精度满足业务要求。
129+ 
130+## 7. 异常处置
131+ 
132+- **Stage1 未收集到激活**：`layer_type` 未匹配到模型中的 Linear 层，调整 `layer_type`（如 `up_proj`、`gate_proj`）。
133+- **Context 为空**：Stage1 未在 prior 阶段运行或未配置 `ContextManager`，确保两阶段在同一流程中顺序执行。
134+- **quant_dtype 与下游量化不一致**：将 Stage1 的 `quant_dtype` 设置为与下游 `qconfig.act.dtype` 一致。
135+- **MoE 模型执行缓慢**：缩小 `layer_type` 匹配范围，尽量只选择共享层而非专家非共享线性层。
136+ 
137+## 8. 术语
138+ 
139+| 术语 | 简述 | 链接 |
140+| --- | --- | --- |
141+| Adapt Rotation | 数据驱动优化旋转矩阵的离群值抑制算法 | [Adapt Rotation 词条](./term_adapt_rotation.md) |
142+| Hadamard 优化 | 通过 Newton-Schulz 迭代求正交极因子以优化旋转矩阵 | [Adapt Rotation 词条](./term_adapt_rotation.md) |
143+| AdaptRotationInterface | 模型适配器需实现的接口（含 `get_hidden_dim()`） | [Adapt Rotation 词条](./term_adapt_rotation.md) |
144+| QuaRot | Adapt Rotation 的上位算法 | [QuaRot 词条](../quarot/term_quarot.md) |
145+ 
146+## 9. 接口文档列表
147+ 
148+| 接口或能力 | 简述 | 链接 |
149+| --- | --- | --- |
150+| `type: "adapt_rotation"` stage 1 | 收集激活并优化旋转矩阵 | [Adapt Rotation 词条](./term_adapt_rotation.md) |
151+| `type: "adapt_rotation"` stage 2 | 应用优化后的旋转矩阵 | [Adapt Rotation 词条](./term_adapt_rotation.md) |
152+| `AdaptRotationInterface` | 模型适配器需实现的接口 | [Adapt Rotation 词条](./term_adapt_rotation.md) |
Ddocs/zh/knowledge_base/quantization_algorithms/attention_mse/attention_mse.md+0-84
@@ -1,84 +0,0 @@
1-# Attention MSE（mse）：敏感层分析算法说明
2- 
3-## 简介
4- 
5-- **概述**：`mse`（均方误差，Mean Squared Error）用于**attn**范围分析：分别使用浮点权重与量化权重执行前向推理，对同一 attention 模块的输出计算均方误差，输出**注意力模块粒度**排序。
6-- **核心思想**：直接度量注意力子系统在量化权重下的输出漂移；数值越大表示该注意力层对权重量化越敏感。
7- 
8-## 使用前准备
9- 
10-安装 msModelSlim 工具，详情请参见《[msModelSlim工具安装指南](../../../install_guide/install_guide.md)》。
11- 
12-## 原理
13- 
14-1. 对同一校准样本，分别使用**浮点权重**与**量化权重**执行前向，在 attention 模块输出处采集张量。
15-2. 对同一层、同一样本的浮点与量化输出计算 MSE：
16- 
17- $$\text{MSE} = \frac{1}{n} \sum_{i=1}^{n} (y_{\text{float}}^{(i)} - y_{\text{quant}}^{(i)})^2$$
18- 
19-3. **解读**：MSE 越大，该 attention 模块对当前量化配置越敏感。
20- 
21-## 适用要求
22- 
23-- **推荐场景**：需要对 **Attention** 结构做权重量化或评估其敏感度时。
24-- **模型适配（必选）**：对应 `model_type` 的模型适配器必须实现 `AttentionMSEAnalysisInterface`，提供模块类名与输出提取函数；未实现会在分析阶段报错。
25-- **model_type**：工具当前仅实现了以下模型的接口适配，其他 `model_type` 会报错或需自行在适配器中实现接口。
26- 
27-| model_type |
28-| ---------------- |
29-| DeepSeek-V3 |
30-| DeepSeek-V3-0324 |
31-| DeepSeek-R1 |
32-| DeepSeek-R1-0528 |
33-| DeepSeek-V3.1 |
34- 
35-## 功能介绍
36- 
37-### 使用说明
38- 
39-本分析依赖工具在 attention 子模块上挂 hook 并读取其前向输出；不同模型的 attention 类名与 `forward` 返回值形态不一致，无法由框架统一推断。因此须在目标 `model_type` 的**模型适配器**中实现 `AttentionMSEAnalysisInterface`（声明待 hook 的类名、以及如何从 `forward` 返回值中取出用于计算 MSE 的张量），`msmodelslim analyze attn --metrics mse` 方可在该模型上使用。以下为接口约定，未实现或实现与模型结构不一致时会在分析阶段报错。
40- 
41-```python
42-class AttentionMSEAnalysisInterface(ABC):
43- @abstractmethod
44- def get_attention_module_cls(self) -> str:
45- ...
46- 
47- @abstractmethod
48- def get_attention_output_extractor(self) -> Callable[[Union[tuple, torch.Tensor]], torch.Tensor]:
49- ...
50-```
51- 
52-| 方法 | 作用 |
53-|------|------|
54-| `get_attention_module_cls` | 返回待挂 hook 的 attention 模块类名字符串 |
55-| `get_attention_output_extractor` | 从 `forward` 返回值中取出用于计算 MSE 的张量 |
56- 
57-### 命令行示例
58- 
59-```bash
60-msmodelslim analyze attn \
61- --model_type DeepSeek-V3 \
62- --model_path ${model_path} \
63- --metrics mse \
64- --calib_dataset ${calib_dataset} \
65- --topk 15 \
66- --device npu
67-```
68- 
69-### 命令行参数说明
70- 
71-| 参数 | 说明 |
72-|------|------|
73-| `attn` | 注意力结构敏感度分析 |
74-| `--metrics` | 指定分析算法，取值为 `mse` 时使用本算法 |
75- 
76-完整参数见 [Attention 敏感层分析使用指南 - 命令行预览](../../../user_guide/usage_sensitive_attn_analysis.md#命令行预览)。
77- 
78-## FAQ
79- 
80-### 报错提示未实现 `AttentionMSEAnalysisInterface`？
81- 
82-**现象**: 运行 `analyze attn --metrics mse` 时报错，提示未实现 `AttentionMSEAnalysisInterface`。
83- 
84-**解决方案**: 当前 `model_type` 的适配器未接入该分析路径；请换用支持列表中的模型类型，或在适配器中按接口实现 hook 类名与输出提取逻辑。
Adocs/zh/knowledge_base/quantization_algorithms/attention_mse/term_attention_mse.md+126-0
@@ -0,0 +1,126 @@
1+# Attention MSE 敏感层分析算法词条
2+ 
3+> **词条类别**：敏感层分析算法
4+> **英文名称**：Attention MSE
5+> **英文缩写**：mse
6+> **应用领域**：量化敏感层分析、Attention 权重量化
7+> **msModelSlim 实现**：`msmodelslim/processor/analysis/`
8+ 
9+---
10+ 
11+## 1. 概述
12+ 
13+Attention MSE（`mse`）是 `msmodelslim analyze` 中 `attn` 范围分析的一种度量算法。它分别使用浮点权重与量化权重执行前向推理，对同一 attention 模块的输出计算均方误差（MSE），输出注意力模块粒度的敏感度排序，与 [MSE Layer Wise](../mse_layer_wise/term_mse_layer_wise.md) 等同为基于 MSE 的敏感层分析指标。其核心特征是：直接度量注意力子系统在量化权重下的输出漂移、依赖适配器接口。
14+ 
15+---
16+ 
17+## 2. 词条介绍
18+ 
19+对 Attention 结构做权重量化或评估其敏感度时，需要直接度量注意力子系统在量化权重下的输出漂移。Attention MSE 通过分别用浮点与量化权重执行前向，在 attention 模块输出处对比两路张量，用 MSE 刻画该模块对权重量化的敏感程度。
20+ 
21+---
22+ 
23+## 3. 原理
24+ 
25+### 1. 核心思想
26+ 
27+Attention MSE 的核心思想是“直接度量输出漂移”：对同一校准样本，分别使用浮点权重与量化权重执行前向，在 attention 模块输出处采集张量，计算两路输出的均方误差；MSE 越大，表示该 attention 模块对当前量化配置越敏感。
28+ 
29+### 2. 数学描述
30+ 
31+对同一层、同一样本的浮点与量化输出计算 MSE：
32+ 
33+$$
34+\text{MSE} = \frac{1}{n} \sum_{i=1}^{n} (y_{\text{float}}^{(i)} - y_{\text{quant}}^{(i)})^2
35+$$
36+ 
37+- $y_{\text{float}}$：使用浮点权重的 attention 输出
38+- $y_{\text{quant}}$：使用量化权重的 attention 输出
39+- $n$：输出元素个数
40+- $\text{MSE}$：均方误差，用于敏感度排序
41+ 
42+### 3. 关键性质
43+ 
44+- **attn 范围分析**：输出注意力模块粒度的敏感度排序。
45+- **直接度量**：直接度量注意力子系统在量化权重下的输出漂移。
46+- **适配器依赖**：需要模型适配器实现 `AttentionMSEAnalysisInterface`。
47+- **量化配置感知**：MSE 大小与当前量化配置相关。
48+ 
49+---
50+ 
51+## 4. 流程示意
52+ 
53+> 以下为本算法在 msModelSlim 中的简化流程概览。
54+ 
55+```mermaid
56+flowchart LR
57+ A[校准前向] --> B[浮点/量化双路]
58+ B --> C[计算输出 MSE]
59+ C --> D[attn 敏感度排序]
60+```
61+ 
62+---
63+ 
64+## 5. 在 msModelSlim 中的实现
65+ 
66+### 1. 实现位置
67+ 
68+Attention MSE 作为 `msmodelslim analyze` 命令的 `attn` 范围分析指标实现，位于 `msmodelslim/processor/analysis/`。
69+ 
70+### 2. 处理流程
71+ 
72+通过 `msmodelslim analyze attn --metrics mse` 命令执行：在 attention 子模块上挂 hook 并读取其前向输出，分别用浮点与量化权重执行前向，在 attention 模块输出处计算 MSE 并排序。不同模型的 attention 类名与 `forward` 返回值形态不一致，须在模型适配器中实现 `AttentionMSEAnalysisInterface`。
73+ 
74+### 3. 命令行示例
75+ 
76+```bash
77+msmodelslim analyze attn \
78+ --model_type DeepSeek-V3 \
79+ --model_path ${model_path} \
80+ --metrics mse \
81+ --calib_dataset ${calib_dataset} \
82+ --topk 15 \
83+ --device npu
84+```
85+ 
86+### 4. 模型适配接口
87+ 
88+模型适配需实现 `AttentionMSEAnalysisInterface` 接口，提供以下方法：
89+ 
90+- `get_attention_module_cls()`：返回待挂 hook 的 attention 模块类名。
91+- `get_attention_output_extractor()`：从 `forward` 返回值中取出用于计算 MSE 的张量。
92+ 
93+---
94+ 
95+## 6. 适用场景与限制
96+ 
97+### 1. 适用场景
98+ 
99+- 需要对 Attention 结构做权重量化或评估其敏感度的场景。
100+- 需要注意力模块粒度敏感度排序以辅助回退决策的场景。
101+ 
102+### 2. 使用限制
103+ 
104+- 对应 `model_type` 的模型适配器必须实现 `AttentionMSEAnalysisInterface`，提供模块类名与输出提取函数；未实现会在分析阶段报错。
105+- 工具当前仅实现 DeepSeek 系列模型的接口适配，其他 `model_type` 会报错或需自行实现。
106+ 
107+---
108+ 
109+## 7. 关联流程
110+ 
111+- 《[敏感层分析使用指南](../../../user_guide/usage_sensitive_layer_wise_analysis.md)》：本算法作为 `attn` 分析的 metrics 使用。
112+- 《[一键量化 (V1)](../../../user_guide/usage_quick_quantization.md)》：分析结果可用于辅助量化配置调优。
113+ 
114+---
115+ 
116+## 8. 关联词条
117+ 
118+- [Std](../std/term_std.md)：对比算法，同为敏感层分析指标，但用于 `linear` 范围。
119+- [MSE Layer Wise](../mse_layer_wise/term_mse_layer_wise.md)：同类算法，同为基于 MSE 的敏感层分析指标，但用于 `layer` 范围。
120+- [MSE Model Wise](../mse_model_wise/term_mse_model_wise.md)：同类算法，基于模型最终输出的 MSE 分析指标。
121+ 
122+---
123+ 
124+## 9. 参考资料
125+ 
126+1. 《Attention MSE 使用指南》([./usage_attention_mse.md](./usage_attention_mse.md))
Adocs/zh/knowledge_base/quantization_algorithms/attention_mse/usage_attention_mse.md+125-0
@@ -0,0 +1,125 @@
1+# Attention MSE 使用指南
2+ 
3+## 1. 适用范围
4+ 
5+本流程适用于在 msModelSlim 中使用 Attention MSE（`mse`）敏感层分析算法。Attention MSE 作为 `msmodelslim analyze attn` 的 metrics 指标，用于注意力模块粒度的敏感度排序。
6+ 
7+适用角色：算法工程师、模型部署工程师
8+ 
9+适用场景：
10+ 
11+- 需要对 Attention 结构做权重量化或评估其敏感度的场景。
12+- 需要注意力模块粒度敏感度排序以辅助回退决策的场景。
13+ 
14+不适用场景：
15+ 
16+- 目标 `model_type` 的适配器未实现 `AttentionMSEAnalysisInterface`（分析会报错）。
17+ 
18+## 2. 流程关系与前置条件
19+ 
20+**上级流程**：模型适配与验证通过后，定稿量化 YAML 前的敏感层分析阶段。
21+ 
22+**前置条件**：
23+ 
24+- 已安装兼容版本的 msModelSlim 工具（详见《[msModelSlim 工具安装指南](../../../install_guide/install_guide.md)》）。
25+- 已确认目标 `model_type` 的适配器实现了 `AttentionMSEAnalysisInterface`（当前支持 DeepSeek 系列）。
26+- 已准备好校准数据集。
27+ 
28+**后续操作**：根据分析结果进行 attention 层回退与 YAML 调参，进入量化流程。
29+ 
30+## 3. 输入和交付件
31+ 
32+| 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 |
33+| --- | --- | --- | --- | --- |
34+| 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被目标 Transformers 版本加载 |
35+| 输入 | 校准数据集 | 工具默认或用户指定 | JSONL 格式，每条含文本 prompt | 可被工具加载并完成前向推理 |
36+| 交付件 | 敏感层分析结果 | 命令行输出 | attention 模块粒度的 score 排序结果 | 结果可读且包含目标层 |
37+ 
38+## 4. 流程总览
39+ 
40+```mermaid
41+flowchart LR
42+ A[准备模型与校准集] --> B[执行 analyze 命令]
43+ B --> C[浮点/量化双路前向]
44+ C --> D[输出 attn 敏感度排序]
45+```
46+ 
47+## 5. 操作步骤
48+ 
49+### 步骤 1：确认适配器实现分析接口
50+ 
51+**目标**：确认目标 `model_type` 的适配器支持 `attn` 范围分析。
52+ 
53+**操作**：
54+ 
55+1. 确认适配器实现了 `AttentionMSEAnalysisInterface`。
56+2. 确认 `get_attention_module_cls()` 返回待挂 hook 的 attention 模块类名字符串。
57+3. 确认 `get_attention_output_extractor()` 能从 `forward` 返回值中取出用于计算 MSE 的张量。
58+ 
59+各方法的具体约定，请参阅《[Attention MSE 词条](./term_attention_mse.md)》。
60+ 
61+**输出**：适配器接口确认。
62+ 
63+### 步骤 2：执行敏感层分析命令
64+ 
65+**目标**：使用 `mse` 指标完成 attention 模块敏感度分析。
66+ 
67+**操作**：
68+ 
69+```bash
70+msmodelslim analyze attn \
71+ --model_type DeepSeek-V3 \
72+ --model_path ${model_path} \
73+ --metrics mse \
74+ --calib_dataset ${calib_dataset} \
75+ --topk 15 \
76+ --device npu
77+```
78+ 
79+参数说明：
80+ 
81+| 参数 | 说明 |
82+| --- | --- |
83+| `attn` | 注意力结构敏感度分析 |
84+| `--metrics` | 指定分析算法，取值为 `mse` 时使用本算法 |
85+| `--topk` | 输出的 topk 敏感层数量 |
86+ 
87+完整参数见《[敏感层分析工具使用指南参数说明](../../../user_guide/usage_sensitive_layer_wise_analysis.md#命令行预览)》。
88+ 
89+**输出**：attention 模块粒度的敏感度排序结果。
90+ 
91+### 步骤 3：解读结果并指导调参
92+ 
93+**目标**：根据敏感度排序结果辅助回退与 YAML 调参。
94+ 
95+**操作**：
96+ 
97+1. 查看排序结果，识别 MSE 较高的 attention 模块。
98+2. 结合业务精度要求确定回退阈值。
99+3. 在量化 YAML 中对敏感 attention 层配置回退或降低量化强度。
100+ 
101+**输出**：回退与调参方案。
102+ 
103+## 6. 验收条件
104+ 
105+- 分析命令执行成功并输出目标层的敏感度排序。
106+- 分析结果可用于指导量化配置调整。
107+ 
108+## 7. 异常处置
109+ 
110+- **报错提示未实现 `AttentionMSEAnalysisInterface`**：当前 `model_type` 的适配器未接入该分析路径，请换用支持列表中的模型类型（如 DeepSeek 系列），或在适配器中按接口实现 hook 类名与输出提取逻辑。
111+ 
112+## 8. 术语
113+ 
114+| 术语 | 简述 | 链接 |
115+| --- | --- | --- |
116+| Attention MSE | 基于浮点/量化双路输出的 MSE 分析算法 | [Attention MSE 词条](./term_attention_mse.md) |
117+| attn 范围分析 | 对注意力模块粒度的敏感度分析 | [敏感层分析使用指南](../../../user_guide/usage_sensitive_layer_wise_analysis.md) |
118+| AttentionMSEAnalysisInterface | 模型适配器需实现的 attn 分析接口 | [Attention MSE 词条](./term_attention_mse.md) |
119+ 
120+## 9. 接口文档列表
121+ 
122+| 接口或能力 | 简述 | 链接 |
123+| --- | --- | --- |
124+| `msmodelslim analyze attn` | 注意力结构敏感度分析命令，`--metrics mse` 启用本算法 | [Attention MSE 词条](./term_attention_mse.md) |
125+| `AttentionMSEAnalysisInterface` | 模型适配器需实现的接口 | [Attention MSE 词条](./term_attention_mse.md) |
Ddocs/zh/knowledge_base/quantization_algorithms/autoround/autoround.md+0-244
@@ -1,244 +0,0 @@
1-# AutoRound：低比特量化算法说明
2- 
3-## 简介
4- 
5-- **来源**：Intel 开发的一种基于 SignSGD 的低比特量化方法。
6-- **背景**：传统量化方法（如四舍五入）在权重量化中并非最优选择，往往会引入较大的量化误差，从而显著降低模型精度，尤其在低比特（如 4bit 及以下）量化场景中表现更为明显。
7-- **核心思想**：通过引入可学习的舍入偏移参数，结合SignSGD优化器自适应调整各权重的舍入方向，并利用温度调度策略逐步硬化舍入操作，有效降低量化重构误差，在超低比特条件下实现模型精度与压缩效率的最优平衡。
8- 
9-## 使用前准备
10- 
11-安装 msModelSlim 工具，详情请参见[《msModelSlim工具安装指南》](../../../install_guide/install_guide.md)。
12- 
13-## 原理和实现
14- 
15-### 原理
16- 
17-AutoRound 的核心思想是优化权重的舍入过程。该过程不是采用简单的四舍五入方式，而是基于 SignSGD（符号梯度下降）算法，自适应地学习每个权重的最佳舍入方向（向上或向下），并有针对性地调整缩放因子和零点。
18- 
19-**核心公式：**
20- 
21-在传统量化中，权重 W 的量化公式通常为：
22- 
23-Ŵ = s × clip(⌊W/s + zp⌉, n, m)
24- 
25-其中 s 是缩放因子，zp 是零点，n 和 m 是量化后的上下界。
26- 
27-AutoRound 在此基础之上引入了可学习的舍入偏移 V 和可选的缩放因子调整参数 α 和 β：
28- 
29-`Ŵ = s × clip(⌊W/s + zp + V⌉, n, m)`，`s = (max(W) × α - min(W) × β) / (2^bit - 1)`
30- 
31-其中 V 用于控制舍入的方向，α 和 β 用于调整缩放因子的范围。
32- 
33-**算法流程：**
34- 
35-该算法是一种逐层优化算法，对每一个decoder layer执行以下优化步骤：
36- 
37-1. **基准建立**：进行浮点前向传播，记录原始输出作为精度基准
38-2. **参数初始化**：对缩放因子、舍入偏移量进行初始化，并将其设置为可训练参数引入量化过程中
39-3. **量化重构**：执行量化-反量化操作，进行前向传播得到量化结果
40-4. **损失计算**：对比量化输出与浮点输出的差异，计算重构损失
41-5. **参数更新**：通过SignSGD优化器更新缩放因子和舍入偏移量
42-6. **迭代优化**：重复步骤1-5直至满足收敛条件或达到最大迭代次数
43-7. **最终量化**：应用迭代训练后的最优参数得到最终量化权重
44- 
45-### 实现
46- 
47-#### 代码实现
48- 
49-- 算法在 [msmodelslim/processor/quant/autoround.py](../../../../../msmodelslim/processor/quant/autoround.py) 中实现，核心类为 `AutoroundQuantProcessor`。
50- 
51-#### 初始化阶段
52- 
53- * 层配置初始化：读取量化配置，并为每个网络层分配对应的量化配置方案
54- * 参数预分配：初始化浮点输出、量化输出和最佳参数
55- 
56-#### pre_run阶段
57- 
58- * 梯度冻结：关闭所有网络层的自动梯度计算，防止在训练过程中直接优化权重
59- 
60-#### preprocess阶段（逐层循环执行）
61- 
62- * 基准输出采集：执行当前层浮点前向传播，并记录浮点输出结果作为优化基准
63- * 线性层封装：对每个线性层进行包装处理，注入可训练的缩放因子和舍入偏移参数
64- * 计算图构建：建立包含量化和反量化操作的可微计算图，支持梯度反向传播
65- 
66-#### process阶段（逐层循环执行）
67- 
68- * 训练器初始化：设置学习率、迭代次数等参数，配置SignSGD优化器
69- * 输入输出配置：使用上一层量化输出作为当前层输入，以浮点输出和量化输出的差距作为优化目标
70- * 参数优化：通过多次迭代更新缩放因子和舍入偏移，最小化重构误差
71- * 收敛监测：实时监测损失变化，达到收敛阈值或最大迭代次数时停止优化，得到最优参数
72- 
73-#### postprocess阶段（逐层循环执行）
74- 
75- * 参数应用：将优化后的量化参数应用于对应层的权重量化
76- * 解除封装：移除线性层的包装，恢复原始网络结构
77- * 前向传播：执行当前层量化后的前向传播，作为下一层的输入
78- 
79-#### post_run阶段
80- 
81- * 清理工作：移除所有模块的临时属性，完成量化流程的最终清理工作
82- 
83-## 适用要求
84- 
85-- **低比特量化**：适合极低比特量化场景中的4比特量化。
86-- **高精度需求**：在低比特条件下仍能保持较高的模型精度。
87-- **计算资源**：需要额外的优化过程，计算成本高于简单量化方法。
88-- **使用限制**：
89- - 适用于llm中的线性层量化。
90- - 需要足够的校准数据或训练迭代次数来优化参数。
91- - **低比特量化极度依赖于良好的离群值抑制算法，建议用户配合[QuaRot](../quarot/quarot.md)或[Iterative Smooth](../iterative_smooth/iterative_smooth.md)等离群值抑制方法一起使用，不建议用户（尤其是缺乏量化调优经验的基础用户）单独使用AutoRound，否则可能导致模型精度严重下降、对话输出异常或其他不可预期的行为，相关风险由用户自行承担。**
92- 
93-## 功能介绍
94- 
95-**注：算法实现包含训练过程，对NPU显存有一定的要求，仅支持NPU显存>=64G的设备。**
96- 
97-### YAML配置示例
98- 
99-作为Processor使用，YAML配置示例如下：
100- 
101-```yaml
102-# AutoRound支持混合量化，即对不同的层使用不同的量化配置，这里以 W8A8 和 W4A4 混合量化为例
103-# W8A8 动态量化配置
104-default_w8a8_dynamic: &default_w8a8_dynamic
105- weight:
106- scope: "per_group" # 权重量化范围
107- dtype: "int8" # 权重量化数据类型
108- symmetric: True # 是否启用对称量化
109- method: "autoround" # 权重量化方法：AutoRound算法，即包含参数训练的权重量化
110- ext:
111- group_size: 256 # 量化组大小，分组将在待量化nn.Linear的input_features维度进行，该值必须能够被其整除
112- scale_dtype: "bfloat16" # 缩放因子数据类型
113- act:
114- scope: "per_token" # 激活值量化范围
115- dtype: "int8" # 激活值量化数据类型
116- symmetric: True # 是否启用对称量化
117- method: "minmax" # 激活值量化方法：MinMax算法
118- 
119-# W4A4 动态量化配置模板
120-default_w4a4_dynamic: &default_w4a4_dynamic
121- weight:
122- scope: "per_group"
123- dtype: "int4"
124- symmetric: True
125- method: "autoround"
126- ext:
127- group_size: 256
128- scale_dtype: "bfloat16"
129- act:
130- scope: "per_token"
131- dtype: "int4"
132- symmetric: True
133- method: "minmax"
134- 
135- 
136-spec:
137- process:
138- - type: "autoround_quant" # 固定为 `autoround_quant`，用于指定 Processor 类型。
139- iters: 400 # 优化迭代次数
140- enable_minmax_tuning: True # 是否启用最小最大值调优
141- enable_round_tuning: True # 是否启用舍入调优
142- strategies:
143- # 策略1：除 up_proj、gate_proj 和 o_proj 层外，其余层均应用 W8A8 量化。
144- - qconfig: *default_w8a8_dynamic
145- exclude:
146- - "*.up_proj"
147- - "*.gate_proj"
148- - "*.o_proj"
149- # 策略2：对up_proj、gate_proj、o_proj层使用W4A4量化
150- - qconfig: *default_w4a4_dynamic
151- include:
152- - "*.up_proj"
153- - "*.gate_proj"
154- - "*.o_proj"
155- 
156-```
157- 
158-### YAML配置字段详解
159- 
160-| 字段名 | 作用 | 类型 | 说明 | 默认值 |
161-|--------|------|------|------|--------|
162-| type | 处理器类型标识 | `string` | 固定值，用于标识这是一个AutoRound量化处理器 | `"autoround_quant"` |
163-| iters | 优化迭代次数 | `int` | 迭代次数，必须大于0，影响优化效果和计算时间 | `10` |
164-| enable_minmax_tuning | 是否启用最小最大值调优 | `bool` | 是否启用最小最大值调优，True表示启用，False表示不启用 | `True` |
165-| enable_round_tuning | 是否启用舍入调优 | `bool` | 是否启用舍入调优，True表示启用，False表示不启用 | `True` |
166-| strategies | 量化策略配置 | `array[object]` | 用于指定量化策略，支持int4和int8混合量化策略 | [见下方详细配置](#strategies-量化策略配置) |
167- 
168-#### strategies (量化策略配置)
169- 
170-**作用**: 配置不同层的量化策略，支持混合量化。
171- 
172-| 字段名 | 作用 | 类型 | 说明 | 示例值 |
173-|--------|------|------|------|--------|
174-| qconfig | 量化配置参数 | `object` | 包含激活值量化和权重量化的详细配置 | [激活值配置](#qconfigact-激活值量化配置)、[权重量化配置](#qconfigweight-权重量化配置) |
175-| include | 包含的层 | `array[string]` | 支持通配符匹配，指定要量化的层 | `["*"]`, `["*self_attn*"]` |
176-| exclude | 排除的层 | `array[string]` | 支持通配符匹配，优先级高于include | `["*down_proj*"]` |
177- 
178-#### qconfig.act (激活值量化配置)
179- 
180-**作用**: 配置激活值的量化参数。
181- 
182-| 参数名 | 作用 | 可选值 | 说明 | 默认值 |
183-|--------|------|--------|------|--------|
184-| scope | 量化范围 | `"per_token"` | 每个token独立参数（动态量化），AutoRound目前仅支持per_token | `"per_token"` |
185-| dtype | 量化数据类型 | `"int8"`, `"int4"` | 8位/4位整数量化 | `"int8"` |
186-| symmetric | 是否对称量化 | `True` | 对称量化，零点为0，AutoRound激活值量化仅支持对称量化 | `True` |
187-| method | 量化方法 | `"minmax"` | 激活值量化方法：MinMax算法 | `"minmax"` |
188- 
189-#### qconfig.weight (权重量化配置)
190- 
191-**作用**: 配置权重的量化参数。
192- 
193-| 参数名 | 作用 | 可选值 | 说明 | 默认值 |
194-|--------|------|--------|------|--------|
195-| scope | 量化范围 | `"per_channel"`, `"per_group"` | per_channel: 每个通道独立参数<br/>per_group: 每个组独立参数，AutoRound权重量化不支持per_tensor | `"per_group"` |
196-| dtype | 量化数据类型 | `"int8"`, `"int4"` | 8位/4位整数量化 | `"int8"` |
197-| symmetric | 是否对称量化 | `True`, `False` | True: 对称量化，零点为0<br/>False: 非对称量化，零点可调整 | `True` |
198-| method | 量化方法 | `"autoround"` | 权重量化方法：AutoRound算法，即包含参数训练的权重量化 | `"autoround"` |
199-| ext | 扩展配置 | `object` | 包含AutoRound特有的配置参数 | [见下方详细配置](#ext-autoround扩展配置) |
200- 
201-#### ext (AutoRound扩展配置)
202- 
203-**作用**: 配置AutoRound算法特有的参数。
204- 
205-| 参数名 | 作用 | 类型 | 说明 | 示例值 |
206-|--------|------|------|------|--------|
207-| group_size | 量化组大小 | `int` | 分组量化的大小，必须能被待量化nn.Linear层的input_features维度整除 | `256` |
208-| scale_dtype | 缩放因子数据类型 | `string` | 缩放因子的数据类型，影响精度和内存占用。可选值：`"float16"`、`"float32"`、`"bfloat16"` | `"bfloat16"` |
209- 
210-### 层过滤机制
211- 
212-层过滤机制用于指定哪些层需要量化，支持include和exclude模式匹配。详细的过滤规则、匹配模式、示例说明和常见层名模式请参考 [线性量化层过滤机制详解](../linear_quant/linear_quant.md#层过滤机制详解)。
213- 
214-## FAQ
215- 
216-### 优化不收敛
217- 
218-**现象**：在优化过程中，浮点结果与量化结果之间的差距波动较大或不收敛。
219- 
220-**解决方案**：调整学习率或增加迭代次数。
221- 
222-### 精度下降明显
223- 
224-**现象**：量化后模型精度下降超过预期。
225- 
226-**解决方案**：增加优化步数，调整量化配置，减少使用`w4a4`量化的层数，或使用更多更优质的校准数据。
227- 
228-### group_size配置错误
229- 
230-**现象**：在量化过程中抛出了shape相关的异常如： shape '[-1, 257]' is invalid for input of size 512。
231- 
232-**原因**：`group_size`参数必须能够被待量化`nn.Linear`层的`input_features`维度整除，否则会导致分组量化失败。
233- 
234-**解决方案**：
235- 
236- - 检查模型各层的`input_features`维度，确保`group_size`能够被其整除
237- - 常见的`input_features`维度包括：4096、8192、11008等
238- - 推荐的`group_size`值：128、256、512等，这些值通常能够被大多数层的`input_features`整除
239- 
240-### 层匹配告警
241- 
242-**现象**：在量化过程中，工具抛出了层匹配告警。
243- 
244-**解决方案**：检查模型定义，确保include/exclude模式匹配到正确的层。如果`include/exclude`未匹配到任何层时，工具会进行告警。详细的常见匹配失败原因和排查步骤请参考 [LinearQuantProcess层匹配告警](../linear_quant/linear_quant.md#层匹配告警)。
Adocs/zh/knowledge_base/quantization_algorithms/autoround/term_autoround.md+164-0
@@ -0,0 +1,164 @@
1+# AutoRound 低比特量化算法词条
2+ 
3+> **词条类别**：量化算法
4+> **英文名称**：AutoRound
5+> **首次提出**：Intel, 2023
6+> **应用领域**：大语言模型量化压缩、低比特量化精度优化
7+> **msModelSlim 实现**：`msmodelslim/processor/quant/autoround.py`
8+ 
9+---
10+ 
11+## 1. 概述
12+ 
13+AutoRound 是一种基于 SignSGD 的大语言模型低比特权重量化算法。它通过引入可学习的舍入偏移参数，结合 SignSGD 优化器自适应调整各权重的舍入方向，并利用温度调度策略逐步硬化舍入操作，有效降低量化重构误差。其核心特征是：可学习舍入、逐层迭代优化、支持 W4A4 等超低比特量化，常与 [QuaRot](../quarot/term_quarot.md) 等离群值抑制算法配合使用。
14+ 
15+---
16+ 
17+## 2. 词条介绍
18+ 
19+传统量化方法（如四舍五入）在权重量化中并非最优选择，往往会引入较大的量化误差，尤其在低比特（如 4bit 及以下）量化场景中表现更为明显。AutoRound 观察到，通过引入可学习的舍入偏移并结合优化器，可以自适应地为每个权重选择最优的舍入方向，从而显著降低量化重构误差。
20+ 
21+---
22+ 
23+## 3. 原理
24+ 
25+### 1. 核心思想
26+ 
27+AutoRound 的核心思想是“把舍入方向变成可学习参数”：不采用简单的四舍五入，而是基于 SignSGD（符号梯度下降）算法，为每个权重学习一个舍入偏移 $V$，自适应决定权重向上或向下舍入，并有针对性地调整缩放因子和零点，从而最小化量化重构误差。
28+ 
29+### 2. 数学描述
30+ 
31+传统量化中权重 $W$ 的量化公式为：
32+ 
33+$$
34+\hat{W} = s \times \operatorname{clip}(\lfloor W/s + zp \rceil, n, m)
35+$$
36+ 
37+- $\hat{W}$：量化后的权重
38+- $s$：缩放因子
39+- $zp$：零点
40+- $n$、$m$：量化后的上下界
41+ 
42+AutoRound 在此基础上引入可学习的舍入偏移 $V$ 与可选的缩放因子调整参数 $\alpha$、$\beta$：
43+ 
44+$$
45+\hat{W} = s \times \operatorname{clip}(\lfloor W/s + zp + V \rceil, n, m)
46+$$
47+ 
48+$$
49+s = \frac{\max(W) \times \alpha - \min(W) \times \beta}{2^{bit} - 1}
50+$$
51+ 
52+- $V$：控制舍入方向的可学习偏移
53+- $\alpha$、$\beta$：用于调整缩放因子范围的参数
54+- $bit$：量化位数
55+ 
56+优化过程为逐层迭代：采集浮点前向输出作为基准，初始化并训练缩放因子与舍入偏移，量化-反量化前向得到量化结果，计算重构损失，通过 SignSGD 更新参数，重复直至收敛或达到最大迭代次数。
57+ 
58+### 3. 关键性质
59+ 
60+- **可学习舍入**：舍入方向由可学习偏移 $V$ 决定，而非固定四舍五入。
61+- **逐层优化**：对每个 decoder 层独立优化，避免误差跨层累积。
62+- **超低比特支持**：面向 4bit 及以下的超低比特量化场景。
63+- **混合量化**：支持对不同层使用不同量化配置（如 W8A8 与 W4A4 混合）。
64+ 
65+---
66+ 
67+## 4. 流程示意
68+ 
69+> 以下为本算法在 msModelSlim 中的简化流程概览。
70+ 
71+```mermaid
72+flowchart LR
73+ A[浮点前向] --> B[初始化量化参数]
74+ B --> C[量化重构]
75+ C --> D[计算重构损失]
76+ D --> E[SignSGD 更新]
77+ E --> F[迭代收敛]
78+ F --> G[应用量化权重]
79+```
80+ 
81+---
82+ 
83+## 5. 在 msModelSlim 中的实现
84+ 
85+### 1. 实现位置
86+ 
87+算法在 `msmodelslim/processor/quant/autoround.py` 中实现，核心类为 `AutoroundQuantProcessor`，通过 `type: "autoround_quant"` 处理器使用。
88+ 
89+### 2. 处理流程
90+ 
91+- **初始化阶段**：读取量化配置，为每个网络层分配对应的量化配置方案，预分配浮点输出、量化输出与最佳参数。
92+- **pre_run 阶段**：关闭所有网络层的自动梯度计算，防止训练过程中直接优化权重。
93+- **preprocess 阶段**（逐层）：采集当前层浮点前向输出作为基准，对线性层包装并注入可训练的缩放因子与舍入偏移参数。
94+- **process 阶段**（逐层）：配置 SignSGD 优化器，迭代更新缩放因子与舍入偏移，最小化重构误差。
95+- **postprocess 阶段**（逐层）：应用优化后的量化参数，解除线性层包装，执行量化后的前向传播。
96+- **post_run 阶段**：清理所有临时属性。
97+ 
98+### 3. 配置示例
99+ 
100+> 以下为最小可用的 YAML 配置片段。各字段的详细含义如下表所示。
101+ 
102+```yaml
103+spec:
104+ process:
105+ - type: "autoround_quant"
106+ iters: 400
107+ enable_minmax_tuning: True
108+ enable_round_tuning: True
109+ strategies:
110+ - qconfig: *default_w4a4_dynamic
111+ include:
112+ - "*.up_proj"
113+ - "*.gate_proj"
114+```
115+ 
116+**字段说明**：
117+ 
118+| 字段名 | 作用 | 说明 |
119+| --- | --- | --- |
120+| type | 处理器类型标识 | 固定为 `"autoround_quant"`。 |
121+| iters | 优化迭代次数 | 大于 0 的整数，影响优化效果与计算时间，默认 `10`。 |
122+| enable_minmax_tuning | 最小最大值调优开关 | 布尔值，是否启用最小最大值调优，默认 `True`。 |
123+| enable_round_tuning | 舍入调优开关 | 布尔值，是否启用舍入调优，默认 `True`。 |
124+| strategies | 量化策略配置 | 策略列表，支持对不同层使用不同量化配置（如 int4 与 int8 混合量化）。 |
125+ 
126+---
127+ 
128+## 6. 适用场景与限制
129+ 
130+### 1. 适用场景
131+ 
132+- 4bit 等超低比特权重量化场景。
133+- 低比特条件下仍需要保持较高模型精度的场景。
134+ 
135+### 2. 使用限制
136+ 
137+- 仅适用于 LLM 中的线性层量化。
138+- 需要足够的校准数据或训练迭代次数来优化参数。
139+- 包含训练过程，对 NPU 显存有一定要求，仅支持 NPU 显存 ≥64G 的设备。
140+- 低比特量化极度依赖良好的离群值抑制算法，建议配合 [QuaRot](../quarot/term_quarot.md) 或 [Iterative Smooth](../iterative_smooth/term_iterative_smooth.md) 使用，不建议单独使用。
141+ 
142+---
143+ 
144+## 7. 关联流程
145+ 
146+- 《[一键量化 (V1)](../../../user_guide/usage_quick_quantization.md)》：可集成 AutoRound 作为低比特权重量化步骤。
147+- 《[量化精度调优指南](../../../user_guide/process_quantization_precision_tuning.md)》：精度不达标时可调整 AutoRound 迭代次数与量化配置。
148+ 
149+---
150+ 
151+## 8. 关联词条
152+ 
153+- [QuaRot](../quarot/term_quarot.md)：配套术语，常在本算法前作为离群值抑制步骤。
154+- [Adapt Rotation](../adapt_rotation/term_adapt_rotation.md)：配套术语，常与本算法配合用于 W4A4 量化。
155+- [Iterative Smooth](../iterative_smooth/term_iterative_smooth.md)：配套术语，常在本算法前作为离群值抑制步骤。
156+- [GPTQ](../gptq/term_gptq.md)：同类算法，同为高精度权重量化优化算法。
157+- [MinMax](../minmax/term_minmax.md)：对比算法，本算法是 MinMax 的低比特精度优化扩展。
158+ 
159+---
160+ 
161+## 9. 参考资料
162+ 
163+1. Cheng W et al. Optimize Weight Rounding via Signed Gradient Descent for the Quantization of LLMs. 2023. https://arxiv.org/abs/2309.05516
164+2. 《AutoRound 使用指南》([./usage_autoround.md](./usage_autoround.md))
Adocs/zh/knowledge_base/quantization_algorithms/autoround/usage_autoround.md+178-0
@@ -0,0 +1,178 @@
1+# AutoRound 使用指南
2+ 
3+## 1. 适用范围
4+ 
5+本流程适用于在 msModelSlim 中配置和使用 AutoRound 低比特量化算法。AutoRound 作为权重量化处理器，通过可学习舍入与 SignSGD 优化，用于 4bit 等超低比特量化场景。
6+ 
7+适用角色：算法工程师、模型部署工程师
8+ 
9+适用场景：
10+ 
11+- 4bit 等超低比特权重量化场景。
12+- 低比特条件下仍需要保持较高模型精度的场景。
13+ 
14+不适用场景：
15+ 
16+- 非 LLM 线性层以外的量化目标。
17+- NPU 显存小于 64G 的设备（算法包含训练过程）。
18+ 
19+## 2. 流程关系与前置条件
20+ 
21+**上级流程**：模型适配与验证通过后，确定量化方案阶段。
22+ 
23+**前置条件**：
24+ 
25+- 已安装兼容版本的 msModelSlim 工具（详见《[msModelSlim 工具安装指南](../../../install_guide/install_guide.md)》）。
26+- 已确认目标模型支持线性层量化。
27+- 已准备好足够的校准数据或训练迭代次数。
28+- 建议先配置离群值抑制算法（如 QuaRot、Iterative Smooth）作为前置步骤。
29+ 
30+**后续操作**：量化流程执行 → 精度验证 → 部署上线或进入调优。
31+ 
32+## 3. 输入和交付件
33+ 
34+| 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 |
35+| --- | --- | --- | --- | --- |
36+| 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被目标 Transformers 版本加载 |
37+| 输入 | 校准数据集 | 工具默认或用户指定 | JSONL 格式，每条含文本 prompt | 至少包含足够样本完成迭代优化 |
38+| 输入 | 量化 YAML 配置文件 | 用户编写 | 符合 msModelSlim YAML 规范，含 `autoround_quant` 处理器配置 | 可通过工具 `--config_path` 参数加载 |
39+| 交付件 | 量化权重目录 | `--save_path` 指定路径 | 含 `quant_model_description.json` 及 `*.safetensors`，已应用优化后的量化权重 | 推理冒烟通过 |
40+ 
41+## 4. 流程总览
42+ 
43+```mermaid
44+flowchart LR
45+ A[编写 YAML 配置] --> B[执行量化命令]
46+ B --> C[逐层优化舍入]
47+ C --> D[应用量化权重]
48+ D --> E[验证量化结果]
49+```
50+ 
51+## 5. 操作步骤
52+ 
53+### 步骤 1：编写 YAML 配置文件
54+ 
55+**目标**：编写包含 `autoround_quant` 处理器配置的 YAML 文件。
56+ 
57+**操作**：
58+ 
59+1. 在 `spec.process` 下配置 `autoround_quant` 处理器，指定 `type: "autoround_quant"`。
60+2. 配置 `iters`（迭代次数，默认 `10`）、`enable_minmax_tuning`（默认 `True`）、`enable_round_tuning`（默认 `True`）。
61+3. 配置 `strategies` 量化策略，支持对不同层使用不同量化配置（混合量化）。
62+4. 建议在 `spec.process` 中先配置离群值抑制算法（如 QuaRot、Iterative Smooth）。
63+ 
64+YAML 配置示例（W8A8 与 W4A4 混合量化）：
65+ 
66+```yaml
67+spec:
68+ process:
69+ - type: "autoround_quant" # 固定为 `autoround_quant`，用于指定 Processor 类型。
70+ iters: 400 # 优化迭代次数
71+ enable_minmax_tuning: True # 是否启用最小最大值调优
72+ enable_round_tuning: True # 是否启用舍入调优
73+ strategies:
74+ # 策略1：除 up_proj、gate_proj 和 o_proj 层外，其余层均应用 W8A8 量化。
75+ - qconfig: *default_w8a8_dynamic
76+ exclude:
77+ - "*.up_proj"
78+ - "*.gate_proj"
79+ - "*.o_proj"
80+ # 策略2：对up_proj、gate_proj、o_proj层使用W4A4量化
81+ - qconfig: *default_w4a4_dynamic
82+ include:
83+ - "*.up_proj"
84+ - "*.gate_proj"
85+ - "*.o_proj"
86+```
87+ 
88+YAML 配置字段详解如下：
89+ 
90+| 字段名 | 作用 | 说明 |
91+| --- | --- | --- |
92+| type | 处理器类型标识 | 固定为 `"autoround_quant"`。 |
93+| iters | 优化迭代次数 | 大于 0 的整数，影响优化效果与计算时间，默认 `10`。 |
94+| enable_minmax_tuning | 最小最大值调优开关 | 布尔值，是否启用最小最大值调优，默认 `True`。 |
95+| enable_round_tuning | 舍入调优开关 | 布尔值，是否启用舍入调优，默认 `True`。 |
96+| strategies | 量化策略配置 | 策略列表，支持对不同层使用不同量化配置（如 int4 与 int8 混合量化）。 |
97+ 
98+**层过滤机制**：
99+ 
100+`include` 定义要包含的层，只有匹配 `include` 模式的层才会被处理；`exclude` 定义要排除的层，匹配 `exclude` 模式的层会被跳过；`exclude` 的优先级高于 `include`。匹配采用 Unix 通配符模式：`*` 匹配任意字符序列、`?` 匹配单个字符、`[abc]` 匹配字符集中的任意字符。若 `include`/`exclude` 未匹配到任何层，工具会进行告警，请核对层名、路径层级、大小写与拼写。
101+ 
102+**输出**：YAML 配置文件 `${CONFIG_PATH}`。
103+ 
104+### 步骤 2：执行量化命令
105+ 
106+**目标**：使用上一步编写的 YAML 配置文件启动量化流程。
107+ 
108+**操作**：
109+ 
110+```bash
111+msmodelslim quant \
112+ --model_path ${MODEL_PATH} \
113+ --save_path ${SAVE_PATH} \
114+ --device npu \
115+ --model_type ${MODEL_TYPE} \
116+ --config_path ${CONFIG_PATH} \
117+ --trust_remote_code True
118+```
119+ 
120+参数说明：
121+ 
122+| 参数 | 必选 | 说明 |
123+| --- | --- | --- |
124+| `model_path` | 是 | 浮点模型权重路径 |
125+| `save_path` | 是 | 量化权重保存路径 |
126+| `device` | 否 | 量化设备，默认 `npu` |
127+| `model_type` | 是 | 模型名称，与支持矩阵一致 |
128+| `config_path` | 是 | 步骤 1 编写的 YAML 配置路径 |
129+| `trust_remote_code` | 否 | 是否信任远程代码，默认 `False` |
130+ 
131+执行流程说明：
132+ 
133+1. 工具加载 YAML 配置，解析 `autoround_quant` 处理器。
134+2. preprocess 阶段逐层采集浮点基准输出并注入可训练量化参数。
135+3. process 阶段逐层运行 SignSGD 优化，最小化重构误差。
136+4. postprocess 阶段应用优化后的量化参数并保存量化权重。
137+ 
138+**输出**：量化权重目录 `${SAVE_PATH}`，包含量化描述文件与权重分片。
139+ 
140+### 步骤 3：验证量化结果
141+ 
142+**目标**：确认量化权重文件完整且可加载。
143+ 
144+**操作**：
145+ 
146+1. 检查输出目录是否包含 `quant_model_description.json` 文件。
147+2. 检查日志确认优化过程收敛且无层匹配告警。
148+3. 使用推理框架加载量化权重进行冒烟测试。
149+ 
150+**输出**：量化权重验证通过。
151+ 
152+## 6. 验收条件
153+ 
154+- 量化权重目录包含 `quant_model_description.json` 及所有必需的 `*.safetensors` 分片文件。
155+- 日志无优化不收敛或层匹配告警。
156+- 量化后模型推理精度优于未使用 AutoRound 的基线。
157+ 
158+## 7. 异常处置
159+ 
160+- **优化不收敛**：浮点结果与量化结果差距波动较大，调整学习率或增加迭代次数。
161+- **精度下降明显**：增加优化步数、调整量化配置、减少 `w4a4` 量化层数，或使用更多更优质的校准数据。
162+- **group_size 配置错误**：抛出 shape 相关异常，确认 `group_size` 能被待量化 `nn.Linear` 层的 `input_features` 维度整除。
163+- **层匹配告警**：检查模型定义，确保 `include`/`exclude` 模式匹配到正确的层。
164+ 
165+## 8. 术语
166+ 
167+| 术语 | 简述 | 链接 |
168+| --- | --- | --- |
169+| AutoRound | 基于 SignSGD 的低比特权重量化算法 | [AutoRound 词条](./term_autoround.md) |
170+| SignSGD | 符号梯度下降优化器 | [AutoRound 词条](./term_autoround.md) |
171+| 混合量化 | 对不同层使用不同量化配置的策略 | [AutoRound 词条](./term_autoround.md) |
172+ 
173+## 9. 接口文档列表
174+ 
175+| 接口或能力 | 简述 | 链接 |
176+| --- | --- | --- |
177+| `autoround_quant` 处理器 | 用于执行 AutoRound 低比特量化的 Processor 配置 | [AutoRound 词条](./term_autoround.md) |
178+| 层过滤机制 | include/exclude 通配符匹配规则 | [线性量化词条](../linear_quant/term_linear_quant.md) |
Ddocs/zh/knowledge_base/quantization_algorithms/awq_smooth/awq_smooth.md+0-316
@@ -1,316 +0,0 @@
1-# AWQ：激活感知权重量化算法说明
2- 
3-## 简介
4- 
5-- **概述**：AWQ（Activation-aware Weight Quantization，激活感知权重量化）是一种用于大语言模型量化过程中抑制激活离群值的算法。该算法通过观察激活值的统计特征，自动搜索最优的缩放因子，在权重量化前对权重进行缩放，从而在保持模型精度的同时有效减少量化误差。AWQ 的核心理念是：并非所有权重对模型输出同等重要，通过激活值分布来识别重要权重通道并给予保护，可以在低比特量化场景下获得更优的精度表现。
6-- **核心思想**：AWQ 算法使用激活值的均值（mean）来度量各权重通道的重要性，通过网格搜索找到使量化结果与浮点基准结果之间均方误差（mean squared error，MSE）最小的缩放因子。
7- 
8-## 使用前准备
9- 
10-安装 msModelSlim 工具，详情请参见[《msModelSlim 工具安装指南》](../../../install_guide/install_guide.md)。
11- 
12-## 原理和实现
13- 
14-### 原理
15- 
16-**算法公式：**
17- 
18-```python
19-scales = act_mean.pow(ratio).clamp(min=1e-4)
20-scales = scales / sqrt(scales.max() * scales.min())
21-```
22- 
23-其中：
24- 
25-- `act_mean`：激活值绝对值的逐通道均值（`mean(abs(act))`），反映各通道的重要性。
26-- `ratio`：缩放比例系数，在 `[0, 1)` 范围内以 `1 / n_grid` 为步长进行网格搜索。
27-- `n_grid`：网格搜索步数，默认值为 `20`，用于控制搜索精度。
28- 
29-**关键特性：**
30- 
31-1. **基于激活均值的重要性评估**：使用激活值绝对值的逐通道均值衡量权重通道的重要性，均值越大的通道在量化时会获得更多保护。
32-2. **网格搜索最优缩放**：在 `[0, 1)` 范围内遍历不同的 `ratio` 值，评估各候选缩放因子的量化效果。
33-3. **实际量化器评估**：使用真实的权重量化器对缩放后的权重进行量化，并基于量化结果与浮点基准结果的均方误差选择最优参数。
34-4. **块级误差评估**：通过自动发现目标模块的最低公共祖先（lowest common ancestor，LCA）并缓存其输入参数，在块级别评估量化误差，而不是只比较单个线性层的权重误差。
35- 
36-**缩放因子搜索流程：**
37- 
38-1. **初始化**：收集激活值均值和祖先模块输入参数缓存。
39-2. **基准推理**：使用原始浮点权重在祖先模块上执行推理，得到浮点基准输出。
40-3. **网格搜索**：在 `[0, 1)` 范围内遍历 `ratio` 值。
41- - 计算缩放因子：`scales = act_mean.pow(ratio).clamp(min=1e-4)`。
42- - 归一化缩放因子：`scales = scales / sqrt(scales.max() * scales.min())`。
43- - 对目标线性层权重应用缩放。
44- - 使用量化器量化缩放后的权重。
45- - 对量化后的权重执行反向缩放。
46- - 在祖先模块上执行推理并计算均方误差。
47- - 恢复原始权重。
48-4. **选择最优参数**：选择均方误差最小的 `ratio` 对应的缩放因子。
49-5. **应用缩放**：通过 `SubgraphFusionFactory` 将最优缩放因子融合到子图权重中。
50- 
51-### 支持的子图类型
52- 
53-#### NormLinearSubgraph（归一化-线性子图）
54- 
55-适用于包含归一化层和多个线性层的结构，例如：
56- 
57-```python
58-x = norm(x)
59-y = torch.cat([linear(x) for linear in linears], dim=-1)
60-```
61- 
62-处理方式：
63- 
64-- 使用所有目标线性层进行缩放因子搜索。
65-- 通过自动发现的最低公共祖先模块进行块级误差评估。
66-- 搜索到最优缩放因子后，对归一化层应用反向缩放，对线性层应用正向缩放。
67- 
68-#### LinearLinearSubgraph（线性-线性子图）
69- 
70-适用于两个连续线性层的结构：
71- 
72-```python
73-y = linear2(linear1(x))
74-```
75- 
76-处理方式：
77- 
78-- 基于 `linear2` 的权重进行缩放因子搜索。
79-- 通过自动发现的最低公共祖先模块进行块级误差评估。
80-- 对 `linear2` 应用正向缩放，对 `linear1` 应用反向缩放。
81- 
82-#### OVSubgraph（注意力输出-值子图）
83- 
84-适用于注意力机制中的输出投影和值投影，支持以下结构：
85- 
86-- MHA（多头注意力）
87-- MQA（多查询注意力）
88-- GQA（分组查询注意力）
89- 
90-处理方式：
91- 
92-- 基于 `o_proj` 权重进行缩放因子搜索。
93-- 通过自动发现的最低公共祖先模块进行块级误差评估。
94-- 对 `o_proj` 应用正向缩放，对 `v_proj` 应用反向缩放。
95- 
96-#### UpDownSubgraph（上投影-下投影子图）
97- 
98-适用于 MLP 门控结构：
99- 
100-```python
101-y = down_proj(ReLU(gate_proj(x)) * up_proj(x))
102-```
103- 
104-处理方式：
105- 
106-- 基于 `down_proj` 权重进行缩放因子搜索。
107-- 通过自动发现的最低公共祖先模块进行块级误差评估。
108-- 对 `down_proj` 应用正向缩放，对 `up_proj` 应用反向缩放。
109- 
110-### 实现
111- 
112-#### 代码实现
113- 
114-AWQ 算法的代码组织在 [msmodelslim/processor/anti_outlier/awq/](../../../../../msmodelslim/processor/anti_outlier/awq/__init__.py) 目录下：
115- 
116-| 文件 | 核心类/函数 | 职责 |
117-| --------------------------------------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------- |
118-| [processor.py](../../../../../msmodelslim/processor/anti_outlier/awq/processor.py) | `AWQProcessor`, `AWQProcessorConfig` | Processor 入口，管理预处理和后处理流程 |
119-| [api.py](../../../../../msmodelslim/processor/anti_outlier/awq/api.py) | `awq()` | 各子图类型的 AWQ 分发与实现 |
120-| [best_scales_search.py](../../../../../msmodelslim/processor/anti_outlier/awq/best_scales_search.py) | `AWQSearcher`, `AWQBestScalesSearcher` | 缩放因子网格搜索逻辑 |
121-| [awq_stats_collector.py](../../../../../msmodelslim/processor/anti_outlier/awq/awq_stats_collector.py) | `AWQStatsCollector` | 激活统计信息收集和中间参数缓存 |
122-| [common.py](../../../../../msmodelslim/processor/anti_outlier/awq/common.py) | `AWQConfig`, `AWQContext`, `offload()`, `onload()` | 算法配置、运行时上下文和张量迁移工具 |
123-| [interface.py](../../../../../msmodelslim/processor/anti_outlier/awq/interface.py) | `AWQInterface` | 模型适配器需要实现的抽象接口 |
124- 
125-#### 预处理阶段
126- 
127-- 通过 `AWQInterface.get_adapter_config_for_subgraph()` 获取子图配置。
128-- 根据 `include` 和 `exclude` 过滤要处理的子图。
129-- 为目标线性层安装 forward hook，收集激活值绝对值的逐通道均值。
130-- 通过 LCA 自动发现块级评估用的祖先模块，并为其安装 forward pre-hook，缓存输入参数。
131- 
132-#### 后处理阶段
133- 
134-- 按优先级处理子图：`up-down`、`ov`、`norm-linear`、`linear-linear`。
135-- 从统计信息中构建 `AWQContext`，包括激活均值、祖先模块实例和输入参数缓存。
136-- 调用 `AWQBestScalesSearcher.search()` 搜索最优缩放因子。
137-- 通过 `SubgraphFusionFactory` 将最优缩放因子融合到子图中。
138-- 停止所有 hook 并清理统计信息。
139- 
140-## 适用要求
141- 
142-- **模型接口要求**：模型适配器需要实现 `AWQInterface` 接口。
143-- **模块命名要求**：配置中的模块名称必须与 `named_modules()` 返回的完整路径一致。
144-- **子图类型要求**：`enable_subgraph_type` 支持的取值为 `norm-linear`、`linear-linear`、`ov`、`up-down`。
145-- **模块属性要求**：目标模块必须存在且具备可写的 `weight`。
146-- **运行时要求**：AWQ 依赖 `ContextManager` 提供全局上下文，运行时会自动创建和管理相关上下文对象。
147- 
148-## 功能介绍
149- 
150-### YAML 配置示例
151- 
152-作为Processor使用，YAML配置示例如下：
153- 
154-```yaml
155-- type: "awq"
156- weight_qconfig:
157- scope: "per_channel"
158- dtype: "int8"
159- symmetric: true
160- method: "minmax"
161- n_grid: 20
162- enable_subgraph_type:
163- - "norm-linear"
164- - "linear-linear"
165- - "ov"
166- - "up-down"
167- include:
168- - "*"
169- exclude: []
170-```
171- 
172-### YAML 配置字段详解
173- 
174-| 字段名 | 作用 | 说明 |
175-| ---------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
176-| `type` | 处理器类型标识 | 固定值为 `"awq"`。 |
177-| `weight_qconfig` | 权重量化配置 | AWQ 搜索阶段使用的权重量化配置。字段定义与 [线性量化算法说明](../linear_quant/linear_quant.md#yaml配置字段详解) 中 `qconfig.weight` 保持一致。 |
178-| `n_grid` | 网格搜索步数 | 正整数，默认值为 `20`，数值越大搜索越细致，但耗时也会增加。 |
179-| `enable_subgraph_type` | 启用的子图类型 | 支持的取值包括 `norm-linear`、`linear-linear`、`ov`、`up-down`。 |
180-| `include` | 包含的层 | 支持通配符匹配。 |
181-| `exclude` | 排除的层 | 支持通配符匹配，优先级高于 `include`。 |
182- 
183-### 模型适配
184- 
185-#### 接口与数据结构
186- 
187-AWQ 模型适配依赖以下接口和数据结构：
188- 
189-```python
190-from dataclasses import dataclass
191-from typing import List, Optional
192-from abc import ABC, abstractmethod
193- 
194-@dataclass
195-class MappingConfig:
196- targets: List[str]
197- source: Optional[str] = None
198- 
199-@dataclass
200-class AdapterConfig:
201- subgraph_type: str
202- mapping: MappingConfig
203- 
204-class AWQInterface(ABC):
205- @abstractmethod
206- def get_adapter_config_for_subgraph(self) -> List[AdapterConfig]:
207- ...
208-```
209- 
210-#### 适配步骤
211- 
212-1. 模型适配器继承 `AWQInterface` 并实现 `get_adapter_config_for_subgraph()`。
213-2. 为模型中的标准子图配置 `subgraph_type` 和 `mapping`。
214-3. 使用完整模块路径填写 `source` 和 `targets`。
215-4. 由框架自动完成块级评估所需的 LCA 发现和参数缓存。
216- 
217-参考实现请参见 [msmodelslim/model/qwen2/model_adapter.py](../../../../../msmodelslim/model/qwen2/model_adapter.py)。
218- 
219-#### 配置示例
220- 
221-以下示例展示了典型 Transformer 层的 AWQ 子图映射：
222- 
223-```python
224-def get_adapter_config_for_subgraph(self) -> List[AdapterConfig]:
225- adapter_config = []
226- for layer_idx in range(self.config.num_hidden_layers):
227- norm_linear_mapping_config1 = MappingConfig(
228- source=f"model.layers.{layer_idx}.input_layernorm",
229- targets=[
230- f"model.layers.{layer_idx}.self_attn.k_proj",
231- f"model.layers.{layer_idx}.self_attn.q_proj",
232- f"model.layers.{layer_idx}.self_attn.v_proj",
233- ],
234- )
235- 
236- norm_linear_mapping_config2 = MappingConfig(
237- source=f"model.layers.{layer_idx}.post_attention_layernorm",
238- targets=[
239- f"model.layers.{layer_idx}.mlp.gate_proj",
240- f"model.layers.{layer_idx}.mlp.up_proj",
241- ],
242- )
243- 
244- ov_mapping_config = MappingConfig(
245- source=f"model.layers.{layer_idx}.self_attn.v_proj",
246- targets=[f"model.layers.{layer_idx}.self_attn.o_proj"],
247- )
248- 
249- up_down_mapping_config = MappingConfig(
250- source=f"model.layers.{layer_idx}.mlp.up_proj",
251- targets=[f"model.layers.{layer_idx}.mlp.down_proj"],
252- )
253- 
254- adapter_config.extend([
255- AdapterConfig(subgraph_type="norm-linear", mapping=norm_linear_mapping_config1),
256- AdapterConfig(subgraph_type="norm-linear", mapping=norm_linear_mapping_config2),
257- AdapterConfig(subgraph_type="ov", mapping=ov_mapping_config),
258- AdapterConfig(subgraph_type="up-down", mapping=up_down_mapping_config),
259- ])
260- 
261- return adapter_config
262-```
263- 
264-### 与 Flex AWQ SSZ 的区别
265- 
266-| 特性 | AWQ | [Flex AWQ SSZ](../flex_awq_ssz/flex_awq_ssz.md) |
267-| ------------ | ------------------------------------- | ------------------------------------- |
268-| 缩放因子计算 | `act_mean.pow(ratio)` 网格搜索 | `A_scale**alpha / W_scale**beta` |
269-| 误差评估方式 | 块级评估 | 使用量化器评估不同参数组合 |
270-| 参数搜索空间 | `ratio` ∈ `[0, 1)`，步长 `1 / n_grid` | `alpha` ∈ `[0, 1]`，`beta` 常设为 `0` |
271-| 配置接口 | `AWQInterface` | `FlexSmoothQuantInterface` |
272-| 量化配置 | 仅需权重量化配置 | 需要激活和权重量化配置 |
273- 
274-## FAQ
275- 
276-### 模块名不匹配
277- 
278-**现象**: `include/exclude` 未命中时，日志提示未匹配模式。
279- 
280-**解决方案**: 核对完整模块名是否与 `named_modules()` 返回的路径一致。
281- 
282-### 子图配置错误
283- 
284-**现象**: `get_adapter_config_for_subgraph()` 返回的配置不正确。
285- 
286-**解决方案**: 检查配置中的 `source` 和 `targets` 字段是否正确。
287- 
288-### 模块不存在
289- 
290-**现象**: 配置中指定的模块名称在模型中不存在。
291- 
292-**解决方案**: 通过 `model.named_modules()` 验证模块是否确实存在。
293- 
294-### 子图类型不支持
295- 
296-**现象**: 配置的子图类型不被支持。
297- 
298-**解决方案**: 建议按模型实际已适配的子图类型填写，支持的取值为 `norm-linear`、`linear-linear`、`ov`、`up-down`。如无特殊需求，可保持默认配置。
299- 
300-### 祖先模块未找到
301- 
302-**现象**: 日志提示 "No name found for inspect module of subgraph"，子图被跳过。
303- 
304-**解决方案**: 检查 `targets` 中的模块名称是否具有合理的共同路径前缀，确保其最低公共祖先模块在模型中存在。
305- 
306-### 激活统计信息缺失
307- 
308-**现象**: 日志提示 "No activation mean for target module"，子图被跳过。
309- 
310-**解决方案**: 确保校准数据（calibration data）足够且模型前向推理正常执行，使钩子能够正确收集激活统计信息。
311- 
312-### 中间参数缓存为空
313- 
314-**现象**: 日志提示 "No kwargs cache for parent module"，子图被跳过。
315- 
316-**解决方案**: 确保通过 LCA 自动发现的祖先模块在前向推理中被正确触发，检查 `targets` 中的模块路径是否正确。
Adocs/zh/knowledge_base/quantization_algorithms/awq_smooth/term_awq_smooth.md+165-0
@@ -0,0 +1,165 @@
1+# AWQ 激活感知权重量化算法词条
2+ 
3+> **词条类别**：离群值抑制算法
4+> **英文名称**：AWQ Smooth
5+> **英文缩写**：AWQ
6+> **中文别名**：激活感知权重量化
7+> **首次提出**：Lin et al., MLSys 2024
8+> **应用领域**：大语言模型量化压缩、低比特量化精度优化
9+> **msModelSlim 实现**：`msmodelslim/processor/anti_outlier/awq/`
10+ 
11+---
12+ 
13+## 1. 概述
14+ 
15+AWQ（Activation-aware Weight Quantization，激活感知权重量化）是一种用于大语言模型量化过程中抑制激活离群值的算法。它通过观察激活值的统计特征，用激活均值度量各权重通道的重要性，并通过网格搜索找到使量化结果与浮点基准之间均方误差最小的缩放因子。其核心特征是：激活感知的重要性评估、网格搜索最优缩放、块级误差评估，常作为 [MinMax](../minmax/term_minmax.md) 等权重量化的前置步骤。
16+ 
17+---
18+ 
19+## 2. 词条介绍
20+ 
21+并非所有权重通道对模型输出同等重要。AWQ 观察到，通过激活值分布可以识别重要权重通道并给予保护：对重要通道施加更小的量化扰动，可以在低比特量化场景下获得更优的精度表现。与 [SmoothQuant](../smooth_quant/term_smooth_quant.md) 的固定缩放不同，AWQ 通过网格搜索在激活统计的指导下寻找最优缩放因子。
22+ 
23+---
24+ 
25+## 3. 原理
26+ 
27+### 1. 核心思想
28+ 
29+AWQ 的核心思想是“按激活重要性保护权重通道”：使用激活值绝对值的逐通道均值度量通道重要性，在 $[0, 1)$ 范围内以网格搜索遍历 `ratio` 参数，用真实的权重量化器评估缩放后的量化误差，选择均方误差最小的缩放因子，并通过最低公共祖先（LCA）在块级别评估误差。
30+ 
31+### 2. 数学描述
32+ 
33+缩放因子的计算公式为：
34+ 
35+$$
36+s = \frac{\operatorname{act\_mean}^{\text{ratio}}}{\sqrt{\max(s) \cdot \min(s)}}, \quad s = \operatorname{clamp}(s, \min=10^{-4})
37+$$
38+ 
39+- $s$：逐通道缩放因子
40+- $\text{act\_mean}$：激活值绝对值的逐通道均值，即 $mean(|act|)$，反映各通道重要性
41+- $\text{ratio}$：缩放比例系数，在 $[0, 1)$ 范围内以 $1 / n\_grid$ 为步长网格搜索
42+- $n\_grid$：网格搜索步数，默认 $20$
43+- $10^{-4}$：缩放因子的最小值
44+ 
45+块级误差评估使用 MSE：
46+ 
47+$$
48+\text{MSE} = \frac{1}{n} \sum_{i=1}^{n} (y_{\text{float}}^{(i)} - y_{\text{quant}}^{(i)})^2
49+$$
50+ 
51+- $y_{\text{float}}$：使用原始浮点权重在祖先模块上的输出
52+- $y_{\text{quant}}$：使用量化权重在祖先模块上的输出
53+ 
54+### 3. 关键性质
55+ 
56+- **激活感知**：基于激活均值识别重要通道并给予保护。
57+- **网格搜索**：在 $[0, 1)$ 范围内搜索最优 `ratio`，步长 $1/n\_grid$。
58+- **真实量化器评估**：使用真实权重量化器评估候选缩放因子的量化误差。
59+- **块级评估**：通过自动发现的最低公共祖先模块在块级别评估误差，而非单层权重误差。
60+ 
61+---
62+ 
63+## 4. 流程示意
64+ 
65+> 以下为本算法在 msModelSlim 中的简化流程概览。
66+ 
67+```mermaid
68+flowchart LR
69+ A[校准数据] --> B[收集激活均值]
70+ B --> C[搜索最优缩放]
71+ C --> D[块级误差评估]
72+ D --> E[融合缩放]
73+ E --> F[交付量化]
74+```
75+ 
76+---
77+ 
78+## 5. 在 msModelSlim 中的实现
79+ 
80+### 1. 实现位置
81+ 
82+算法在 `msmodelslim/processor/anti_outlier/awq/` 目录下实现，核心类包括 `AWQProcessor`、`AWQBestScalesSearcher`、`AWQStatsCollector`，通过 `type: "awq"` 处理器使用。
83+ 
84+### 2. 处理流程
85+ 
86+- **预处理阶段**：通过 `AWQInterface.get_adapter_config_for_subgraph()` 获取子图配置，按 `include/exclude` 过滤，为目标线性层安装 forward hook 收集激活均值，并通过 LCA 自动发现祖先模块、安装 forward pre-hook 缓存输入参数。
87+- **后处理阶段**：按优先级处理子图（`up-down`、`ov`、`norm-linear`、`linear-linear`），调用 `AWQBestScalesSearcher.search()` 搜索最优缩放因子，通过 `SubgraphFusionFactory` 融合到子图，最后清理 hook。
88+ 
89+### 3. 配置示例
90+ 
91+> 以下为最小可用的 YAML 配置片段。各字段的详细含义如下表所示。
92+ 
93+```yaml
94+spec:
95+ process:
96+ - type: "awq"
97+ weight_qconfig:
98+ scope: "per_channel"
99+ dtype: "int8"
100+ symmetric: true
101+ method: "minmax"
102+ n_grid: 20
103+ enable_subgraph_type:
104+ - "norm-linear"
105+ - "linear-linear"
106+ - "ov"
107+ - "up-down"
108+ include: ["*"]
109+ exclude: []
110+```
111+ 
112+**字段说明**：
113+ 
114+| 字段名 | 作用 | 说明 |
115+| --- | --- | --- |
116+| type | 处理器类型标识 | 固定为 `"awq"`。 |
117+| weight_qconfig | 权重量化配置 | AWQ 搜索阶段使用的权重量化配置，字段定义与 `linear_quant` 的 `qconfig.weight` 一致。 |
118+| n_grid | 网格搜索步数 | 正整数，默认 `20`，数值越大搜索越细致但耗时增加。 |
119+| enable_subgraph_type | 启用的子图类型 | 支持 `norm-linear`、`linear-linear`、`ov`、`up-down`。 |
120+| include | 包含的层 | 字符串列表，支持通配符匹配。 |
121+| exclude | 排除的层 | 字符串列表，支持通配符匹配，优先级高于 `include`。 |
122+ 
123+### 4. 模型适配接口
124+ 
125+模型适配需实现 `AWQInterface` 接口的 `get_adapter_config_for_subgraph()` 方法，返回 `List[AdapterConfig]`（含 `subgraph_type` 与 `mapping`）。参考实现：`msmodelslim/model/qwen2/model_adapter.py`。
126+ 
127+---
128+ 
129+## 6. 适用场景与限制
130+ 
131+### 1. 适用场景
132+ 
133+- 需要自动搜索最优权重缩放因子、保护重要通道的低比特量化场景。
134+- 作为权重量化的前置步骤，为 [MinMax](../minmax/term_minmax.md)、[SSZ](../ssz/term_ssz.md) 等权重量化算法提供更优的权重分布。
135+ 
136+### 2. 使用限制
137+ 
138+- 模型适配器需要实现 `AWQInterface` 接口。
139+- 配置中的模块名称必须与 `named_modules()` 返回的完整路径一致。
140+- 目标模块必须存在且具备可写的 `weight`。
141+- 依赖 `ContextManager` 提供全局上下文。
142+ 
143+---
144+ 
145+## 7. 关联流程
146+ 
147+- 《[一键量化 (V1)](../../../user_guide/usage_quick_quantization.md)》：默认集成本算法作为离群值抑制前置步骤。
148+- 《[量化精度调优指南](../../../user_guide/process_quantization_precision_tuning.md)》：精度不达标时可考虑启用本算法。
149+ 
150+---
151+ 
152+## 8. 关联词条
153+ 
154+- [SmoothQuant](../smooth_quant/term_smooth_quant.md)：同类算法，同属离群值抑制算法族，但采用固定缩放而非激活感知搜索。
155+- [Flex AWQ SSZ](../flex_awq_ssz/term_flex_awq_ssz.md)：同类算法，本算法的扩展，使用真实量化器评估参数。
156+- [MinMax](../minmax/term_minmax.md)：配套术语，AWQ 搜索阶段使用 `weight_qconfig` 指定的量化配置。
157+- [SSZ](../ssz/term_ssz.md)：配套术语，常与 AWQ 的平滑配合用于权重量化。
158+- [QuaRot](../quarot/term_quarot.md)：对比算法，采用正交旋转而非缩放抑制离群值。
159+ 
160+---
161+ 
162+## 9. 参考资料
163+ 
164+1. Lin J et al. AWQ: Activation-aware Weight Quantization for LLM Compression and Acceleration. MLSys 2024. https://arxiv.org/abs/2306.00978
165+2. 《AWQ 使用指南》([./usage_awq_smooth.md](./usage_awq_smooth.md))
Adocs/zh/knowledge_base/quantization_algorithms/awq_smooth/usage_awq_smooth.md+171-0
@@ -0,0 +1,171 @@
1+# AWQ 使用指南
2+ 
3+## 1. 适用范围
4+ 
5+本流程适用于在 msModelSlim 中配置和使用 AWQ 激活感知权重量化算法。AWQ 作为离群值抑制算法，通常作为权重量化前的预处理步骤，通过激活感知搜索最优缩放因子，提升低比特量化的精度。
6+ 
7+适用角色：算法工程师、模型部署工程师
8+ 
9+适用场景：
10+ 
11+- 需要自动搜索最优权重缩放因子、保护重要通道的低比特量化场景。
12+- 作为权重量化的前置步骤，为 MinMax、SSZ 等权重量化算法提供更优的权重分布。
13+ 
14+不适用场景：
15+ 
16+- 模型适配器未实现 `AWQInterface` 接口。
17+- 目标模块无 `weight` 属性或模块名无法通过 `named_modules()` 定位。
18+ 
19+## 2. 流程关系与前置条件
20+ 
21+**上级流程**：模型适配与验证通过后，确定量化方案阶段。
22+ 
23+**前置条件**：
24+ 
25+- 已安装兼容版本的 msModelSlim 工具（详见《[msModelSlim 工具安装指南](../../../install_guide/install_guide.md)》）。
26+- 已确认目标模型适配器实现了 `AWQInterface` 接口，并正确配置子图映射。
27+- 已确定下游权重量化方案（如 INT8、INT4），以便配置 `weight_qconfig`。
28+- 已准备好校准数据集，用于收集激活统计信息。
29+ 
30+**后续操作**：量化流程执行 → 精度验证 → 部署上线或进入调优。
31+ 
32+## 3. 输入和交付件
33+ 
34+| 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 |
35+| --- | --- | --- | --- | --- |
36+| 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被目标 Transformers 版本加载 |
37+| 输入 | 校准数据集 | 工具默认或用户指定 | JSONL 格式，每条含文本 prompt | 可被工具加载并完成前向推理 |
38+| 输入 | 量化 YAML 配置文件 | 用户编写 | 符合 msModelSlim YAML 规范，含 `awq` 处理器配置 | 可通过工具 `--config_path` 参数加载 |
39+| 交付件 | 平滑后的量化权重目录 | `--save_path` 指定路径 | 含 `quant_model_description.json` 及 `*.safetensors`，已应用最优缩放 | 推理冒烟通过 |
40+ 
41+## 4. 流程总览
42+ 
43+```mermaid
44+flowchart LR
45+ A[编写 YAML 配置] --> B[执行量化命令]
46+ B --> C[收集激活均值]
47+ C --> D[搜索并融合缩放]
48+ D --> E[验证量化结果]
49+```
50+ 
51+## 5. 操作步骤
52+ 
53+### 步骤 1：编写 YAML 配置文件
54+ 
55+**目标**：编写包含 `awq` 处理器配置的 YAML 文件。
56+ 
57+**操作**：
58+ 
59+1. 在 `spec.process` 下配置 `awq` 处理器，指定 `type: "awq"`。
60+2. 配置 `weight_qconfig`（AWQ 搜索阶段使用的权重量化配置）。
61+3. 按需配置 `n_grid`（默认 `20`）、`enable_subgraph_type` 与 `include`/`exclude`。
62+ 
63+YAML 配置示例：
64+ 
65+```yaml
66+spec:
67+ process:
68+ - type: "awq"
69+ weight_qconfig:
70+ scope: "per_channel"
71+ dtype: "int8"
72+ symmetric: true
73+ method: "minmax"
74+ n_grid: 20
75+ enable_subgraph_type:
76+ - "norm-linear"
77+ - "linear-linear"
78+ - "ov"
79+ - "up-down"
80+ include: ["*"]
81+ exclude: []
82+```
83+ 
84+YAML 配置字段详解如下：
85+ 
86+| 字段名 | 作用 | 说明 |
87+| --- | --- | --- |
88+| type | 处理器类型标识 | 固定为 `"awq"`。 |
89+| weight_qconfig | 权重量化配置 | AWQ 搜索阶段使用的权重量化配置，字段定义与 `linear_quant` 的 `qconfig.weight` 一致。 |
90+| n_grid | 网格搜索步数 | 正整数，默认 `20`，数值越大搜索越细致但耗时增加。 |
91+| enable_subgraph_type | 启用的子图类型 | 支持 `norm-linear`、`linear-linear`、`ov`、`up-down`。 |
92+| include | 包含的层 | 字符串列表，支持通配符匹配。 |
93+| exclude | 排除的层 | 字符串列表，支持通配符匹配，优先级高于 `include`。 |
94+ 
95+**输出**：YAML 配置文件 `${CONFIG_PATH}`。
96+ 
97+### 步骤 2：执行量化命令
98+ 
99+**目标**：使用上一步编写的 YAML 配置文件启动量化流程。
100+ 
101+**操作**：
102+ 
103+```bash
104+msmodelslim quant \
105+ --model_path ${MODEL_PATH} \
106+ --save_path ${SAVE_PATH} \
107+ --device npu \
108+ --model_type ${MODEL_TYPE} \
109+ --config_path ${CONFIG_PATH} \
110+ --trust_remote_code True
111+```
112+ 
113+参数说明：
114+ 
115+| 参数 | 必选 | 说明 |
116+| --- | --- | --- |
117+| `model_path` | 是 | 浮点模型权重路径 |
118+| `save_path` | 是 | 量化权重保存路径 |
119+| `device` | 否 | 量化设备，默认 `npu` |
120+| `model_type` | 是 | 模型名称，与支持矩阵一致 |
121+| `config_path` | 是 | 步骤 1 编写的 YAML 配置路径 |
122+| `trust_remote_code` | 否 | 是否信任远程代码，默认 `False` |
123+ 
124+执行流程说明：
125+ 
126+1. 工具加载 YAML 配置，解析 `awq` 处理器。
127+2. 预处理阶段为目标线性层安装 forward hook，收集激活均值并缓存祖先模块输入。
128+3. 后处理阶段按子图优先级搜索最优缩放因子，通过 `SubgraphFusionFactory` 融合。
129+4. 继续执行下游量化处理器并保存量化权重。
130+ 
131+**输出**：量化权重目录 `${SAVE_PATH}`，包含量化描述文件与权重分片。
132+ 
133+### 步骤 3：验证量化结果
134+ 
135+**目标**：确认量化权重文件完整且可加载。
136+ 
137+**操作**：
138+ 
139+1. 检查输出目录是否包含 `quant_model_description.json` 文件。
140+2. 检查日志确认无层匹配告警或祖先模块未找到告警。
141+3. 使用推理框架加载量化权重进行冒烟测试。
142+ 
143+**输出**：量化权重验证通过。
144+ 
145+## 6. 验收条件
146+ 
147+- 量化权重目录包含 `quant_model_description.json` 及所有必需的 `*.safetensors` 分片文件。
148+- 日志无激活统计信息缺失或中间参数缓存为空告警。
149+- 量化后模型推理精度不低于未使用 AWQ 的基线。
150+ 
151+## 7. 异常处置
152+ 
153+- **模块名不匹配**：`include/exclude` 未命中时日志提示未匹配模式，核对完整模块名。
154+- **祖先模块未找到**：日志提示 `No name found for inspect module of subgraph`，检查 `targets` 中的模块是否具有合理的共同路径前缀。
155+- **激活统计信息缺失**：日志提示 `No activation mean for target module`，确保校准数据足够且前向推理正常。
156+- **中间参数缓存为空**：日志提示 `No kwargs cache for parent module`，检查 LCA 发现的祖先模块是否被正确触发。
157+ 
158+## 8. 术语
159+ 
160+| 术语 | 简述 | 链接 |
161+| --- | --- | --- |
162+| AWQ | 激活感知权重量化，基于激活均值搜索最优缩放因子 | [AWQ 词条](./term_awq_smooth.md) |
163+| weight_qconfig | AWQ 搜索阶段使用的权重量化配置 | [AWQ 词条](./term_awq_smooth.md) |
164+| 最低公共祖先（LCA） | 用于块级误差评估的祖先模块 | [AWQ 词条](./term_awq_smooth.md) |
165+ 
166+## 9. 接口文档列表
167+ 
168+| 接口或能力 | 简述 | 链接 |
169+| --- | --- | --- |
170+| `awq` 处理器 | 用于执行激活感知权重量化的 Processor 配置 | [AWQ 词条](./term_awq_smooth.md) |
171+| `AWQInterface` | 模型适配器需实现的激活感知量化接口 | [AWQ 词条](./term_awq_smooth.md) |
Ddocs/zh/knowledge_base/quantization_algorithms/ceil_x/ceil_x.md+0-156
@@ -1,156 +0,0 @@
1-# Ceil_X：自适应除数 MXFP4 权重量化算法说明
2- 
3-## 简介
4- 
5-- **问题**：MXFP4 per-block 量化中，传统方法使用 $s = \lfloor \log_2(\max(|x|)) \rfloor - e_{\text{max}}$ 计算 shared exponent，缩放后数值范围为 $\max(|x|) / 2^s \in [4, 8)$，而 MXFP4 的表示上限为 6.0，导致 $\,[6, 8)$ 区间内的大值被截断，引入较大量化误差。
6-- **目标**：通过引入可配置除数 $c$ 配合 `ceil` 操作，将缩放后数值范围压缩至 MXFP4 的可表示区间内，减少大值截断，提升量化精度。
7- 
8-## 使用前准备
9- 
10-安装 msModelSlim 工具，详情请参见《[msModelSlim工具安装指南](../../../install_guide/install_guide.md)》。
11- 
12-## 原理和实现
13- 
14-### 原理
15- 
16-Ceil_X 算法针对传统 MXFP4 per-block 量化的大值截断问题，使用 **ceil** + **可配置除数** 重新设计 shared exponent 的计算方式。
17- 
18-**传统 floor 缩放的问题：**
19- 
20-传统方法计算 shared exponent：
21- 
22-$$s_{\text{floor}} = \lfloor \log_2(\max(|x|)) \rfloor - e_{\text{max}}$$
23- 
24-缩放后 block 内最大值的量级为：
25- 
26-$$\frac{\max(|x|)}{2^{s_{\text{floor}}}} = \frac{\max(|x|)}{2^{\lfloor \log_2(\max(|x|)) \rfloor - 2}} = 4 \cdot \frac{\max(|x|)}{2^{\lfloor \log_2(\max(|x|)) \rfloor}} \in [4, 8)$$
27- 
28-由于 $\max(|x|) / 2^{\lfloor \log_2(\max(|x|)) \rfloor} \in [1, 2)$，整体范围落在 $\,[4, 8)$。但 MXFP4 的表示上限为 6.0，$\,[6, 8)$ 区间内的值被截断，产生较大误差。
29- 
30-**Ceil_X 的改进：**
31- 
32-Ceil_X 引入除数 $c$ 并改用 ceil 操作。对于每个 block，缩放因子 $2^s$ 的计算方式为：
33- 
34-$$s = \text{ceil}\left(\log_2\left(\frac{\max(|x|)}{c}\right)\right)$$
35- 
36-缩放后 block 内最大值的量级为：
37- 
38-$$\frac{\max(|x|)}{2^s} = \frac{\max(|x|)}{2^{\text{ceil}(\log_2(\max(|x|)/c))}}$$
39- 
40-当 $\max(|x|) \in (c/2, c]$ 时，$\log_2(\max/c) \in (-1, 0]$，$\text{ceil}=0$，缩放后值为 $\max(|x|) \in (c/2, c]$；当 $\max(|x|) \in (c, 2c)$ 时，$\log_2(\max/c) \in (0, 1)$，$\text{ceil}=1$，缩放后值为 $\max(|x|)/2 \in (c/2, c)$。因此缩放后数值范围被压缩到 $(c/2, c]$。
41- 
42-默认 $c = 7.25$ 时，缩放后数值范围为 $(3.625, 7.25]$。相比传统方法的 $[4, 8)$：
43- 
44-- 下界从 $4$ 降至 $3.625$，为小值保留了更大的表示范围，提升小值量化精度
45-- $[6, 8)$ 区间仅剩 $(6, 7.25]$ 仍存在轻微截断，截断比例显著减小
46- 
47-**核心思想：**
48- 
49-1. **分块处理**：将权重矩阵沿指定轴按块大小 32 划分成独立的数据块。
50-2. **Ceil_X 缩放**：对每个数据块计算 shared exponent：
51- $$s = \text{ceil}\left(\log_2\left(\frac{\max(|x|)}{c} + \epsilon\right)\right) - e_{\text{max}}$$
52- 其中 $c$ 是可配置的除数（ceil_x_value），$\epsilon = 9.6 \times 10^{-7}$ 为数值稳定项，$e_{\text{max}} = 2^{e_{\text{bits}}-1} = 2$。
53-3. **自适应搜索（可选）**：在 $\,[c_{\text{min}}, c_{\text{max}}]$ 范围内以步长 $c_{\text{step}}$ 搜索使 MSE 最小的除数 $c$：
54- $$c^* = \arg\min_{c \in [c_{\text{min}}, c_{\text{max}}]} \sum_{\text{blocks}} \|x - \hat{x}(c)\|^2$$
55- 
56-### 实现
57- 
58-算法实现在 [`msmodelslim/core/quantizer/impl/ceil_x.py`](../../../../../msmodelslim/core/quantizer/impl/ceil_x.py) 中：
59- 
60-- 实现类：`MXWeightPerBlockCeilX`
61-- 注册的量化类型：`mxfp4_per_block_sym`
62-- 配置模型：`CeilXExtConfig`
63- 
64-**核心代码逻辑：**
65- 
66-```python
67-# 计算 per-block min/max
68-self.minmax_block_observer.update(weight_value, sync=False, shared_exp_axes=shared_exp_axes)
69-min_val, max_val = self.minmax_block_observer.get_min_max()
70- 
71-# 计算 ceil_x shared exponent
72-shared_exp = ceil(log2(max_val / ceil_x_value + 9.6e-7))
73-shared_exp = clip(shared_exp, -scale_emax - emax, scale_emax - emax)
74- 
75-# 量化
76-w_q_storage = quantize(QStorage(FLOAT, weight_value), q_param)
77-```
78- 
79-**enable_search 搜索策略：**
80- 
81-```python
82-# 在 [search_min, search_max] 内以 search_step 步长搜索最优 ceil_x_value
83-candidates = [search_min + i * search_step for i in range(num_steps)]
84-for value in candidates:
85- q_param = ceil_x_qparam(..., ceil_x_value=value)
86- recon = dequantize(quantize(weight, q_param), q_param).value
87- mse = ((weight - recon) ** 2).mean().item()
88- if mse < best_mse:
89- best_mse, best_value = mse, value
90-```
91- 
92-## 适用要求
93- 
94-- **精度提升**：适用于对 mxFP4 量化精度有更高要求的场景，尤其是权重分布范围较大、floor 缩放导致步长过粗的模型层。
95-- **计算成本**：无搜索模式时计算量与标准 MXFP4 量化一致；启用 enable_search 时增加若干次前向量化评估。
96- 
97-## 功能介绍
98- 
99-### YAML配置示例
100- 
101-```yaml
102-spec:
103- process:
104- - type: "linear_quant"
105- qconfig:
106- weight:
107- scope: "per_block"
108- dtype: "mxfp4"
109- symmetric: true
110- method: "ceil_x"
111- ext:
112- ceil_x_value: 7.25 # 除数，取值范围 [6.0, 12.0]
113- enable_search: false # 是否启用 MSE 搜索
114- search_min: 6.0 # 搜索范围下限
115- search_max: 12.0 # 搜索范围上限
116- search_step: 0.25 # 搜索步长
117-```
118- 
119-### YAML配置字段详解
120- 
121-#### qconfig.weight.ext (权重量化扩展参数)
122- 
123-| 参数名 | 作用 | 可选值 | 说明 | 默认值 |
124-|--------|------|--------|------|--------|
125-| `ceil_x_value` | 除数 $c$ | [6.0, 12.0] | 控制 shared exponent 的收紧程度 | 7.25 |
126-| `enable_search` | 是否启用 MSE 搜索 | `true`, `false` | 在搜索范围内寻找最优除数 | `false` |
127-| `search_min` | 搜索范围下限 | [6.0, 12.0] | MSE 搜索的起始值 | 6.0 |
128-| `search_max` | 搜索范围上限 | [6.0, 12.0] | MSE 搜索的结束值，须大于 search_min | 12.0 |
129-| `search_step` | 搜索步长 | > 0 | 搜索时的步进间隔 | 0.25 |
130- 
131-## 技术优势
132- 
133-### 与传统 mxFP4 量化的对比
134- 
135-| 特性 | 传统 mxFP4 量化 | Ceil_X 量化 |
136-|------|----------------|-------------|
137-| 缩放因子 | $2^{\lfloor \log_2(\max) \rfloor - 2}$ | $2^{\text{ceil}(\log_2(\max / c))}$ |
138-| 缩放后数值范围 | $[4, 8)$ | $(c/2, c] = (3.625, 7.25]$ |
139-| 大值截断 | $[6, 8)$ 区间被截断 | 仅 $(6, 7.25]$ 轻微截断，截断比例显著减小 |
140-| 小值表示范围 | 下界 $4$ | 下界 $3.625$，小值量化精度更高 |
141-| 自适应搜索 | 不支持 | 可选 MSE 最优搜索 |
142-| 计算复杂度 | O(N) | O(N)（无搜索）/ O(kN)（搜索时） |
143- 
144-## FAQ
145- 
146-### Ceil_X 名称的由来？
147- 
148-Ceil_X 来源于算法使用的两个核心操作：`ceil`（向上取整）和可配置除数 `x`（ceil_x_value）。与 floor 缩放相比，ceil 操作将缩放后数值范围从 $[4, 8)$ 压缩至 $(c/2, c]$，完全落在 MXFP4 的可表示区间 $[0, 6]$ 内，避免大值截断。
149- 
150-### 默认值 7.25 是如何确定的？
151- 
152-7.25 在 W4A4 MXFP4 对称量化中经多次经验验证得到。在该取值下，ceil 操作使缩放后数值范围从 $[4, 8)$ 压缩至 $(3.625, 7.25]$，完全落在 MXFP4 的表示范围内，消除大值截断误差。
153- 
154-### enable_search 模式搜索的是什么？
155- 
156-搜索在同一层权重上寻找使整体 MSE 最小的全局除数 $c$（非 per-block 独立搜索）。搜索结果存入独立字段，不会修改用户的原始配置值。
Adocs/zh/knowledge_base/quantization_algorithms/ceil_x/term_ceil_x.md+173-0
@@ -0,0 +1,173 @@
1+# Ceil_X 自适应除数 MXFP4 量化算法词条
2+ 
3+> **词条类别**：量化算法
4+> **英文名称**：Ceil_X
5+> **英文缩写**：Ceil_X
6+> **应用领域**：MXFP4 权重量化、低比特量化精度优化
7+> **msModelSlim 实现**：`msmodelslim/core/quantizer/impl/ceil_x.py`
8+ 
9+---
10+ 
11+## 1. 概述
12+ 
13+Ceil_X 是一种针对 MXFP4 per-block 权重量化的精度优化算法。它通过引入可配置除数 $c$ 配合 `ceil` 操作重新设计 shared exponent 的计算方式，将缩放后数值范围压缩至 MXFP4 的可表示区间内，减少大值截断，提升量化精度。其核心特征是：ceil + 可配置除数、可选全局 MSE 搜索最优除数、零配置开箱即用，是 [MinMax](../minmax/term_minmax.md) MXFP4 量化的截断抑制优化。
14+ 
15+---
16+ 
17+## 2. 词条介绍
18+ 
19+MXFP4 per-block 量化中，传统方法使用 $s = \lfloor \log_2(\max(|x|)) \rfloor - e_{\text{max}}$ 计算 shared exponent，缩放后数值范围为 $[4, 8)$，而 MXFP4 的表示上限为 $6.0$，导致 $[6, 8)$ 区间内的大值被截断，引入较大量化误差。Ceil_X 通过引入可配置除数 $c$ 配合 `ceil` 操作，将缩放后数值范围压缩至 $(c/2, c]$，完全落在 MXFP4 的可表示区间内。
20+ 
21+---
22+ 
23+## 3. 原理
24+ 
25+### 1. 核心思想
26+ 
27+Ceil_X 的核心思想是“用 ceil + 可配置除数收紧缩放范围”：对每个 block，使用 `ceil(log2(max(|x|) / c))` 计算 shared exponent，其中 $c$ 是可配置的除数（`ceil_x_value`）。相比传统 floor 缩放，ceil 操作将缩放后数值范围从 $[4, 8)$ 压缩至 $(c/2, c]$，消除大值截断；当启用搜索模式时，在搜索范围内寻找使整体 MSE 最小的全局除数 $c$。
28+ 
29+### 2. 数学描述
30+ 
31+传统 floor 缩放：
32+ 
33+$$
34+s_{\text{floor}} = \lfloor \log_2(\max(|x|)) \rfloor - e_{\text{max}}
35+$$
36+ 
37+Ceil_X 缩放：
38+ 
39+$$
40+s = \operatorname{ceil}\left(\log_2\left(\frac{\max(|x|)}{c} + \epsilon\right)\right) - e_{\text{max}}
41+$$
42+ 
43+- $s$：shared exponent
44+- $\max(|x|)$：block 内权重绝对值的最大值
45+- $c$：可配置除数（`ceil_x_value`，默认 $7.25$）
46+- $\epsilon$：数值稳定项，$\epsilon = 9.6 \times 10^{-7}$
47+- $e_{\text{max}}$：指数偏置，MXFP4 E4M2 格式下 $e_{\text{max}} = 2^{e_{\text{bits}}-1} = 2$
48+ 
49+缩放后 block 内最大值的量级：
50+ 
51+$$
52+\frac{\max(|x|)}{2^s} = \frac{\max(|x|)}{2^{\operatorname{ceil}(\log_2(\max(|x|)/c))}} \in \left(\frac{c}{2}, c\right]
53+$$
54+ 
55+默认 $c = 7.25$ 时，缩放后数值范围为 $(3.625, 7.25]$，相比传统方法的 $[4, 8)$：下界降低、截断比例显著减小。
56+ 
57+可选的自适应搜索：
58+ 
59+$$
60+c^* = \arg\min_{c \in [c_{\min}, c_{\max}]} \sum_{\text{blocks}} \|x - \hat{x}(c)\|^2
61+$$
62+ 
63+- $c^*$：搜索得到的最优除数
64+- $c_{\min}$、$c_{\max}$：搜索范围（默认 $[6.0, 12.0]$）
65+- $\hat{x}(c)$：使用除数 $c$ 量化-反量化后的值
66+ 
67+### 3. 关键性质
68+ 
69+- **ceil 缩放**：使用 ceil 操作收紧缩放范围，避免大值截断。
70+- **可配置除数**：`ceil_x_value` 控制缩放收紧程度，默认 $7.25$。
71+- **自适应搜索**：可选启用全局 MSE 搜索最优除数 $c$。
72+- **零配置可用**：不启用搜索时无额外超参，开箱即用。
73+ 
74+---
75+ 
76+## 4. 流程示意
77+ 
78+> 以下为本算法在 msModelSlim 中的简化流程概览。
79+ 
80+```mermaid
81+flowchart LR
82+ A[分块处理] --> B[计算 ceil_x 指数]
83+ B --> C[量化-反量化]
84+ C --> D{启用搜索?}
85+ D -- 是 --> E[搜索最优除数]
86+ D -- 否 --> F[输出量化结果]
87+ E --> F
88+```
89+ 
90+---
91+ 
92+## 5. 在 msModelSlim 中的实现
93+ 
94+### 1. 实现位置
95+ 
96+算法在 `msmodelslim/core/quantizer/impl/ceil_x.py` 中实现，实现类为 `MXWeightPerBlockCeilX`，注册的量化类型为 `mxfp4_per_block_sym`，配置模型为 `CeilXExtConfig`，作为 `linear_quant` 处理器的权重量化方法（`method: "ceil_x"`）使用。
97+ 
98+### 2. 处理流程
99+ 
100+1. 使用 `minmax_block_observer` 计算 per-block min/max。
101+2. 计算 ceil_x shared exponent：`shared_exp = ceil(log2(max_val / ceil_x_value + 9.6e-7))`，并进行 clip 限制。
102+3. 量化权重。
103+4. 启用 `enable_search` 时，在 `[search_min, search_max]` 内以 `search_step` 步长搜索使整体 MSE 最小的 `ceil_x_value`。
104+ 
105+### 3. 配置示例
106+ 
107+> 以下为最小可用的 YAML 配置片段。各字段的详细含义如下表所示。
108+ 
109+```yaml
110+spec:
111+ process:
112+ - type: "linear_quant"
113+ qconfig:
114+ weight:
115+ scope: "per_block"
116+ dtype: "mxfp4"
117+ symmetric: true
118+ method: "ceil_x"
119+ ext:
120+ ceil_x_value: 7.25
121+ enable_search: false
122+```
123+ 
124+**字段说明**：
125+ 
126+| 字段名 | 作用 | 说明 |
127+| --- | --- | --- |
128+| scope | 量化范围 | 固定为 `"per_block"`。 |
129+| dtype | 量化数据类型 | 固定为 `"mxfp4"`。 |
130+| symmetric | 是否对称量化 | `true`。 |
131+| method | 量化方法 | 固定为 `"ceil_x"`。 |
132+| ext.ceil_x_value | 除数 | 取值范围 `[6.0, 12.0]`，默认 `7.25`。 |
133+| ext.enable_search | 是否启用 MSE 搜索 | `true`/`false`，默认 `false`。 |
134+| ext.search_min | 搜索范围下限 | 默认 `6.0`。 |
135+| ext.search_max | 搜索范围上限 | 须大于 `search_min`，默认 `12.0`。 |
136+| ext.search_step | 搜索步长 | 大于 0，默认 `0.25`。 |
137+ 
138+---
139+ 
140+## 6. 适用场景与限制
141+ 
142+### 1. 适用场景
143+ 
144+- 对 mxFP4 量化精度有更高要求的场景。
145+- 权重分布范围较大、floor 缩放导致步长过粗或大值截断的模型层。
146+ 
147+### 2. 使用限制
148+ 
149+- 仅支持 mxFP4 格式的 per_block 对称量化。
150+- 启用 `enable_search` 时增加若干次前向量化评估，计算开销增大。
151+- `search_max` 须大于 `search_min`。
152+ 
153+---
154+ 
155+## 7. 关联流程
156+ 
157+- 《[一键量化 (V1)](../../../user_guide/usage_quick_quantization.md)》：可集成 Ceil_X 作为 MXFP4 权重量化步骤。
158+- 《[量化精度调优指南](../../../user_guide/process_quantization_precision_tuning.md)》：精度不达标时可考虑使用 Ceil_X。
159+ 
160+---
161+ 
162+## 8. 关联词条
163+ 
164+- [线性量化](../linear_quant/term_linear_quant.md)：应用对象，Ceil_X 作为线性量化的权重量化方法使用。
165+- [FouroverSix](../fouroversix/term_fouroversix.md)：同类算法，同为 MXFP4 格式的缩放策略优化算法。
166+- [MSE_Round](../mse_round/term_mse_round.md)：同类算法，同为 MXFP 格式的 shared exponent 优化算法（针对 MXFP8）。
167+- [MinMax](../minmax/term_minmax.md)：对比算法，Ceil_X 是 MinMax MXFP4 量化的截断抑制优化。
168+ 
169+---
170+ 
171+## 9. 参考资料
172+ 
173+1. 《Ceil_X 使用指南》([./usage_ceil_x.md](./usage_ceil_x.md))
Adocs/zh/knowledge_base/quantization_algorithms/ceil_x/usage_ceil_x.md+169-0
@@ -0,0 +1,169 @@
1+# Ceil_X 使用指南
2+ 
3+## 1. 适用范围
4+ 
5+本流程适用于在 msModelSlim 中配置和使用 Ceil_X 自适应除数 MXFP4 量化算法。Ceil_X 作为 `linear_quant` 处理器的权重量化方法，通过 ceil + 可配置除数优化 shared exponent，减少大值截断，提升 mxFP4 权重量化精度。
6+ 
7+适用角色：算法工程师、模型部署工程师
8+ 
9+适用场景：
10+ 
11+- 对 mxFP4 量化精度有更高要求的场景。
12+- 权重分布范围较大、floor 缩放导致步长过粗或大值截断的模型层。
13+ 
14+不适用场景：
15+ 
16+- 非 mxFP4 格式或非 per_block 对称量化的场景。
17+ 
18+## 2. 流程关系与前置条件
19+ 
20+**上级流程**：模型适配与验证通过后，确定量化方案阶段。
21+ 
22+**前置条件**：
23+ 
24+- 已安装兼容版本的 msModelSlim 工具（详见《[msModelSlim 工具安装指南](../../../install_guide/install_guide.md)》）。
25+- 已确认目标模型包含可量化的 `nn.Linear` 模块。
26+- 已确定量化方案为 mxFP4 per_block 对称量化。
27+ 
28+**后续操作**：量化流程执行 → 精度验证 → 部署上线或进入调优。
29+ 
30+## 3. 输入和交付件
31+ 
32+| 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 |
33+| --- | --- | --- | --- | --- |
34+| 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被目标 Transformers 版本加载 |
35+| 输入 | 量化 YAML 配置文件 | 用户编写 | 符合 msModelSlim YAML 规范，含 `method: "ceil_x"` 权重量化配置 | 可通过工具 `--config_path` 参数加载 |
36+| 交付件 | 量化权重目录 | `--save_path` 指定路径 | 含 `quant_model_description.json` 及 `*.safetensors`，已应用 Ceil_X 量化 | 推理冒烟通过 |
37+ 
38+## 4. 流程总览
39+ 
40+```mermaid
41+flowchart LR
42+ A[编写 YAML 配置] --> B[执行量化命令]
43+ B --> C[计算 ceil_x 指数]
44+ C --> D[量化并部署]
45+ D --> E[验证量化结果]
46+```
47+ 
48+## 5. 操作步骤
49+ 
50+### 步骤 1：编写 YAML 配置文件
51+ 
52+**目标**：编写包含 Ceil_X 权重量化配置的 YAML 文件。
53+ 
54+**操作**：
55+ 
56+1. 在 `spec.process` 下配置 `linear_quant` 处理器。
57+2. 在 `qconfig.weight` 中设置 `scope: "per_block"`、`dtype: "mxfp4"`、`symmetric: true`、`method: "ceil_x"`。
58+3. 按需在 `ext` 中配置 `ceil_x_value`、`enable_search`、`search_min`、`search_max`、`search_step`。
59+ 
60+YAML 配置示例：
61+ 
62+```yaml
63+spec:
64+ process:
65+ - type: "linear_quant"
66+ qconfig:
67+ weight:
68+ scope: "per_block"
69+ dtype: "mxfp4"
70+ symmetric: true
71+ method: "ceil_x"
72+ ext:
73+ ceil_x_value: 7.25 # 除数，取值范围 [6.0, 12.0]
74+ enable_search: false # 是否启用 MSE 搜索
75+ search_min: 6.0 # 搜索范围下限
76+ search_max: 12.0 # 搜索范围上限
77+ search_step: 0.25 # 搜索步长
78+```
79+ 
80+YAML 配置字段详解如下：
81+ 
82+| 字段名 | 作用 | 说明 |
83+| --- | --- | --- |
84+| scope | 量化范围 | 固定为 `"per_block"`。 |
85+| dtype | 量化数据类型 | 固定为 `"mxfp4"`。 |
86+| symmetric | 是否对称量化 | `true`。 |
87+| method | 量化方法 | 固定为 `"ceil_x"`。 |
88+| ext.ceil_x_value | 除数 | 取值范围 `[6.0, 12.0]`，默认 `7.25`。 |
89+| ext.enable_search | 是否启用 MSE 搜索 | `true`/`false`，默认 `false`。 |
90+| ext.search_min | 搜索范围下限 | 默认 `6.0`。 |
91+| ext.search_max | 搜索范围上限 | 须大于 `search_min`，默认 `12.0`。 |
92+| ext.search_step | 搜索步长 | 大于 0，默认 `0.25`。 |
93+ 
94+**输出**：YAML 配置文件 `${CONFIG_PATH}`。
95+ 
96+### 步骤 2：执行量化命令
97+ 
98+**目标**：使用上一步编写的 YAML 配置文件启动量化流程。
99+ 
100+**操作**：
101+ 
102+```bash
103+msmodelslim quant \
104+ --model_path ${MODEL_PATH} \
105+ --save_path ${SAVE_PATH} \
106+ --device npu \
107+ --model_type ${MODEL_TYPE} \
108+ --config_path ${CONFIG_PATH} \
109+ --trust_remote_code True
110+```
111+ 
112+参数说明：
113+ 
114+| 参数 | 必选 | 说明 |
115+| --- | --- | --- |
116+| `model_path` | 是 | 浮点模型权重路径 |
117+| `save_path` | 是 | 量化权重保存路径 |
118+| `device` | 否 | 量化设备，默认 `npu` |
119+| `model_type` | 是 | 模型名称，与支持矩阵一致 |
120+| `config_path` | 是 | 步骤 1 编写的 YAML 配置路径 |
121+| `trust_remote_code` | 否 | 是否信任远程代码，默认 `False` |
122+ 
123+执行流程说明：
124+ 
125+1. 工具加载 YAML 配置，解析 `linear_quant` 处理器与 Ceil_X 配置。
126+2. 量化器计算每个 block 的 ceil_x shared exponent。
127+3. 启用 `enable_search` 时搜索最优除数 `ceil_x_value`。
128+4. 保存量化权重。
129+ 
130+**输出**：量化权重目录 `${SAVE_PATH}`，包含量化描述文件与权重分片。
131+ 
132+### 步骤 3：验证量化结果
133+ 
134+**目标**：确认量化权重文件完整且可加载。
135+ 
136+**操作**：
137+ 
138+1. 检查输出目录是否包含 `quant_model_description.json` 文件。
139+2. 检查日志确认量化流程正常完成。
140+3. 使用推理框架加载量化权重进行冒烟测试。
141+ 
142+**输出**：量化权重验证通过。
143+ 
144+## 6. 验收条件
145+ 
146+- 量化权重目录包含 `quant_model_description.json` 及所有必需的 `*.safetensors` 分片文件。
147+- 日志无配置组合无效告警。
148+- 量化后模型推理精度优于使用固定 floor 缩放（minmax）的基线。
149+ 
150+## 7. 异常处置
151+ 
152+- **配置组合无效**：确认权重 `scope` 为 `per_block`、`dtype` 为 `mxfp4`、`method` 为 `ceil_x`。
153+- **搜索范围配置错误**：确认 `search_max` 大于 `search_min`，且取值在 `[6.0, 12.0]` 内。
154+- **精度不达标**：调整 `ceil_x_value` 或在 `[6.0, 12.0]` 内启用 `enable_search` 搜索最优除数。
155+ 
156+## 8. 术语
157+ 
158+| 术语 | 简述 | 链接 |
159+| --- | --- | --- |
160+| Ceil_X | 使用 ceil + 可配置除数优化 MXFP4 shared exponent 的算法 | [Ceil_X 词条](./term_ceil_x.md) |
161+| shared exponent | MXFP 格式中 block 共享的指数缩放参数 | [Ceil_X 词条](./term_ceil_x.md) |
162+| ceil_x_value | 可配置除数，控制缩放收紧程度 | [Ceil_X 词条](./term_ceil_x.md) |
163+ 
164+## 9. 接口文档列表
165+ 
166+| 接口或能力 | 简述 | 链接 |
167+| --- | --- | --- |
168+| `linear_quant` 处理器 | 线性层量化处理器，通过 `method: "ceil_x"` 启用 Ceil_X | [线性量化词条](../linear_quant/term_linear_quant.md) |
169+| `MXWeightPerBlockCeilX` | Ceil_X 权重量化实现类 | [Ceil_X 词条](./term_ceil_x.md) |
Ddocs/zh/knowledge_base/quantization_algorithms/dual_scale/dual_scale.md+0-148
@@ -1,148 +0,0 @@
1-# DualScale：w4a4量化方案说明
2- 
3-## 简介
4- 
5-- **背景**：传统的分组量化通常采用单尺度（single-scale）策略：每组K维元素共享一个缩放因子。例如，MXFP4格式中每32个元素使用一个FP8格式的共享指数。然而，激活值中存在结构化的异常通道（outlier
6- channels）——某些通道的值平均比其他通道高出数个数量级。单尺度量化难以同时精准表示这些差异巨大的数值范围，导致精度损失。
7-- **核心思想**：通过两级粒度递进的缩放因子，在保持硬件高效性的同时提升4比特量化的精度。
8- 
9-## 使用前准备
10- 
11-安装 msModelSlim 工具，详情请参见《[msModelSlim工具安装指南](../../../install_guide/install_guide.md)》。
12- 
13-## 原理和实现
14- 
15-### 原理
16- 
17-计算逻辑与核心公式如下：
18- 
19-#### 1.权重激活值 (Activation) 的动态量化与反量化 (Fake Quantization)
20- 
21-**a) 外层缩放 (Dual Scale)**
22- 
23-将输入 X 按照 `x_dual_block_size` 划分，计算每个大块的最大绝对值，得到外层尺度 $S_{dual\_x}$:
24-$$X_{dualscaled} = \frac{X}{S_{dual\_x}}, \quad S_{dual\_x} = \frac{\max(|X_{block}|)}{{MXFP4\_MAX\_NORMAL}}$$
25- 
26-**b) 内层量化与反量化 (Inner Quant-Dequant)**
27- 
28-将 $X_{dualscaled}$ 进一步按 `x_inner_block_size` 划分，计算内层尺度并转换为目标低比特格式：
29-$$X_{q\_dq\_inner} = \text{mxfp4\_quantize\_dequantize}(X_{dualscaled}, S_{inner\_x})$$
30- 
31-**c) 外层反量化 (Dual Scale Dequantization)**
32- 
33-$$X_{q\_dq} = X_{q\_dq\_inner} \times S_{dual\_x}$$
34- 
35-#### 2. 权重 (Weight) 的静态反量化 (Dequantization)
36- 
37-权重在初始化时已完成了量化存储，前向传播时仅进行两级反量化恢复至高精度：
38- 
39-**a) 内层反量化 (Inner Dequantization)**
40- 
41-根据内层参数 `inner_w_q_param` 恢复基础缩放：
42-$$W_{dualscaled\_q\_dq} = \text{dequantize}(W_{quantized}, S_{inner\_w})$$
43- 
44-**b) 外层反量化 (Dual Scale Dequantization)**
45- 
46-乘以模型初始化时固化的外层权重尺度 `weight_dual_scale` ($S_{dual\_w}$):
47-$$W_{q\_dq} = W_{dualscaled\_q\_dq} \times S_{dual\_w}$$
48- 
49-#### 3. 矩阵乘法 (Linear Inverted)
50- 
51-$$\text{Output} = X_{q\_dq} \cdot W_{q\_dq}^T + \text{bias}$$
52- 
53-### 实现
54- 
55-DualScale 方案通过两个量化器协同实现双尺度量化，两者均通过 `QABCRegistry.multi_register` 注册，dispatch_key 为 `(qir.mxfp4_dual_scale_sym, "dualscale")`：
56- 
57-1. **权重双尺度量化器**（`MXWeightDualScaleMinmax`，继承 `AutoWeightQuantizer`）：在权重初始化阶段完成静态量化。
58- - 内层封装一个 `QScope.PER_BLOCK` 的 mxfp4 量化器，用于执行内层 block 量化。
59- - `init_weight` 流程：
60- 1. 按 `axes` 与 `dual_block_size` 将权重重塑为块状；
61- 2. 通过 `MsMinMaxBlockObserver` 统计每个外层块的最大值，计算外层尺度 $S_{dual\_w} = \frac{\max(|W_{block}|)}{\text{MXFP4\_MAX\_NORMAL}}$（其中 `MXFP4_MAX_NORMAL = 6.0`）；
62- 3. 权重除以 $S_{dual\_w}$ 后交由内层量化器进行 mxfp4 量化存储；
63- 4. 外层尺度 $S_{dual\_w}$ 以参数形式保存在 `q_param.ext['dual_scale']` 中。
64- - `forward`（反量化）流程：
65- 1. 调用内层量化器完成内层反量化；
66- 2. 将结果重塑为块状；
67- 3. 乘以 $S_{dual\_w}$ 恢复外层尺度；
68- 4. 还原原始形状后返回。
69- 
70-2. **激活双尺度量化器**（`MXActDualScaleMinmax`，继承 `AutoActQuantizer`）：data-free 量化，`is_data_free` 返回 `True`。
71- - `forward` 直接返回输入 `x`（伪量化，实际量化在推理阶段由硬件完成）；
72- - 配置参数与权重量化器保持一致，包含 `dual_block_size` 与 `axes`，确保权重和激活采用相同的双尺度分块策略。
73- 
74-## 适用要求
75- 
76-- **低比特量化**：适合极低比特量化场景中的4比特量化。
77-- **高精度需求**：在低比特条件下仍能保持较高的模型精度。
78-- **计算资源**：需要额外的优化过程，计算成本高于简单量化方法。
79-- **使用限制**：
80- 
81- - 需要足够的校准数据或训练迭代次数来优化参数，由于涉及到迭代优化，量化时长相对其他方法较久。
82- - 当前该方案主要面向Qwen3稠密系列模型（如Qwen3-8B/14B/32B）的低比特量化场景，不保证可泛化到其他系列模型。
83- 
84-## 功能介绍
85- 
86-> [!NOTE]
87->
88->算法实现包含训练过程，对NPU显存有一定的要求，仅支持NPU显存>=64G的设备。
89- 
90-### YAML配置示例
91- 
92-作为Processor使用，YAML配置示例如下：
93- 
94-```yaml
95- process:
96- - type: "linear_quant"
97- qconfig:
98- act:
99- scope: "dual_scale"
100- dtype: "mxfp4"
101- symmetric: True
102- method: "dualscale"
103- ext: {
104- dual_block_size: 512
105- }
106- weight:
107- scope: "dual_scale"
108- dtype: "mxfp4"
109- symmetric: True
110- method: "dualscale"
111- ext: {
112- dual_block_size: 512
113- }
114-```
115- 
116-### YAML配置字段详解
117- 
118-#### qconfig.act (激活值量化配置)
119- 
120-**作用**: 配置激活值的量化参数。
121- 
122-| 参数名 | 作用 | 可选值 | 说明 | 默认值 |
123-|-----------------|---------|-----------------|----------------------------------------|---------------|
124-| scope | 量化范围 | `"dual_scale"` | dual_scale: 双尺度 | `"per_block"` |
125-| dtype | 量化数据类型 | `"mxfp4"` | mxFP4 格式量化 | `"mxfp4"` |
126-| symmetric | 是否对称量化 | `True`, `False` | true: 对称量化，零点为0<br/>false: 非对称量化，零点可调整 | `True` |
127-| method | 量化方法 | `"dualscale"` | dualscale: 二级量化算法 | `"dualscale"` |
128-| ext | 扩展配置 | `object` | 包含 DualScale 特有的配置参数 | [见下方详细配置](#ext-dualscale扩展配置) |
129- 
130-#### qconfig.weight (权重量化配置)
131- 
132-**作用**: 配置权重的量化参数。
133- 
134-| 参数名 | 作用 | 可选值 | 说明 | 默认值 |
135-|-----------------|---------|-----------------|----------------------------------------|---------------|
136-| scope | 量化范围 | `"dual_scale"` | dual_scale: 双尺度 | `"per_block"` |
137-| dtype | 量化数据类型 | `"mxfp4"` | mxFP4 格式量化 | `"mxfp4"` |
138-| symmetric | 是否对称量化 | `True`, `False` | true: 对称量化，零点为0<br/>false: 非对称量化，零点可调整 | `True` |
139-| method | 量化方法 | `"dualscale"` | dualscale: 二级量化算法 | `"dualscale"` |
140-| ext | 扩展配置 | `object` | 包含 DualScale 特有的配置参数 | [见下方详细配置](#ext-dualscale扩展配置) |
141- 
142-#### ext (DualScale扩展配置)
143- 
144-**作用**: 配置 DualScale 算法特有的参数。
145- 
146-| 参数名 | 作用 | 类型 | 说明 | 示例值 |
147-|-----------------|---------|--------|-----------------------------------|-------|
148-| dual_block_size | block大小 | `int` | dual_block_size: block大小 | `512` |