已合并
[Doc] 整改知识库 quantization_algorithms 量化算法文档 #876
wanlongze123创建于 8月25日
[Doc] 整改知识库 quantization_algorithms 量化算法文档 #876
已合并
共 62 个文件变更+3411-5887
| @@ -1,66 +1,66 @@ | |||
| 1 | ---- | ||
| 2 | -toc_depth: 3 | ||
| 3 | ---- | ||
| 4 | # 量化算法总览 | 1 | # 量化算法总览 |
| 5 | 2 | ||
| 6 | msModelSlim 支持多种先进的量化算法，涵盖了从离群值抑制到低比特优化的各个环节。下表按类别总结了目前支持的核心算法及其主要特性。 | 3 | msModelSlim 支持多种先进的量化算法，涵盖了从离群值抑制到低比特优化的各个环节。下表按类别总结了目前支持的核心算法及其主要特性。 |
| 7 | 4 | ||
| 8 | -## 离群值抑制算法 | 5 | +> **阅读建议**：每个算法目录包含“词条”和“使用指南”两类文档。词条只介绍算法定义、原理、性质、适用场景与关联知识；使用指南面向入门用户，重点解释配置参数的含义、推荐起步值以及何时调整。需要查询完整字段类型、默认值和高级任务级配置时，请继续阅读《[modelslim_v1 配置说明](../../api_reference/config/task/modelslim_v1.md)》。 |
| 6 | + | ||
| 7 | +## 1. 离群值抑制算法 | ||
| 9 | 8 | ||
| 10 | 离群值抑制算法旨在平滑激活值的分布，减少量化带来的精度损失。 | 9 | 离群值抑制算法旨在平滑激活值的分布，减少量化带来的精度损失。 |
| 11 | 10 | ||
| 12 | | 算法名称 | 核心思想 | 适用场景 | 词条 | 使用指南 | | 11 | | 算法名称 | 核心思想 | 适用场景 | 词条 | 使用指南 | |
| 13 | | :--- | :--- | :--- | :--- | :--- | | 12 | | :--- | :--- | :--- | :--- | :--- | |
| 14 | -| **QuaRot** | 应用正交旋转矩阵平滑激活值分布 | 抑制激活离群值，提升精度 | [词条](quarot/term_quarot.md) | [使用指南](quarot/usage_quarot.md) | | 13 | +| **QuaRot** | 应用正交旋转矩阵平滑激活值分布 | 抑制激活离群值，提升精度 | [QuaRot 词条](quarot/term_quarot.md) | [QuaRot 使用指南](quarot/usage_quarot.md) | |
| 15 | -| **Adapt Rotation** | 在QuaRot基础上使用基于校准数据迭代优化 Hadamard 旋转矩阵 | 优化旋转矩阵，进一步提升低比特量化精度 | [词条](adapt_rotation/term_adapt_rotation.md) | [使用指南](adapt_rotation/usage_adapt_rotation.md) | | 14 | +| **Adapt Rotation** | 在 QuaRot 基础上使用基于校准数据迭代优化 Hadamard 旋转矩阵 | 优化旋转矩阵，进一步提升低比特量化精度 | [Adapt Rotation 词条](adapt_rotation/term_adapt_rotation.md) | [Adapt Rotation 使用指南](adapt_rotation/usage_adapt_rotation.md) | |
| 16 | -| **SmoothQuant** | 协同缩放激活与权重，平滑离群值 | 抑制激活离群值 | [词条](smooth_quant/term_smooth_quant.md) | [使用指南](smooth_quant/usage_smooth_quant.md) | | 15 | +| **SmoothQuant** | 协同缩放激活与权重，平滑离群值 | 抑制激活离群值 | [SmoothQuant 词条](smooth_quant/term_smooth_quant.md) | [SmoothQuant 使用指南](smooth_quant/usage_smooth_quant.md) | |
| 17 | -| **Iterative Smooth** | 迭代式平滑缩放，更精细的分布调整 | 复杂分布下的精度优化 | [词条](iterative_smooth/term_iterative_smooth.md) | [使用指南](iterative_smooth/usage_iterative_smooth.md) | | 16 | +| **Iterative Smooth** | 迭代式平滑缩放，更精细的分布调整 | 复杂分布下的精度优化 | [Iterative Smooth 词条](iterative_smooth/term_iterative_smooth.md) | [Iterative Smooth 使用指南](iterative_smooth/usage_iterative_smooth.md) | |
| 18 | -| **Flex Smooth Quant** | 二阶段网格搜索自动寻找最优 alpha/beta | 灵活适配不同架构 | [词条](flex_smooth_quant/term_flex_smooth_quant.md) | [使用指南](flex_smooth_quant/usage_flex_smooth_quant.md) | | 17 | +| **Flex Smooth Quant** | 二阶段网格搜索自动寻找最优 alpha/beta | 灵活适配不同架构 | [Flex Smooth Quant 词条](flex_smooth_quant/term_flex_smooth_quant.md) | [Flex Smooth Quant 使用指南](flex_smooth_quant/usage_flex_smooth_quant.md) | |
| 19 | -| **Flex AWQ SSZ** | 结合 AWQ 与 SSZ，使用真实量化器评估误差 | 自动搜索最优平滑参数 | [词条](flex_awq_ssz/term_flex_awq_ssz.md) | [使用指南](flex_awq_ssz/usage_flex_awq_ssz.md) | | 18 | +| **Flex AWQ SSZ** | 结合 AWQ 与 SSZ，使用真实量化器评估误差 | 自动搜索最优平滑参数 | [Flex AWQ SSZ 词条](flex_awq_ssz/term_flex_awq_ssz.md) | [Flex AWQ SSZ 使用指南](flex_awq_ssz/usage_flex_awq_ssz.md) | |
| 20 | -| **KV Smooth** | 针对 KV Cache 的平滑抑制算法 | 降低 KV Cache 显存占用 | [词条](kv_smooth/term_kv_smooth.md) | [使用指南](kv_smooth/usage_kv_smooth.md) | | 19 | +| **KV Smooth** | 针对 KV Cache 的平滑抑制算法 | 降低 KV Cache 显存占用 | [KV Smooth 词条](kv_smooth/term_kv_smooth.md) | [KV Smooth 使用指南](kv_smooth/usage_kv_smooth.md) | |
| 21 | -| **AWQ** | 基于激活值统计特征网格搜索最优缩放因子 | 自动搜索最优平滑参数 | [词条](awq_smooth/term_awq_smooth.md) | [使用指南](awq_smooth/usage_awq_smooth.md) | | 20 | +| **AWQ** | 基于激活值统计特征网格搜索最优缩放因子 | 自动搜索最优平滑参数 | [AWQ 词条](awq_smooth/term_awq_smooth.md) | [AWQ 使用指南](awq_smooth/usage_awq_smooth.md) | |
| 22 | 21 | ||
| 23 | -## 量化算法 | 22 | +## 2. 量化算法 |
| 24 | 23 | ||
| 25 | 包含权重量化、激活量化以及针对特定结构的量化方案。 | 24 | 包含权重量化、激活量化以及针对特定结构的量化方案。 |
| 26 | 25 | ||
| 27 | | 算法名称 | 类型 | 核心思想 | 适用场景 | 词条 | 使用指南 | | 26 | | 算法名称 | 类型 | 核心思想 | 适用场景 | 词条 | 使用指南 | |
| 28 | | :--- | :--- | :--- | :--- | :--- | :--- | | 27 | | :--- | :--- | :--- | :--- | :--- | :--- | |
| 29 | -| **AutoRound** | 权重量化优化 | 基于 SignSGD 优化舍入偏移，降低重构误差 | 4bit 等超低比特量化 | [词条](autoround/term_autoround.md) | [使用指南](autoround/usage_autoround.md) | | 28 | +| **AutoRound** | 权重量化优化 | 基于 SignSGD 优化舍入偏移，降低重构误差 | 4bit 等超低比特量化 | [AutoRound 词条](autoround/term_autoround.md) | [AutoRound 使用指南](autoround/usage_autoround.md) | |
| 30 | -| **FA3 Quant** | 激活量化 | 针对 Attention 激活的 per-head INT8 量化 | 长序列、MLA 架构模型 | [词条](fa3_quant/term_fa3_quant.md) | [使用指南](fa3_quant/usage_fa3_quant.md) | | 29 | +| **FA3 Quant** | 激活量化 | 针对 Attention 激活的 per-head INT8 量化 | 长序列、MLA 架构模型 | [FA3 Quant 词条](fa3_quant/term_fa3_quant.md) | [FA3 Quant 使用指南](fa3_quant/usage_fa3_quant.md) | |
| 31 | -| **GPTQ** | 权重量化优化 | 通过逐列优化和误差补偿最小化量化误差 | 高精度权重量化需求 | [词条](gptq/term_gptq.md) | [使用指南](gptq/usage_gptq.md) | | 30 | +| **GPTQ** | 权重量化优化 | 通过逐列优化和误差补偿最小化量化误差 | 高精度权重量化需求 | [GPTQ 词条](gptq/term_gptq.md) | [GPTQ 使用指南](gptq/usage_gptq.md) | |
| 32 | -| **KVCache Quant** | KV Cache 量化 | 针对 KV Cache 的量化方案 | 提升长序列推理效率 | [词条](kvcache_quant/term_kvcache_quant.md) | [使用指南](kvcache_quant/usage_kvcache_quant.md) | | 31 | +| **KVCache Quant** | KV Cache 量化 | 针对 KV Cache 的量化方案 | 提升长序列推理效率 | [KVCache Quant 词条](kvcache_quant/term_kvcache_quant.md) | [KVCache Quant 使用指南](kvcache_quant/usage_kvcache_quant.md) | |
| 33 | -| **Linear Quant** | 基础量化 | 对线性层进行权重量化和激活量化 | 基础量化场景 | [词条](linear_quant/term_linear_quant.md) | [使用指南](linear_quant/usage_linear_quant.md) | | 32 | +| **Linear Quant** | 基础量化 | 对线性层进行权重量化和激活量化 | 基础量化场景 | [Linear Quant 词条](linear_quant/term_linear_quant.md) | [Linear Quant 使用指南](linear_quant/usage_linear_quant.md) | |
| 34 | -| **PDMIX** | 混合阶段量化 | Prefilling 使用动态量化，Decoding 使用静态量化 | 大模型推理加速，平衡精度与性能 | [词条](pdmix/term_pdmix.md) | [使用指南](pdmix/usage_pdmix.md) | | 33 | +| **PDMIX** | 混合阶段量化 | Prefilling 使用动态量化，Decoding 使用静态量化 | 大模型推理加速，平衡精度与性能 | [PDMIX 词条](pdmix/term_pdmix.md) | [PDMIX 使用指南](pdmix/usage_pdmix.md) | |
| 35 | -| **Histogram** | 激活量化 | 分析直方图分布，搜索最优截断区间 | 过滤离群值，提高精度 | [词条](histogram_activation_quantization/term_histogram_activation_quantization.md) | [使用指南](histogram_activation_quantization/usage_histogram_activation_quantization.md) | | 34 | +| **Histogram** | 激活量化 | 分析直方图分布，搜索最优截断区间 | 过滤离群值，提高精度 | [Histogram 词条](histogram_activation_quantization/term_histogram_activation_quantization.md) | [Histogram 使用指南](histogram_activation_quantization/usage_histogram_activation_quantization.md) | |
| 36 | -| **MinMax** | 基础量化 | 统计最大最小值确定量化范围 | 基础量化场景，计算开销低 | [词条](minmax/term_minmax.md) | [使用指南](minmax/usage_minmax.md) | | 35 | +| **MinMax** | 基础量化 | 统计最大最小值确定量化范围 | 基础量化场景，计算开销低 | [MinMax 词条](minmax/term_minmax.md) | [MinMax 使用指南](minmax/usage_minmax.md) | |
| 37 | -| **SSZ** | 权重量化 | 迭代搜索最优缩放因子和偏移量 | 权重分布不均的精度优化 | [词条](ssz/term_ssz.md) | [使用指南](ssz/usage_ssz.md) | | 36 | +| **SSZ** | 权重量化 | 迭代搜索最优缩放因子和偏移量 | 权重分布不均的精度优化 | [SSZ 词条](ssz/term_ssz.md) | [SSZ 使用指南](ssz/usage_ssz.md) | |
| 38 | -| **LAOS** | 低比特量化 | 针对 W4A4 等极低比特场景的优化 | 极致压缩需求 | [词条](laos/term_laos.md) | [使用指南](laos/usage_laos.md) | | 37 | +| **LAOS** | 低比特量化 | 针对 W4A4 等极低比特场景的优化 | 极致压缩需求 | [LAOS 词条](laos/term_laos.md) | [LAOS 使用指南](laos/usage_laos.md) | |
| 39 | -| **Float Sparse** | 稀疏化 | 基于 ADMM 算法实现模型浮点 sparse | 高压缩率需求 | [词条](float_sparse/term_float_sparse.md) | [使用指南](float_sparse/usage_float_sparse.md) | | 38 | +| **Float Sparse** | 稀疏化 | 基于 ADMM 算法实现模型浮点稀疏化 | 高压缩率需求 | [Float Sparse 词条](float_sparse/term_float_sparse.md) | [Float Sparse 使用指南](float_sparse/usage_float_sparse.md) | |
| 40 | -| **SVDQuant** | 综合方案 | 离群值迁移 + SVD 低秩残差 + 残差量化 | 扩散模型等低比特量化 | [词条](svdquant/term_svdquant.md) | [使用指南](svdquant/usage_svdquant.md) | | 39 | +| **SVDQuant** | 综合方案 | 离群值迁移 + SVD 低秩残差 + 残差量化 | 扩散模型等低比特量化 | [SVDQuant 词条](svdquant/term_svdquant.md) | [SVDQuant 使用指南](svdquant/usage_svdquant.md) | |
| 41 | -| **MSE_Round** | 权重量化 | 按 block 在 ceil/floor shared exponent 间按 MSE 择优 | MXFP8 权重量化精度优化 | [词条](mse_round/term_mse_round.md) | [使用指南](mse_round/usage_mse_round.md) | | 40 | +| **MSE_Round** | 权重量化 | 按 block 在 ceil/floor shared exponent 间按 MSE 择优 | MXFP8 权重量化精度优化 | [MSE_Round 词条](mse_round/term_mse_round.md) | [MSE_Round 使用指南](mse_round/usage_mse_round.md) | |
| 42 | -| **FouroverSix** | 权重量化 | 自适应选择块缩放（Scale-to-6 / Scale-to-4） | MXFP4 量化误差优化 | [词条](fouroversix/term_fouroversix.md) | [使用指南](fouroversix/usage_fouroversix.md) | | 41 | +| **FouroverSix** | 权重量化 | 自适应选择块缩放（Scale-to-6 / Scale-to-4） | MXFP4 量化误差优化 | [FouroverSix 词条](fouroversix/term_fouroversix.md) | [FouroverSix 使用指南](fouroversix/usage_fouroversix.md) | |
| 43 | -| **Ceil_X** | 权重量化 | ceil + 可配置除数计算 shared exponent | MXFP4 大值截断抑制 | [词条](ceil_x/term_ceil_x.md) | [使用指南](ceil_x/usage_ceil_x.md) | | 42 | +| **Ceil_X** | 权重量化 | ceil + 可配置除数计算 shared exponent | MXFP4 大值截断抑制 | [Ceil_X 词条](ceil_x/term_ceil_x.md) | [Ceil_X 使用指南](ceil_x/usage_ceil_x.md) | |
| 44 | -| **DualScale** | 权重量化 | 两级粒度递进缩放，缓解异常通道 | W4A4 等低比特场景 | [词条](dual_scale/term_dual_scale.md) | [使用指南](dual_scale/usage_dual_scale.md) | | 43 | +| **DualScale** | 权重量化 | 两级粒度递进缩放，缓解异常通道 | W4A4 等低比特场景 | [DualScale 词条](dual_scale/term_dual_scale.md) | [DualScale 使用指南](dual_scale/usage_dual_scale.md) | |
| 45 | 44 | ||
| 46 | -## 敏感层分析算法 | 45 | +## 3. 敏感层分析算法 |
| 47 | 46 | ||
| 48 | 敏感层分析通过`msmodelslim analyze`在校准数据上度量各层或子结构对量化的敏感程度，得到排序结果以辅助回退与 YAML 调参。 | 47 | 敏感层分析通过`msmodelslim analyze`在校准数据上度量各层或子结构对量化的敏感程度，得到排序结果以辅助回退与 YAML 调参。 |
| 49 | 48 | ||
| 50 | | 算法名称 | 分析范围 | 核心思想 | 适用场景 | 词条 | 使用指南 | | 49 | | 算法名称 | 分析范围 | 核心思想 | 适用场景 | 词条 | 使用指南 | |
| 51 | | :--- | :--- | :--- | :--- | :--- | :--- | | 50 | | :--- | :--- | :--- | :--- | :--- | :--- | |
| 52 | -| **Std** | linear（线性层） | 用激活动态范围与标准差的比值刻画敏感度 | 量化前线性层粗筛、默认策略之一 | [词条](std/term_std.md) | [使用指南](std/usage_std.md) | | 51 | +| **Std** | linear（线性层） | 用激活动态范围与标准差的比值刻画敏感度 | 量化前线性层粗筛、默认策略之一 | [Std 词条](std/term_std.md) | [Std 使用指南](std/usage_std.md) | |
| 53 | -| **Quantile** | linear（线性层） | 基于分位数与 IQR 构造 score，对离群点相对稳健 | 激活尾部重、希望降低离群主导 | [词条](quantile/term_quantile.md) | [使用指南](quantile/usage_quantile.md) | | 52 | +| **Quantile** | linear（线性层） | 基于分位数与 IQR 构造 score，对离群点相对稳健 | 激活尾部重、希望降低离群主导 | [Quantile 词条](quantile/term_quantile.md) | [Quantile 使用指南](quantile/usage_quantile.md) | |
| 54 | -| **Kurtosis** | linear（线性层） | 估计激活峰度，识别尖峰与极端值影响 | 关注尖峰分布、配合回退或混精 | [词条](kurtosis/term_kurtosis.md) | [使用指南](kurtosis/usage_kurtosis.md) | | 53 | +| **Kurtosis** | linear（线性层） | 估计激活峰度，识别尖峰与极端值影响 | 关注尖峰分布、配合回退或混精 | [Kurtosis 词条](kurtosis/term_kurtosis.md) | [Kurtosis 使用指南](kurtosis/usage_kurtosis.md) | |
| 55 | -| **Attention MSE（mse）** | attn（attention 结构） | 浮点与量化权重下 attention 输出的 MSE | Attention 权重量化敏感度（需适配器接口） | [词条](attention_mse/term_attention_mse.md) | [使用指南](attention_mse/usage_attention_mse.md) | | 54 | +| **Attention MSE（mse）** | attn（attention 结构） | 浮点与量化权重下 attention 输出的 MSE | Attention 权重量化敏感度（需适配器接口） | [Attention MSE 词条](attention_mse/term_attention_mse.md) | [Attention MSE 使用指南](attention_mse/usage_attention_mse.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) | | 55 | +| **层级 MSE（mse_layer_wise）** | layer（Decoder 块） | 块内选中子模块输出上 MSE 的块内均值 | 整层或整块（如 MLP / attention 段）回退 | [层级 MSE 词条](mse_layer_wise/term_mse_layer_wise.md) | [层级 MSE 使用指南](mse_layer_wise/usage_mse_layer_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) | | 56 | +| **模型级 MSE（mse_model_wise）** | layer（链式前向） | 逐层量化扰动对**模型最终输出**的 MSE | 从最终隐藏状态视角看层敏感度 | [模型级 MSE 词条](mse_model_wise/term_mse_model_wise.md) | [模型级 MSE 使用指南](mse_model_wise/usage_mse_model_wise.md) | |
| 57 | +| **RA Compress** | attn_head（注意力头） | 基于重复段结构度量归纳头/回声头的跨段注意力强度，筛选关键 KV head | 长序列 KV cache 压缩前筛选需保留的 KV head | [RA Compress 词条](ra_compress/term_ra_compress.md) | [RA Compress 使用指南](ra_compress/usage_ra_compress.md) | | ||
| 58 | 58 | ||
| 59 | -## 算法选择建议 | 59 | +## 4. 算法选择建议 |
| 60 | 60 | ||
| 61 | 初学者可优先使用《[一键量化 (V1)](../../user_guide/usage_quick_quantization.md)》，自动集成已验证的算法组合。需要自动搜索配置时，参见《[自动调优策略总览](../tuning_strategies/README.md)》。实践配置亦可参考 `lab_practice/` 下对应 YAML。 | 61 | 初学者可优先使用《[一键量化 (V1)](../../user_guide/usage_quick_quantization.md)》，自动集成已验证的算法组合。需要自动搜索配置时，参见《[自动调优策略总览](../tuning_strategies/README.md)》。实践配置亦可参考 `lab_practice/` 下对应 YAML。 |
| 62 | 62 | ||
| 63 | -### 量化算法 | 63 | +### 4.1 量化算法 |
| 64 | 64 | ||
| 65 | - **W8A8**：最常用 **MinMax**——统计最大最小值确定量化范围，计算开销低，适合作为默认起步方案。 | 65 | - **W8A8**：最常用 **MinMax**——统计最大最小值确定量化范围，计算开销低，适合作为默认起步方案。 |
| 66 | - **W4A8**：权重侧用 **SSZ** 迭代搜索缩放因子与偏移，激活 A8 仍用 **MinMax**，二者配合使用。 | 66 | - **W4A8**：权重侧用 **SSZ** 迭代搜索缩放因子与偏移，激活 A8 仍用 **MinMax**，二者配合使用。 |
| @@ -68,15 +68,16 @@ msModelSlim 支持多种先进的量化算法，涵盖了从离群值抑制到 | |||
| 68 | - **W4A4（INT / MXFP）**：可选用基于训练的 **AutoRound** 进一步抬精度，INT 与 MXFP 均支持；但对算力要求更高，量化耗时通常成倍高于其他大多数算法，选用时需权衡资源与时延。 | 68 | - **W4A4（INT / MXFP）**：可选用基于训练的 **AutoRound** 进一步抬精度，INT 与 MXFP 均支持；但对算力要求更高，量化耗时通常成倍高于其他大多数算法，选用时需权衡资源与时延。 |
| 69 | - **长序列 / C8**：产品上将 **KVCache Quant** 与 **FA3 Quant** 都纳入 C8。前者量化写入缓存的 Key/Value，专攻缩小 KV Cache、缓解推理显存压力；后者量化 Attention 路径上的 Q/K/V 激活以加速 attention 运算（仅支持 MLA）。二者机制不同，实践中一般只开其一，按显存或算力瓶颈选择。 | 69 | - **长序列 / C8**：产品上将 **KVCache Quant** 与 **FA3 Quant** 都纳入 C8。前者量化写入缓存的 Key/Value，专攻缩小 KV Cache、缓解推理显存压力；后者量化 Attention 路径上的 Q/K/V 激活以加速 attention 运算（仅支持 MLA）。二者机制不同，实践中一般只开其一，按显存或算力瓶颈选择。 |
| 70 | 70 | ||
| 71 | -### 离群值抑制算法 | 71 | +### 4.2 离群值抑制算法 |
| 72 | 72 | ||
| 73 | - 常用 **Flex Smooth Quant** 与 **QuaRot**：可独立使用，也可串联叠加。前者二阶段网格搜索 alpha / beta，适配面广；后者正交旋转平滑激活离群，精度收益往往更明显，但对模型适配要求更高。 | 73 | - 常用 **Flex Smooth Quant** 与 **QuaRot**：可独立使用，也可串联叠加。前者二阶段网格搜索 alpha / beta，适配面广；后者正交旋转平滑激活离群，精度收益往往更明显，但对模型适配要求更高。 |
| 74 | - **Flex AWQ SSZ** 在 4bit 低精场景下效果较好，但搜索相对较慢，适合精度优先、可接受更长量化时间的场景。 | 74 | - **Flex AWQ SSZ** 在 4bit 低精场景下效果较好，但搜索相对较慢，适合精度优先、可接受更长量化时间的场景。 |
| 75 | 75 | ||
| 76 | -### 敏感层分析 | 76 | +### 4.3 敏感层分析 |
| 77 | 77 | ||
| 78 | -当前敏感层分析支持按不同范围（`linear` / `layer` / `attn`）度量敏感度，并据此做对应粒度的回退或混精调参。使用指南：《[线性层](../../user_guide/usage_sensitive_linear_analysis.md)》、《[层级](../../user_guide/usage_sensitive_layer_wise_analysis.md)》、《[Attention](../../user_guide/usage_sensitive_attn_analysis.md)》。 | 78 | +当前敏感层分析支持按不同范围（`linear` / `layer` / `attn` / `attn_head`）度量敏感度，并据此做对应粒度的回退、混精调参或 KV cache 压缩配置。使用指南：《[线性层](../../user_guide/usage_sensitive_linear_analysis.md)》、《[层级](../../user_guide/usage_sensitive_layer_wise_analysis.md)》、《[Attention](../../user_guide/usage_sensitive_attn_analysis.md)》、《[Attention Head](../../user_guide/usage_sensitive_attn_head_analysis.md)》。 |
| 79 | 79 | ||
| 80 | - **linear**（线性层）：首选 **Kurtosis**，用激活峰度刻画尖峰与尾部影响，辅助识别需回退或提位宽的线性层。 | 80 | - **linear**（线性层）：首选 **Kurtosis**，用激活峰度刻画尖峰与尾部影响，辅助识别需回退或提位宽的线性层。 |
| 81 | - **layer**（Decoder 块）：首选 **mse_layer_wise**，适合整层 / 整块（如 MLP、attention 段）回退。 | 81 | - **layer**（Decoder 块）：首选 **mse_layer_wise**，适合整层 / 整块（如 MLP、attention 段）回退。 |
| 82 | - **attn**（Attention 结构）：首选 **Attention MSE（mse）**，主要用于配合 **FA3 Quant** 识别需回退的 Attention 模块（需适配器接口）。 | 82 | - **attn**（Attention 结构）：首选 **Attention MSE（mse）**，主要用于配合 **FA3 Quant** 识别需回退的 Attention 模块（需适配器接口）。 |
| 83 | +- **attn_head**（注意力头）：首选 **RA Compress**，基于重复段结构筛选归纳头 / 回声头，用于长序列 KV cache 压缩配置（仅支持 LLM，须使用 `calib_dummy.jsonl`）。 | ||
| @@ -1,16 +1,14 @@ | |||
| 1 | -# Adapt Rotation 自适应旋转优化算法词条 | 1 | +# Adapt Rotation 自适应旋转优化算法 量化术语百科词条 |
| 2 | 2 | ||
| 3 | -> **词条类别**：离群值抑制算法 | 3 | +> **词条类别**：[离群值抑制算法](../README.md#1-离群值抑制算法)<br> |
| 4 | -> **英文名称**：Adapt Rotation | 4 | +> **英文名称**：adapt_rotation<br> |
| 5 | -> **英文缩写**：AdaptRotation | 5 | +> **应用领域**：大语言模型量化压缩、低比特量化精度优化<br> |
| 6 | -> **应用领域**：大语言模型量化压缩、低比特量化精度优化 | ||
| 7 | -> **msModelSlim 实现**：`msmodelslim/processor/adapt_rotation/` | ||
| 8 | 6 | ||
| 9 | --- | 7 | --- |
| 10 | 8 | ||
| 11 | ## 1. 概述 | 9 | ## 1. 概述 |
| 12 | 10 | ||
| 13 | -Adapt Rotation（自适应旋转优化）是一种用于大语言模型量化的离群值抑制算法，属于 [QuaRot](../quarot/term_quarot.md) 的扩展。它以校准数据驱动的方式，在固定 Hadamard 矩阵的基础上通过迭代优化学习正交旋转矩阵，使变换后的激活值在量化时具有更小的重构误差，从而进一步抑制激活离群值、提升低比特量化精度。其核心特征是：正交变换保证计算等价、数据驱动优化、采用两阶段（Stage1 优化 / Stage2 应用）流程。 | 11 | +Adapt Rotation（自适应旋转优化）是一种面向低比特量化的离群值抑制算法，也是 [QuaRot](../quarot/term_quarot.md) 的数据驱动扩展。它利用校准数据优化正交旋转，使激活分布更均衡、量化重构误差更小；核心特征是保持线性变换等价、旋转参数可学习，并将旋转学习与应用分阶段完成。 |
| 14 | 12 | ||
| 15 | --- | 13 | --- |
| 16 | 14 | ||
| @@ -18,15 +16,21 @@ Adapt Rotation（自适应旋转优化）是一种用于大语言模型量化的 | |||
| 18 | 16 | ||
| 19 | [QuaRot](../quarot/term_quarot.md) 使用固定的 Hadamard 矩阵对权重与激活施加正交旋转以均衡各通道数值范围，但固定的 Hadamard 矩阵未必与特定模型的激活分布最匹配。Adapt Rotation 观察到，若旋转矩阵能针对校准数据迭代优化，则变换后的激活在量化-反量化后的重构误差更小。因此它在 QuaRot 基础上引入数据驱动的旋转优化，为解决固定旋转矩阵与目标模型激活分布不匹配的问题提供了更优选择。 | 17 | [QuaRot](../quarot/term_quarot.md) 使用固定的 Hadamard 矩阵对权重与激活施加正交旋转以均衡各通道数值范围，但固定的 Hadamard 矩阵未必与特定模型的激活分布最匹配。Adapt Rotation 观察到，若旋转矩阵能针对校准数据迭代优化，则变换后的激活在量化-反量化后的重构误差更小。因此它在 QuaRot 基础上引入数据驱动的旋转优化，为解决固定旋转矩阵与目标模型激活分布不匹配的问题提供了更优选择。 |
| 20 | 18 | ||
| 21 | ---- | 19 | +从量化流程中的定位看，该算法更接近量化前的分布整形步骤：先降低离群值对量化尺度的支配，再由后续量化算法完成真正的离散化。这种思路的价值在于不必简单扩大位宽，而是通过重分配、旋转或平滑数值幅度，提高有限量化区间对主体数据分布的利用率。 |
| 22 | 20 | ||
| 23 | -## 3. 原理 | 21 | +### 2.1 核心思想 |
| 24 | - | ||
| 25 | -### 1. 核心思想 | ||
| 26 | 22 | ||
| 27 | Adapt Rotation 的核心思想是“用数据驱动的方式优化正交旋转”：给定初始 Hadamard 矩阵 $H$ 与校准激活数据，通过迭代优化学习一个可优化的正交矩阵 $R$，使变换后的旋转矩阵 $H_{\text{adapted}} = H \cdot R$ 在给定激活数据上的量化-反量化重构误差最小。由于 $R$ 为正交矩阵，变换前后模型计算等价。 | 23 | Adapt Rotation 的核心思想是“用数据驱动的方式优化正交旋转”：给定初始 Hadamard 矩阵 $H$ 与校准激活数据，通过迭代优化学习一个可优化的正交矩阵 $R$，使变换后的旋转矩阵 $H_{\text{adapted}} = H \cdot R$ 在给定激活数据上的量化-反量化重构误差最小。由于 $R$ 为正交矩阵，变换前后模型计算等价。 |
| 28 | 24 | ||
| 29 | -### 2. 数学描述 | 25 | +其有效性来自“在不丢失向量能量的前提下改变坐标峰值”。 |
| 26 | + | ||
| 27 | +### 2.2 工作机制 | ||
| 28 | + | ||
| 29 | +固定 Hadamard 旋转能够平均地混合坐标，但它只利用矩阵结构，不知道真实模型激活在哪些方向上最难量化。Adapt Rotation 先用 Hadamard 作为稳定的初始正交基，再利用校准激活反复构造“当前旋转后的浮点激活”与“其量化-反量化结果”之间的对应关系。若记二者为 $A$ 和 $B$，算法希望找到一个正交更新，使 $A$ 在旋转后尽可能靠近 $B$。 | ||
| 30 | + | ||
| 31 | +在固定当前量化结果的条件下，这一步可写成正交 Procrustes 类问题，其解与 $A^TB$ 的极分解正交因子相关。算法通过迭代求取该正交因子并累积到已有旋转上，再重新计算量化结果，如此交替进行。整个过程中旋转始终保持正交，因此它改变的是坐标系中能量的分布方式，而不是向量的 $L_2$ 范数或线性变换可表达的信息。 | ||
| 32 | + | ||
| 33 | +### 2.3 数学描述 | ||
| 30 | 34 | ||
| 31 | 设初始 Hadamard 矩阵为 $H$，学习得到的正交旋转为 $R$，则变换后的旋转矩阵为： | 35 | 设初始 Hadamard 矩阵为 $H$，学习得到的正交旋转为 $R$，则变换后的旋转矩阵为： |
| 32 | 36 | ||
| @@ -42,115 +46,43 @@ $$ | |||
| 42 | - $A$、$B$：Newton-Schulz 迭代中用于求解正交极因子的矩阵 | 46 | - $A$、$B$：Newton-Schulz 迭代中用于求解正交极因子的矩阵 |
| 43 | - $R_{\text{acc}}$：累积旋转矩阵 | 47 | - $R_{\text{acc}}$：累积旋转矩阵 |
| 44 | 48 | ||
| 45 | -### 3. 关键性质 | 49 | +若把当前旋转后的浮点激活记为 $A=XQ$，对应的量化-反量化结果记为 $B=\mathcal{Q}(A)$，则固定 $B$ 后可考虑： |
| 50 | + | ||
| 51 | +$$ | ||
| 52 | +Q^{*}=\arg\min_{Q^TQ=I}\|XQ-B\|_F^2. | ||
| 53 | +$$ | ||
| 54 | + | ||
| 55 | +该问题等价于最大化 $\operatorname{tr}(Q^TX^TB)$。若 $X^TB=U\Sigma V^T$，经典正交 Procrustes 解为 $Q^*=UV^T$。实际迭代可以用极分解的正交因子来近似或更新这一解。重新得到 $Q$ 后还需要再次执行 $B=\mathcal{Q}(XQ)$，因为量化投影会随坐标系改变。 | ||
| 56 | + | ||
| 57 | +### 2.4 关键性质 | ||
| 46 | 58 | ||
| 47 | - **计算等价性**：正交旋转不改变矩阵乘法的数学结果，不引入额外推理误差。 | 59 | - **计算等价性**：正交旋转不改变矩阵乘法的数学结果，不引入额外推理误差。 |
| 48 | - **数据驱动优化**：旋转矩阵针对校准数据迭代优化，而非固定 Hadamard。 | 60 | - **数据驱动优化**：旋转矩阵针对校准数据迭代优化，而非固定 Hadamard。 |
| 49 | - **两阶段流程**：Stage1 优化旋转矩阵，Stage2 将优化结果应用到 QuaRot 流程。 | 61 | - **两阶段流程**：Stage1 优化旋转矩阵，Stage2 将优化结果应用到 QuaRot 流程。 |
| 50 | -- **适配器依赖**：依赖 `AdaptRotationInterface`（继承 `QuaRotInterface` 并实现 `get_hidden_dim()`）。 | 62 | +- **校准分布相关**：优化后的旋转针对所用校准激活与目标量化设置，数据或位宽变化时最优旋转可能变化。 |
| 51 | 63 | ||
| 52 | ---- | 64 | +从误差与适用边界看，主要误差风险是校准过拟合与量化目标错配：如果校准数据不能覆盖真实输入，学到的旋转可能只对局部样本有效；如果优化时使用的位宽/粒度与最终量化方案不同，最优方向也可能发生变化。 |
| 53 | 65 | ||
| 54 | -## 4. 流程示意 | 66 | +### 2.5 适用场景 |
| 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 | 67 | ||
| 134 | - 需要比固定 Hadamard 旋转更优的离群值抑制效果、低比特量化的场景。 | 68 | - 需要比固定 Hadamard 旋转更优的离群值抑制效果、低比特量化的场景。 |
| 135 | - 作为 [AutoRound](../autoround/term_autoround.md) 等低比特量化算法的前置离群值抑制步骤。 | 69 | - 作为 [AutoRound](../autoround/term_autoround.md) 等低比特量化算法的前置离群值抑制步骤。 |
| 136 | 70 | ||
| 137 | -### 2. 使用限制 | 71 | +更具体地说，这类算法适合“量化误差主要由少数大幅值通道或 token 拉高尺度”的情况。若问题来源并不是离群值，而是模型本身对低比特表示普遍敏感，则单独增加平滑或旋转强度通常收益有限，应结合更高精度量化或敏感层回退。 |
| 138 | 72 | ||
| 139 | -- 模型必须实现 `AdaptRotationInterface`（依赖 `QuaRotInterface` 并实现 `get_hidden_dim()`）。 | 73 | +### 2.6 使用限制 |
| 140 | -- Stage1 必须在 ContextManager 下运行，以便将 `adapted_matrix` 传递给 Stage2。 | 74 | + |
| 141 | -- Stage1 的 `quant_dtype` 应与下游量化（如 `linear_quant`/`autoround_quant`）的激活值类型一致（w4a4 用 `int4`，w8a8 用 `int8`）。 | 75 | +- 两阶段需要连续使用同一组学习得到的旋转矩阵：第一阶段负责优化，第二阶段负责将其应用到等价旋转变换。 |
| 142 | -- MoE 模型若 `layer_type` 匹配范围落入专家非共享线性层，激活收集与优化耗时会显著增加。 | 76 | +- 旋转矩阵的优化目标应与后续实际激活量化位宽一致；目标位宽改变后应重新优化旋转矩阵。 |
| 77 | +- 在 MoE 等包含大量非共享专家层的模型中，扩大旋转优化范围会显著增加激活统计与迭代优化开销。 | ||
| 78 | + | ||
| 79 | +这些限制反映了算法对模型结构和等价变换条件的依赖。若目标模型不满足相应结构假设，强行套用可能破坏原有计算关系；因此遇到不兼容结构时应优先缩小作用范围或使用模型已验证的配方，而不是盲目增大平滑强度。 | ||
| 143 | 80 | ||
| 144 | --- | 81 | --- |
| 145 | 82 | ||
| 146 | -## 7. 关联流程 | 83 | +## 3. 关联词条 |
| 147 | 84 | ||
| 148 | -- 《[一键量化 (V1)](../../../user_guide/usage_quick_quantization.md)》：可集成离群值抑制前置步骤。 | 85 | +可以从“同类方法、前后处理关系和应用对象”三个方向理解本词条与其他算法的关系。下面的关联项既用于横向比较不同技术路线，也用于帮助定位该算法在完整量化方案中的位置。 |
| 149 | -- 《[量化精度调优指南](../../../user_guide/process_quantization_precision_tuning.md)》：精度不达标时可考虑启用本算法。 | ||
| 150 | - | ||
| 151 | ---- | ||
| 152 | - | ||
| 153 | -## 8. 关联词条 | ||
| 154 | 86 | ||
| 155 | - [QuaRot](../quarot/term_quarot.md)：上位概念，本算法在 QuaRot 基础上优化旋转矩阵。 | 87 | - [QuaRot](../quarot/term_quarot.md)：上位概念，本算法在 QuaRot 基础上优化旋转矩阵。 |
| 156 | - [SmoothQuant](../smooth_quant/term_smooth_quant.md)：对比算法，采用通道级缩放而非正交旋转抑制离群值。 | 88 | - [SmoothQuant](../smooth_quant/term_smooth_quant.md)：对比算法，采用通道级缩放而非正交旋转抑制离群值。 |
| @@ -159,6 +91,8 @@ spec: | |||
| 159 | 91 | ||
| 160 | --- | 92 | --- |
| 161 | 93 | ||
| 162 | -## 9. 参考资料 | 94 | +## 4. 参考文档 |
| 163 | 95 | ||
| 164 | -1. 《Adapt Rotation 使用指南》([./usage_adapt_rotation.md](./usage_adapt_rotation.md)) | 96 | +参考文档优先列出算法原始论文或权威出处，并补充仓库内对应使用指南。需要进一步理解参数选择时，可先阅读使用指南，再回到原论文核对算法假设和推导。 |
| 97 | + | ||
| 98 | +1. 《[Adapt Rotation 参数配置流程指南](./usage_adapt_rotation.md)》 | ||
| @@ -1,76 +1,49 @@ | |||
| 1 | -# Adapt Rotation 使用指南 | 1 | +# Adapt Rotation 参数配置流程指南 |
| 2 | 2 | ||
| 3 | ## 1. 适用范围 | 3 | ## 1. 适用范围 |
| 4 | 4 | ||
| 5 | -本流程适用于在 msModelSlim 中使用 Adapt Rotation（自适应旋转优化）离群值抑制算法。Adapt Rotation 作为 `type: "adapt_rotation"` 处理器，在 [QuaRot](../quarot/term_quarot.md) 基础上通过数据驱动优化旋转矩阵，用于提升低比特（如 W4A4）量化精度。 | 5 | +Adapt Rotation（自适应旋转优化）离群值抑制算法。Adapt Rotation 作为 `type: "adapt_rotation"` 处理器，在 [QuaRot](../quarot/term_quarot.md) 基础上通过数据驱动优化旋转矩阵，用于提升低比特（如 W4A4）量化精度。 |
| 6 | 6 | ||
| 7 | -适用角色：算法工程师、模型部署工程师 | 7 | +本指南面向首次配置 Adapt Rotation 的用户，重点不是展开完整执行命令，而是说明推荐配置为什么适合作为起点、哪些参数真正需要调，以及出现精度或资源问题时应优先改哪一项。这类算法的主要作用是先改善待量化张量的数值分布，再交给后续量化步骤处理，本身通常不是最终的量化格式。因此判断配置是否合适时，不仅要看平滑或旋转后的张量范围，还要看与后续量化组合后的端到端精度；建议保持后续量化配置不变，只调整当前算法参数。 |
| 8 | 8 | ||
| 9 | -适用场景： | 9 | +如果目标模型已经有完整且已验证的量化配方，应优先复用该配方；若当前算法与目标模型结构、数值格式或部署后端不兼容，不应通过增大搜索强度或扩大作用范围来绕过支持约束。 |
| 10 | 10 | ||
| 11 | -- 需要对激活离群值做更精细抑制、进一步提升低比特量化精度的场景。 | 11 | +## 2. 输入和交付件 |
| 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 | 12 | ||
| 32 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | | 13 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | |
| 33 | | --- | --- | --- | --- | --- | | 14 | | --- | --- | --- | --- | --- | |
| 34 | -| 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被目标 Transformers 版本加载 | | 15 | +| 输入 | 目标模型与量化目标 | 待量化模型及部署/评测方案 | 明确目标数值格式或位宽、作用模块、精度/性能目标以及部署约束 | 能说明为什么选择本算法以及它在整体量化方案中的位置 | |
| 35 | -| 输入 | 校准数据集 | 工具默认或用户指定 | JSONL 格式，每条含文本 prompt | 可被工具加载并完成前向推理 | | 16 | +| 输入 | 配置约束与实践基线 | 本算法配置说明、目标模型已有 `lab_practice` 配方（如有） | 字段名、支持组合、作用范围和模型适配与当前版本一致 | 推荐起点能够追溯到当前配置定义或已验证实践 | |
| 36 | -| 交付件 | 优化后的旋转矩阵 | 上下文机制（Context） | Stage1 写入 `ctx["adapt_rotation"].state["adapted_matrix"]` | 可被 Stage2 读取并覆盖默认旋转 | | 17 | +| 输入 | 校准数据（算法需要时） | 任务 `dataset`、校准集或模型实践配方 | 数据应能代表真实输入分布；多阶段算法尽量保持各阶段数据分布一致 | 能被当前量化流程正常读取，并覆盖主要输入形态 | |
| 37 | -| 交付件 | 应用旋转后的模型 | 量化流程输出 | 完成层融合与旋转的模型 | 可继续执行下游量化 | | 18 | +| 交付件 | Adapt Rotation 参数配置方案 | 用户量化 YAML 或任务配置 | 参数取值合法、作用范围明确；关键参数说明选择依据 | 可作为后续量化流程的算法配置输入，并可复现本指南中的基线选择 | |
| 38 | 19 | ||
| 39 | -## 4. 流程总览 | 20 | +## 3. 流程总览 |
| 21 | + | ||
| 22 | +入门时建议先用一组稳定配置建立基线，再围绕影响最大的参数做单变量调整。下面的流程强调“先选参数、再看效果”，不展开量化命令本身。 | ||
| 40 | 23 | ||
| 41 | ```mermaid | 24 | ```mermaid |
| 42 | flowchart LR | 25 | flowchart LR |
| 43 | - A[准备模型与校准集] --> B[Stage1 收集激活并优化] | 26 | + A[确定目标位宽与校准集] --> B[Stage1 优化旋转矩阵] |
| 44 | - B --> C[写入 Context 传递旋转矩阵] | 27 | + B[Stage1 优化旋转矩阵] --> C[Stage2 应用旋转] |
| 45 | - C --> D[Stage2 应用优化旋转] | 28 | + C[Stage2 应用旋转] --> D[衔接低比特量化] |
| 46 | - D --> E[下游量化与保存] | 29 | + D[衔接低比特量化] --> E[对比精度] |
| 47 | ``` | 30 | ``` |
| 48 | 31 | ||
| 49 | -## 5. 操作步骤 | 32 | +实际使用时建议把流程理解为“建立基线—观察结果—单变量调整—再次验证”的闭环。流程图中的前几个节点用于固定量化对象、统计信息或初始参数，后几个节点用于应用算法并检查结果；如果效果不理想，应优先回到最近一次修改的参数，而不是同时更换位宽、粒度、作用范围和算法强度。这样可以明确每次变化的因果关系，也便于把有效配置沉淀为后续模型配方。 |
| 50 | 33 | ||
| 51 | -### 步骤 1：确认适配器实现分析接口 | 34 | +## 4. 操作步骤 |
| 52 | 35 | ||
| 53 | -**目标**：确认目标 `model_type` 的适配器支持 Adapt Rotation 两阶段流程。 | 36 | +### 步骤 1：确认目标与约束 |
| 37 | + | ||
| 38 | +**操作**：先固定目标模型、最终量化格式/位宽、作用对象和评测基线，再确认当前版本支持的参数组合。目标模型已有 `lab_practice` 配方时，优先把该配方作为实践基线；没有模型专用配方时，再使用本指南给出的通用推荐起点。若算法依赖校准统计或优化数据，还应在调参前固定代表性数据，避免把数据分布变化误判为参数收益。 | ||
| 39 | + | ||
| 40 | +**输出**：一份明确的配置目标：目标位宽/格式、处理范围、校准条件、评测基线和部署约束。 | ||
| 41 | + | ||
| 42 | +### 步骤 2：建立推荐基线 | ||
| 54 | 43 | ||
| 55 | **操作**： | 44 | **操作**： |
| 56 | 45 | ||
| 57 | -1. 确认适配器实现了 `AdaptRotationInterface`（继承 `QuaRotInterface` 并实现 `get_hidden_dim()`）。 | 46 | +下面配置用于建立**第一版可比较基线**。如果目标模型已有 `lab_practice` 配方，优先使用已验证配方，再参考本节理解每个参数为什么这样选。 |
| 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 | 47 | ||
| 75 | ```yaml | 48 | ```yaml |
| 76 | spec: | 49 | spec: |
| @@ -83,70 +56,74 @@ spec: | |||
| 83 | quant_dtype: "int4" | 56 | quant_dtype: "int4" |
| 84 | block_size: -1 | 57 | block_size: -1 |
| 85 | max_samples: 2048 | 58 | max_samples: 2048 |
| 86 | - dataset: boolq.jsonl | 59 | + dataset: "boolq.jsonl" |
| 87 | -``` | ||
| 88 | 60 | ||
| 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: | 61 | process: |
| 103 | - type: "adapt_rotation" | 62 | - type: "adapt_rotation" |
| 104 | stage: 2 | 63 | stage: 2 |
| 105 | - online: False | 64 | + online: false |
| 106 | block_size: -1 | 65 | block_size: -1 |
| 107 | max_tp_size: 1 | 66 | max_tp_size: 1 |
| 108 | ``` | 67 | ``` |
| 109 | 68 | ||
| 110 | -**输出**：完成层融合与旋转的模型。 | 69 | +上面的推荐值用于建立第一版可复现基线，其中最值得关注的配置包括 `stage`, `steps`, `quant_dtype`, `layer_type`。推荐值并不表示所有模型都只能使用该组合，而是优先选择仓库默认值、已验证实践或较稳健的中间取值，以降低第一次使用时同时遇到精度和兼容性问题的概率。如果目标模型已经有 `lab_practice` 配方，应优先复用该配方；只有在基线精度、显存或吞吐不满足目标时，再按照下一节的参数说明逐项调整。 |
| 111 | 70 | ||
| 112 | -### 步骤 4：执行下游量化并验收 | 71 | +**输出**：一份可复现的推荐基线配置，后续所有参数调整均以此为比较对象。 |
| 113 | 72 | ||
| 114 | -**目标**：完成量化、保存并验证精度。 | 73 | +### 步骤 3：选择并调整参数 |
| 115 | 74 | ||
| 116 | **操作**： | 75 | **操作**： |
| 117 | 76 | ||
| 118 | -1. 在 Stage2 之后接下游量化处理器（如 `autoround_quant`）。 | 77 | +ModelSlim 实现入口： |
| 119 | -2. 配置 `save` 阶段保存量化模型。 | 78 | +[查看对应实现目录](../../../../../msmodelslim/processor/adapt_rotation) |
| 120 | -3. 在验证集上评估量化精度，若不达标则调整 `layer_type`、`steps` 等参数后重跑。 | ||
| 121 | 79 | ||
| 122 | -**输出**：量化模型及精度验收结果。 | 80 | +参数选择建议按三个层次理解：首先确认 `dtype/scope/method` 等**算法支持约束**，这类字段不是任意可调；其次确定 `include/exclude`、子图类型等**作用范围**；最后再调整会改变误差与开销的数值参数。下面的推荐值区分了代码默认值、仓库 `lab_practice` 中已验证的实践值和适合首次使用的推荐起点。如果目标模型已有实践配置，优先沿用实践配置，再根据本节说明做单变量调整。 |
| 123 | 81 | ||
| 124 | -## 6. 验收条件 | 82 | +| 配置项 | 含义（原理） | 推荐配置 | 选择与调整建议 | |
| 83 | +| --- | --- | --- | --- | | ||
| 84 | +| `type` | 处理器类型标识，固定为 `adapt_rotation`。它只负责选择处理器，不参与旋转优化。 | 固定 `adapt_rotation`。 | 不要把 `type` 当作调参项；如果改成其他处理器，相当于切换算法，应重新选择整组配置。 | | ||
| 85 | +| `stage` | 决定当前是 Stage 1“基于校准数据学习/优化旋转”还是 Stage 2“把已学习旋转应用到模型”。Stage 1/2 允许的字段不同，配置会按阶段进行严格校验。 | 先执行 `stage: 1`，随后执行 `stage: 2`；两阶段使用同一套旋转目标。 | 两阶段不能省略或交换职责。最终量化目标、旋转块设置等发生变化后，应重新执行 Stage 1，而不是只改 Stage 2。 | | ||
| 86 | +| `steps` | Stage 1 的优化迭代次数。更多步数意味着旋转参数有更多机会降低模拟量化误差，但校准耗时近似随迭代增加；达到平台期后继续增加通常只增加时间。 | 默认值和 Qwen3 W4A4 实践均为 `20`，推荐先保持 `20`。 | 只有在相同校准集上看到旋转目标仍在明显下降、且最终量化精度仍受旋转不足影响时才增加。若 20 步后已经收敛或增加步数没有改善下游评测，保持默认即可。 | | ||
| 87 | +| `quant_dtype` | Stage 1 用来模拟下游激活量化误差的目标类型，当前支持 `int4`/`int8`。旋转优化会针对这个误差模型学习，因此它必须代表真正的下游 A 位宽。 | W4A4 用 `int4`，W8A8 用 `int8`；Qwen3 W4A4 实践依赖默认 `int4`。 | 这是“目标定义”而非微调旋钮。最终激活从 INT4 改成 INT8 时必须同步修改并重跑 Stage 1；否则学到的旋转针对的是另一套量化噪声。 | | ||
| 88 | +| `layer_type` | Stage 1 收集激活的层名子串列表，决定哪些投影层的数据参与自适应旋转优化。列表越宽，观测范围越大，但也更依赖模型命名和结构一致性。 | 默认/实践起点为 `["up_proj"]`。 | 先用模型适配中已验证的投影类型。只有确认其他投影同样属于该旋转路径、且当前采样不能代表最终误差时才扩展；如果填写的名称没有稳定匹配模块，先修正匹配而不是增加 `steps`。 | | ||
| 89 | +| `block_size` | 旋转块大小；`-1` 表示按 `hidden_dim` 做整块旋转，正值必须为 2 的幂。块化会把全维旋转限制在局部块内，通常用于并行、算子或内存约束。 | 精度基线优先 `-1`；只有明确的部署/并行要求时再使用合法的 2 的幂。 | 较小块会减少跨块混合能力，可能削弱离群值扩散效果，但更容易匹配部分并行/运行时约束。改块大小后应重新完成 Stage 1/Stage 2，并重新验证量化精度。 | | ||
| 90 | +| `max_samples` | Stage 1 每层用于优化的最大样本数，默认 `2048`。它控制估计旋转目标时的数据覆盖度，同时影响显存与校准时间。 | 先用 `2048`。 | 当不同校准批次得到的旋转收益波动较大，或业务分布明显更复杂时再增加；资源紧张时可降低，但样本过少会使优化更依赖少量校准样本。优先改善校准集代表性，再盲目堆样本数。 | | ||
| 91 | +| `dataset`（Stage 1 校准数据） | Stage 1 需要用校准样本收集目标投影的激活并优化旋转，因此数据分布会直接影响学到的旋转矩阵。它虽属于任务级数据配置而不是 `AdaptRotationProcessorConfig` 字段，但对该算法的参数选择具有决定性影响。 | 优先使用与最终量化校准、真实业务输入同分布的数据；示例 `boolq.jsonl` 只适合作为可运行起点。 | 如果模型主要处理长上下文、代码、多轮对话或其他特殊分布，应让校准集覆盖这些输入特征。更换数据集后应重新执行 Stage 1；不要把在一种分布上学到的旋转直接视为另一种分布的固定参数。 | | ||
| 92 | +| `online` | Stage 2 是否保留在线旋转。`false` 尽量把旋转离线融合到权重；`true` 则在运行时保留部分旋转逻辑。 | 默认 `false`，仓库实践也使用离线模式。 | 只有目标部署明确支持在线旋转、且确实需要在线/混合旋转时才开启。打开后应同时检查 `block_size`、`down_proj_online_layers`、`max_tp_size` 与实际并行配置。 | | ||
| 93 | +| `down_proj_online_layers` | Stage 2 指定哪些 Decoder 层的 `down_proj` 使用在线旋转，元素必须为非负层索引。它用于混合离线/在线策略。 | 默认 `[]`。 | 离线基线不需要设置。只有特定 `down_proj` 无法离线融合，或模型实践明确要求这些层在线旋转时再逐层加入；列表越大，运行时旋转开销越高。 | | ||
| 94 | +| `max_tp_size` | Stage 2 在线旋转使用的最大 Tensor Parallel 并行度，必须为 1 或 2 的幂。它参与在线旋转的分块/兼容约束。 | 离线模式保持默认即可；在线时设为**实际需要支持的最大 TP**。Qwen3 W4A4 实践使用 `1`。 | 不要为了“预留余量”随意放大。部署从 TP=1 改到更高 TP 时才同步修改，并确认旋转块与分片维度可兼容。 | | ||
| 125 | 95 | ||
| 126 | -- Stage1 能收集到非空激活并成功输出优化旋转矩阵。 | 96 | +### 参数组合与选择顺序 |
| 127 | -- Stage2 能读取 `adapted_matrix` 并完成层融合与旋转。 | ||
| 128 | -- 量化流程执行成功，精度满足业务要求。 | ||
| 129 | 97 | ||
| 130 | -## 7. 异常处置 | 98 | +1. **先锁定部署目标与支持组合**：先确定最终位宽/数值格式，再确认当前量化器实际注册了对应的 `dtype + scope + symmetric + method` 组合；不要为了追求某个参数值而越过支持约束。 |
| 99 | +2. **再固定作用范围**：使用已有模型配方时，先复用其 `include/exclude` 或子图类型；没有配方时先建立覆盖范围明确的基线，确认算法确实作用到了预期模块。 | ||
| 100 | +3. **最后只调一个主要旋钮**：数值搜索步数、平滑强度、分组大小等一次只改一项，并保持同一校准集和评测集。若调整后没有稳定收益，回到上一个基线，而不是继续叠加多个变化。 | ||
| 131 | 101 | ||
| 132 | -- **Stage1 未收集到激活**：`layer_type` 未匹配到模型中的 Linear 层，调整 `layer_type`（如 `up_proj`、`gate_proj`）。 | 102 | +对 Adapt Rotation 来说，`quant_dtype` 和 Stage1/Stage2 的一致性优先级高于 `steps`。第一次调参时先固定最终位宽和两阶段范围，再判断是否真的需要增加优化步数或改块大小。 |
| 133 | -- **Context 为空**：Stage1 未在 prior 阶段运行或未配置 `ContextManager`，确保两阶段在同一流程中顺序执行。 | ||
| 134 | -- **quant_dtype 与下游量化不一致**：将 Stage1 的 `quant_dtype` 设置为与下游 `qconfig.act.dtype` 一致。 | ||
| 135 | -- **MoE 模型执行缓慢**：缩小 `layer_type` 匹配范围，尽量只选择共享层而非专家非共享线性层。 | ||
| 136 | 103 | ||
| 137 | -## 8. 术语 | 104 | +**输出**：一份完成单变量调整的算法参数方案，关键字段均有明确的选择依据和调整方向。 |
| 105 | + | ||
| 106 | +### 步骤 4：根据结果收敛参数方案 | ||
| 107 | + | ||
| 108 | +**操作**： | ||
| 109 | + | ||
| 110 | +调参时建议先记录一份完整基线，包括使用的数据集、量化范围、关键参数和端到端指标。每轮只改变一个变量，并把变化结果与基线直接比较；如果某项调整带来收益，再继续小步搜索其邻近取值。对于只有少数层或模块异常的情况，优先采用局部排除、局部回退或混合精度，而不是直接提高全模型精度配置，这通常更容易保留压缩和性能收益。 | ||
| 111 | + | ||
| 112 | +- **先跑推荐基线，再调单变量。** 不要同时修改位宽、粒度、算法参数和层范围，否则很难判断精度变化来自哪一项。 | ||
| 113 | +- **优先回退局部，而不是整体提高精度。** 如果只有少数层敏感，优先通过 `exclude` 或混合策略保留高精度，通常比整体升位宽更划算。 | ||
| 114 | +- **最终以模型实践配置和部署能力为准。** 入门推荐用于建立稳定起点；目标模型已有 `lab_practice` 配方时，应优先复用已验证组合。 | ||
| 115 | + | ||
| 116 | +**输出**：一份可进入后续量化流程的最终参数方案，并保留相对于推荐基线的调整记录。 | ||
| 117 | + | ||
| 118 | +## 5. 术语 | ||
| 138 | 119 | ||
| 139 | | 术语 | 简述 | 链接 | | 120 | | 术语 | 简述 | 链接 | |
| 140 | | --- | --- | --- | | 121 | | --- | --- | --- | |
| 141 | -| Adapt Rotation | 数据驱动优化旋转矩阵的离群值抑制算法 | [Adapt Rotation 词条](./term_adapt_rotation.md) | | 122 | +| 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 | 123 | ||
| 146 | -## 9. 接口文档列表 | 124 | +## 6. 接口文档列表 |
| 147 | 125 | ||
| 148 | | 接口或能力 | 简述 | 链接 | | 126 | | 接口或能力 | 简述 | 链接 | |
| 149 | | --- | --- | --- | | 127 | | --- | --- | --- | |
| 150 | -| `type: "adapt_rotation"` stage 1 | 收集激活并优化旋转矩阵 | [Adapt Rotation 词条](./term_adapt_rotation.md) | | 128 | +| adapt_rotation 配置说明 | 字段类型、默认值、合法取值与完整配置约束。 | 《[adapt_rotation 配置说明](../../../api_reference/config/processor/adapt_rotation.md)》 | |
| 151 | -| `type: "adapt_rotation"` stage 2 | 应用优化后的旋转矩阵 | [Adapt Rotation 词条](./term_adapt_rotation.md) | | 129 | +| modelslim_v1 配置说明 | 需要继续探索 runner、prior、save、dataset 等任务级高级配置时查阅。 | 《[modelslim_v1 配置说明](../../../api_reference/config/task/modelslim_v1.md)》 | |
| 152 | -| `AdaptRotationInterface` | 模型适配器需实现的接口 | [Adapt Rotation 词条](./term_adapt_rotation.md) | | ||
| @@ -1,16 +1,14 @@ | |||
| 1 | -# Attention MSE 敏感层分析算法词条 | 1 | +# Attention MSE 敏感层分析算法 量化术语百科词条 |
| 2 | 2 | ||
| 3 | -> **词条类别**：敏感层分析算法 | 3 | +> **词条类别**：[敏感层分析算法](../README.md#3-敏感层分析算法)<br> |
| 4 | -> **英文名称**：Attention MSE | 4 | +> **英文名称**：attention_mse<br> |
| 5 | -> **英文缩写**：mse | 5 | +> **应用领域**：量化敏感层分析、Attention 权重量化<br> |
| 6 | -> **应用领域**：量化敏感层分析、Attention 权重量化 | ||
| 7 | -> **msModelSlim 实现**：`msmodelslim/processor/analysis/` | ||
| 8 | 6 | ||
| 9 | --- | 7 | --- |
| 10 | 8 | ||
| 11 | ## 1. 概述 | 9 | ## 1. 概述 |
| 12 | 10 | ||
| 13 | -Attention MSE（`mse`）是 `msmodelslim analyze` 中 `attn` 范围分析的一种度量算法。它分别使用浮点权重与量化权重执行前向推理，对同一 attention 模块的输出计算均方误差（MSE），输出注意力模块粒度的敏感度排序，与 [MSE Layer Wise](../mse_layer_wise/term_mse_layer_wise.md) 等同为基于 MSE 的敏感层分析指标。其核心特征是：直接度量注意力子系统在量化权重下的输出漂移、依赖适配器接口。 | 11 | +Attention MSE（`mse`）是一种注意力模块粒度的量化敏感度分析算法。它比较同一 Attention 模块在浮点权重与目标量化权重下的输出，并以均方误差衡量量化扰动，从而形成敏感度排序；核心特征是直接观察注意力子系统的实际输出误差，可与 [MSE Layer Wise](../mse_layer_wise/term_mse_layer_wise.md) 等层级指标互补。 |
| 14 | 12 | ||
| 15 | --- | 13 | --- |
| 16 | 14 | ||
| @@ -18,15 +16,21 @@ Attention MSE（`mse`）是 `msmodelslim analyze` 中 `attn` 范围分析的一 | |||
| 18 | 16 | ||
| 19 | 对 Attention 结构做权重量化或评估其敏感度时，需要直接度量注意力子系统在量化权重下的输出漂移。Attention MSE 通过分别用浮点与量化权重执行前向，在 attention 模块输出处对比两路张量，用 MSE 刻画该模块对权重量化的敏感程度。 | 17 | 对 Attention 结构做权重量化或评估其敏感度时，需要直接度量注意力子系统在量化权重下的输出漂移。Attention MSE 通过分别用浮点与量化权重执行前向，在 attention 模块输出处对比两路张量，用 MSE 刻画该模块对权重量化的敏感程度。 |
| 20 | 18 | ||
| 21 | ---- | 19 | +从量化流程中的定位看，该算法承担的是决策辅助，而不是直接改变模型权重或激活。它通过统计分布特征、比较量化前后差异或分析注意力行为等方式，构造可比较的层级、模块级或注意力头级指标，把“哪些位置更值得保护”转化为可排序或可筛选的结果，从而为局部回退、混合精度或压缩保留策略提供依据。 |
| 22 | 20 | ||
| 23 | -## 3. 原理 | 21 | +### 2.1 核心思想 |
| 24 | 22 | ||
| 25 | -### 1. 核心思想 | 23 | +Attention MSE 的核心思想是“直接度量输出漂移”：对同一校准样本，分别使用浮点权重与量化权重执行前向，在 attention 模块输出处采集张量，计算两路输出的均方误差；MSE 越大，表示该 attention 模块对当前量化方案越敏感。 |
| 26 | 24 | ||
| 27 | -Attention MSE 的核心思想是“直接度量输出漂移”：对同一校准样本，分别使用浮点权重与量化权重执行前向，在 attention 模块输出处采集张量，计算两路输出的均方误差；MSE 越大，表示该 attention 模块对当前量化配置越敏感。 | 25 | +该指标比单纯比较权重 MSE 更接近 attention 的实际功能，因为它把权重误差经过 Q/K/V 投影、点积和 softmax 后的综合影响压缩成一个输出层面的分数。 |
| 28 | 26 | ||
| 29 | -### 2. 数学描述 | 27 | +### 2.2 工作机制 |
| 28 | + | ||
| 29 | +分析时可以把目标 attention 模块视为一个受控干预对象：输入样本保持一致，只改变待评估量化配置所造成的权重/算子数值误差，然后分别得到浮点输出 $Y_{fp}$ 与量化输出 $Y_q$。两者的 MSE 就是这次量化扰动在 attention 子系统输出端留下的直接痕迹。 | ||
| 30 | + | ||
| 31 | +这一位置具有较强的综合性。Q/K 的误差会先影响点积 logits，随后经过 softmax 非线性重新分配注意力概率；V 或输出投影的误差则会影响加权求和结果。因此 attention 输出 MSE 不只反映某个权重张量自身的量化误差，还部分包含了注意力内部非线性对误差的放大或抑制。按相同数据与相同基线逐模块比较，就可以得到用于回退或提精度的相对敏感度排序。 | ||
| 32 | + | ||
| 33 | +### 2.3 数学描述 | ||
| 30 | 34 | ||
| 31 | 对同一层、同一样本的浮点与量化输出计算 MSE： | 35 | 对同一层、同一样本的浮点与量化输出计算 MSE： |
| 32 | 36 | ||
| @@ -39,81 +43,48 @@ $$ | |||
| 39 | - $n$：输出元素个数 | 43 | - $n$：输出元素个数 |
| 40 | - $\text{MSE}$：均方误差，用于敏感度排序 | 44 | - $\text{MSE}$：均方误差，用于敏感度排序 |
| 41 | 45 | ||
| 42 | -### 3. 关键性质 | 46 | +对小扰动做一阶展开，可把 Q/K 引起的 logit 误差写为： |
| 47 | + | ||
| 48 | +$$ | ||
| 49 | +\Delta L \approx \frac{\Delta QK^T+Q\Delta K^T}{\sqrt d}. | ||
| 50 | +$$ | ||
| 51 | + | ||
| 52 | +若 $P=\operatorname{softmax}(L)$，则某一行 softmax 的局部 Jacobian 为 $J_{\mathrm{sm}}=\operatorname{diag}(p)-pp^T$，从而： | ||
| 53 | + | ||
| 54 | +$$ | ||
| 55 | +\Delta O \approx J_{\mathrm{sm}}\Delta L\,V + P\Delta V. | ||
| 56 | +$$ | ||
| 57 | + | ||
| 58 | +这一近似说明 Attention MSE 同时受到量化误差大小和当前注意力分布形态影响：当多个位置 logits 接近时，概率重排可能更明显；当 softmax 已高度饱和时，部分方向的扰动又可能被压缩。 | ||
| 59 | + | ||
| 60 | +### 2.4 关键性质 | ||
| 43 | 61 | ||
| 44 | - **attn 范围分析**：输出注意力模块粒度的敏感度排序。 | 62 | - **attn 范围分析**：输出注意力模块粒度的敏感度排序。 |
| 45 | - **直接度量**：直接度量注意力子系统在量化权重下的输出漂移。 | 63 | - **直接度量**：直接度量注意力子系统在量化权重下的输出漂移。 |
| 46 | -- **适配器依赖**：需要模型适配器实现 `AttentionMSEAnalysisInterface`。 | 64 | +- **量化配置感知**：MSE 大小与当前量化方案相关。 |
| 47 | -- **量化配置感知**：MSE 大小与当前量化配置相关。 | 65 | +- **包含 attention 非线性传播**：Q/K 误差经过 logits 与 softmax 后的放大效应能够反映到最终输出 MSE 中。 |
| 48 | 66 | ||
| 49 | ---- | 67 | +局限也来自同一点：MSE 受输出幅值、序列长度、mask、输入语义以及当前量化基线影响，绝对数值没有跨模型通用阈值；它也只是数值代理，并不等价于最终任务质量。 |
| 50 | 68 | ||
| 51 | -## 4. 流程示意 | 69 | +### 2.5 适用场景 |
| 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 | 70 | ||
| 99 | - 需要对 Attention 结构做权重量化或评估其敏感度的场景。 | 71 | - 需要对 Attention 结构做权重量化或评估其敏感度的场景。 |
| 100 | - 需要注意力模块粒度敏感度排序以辅助回退决策的场景。 | 72 | - 需要注意力模块粒度敏感度排序以辅助回退决策的场景。 |
| 101 | 73 | ||
| 102 | -### 2. 使用限制 | 74 | +更具体地说，这类算法适合在需要把有限的高精度或保留预算分配给少数关键位置时使用。应先固定待分析模型、对象范围和指标；若指标依赖量化结果，再固定量化基线；若指标依赖数据，再固定校准数据。这样得到的排序才具有可比较性，后续才能可靠地指导局部保护策略。 |
| 103 | 75 | ||
| 104 | -- 对应 `model_type` 的模型适配器必须实现 `AttentionMSEAnalysisInterface`，提供模块类名与输出提取函数；未实现会在分析阶段报错。 | 76 | +### 2.6 使用限制 |
| 105 | -- 工具当前仅实现 DeepSeek 系列模型的接口适配，其他 `model_type` 会报错或需自行实现。 | 77 | + |
| 78 | +- 需要能够获得同一 Attention 模块在浮点权重与目标量化权重下的可比输出。 | ||
| 79 | +- MSE 数值依赖当前量化方案与校准数据，只适合在相同量化目标下比较模块之间的相对敏感度。 | ||
| 80 | + | ||
| 81 | +这些限制意味着分析结果具有明确的上下文依赖：模型结构或分析范围发生变化后，原有排序通常不应直接复用；对于数据依赖型或量化差异型指标，校准数据和量化基线变化同样会影响结果。正式固化局部保护策略前，建议在最终配置附近重新运行一次分析。 | ||
| 106 | 82 | ||
| 107 | --- | 83 | --- |
| 108 | 84 | ||
| 109 | -## 7. 关联流程 | 85 | +## 3. 关联词条 |
| 110 | 86 | ||
| 111 | -- 《[敏感层分析使用指南](../../../user_guide/usage_sensitive_layer_wise_analysis.md)》：本算法作为 `attn` 分析的 metrics 使用。 | 87 | +可以从“同类方法、前后处理关系和应用对象”三个方向理解本词条与其他算法的关系。下面的关联项既用于横向比较不同技术路线，也用于帮助定位该算法在完整量化方案中的位置。 |
| 112 | -- 《[一键量化 (V1)](../../../user_guide/usage_quick_quantization.md)》：分析结果可用于辅助量化配置调优。 | ||
| 113 | - | ||
| 114 | ---- | ||
| 115 | - | ||
| 116 | -## 8. 关联词条 | ||
| 117 | 88 | ||
| 118 | - [Std](../std/term_std.md)：对比算法，同为敏感层分析指标，但用于 `linear` 范围。 | 89 | - [Std](../std/term_std.md)：对比算法，同为敏感层分析指标，但用于 `linear` 范围。 |
| 119 | - [MSE Layer Wise](../mse_layer_wise/term_mse_layer_wise.md)：同类算法，同为基于 MSE 的敏感层分析指标，但用于 `layer` 范围。 | 90 | - [MSE Layer Wise](../mse_layer_wise/term_mse_layer_wise.md)：同类算法，同为基于 MSE 的敏感层分析指标，但用于 `layer` 范围。 |
| @@ -121,6 +92,8 @@ msmodelslim analyze attn \ | |||
| 121 | 92 | ||
| 122 | --- | 93 | --- |
| 123 | 94 | ||
| 124 | -## 9. 参考资料 | 95 | +## 4. 参考文档 |
| 125 | 96 | ||
| 126 | -1. 《Attention MSE 使用指南》([./usage_attention_mse.md](./usage_attention_mse.md)) | 97 | +参考文档优先列出算法原始论文或权威出处，并补充仓库内对应使用指南。需要进一步理解参数选择时，可先阅读使用指南，再回到原论文核对算法假设和推导。 |
| 98 | + | ||
| 99 | +1. 《[Attention MSE 分析配置流程指南](./usage_attention_mse.md)》 | ||
| @@ -1,125 +1,101 @@ | |||
| 1 | -# Attention MSE 使用指南 | 1 | +# Attention MSE 分析配置流程指南 |
| 2 | 2 | ||
| 3 | ## 1. 适用范围 | 3 | ## 1. 适用范围 |
| 4 | 4 | ||
| 5 | -本流程适用于在 msModelSlim 中使用 Attention MSE（`mse`）敏感层分析算法。Attention MSE 作为 `msmodelslim analyze attn` 的 metrics 指标，用于注意力模块粒度的敏感度排序。 | 5 | +Attention MSE（`mse`）敏感层分析算法。Attention MSE 作为 `msmodelslim analyze attn` 的 metrics 指标，用于注意力模块粒度的敏感度排序。 |
| 6 | 6 | ||
| 7 | -适用角色：算法工程师、模型部署工程师 | 7 | +本指南面向首次配置 Attention MSE 的用户，重点不是展开完整执行命令，而是说明推荐配置为什么适合作为起点、哪些参数真正需要调，以及出现精度或资源问题时应优先改哪一项。这类算法的输出主要用于指导哪些层、模块或注意力头需要重点保护，而不是直接生成量化权重。配置时应先固定待分析模型、分析范围和指标口径；如果指标依赖校准数据或量化结果，还应保持数据集和量化基线一致。排序或分数用于形成候选集合，最终策略仍应结合实际量化或压缩效果验证。 |
| 8 | 8 | ||
| 9 | -适用场景： | 9 | +如果目标是直接生成量化权重而不是筛选敏感对象，本指南不能替代正式量化流程；分析分数也不应被当作无需验证的硬回退阈值。 |
| 10 | 10 | ||
| 11 | -- 需要对 Attention 结构做权重量化或评估其敏感度的场景。 | 11 | +## 2. 输入和交付件 |
| 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 | 12 | ||
| 32 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | | 13 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | |
| 33 | | --- | --- | --- | --- | --- | | 14 | | --- | --- | --- | --- | --- | |
| 34 | -| 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被目标 Transformers 版本加载 | | 15 | +| 输入 | 待分析模型与量化基线 | 待分析模型、计划用于正式量化的配置 | 固定模型版本、目标量化范围和量化基线；分析范围应与后续实际量化对象一致 | 能明确本轮分析要比较的模型状态与候选范围 | |
| 35 | -| 输入 | 校准数据集 | 工具默认或用户指定 | JSONL 格式，每条含文本 prompt | 可被工具加载并完成前向推理 | | 16 | +| 输入 | 校准数据与分析参数约束 | 代表性校准数据、敏感层分析指南及相关配置 | 数据分布尽量覆盖真实输入；指标、`patterns`/范围和候选数量使用当前版本支持的取值 | 同一轮比较使用一致的数据、指标定义和分析范围 | |
| 36 | -| 交付件 | 敏感层分析结果 | 命令行输出 | attention 模块粒度的 score 排序结果 | 结果可读且包含目标层 | | 17 | +| 交付件 | Attention MSE 分析配置方案 | 敏感层分析命令/配置或评审记录 | 记录指标、分析范围、候选数量及选择依据；结果作为后续回退或混合精度的候选输入 | 能稳定复现同一分析条件，并说明候选如何用于后续量化决策 | |
| 37 | 18 | ||
| 38 | -## 4. 流程总览 | 19 | +## 3. 流程总览 |
| 20 | + | ||
| 21 | +入门时建议先用一组稳定配置建立基线，再围绕影响最大的参数做单变量调整。下面的流程强调“先选参数、再看效果”，不展开量化命令本身。 | ||
| 39 | 22 | ||
| 40 | ```mermaid | 23 | ```mermaid |
| 41 | flowchart LR | 24 | flowchart LR |
| 42 | - A[准备模型与校准集] --> B[执行 analyze 命令] | 25 | + A[确定 Attention 分析范围] --> B[固定 metrics=mse] |
| 43 | - B --> C[浮点/量化双路前向] | 26 | + B[固定 metrics=mse] --> C[完成浮点/量化双路前向] |
| 44 | - C --> D[输出 attn 敏感度排序] | 27 | + C[完成浮点/量化双路前向] --> D[计算 Attention 输出 MSE] |
| 28 | + D[计算 Attention 输出 MSE] --> E[按 score 选择回退候选] | ||
| 45 | ``` | 29 | ``` |
| 46 | 30 | ||
| 47 | -## 5. 操作步骤 | 31 | +实际使用时建议把流程理解为“固定分析条件—计算指标—形成排序或筛选结果—验证保护候选”的闭环。前半段最重要的是保持模型和分析范围一致；若指标依赖量化结果或校准数据，还需要同步固定量化基线和数据集。如果结果波动较大，应先检查分析对象与输入条件，再调整 `top_k`、筛选比例等展示或决策参数。不要在同一轮同时更换指标和它依赖的基线条件，否则很难判断排序变化来自哪里。 |
| 48 | 32 | ||
| 49 | -### 步骤 1：确认适配器实现分析接口 | 33 | +## 4. 操作步骤 |
| 50 | 34 | ||
| 51 | -**目标**：确认目标 `model_type` 的适配器支持 `attn` 范围分析。 | 35 | +### 步骤 1：确认目标与约束 |
| 36 | + | ||
| 37 | +**操作**：固定待分析模型、正式量化基线、校准数据和分析范围。先确认本次分析是为了筛选线性层、Decoder 层、Attention 结构或其他候选对象，并让分析范围与后续实际量化范围一致。如果模型、校准数据、量化基线或候选范围同时变化，分数排序将难以归因，因此这些条件应先固定，再调整指标或候选数量。 | ||
| 38 | + | ||
| 39 | +**输出**：一份固定的分析上下文：模型版本、量化基线、校准数据、分析范围以及要解决的回退/混合精度问题。 | ||
| 40 | + | ||
| 41 | +### 步骤 2：建立推荐基线 | ||
| 52 | 42 | ||
| 53 | **操作**： | 43 | **操作**： |
| 54 | 44 | ||
| 55 | -1. 确认适配器实现了 `AttentionMSEAnalysisInterface`。 | 45 | +- 分析范围：`attn`； |
| 56 | -2. 确认 `get_attention_module_cls()` 返回待挂 hook 的 attention 模块类名字符串。 | 46 | +- `--metrics`：`mse`； |
| 57 | -3. 确认 `get_attention_output_extractor()` 能从 `forward` 返回值中取出用于计算 MSE 的张量。 | 47 | +- `--top_k`：先用 `15`； |
| 58 | 48 | ||
| 59 | -各方法的具体约定，请参阅《[Attention MSE 词条](./term_attention_mse.md)》。 | 49 | +上面的推荐值用于建立第一版可复现分析基线，其中最值得关注的配置包括 `attn`, `--metrics`, `--top_k`。这些值优先选择较容易解释、结果规模适中且不会改变指标定义的起点，目的是先得到稳定排序，再决定是否扩大候选范围。对于新模型，建议先保持模型、分析范围和指标固定完成一次完整分析；若指标依赖量化结果或数据，再同步固定量化基线和校准集。只有当候选过多、过少或排序不稳定时，再按照下一节说明调整候选数量、分析范围或相关输入条件。 |
| 60 | 50 | ||
| 61 | -**输出**：适配器接口确认。 | 51 | +**输出**：一组可复现的敏感性分析基线参数，用于生成第一版候选排序。 |
| 62 | 52 | ||
| 63 | -### 步骤 2：执行敏感层分析命令 | 53 | +### 步骤 3：选择并调整参数 |
| 64 | - | ||
| 65 | -**目标**：使用 `mse` 指标完成 attention 模块敏感度分析。 | ||
| 66 | 54 | ||
| 67 | **操作**： | 55 | **操作**： |
| 68 | 56 | ||
| 69 | -```bash | 57 | +ModelSlim 实现入口： |
| 70 | -msmodelslim analyze attn \ | 58 | +[查看对应实现目录](../../../../../msmodelslim/processor/analysis/binary_operator/metrics/attention_mse) |
| 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 | 59 | ||
| 79 | -参数说明： | 60 | +本节只解释会影响分析对象、统计结果或候选输出的参数。对敏感性分析而言，最重要的不是把 `top_k` 调到某个固定值，而是保证**分析范围、校准数据和后续实际量化范围一致**：否则得到的排序即使数值稳定，也可能无法指导最终配置。推荐值用于建立第一版可比较基线；修改参数时应保持模型版本、校准集和量化基线固定，以便判断排序变化来自哪个参数。 |
| 80 | 61 | ||
| 81 | -| 参数 | 说明 | | 62 | +| 配置项 | 含义（原理） | 推荐配置 | 什么时候调整 | |
| 82 | -| --- | --- | | 63 | +| --- | --- | --- | --- | |
| 83 | -| `attn` | 注意力结构敏感度分析 | | 64 | +| 分析范围 `attn` | 按 Attention 模块比较浮点路径与量化路径的 Attention 输出，score 为对应输出的 MSE 均值。 | 固定 `attn`。 | 当前 Attention MSE 就使用 `attn`；如果目标是 Decoder block 或单个 Linear 的敏感度，应改用对应分析算法，而不是改变本指标的解释。 | |
| 84 | -| `--metrics` | 指定分析算法，取值为 `mse` 时使用本算法 | | 65 | +| `--metrics` | 选择本指南对应的分析指标 `mse`；指标决定 score 的定义和排序含义。 | 固定 `mse`。 | 保持 `mse`。它衡量的是实际量化干预后的输出差异，分数越大表示当前量化基线下该 Attention 模块的输出更容易被扰动。换成其他指标后不应继续沿用 MSE 的排序解释。 | |
| 85 | -| `--topk` | 输出的 topk 敏感层数量 | | 66 | +| `--calibration_dataset` / `--calib_dataset` | 用于前向收集激活或浮点/量化输出的校准数据，**JSON/JSONL 格式**（LLM 文本样本文件，如 `mix_calib.jsonl`；VLM 为多模态目录）。数据分布直接决定统计量、MSE 或 Head 分数，因此它是影响分析有效性的核心输入，而不是普通文件路径。 | 优先使用**与后续正式量化相同或同分布**的校准集；快速验证才使用内置示例。 | 如果排序在不同数据上明显变化，先判断校准集是否覆盖真实长度、主题和输入形态，再考虑扩大 `top_k`。正式回退决策应尽量在代表性数据上完成。 | |
| 67 | +| `--top_k` / `--topk` | 控制最终展示/导出的高分候选数量，默认 `15`。它不改变底层 score 计算，也不会让算法重新分析更多数据。 | 从 `15` 开始。 | 候选只是后续验证集合：需要更多回退候选时增大，需要快速人工审查时减小。不要把 `top_k` 当作敏感度阈值；不同模型、不同指标的绝对 score 尺度并不统一。 | | ||
| 86 | 68 | ||
| 87 | -完整参数见《[敏感层分析工具使用指南参数说明](../../../user_guide/usage_sensitive_layer_wise_analysis.md#命令行预览)》。 | 69 | +### 参数组合与结果解释 |
| 88 | 70 | ||
| 89 | -**输出**：attention 模块粒度的敏感度排序结果。 | 71 | +- **先固定校准集和量化基线，再比较排序**。如果同时换了数据、量化配置和分析范围，score 的变化无法归因。 |
| 72 | +- **高分表示“按 `mse` 定义更值得关注”，不等价于一定要回退**。应把 Top-K 当作候选集，再用实际量化精度或模型任务指标验证。 | ||
| 73 | +- **`top_k` 只改变输出规模**。真正影响“谁排在前面”的通常是校准数据、候选范围以及本指标自身的统计定义。 | ||
| 90 | 74 | ||
| 91 | -### 步骤 3：解读结果并指导调参 | 75 | +Attention MSE 依赖“当前量化配置”。如果 FA3/KV/线性量化位宽或粒度改变，应重新分析；旧排序只能说明旧量化基线下的敏感性。 |
| 92 | 76 | ||
| 93 | -**目标**：根据敏感度排序结果辅助回退与 YAML 调参。 | 77 | +**输出**：一份参数含义和调整方向明确的分析配置；修改项能够与排序变化建立对应关系。 |
| 78 | + | ||
| 79 | +### 步骤 4：解释结果并收敛候选方案 | ||
| 94 | 80 | ||
| 95 | **操作**： | 81 | **操作**： |
| 96 | 82 | ||
| 97 | -1. 查看排序结果，识别 MSE 较高的 attention 模块。 | 83 | +使用分析结果时建议保留一份完整基线，包括模型版本、分析范围、指标类型和候选数量；若指标依赖数据或量化结果，还应记录对应校准集与量化基线。每轮只改变一个分析条件，并观察高敏感或高优先级对象是否仍然稳定出现在结果前部；如果结果稳定，再把候选用于局部回退、提位宽或重点保留实验。只有实际量化或压缩效果确实改善时，才把候选固化到最终策略中，避免把一次分析分数直接当成硬阈值。 |
| 98 | -2. 结合业务精度要求确定回退阈值。 | ||
| 99 | -3. 在量化 YAML 中对敏感 attention 层配置回退或降低量化强度。 | ||
| 100 | 84 | ||
| 101 | -**输出**：回退与调参方案。 | 85 | +- Score 较高的对象优先进入“回退/提位宽候选池”，但最终是否回退仍应结合端到端精度验证。 |
| 86 | +- `top_k` 只是候选展示数量，不是精度阈值；不要把第15名等位置机械当成回退边界。 | ||
| 87 | +- 分析范围（`patterns`/`quant_modules`）应尽量与实际量化范围一致，否则得到的排序无法准确指导最终 YAML。 | ||
| 102 | 88 | ||
| 103 | -## 6. 验收条件 | 89 | +**输出**：一份经过实际量化或任务指标验证的敏感对象候选，以及对应的局部回退、提位宽或保护建议。 |
| 104 | 90 | ||
| 105 | -- 分析命令执行成功并输出目标层的敏感度排序。 | 91 | +## 5. 术语 |
| 106 | -- 分析结果可用于指导量化配置调整。 | ||
| 107 | - | ||
| 108 | -## 7. 异常处置 | ||
| 109 | - | ||
| 110 | -- **报错提示未实现 `AttentionMSEAnalysisInterface`**：当前 `model_type` 的适配器未接入该分析路径，请换用支持列表中的模型类型（如 DeepSeek 系列），或在适配器中按接口实现 hook 类名与输出提取逻辑。 | ||
| 111 | - | ||
| 112 | -## 8. 术语 | ||
| 113 | 92 | ||
| 114 | | 术语 | 简述 | 链接 | | 93 | | 术语 | 简述 | 链接 | |
| 115 | | --- | --- | --- | | 94 | | --- | --- | --- | |
| 116 | -| Attention MSE | 基于浮点/量化双路输出的 MSE 分析算法 | [Attention MSE 词条](./term_attention_mse.md) | | 95 | +| Attention 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 | 96 | ||
| 120 | -## 9. 接口文档列表 | 97 | +## 6. 接口文档列表 |
| 121 | 98 | ||
| 122 | | 接口或能力 | 简述 | 链接 | | 99 | | 接口或能力 | 简述 | 链接 | |
| 123 | | --- | --- | --- | | 100 | | --- | --- | --- | |
| 124 | -| `msmodelslim analyze attn` | 注意力结构敏感度分析命令，`--metrics mse` 启用本算法 | [Attention MSE 词条](./term_attention_mse.md) | | 101 | +| 敏感层分析使用指南 | 完整 CLI、输入输出和进阶流程。 | 《[敏感层分析使用指南](../../../user_guide/usage_sensitive_attn_analysis.md)》 | |
| 125 | -| `AttentionMSEAnalysisInterface` | 模型适配器需实现的接口 | [Attention MSE 词条](./term_attention_mse.md) | | ||
| @@ -1,16 +1,14 @@ | |||
| 1 | -# AutoRound 低比特量化算法词条 | 1 | +# AutoRound 低比特量化算法 量化术语百科词条 |
| 2 | 2 | ||
| 3 | -> **词条类别**：量化算法 | 3 | +> **词条类别**：[量化算法](../README.md#2-量化算法)<br> |
| 4 | -> **英文名称**：AutoRound | 4 | +> **英文名称**：autoround<br> |
| 5 | -> **首次提出**：Intel, 2023 | 5 | +> **应用领域**：大语言模型量化压缩、低比特量化精度优化<br> |
| 6 | -> **应用领域**：大语言模型量化压缩、低比特量化精度优化 | ||
| 7 | -> **msModelSlim 实现**：`msmodelslim/processor/quant/autoround.py` | ||
| 8 | 6 | ||
| 9 | --- | 7 | --- |
| 10 | 8 | ||
| 11 | ## 1. 概述 | 9 | ## 1. 概述 |
| 12 | 10 | ||
| 13 | -AutoRound 是一种基于 SignSGD 的大语言模型低比特权重量化算法。它通过引入可学习的舍入偏移参数，结合 SignSGD 优化器自适应调整各权重的舍入方向，并利用温度调度策略逐步硬化舍入操作，有效降低量化重构误差。其核心特征是：可学习舍入、逐层迭代优化、支持 W4A4 等超低比特量化，常与 [QuaRot](../quarot/term_quarot.md) 等离群值抑制算法配合使用。 | 11 | +AutoRound 是一种面向大语言模型低比特权重量化的优化算法。它为权重引入可学习的舍入偏移，并通过迭代优化选择更有利的舍入方向，以降低量化后的局部重构误差；核心特征是可学习舍入、逐层优化和对 INT4 等低比特权重的精度增强，可与 [QuaRot](../quarot/term_quarot.md) 等离群值抑制方法组合使用。 |
| 14 | 12 | ||
| 15 | --- | 13 | --- |
| 16 | 14 | ||
| @@ -18,15 +16,21 @@ AutoRound 是一种基于 SignSGD 的大语言模型低比特权重量化算法 | |||
| 18 | 16 | ||
| 19 | 传统量化方法（如四舍五入）在权重量化中并非最优选择，往往会引入较大的量化误差，尤其在低比特（如 4bit 及以下）量化场景中表现更为明显。AutoRound 观察到，通过引入可学习的舍入偏移并结合优化器，可以自适应地为每个权重选择最优的舍入方向，从而显著降低量化重构误差。 | 17 | 传统量化方法（如四舍五入）在权重量化中并非最优选择，往往会引入较大的量化误差，尤其在低比特（如 4bit 及以下）量化场景中表现更为明显。AutoRound 观察到，通过引入可学习的舍入偏移并结合优化器，可以自适应地为每个权重选择最优的舍入方向，从而显著降低量化重构误差。 |
| 20 | 18 | ||
| 21 | ---- | 19 | +从量化流程中的定位看，该算法解决的是“如何把连续浮点值映射到受限数值集合，同时尽量保留模型输出”的问题。与只按极值直接计算尺度的基础方法相比，它通常会利用更细的统计信息、优化目标或结构约束来控制误差，因此更适合对精度有明确要求的量化场景。 |
| 22 | 20 | ||
| 23 | -## 3. 原理 | 21 | +### 2.1 核心思想 |
| 24 | - | ||
| 25 | -### 1. 核心思想 | ||
| 26 | 22 | ||
| 27 | AutoRound 的核心思想是“把舍入方向变成可学习参数”：不采用简单的四舍五入，而是基于 SignSGD（符号梯度下降）算法，为每个权重学习一个舍入偏移 $V$，自适应决定权重向上或向下舍入，并有针对性地调整缩放因子和零点，从而最小化量化重构误差。 | 23 | AutoRound 的核心思想是“把舍入方向变成可学习参数”：不采用简单的四舍五入，而是基于 SignSGD（符号梯度下降）算法，为每个权重学习一个舍入偏移 $V$，自适应决定权重向上或向下舍入，并有针对性地调整缩放因子和零点，从而最小化量化重构误差。 |
| 28 | 24 | ||
| 29 | -### 2. 数学描述 | 25 | +AutoRound 有效的关键在于“低比特误差是相关的，而不是每个权重独立的”。 |
| 26 | + | ||
| 27 | +### 2.2 工作机制 | ||
| 28 | + | ||
| 29 | +传统 nearest rounding 对每个标量独立选择最近整数码，它只保证当前标量的误差局部最小，并不保证一整层的输出重构误差最小。AutoRound 在量化阈值附近为权重引入可学习的舍入偏移，使权重可以跨过原本的舍入边界；与此同时，还可以联合调整裁剪/尺度相关参数，在“扩大可表示范围”和“减小量化步长”之间寻找更合适的平衡。 | ||
| 30 | + | ||
| 31 | +优化时以校准输入下的浮点层输出为教师信号，量化权重产生学生输出，损失由两者的重构差异构成。SignSGD 只使用梯度符号更新高维舍入变量，避免过度依赖梯度幅值，并使大量离散边界附近的变量能够稳定地向降低输出误差的方向移动。优化结束后，学习变量被折叠为最终整数码与量化参数，不需要在推理时继续迭代。 | ||
| 32 | + | ||
| 33 | +### 2.3 数学描述 | ||
| 30 | 34 | ||
| 31 | 传统量化中权重 $W$ 的量化公式为： | 35 | 传统量化中权重 $W$ 的量化公式为： |
| 32 | 36 | ||
| @@ -55,100 +59,51 @@ $$ | |||
| 55 | 59 | ||
| 56 | 优化过程为逐层迭代：采集浮点前向输出作为基准，初始化并训练缩放因子与舍入偏移，量化-反量化前向得到量化结果，计算重构损失，通过 SignSGD 更新参数，重复直至收敛或达到最大迭代次数。 | 60 | 优化过程为逐层迭代：采集浮点前向输出作为基准，初始化并训练缩放因子与舍入偏移，量化-反量化前向得到量化结果，计算重构损失，通过 SignSGD 更新参数，重复直至收敛或达到最大迭代次数。 |
| 57 | 61 | ||
| 58 | -### 3. 关键性质 | 62 | +若把归一化权重写为 $u=W/s+z$，传统最近舍入取 $q=\operatorname{round}(u)$。学习式舍入可以抽象为： |
| 63 | + | ||
| 64 | +$$ | ||
| 65 | +q(V)=\operatorname{clip}\big(\lfloor u\rfloor+h(V),q_{\min},q_{\max}\big),\qquad h(V)\in\{0,1\}, | ||
| 66 | +$$ | ||
| 67 | + | ||
| 68 | +其中训练阶段用可优化的连续形式近似二值函数 $h$，结束后再固化为 0/1 决策。若校准输入为 $X$，常见层重构目标可写为： | ||
| 69 | + | ||
| 70 | +$$ | ||
| 71 | +\mathcal L=\|XW^T-X\hat W(V,s,z)^T\|_F^2. | ||
| 72 | +$$ | ||
| 73 | + | ||
| 74 | +这比单纯最小化 $\|W-\hat W\|_F^2$ 多考虑了输入方向的重要性：某些权重误差如果对应激活长期很小，对输出影响也较弱。 | ||
| 75 | + | ||
| 76 | +### 2.4 关键性质 | ||
| 59 | 77 | ||
| 60 | - **可学习舍入**：舍入方向由可学习偏移 $V$ 决定，而非固定四舍五入。 | 78 | - **可学习舍入**：舍入方向由可学习偏移 $V$ 决定，而非固定四舍五入。 |
| 61 | - **逐层优化**：对每个 decoder 层独立优化，避免误差跨层累积。 | 79 | - **逐层优化**：对每个 decoder 层独立优化，避免误差跨层累积。 |
| 62 | - **超低比特支持**：面向 4bit 及以下的超低比特量化场景。 | 80 | - **超低比特支持**：面向 4bit 及以下的超低比特量化场景。 |
| 63 | -- **混合量化**：支持对不同层使用不同量化配置（如 W8A8 与 W4A4 混合）。 | 81 | +- **可与混合精度结合**：对仍然敏感的层可保留更高位宽，而其余层使用更低位宽。 |
| 82 | +- **推理无优化开销**：训练式搜索只用于确定最终整数码与量化参数，部署时不需要继续更新舍入变量。 | ||
| 64 | 83 | ||
| 65 | ---- | 84 | +从误差与适用边界看，低比特越低，整数码越少，舍入阈值和裁剪边界越敏感，优化收益通常越明显，但同时更容易过拟合少量校准样本。迭代不足可能尚未找到稳定整数分配，迭代过多或学习设置不合适则可能只改善局部重构而不改善下游任务。 |
| 66 | 85 | ||
| 67 | -## 4. 流程示意 | 86 | +### 2.5 适用场景 |
| 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 | 87 | ||
| 132 | - 4bit 等超低比特权重量化场景。 | 88 | - 4bit 等超低比特权重量化场景。 |
| 133 | - 低比特条件下仍需要保持较高模型精度的场景。 | 89 | - 低比特条件下仍需要保持较高模型精度的场景。 |
| 134 | 90 | ||
| 135 | -### 2. 使用限制 | 91 | +更具体地说，是否适用主要取决于目标位宽、模型结构和部署后端三点。若目标部署链已经明确支持该算法对应的量化格式，并且校准数据能够覆盖主要业务分布，通常可以优先从该算法的推荐配置建立基线，再根据精度结果决定是否增加更复杂的优化。 |
| 92 | + | ||
| 93 | +### 2.6 使用限制 | ||
| 136 | 94 | ||
| 137 | - 仅适用于 LLM 中的线性层量化。 | 95 | - 仅适用于 LLM 中的线性层量化。 |
| 138 | - 需要足够的校准数据或训练迭代次数来优化参数。 | 96 | - 需要足够的校准数据或训练迭代次数来优化参数。 |
| 139 | - 包含训练过程，对 NPU 显存有一定要求，仅支持 NPU 显存 ≥64G 的设备。 | 97 | - 包含训练过程，对 NPU 显存有一定要求，仅支持 NPU 显存 ≥64G 的设备。 |
| 140 | - 低比特量化极度依赖良好的离群值抑制算法，建议配合 [QuaRot](../quarot/term_quarot.md) 或 [Iterative Smooth](../iterative_smooth/term_iterative_smooth.md) 使用，不建议单独使用。 | 98 | - 低比特量化极度依赖良好的离群值抑制算法，建议配合 [QuaRot](../quarot/term_quarot.md) 或 [Iterative Smooth](../iterative_smooth/term_iterative_smooth.md) 使用，不建议单独使用。 |
| 141 | 99 | ||
| 142 | ---- | 100 | +这些限制应在调参前确认，而不是等精度异常后再排查。尤其是数据类型、张量维度、分组大小和后端算子支持等硬约束，一旦不满足，继续调整算法参数通常无法解决问题；应先回到受支持的配置组合。 |
| 143 | - | ||
| 144 | -## 7. 关联流程 | ||
| 145 | - | ||
| 146 | -- 《[一键量化 (V1)](../../../user_guide/usage_quick_quantization.md)》：可集成 AutoRound 作为低比特权重量化步骤。 | ||
| 147 | -- 《[量化精度调优指南](../../../user_guide/process_quantization_precision_tuning.md)》：精度不达标时可调整 AutoRound 迭代次数与量化配置。 | ||
| 148 | 101 | ||
| 149 | --- | 102 | --- |
| 150 | 103 | ||
| 151 | -## 8. 关联词条 | 104 | +## 3. 关联词条 |
| 105 | + | ||
| 106 | +可以从“同类方法、前后处理关系和应用对象”三个方向理解本词条与其他算法的关系。下面的关联项既用于横向比较不同技术路线，也用于帮助定位该算法在完整量化方案中的位置。 | ||
| 152 | 107 | ||
| 153 | - [QuaRot](../quarot/term_quarot.md)：配套术语，常在本算法前作为离群值抑制步骤。 | 108 | - [QuaRot](../quarot/term_quarot.md)：配套术语，常在本算法前作为离群值抑制步骤。 |
| 154 | - [Adapt Rotation](../adapt_rotation/term_adapt_rotation.md)：配套术语，常与本算法配合用于 W4A4 量化。 | 109 | - [Adapt Rotation](../adapt_rotation/term_adapt_rotation.md)：配套术语，常与本算法配合用于 W4A4 量化。 |
| @@ -158,7 +113,9 @@ spec: | |||
| 158 | 113 | ||
| 159 | --- | 114 | --- |
| 160 | 115 | ||
| 161 | -## 9. 参考资料 | 116 | +## 4. 参考文档 |
| 162 | 117 | ||
| 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 | 118 | +参考文档优先列出算法原始论文或权威出处，并补充仓库内对应使用指南。需要进一步理解参数选择时，可先阅读使用指南，再回到原论文核对算法假设和推导。 |
| 164 | -2. 《AutoRound 使用指南》([./usage_autoround.md](./usage_autoround.md)) | 119 | + |
| 120 | +1. Cheng W, Zhang W, Shen H, et al. "Optimize Weight Rounding via Signed Gradient Descent for the Quantization of LLMs." Findings of EMNLP 2024. https://arxiv.org/abs/2309.05516 | ||
| 121 | +2. 《[AutoRound 参数配置流程指南](./usage_autoround.md)》 | ||
| @@ -1,178 +1,140 @@ | |||
| 1 | -# AutoRound 使用指南 | 1 | +# AutoRound 参数配置流程指南 |
| 2 | 2 | ||
| 3 | ## 1. 适用范围 | 3 | ## 1. 适用范围 |
| 4 | 4 | ||
| 5 | -本流程适用于在 msModelSlim 中配置和使用 AutoRound 低比特量化算法。AutoRound 作为权重量化处理器，通过可学习舍入与 SignSGD 优化，用于 4bit 等超低比特量化场景。 | 5 | +AutoRound 低比特量化算法。AutoRound 作为权重量化处理器，通过可学习舍入与 SignSGD 优化，用于 4bit 等超低比特量化场景。 |
| 6 | 6 | ||
| 7 | -适用角色：算法工程师、模型部署工程师 | 7 | +本指南面向首次配置 AutoRound 的用户，重点不是展开完整执行命令，而是说明推荐配置为什么适合作为起点、哪些参数真正需要调，以及出现精度或资源问题时应优先改哪一项。这类算法通常直接影响量化尺度、舍入方式、量化粒度或低比特表示，因此参数选择会同时影响精度、压缩率以及部署兼容性。第一次使用时建议先固定目标位宽、校准集和评测方式，只采用本指南给出的推荐起点；确认基线稳定后，再围绕真正影响算法行为的参数逐项调整。 |
| 8 | 8 | ||
| 9 | -适用场景： | 9 | +如果目标模型已经有完整且已验证的量化配方，应优先复用该配方；若当前算法与目标模型结构、数值格式或部署后端不兼容，不应通过增大搜索强度或扩大作用范围来绕过支持约束。 |
| 10 | 10 | ||
| 11 | -- 4bit 等超低比特权重量化场景。 | 11 | +## 2. 输入和交付件 |
| 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 | 12 | ||
| 34 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | | 13 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | |
| 35 | | --- | --- | --- | --- | --- | | 14 | | --- | --- | --- | --- | --- | |
| 36 | -| 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被目标 Transformers 版本加载 | | 15 | +| 输入 | 目标模型与量化目标 | 待量化模型及部署/评测方案 | 明确目标数值格式或位宽、作用模块、精度/性能目标以及部署约束 | 能说明为什么选择本算法以及它在整体量化方案中的位置 | |
| 37 | -| 输入 | 校准数据集 | 工具默认或用户指定 | JSONL 格式，每条含文本 prompt | 至少包含足够样本完成迭代优化 | | 16 | +| 输入 | 配置约束与实践基线 | 本算法配置说明、目标模型已有 `lab_practice` 配方（如有） | 字段名、支持组合、作用范围和模型适配与当前版本一致 | 推荐起点能够追溯到当前配置定义或已验证实践 | |
| 38 | -| 输入 | 量化 YAML 配置文件 | 用户编写 | 符合 msModelSlim YAML 规范，含 `autoround_quant` 处理器配置 | 可通过工具 `--config_path` 参数加载 | | 17 | +| 输入 | 校准数据（算法需要时） | 任务 `dataset`、校准集或模型实践配方 | 数据应能代表真实输入分布；多阶段算法尽量保持各阶段数据分布一致 | 能被当前量化流程正常读取，并覆盖主要输入形态 | |
| 39 | -| 交付件 | 量化权重目录 | `--save_path` 指定路径 | 含 `quant_model_description.json` 及 `*.safetensors`，已应用优化后的量化权重 | 推理冒烟通过 | | 18 | +| 交付件 | AutoRound 参数配置方案 | 用户量化 YAML 或任务配置 | 参数取值合法、作用范围明确；关键参数说明选择依据 | 可作为后续量化流程的算法配置输入，并可复现本指南中的基线选择 | |
| 40 | 19 | ||
| 41 | -## 4. 流程总览 | 20 | +## 3. 流程总览 |
| 21 | + | ||
| 22 | +入门时建议先用一组稳定配置建立基线，再围绕影响最大的参数做单变量调整。下面的流程强调“先选参数、再看效果”，不展开量化命令本身。 | ||
| 42 | 23 | ||
| 43 | ```mermaid | 24 | ```mermaid |
| 44 | flowchart LR | 25 | flowchart LR |
| 45 | - A[编写 YAML 配置] --> B[执行量化命令] | 26 | + A[确定目标位宽与混合策略] --> B[设置优化轮数] |
| 46 | - B --> C[逐层优化舍入] | 27 | + B[设置优化轮数] --> C[逐层优化量化参数与舍入] |
| 47 | - C --> D[应用量化权重] | 28 | + C[逐层优化量化参数与舍入] --> D[应用量化结果] |
| 48 | - D --> E[验证量化结果] | 29 | + D[应用量化结果] --> E[对比精度与耗时] |
| 49 | ``` | 30 | ``` |
| 50 | 31 | ||
| 51 | -## 5. 操作步骤 | 32 | +实际使用时建议把流程理解为“建立基线—观察结果—单变量调整—再次验证”的闭环。流程图中的前几个节点用于固定量化对象、统计信息或初始参数，后几个节点用于应用算法并检查结果；如果效果不理想，应优先回到最近一次修改的参数，而不是同时更换位宽、粒度、作用范围和算法强度。这样可以明确每次变化的因果关系，也便于把有效配置沉淀为后续模型配方。 |
| 52 | 33 | ||
| 53 | -### 步骤 1：编写 YAML 配置文件 | 34 | +## 4. 操作步骤 |
| 54 | 35 | ||
| 55 | -**目标**：编写包含 `autoround_quant` 处理器配置的 YAML 文件。 | 36 | +### 步骤 1：确认目标与约束 |
| 37 | + | ||
| 38 | +**操作**：先固定目标模型、最终量化格式/位宽、作用对象和评测基线，再确认当前版本支持的参数组合。目标模型已有 `lab_practice` 配方时，优先把该配方作为实践基线；没有模型专用配方时，再使用本指南给出的通用推荐起点。若算法依赖校准统计或优化数据，还应在调参前固定代表性数据，避免把数据分布变化误判为参数收益。 | ||
| 39 | + | ||
| 40 | +**输出**：一份明确的配置目标：目标位宽/格式、处理范围、校准条件、评测基线和部署约束。 | ||
| 41 | + | ||
| 42 | +### 步骤 2：建立推荐基线 | ||
| 56 | 43 | ||
| 57 | **操作**： | 44 | **操作**： |
| 58 | 45 | ||
| 59 | -1. 在 `spec.process` 下配置 `autoround_quant` 处理器，指定 `type: "autoround_quant"`。 | 46 | +下面配置用于建立**第一版可比较基线**。如果目标模型已有 `lab_practice` 配方，优先使用已验证配方，再参考本节理解每个参数为什么这样选。 |
| 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 | 47 | ||
| 66 | ```yaml | 48 | ```yaml |
| 67 | spec: | 49 | spec: |
| 68 | process: | 50 | process: |
| 69 | - - type: "autoround_quant" # 固定为 `autoround_quant`，用于指定 Processor 类型。 | 51 | + - type: "autoround_quant" |
| 70 | - iters: 400 # 优化迭代次数 | 52 | + iters: 400 |
| 71 | - enable_minmax_tuning: True # 是否启用最小最大值调优 | 53 | + enable_minmax_tuning: true |
| 72 | - enable_round_tuning: True # 是否启用舍入调优 | 54 | + enable_round_tuning: true |
| 73 | strategies: | 55 | strategies: |
| 74 | - # 策略1：除 up_proj、gate_proj 和 o_proj 层外，其余层均应用 W8A8 量化。 | 56 | + - qconfig: |
| 75 | - - qconfig: *default_w8a8_dynamic | 57 | + act: |
| 76 | - exclude: | 58 | + dtype: "int8" |
| 77 | - - "*.up_proj" | 59 | + scope: "per_token" |
| 78 | - - "*.gate_proj" | 60 | + symmetric: true |
| 79 | - - "*.o_proj" | 61 | + method: "minmax" |
| 80 | - # 策略2：对up_proj、gate_proj、o_proj层使用W4A4量化 | 62 | + weight: |
| 81 | - - qconfig: *default_w4a4_dynamic | 63 | + dtype: "int8" |
| 82 | - include: | 64 | + scope: "per_channel" |
| 83 | - - "*.up_proj" | 65 | + symmetric: true |
| 84 | - - "*.gate_proj" | 66 | + method: "autoround" |
| 85 | - - "*.o_proj" | 67 | + exclude: ["*.up_proj", "*.gate_proj", "*.o_proj"] |
| 68 | + - qconfig: | ||
| 69 | + act: | ||
| 70 | + dtype: "int4" | ||
| 71 | + scope: "per_token" | ||
| 72 | + symmetric: true | ||
| 73 | + method: "minmax" | ||
| 74 | + weight: | ||
| 75 | + dtype: "int4" | ||
| 76 | + scope: "per_channel" | ||
| 77 | + symmetric: true | ||
| 78 | + method: "autoround" | ||
| 79 | + include: ["*.up_proj", "*.gate_proj", "*.o_proj"] | ||
| 86 | ``` | 80 | ``` |
| 87 | 81 | ||
| 88 | -YAML 配置字段详解如下： | 82 | +上面的推荐值用于建立第一版可复现基线，其中最值得关注的配置包括 `type`, `iters`, `enable_minmax_tuning`, `enable_round_tuning`。推荐值并不表示所有模型都只能使用该组合，而是优先选择仓库默认值、已验证实践或较稳健的中间取值，以降低第一次使用时同时遇到精度和兼容性问题的概率。如果目标模型已经有 `lab_practice` 配方，应优先复用该配方；只有在基线精度、显存或吞吐不满足目标时，再按照下一节的参数说明逐项调整。 |
| 89 | 83 | ||
| 90 | -| 字段名 | 作用 | 说明 | | 84 | +**输出**：一份可复现的推荐基线配置，后续所有参数调整均以此为比较对象。 |
| 91 | -| --- | --- | --- | | ||
| 92 | -| type | 处理器类型标识 | 固定为 `"autoround_quant"`。 | | ||
| 93 | -| iters | 优化迭代次数 | 大于 0 的整数，影响优化效果与计算时间，默认 `10`。 | | ||
| 94 | -| enable_minmax_tuning | 最小最大值调优开关 | 布尔值，是否启用最小最大值调优，默认 `True`。 | | ||
| 95 | -| enable_round_tuning | 舍入调优开关 | 布尔值，是否启用舍入调优，默认 `True`。 | | ||
| 96 | -| strategies | 量化策略配置 | 策略列表，支持对不同层使用不同量化配置（如 int4 与 int8 混合量化）。 | | ||
| 97 | 85 | ||
| 98 | -**层过滤机制**： | 86 | +### 步骤 3：选择并调整参数 |
| 99 | - | ||
| 100 | -`include` 定义要包含的层，只有匹配 `include` 模式的层才会被处理；`exclude` 定义要排除的层，匹配 `exclude` 模式的层会被跳过；`exclude` 的优先级高于 `include`。匹配采用 Unix 通配符模式：`*` 匹配任意字符序列、`?` 匹配单个字符、`[abc]` 匹配字符集中的任意字符。若 `include`/`exclude` 未匹配到任何层，工具会进行告警，请核对层名、路径层级、大小写与拼写。 | ||
| 101 | - | ||
| 102 | -**输出**：YAML 配置文件 `${CONFIG_PATH}`。 | ||
| 103 | - | ||
| 104 | -### 步骤 2：执行量化命令 | ||
| 105 | - | ||
| 106 | -**目标**：使用上一步编写的 YAML 配置文件启动量化流程。 | ||
| 107 | 87 | ||
| 108 | **操作**： | 88 | **操作**： |
| 109 | 89 | ||
| 110 | -```bash | 90 | +ModelSlim 实现入口： |
| 111 | -msmodelslim quant \ | 91 | +[查看对应实现目录](../../../../../msmodelslim/processor/quant/autoround.py) |
| 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 | 92 | ||
| 120 | -参数说明： | 93 | +参数选择建议按三个层次理解：首先确认 `dtype/scope/method` 等**算法支持约束**，这类字段不是任意可调；其次确定 `include/exclude`、子图类型等**作用范围**；最后再调整会改变误差与开销的数值参数。下面的推荐值区分了代码默认值、仓库 `lab_practice` 中已验证的实践值和适合首次使用的推荐起点。如果目标模型已有实践配置，优先沿用实践配置，再根据本节说明做单变量调整。 |
| 121 | 94 | ||
| 122 | -| 参数 | 必选 | 说明 | | 95 | +| 配置项 | 含义（原理） | 推荐配置 | 选择与调整建议 | |
| 123 | -| --- | --- | --- | | 96 | +| --- | --- | --- | --- | |
| 124 | -| `model_path` | 是 | 浮点模型权重路径 | | 97 | +| `type` | 处理器标识，固定为 `autoround_quant`。 | 固定值。 | 不作为调参项。 | |
| 125 | -| `save_path` | 是 | 量化权重保存路径 | | 98 | +| `iters` | AutoRound 优化迭代次数。代码默认 `10` 更偏向快速起跑；仓库 Qwen3 W4A4 实践使用 `400`，说明实际低比特精度优化往往需要显著更多迭代。 | 正式精度基线推荐从仓库实践的 `400` 起步；只验证流程时可先用较小值。 | 观察相同校准集下的最终误差/任务指标：增加迭代仍持续改善时才继续加；结果已稳定则不必追求更大数字。不要把“默认 10”误解为低比特精度最佳值。 | |
| 126 | -| `device` | 否 | 量化设备，默认 `npu` | | 99 | +| `enable_minmax_tuning` | 是否允许优化截断边界/量化范围。开启后算法不仅优化舍入，还能调整 MinMax 范围，缓解极端值把步长拉大的问题。 | 推荐 `true`。 | 通常保持开启。只有做消融或明确需要锁定量化范围时才关闭；关闭后若精度下降，优先恢复该开关，而不是先增加 `iters`。 | |
| 127 | -| `model_type` | 是 | 模型名称，与支持矩阵一致 | | 100 | +| `enable_round_tuning` | 是否优化权重舍入方向，是 AutoRound 区别于普通 MinMax 权重量化的核心机制之一。 | 推荐 `true`。 | 常规使用不建议关闭；只在定位算法贡献或兼容性实验时关闭。关闭后即使 `iters` 很大，也无法获得完整的 AutoRound 舍入优化收益。 | |
| 128 | -| `config_path` | 是 | 步骤 1 编写的 YAML 配置路径 | | 101 | +| `strategies` | 混合量化策略列表。每条 strategy 有自己的 `qconfig` 和 `include/exclude`，用于让不同模块使用不同位宽/粒度。策略边界决定最终哪些层承担低比特误差。 | 优先复用模型实践。无专用配方时，先用较高精度覆盖大部分模块，再把明确适合的模块降到目标低比特。 | 策略调整顺序应是：先保护少数敏感模块，再扩大低比特覆盖。若 W4A4 精度不足，先把高敏感层移到 W8A8/更高精度策略，不要立即把全模型都升位宽。 | |
| 129 | -| `trust_remote_code` | 否 | 是否信任远程代码，默认 `False` | | 102 | +| `strategies[].qconfig.act` | 每条策略的激活量化配置。AutoRound 主要优化权重，但激活位宽/粒度决定优化时面对的完整 W/A 误差环境。仓库 W4A4 实践使用 INT4 per-token，W8A8 策略使用 INT8 per-token。 | 与最终激活部署格式一致；常见 INT 激活从 `per_token + symmetric + minmax` 起步。 | 改变激活位宽会改变最优权重舍入，应视为整套目标变化并重新优化。不要在 AutoRound 完成后只替换激活 qconfig 而复用旧权重优化结果。 | |
| 103 | +| `strategies[].qconfig.weight` | AutoRound 权重量化配置，`method` 应为 `autoround`，位宽/粒度决定权重码本与优化难度。 | 与最终权重格式一致；仓库 W4A4/W8A8 实践使用 per-channel 对称权重。 | 位宽越低误差压力越大。若从 INT8 改 INT4，除了更新 qconfig，还应重新跑优化并重新评估 `iters` 与策略范围。 | | ||
| 104 | +| `strategies[].include/exclude` | 给每条混合精度策略划分模块范围。多个策略组合时，这是决定实际落在哪个 qconfig 的关键。 | 直接沿用已验证模型配方；自定义时让各策略范围清晰、尽量避免模糊重叠。 | 精度不足优先做局部策略迁移：把最敏感的投影层从低比特策略移到高比特策略，再看收益；这样比全局提升位宽更容易控制压缩收益。 | | ||
| 130 | 105 | ||
| 131 | -执行流程说明： | 106 | +### 参数组合与选择顺序 |
| 132 | 107 | ||
| 133 | -1. 工具加载 YAML 配置，解析 `autoround_quant` 处理器。 | 108 | +1. **先锁定部署目标与支持组合**：先确定最终位宽/数值格式，再确认当前量化器实际注册了对应的 `dtype + scope + symmetric + method` 组合；不要为了追求某个参数值而越过支持约束。 |
| 134 | -2. preprocess 阶段逐层采集浮点基准输出并注入可训练量化参数。 | 109 | +2. **再固定作用范围**：使用已有模型配方时，先复用其 `include/exclude` 或子图类型；没有配方时先建立覆盖范围明确的基线，确认算法确实作用到了预期模块。 |
| 135 | -3. process 阶段逐层运行 SignSGD 优化，最小化重构误差。 | 110 | +3. **最后只调一个主要旋钮**：数值搜索步数、平滑强度、分组大小等一次只改一项，并保持同一校准集和评测集。若调整后没有稳定收益，回到上一个基线，而不是继续叠加多个变化。 |
| 136 | -4. postprocess 阶段应用优化后的量化参数并保存量化权重。 | ||
| 137 | 111 | ||
| 138 | -**输出**：量化权重目录 `${SAVE_PATH}`，包含量化描述文件与权重分片。 | 112 | +AutoRound 中 `iters` 不是第一个该调的参数。先确保策略中的最终 W/A 位宽、粒度和模块范围正确，再用 `iters` 控制优化充分程度；否则更多迭代只是在优化错误的目标。 |
| 139 | 113 | ||
| 140 | -### 步骤 3：验证量化结果 | 114 | +**输出**：一份完成单变量调整的算法参数方案，关键字段均有明确的选择依据和调整方向。 |
| 141 | 115 | ||
| 142 | -**目标**：确认量化权重文件完整且可加载。 | 116 | +### 步骤 4：根据结果收敛参数方案 |
| 143 | 117 | ||
| 144 | **操作**： | 118 | **操作**： |
| 145 | 119 | ||
| 146 | -1. 检查输出目录是否包含 `quant_model_description.json` 文件。 | 120 | +调参时建议先记录一份完整基线，包括使用的数据集、量化范围、关键参数和端到端指标。每轮只改变一个变量，并把变化结果与基线直接比较；如果某项调整带来收益，再继续小步搜索其邻近取值。对于只有少数层或模块异常的情况，优先采用局部排除、局部回退或混合精度，而不是直接提高全模型精度配置，这通常更容易保留压缩和性能收益。 |
| 147 | -2. 检查日志确认优化过程收敛且无层匹配告警。 | ||
| 148 | -3. 使用推理框架加载量化权重进行冒烟测试。 | ||
| 149 | 121 | ||
| 150 | -**输出**：量化权重验证通过。 | 122 | +- AutoRound 的主要代价是优化时间和显存。精度不足时优先增加 `iters` 或调整混合策略；资源不足时先减少需要4bit优化的层，而不是关闭核心舍入优化。 |
| 123 | +- **先跑推荐基线，再调单变量。** 不要同时修改位宽、粒度、算法参数和层范围，否则很难判断精度变化来自哪一项。 | ||
| 124 | +- **优先回退局部，而不是整体提高精度。** 如果只有少数层敏感，优先通过 `exclude` 或混合策略保留高精度，通常比整体升位宽更划算。 | ||
| 125 | +- **最终以模型实践配置和部署能力为准。** 入门推荐用于建立稳定起点；目标模型已有 `lab_practice` 配方时，应优先复用已验证组合。 | ||
| 151 | 126 | ||
| 152 | -## 6. 验收条件 | 127 | +**输出**：一份可进入后续量化流程的最终参数方案，并保留相对于推荐基线的调整记录。 |
| 153 | 128 | ||
| 154 | -- 量化权重目录包含 `quant_model_description.json` 及所有必需的 `*.safetensors` 分片文件。 | 129 | +## 5. 术语 |
| 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 | 130 | ||
| 167 | | 术语 | 简述 | 链接 | | 131 | | 术语 | 简述 | 链接 | |
| 168 | | --- | --- | --- | | 132 | | --- | --- | --- | |
| 169 | -| AutoRound | 基于 SignSGD 的低比特权重量化算法 | [AutoRound 词条](./term_autoround.md) | | 133 | +| AutoRound 低比特量化算法 | 说明该算法的定义、核心原理、关键性质、适用场景与限制。 | 《[AutoRound 低比特量化算法 量化术语百科词条](./term_autoround.md)》 | |
| 170 | -| SignSGD | 符号梯度下降优化器 | [AutoRound 词条](./term_autoround.md) | | ||
| 171 | -| 混合量化 | 对不同层使用不同量化配置的策略 | [AutoRound 词条](./term_autoround.md) | | ||
| 172 | 134 | ||
| 173 | -## 9. 接口文档列表 | 135 | +## 6. 接口文档列表 |
| 174 | 136 | ||
| 175 | | 接口或能力 | 简述 | 链接 | | 137 | | 接口或能力 | 简述 | 链接 | |
| 176 | | --- | --- | --- | | 138 | | --- | --- | --- | |
| 177 | -| `autoround_quant` 处理器 | 用于执行 AutoRound 低比特量化的 Processor 配置 | [AutoRound 词条](./term_autoround.md) | | 139 | +| autoround_quant 配置说明 | 字段类型、默认值、合法取值与完整配置约束。 | 《[autoround_quant 配置说明](../../../api_reference/config/processor/autoround_quant.md)》 | |
| 178 | -| 层过滤机制 | include/exclude 通配符匹配规则 | [线性量化词条](../linear_quant/term_linear_quant.md) | | 140 | +| modelslim_v1 配置说明 | 需要继续探索 runner、prior、save、dataset 等任务级高级配置时查阅。 | 《[modelslim_v1 配置说明](../../../api_reference/config/task/modelslim_v1.md)》 | |
| @@ -1,18 +1,15 @@ | |||
| 1 | -# AWQ 激活感知权重量化算法词条 | 1 | +# AWQ 激活感知权重量化算法 量化术语百科词条 |
| 2 | 2 | ||
| 3 | -> **词条类别**：离群值抑制算法 | 3 | +> **词条类别**：[离群值抑制算法](../README.md#1-离群值抑制算法)<br> |
| 4 | -> **英文名称**：AWQ Smooth | 4 | +> **英文名称**：awq_smooth<br> |
| 5 | -> **英文缩写**：AWQ | 5 | +> **应用领域**：大语言模型量化压缩、低比特量化精度优化<br> |
| 6 | -> **中文别名**：激活感知权重量化 | ||
| 7 | > **首次提出**：Lin et al., MLSys 2024 | 6 | > **首次提出**：Lin et al., MLSys 2024 |
| 8 | -> **应用领域**：大语言模型量化压缩、低比特量化精度优化 | ||
| 9 | -> **msModelSlim 实现**：`msmodelslim/processor/anti_outlier/awq/` | ||
| 10 | 7 | ||
| 11 | --- | 8 | --- |
| 12 | 9 | ||
| 13 | ## 1. 概述 | 10 | ## 1. 概述 |
| 14 | 11 | ||
| 15 | -AWQ（Activation-aware Weight Quantization，激活感知权重量化）是一种用于大语言模型量化过程中抑制激活离群值的算法。它通过观察激活值的统计特征，用激活均值度量各权重通道的重要性，并通过网格搜索找到使量化结果与浮点基准之间均方误差最小的缩放因子。其核心特征是：激活感知的重要性评估、网格搜索最优缩放、块级误差评估，常作为 [MinMax](../minmax/term_minmax.md) 等权重量化的前置步骤。 | 12 | +AWQ（Activation-aware Weight Quantization）是一种激活感知的权重缩放与离群值抑制方法。它利用校准激活估计通道重要性，并搜索缩放因子，在保持等价变换关系的同时降低后续权重量化误差；核心特征是激活感知、通道级缩放和误差驱动搜索，适合作为低比特权重量化前的分布整形步骤。 |
| 16 | 13 | ||
| 17 | --- | 14 | --- |
| 18 | 15 | ||
| @@ -20,15 +17,21 @@ AWQ（Activation-aware Weight Quantization，激活感知权重量化）是一 | |||
| 20 | 17 | ||
| 21 | 并非所有权重通道对模型输出同等重要。AWQ 观察到，通过激活值分布可以识别重要权重通道并给予保护：对重要通道施加更小的量化扰动，可以在低比特量化场景下获得更优的精度表现。与 [SmoothQuant](../smooth_quant/term_smooth_quant.md) 的固定缩放不同，AWQ 通过网格搜索在激活统计的指导下寻找最优缩放因子。 | 18 | 并非所有权重通道对模型输出同等重要。AWQ 观察到，通过激活值分布可以识别重要权重通道并给予保护：对重要通道施加更小的量化扰动，可以在低比特量化场景下获得更优的精度表现。与 [SmoothQuant](../smooth_quant/term_smooth_quant.md) 的固定缩放不同，AWQ 通过网格搜索在激活统计的指导下寻找最优缩放因子。 |
| 22 | 19 | ||
| 23 | ---- | 20 | +从量化流程中的定位看，该算法更接近量化前的分布整形步骤：先降低离群值对量化尺度的支配，再由后续量化算法完成真正的离散化。这种思路的价值在于不必简单扩大位宽，而是通过重分配、旋转或平滑数值幅度，提高有限量化区间对主体数据分布的利用率。 |
| 24 | 21 | ||
| 25 | -## 3. 原理 | 22 | +### 2.1 核心思想 |
| 26 | 23 | ||
| 27 | -### 1. 核心思想 | 24 | +AWQ 的核心思想是“按激活重要性保护权重通道”：使用校准激活统计量估计输入通道的重要程度，再通过等价的逐通道缩放，把更有利的量化分辨率分配给对输出影响更大的权重通道。缩放强度不是固定经验值，而是在一组候选比例中结合真实权重量化后的输出重构误差选择，使“保护重要通道”与“避免其他权重尺度恶化”取得平衡。 |
| 28 | 25 | ||
| 29 | -AWQ 的核心思想是“按激活重要性保护权重通道”：使用激活值绝对值的逐通道均值度量通道重要性，在 $[0, 1)$ 范围内以网格搜索遍历 `ratio` 参数，用真实的权重量化器评估缩放后的量化误差，选择均方误差最小的缩放因子，并通过最低公共祖先（LCA）在块级别评估误差。 | 26 | +从误差传播看，若量化后的权重写成 $Q(sW)=sW+E$，则等价缩放后的输出误差约为 $(X/s)E$。 |
| 30 | 27 | ||
| 31 | -### 2. 数学描述 | 28 | +### 2.2 工作机制 |
| 29 | + | ||
| 30 | +AWQ 类方法首先利用校准激活估计每个输入通道的重要程度。若某个通道的激活经常具有较大幅值，那么该通道上的权重量化误差会被更大的输入系数放大，对层输出造成更明显影响。因此算法不是平均对待所有权重，而是通过逐通道尺度把更重要通道对应的权重放大，使这些权重在低比特网格上获得更有利的表示。 | ||
| 31 | + | ||
| 32 | +缩放本身采用等价重参数化：若 $X'=X/s$、$W'=W\cdot s$，则浮点乘积保持不变。真正需要搜索的是“迁移多少幅度”最合适。候选 ratio 决定激活重要性对尺度的作用强弱；每个候选都会经过目标权重量化，并在包含相关子层的输出上计算重构误差。这样，搜索目标直接面向量化后的计算误差，而不是只追求权重张量本身看起来更平滑。 | ||
| 33 | + | ||
| 34 | +### 2.3 数学描述 | ||
| 32 | 35 | ||
| 33 | 缩放因子的计算公式为： | 36 | 缩放因子的计算公式为： |
| 34 | 37 | ||
| @@ -39,7 +42,6 @@ $$ | |||
| 39 | - $s$：逐通道缩放因子 | 42 | - $s$：逐通道缩放因子 |
| 40 | - $\text{act\_mean}$：激活值绝对值的逐通道均值，即 $mean(|act|)$，反映各通道重要性 | 43 | - $\text{act\_mean}$：激活值绝对值的逐通道均值，即 $mean(|act|)$，反映各通道重要性 |
| 41 | - $\text{ratio}$：缩放比例系数，在 $[0, 1)$ 范围内以 $1 / n\_grid$ 为步长网格搜索 | 44 | - $\text{ratio}$：缩放比例系数，在 $[0, 1)$ 范围内以 $1 / n\_grid$ 为步长网格搜索 |
| 42 | -- $n\_grid$：网格搜索步数，默认 $20$ | ||
| 43 | - $10^{-4}$：缩放因子的最小值 | 45 | - $10^{-4}$：缩放因子的最小值 |
| 44 | 46 | ||
| 45 | 块级误差评估使用 MSE： | 47 | 块级误差评估使用 MSE： |
| @@ -51,115 +53,62 @@ $$ | |||
| 51 | - $y_{\text{float}}$：使用原始浮点权重在祖先模块上的输出 | 53 | - $y_{\text{float}}$：使用原始浮点权重在祖先模块上的输出 |
| 52 | - $y_{\text{quant}}$：使用量化权重在祖先模块上的输出 | 54 | - $y_{\text{quant}}$：使用量化权重在祖先模块上的输出 |
| 53 | 55 | ||
| 54 | -### 3. 关键性质 | 56 | +把缩放写成 $D=\operatorname{diag}(s)$，浮点等价关系为： |
| 57 | + | ||
| 58 | +$$ | ||
| 59 | +Y=XW^T=(XD^{-1})(WD)^T. | ||
| 60 | +$$ | ||
| 61 | + | ||
| 62 | +若 $WD$ 经过权重量化后产生误差矩阵 $E=\mathcal Q(WD)-WD$，则量化输出误差为： | ||
| 63 | + | ||
| 64 | +$$ | ||
| 65 | +\Delta Y=(XD^{-1})E^T. | ||
| 66 | +$$ | ||
| 67 | + | ||
| 68 | +因此增大某通道 $s_j$ 会显式减小该通道激活系数 $X_j/s_j$，但同时也会改变 $E$，因为量化器看到的是重新缩放后的 $WD$。AWQ 的搜索本质上是在这两个相反效应之间寻找输出误差最小点。 | ||
| 69 | + | ||
| 70 | +### 2.4 关键性质 | ||
| 55 | 71 | ||
| 56 | - **激活感知**：基于激活均值识别重要通道并给予保护。 | 72 | - **激活感知**：基于激活均值识别重要通道并给予保护。 |
| 57 | -- **网格搜索**：在 $[0, 1)$ 范围内搜索最优 `ratio`，步长 $1/n\_grid$。 | 73 | +- **候选尺度搜索**：在不同迁移强度之间比较真实量化后的输出误差，避免只依赖解析启发式。 |
| 58 | - **真实量化器评估**：使用真实权重量化器评估候选缩放因子的量化误差。 | 74 | - **真实量化器评估**：使用真实权重量化器评估候选缩放因子的量化误差。 |
| 59 | - **块级评估**：通过自动发现的最低公共祖先模块在块级别评估误差，而非单层权重误差。 | 75 | - **块级评估**：通过自动发现的最低公共祖先模块在块级别评估误差，而非单层权重误差。 |
| 76 | +- **误差目标面向输出**：候选尺度需要在真实量化后比较输出重构，而不是只最小化权重张量自身 MSE。 | ||
| 60 | 77 | ||
| 61 | ---- | 78 | +因此尺度不能无限增大，需要用真实量化器和输出误差搜索折中。激活均值是一种稳健的重要性代理，但如果任务关键行为由少量罕见 token 触发，仅靠均值也可能低估这些通道。 |
| 62 | 79 | ||
| 63 | -## 4. 流程示意 | 80 | +### 2.5 适用场景 |
| 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 | 81 | ||
| 133 | - 需要自动搜索最优权重缩放因子、保护重要通道的低比特量化场景。 | 82 | - 需要自动搜索最优权重缩放因子、保护重要通道的低比特量化场景。 |
| 134 | - 作为权重量化的前置步骤，为 [MinMax](../minmax/term_minmax.md)、[SSZ](../ssz/term_ssz.md) 等权重量化算法提供更优的权重分布。 | 83 | - 作为权重量化的前置步骤，为 [MinMax](../minmax/term_minmax.md)、[SSZ](../ssz/term_ssz.md) 等权重量化算法提供更优的权重分布。 |
| 135 | 84 | ||
| 136 | -### 2. 使用限制 | 85 | +更具体地说，这类算法适合“量化误差主要由少数大幅值通道或 token 拉高尺度”的情况。若问题来源并不是离群值，而是模型本身对低比特表示普遍敏感，则单独增加平滑或旋转强度通常收益有限，应结合更高精度量化或敏感层回退。 |
| 137 | 86 | ||
| 138 | -- 模型适配器需要实现 `AWQInterface` 接口。 | 87 | +### 2.6 使用限制 |
| 139 | -- 配置中的模块名称必须与 `named_modules()` 返回的完整路径一致。 | 88 | + |
| 140 | -- 目标模块必须存在且具备可写的 `weight`。 | 89 | +- 需要校准数据提供稳定的激活统计；校准分布偏离实际业务时，搜索到的重要通道与缩放因子可能失效。 |
| 141 | -- 依赖 `ContextManager` 提供全局上下文。 | 90 | +- 搜索阶段应使用与最终部署一致的权重量化方式评估候选缩放，否则最小重构误差不一定对应最终最优精度。 |
| 91 | +- 网格搜索会带来额外校准开销，搜索密度越高，耗时越大。 | ||
| 92 | + | ||
| 93 | +这些限制反映了算法对模型结构和等价变换条件的依赖。若目标模型不满足相应结构假设，强行套用可能破坏原有计算关系；因此遇到不兼容结构时应优先缩小作用范围或使用模型已验证的配方，而不是盲目增大平滑强度。 | ||
| 142 | 94 | ||
| 143 | --- | 95 | --- |
| 144 | 96 | ||
| 145 | -## 7. 关联流程 | 97 | +## 3. 关联词条 |
| 146 | 98 | ||
| 147 | -- 《[一键量化 (V1)](../../../user_guide/usage_quick_quantization.md)》：默认集成本算法作为离群值抑制前置步骤。 | 99 | +可以从“同类方法、前后处理关系和应用对象”三个方向理解本词条与其他算法的关系。下面的关联项既用于横向比较不同技术路线，也用于帮助定位该算法在完整量化方案中的位置。 |
| 148 | -- 《[量化精度调优指南](../../../user_guide/process_quantization_precision_tuning.md)》：精度不达标时可考虑启用本算法。 | ||
| 149 | - | ||
| 150 | ---- | ||
| 151 | - | ||
| 152 | -## 8. 关联词条 | ||
| 153 | 100 | ||
| 154 | - [SmoothQuant](../smooth_quant/term_smooth_quant.md)：同类算法，同属离群值抑制算法族，但采用固定缩放而非激活感知搜索。 | 101 | - [SmoothQuant](../smooth_quant/term_smooth_quant.md)：同类算法，同属离群值抑制算法族，但采用固定缩放而非激活感知搜索。 |
| 155 | - [Flex AWQ SSZ](../flex_awq_ssz/term_flex_awq_ssz.md)：同类算法，本算法的扩展，使用真实量化器评估参数。 | 102 | - [Flex AWQ SSZ](../flex_awq_ssz/term_flex_awq_ssz.md)：同类算法，本算法的扩展，使用真实量化器评估参数。 |
| 156 | -- [MinMax](../minmax/term_minmax.md)：配套术语，AWQ 搜索阶段使用 `weight_qconfig` 指定的量化配置。 | 103 | +- [MinMax](../minmax/term_minmax.md)：配套术语，AWQ 搜索阶段需要用目标权重量化方法评估候选缩放。 |
| 157 | - [SSZ](../ssz/term_ssz.md)：配套术语，常与 AWQ 的平滑配合用于权重量化。 | 104 | - [SSZ](../ssz/term_ssz.md)：配套术语，常与 AWQ 的平滑配合用于权重量化。 |
| 158 | - [QuaRot](../quarot/term_quarot.md)：对比算法，采用正交旋转而非缩放抑制离群值。 | 105 | - [QuaRot](../quarot/term_quarot.md)：对比算法，采用正交旋转而非缩放抑制离群值。 |
| 159 | 106 | ||
| 160 | --- | 107 | --- |
| 161 | 108 | ||
| 162 | -## 9. 参考资料 | 109 | +## 4. 参考文档 |
| 110 | + | ||
| 111 | +参考文档优先列出算法原始论文或权威出处，并补充仓库内对应使用指南。需要进一步理解参数选择时，可先阅读使用指南，再回到原论文核对算法假设和推导。 | ||
| 163 | 112 | ||
| 164 | 1. Lin J et al. AWQ: Activation-aware Weight Quantization for LLM Compression and Acceleration. MLSys 2024. https://arxiv.org/abs/2306.00978 | 113 | 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)) | 114 | +2. 《[AWQ 参数配置流程指南](./usage_awq_smooth.md)》 |
| @@ -1,66 +1,49 @@ | |||
| 1 | -# AWQ 使用指南 | 1 | +# AWQ 参数配置流程指南 |
| 2 | 2 | ||
| 3 | ## 1. 适用范围 | 3 | ## 1. 适用范围 |
| 4 | 4 | ||
| 5 | -本流程适用于在 msModelSlim 中配置和使用 AWQ 激活感知权重量化算法。AWQ 作为离群值抑制算法，通常作为权重量化前的预处理步骤，通过激活感知搜索最优缩放因子，提升低比特量化的精度。 | 5 | +AWQ 激活感知权重量化算法。AWQ 作为离群值抑制算法，通常作为权重量化前的预处理步骤，通过激活感知搜索最优缩放因子，提升低比特量化的精度。 |
| 6 | 6 | ||
| 7 | -适用角色：算法工程师、模型部署工程师 | 7 | +本指南面向首次配置 AWQ 的用户，重点不是展开完整执行命令，而是说明推荐配置为什么适合作为起点、哪些参数真正需要调，以及出现精度或资源问题时应优先改哪一项。这类算法的主要作用是先改善待量化张量的数值分布，再交给后续量化步骤处理，本身通常不是最终的量化格式。因此判断配置是否合适时，不仅要看平滑或旋转后的张量范围，还要看与后续量化组合后的端到端精度；建议保持后续量化配置不变，只调整当前算法参数。 |
| 8 | 8 | ||
| 9 | -适用场景： | 9 | +如果目标模型已经有完整且已验证的量化配方，应优先复用该配方；若当前算法与目标模型结构、数值格式或部署后端不兼容，不应通过增大搜索强度或扩大作用范围来绕过支持约束。 |
| 10 | 10 | ||
| 11 | -- 需要自动搜索最优权重缩放因子、保护重要通道的低比特量化场景。 | 11 | +## 2. 输入和交付件 |
| 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 | 12 | ||
| 34 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | | 13 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | |
| 35 | | --- | --- | --- | --- | --- | | 14 | | --- | --- | --- | --- | --- | |
| 36 | -| 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被目标 Transformers 版本加载 | | 15 | +| 输入 | 目标模型与量化目标 | 待量化模型及部署/评测方案 | 明确目标数值格式或位宽、作用模块、精度/性能目标以及部署约束 | 能说明为什么选择本算法以及它在整体量化方案中的位置 | |
| 37 | -| 输入 | 校准数据集 | 工具默认或用户指定 | JSONL 格式，每条含文本 prompt | 可被工具加载并完成前向推理 | | 16 | +| 输入 | 配置约束与实践基线 | 本算法配置说明、目标模型已有 `lab_practice` 配方（如有） | 字段名、支持组合、作用范围和模型适配与当前版本一致 | 推荐起点能够追溯到当前配置定义或已验证实践 | |
| 38 | -| 输入 | 量化 YAML 配置文件 | 用户编写 | 符合 msModelSlim YAML 规范，含 `awq` 处理器配置 | 可通过工具 `--config_path` 参数加载 | | 17 | +| 输入 | 校准数据（算法需要时） | 任务 `dataset`、校准集或模型实践配方 | 数据应能代表真实输入分布；多阶段算法尽量保持各阶段数据分布一致 | 能被当前量化流程正常读取，并覆盖主要输入形态 | |
| 39 | -| 交付件 | 平滑后的量化权重目录 | `--save_path` 指定路径 | 含 `quant_model_description.json` 及 `*.safetensors`，已应用最优缩放 | 推理冒烟通过 | | 18 | +| 交付件 | AWQ 参数配置方案 | 用户量化 YAML 或任务配置 | 参数取值合法、作用范围明确；关键参数说明选择依据 | 可作为后续量化流程的算法配置输入，并可复现本指南中的基线选择 | |
| 40 | 19 | ||
| 41 | -## 4. 流程总览 | 20 | +## 3. 流程总览 |
| 21 | + | ||
| 22 | +入门时建议先用一组稳定配置建立基线，再围绕影响最大的参数做单变量调整。下面的流程强调“先选参数、再看效果”，不展开量化命令本身。 | ||
| 42 | 23 | ||
| 43 | ```mermaid | 24 | ```mermaid |
| 44 | flowchart LR | 25 | flowchart LR |
| 45 | - A[编写 YAML 配置] --> B[执行量化命令] | 26 | + A[确定下游权重量化方式] --> B[收集激活重要性统计] |
| 46 | - B --> C[收集激活均值] | 27 | + B[收集激活重要性统计] --> C[网格搜索缩放因子] |
| 47 | - C --> D[搜索并融合缩放] | 28 | + C[网格搜索缩放因子] --> D[融合缩放] |
| 48 | - D --> E[验证量化结果] | 29 | + D[融合缩放] --> E[进入权重量化] |
| 49 | ``` | 30 | ``` |
| 50 | 31 | ||
| 51 | -## 5. 操作步骤 | 32 | +实际使用时建议把流程理解为“建立基线—观察结果—单变量调整—再次验证”的闭环。流程图中的前几个节点用于固定量化对象、统计信息或初始参数，后几个节点用于应用算法并检查结果；如果效果不理想，应优先回到最近一次修改的参数，而不是同时更换位宽、粒度、作用范围和算法强度。这样可以明确每次变化的因果关系，也便于把有效配置沉淀为后续模型配方。 |
| 52 | 33 | ||
| 53 | -### 步骤 1：编写 YAML 配置文件 | 34 | +## 4. 操作步骤 |
| 54 | 35 | ||
| 55 | -**目标**：编写包含 `awq` 处理器配置的 YAML 文件。 | 36 | +### 步骤 1：确认目标与约束 |
| 37 | + | ||
| 38 | +**操作**：先固定目标模型、最终量化格式/位宽、作用对象和评测基线，再确认当前版本支持的参数组合。目标模型已有 `lab_practice` 配方时，优先把该配方作为实践基线；没有模型专用配方时，再使用本指南给出的通用推荐起点。若算法依赖校准统计或优化数据，还应在调参前固定代表性数据，避免把数据分布变化误判为参数收益。 | ||
| 39 | + | ||
| 40 | +**输出**：一份明确的配置目标：目标位宽/格式、处理范围、校准条件、评测基线和部署约束。 | ||
| 41 | + | ||
| 42 | +### 步骤 2：建立推荐基线 | ||
| 56 | 43 | ||
| 57 | **操作**： | 44 | **操作**： |
| 58 | 45 | ||
| 59 | -1. 在 `spec.process` 下配置 `awq` 处理器，指定 `type: "awq"`。 | 46 | +下面配置用于建立**第一版可比较基线**。如果目标模型已有 `lab_practice` 配方，优先使用已验证配方，再参考本节理解每个参数为什么这样选。 |
| 60 | -2. 配置 `weight_qconfig`（AWQ 搜索阶段使用的权重量化配置）。 | ||
| 61 | -3. 按需配置 `n_grid`（默认 `20`）、`enable_subgraph_type` 与 `include`/`exclude`。 | ||
| 62 | - | ||
| 63 | -YAML 配置示例： | ||
| 64 | 47 | ||
| 65 | ```yaml | 48 | ```yaml |
| 66 | spec: | 49 | spec: |
| @@ -81,91 +64,59 @@ spec: | |||
| 81 | exclude: [] | 64 | exclude: [] |
| 82 | ``` | 65 | ``` |
| 83 | 66 | ||
| 84 | -YAML 配置字段详解如下： | 67 | +上面的推荐值用于建立第一版可复现基线，其中最值得关注的配置包括 `type`, `weight_qconfig`, `n_grid`, `enable_subgraph_type`。推荐值并不表示所有模型都只能使用该组合，而是优先选择仓库默认值、已验证实践或较稳健的中间取值，以降低第一次使用时同时遇到精度和兼容性问题的概率。如果目标模型已经有 `lab_practice` 配方，应优先复用该配方；只有在基线精度、显存或吞吐不满足目标时，再按照下一节的参数说明逐项调整。 |
| 85 | 68 | ||
| 86 | -| 字段名 | 作用 | 说明 | | 69 | +**输出**：一份可复现的推荐基线配置，后续所有参数调整均以此为比较对象。 |
| 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 | 70 | ||
| 95 | -**输出**：YAML 配置文件 `${CONFIG_PATH}`。 | 71 | +### 步骤 3：选择并调整参数 |
| 96 | - | ||
| 97 | -### 步骤 2：执行量化命令 | ||
| 98 | - | ||
| 99 | -**目标**：使用上一步编写的 YAML 配置文件启动量化流程。 | ||
| 100 | 72 | ||
| 101 | **操作**： | 73 | **操作**： |
| 102 | 74 | ||
| 103 | -```bash | 75 | +ModelSlim 实现入口： |
| 104 | -msmodelslim quant \ | 76 | +[查看对应实现目录](../../../../../msmodelslim/processor/anti_outlier/awq) |
| 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 | 77 | ||
| 113 | -参数说明： | 78 | +参数选择建议按三个层次理解：首先确认 `dtype/scope/method` 等**算法支持约束**，这类字段不是任意可调；其次确定 `include/exclude`、子图类型等**作用范围**；最后再调整会改变误差与开销的数值参数。下面的推荐值区分了代码默认值、仓库 `lab_practice` 中已验证的实践值和适合首次使用的推荐起点。如果目标模型已有实践配置，优先沿用实践配置，再根据本节说明做单变量调整。 |
| 114 | 79 | ||
| 115 | -| 参数 | 必选 | 说明 | | 80 | +| 配置项 | 含义（原理） | 推荐配置 | 选择与调整建议 | |
| 116 | -| --- | --- | --- | | 81 | +| --- | --- | --- | --- | |
| 117 | -| `model_path` | 是 | 浮点模型权重路径 | | 82 | +| `type` | 处理器标识，固定为 `awq`。 | 固定。 | 不作为精度旋钮。 | |
| 118 | -| `save_path` | 是 | 量化权重保存路径 | | 83 | +| `weight_qconfig` | AWQ 搜索缩放系数时用于模拟最终权重量化误差的配置。搜索器会用它评价候选缩放，因此其 `dtype/scope/symmetric/method` 必须代表最终权重量化器。 | 必须与下游最终权重量化配置保持一致。INT4 权重目标就用 INT4 配置；只做 W8 权重量化则用 INT8。 | 最终权重量化方式一旦变化，应重新搜索 AWQ scale。不要用 INT8 的搜索结果直接服务 INT4，也不要搜索时用 per-channel、落地时改成另一种粒度。 | |
| 119 | -| `device` | 否 | 量化设备，默认 `npu` | | 84 | +| `n_grid` | AWQ 缩放系数的网格搜索密度，默认 `20`。网格越密，候选更细，搜索时间也相应增加。 | 先用默认 `20`。 | 当最优点对网格位置很敏感、重复试验显示粗网格错过明显更优区间时再增加；快速验证可减少。若精度问题来自错误 qconfig 或子图范围，增加网格数不会解决。 | |
| 120 | -| `model_type` | 是 | 模型名称，与支持矩阵一致 | | 85 | +| `enable_subgraph_type` | 控制 AWQ 在哪些可融合结构上搜索/应用平滑，支持 `norm-linear`、`linear-linear`、`ov`、`up-down`。不同模型结构可匹配的子图不同。 | 没有模型配方时从默认四类建立覆盖基线；有实践配置时只启用实践中验证的结构。 | 如果某类结构不匹配、效果不稳定或部署融合不支持，就只关闭该类；不要为了规避单个问题把所有子图都关掉。新增子图类型后要重新校准，因为搜索数据和权重路径都变了。 | |
| 121 | -| `config_path` | 是 | 步骤 1 编写的 YAML 配置路径 | | 86 | +| `include` | 作用范围白名单，使用模块名模式决定哪些匹配到的模块进入当前算法。它只决定“在哪些模块做”，不会改变算法内部公式。 | 无模型专用配方时从 `["*"]` 开始；已有 `lab_practice` 时直接沿用其模块范围。 | 先保证范围覆盖预期模块，再看精度。范围过宽时，少数结构不兼容或敏感层会放大整体风险；范围过窄则可能让算法收益看不出来。收窄范围时优先按结构族或已知敏感层调整，不建议仅凭层号大面积删除。 | |
| 122 | -| `trust_remote_code` | 否 | 是否信任远程代码，默认 `False` | | 87 | +| `exclude` | 作用范围黑名单，命中后从 `include` 的候选中排除，优先级高于 `include`。适合保护敏感层、首尾层或模型专用不兼容结构。 | 默认先保持空列表；只有实践配方、兼容性约束或敏感性结果给出明确证据时再加入。 | 局部精度问题优先通过 `exclude` 做小范围回退，比提高全模型位宽或关闭整个算法更容易保留收益。每次增加排除项后应确认通配符没有误伤相邻模块。 | |
| 123 | 88 | ||
| 124 | -执行流程说明： | 89 | +### 参数组合与选择顺序 |
| 125 | 90 | ||
| 126 | -1. 工具加载 YAML 配置，解析 `awq` 处理器。 | 91 | +1. **先锁定部署目标与支持组合**：先确定最终位宽/数值格式，再确认当前量化器实际注册了对应的 `dtype + scope + symmetric + method` 组合；不要为了追求某个参数值而越过支持约束。 |
| 127 | -2. 预处理阶段为目标线性层安装 forward hook，收集激活均值并缓存祖先模块输入。 | 92 | +2. **再固定作用范围**：使用已有模型配方时，先复用其 `include/exclude` 或子图类型；没有配方时先建立覆盖范围明确的基线，确认算法确实作用到了预期模块。 |
| 128 | -3. 后处理阶段按子图优先级搜索最优缩放因子，通过 `SubgraphFusionFactory` 融合。 | 93 | +3. **最后只调一个主要旋钮**：数值搜索步数、平滑强度、分组大小等一次只改一项，并保持同一校准集和评测集。若调整后没有稳定收益，回到上一个基线，而不是继续叠加多个变化。 |
| 129 | -4. 继续执行下游量化处理器并保存量化权重。 | ||
| 130 | 94 | ||
| 131 | -**输出**：量化权重目录 `${SAVE_PATH}`，包含量化描述文件与权重分片。 | 95 | +AWQ 最关键的联动是 **`weight_qconfig` ↔ 最终权重量化配置**。先把目标 qconfig 定死，再决定子图范围，最后才用 `n_grid` 微调搜索精度。 |
| 132 | 96 | ||
| 133 | -### 步骤 3：验证量化结果 | 97 | +**输出**：一份完成单变量调整的算法参数方案，关键字段均有明确的选择依据和调整方向。 |
| 134 | 98 | ||
| 135 | -**目标**：确认量化权重文件完整且可加载。 | 99 | +### 步骤 4：根据结果收敛参数方案 |
| 136 | 100 | ||
| 137 | **操作**： | 101 | **操作**： |
| 138 | 102 | ||
| 139 | -1. 检查输出目录是否包含 `quant_model_description.json` 文件。 | 103 | +调参时建议先记录一份完整基线，包括使用的数据集、量化范围、关键参数和端到端指标。每轮只改变一个变量，并把变化结果与基线直接比较；如果某项调整带来收益，再继续小步搜索其邻近取值。对于只有少数层或模块异常的情况，优先采用局部排除、局部回退或混合精度，而不是直接提高全模型精度配置，这通常更容易保留压缩和性能收益。 |
| 140 | -2. 检查日志确认无层匹配告警或祖先模块未找到告警。 | ||
| 141 | -3. 使用推理框架加载量化权重进行冒烟测试。 | ||
| 142 | 104 | ||
| 143 | -**输出**：量化权重验证通过。 | 105 | +- **先跑推荐基线，再调单变量。** 不要同时修改位宽、粒度、算法参数和层范围，否则很难判断精度变化来自哪一项。 |
| 106 | +- **优先回退局部，而不是整体提高精度。** 如果只有少数层敏感，优先通过 `exclude` 或混合策略保留高精度，通常比整体升位宽更划算。 | ||
| 107 | +- **最终以模型实践配置和部署能力为准。** 入门推荐用于建立稳定起点；目标模型已有 `lab_practice` 配方时，应优先复用已验证组合。 | ||
| 144 | 108 | ||
| 145 | -## 6. 验收条件 | 109 | +**输出**：一份可进入后续量化流程的最终参数方案，并保留相对于推荐基线的调整记录。 |
| 146 | 110 | ||
| 147 | -- 量化权重目录包含 `quant_model_description.json` 及所有必需的 `*.safetensors` 分片文件。 | 111 | +## 5. 术语 |
| 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 | 112 | ||
| 160 | | 术语 | 简述 | 链接 | | 113 | | 术语 | 简述 | 链接 | |
| 161 | | --- | --- | --- | | 114 | | --- | --- | --- | |
| 162 | -| AWQ | 激活感知权重量化，基于激活均值搜索最优缩放因子 | [AWQ 词条](./term_awq_smooth.md) | | 115 | +| AWQ 激活感知权重量化算法 | 说明该算法的定义、核心原理、关键性质、适用场景与限制。 | 《[AWQ 激活感知权重量化算法 量化术语百科词条](./term_awq_smooth.md)》 | |
| 163 | -| weight_qconfig | AWQ 搜索阶段使用的权重量化配置 | [AWQ 词条](./term_awq_smooth.md) | | ||
| 164 | -| 最低公共祖先（LCA） | 用于块级误差评估的祖先模块 | [AWQ 词条](./term_awq_smooth.md) | | ||
| 165 | 116 | ||
| 166 | -## 9. 接口文档列表 | 117 | +## 6. 接口文档列表 |
| 167 | 118 | ||
| 168 | | 接口或能力 | 简述 | 链接 | | 119 | | 接口或能力 | 简述 | 链接 | |
| 169 | | --- | --- | --- | | 120 | | --- | --- | --- | |
| 170 | -| `awq` 处理器 | 用于执行激活感知权重量化的 Processor 配置 | [AWQ 词条](./term_awq_smooth.md) | | 121 | +| awq 配置说明 | 字段类型、默认值、合法取值与完整配置约束。 | 《[awq 配置说明](../../../api_reference/config/processor/awq.md)》 | |
| 171 | -| `AWQInterface` | 模型适配器需实现的激活感知量化接口 | [AWQ 词条](./term_awq_smooth.md) | | 122 | +| modelslim_v1 配置说明 | 需要继续探索 runner、prior、save、dataset 等任务级高级配置时查阅。 | 《[modelslim_v1 配置说明](../../../api_reference/config/task/modelslim_v1.md)》 | |
| @@ -1,16 +1,14 @@ | |||
| 1 | -# Ceil_X 自适应除数 MXFP4 量化算法词条 | 1 | +# Ceil_X 自适应除数 MXFP4 量化算法 量化术语百科词条 |
| 2 | 2 | ||
| 3 | -> **词条类别**：量化算法 | 3 | +> **词条类别**：[量化算法](../README.md#2-量化算法)<br> |
| 4 | -> **英文名称**：Ceil_X | 4 | +> **英文名称**：ceil_x<br> |
| 5 | -> **英文缩写**：Ceil_X | 5 | +> **应用领域**：MXFP4 权重量化、低比特量化精度优化<br> |
| 6 | -> **应用领域**：MXFP4 权重量化、低比特量化精度优化 | ||
| 7 | -> **msModelSlim 实现**：`msmodelslim/core/quantizer/impl/ceil_x.py` | ||
| 8 | 6 | ||
| 9 | --- | 7 | --- |
| 10 | 8 | ||
| 11 | ## 1. 概述 | 9 | ## 1. 概述 |
| 12 | 10 | ||
| 13 | -Ceil_X 是一种针对 MXFP4 per-block 权重量化的精度优化算法。它通过引入可配置除数 $c$ 配合 `ceil` 操作重新设计 shared exponent 的计算方式，将缩放后数值范围压缩至 MXFP4 的可表示区间内，减少大值截断，提升量化精度。其核心特征是：ceil + 可配置除数、可选全局 MSE 搜索最优除数、零配置开箱即用，是 [MinMax](../minmax/term_minmax.md) MXFP4 量化的截断抑制优化。 | 11 | +Ceil_X 是一种面向 MXFP4 per-block 权重量化的尺度优化算法。它通过 `ceil` 与可配置除数组合调整 shared exponent，使块内大值更少因缩放不足而被截断；核心特征是块级共享指数、可调除数和可选误差搜索，适合在 MXFP4 低比特权重量化中改善大值截断带来的精度损失。 |
| 14 | 12 | ||
| 15 | --- | 13 | --- |
| 16 | 14 | ||
| @@ -18,15 +16,21 @@ Ceil_X 是一种针对 MXFP4 per-block 权重量化的精度优化算法。它 | |||
| 18 | 16 | ||
| 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 的可表示区间内。 | 17 | 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 | 18 | ||
| 21 | ---- | 19 | +从量化流程中的定位看，该算法解决的是“如何把连续浮点值映射到受限数值集合，同时尽量保留模型输出”的问题。与只按极值直接计算尺度的基础方法相比，它通常会利用更细的统计信息、优化目标或结构约束来控制误差，因此更适合对精度有明确要求的量化场景。 |
| 22 | 20 | ||
| 23 | -## 3. 原理 | 21 | +### 2.1 核心思想 |
| 24 | 22 | ||
| 25 | -### 1. 核心思想 | 23 | +Ceil_X 的核心思想是“用向上取整的共享指数优先保证动态范围，再用除数 $c$ 调整范围与分辨率的平衡”。对每个 block，根据 $\lceil\log_2(\max|x|/c)\rceil$ 选择 power-of-two shared scale。相较直接向下取整指数，ceil 候选为大值预留更多表示空间；参数 $c$ 则移动指数跳变边界，使算法能够在减少饱和和保持较细量化步长之间折中。 |
| 26 | 24 | ||
| 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$。 | 25 | +ceil 的优势是显著降低最大值因 shared exponent 过小而发生的溢出/截断风险，特别适用于 FP4 高端码点有限、饱和误差昂贵的块。 |
| 28 | 26 | ||
| 29 | -### 2. 数学描述 | 27 | +### 2.2 工作机制 |
| 28 | + | ||
| 29 | +MXFP4 这类块浮点格式通常让一组元素共享一个 2 的幂尺度（shared exponent）。给定块内最大绝对值后，连续理想尺度往往落在两个相邻的 2 的幂之间；选择较小指数可以得到更细的步长，但可能使最大元素超出可表示范围，选择较大指数则有更大裕量但会牺牲分辨率。Ceil_X 通过向上取整 shared exponent，优先保证块内大值有足够表示裕量。 | ||
| 30 | + | ||
| 31 | +参数 $c$ 用来移动“何时需要跳到下一个指数”的边界。把最大值先除以 $c$ 再取 $\lceil\log_2\rceil$，等价于控制缩放后最大值应落入哪个目标区间。较大的 $c$ 通常倾向于保留更小的 shared exponent、获得更细步长，但饱和风险增加；较小的 $c$ 更保守。若启用搜索，则对候选 $c$ 做真实 QDQ，并用累计 MSE 选择全局折中点。 | ||
| 32 | + | ||
| 33 | +### 2.3 数学描述 | ||
| 30 | 34 | ||
| 31 | 传统 floor 缩放： | 35 | 传统 floor 缩放： |
| 32 | 36 | ||
| @@ -42,7 +46,7 @@ $$ | |||
| 42 | 46 | ||
| 43 | - $s$：shared exponent | 47 | - $s$：shared exponent |
| 44 | - $\max(|x|)$：block 内权重绝对值的最大值 | 48 | - $\max(|x|)$：block 内权重绝对值的最大值 |
| 45 | -- $c$：可配置除数（`ceil_x_value`，默认 $7.25$） | 49 | +- $c$：控制 shared exponent 跳变边界的正除数。 |
| 46 | - $\epsilon$：数值稳定项，$\epsilon = 9.6 \times 10^{-7}$ | 50 | - $\epsilon$：数值稳定项，$\epsilon = 9.6 \times 10^{-7}$ |
| 47 | - $e_{\text{max}}$：指数偏置，MXFP4 E4M2 格式下 $e_{\text{max}} = 2^{e_{\text{bits}}-1} = 2$ | 51 | - $e_{\text{max}}$：指数偏置，MXFP4 E4M2 格式下 $e_{\text{max}} = 2^{e_{\text{bits}}-1} = 2$ |
| 48 | 52 | ||
| @@ -52,7 +56,7 @@ $$ | |||
| 52 | \frac{\max(|x|)}{2^s} = \frac{\max(|x|)}{2^{\operatorname{ceil}(\log_2(\max(|x|)/c))}} \in \left(\frac{c}{2}, c\right] | 56 | \frac{\max(|x|)}{2^s} = \frac{\max(|x|)}{2^{\operatorname{ceil}(\log_2(\max(|x|)/c))}} \in \left(\frac{c}{2}, c\right] |
| 53 | $$ | 57 | $$ |
| 54 | 58 | ||
| 55 | -默认 $c = 7.25$ 时，缩放后数值范围为 $(3.625, 7.25]$，相比传统方法的 $[4, 8)$：下界降低、截断比例显著减小。 | 59 | +一般地，缩放后 block 最大值被约束在 $(c/2,c]$ 的数量级区间内。$c$ 改变时，shared exponent 只会在跨越 2 的幂边界时离散跳变，因此误差关于 $c$ 呈分段变化。 |
| 56 | 60 | ||
| 57 | 可选的自适应搜索： | 61 | 可选的自适应搜索： |
| 58 | 62 | ||
| @@ -61,105 +65,46 @@ c^* = \arg\min_{c \in [c_{\min}, c_{\max}]} \sum_{\text{blocks}} \|x - \hat{x}(c | |||
| 61 | $$ | 65 | $$ |
| 62 | 66 | ||
| 63 | - $c^*$：搜索得到的最优除数 | 67 | - $c^*$：搜索得到的最优除数 |
| 64 | -- $c_{\min}$、$c_{\max}$：搜索范围（默认 $[6.0, 12.0]$） | 68 | +- $c_{\min}$、$c_{\max}$：候选除数的搜索边界。 |
| 65 | - $\hat{x}(c)$：使用除数 $c$ 量化-反量化后的值 | 69 | - $\hat{x}(c)$：使用除数 $c$ 量化-反量化后的值 |
| 66 | 70 | ||
| 67 | -### 3. 关键性质 | 71 | +若 shared exponent 为 $s$，把归一化块记为 $u=x/2^s$，则后续 MXFP4 编码可抽象为 $\hat x=2^s\,\mathcal F(u)$，其中 $\mathcal F$ 表示低比特浮点格点投影。于是块误差为： |
| 72 | + | ||
| 73 | +$$ | ||
| 74 | +E(s)=\sum_i\left(x_i-2^s\mathcal F(x_i/2^s)\right)^2. | ||
| 75 | +$$ | ||
| 76 | + | ||
| 77 | +Ceil_X 并不是直接连续优化 $E(s)$，而是通过 $c$ 控制整数指数 $s(c)$。当 $s(c)$ 不变时 $E$ 完全不变；当 $s(c)$ 跨越相邻指数时，整个块同时切换到新的格点尺度。 | ||
| 78 | + | ||
| 79 | +### 2.4 关键性质 | ||
| 68 | 80 | ||
| 69 | - **ceil 缩放**：使用 ceil 操作收紧缩放范围，避免大值截断。 | 81 | - **ceil 缩放**：使用 ceil 操作收紧缩放范围，避免大值截断。 |
| 70 | -- **可配置除数**：`ceil_x_value` 控制缩放收紧程度，默认 $7.25$。 | 82 | +- **可调指数边界**：除数 $c$ 控制何时切换到更大的 shared exponent。 |
| 71 | - **自适应搜索**：可选启用全局 MSE 搜索最优除数 $c$。 | 83 | - **自适应搜索**：可选启用全局 MSE 搜索最优除数 $c$。 |
| 72 | -- **零配置可用**：不启用搜索时无额外超参，开箱即用。 | 84 | +- **范围/分辨率权衡**：ceil 提供更大动态范围裕量，但指数上移会同步增大量化步长。 |
| 73 | 85 | ||
| 74 | ---- | 86 | +从误差与适用边界看，全局搜索得到的 $c$ 是跨许多 block 的平均最优，不保证每个 block 都最优，这也是它与逐块 MSE_Round 的重要差异。 |
| 75 | 87 | ||
| 76 | -## 4. 流程示意 | 88 | +### 2.5 适用场景 |
| 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 | 89 | ||
| 144 | - 对 mxFP4 量化精度有更高要求的场景。 | 90 | - 对 mxFP4 量化精度有更高要求的场景。 |
| 145 | - 权重分布范围较大、floor 缩放导致步长过粗或大值截断的模型层。 | 91 | - 权重分布范围较大、floor 缩放导致步长过粗或大值截断的模型层。 |
| 146 | 92 | ||
| 147 | -### 2. 使用限制 | 93 | +更具体地说，是否适用主要取决于目标位宽、模型结构和部署后端三点。若目标部署链已经明确支持该算法对应的量化格式，并且校准数据能够覆盖主要业务分布，通常可以优先从该算法的推荐配置建立基线，再根据精度结果决定是否增加更复杂的优化。 |
| 94 | + | ||
| 95 | +### 2.6 使用限制 | ||
| 148 | 96 | ||
| 149 | - 仅支持 mxFP4 格式的 per_block 对称量化。 | 97 | - 仅支持 mxFP4 格式的 per_block 对称量化。 |
| 150 | - 启用 `enable_search` 时增加若干次前向量化评估，计算开销增大。 | 98 | - 启用 `enable_search` 时增加若干次前向量化评估，计算开销增大。 |
| 151 | - `search_max` 须大于 `search_min`。 | 99 | - `search_max` 须大于 `search_min`。 |
| 152 | 100 | ||
| 153 | ---- | 101 | +这些限制应在调参前确认，而不是等精度异常后再排查。尤其是数据类型、张量维度、分组大小和后端算子支持等硬约束，一旦不满足，继续调整算法参数通常无法解决问题；应先回到受支持的配置组合。 |
| 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 | 102 | ||
| 160 | --- | 103 | --- |
| 161 | 104 | ||
| 162 | -## 8. 关联词条 | 105 | +## 3. 关联词条 |
| 106 | + | ||
| 107 | +可以从“同类方法、前后处理关系和应用对象”三个方向理解本词条与其他算法的关系。下面的关联项既用于横向比较不同技术路线，也用于帮助定位该算法在完整量化方案中的位置。 | ||
| 163 | 108 | ||
| 164 | - [线性量化](../linear_quant/term_linear_quant.md)：应用对象，Ceil_X 作为线性量化的权重量化方法使用。 | 109 | - [线性量化](../linear_quant/term_linear_quant.md)：应用对象，Ceil_X 作为线性量化的权重量化方法使用。 |
| 165 | - [FouroverSix](../fouroversix/term_fouroversix.md)：同类算法，同为 MXFP4 格式的缩放策略优化算法。 | 110 | - [FouroverSix](../fouroversix/term_fouroversix.md)：同类算法，同为 MXFP4 格式的缩放策略优化算法。 |
| @@ -168,6 +113,8 @@ spec: | |||
| 168 | 113 | ||
| 169 | --- | 114 | --- |
| 170 | 115 | ||
| 171 | -## 9. 参考资料 | 116 | +## 4. 参考文档 |
| 172 | 117 | ||
| 173 | -1. 《Ceil_X 使用指南》([./usage_ceil_x.md](./usage_ceil_x.md)) | 118 | +参考文档优先列出算法原始论文或权威出处，并补充仓库内对应使用指南。需要进一步理解参数选择时，可先阅读使用指南，再回到原论文核对算法假设和推导。 |
| 119 | + | ||
| 120 | +1. 《[Ceil_X 参数配置流程指南](./usage_ceil_x.md)》 | ||
| @@ -1,63 +1,49 @@ | |||
| 1 | -# Ceil_X 使用指南 | 1 | +# Ceil_X 参数配置流程指南 |
| 2 | 2 | ||
| 3 | ## 1. 适用范围 | 3 | ## 1. 适用范围 |
| 4 | 4 | ||
| 5 | -本流程适用于在 msModelSlim 中配置和使用 Ceil_X 自适应除数 MXFP4 量化算法。Ceil_X 作为 `linear_quant` 处理器的权重量化方法，通过 ceil + 可配置除数优化 shared exponent，减少大值截断，提升 mxFP4 权重量化精度。 | 5 | +Ceil_X 自适应除数 MXFP4 量化算法。Ceil_X 作为 `linear_quant` 处理器的权重量化方法，通过 ceil + 可配置除数优化 shared exponent，减少大值截断，提升 mxFP4 权重量化精度。 |
| 6 | 6 | ||
| 7 | -适用角色：算法工程师、模型部署工程师 | 7 | +本指南面向首次配置 Ceil_X 的用户，重点不是展开完整执行命令，而是说明推荐配置为什么适合作为起点、哪些参数真正需要调，以及出现精度或资源问题时应优先改哪一项。这类算法通常直接影响量化尺度、舍入方式、量化粒度或低比特表示，因此参数选择会同时影响精度、压缩率以及部署兼容性。第一次使用时建议先固定目标位宽、校准集和评测方式，只采用本指南给出的推荐起点；确认基线稳定后，再围绕真正影响算法行为的参数逐项调整。 |
| 8 | 8 | ||
| 9 | -适用场景： | 9 | +如果目标模型已经有完整且已验证的量化配方，应优先复用该配方；若当前算法与目标模型结构、数值格式或部署后端不兼容，不应通过增大搜索强度或扩大作用范围来绕过支持约束。 |
| 10 | 10 | ||
| 11 | -- 对 mxFP4 量化精度有更高要求的场景。 | 11 | +## 2. 输入和交付件 |
| 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 | 12 | ||
| 32 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | | 13 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | |
| 33 | | --- | --- | --- | --- | --- | | 14 | | --- | --- | --- | --- | --- | |
| 34 | -| 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被目标 Transformers 版本加载 | | 15 | +| 输入 | 目标模型与量化目标 | 待量化模型及部署/评测方案 | 明确目标数值格式或位宽、作用模块、精度/性能目标以及部署约束 | 能说明为什么选择本算法以及它在整体量化方案中的位置 | |
| 35 | -| 输入 | 量化 YAML 配置文件 | 用户编写 | 符合 msModelSlim YAML 规范，含 `method: "ceil_x"` 权重量化配置 | 可通过工具 `--config_path` 参数加载 | | 16 | +| 输入 | 配置约束与实践基线 | 本算法配置说明、目标模型已有 `lab_practice` 配方（如有） | 字段名、支持组合、作用范围和模型适配与当前版本一致 | 推荐起点能够追溯到当前配置定义或已验证实践 | |
| 36 | -| 交付件 | 量化权重目录 | `--save_path` 指定路径 | 含 `quant_model_description.json` 及 `*.safetensors`，已应用 Ceil_X 量化 | 推理冒烟通过 | | 17 | +| 输入 | 校准数据（算法需要时） | 任务 `dataset`、校准集或模型实践配方 | 数据应能代表真实输入分布；多阶段算法尽量保持各阶段数据分布一致 | 能被当前量化流程正常读取，并覆盖主要输入形态 | |
| 18 | +| 交付件 | Ceil_X 参数配置方案 | 用户量化 YAML 或任务配置 | 参数取值合法、作用范围明确；关键参数说明选择依据 | 可作为后续量化流程的算法配置输入，并可复现本指南中的基线选择 | | ||
| 37 | 19 | ||
| 38 | -## 4. 流程总览 | 20 | +## 3. 流程总览 |
| 21 | + | ||
| 22 | +入门时建议先用一组稳定配置建立基线，再围绕影响最大的参数做单变量调整。下面的流程强调“先选参数、再看效果”，不展开量化命令本身。 | ||
| 39 | 23 | ||
| 40 | ```mermaid | 24 | ```mermaid |
| 41 | flowchart LR | 25 | flowchart LR |
| 42 | - A[编写 YAML 配置] --> B[执行量化命令] | 26 | + A[确定 MXFP4 per-block 方案] --> B[选择固定除数或搜索模式] |
| 43 | - B --> C[计算 ceil_x 指数] | 27 | + B[选择固定除数或搜索模式] --> C[计算 shared exponent] |
| 44 | - C --> D[量化并部署] | 28 | + C[计算 shared exponent] --> D[量化权重] |
| 45 | - D --> E[验证量化结果] | 29 | + D[量化权重] --> E[对比误差] |
| 46 | ``` | 30 | ``` |
| 47 | 31 | ||
| 48 | -## 5. 操作步骤 | 32 | +实际使用时建议把流程理解为“建立基线—观察结果—单变量调整—再次验证”的闭环。流程图中的前几个节点用于固定量化对象、统计信息或初始参数，后几个节点用于应用算法并检查结果；如果效果不理想，应优先回到最近一次修改的参数，而不是同时更换位宽、粒度、作用范围和算法强度。这样可以明确每次变化的因果关系，也便于把有效配置沉淀为后续模型配方。 |
| 49 | 33 | ||
| 50 | -### 步骤 1：编写 YAML 配置文件 | 34 | +## 4. 操作步骤 |
| 51 | 35 | ||
| 52 | -**目标**：编写包含 Ceil_X 权重量化配置的 YAML 文件。 | 36 | +### 步骤 1：确认目标与约束 |
| 37 | + | ||
| 38 | +**操作**：先固定目标模型、最终量化格式/位宽、作用对象和评测基线，再确认当前版本支持的参数组合。目标模型已有 `lab_practice` 配方时，优先把该配方作为实践基线；没有模型专用配方时，再使用本指南给出的通用推荐起点。若算法依赖校准统计或优化数据，还应在调参前固定代表性数据，避免把数据分布变化误判为参数收益。 | ||
| 39 | + | ||
| 40 | +**输出**：一份明确的配置目标：目标位宽/格式、处理范围、校准条件、评测基线和部署约束。 | ||
| 41 | + | ||
| 42 | +### 步骤 2：建立推荐基线 | ||
| 53 | 43 | ||
| 54 | **操作**： | 44 | **操作**： |
| 55 | 45 | ||
| 56 | -1. 在 `spec.process` 下配置 `linear_quant` 处理器。 | 46 | +下面配置用于建立**第一版可比较基线**。如果目标模型已有 `lab_practice` 配方，优先使用已验证配方，再参考本节理解每个参数为什么这样选。 |
| 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 | 47 | ||
| 62 | ```yaml | 48 | ```yaml |
| 63 | spec: | 49 | spec: |
| @@ -77,93 +63,60 @@ spec: | |||
| 77 | search_step: 0.25 # 搜索步长 | 63 | search_step: 0.25 # 搜索步长 |
| 78 | ``` | 64 | ``` |
| 79 | 65 | ||
| 80 | -YAML 配置字段详解如下： | 66 | +上面的推荐值用于建立第一版可复现基线，其中最值得关注的配置包括 `scope`, `dtype`, `symmetric`, `method`。推荐值并不表示所有模型都只能使用该组合，而是优先选择仓库默认值、已验证实践或较稳健的中间取值，以降低第一次使用时同时遇到精度和兼容性问题的概率。如果目标模型已经有 `lab_practice` 配方，应优先复用该配方；只有在基线精度、显存或吞吐不满足目标时，再按照下一节的参数说明逐项调整。 |
| 81 | 67 | ||
| 82 | -| 字段名 | 作用 | 说明 | | 68 | +**输出**：一份可复现的推荐基线配置，后续所有参数调整均以此为比较对象。 |
| 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 | 69 | ||
| 94 | -**输出**：YAML 配置文件 `${CONFIG_PATH}`。 | 70 | +### 步骤 3：选择并调整参数 |
| 95 | - | ||
| 96 | -### 步骤 2：执行量化命令 | ||
| 97 | - | ||
| 98 | -**目标**：使用上一步编写的 YAML 配置文件启动量化流程。 | ||
| 99 | 71 | ||
| 100 | **操作**： | 72 | **操作**： |
| 101 | 73 | ||
| 102 | -```bash | 74 | +参数选择建议按三个层次理解：首先确认 `dtype/scope/method` 等**算法支持约束**，这类字段不是任意可调；其次确定 `include/exclude`、子图类型等**作用范围**；最后再调整会改变误差与开销的数值参数。下面的推荐值区分了代码默认值、仓库 `lab_practice` 中已验证的实践值和适合首次使用的推荐起点。如果目标模型已有实践配置，优先沿用实践配置，再根据本节说明做单变量调整。 |
| 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 | 75 | ||
| 112 | -参数说明： | 76 | +| 配置项 | 含义（原理） | 推荐配置 | 选择与调整建议 | |
| 77 | +| --- | --- | --- | --- | | ||
| 78 | +| `scope` | 当前 Ceil-X 量化器只注册为 MXFP4 `per_block` 权重量化。分块共享指数是算法定义的一部分。 | 固定 `per_block`。 | 需要其他粒度时应换量化器，而不是修改该字段。 | | ||
| 79 | +| `dtype` | 当前只支持 `mxfp4`。MXFP4 的块大小由 dtype 的 MX 格式定义。 | 固定 `mxfp4`。 | 目标后端不是 MXFP4 时不要使用 Ceil-X。 | | ||
| 80 | +| `symmetric` | 当前注册组合为对称量化。 | 固定 `true`。 | 不要改为非对称；当前没有对应注册实现。 | | ||
| 81 | +| `method` | 选择 Ceil-X shared exponent 策略。 | 固定 `ceil_x`。 | 切换 method 就是切换算法。 | | ||
| 82 | +| `ext.axes` | 指定沿哪些张量维度做 MX block reshape/共享指数，默认 `-1`（最后一维）。轴选择会改变哪些元素共享一个 block，因此直接影响尺度统计和导出布局。 | 线性权重通常保持默认 `-1`；只有模型/后端布局明确要求其他轴时才修改。 | 不要把 axes 当精度微调参数。改轴之前确认目标权重维度、block 布局和后端一致；否则即使离线误差降低，也可能无法正确部署。 | | ||
| 83 | +| `ext.ceil_x_value` | Ceil-X 中 shared exponent 计算的除数，范围 `[6,12]`，默认 `7.25`。源码关系为 c 越大，shared exponent 越小、量化步长更细，但同时更接近表示上限、溢出风险更高。 | 不搜索时用默认 `7.25`。 | 如果固定值误差不理想，优先开启自动 MSE 搜索，而不是凭经验大幅手调。手调时应在合法范围内小步变化并同时观察溢出/饱和与重构误差。 | | ||
| 84 | +| `ext.enable_search` | 是否在给定区间内枚举 `ceil_x_value`，用权重重构 MSE 选择最优候选。 | 快速/稳定配方用 `false`；独立模型精度优先时可设 `true`。 | 固定 7.25 已满足精度就无需搜索；不同层分布差异明显或固定值损失偏高时开启。开启后 `ceil_x_value` 只是初始/配置值，不再是主要手调旋钮。 | | ||
| 85 | +| `ext.search_min` / `ext.search_max` | 自动搜索区间，默认 `[6,12]`，且上下界都必须在算法允许范围内、上界大于下界。 | 保持 `6.0` / `12.0`。 | 只有观察到最佳候选长期落在边界附近时才考虑收窄/调整区间；由于算法本身合法范围就是 `[6,12]`，不能向外无限扩。 | | ||
| 86 | +| `ext.search_step` | 候选步长，默认 `0.25`。候选数约由区间宽度/步长决定，步长越小越细但耗时越高。 | 先 `0.25`。 | 若最佳点附近 MSE 曲线很陡且精度对候选敏感，可减小步长；若只是快速筛选可适度增大。先固定搜索范围，再改变步长，便于判断收益。 | | ||
| 113 | 87 | ||
| 114 | -| 参数 | 必选 | 说明 | | 88 | +### 参数组合与选择顺序 |
| 115 | -| --- | --- | --- | | ||
| 116 | -| `model_path` | 是 | 浮点模型权重路径 | | ||
| 117 | -| `save_path` | 是 | 量化权重保存路径 | | ||
| 118 | -| `device` | 否 | 量化设备，默认 `npu` | | ||
| 119 | -| `model_type` | 是 | 模型名称，与支持矩阵一致 | | ||
| 120 | -| `config_path` | 是 | 步骤 1 编写的 YAML 配置路径 | | ||
| 121 | -| `trust_remote_code` | 否 | 是否信任远程代码，默认 `False` | | ||
| 122 | 89 | ||
| 123 | -执行流程说明： | 90 | +1. **先锁定部署目标与支持组合**：先确定最终位宽/数值格式，再确认当前量化器实际注册了对应的 `dtype + scope + symmetric + method` 组合；不要为了追求某个参数值而越过支持约束。 |
| 91 | +2. **再固定作用范围**：使用已有模型配方时，先复用其 `include/exclude` 或子图类型；没有配方时先建立覆盖范围明确的基线，确认算法确实作用到了预期模块。 | ||
| 92 | +3. **最后只调一个主要旋钮**：数值搜索步数、平滑强度、分组大小等一次只改一项，并保持同一校准集和评测集。若调整后没有稳定收益，回到上一个基线，而不是继续叠加多个变化。 | ||
| 124 | 93 | ||
| 125 | -1. 工具加载 YAML 配置，解析 `linear_quant` 处理器与 Ceil_X 配置。 | 94 | +Ceil-X 中真正可调的是 `ceil_x_value` 或其搜索配置；`dtype/scope/symmetric/method/axes` 更多属于格式与布局约束。精度不足时先用默认范围开启搜索，再考虑改变搜索粒度。 |
| 126 | -2. 量化器计算每个 block 的 ceil_x shared exponent。 | ||
| 127 | -3. 启用 `enable_search` 时搜索最优除数 `ceil_x_value`。 | ||
| 128 | -4. 保存量化权重。 | ||
| 129 | 95 | ||
| 130 | -**输出**：量化权重目录 `${SAVE_PATH}`，包含量化描述文件与权重分片。 | 96 | +**输出**：一份完成单变量调整的算法参数方案，关键字段均有明确的选择依据和调整方向。 |
| 131 | 97 | ||
| 132 | -### 步骤 3：验证量化结果 | 98 | +### 步骤 4：根据结果收敛参数方案 |
| 133 | - | ||
| 134 | -**目标**：确认量化权重文件完整且可加载。 | ||
| 135 | 99 | ||
| 136 | **操作**： | 100 | **操作**： |
| 137 | 101 | ||
| 138 | -1. 检查输出目录是否包含 `quant_model_description.json` 文件。 | 102 | +调参时建议先记录一份完整基线，包括使用的数据集、量化范围、关键参数和端到端指标。每轮只改变一个变量，并把变化结果与基线直接比较；如果某项调整带来收益，再继续小步搜索其邻近取值。对于只有少数层或模块异常的情况，优先采用局部排除、局部回退或混合精度，而不是直接提高全模型精度配置，这通常更容易保留压缩和性能收益。 |
| 139 | -2. 检查日志确认量化流程正常完成。 | ||
| 140 | -3. 使用推理框架加载量化权重进行冒烟测试。 | ||
| 141 | 103 | ||
| 142 | -**输出**：量化权重验证通过。 | 104 | +- 固定 `7.25` 是低成本起点；只有固定值不满足精度时再开启搜索，可避免每次试验都支付搜索成本。 |
| 105 | +- **先跑推荐基线，再调单变量。** 不要同时修改位宽、粒度、算法参数和层范围，否则很难判断精度变化来自哪一项。 | ||
| 106 | +- **优先回退局部，而不是整体提高精度。** 如果只有少数层敏感，优先通过 `exclude` 或混合策略保留高精度，通常比整体升位宽更划算。 | ||
| 107 | +- **最终以模型实践配置和部署能力为准。** 入门推荐用于建立稳定起点；目标模型已有 `lab_practice` 配方时，应优先复用已验证组合。 | ||
| 143 | 108 | ||
| 144 | -## 6. 验收条件 | 109 | +**输出**：一份可进入后续量化流程的最终参数方案，并保留相对于推荐基线的调整记录。 |
| 145 | 110 | ||
| 146 | -- 量化权重目录包含 `quant_model_description.json` 及所有必需的 `*.safetensors` 分片文件。 | 111 | +## 5. 术语 |
| 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 | 112 | ||
| 158 | | 术语 | 简述 | 链接 | | 113 | | 术语 | 简述 | 链接 | |
| 159 | | --- | --- | --- | | 114 | | --- | --- | --- | |
| 160 | -| Ceil_X | 使用 ceil + 可配置除数优化 MXFP4 shared exponent 的算法 | [Ceil_X 词条](./term_ceil_x.md) | | 115 | +| Ceil_X 自适应除数 MXFP4 量化算法 | 说明该算法的定义、核心原理、关键性质、适用场景与限制。 | 《[Ceil_X 自适应除数 MXFP4 量化算法 量化术语百科词条](./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 | 116 | ||
| 164 | -## 9. 接口文档列表 | 117 | +## 6. 接口文档列表 |
| 165 | 118 | ||
| 166 | | 接口或能力 | 简述 | 链接 | | 119 | | 接口或能力 | 简述 | 链接 | |
| 167 | | --- | --- | --- | | 120 | | --- | --- | --- | |
| 168 | -| `linear_quant` 处理器 | 线性层量化处理器，通过 `method: "ceil_x"` 启用 Ceil_X | [线性量化词条](../linear_quant/term_linear_quant.md) | | 121 | +| linear_quant 配置说明 | 字段类型、默认值、合法取值与完整配置约束。 | 《[linear_quant 配置说明](../../../api_reference/config/processor/linear_quant.md)》 | |
| 169 | -| `MXWeightPerBlockCeilX` | Ceil_X 权重量化实现类 | [Ceil_X 词条](./term_ceil_x.md) | | 122 | +| modelslim_v1 配置说明 | 需要继续探索 runner、prior、save、dataset 等任务级高级配置时查阅。 | 《[modelslim_v1 配置说明](../../../api_reference/config/task/modelslim_v1.md)》 | |
| @@ -1,16 +1,14 @@ | |||
| 1 | -# DualScale 双尺度量化算法词条 | 1 | +# DualScale 双尺度量化算法 量化术语百科词条 |
| 2 | 2 | ||
| 3 | -> **词条类别**：量化算法 | 3 | +> **词条类别**：[量化算法](../README.md#2-量化算法)<br> |
| 4 | -> **英文名称**：DualScale | 4 | +> **英文名称**：dual_scale<br> |
| 5 | -> **英文缩写**：DualScale | 5 | +> **应用领域**：大语言模型量化压缩、低比特量化精度优化<br> |
| 6 | -> **应用领域**：大语言模型量化压缩、低比特量化精度优化 | ||
| 7 | -> **msModelSlim 实现**：`msmodelslim/core/quantizer/impl/dualscale.py` | ||
| 8 | 6 | ||
| 9 | --- | 7 | --- |
| 10 | 8 | ||
| 11 | ## 1. 概述 | 9 | ## 1. 概述 |
| 12 | 10 | ||
| 13 | -DualScale 是一种面向 W4A4 低比特量化场景的双尺度量化方案。它通过两级粒度递进的缩放因子，在保持硬件高效性的同时缓解激活异常通道（outlier channels）对量化精度的影响。其核心特征是：外层大块缩放 + 内层 block 量化的两级结构、权重静态量化存储、激活 data-free 伪量化，主要面向 Qwen3 稠密系列模型，作为 [线性量化](../linear_quant/term_linear_quant.md) 的量化方法使用。 | 11 | +DualScale 是一种面向 W4A4 等低比特场景的双尺度量化方法。它在较粗粒度尺度之外再引入更细粒度缩放，以减弱异常通道对同一量化区间的支配；核心特征是两级尺度协同、权重与激活可采用不同缩放路径，并在保持硬件友好性的同时提高低比特表示对局部动态范围差异的适应能力。 |
| 14 | 12 | ||
| 15 | --- | 13 | --- |
| 16 | 14 | ||
| @@ -18,15 +16,21 @@ DualScale 是一种面向 W4A4 低比特量化场景的双尺度量化方案。 | |||
| 18 | 16 | ||
| 19 | 传统的分组量化通常采用单尺度（single-scale）策略：每组 K 维元素共享一个缩放因子。然而，激活值中存在结构化的异常通道——某些通道的值平均比其他通道高出数个数量级，单尺度量化难以同时精准表示这些差异巨大的数值范围，导致精度损失。DualScale 通过两级粒度递进的缩放因子，先按大块计算外层尺度吸收异常通道差异，再在内层 block 完成低比特量化。 | 17 | 传统的分组量化通常采用单尺度（single-scale）策略：每组 K 维元素共享一个缩放因子。然而，激活值中存在结构化的异常通道——某些通道的值平均比其他通道高出数个数量级，单尺度量化难以同时精准表示这些差异巨大的数值范围，导致精度损失。DualScale 通过两级粒度递进的缩放因子，先按大块计算外层尺度吸收异常通道差异，再在内层 block 完成低比特量化。 |
| 20 | 18 | ||
| 21 | ---- | 19 | +从量化流程中的定位看，该算法解决的是“如何把连续浮点值映射到受限数值集合，同时尽量保留模型输出”的问题。与只按极值直接计算尺度的基础方法相比，它通常会利用更细的统计信息、优化目标或结构约束来控制误差，因此更适合对精度有明确要求的量化场景。 |
| 22 | 20 | ||
| 23 | -## 3. 原理 | 21 | +### 2.1 核心思想 |
| 24 | 22 | ||
| 25 | -### 1. 核心思想 | 23 | +DualScale 的核心思想是“两级缩放递进吸收分布差异”：先在较大的粗粒度 block 上估计外层尺度并完成幅值归一化，再在更小的内层 block 上使用 MXFP4 shared scale 表示局部变化。这样，外层尺度负责块间数量级差异，内层尺度负责块内细节，避免一个低比特 shared exponent 同时承担过大的全局动态范围。 |
| 26 | 24 | ||
| 27 | -DualScale 的核心思想是“两级缩放递进吸收分布差异”：外层按 `dual_block_size` 划分大块，计算每个大块的最大绝对值得到外层尺度 $S_{dual}$，将输入除以该尺度；内层再按 `inner_block_size` 划分，执行 mxFP4 量化-反量化。通过先缩放再量化的两级结构，异常通道的差异被外层尺度吸收。 | 25 | +两级尺度有效的原因是把“动态范围表示能力”分层分配。 |
| 28 | 26 | ||
| 29 | -### 2. 数学描述 | 27 | +### 2.2 工作机制 |
| 28 | + | ||
| 29 | +单级块尺度要求一个尺度同时描述整个共享块的绝对量级与块内局部变化。当不同大块之间量级差异很大时，单一 shared exponent 往往需要在“覆盖最大块”和“给普通块足够分辨率”之间做困难折中。DualScale 把这两个问题拆开：外层尺度先负责消除较大范围的块间幅度差异，得到归一化张量；内层 MXFP4 尺度再负责描述归一化后的小块局部分布。 | ||
| 30 | + | ||
| 31 | +因此每个元素的有效反量化尺度可以理解为“外层尺度 × 内层共享尺度”。外层通常使用更大的 block，元数据较少，主要捕获粗粒度动态范围；内层 block 更小，负责精细适配局部峰值。两级分解让内层低比特格式不必独自承担跨越很大数量级的动态范围，从而提高有限指数/尾数码点的利用效率。 | ||
| 32 | + | ||
| 33 | +### 2.3 数学描述 | ||
| 30 | 34 | ||
| 31 | 激活的外层缩放（Dual Scale）： | 35 | 激活的外层缩放（Dual Scale）： |
| 32 | 36 | ||
| @@ -64,99 +68,42 @@ $$ | |||
| 64 | \text{Output} = X_{q\_dq} \cdot W_{q\_dq}^T + \text{bias} | 68 | \text{Output} = X_{q\_dq} \cdot W_{q\_dq}^T + \text{bias} |
| 65 | $$ | 69 | $$ |
| 66 | 70 | ||
| 67 | -### 3. 关键性质 | 71 | +对元素 $x_i$，令其所属外层块尺度为 $S_o(b(i))$、内层块尺度为 $S_i(g(i))$，则有效反量化关系可概括为： |
| 72 | + | ||
| 73 | +$$ | ||
| 74 | +\hat x_i=S_o(b(i))\,S_i(g(i))\,q_i. | ||
| 75 | +$$ | ||
| 76 | + | ||
| 77 | +因此有效步长也是两个尺度的乘积。若外层归一化把 $|x|$ 压到相近数量级，则 $S_i$ 的动态范围需求变小，低比特 shared-scale 的离散误差也随之降低。反过来，外层尺度自身的量化/存储精度也会成为额外误差源。 | ||
| 78 | + | ||
| 79 | +### 2.4 关键性质 | ||
| 68 | 80 | ||
| 69 | - **两级缩放**：外层大块缩放 + 内层 block 量化的递进结构。 | 81 | - **两级缩放**：外层大块缩放 + 内层 block 量化的递进结构。 |
| 70 | - **异常通道吸收**：外层尺度吸收异常通道的差异，缓解单尺度量化的精度损失。 | 82 | - **异常通道吸收**：外层尺度吸收异常通道的差异，缓解单尺度量化的精度损失。 |
| 71 | -- **权重静态存储**：权重在初始化时完成量化存储，前向仅做反量化。 | 83 | +- **层级动态范围分解**：粗尺度描述块间幅值，细尺度描述块内局部分布。 |
| 72 | -- **激活 data-free**：激活量化器 `is_data_free` 返回 `True`，实际量化在推理阶段由硬件完成。 | ||
| 73 | 84 | ||
| 74 | ---- | 85 | +代价是额外尺度元数据和更多层级的缩放/反缩放。若 dual block 太大，外层仍可能被少数极值支配；太小则尺度数量和访存开销上升。 |
| 75 | 86 | ||
| 76 | -## 4. 流程示意 | 87 | +### 2.5 适用场景 |
| 77 | - | ||
| 78 | -> 以下为本算法在 msModelSlim 中的简化流程概览。 | ||
| 79 | - | ||
| 80 | -```mermaid | ||
| 81 | -flowchart LR | ||
| 82 | - A[外层大块缩放] --> B[内层 block 量化] | ||
| 83 | - B --> C[外层反量化] | ||
| 84 | - C --> D[矩阵乘法] | ||
| 85 | -``` | ||
| 86 | - | ||
| 87 | ---- | ||
| 88 | - | ||
| 89 | -## 5. 在 msModelSlim 中的实现 | ||
| 90 | - | ||
| 91 | -### 1. 实现位置 | ||
| 92 | - | ||
| 93 | -算法在 `msmodelslim/core/quantizer/impl/dualscale.py` 中实现，包括权重量化器 `MXWeightDualScaleMinmax` 与激活量化器 `MXActDualScaleMinmax`，均通过 `QABCRegistry.multi_register` 注册，dispatch_key 为 `(qir.mxfp4_dual_scale_sym, "dualscale")`。 | ||
| 94 | - | ||
| 95 | -### 2. 处理流程 | ||
| 96 | - | ||
| 97 | -- **权重量化器**（`MXWeightDualScaleMinmax`）：在权重初始化阶段完成静态量化。`init_weight` 按 `axes` 与 `dual_block_size` 将权重重塑为块状，统计外层块最大值计算外层尺度，权重除以外层尺度后交由内层量化器进行 mxFP4 量化存储。`forward` 完成内层反量化、乘以 $S_{\text{dual\_w}}$ 恢复外层尺度。 | ||
| 98 | -- **激活量化器**（`MXActDualScaleMinmax`）：data-free 量化，`forward` 直接返回输入 `x`（实际量化在推理阶段由硬件完成）。 | ||
| 99 | - | ||
| 100 | -### 3. 配置示例 | ||
| 101 | - | ||
| 102 | -> 以下为最小可用的 YAML 配置片段。各字段的详细含义如下表所示。 | ||
| 103 | - | ||
| 104 | -```yaml | ||
| 105 | -spec: | ||
| 106 | - process: | ||
| 107 | - - type: "linear_quant" | ||
| 108 | - qconfig: | ||
| 109 | - act: | ||
| 110 | - scope: "dual_scale" | ||
| 111 | - dtype: "mxfp4" | ||
| 112 | - symmetric: True | ||
| 113 | - method: "dualscale" | ||
| 114 | - ext: | ||
| 115 | - dual_block_size: 512 | ||
| 116 | - weight: | ||
| 117 | - scope: "dual_scale" | ||
| 118 | - dtype: "mxfp4" | ||
| 119 | - symmetric: True | ||
| 120 | - method: "dualscale" | ||
| 121 | - ext: | ||
| 122 | - dual_block_size: 512 | ||
| 123 | -``` | ||
| 124 | - | ||
| 125 | -**字段说明**： | ||
| 126 | - | ||
| 127 | -| 字段名 | 作用 | 说明 | | ||
| 128 | -| --- | --- | --- | | ||
| 129 | -| scope | 量化范围 | 固定为 `"dual_scale"`（双尺度）。 | | ||
| 130 | -| dtype | 量化数据类型 | 固定为 `"mxfp4"`。 | | ||
| 131 | -| symmetric | 是否对称量化 | `true` 为对称，`false` 为非对称。 | | ||
| 132 | -| method | 量化方法 | 固定为 `"dualscale"`。 | | ||
| 133 | -| ext.dual_block_size | 外层大块大小 | 整数，如 `512`。 | | ||
| 134 | - | ||
| 135 | ---- | ||
| 136 | - | ||
| 137 | -## 6. 适用场景与限制 | ||
| 138 | - | ||
| 139 | -### 1. 适用场景 | ||
| 140 | 88 | ||
| 141 | - W4A4 等超低比特量化场景，需要保持较高模型精度的场景。 | 89 | - W4A4 等超低比特量化场景，需要保持较高模型精度的场景。 |
| 142 | - 激活值存在结构化异常通道的模型量化场景。 | 90 | - 激活值存在结构化异常通道的模型量化场景。 |
| 143 | 91 | ||
| 144 | -### 2. 使用限制 | 92 | +更具体地说，是否适用主要取决于目标位宽、模型结构和部署后端三点。若目标部署链已经明确支持该算法对应的量化格式，并且校准数据能够覆盖主要业务分布，通常可以优先从该算法的推荐配置建立基线，再根据精度结果决定是否增加更复杂的优化。 |
| 93 | + | ||
| 94 | +### 2.6 使用限制 | ||
| 145 | 95 | ||
| 146 | - 需要足够的校准数据或训练迭代次数来优化参数，量化时长相对较久。 | 96 | - 需要足够的校准数据或训练迭代次数来优化参数，量化时长相对较久。 |
| 147 | - 当前主要面向 Qwen3 稠密系列模型（如 Qwen3-8B/14B/32B），不保证可泛化到其他系列模型。 | 97 | - 当前主要面向 Qwen3 稠密系列模型（如 Qwen3-8B/14B/32B），不保证可泛化到其他系列模型。 |
| 148 | - 算法实现包含训练过程，对 NPU 显存有一定要求，仅支持 NPU 显存 ≥64G 的设备。 | 98 | - 算法实现包含训练过程，对 NPU 显存有一定要求，仅支持 NPU 显存 ≥64G 的设备。 |
| 149 | 99 | ||
| 150 | ---- | 100 | +这些限制应在调参前确认，而不是等精度异常后再排查。尤其是数据类型、张量维度、分组大小和后端算子支持等硬约束，一旦不满足，继续调整算法参数通常无法解决问题；应先回到受支持的配置组合。 |
| 151 | - | ||
| 152 | -## 7. 关联流程 | ||
| 153 | - | ||
| 154 | -- 《[一键量化 (V1)](../../../user_guide/usage_quick_quantization.md)》：可集成 DualScale 作为 W4A4 低比特量化方案。 | ||
| 155 | -- 《[量化精度调优指南](../../../user_guide/process_quantization_precision_tuning.md)》：精度不达标时可调整 DualScale 配置。 | ||
| 156 | 101 | ||
| 157 | --- | 102 | --- |
| 158 | 103 | ||
| 159 | -## 8. 关联词条 | 104 | +## 3. 关联词条 |
| 105 | + | ||
| 106 | +可以从“同类方法、前后处理关系和应用对象”三个方向理解本词条与其他算法的关系。下面的关联项既用于横向比较不同技术路线，也用于帮助定位该算法在完整量化方案中的位置。 | ||
| 160 | 107 | ||
| 161 | - [线性量化](../linear_quant/term_linear_quant.md)：应用对象，DualScale 作为线性量化的量化方法（`scope: "dual_scale"`）使用。 | 108 | - [线性量化](../linear_quant/term_linear_quant.md)：应用对象，DualScale 作为线性量化的量化方法（`scope: "dual_scale"`）使用。 |
| 162 | - [LAOS](../laos/term_laos.md)：同类算法，同为面向 Qwen3 稠密系列的 W4A4 量化方案。 | 109 | - [LAOS](../laos/term_laos.md)：同类算法，同为面向 Qwen3 稠密系列的 W4A4 量化方案。 |
| @@ -164,6 +111,8 @@ spec: | |||
| 164 | 111 | ||
| 165 | --- | 112 | --- |
| 166 | 113 | ||
| 167 | -## 9. 参考资料 | 114 | +## 4. 参考文档 |
| 168 | 115 | ||
| 169 | -1. 《DualScale 使用指南》([./usage_dual_scale.md](./usage_dual_scale.md)) | 116 | +参考文档优先列出算法原始论文或权威出处，并补充仓库内对应使用指南。需要进一步理解参数选择时，可先阅读使用指南，再回到原论文核对算法假设和推导。 |
| 117 | + | ||
| 118 | +1. 《[DualScale 参数配置流程指南](./usage_dual_scale.md)》 | ||
| @@ -1,66 +1,49 @@ | |||
| 1 | -# DualScale 使用指南 | 1 | +# DualScale 参数配置流程指南 |
| 2 | 2 | ||
| 3 | ## 1. 适用范围 | 3 | ## 1. 适用范围 |
| 4 | 4 | ||
| 5 | -本流程适用于在 msModelSlim 中配置和使用 DualScale 双尺度量化算法。DualScale 作为 `linear_quant` 处理器的量化方法，通过两级缩放递进结构缓解异常通道影响，用于 Qwen3 稠密系列模型的 W4A4 低比特量化。 | 5 | +DualScale 双尺度量化算法。DualScale 作为 `linear_quant` 处理器的量化方法，通过两级缩放递进结构缓解异常通道影响，用于 Qwen3 稠密系列模型的 W4A4 低比特量化。 |
| 6 | 6 | ||
| 7 | -适用角色：算法工程师、模型部署工程师 | 7 | +本指南面向首次配置 DualScale 的用户，重点不是展开完整执行命令，而是说明推荐配置为什么适合作为起点、哪些参数真正需要调，以及出现精度或资源问题时应优先改哪一项。这类算法通常直接影响量化尺度、舍入方式、量化粒度或低比特表示，因此参数选择会同时影响精度、压缩率以及部署兼容性。第一次使用时建议先固定目标位宽、校准集和评测方式，只采用本指南给出的推荐起点；确认基线稳定后，再围绕真正影响算法行为的参数逐项调整。 |
| 8 | 8 | ||
| 9 | -适用场景： | 9 | +如果目标模型已经有完整且已验证的量化配方，应优先复用该配方；若当前算法与目标模型结构、数值格式或部署后端不兼容，不应通过增大搜索强度或扩大作用范围来绕过支持约束。 |
| 10 | 10 | ||
| 11 | -- W4A4 等超低比特量化场景，需要保持较高模型精度的场景。 | 11 | +## 2. 输入和交付件 |
| 12 | -- 激活值存在结构化异常通道的模型量化场景。 | ||
| 13 | - | ||
| 14 | -不适用场景： | ||
| 15 | - | ||
| 16 | -- 非 Qwen3 稠密系列模型（不保证可泛化）。 | ||
| 17 | -- NPU 显存小于 64G 的设备（算法包含训练过程）。 | ||
| 18 | - | ||
| 19 | -## 2. 流程关系与前置条件 | ||
| 20 | - | ||
| 21 | -**上级流程**：模型适配与验证通过后，确定量化方案阶段。 | ||
| 22 | - | ||
| 23 | -**前置条件**： | ||
| 24 | - | ||
| 25 | -- 已安装兼容版本的 msModelSlim 工具（详见《[msModelSlim 工具安装指南](../../../install_guide/install_guide.md)》）。 | ||
| 26 | -- 已确认目标模型为 Qwen3 稠密系列（如 Qwen3-8B/14B/32B）。 | ||
| 27 | -- 已准备好足够的校准数据。 | ||
| 28 | -- 已确认 NPU 显存 ≥64G。 | ||
| 29 | - | ||
| 30 | -**后续操作**：量化流程执行 → 精度验证 → 部署上线或进入调优。 | ||
| 31 | - | ||
| 32 | -## 3. 输入和交付件 | ||
| 33 | 12 | ||
| 34 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | | 13 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | |
| 35 | | --- | --- | --- | --- | --- | | 14 | | --- | --- | --- | --- | --- | |
| 36 | -| 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被目标 Transformers 版本加载 | | 15 | +| 输入 | 目标模型与量化目标 | 待量化模型及部署/评测方案 | 明确目标数值格式或位宽、作用模块、精度/性能目标以及部署约束 | 能说明为什么选择本算法以及它在整体量化方案中的位置 | |
| 37 | -| 输入 | 校准数据集 | 工具默认或用户指定 | JSONL 格式，每条含文本 prompt | 可被工具加载并完成前向推理 | | 16 | +| 输入 | 配置约束与实践基线 | 本算法配置说明、目标模型已有 `lab_practice` 配方（如有） | 字段名、支持组合、作用范围和模型适配与当前版本一致 | 推荐起点能够追溯到当前配置定义或已验证实践 | |
| 38 | -| 输入 | 量化 YAML 配置文件 | 用户编写 | 符合 msModelSlim YAML 规范，含 `scope: "dual_scale"` 量化配置 | 可通过工具 `--config_path` 参数加载 | | 17 | +| 输入 | 校准数据（算法需要时） | 任务 `dataset`、校准集或模型实践配方 | 数据应能代表真实输入分布；多阶段算法尽量保持各阶段数据分布一致 | 能被当前量化流程正常读取，并覆盖主要输入形态 | |
| 39 | -| 交付件 | 量化权重目录 | `--save_path` 指定路径 | 含 `quant_model_description.json` 及 `*.safetensors`，已应用双尺度量化 | 推理冒烟通过 | | 18 | +| 交付件 | DualScale 参数配置方案 | 用户量化 YAML 或任务配置 | 参数取值合法、作用范围明确；关键参数说明选择依据 | 可作为后续量化流程的算法配置输入，并可复现本指南中的基线选择 | |
| 40 | 19 | ||
| 41 | -## 4. 流程总览 | 20 | +## 3. 流程总览 |
| 21 | + | ||
| 22 | +入门时建议先用一组稳定配置建立基线，再围绕影响最大的参数做单变量调整。下面的流程强调“先选参数、再看效果”，不展开量化命令本身。 | ||
| 42 | 23 | ||
| 43 | ```mermaid | 24 | ```mermaid |
| 44 | flowchart LR | 25 | flowchart LR |
| 45 | - A[编写 YAML 配置] --> B[执行量化命令] | 26 | + A[确定 MXFP4 双尺度方案] --> B[设置外层 block 大小] |
| 46 | - B --> C[外层缩放计算] | 27 | + B[设置外层 block 大小] --> C[计算两级尺度] |
| 47 | - C --> D[内层量化] | 28 | + C[计算两级尺度] --> D[量化激活与权重] |
| 48 | - D --> E[验证量化结果] | 29 | + D[量化激活与权重] --> E[对比误差] |
| 49 | ``` | 30 | ``` |
| 50 | 31 | ||
| 51 | -## 5. 操作步骤 | 32 | +实际使用时建议把流程理解为“建立基线—观察结果—单变量调整—再次验证”的闭环。流程图中的前几个节点用于固定量化对象、统计信息或初始参数，后几个节点用于应用算法并检查结果；如果效果不理想，应优先回到最近一次修改的参数，而不是同时更换位宽、粒度、作用范围和算法强度。这样可以明确每次变化的因果关系，也便于把有效配置沉淀为后续模型配方。 |
| 52 | 33 | ||
| 53 | -### 步骤 1：编写 YAML 配置文件 | 34 | +## 4. 操作步骤 |
| 54 | 35 | ||
| 55 | -**目标**：编写包含 DualScale 量化配置的 YAML 文件。 | 36 | +### 步骤 1：确认目标与约束 |
| 37 | + | ||
| 38 | +**操作**：先固定目标模型、最终量化格式/位宽、作用对象和评测基线，再确认当前版本支持的参数组合。目标模型已有 `lab_practice` 配方时，优先把该配方作为实践基线；没有模型专用配方时，再使用本指南给出的通用推荐起点。若算法依赖校准统计或优化数据，还应在调参前固定代表性数据，避免把数据分布变化误判为参数收益。 | ||
| 39 | + | ||
| 40 | +**输出**：一份明确的配置目标：目标位宽/格式、处理范围、校准条件、评测基线和部署约束。 | ||
| 41 | + | ||
| 42 | +### 步骤 2：建立推荐基线 | ||
| 56 | 43 | ||
| 57 | **操作**： | 44 | **操作**： |
| 58 | 45 | ||
| 59 | -1. 在 `spec.process` 下配置 `linear_quant` 处理器。 | 46 | +下面配置用于建立**第一版可比较基线**。如果目标模型已有 `lab_practice` 配方，优先使用已验证配方，再参考本节理解每个参数为什么这样选。 |
| 60 | -2. 在 `qconfig.act` 与 `qconfig.weight` 中设置 `scope: "dual_scale"`、`dtype: "mxfp4"`、`symmetric: True`、`method: "dualscale"`。 | ||
| 61 | -3. 在 `ext` 中配置 `dual_block_size`（外层大块大小）。 | ||
| 62 | - | ||
| 63 | -YAML 配置示例： | ||
| 64 | 47 | ||
| 65 | ```yaml | 48 | ```yaml |
| 66 | spec: | 49 | spec: |
| @@ -83,90 +66,56 @@ spec: | |||
| 83 | dual_block_size: 512 | 66 | dual_block_size: 512 |
| 84 | ``` | 67 | ``` |
| 85 | 68 | ||
| 86 | -YAML 配置字段详解如下： | 69 | +上面的推荐值用于建立第一版可复现基线，其中最值得关注的配置包括 `scope`, `dtype`, `symmetric`, `method`。推荐值并不表示所有模型都只能使用该组合，而是优先选择仓库默认值、已验证实践或较稳健的中间取值，以降低第一次使用时同时遇到精度和兼容性问题的概率。如果目标模型已经有 `lab_practice` 配方，应优先复用该配方；只有在基线精度、显存或吞吐不满足目标时，再按照下一节的参数说明逐项调整。 |
| 87 | 70 | ||
| 88 | -| 字段名 | 作用 | 说明 | | 71 | +**输出**：一份可复现的推荐基线配置，后续所有参数调整均以此为比较对象。 |
| 89 | -| --- | --- | --- | | ||
| 90 | -| scope | 量化范围 | 固定为 `"dual_scale"`（双尺度）。 | | ||
| 91 | -| dtype | 量化数据类型 | 固定为 `"mxfp4"`。 | | ||
| 92 | -| symmetric | 是否对称量化 | `true` 为对称，`false` 为非对称。 | | ||
| 93 | -| method | 量化方法 | 固定为 `"dualscale"`。 | | ||
| 94 | -| ext.dual_block_size | 外层大块大小 | 整数，如 `512`。 | | ||
| 95 | 72 | ||
| 96 | -**输出**：YAML 配置文件 `${CONFIG_PATH}`。 | 73 | +### 步骤 3：选择并调整参数 |
| 97 | - | ||
| 98 | -### 步骤 2：执行量化命令 | ||
| 99 | - | ||
| 100 | -**目标**：使用上一步编写的 YAML 配置文件启动量化流程。 | ||
| 101 | 74 | ||
| 102 | **操作**： | 75 | **操作**： |
| 103 | 76 | ||
| 104 | -```bash | 77 | +参数选择建议按三个层次理解：首先确认 `dtype/scope/method` 等**算法支持约束**，这类字段不是任意可调；其次确定 `include/exclude`、子图类型等**作用范围**；最后再调整会改变误差与开销的数值参数。下面的推荐值区分了代码默认值、仓库 `lab_practice` 中已验证的实践值和适合首次使用的推荐起点。如果目标模型已有实践配置，优先沿用实践配置，再根据本节说明做单变量调整。 |
| 105 | -msmodelslim quant \ | ||
| 106 | - --model_path ${MODEL_PATH} \ | ||
| 107 | - --save_path ${SAVE_PATH} \ | ||
| 108 | - --device npu \ | ||
| 109 | - --model_type ${MODEL_TYPE} \ | ||
| 110 | - --config_path ${CONFIG_PATH} \ | ||
| 111 | - --trust_remote_code True | ||
| 112 | -``` | ||
| 113 | 78 | ||
| 114 | -参数说明： | 79 | +| 配置项 | 含义（原理） | 推荐配置 | 选择与调整建议 | |
| 80 | +| --- | --- | --- | --- | | ||
| 81 | +| `scope` | 当前 DualScale 量化器注册的专用粒度，表示在普通 MXFP4 block scale 之外再引入更大粒度的第二层尺度。 | 固定 `dual_scale`。 | 其他 scope 不属于本算法。 | | ||
| 82 | +| `dtype` | 当前注册格式为 `mxfp4`。内部仍会先使用 MXFP4 per-block MinMax，再乘第二层 scale。 | 固定 `mxfp4`。 | 部署格式改变时应选择对应算法。 | | ||
| 83 | +| `symmetric` | 当前注册组合为对称 MXFP4 DualScale。 | 固定 `true`。 | 当前不建议修改。 | | ||
| 84 | +| `method` | 选择 DualScale 实现。 | 固定 `dualscale`。 | 不是精度旋钮。 | | ||
| 85 | +| `ext.axes` | 决定沿哪个维度进行 inner block 与 outer dual block 的 reshape，默认 `-1`。它影响尺度共享的方向。 | 通常保持 `-1`，除非实践配置/后端明确指定其他轴。 | 轴与张量布局绑定，不能只为了离线 MSE 改轴；修改后需要同时验证权重与激活两路的布局和部署解析。 | | ||
| 86 | +| `ext.dual_block_size` | 第二层尺度覆盖的大块大小。内部先做 MXFP4 小块量化，再按 `dual_block_size` 计算/保存额外 scale；大块越小，第二层尺度越局部，适应局部分布更强，但尺度数量和处理开销更高。 | 仓库 Qwen-Image-Edit 实践对激活和权重都使用 `512`，可作为该模型族/格式的优先起点。 | 局部动态范围差异很大时可尝试减小；若尺度元数据或处理开销更重要可增大。调整时激活和权重不一定必须相同，但首次比较建议保持一致，避免两个方向同时变化。 | | ||
| 115 | 87 | ||
| 116 | -| 参数 | 必选 | 说明 | | 88 | +### 参数组合与选择顺序 |
| 117 | -| --- | --- | --- | | ||
| 118 | -| `model_path` | 是 | 浮点模型权重路径 | | ||
| 119 | -| `save_path` | 是 | 量化权重保存路径 | | ||
| 120 | -| `device` | 否 | 量化设备，默认 `npu` | | ||
| 121 | -| `model_type` | 是 | 模型名称，与支持矩阵一致 | | ||
| 122 | -| `config_path` | 是 | 步骤 1 编写的 YAML 配置路径 | | ||
| 123 | -| `trust_remote_code` | 否 | 是否信任远程代码，默认 `False` | | ||
| 124 | 89 | ||
| 125 | -执行流程说明： | 90 | +1. **先锁定部署目标与支持组合**：先确定最终位宽/数值格式，再确认当前量化器实际注册了对应的 `dtype + scope + symmetric + method` 组合；不要为了追求某个参数值而越过支持约束。 |
| 91 | +2. **再固定作用范围**：使用已有模型配方时，先复用其 `include/exclude` 或子图类型；没有配方时先建立覆盖范围明确的基线，确认算法确实作用到了预期模块。 | ||
| 92 | +3. **最后只调一个主要旋钮**：数值搜索步数、平滑强度、分组大小等一次只改一项，并保持同一校准集和评测集。若调整后没有稳定收益，回到上一个基线，而不是继续叠加多个变化。 | ||
| 126 | 93 | ||
| 127 | -1. 工具加载 YAML 配置，解析 `linear_quant` 处理器与 DualScale 配置。 | 94 | +DualScale 的核心旋钮是 `dual_block_size`。先固定 MXFP4 + dual_scale 格式和 axes；再在同一模型上比较不同 outer block 大小的重构/任务精度与尺度开销。 |
| 128 | -2. 权重在初始化阶段完成静态量化存储（外层尺度 + 内层 block 量化）。 | ||
| 129 | -3. 前向时激活按外层缩放、内层量化、外层反量化执行。 | ||
| 130 | -4. 保存量化权重。 | ||
| 131 | 95 | ||
| 132 | -**输出**：量化权重目录 `${SAVE_PATH}`，包含量化描述文件与权重分片。 | 96 | +**输出**：一份完成单变量调整的算法参数方案，关键字段均有明确的选择依据和调整方向。 |
| 133 | 97 | ||
| 134 | -### 步骤 3：验证量化结果 | 98 | +### 步骤 4：根据结果收敛参数方案 |
| 135 | - | ||
| 136 | -**目标**：确认量化权重文件完整且可加载。 | ||
| 137 | 99 | ||
| 138 | **操作**： | 100 | **操作**： |
| 139 | 101 | ||
| 140 | -1. 检查输出目录是否包含 `quant_model_description.json` 文件。 | 102 | +调参时建议先记录一份完整基线，包括使用的数据集、量化范围、关键参数和端到端指标。每轮只改变一个变量，并把变化结果与基线直接比较；如果某项调整带来收益，再继续小步搜索其邻近取值。对于只有少数层或模块异常的情况，优先采用局部排除、局部回退或混合精度，而不是直接提高全模型精度配置，这通常更容易保留压缩和性能收益。 |
| 141 | -2. 检查日志确认量化流程正常完成。 | ||
| 142 | -3. 使用推理框架加载量化权重进行冒烟测试。 | ||
| 143 | 103 | ||
| 144 | -**输出**：量化权重验证通过。 | 104 | +- **先跑推荐基线，再调单变量。** 不要同时修改位宽、粒度、算法参数和层范围，否则很难判断精度变化来自哪一项。 |
| 105 | +- **优先回退局部，而不是整体提高精度。** 如果只有少数层敏感，优先通过 `exclude` 或混合策略保留高精度，通常比整体升位宽更划算。 | ||
| 106 | +- **最终以模型实践配置和部署能力为准。** 入门推荐用于建立稳定起点；目标模型已有 `lab_practice` 配方时，应优先复用已验证组合。 | ||
| 145 | 107 | ||
| 146 | -## 6. 验收条件 | 108 | +**输出**：一份可进入后续量化流程的最终参数方案，并保留相对于推荐基线的调整记录。 |
| 147 | 109 | ||
| 148 | -- 量化权重目录包含 `quant_model_description.json` 及所有必需的 `*.safetensors` 分片文件。 | 110 | +## 5. 术语 |
| 149 | -- 日志无配置组合无效告警。 | ||
| 150 | -- 量化后模型推理精度优于基线。 | ||
| 151 | - | ||
| 152 | -## 7. 异常处置 | ||
| 153 | - | ||
| 154 | -- **配置组合无效**：确认 `scope` 为 `dual_scale`、`dtype` 为 `mxfp4`、`method` 为 `dualscale`。 | ||
| 155 | -- **精度不达标**：调整 `dual_block_size`，或确认校准数据质量与模型适配范围。 | ||
| 156 | -- **显存不足**：确认 NPU 显存 ≥64G，必要时减少校准数据规模。 | ||
| 157 | - | ||
| 158 | -## 8. 术语 | ||
| 159 | 111 | ||
| 160 | | 术语 | 简述 | 链接 | | 112 | | 术语 | 简述 | 链接 | |
| 161 | | --- | --- | --- | | 113 | | --- | --- | --- | |
| 162 | -| DualScale | 两级缩放递进的双尺度量化算法 | [DualScale 词条](./term_dual_scale.md) | | 114 | +| DualScale 双尺度量化算法 | 说明该算法的定义、核心原理、关键性质、适用场景与限制。 | 《[DualScale 双尺度量化算法 量化术语百科词条](./term_dual_scale.md)》 | |
| 163 | -| dual_block_size | 外层大块的大小 | [DualScale 词条](./term_dual_scale.md) | | ||
| 164 | -| 异常通道 | 数值平均高出其他通道数个数量级的通道 | [DualScale 词条](./term_dual_scale.md) | | ||
| 165 | 115 | ||
| 166 | -## 9. 接口文档列表 | 116 | +## 6. 接口文档列表 |
| 167 | 117 | ||
| 168 | | 接口或能力 | 简述 | 链接 | | 118 | | 接口或能力 | 简述 | 链接 | |
| 169 | | --- | --- | --- | | 119 | | --- | --- | --- | |
| 170 | -| `linear_quant` 处理器 | 线性层量化处理器，通过 `scope: "dual_scale"` 启用 DualScale | [线性量化词条](../linear_quant/term_linear_quant.md) | | 120 | +| linear_quant 配置说明 | 字段类型、默认值、合法取值与完整配置约束。 | 《[linear_quant 配置说明](../../../api_reference/config/processor/linear_quant.md)》 | |
| 171 | -| `MXWeightDualScaleMinmax` | 权重双尺度量化器 | [DualScale 词条](./term_dual_scale.md) | | 121 | +| modelslim_v1 配置说明 | 需要继续探索 runner、prior、save、dataset 等任务级高级配置时查阅。 | 《[modelslim_v1 配置说明](../../../api_reference/config/task/modelslim_v1.md)》 | |
| 172 | -| `MXActDualScaleMinmax` | 激活双尺度量化器 | [DualScale 词条](./term_dual_scale.md) | | ||
| @@ -1,16 +1,14 @@ | |||
| 1 | -# FA3 Quant 注意力激活量化算法词条 | 1 | +# FA3 Quant 注意力激活量化算法 量化术语百科词条 |
| 2 | 2 | ||
| 3 | -> **词条类别**：量化算法 | 3 | +> **词条类别**：[量化算法](../README.md#2-量化算法)<br> |
| 4 | -> **英文名称**：FA3 Quant | 4 | +> **英文名称**：fa3_quant<br> |
| 5 | -> **英文缩写**：FA3 | 5 | +> **应用领域**：大语言模型量化压缩、推理加速、长序列推理<br> |
| 6 | -> **应用领域**：大语言模型量化压缩、推理加速、长序列推理 | ||
| 7 | -> **msModelSlim 实现**：`msmodelslim/processor/quant/fa3/` | ||
| 8 | 6 | ||
| 9 | --- | 7 | --- |
| 10 | 8 | ||
| 11 | ## 1. 概述 | 9 | ## 1. 概述 |
| 12 | 10 | ||
| 13 | -FA3 Quant（Flash Attention 3 激活量化）是一种针对注意力机制激活的 per-head（逐注意力头）量化算法。它对注意力机制中的 Q、K、V 激活进行多种粒度的量化（INT8、FP8），在保持模型精度的前提下提升推理性能和降低显存占用。其核心特征是：per-head 静态量化、Recall Window 算法寻找最小量化范围、支持 MLA 架构，通常与 [线性量化](../linear_quant/term_linear_quant.md) 配合实现全量化方案。 | 11 | +FA3 Quant 是一种面向注意力激活的逐 Head 量化算法。它对 Q、K、V 等注意力中间张量按 Head 建立量化范围，以降低长序列 Attention 的存储与计算开销，并尽量控制激活量化误差；核心特征是 per-head 粒度、面向 Attention 路径的激活量化和针对范围选择的专门统计策略。 |
| 14 | 12 | ||
| 15 | --- | 13 | --- |
| 16 | 14 | ||
| @@ -18,22 +16,28 @@ FA3 Quant（Flash Attention 3 激活量化）是一种针对注意力机制激 | |||
| 18 | 16 | ||
| 19 | 在长序列下，Attention 的中间激活 Q、K、V 张量在显存中占比高，对其进行量化可以有效降低显存占用并提升计算效率。但 Q、K、V 的激活动态范围大且分布高度不均，直接进行全局量化会导致精度损失严重。FA3 Quant 通过逐注意力头独立量化，适应不同 head 的激活分布差异。 | 17 | 在长序列下，Attention 的中间激活 Q、K、V 张量在显存中占比高，对其进行量化可以有效降低显存占用并提升计算效率。但 Q、K、V 的激活动态范围大且分布高度不均，直接进行全局量化会导致精度损失严重。FA3 Quant 通过逐注意力头独立量化，适应不同 head 的激活分布差异。 |
| 20 | 18 | ||
| 21 | ---- | 19 | +从量化流程中的定位看，该算法解决的是“如何把连续浮点值映射到受限数值集合，同时尽量保留模型输出”的问题。与只按极值直接计算尺度的基础方法相比，它通常会利用更细的统计信息、优化目标或结构约束来控制误差，因此更适合对精度有明确要求的量化场景。 |
| 22 | 20 | ||
| 23 | -## 3. 原理 | 21 | +### 2.1 核心思想 |
| 24 | - | ||
| 25 | -### 1. 核心思想 | ||
| 26 | 22 | ||
| 27 | FA3 Quant 的核心思想是“逐注意力头独立量化”：对每个注意力头独立计算量化参数（scale），适应不同 head 的激活分布差异；每个 head 使用 Recall Window 算法找到包含指定比例数据的最小数值分布区间作为量化范围，避免离群值拉大量化尺度。 | 23 | FA3 Quant 的核心思想是“逐注意力头独立量化”：对每个注意力头独立计算量化参数（scale），适应不同 head 的激活分布差异；每个 head 使用 Recall Window 算法找到包含指定比例数据的最小数值分布区间作为量化范围，避免离群值拉大量化尺度。 |
| 28 | 24 | ||
| 29 | -### 2. 数学描述 | 25 | +per-head 统计可以阻断“一个 head 的离群值让所有 head 都变粗”的误差耦合；Recall Window 则进一步解决单个 head 内极少量尾部样本的问题。 |
| 26 | + | ||
| 27 | +### 2.2 工作机制 | ||
| 28 | + | ||
| 29 | +不同 attention head 的 Q/K/V 或中间激活分布并不一定相同。如果所有 head 共享一个量化尺度，某个 head 的极端值会抬高整组步长，使其他 head 的主体数据浪费大量码点。FA3 Quant 因此按 head 独立收集统计量，把“跨 head 的动态范围差异”从量化误差来源中分离出去。 | ||
| 30 | + | ||
| 31 | +在每个 head 内，Recall Window 不强求量化区间覆盖全部样本，而是在排序后的样本上寻找能包含给定比例数据的最短区间。它相当于主动舍弃极少量尾部点，以换取更窄的主体范围和更小的量化步长。对称量化时再用窗口两端绝对值的较大者形成 $[-a,a]$ 范围；跨校准批次则需要合并统计，避免某一批次的偶然窄区间导致真实推理时频繁饱和。 | ||
| 32 | + | ||
| 33 | +### 2.3 数学描述 | ||
| 30 | 34 | ||
| 31 | 对激活张量 $x$（shape 为 $(B, H, S, D)$），将其 reshape 为 $(H, N)$，其中 $N = B \times S \times D$，每个 head 独立收集 $N$ 个数据点。 | 35 | 对激活张量 $x$（shape 为 $(B, H, S, D)$），将其 reshape 为 $(H, N)$，其中 $N = B \times S \times D$，每个 head 独立收集 $N$ 个数据点。 |
| 32 | 36 | ||
| 33 | 对每个 head 使用 Recall Window 算法寻找最小量化范围： | 37 | 对每个 head 使用 Recall Window 算法寻找最小量化范围： |
| 34 | 38 | ||
| 35 | 1. 排序：$\text{sorted\_data} = \operatorname{sort}(\text{head\_data})$ | 39 | 1. 排序：$\text{sorted\_data} = \operatorname{sort}(\text{head\_data})$ |
| 36 | -2. 目标元素数量：$\text{target\_num} = \lfloor \text{ratio} \times N \rfloor$（默认 $\text{ratio} = 0.9999$） | 40 | +2. 目标元素数量：$\text{target\_num} = \lfloor \text{ratio} \times N \rfloor$ |
| 37 | 3. 滑动窗口搜索窗口长度最小的范围 $[\text{sorted\_data}[i], \text{sorted\_data}[i + \text{target\_num} - 1]]$ | 41 | 3. 滑动窗口搜索窗口长度最小的范围 $[\text{sorted\_data}[i], \text{sorted\_data}[i + \text{target\_num} - 1]]$ |
| 38 | 42 | ||
| 39 | 对称量化参数： | 43 | 对称量化参数： |
| @@ -47,102 +51,51 @@ $$ | |||
| 47 | - $S$：序列长度 | 51 | - $S$：序列长度 |
| 48 | - $D$：head 维度 | 52 | - $D$：head 维度 |
| 49 | - $h$：注意力头索引 | 53 | - $h$：注意力头索引 |
| 50 | -- $\text{ratio}$：Recall Window 保留比例，默认 $0.9999$ | 54 | +- $\text{ratio}$：Recall Window 希望保留在量化区间内的样本比例。 |
| 51 | - $\text{scale}[h]$：第 $h$ 个头的量化缩放因子 | 55 | - $\text{scale}[h]$：第 $h$ 个头的量化缩放因子 |
| 52 | 56 | ||
| 53 | 跨批次累积统计时，量化范围取所有校准批次的最小值/最大值并集。 | 57 | 跨批次累积统计时，量化范围取所有校准批次的最小值/最大值并集。 |
| 54 | 58 | ||
| 55 | -### 3. 关键性质 | 59 | +将某个 head 的排序样本记为 $x_{(1)}\le\cdots\le x_{(N)}$，保留数量 $m=\lfloor rN\rfloor$，Recall Window 可写为： |
| 60 | + | ||
| 61 | +$$ | ||
| 62 | +i^*=\arg\min_{1\le i\le N-m+1}\left(x_{(i+m-1)}-x_{(i)}\right), | ||
| 63 | +$$ | ||
| 64 | + | ||
| 65 | +$$ | ||
| 66 | +[l,u]=[x_{(i^*)},x_{(i^*+m-1)}]. | ||
| 67 | +$$ | ||
| 68 | + | ||
| 69 | +被窗口排除的样本产生 clipping error；窗口越窄，范围内量化步长越小。对于对称 INT8，可进一步令 $a=\max(|l|,|u|)$、$s=a/127$。因此保留率 $r$ 明确控制“裁剪尾部多少”与“主体分辨率多细”的权衡。 | ||
| 70 | + | ||
| 71 | +### 2.4 关键性质 | ||
| 56 | 72 | ||
| 57 | - **per-head 量化**：对每个注意力头独立计算量化参数，适应分布差异。 | 73 | - **per-head 量化**：对每个注意力头独立计算量化参数，适应分布差异。 |
| 58 | - **Recall Window**：滑动窗口寻找包含指定比例数据的最小范围，抑制离群值影响。 | 74 | - **Recall Window**：滑动窗口寻找包含指定比例数据的最小范围，抑制离群值影响。 |
| 59 | - **多粒度支持**：支持 INT8 与 FP8（静态/动态）多种量化粒度。 | 75 | - **多粒度支持**：支持 INT8 与 FP8（静态/动态）多种量化粒度。 |
| 60 | -- **MLA 适配**：针对 Multi-head Latent Attention 计算的关键位置插入量化节点。 | 76 | +- **裁剪与精度可权衡**：Recall Window 的保留比例直接决定尾部饱和与主体分辨率之间的平衡。 |
| 61 | 77 | ||
| 62 | ---- | 78 | +从误差与适用边界看，注意力对 Q/K 量化尤其敏感，因为误差会进入点积并经过 softmax。一个看似很小的 logit 偏差，在两个候选位置得分接近时可能改变概率排序；因此校准数据必须覆盖真实序列长度、位置模式和 head 行为。 |
| 63 | 79 | ||
| 64 | -## 4. 流程示意 | 80 | +### 2.5 适用场景 |
| 65 | - | ||
| 66 | -> 以下为本算法在 msModelSlim 中的简化流程概览。 | ||
| 67 | - | ||
| 68 | -```mermaid | ||
| 69 | -flowchart LR | ||
| 70 | - A[注入占位器] --> B[校准收集统计] | ||
| 71 | - B --> C[Recall Window 搜索] | ||
| 72 | - C --> D[计算量化参数] | ||
| 73 | - D --> E[部署伪量化] | ||
| 74 | -``` | ||
| 75 | - | ||
| 76 | ---- | ||
| 77 | - | ||
| 78 | -## 5. 在 msModelSlim 中的实现 | ||
| 79 | - | ||
| 80 | -### 1. 实现位置 | ||
| 81 | - | ||
| 82 | -算法在 `msmodelslim/processor/quant/fa3/processor.py` 中实现，通过 `type: "fa3_quant"` 处理器使用。 | ||
| 83 | - | ||
| 84 | -### 2. 处理流程 | ||
| 85 | - | ||
| 86 | -- **注入阶段**（`preprocess`）：调用模型适配器的 `inject_fa3_placeholders()`，在 MLA 计算流程的关键位置插入占位器 `FA3QuantPlaceHolder`，支持 `include/exclude` 选择性注入。 | ||
| 87 | -- **校准阶段**（`process`）：占位符替换为监听器 `_FA3PerheadObserver`，校准数据流经注意力层时收集每个 head 的激活统计信息。 | ||
| 88 | -- **伪量化部署阶段**（`postprocess`）：从监听器提取 min/max，调用 `calculate_qparam()` 计算对称量化参数，创建 IR 替换监听器。 | ||
| 89 | - | ||
| 90 | -### 3. 配置示例 | ||
| 91 | - | ||
| 92 | -> 以下为最小可用的 YAML 配置片段。各字段的详细含义如下表所示。 | ||
| 93 | - | ||
| 94 | -```yaml | ||
| 95 | -spec: | ||
| 96 | - process: | ||
| 97 | - - type: "fa3_quant" | ||
| 98 | - qconfig: | ||
| 99 | - dtype: "fp8_e4m3" | ||
| 100 | - scope: "per_token" | ||
| 101 | - symmetric: True | ||
| 102 | - method: "minmax" | ||
| 103 | - include: [ "*" ] | ||
| 104 | - exclude: [ "model.layers.0.self_attn" ] | ||
| 105 | -``` | ||
| 106 | - | ||
| 107 | -**字段说明**： | ||
| 108 | - | ||
| 109 | -| 字段名 | 作用 | 说明 | | ||
| 110 | -| --- | --- | --- | | ||
| 111 | -| type | 处理器类型标识 | 固定为 `"fa3_quant"`。 | | ||
| 112 | -| qconfig | 量化统一配置 | Q/K/V 的统一量化配置，与 `details` 不可同时配置。 | | ||
| 113 | -| details | 量化详细配置 | 按 `fa_q`/`fa_k`/`fa_v` 分别配置各激活值的量化方式。 | | ||
| 114 | -| include | 包含的注意力层 | 字符串列表，支持通配符匹配，指定执行 FA3 量化的注意力层。 | | ||
| 115 | -| exclude | 排除的注意力层 | 字符串列表，支持通配符匹配，优先级高于 `include`。 | | ||
| 116 | - | ||
| 117 | -### 4. 模型适配接口 | ||
| 118 | - | ||
| 119 | -模型适配需实现 `FA3QuantAdapterInterface` 接口的 `inject_fa3_placeholders()` 方法，在 MLA 计算流程关键位置插入占位器 `FA3QuantPlaceHolder`。参考实现：`msmodelslim/model/deepseek_v3/model_adapter.py`。 | ||
| 120 | - | ||
| 121 | ---- | ||
| 122 | - | ||
| 123 | -## 6. 适用场景与限制 | ||
| 124 | - | ||
| 125 | -### 1. 适用场景 | ||
| 126 | 81 | ||
| 127 | - 长序列推理场景下需要降低 Attention 中间激活显存占用的场景。 | 82 | - 长序列推理场景下需要降低 Attention 中间激活显存占用的场景。 |
| 128 | - 基于 MLA 架构的模型（如 DeepSeek 系列）的全量化方案。 | 83 | - 基于 MLA 架构的模型（如 DeepSeek 系列）的全量化方案。 |
| 129 | 84 | ||
| 130 | -### 2. 使用限制 | 85 | +更具体地说，是否适用主要取决于目标位宽、模型结构和部署后端三点。若目标部署链已经明确支持该算法对应的量化格式，并且校准数据能够覆盖主要业务分布，通常可以优先从该算法的推荐配置建立基线，再根据精度结果决定是否增加更复杂的优化。 |
| 131 | 86 | ||
| 132 | -- 必须有支持 FA3 的模型适配器实现 `FA3QuantAdapterInterface`，适用于基于 MLA 的注意力机制。 | 87 | +### 2.6 使用限制 |
| 133 | -- 当前支持 INT8/FP8 静态对称量化与 FP8 动态量化。 | 88 | + |
| 134 | -- `qconfig` 与 `details` 字段不支持同时配置。 | 89 | +- 主要面向与 FA3 低精度注意力路径兼容的注意力结构，尤其是 MLA 类架构；普通注意力结构不能直接假设具有相同的量化插入点。 |
| 90 | +- Q、K、V 的量化粒度和数据格式必须与实际注意力算子能力一致；更低精度格式通常需要更严格的端到端精度验证。 | ||
| 91 | + | ||
| 92 | +这些限制应在调参前确认，而不是等精度异常后再排查。尤其是数据类型、张量维度、分组大小和后端算子支持等硬约束，一旦不满足，继续调整算法参数通常无法解决问题；应先回到受支持的配置组合。 | ||
| 135 | 93 | ||
| 136 | --- | 94 | --- |
| 137 | 95 | ||
| 138 | -## 7. 关联流程 | 96 | +## 3. 关联词条 |
| 139 | 97 | ||
| 140 | -- 《[一键量化 (V1)](../../../user_guide/usage_quick_quantization.md)》：可集成 FA3 Quant 作为注意力激活量化步骤。 | 98 | +可以从“同类方法、前后处理关系和应用对象”三个方向理解本词条与其他算法的关系。下面的关联项既用于横向比较不同技术路线，也用于帮助定位该算法在完整量化方案中的位置。 |
| 141 | -- 《[量化精度调优指南](../../../user_guide/process_quantization_precision_tuning.md)》：精度不达标时可调整 FA3 Quant 配置。 | ||
| 142 | - | ||
| 143 | ---- | ||
| 144 | - | ||
| 145 | -## 8. 关联词条 | ||
| 146 | 99 | ||
| 147 | - [线性量化](../linear_quant/term_linear_quant.md)：配套术语，FA3 Quant 通常与线性量化配合实现全量化方案。 | 100 | - [线性量化](../linear_quant/term_linear_quant.md)：配套术语，FA3 Quant 通常与线性量化配合实现全量化方案。 |
| 148 | - [KVCache Quant](../kvcache_quant/term_kvcache_quant.md)：配套术语，同属长序列推理的缓存/激活量化方案。 | 101 | - [KVCache Quant](../kvcache_quant/term_kvcache_quant.md)：配套术语，同属长序列推理的缓存/激活量化方案。 |
| @@ -151,7 +104,9 @@ spec: | |||
| 151 | 104 | ||
| 152 | --- | 105 | --- |
| 153 | 106 | ||
| 154 | -## 9. 参考资料 | 107 | +## 4. 参考文档 |
| 108 | + | ||
| 109 | +参考文档优先列出算法原始论文或权威出处，并补充仓库内对应使用指南。需要进一步理解参数选择时，可先阅读使用指南，再回到原论文核对算法假设和推导。 | ||
| 155 | 110 | ||
| 156 | 1. Dao T et al. FlashAttention-3: Fast and Accurate Attention with Asynchrony and Low-precision. 2024. https://arxiv.org/abs/2407.08608 | 111 | 1. Dao T et al. FlashAttention-3: Fast and Accurate Attention with Asynchrony and Low-precision. 2024. https://arxiv.org/abs/2407.08608 |
| 157 | -2. 《FA3 Quant 使用指南》([./usage_fa3_quant.md](./usage_fa3_quant.md)) | 112 | +2. 《[FA3 Quant 参数配置流程指南](./usage_fa3_quant.md)》 |
| @@ -1,162 +1,114 @@ | |||
| 1 | -# FA3 Quant 使用指南 | 1 | +# FA3 Quant 参数配置流程指南 |
| 2 | 2 | ||
| 3 | ## 1. 适用范围 | 3 | ## 1. 适用范围 |
| 4 | 4 | ||
| 5 | -本流程适用于在 msModelSlim 中配置和使用 FA3 Quant 注意力激活量化算法。FA3 Quant 作为激活量化处理器，对注意力机制中的 Q、K、V 激活进行 per-head 量化，用于降低显存占用并提升推理效率。 | 5 | +FA3 Quant 注意力激活量化算法。FA3 Quant 作为激活量化处理器，对注意力机制中的 Q、K、V 激活进行 per-head 量化，用于降低显存占用并提升推理效率。 |
| 6 | 6 | ||
| 7 | -适用角色：算法工程师、模型部署工程师 | 7 | +本指南面向首次配置 FA3 Quant 的用户，重点不是展开完整执行命令，而是说明推荐配置为什么适合作为起点、哪些参数真正需要调，以及出现精度或资源问题时应优先改哪一项。这类算法通常直接影响量化尺度、舍入方式、量化粒度或低比特表示，因此参数选择会同时影响精度、压缩率以及部署兼容性。第一次使用时建议先固定目标位宽、校准集和评测方式，只采用本指南给出的推荐起点；确认基线稳定后，再围绕真正影响算法行为的参数逐项调整。 |
| 8 | 8 | ||
| 9 | -适用场景： | 9 | +如果目标模型已经有完整且已验证的量化配方，应优先复用该配方；若当前算法与目标模型结构、数值格式或部署后端不兼容，不应通过增大搜索强度或扩大作用范围来绕过支持约束。 |
| 10 | 10 | ||
| 11 | -- 长序列推理场景下需要降低 Attention 中间激活显存占用的场景。 | 11 | +## 2. 输入和交付件 |
| 12 | -- 基于 MLA 架构的模型（如 DeepSeek 系列）的全量化方案。 | ||
| 13 | - | ||
| 14 | -不适用场景： | ||
| 15 | - | ||
| 16 | -- 模型适配器未实现 `FA3QuantAdapterInterface` 接口。 | ||
| 17 | -- 非 MLA 架构的注意力机制。 | ||
| 18 | - | ||
| 19 | -## 2. 流程关系与前置条件 | ||
| 20 | - | ||
| 21 | -**上级流程**：模型适配与验证通过后，确定量化方案阶段。 | ||
| 22 | - | ||
| 23 | -**前置条件**： | ||
| 24 | - | ||
| 25 | -- 已安装兼容版本的 msModelSlim 工具（详见《[msModelSlim 工具安装指南](../../../install_guide/install_guide.md)》）。 | ||
| 26 | -- 已确认目标模型基于 MLA 架构，且适配器实现了 `FA3QuantAdapterInterface` 接口。 | ||
| 27 | -- 已准备好校准数据集，用于收集每个 head 的激活统计信息。 | ||
| 28 | - | ||
| 29 | -**后续操作**：量化流程执行 → 精度验证 → 部署上线或进入调优。 | ||
| 30 | - | ||
| 31 | -## 3. 输入和交付件 | ||
| 32 | 12 | ||
| 33 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | | 13 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | |
| 34 | | --- | --- | --- | --- | --- | | 14 | | --- | --- | --- | --- | --- | |
| 35 | -| 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被目标 Transformers 版本加载 | | 15 | +| 输入 | 目标模型与量化目标 | 待量化模型及部署/评测方案 | 明确目标数值格式或位宽、作用模块、精度/性能目标以及部署约束 | 能说明为什么选择本算法以及它在整体量化方案中的位置 | |
| 36 | -| 输入 | 校准数据集 | 工具默认或用户指定 | JSONL 格式，每条含文本 prompt | 可被工具加载并完成前向推理 | | 16 | +| 输入 | 配置约束与实践基线 | 本算法配置说明、目标模型已有 `lab_practice` 配方（如有） | 字段名、支持组合、作用范围和模型适配与当前版本一致 | 推荐起点能够追溯到当前配置定义或已验证实践 | |
| 37 | -| 输入 | 量化 YAML 配置文件 | 用户编写 | 符合 msModelSlim YAML 规范，含 `fa3_quant` 处理器配置 | 可通过工具 `--config_path` 参数加载 | | 17 | +| 输入 | 校准数据（算法需要时） | 任务 `dataset`、校准集或模型实践配方 | 数据应能代表真实输入分布；多阶段算法尽量保持各阶段数据分布一致 | 能被当前量化流程正常读取，并覆盖主要输入形态 | |
| 38 | -| 交付件 | 量化权重目录 | `--save_path` 指定路径 | 含 `quant_model_description.json` 及 `*.safetensors`，已应用 FA3 量化 | 推理冒烟通过 | | 18 | +| 交付件 | FA3 Quant 参数配置方案 | 用户量化 YAML 或任务配置 | 参数取值合法、作用范围明确；关键参数说明选择依据 | 可作为后续量化流程的算法配置输入，并可复现本指南中的基线选择 | |
| 39 | 19 | ||
| 40 | -## 4. 流程总览 | 20 | +## 3. 流程总览 |
| 21 | + | ||
| 22 | +入门时建议先用一组稳定配置建立基线，再围绕影响最大的参数做单变量调整。下面的流程强调“先选参数、再看效果”，不展开量化命令本身。 | ||
| 41 | 23 | ||
| 42 | ```mermaid | 24 | ```mermaid |
| 43 | flowchart LR | 25 | flowchart LR |
| 44 | - A[编写 YAML 配置] --> B[执行量化命令] | 26 | + A[确定 Attention 量化目标] --> B[选择统一或 Q/K/V 独立配置] |
| 45 | - B --> C[注入占位器并校准] | 27 | + B[选择统一或 Q/K/V 独立配置] --> C[统计量化尺度] |
| 46 | - C --> D[计算量化参数] | 28 | + C[统计量化尺度] --> D[应用 Attention 激活量化] |
| 47 | - D --> E[验证量化结果] | 29 | + D[应用 Attention 激活量化] --> E[验证长序列精度] |
| 48 | ``` | 30 | ``` |
| 49 | 31 | ||
| 50 | -## 5. 操作步骤 | 32 | +实际使用时建议把流程理解为“建立基线—观察结果—单变量调整—再次验证”的闭环。流程图中的前几个节点用于固定量化对象、统计信息或初始参数，后几个节点用于应用算法并检查结果；如果效果不理想，应优先回到最近一次修改的参数，而不是同时更换位宽、粒度、作用范围和算法强度。这样可以明确每次变化的因果关系，也便于把有效配置沉淀为后续模型配方。 |
| 51 | 33 | ||
| 52 | -### 步骤 1：编写 YAML 配置文件 | 34 | +## 4. 操作步骤 |
| 53 | 35 | ||
| 54 | -**目标**：编写包含 `fa3_quant` 处理器配置的 YAML 文件。 | 36 | +### 步骤 1：确认目标与约束 |
| 37 | + | ||
| 38 | +**操作**：先固定目标模型、最终量化格式/位宽、作用对象和评测基线，再确认当前版本支持的参数组合。目标模型已有 `lab_practice` 配方时，优先把该配方作为实践基线；没有模型专用配方时，再使用本指南给出的通用推荐起点。若算法依赖校准统计或优化数据，还应在调参前固定代表性数据，避免把数据分布变化误判为参数收益。 | ||
| 39 | + | ||
| 40 | +**输出**：一份明确的配置目标：目标位宽/格式、处理范围、校准条件、评测基线和部署约束。 | ||
| 41 | + | ||
| 42 | +### 步骤 2：建立推荐基线 | ||
| 55 | 43 | ||
| 56 | **操作**： | 44 | **操作**： |
| 57 | 45 | ||
| 58 | -1. 在 `spec.process` 下配置 `fa3_quant` 处理器，指定 `type: "fa3_quant"`。 | 46 | +下面配置用于建立**第一版可比较基线**。如果目标模型已有 `lab_practice` 配方，优先使用已验证配方，再参考本节理解每个参数为什么这样选。 |
| 59 | -2. 配置 `qconfig`（统一量化配置）或 `details`（逐激活值详细配置），二者不可同时配置。 | ||
| 60 | -3. 按需配置 `include`/`exclude` 控制参与量化的注意力层。 | ||
| 61 | - | ||
| 62 | -YAML 配置示例（统一配置）： | ||
| 63 | 47 | ||
| 64 | ```yaml | 48 | ```yaml |
| 65 | spec: | 49 | spec: |
| 66 | process: | 50 | process: |
| 67 | - type: "fa3_quant" | 51 | - type: "fa3_quant" |
| 68 | - qconfig: | 52 | + # 不设置 qconfig/details：使用默认 INT8 per-head 对称量化。 |
| 69 | - dtype: "fp8_e4m3" | 53 | + include: ["*"] |
| 70 | - scope: "per_token" | 54 | + exclude: [] |
| 71 | - symmetric: True | ||
| 72 | - method: "minmax" | ||
| 73 | - include: [ "*" ] # 包含的注意力层 | ||
| 74 | - exclude: [ "model.layers.0.self_attn" ] # 排除的注意力层 | ||
| 75 | ``` | 55 | ``` |
| 76 | 56 | ||
| 77 | -YAML 配置字段详解如下： | 57 | +上面的推荐值用于建立第一版可复现基线，其中最值得关注的配置包括 `type`, `qconfig`, `details`, `include`。推荐值并不表示所有模型都只能使用该组合，而是优先选择仓库默认值、已验证实践或较稳健的中间取值，以降低第一次使用时同时遇到精度和兼容性问题的概率。如果目标模型已经有 `lab_practice` 配方，应优先复用该配方；只有在基线精度、显存或吞吐不满足目标时，再按照下一节的参数说明逐项调整。 |
| 78 | 58 | ||
| 79 | -| 字段名 | 作用 | 说明 | | 59 | +**输出**：一份可复现的推荐基线配置，后续所有参数调整均以此为比较对象。 |
| 80 | -| --- | --- | --- | | ||
| 81 | -| type | 处理器类型标识 | 固定为 `"fa3_quant"`。 | | ||
| 82 | -| qconfig | 量化统一配置 | Q/K/V 的统一量化配置，与 `details` 不可同时配置。 | | ||
| 83 | -| details | 量化详细配置 | 按 `fa_q`/`fa_k`/`fa_v` 分别配置各激活值的量化方式。 | | ||
| 84 | -| include | 包含的注意力层 | 字符串列表，支持通配符匹配，指定执行 FA3 量化的注意力层。 | | ||
| 85 | -| exclude | 排除的注意力层 | 字符串列表，支持通配符匹配，优先级高于 `include`。 | | ||
| 86 | 60 | ||
| 87 | -**输出**：YAML 配置文件 `${CONFIG_PATH}`。 | 61 | +### 步骤 3：选择并调整参数 |
| 88 | - | ||
| 89 | -### 步骤 2：执行量化命令 | ||
| 90 | - | ||
| 91 | -**目标**：使用上一步编写的 YAML 配置文件启动量化流程。 | ||
| 92 | 62 | ||
| 93 | **操作**： | 63 | **操作**： |
| 94 | 64 | ||
| 95 | -```bash | 65 | +ModelSlim 实现入口： |
| 96 | -msmodelslim quant \ | 66 | +[查看对应实现目录](../../../../../msmodelslim/processor/quant/fa3) |
| 97 | - --model_path ${MODEL_PATH} \ | ||
| 98 | - --save_path ${SAVE_PATH} \ | ||
| 99 | - --device npu \ | ||
| 100 | - --model_type ${MODEL_TYPE} \ | ||
| 101 | - --config_path ${CONFIG_PATH} \ | ||
| 102 | - --trust_remote_code True | ||
| 103 | -``` | ||
| 104 | 67 | ||
| 105 | -参数说明： | 68 | +参数选择建议按三个层次理解：首先确认 `dtype/scope/method` 等**算法支持约束**，这类字段不是任意可调；其次确定 `include/exclude`、子图类型等**作用范围**；最后再调整会改变误差与开销的数值参数。下面的推荐值区分了代码默认值、仓库 `lab_practice` 中已验证的实践值和适合首次使用的推荐起点。如果目标模型已有实践配置，优先沿用实践配置，再根据本节说明做单变量调整。 |
| 106 | 69 | ||
| 107 | -| 参数 | 必选 | 说明 | | 70 | +| 配置项 | 含义（原理） | 推荐配置 | 选择与调整建议 | |
| 108 | -| --- | --- | --- | | 71 | +| --- | --- | --- | --- | |
| 109 | -| `model_path` | 是 | 浮点模型权重路径 | | 72 | +| `type` | 处理器标识，固定为 `fa3_quant`。 | 固定。 | 不作为调参项。 | |
| 110 | -| `save_path` | 是 | 量化权重保存路径 | | 73 | +| `qconfig` | Q/K/V 共用的一套量化配置；与 `details` 互斥。两者都省略时，当前处理器构造默认 INT8、`per_head`、对称、MinMax 配置。 | 第一次验证通用 Attention/MLA 路径可省略，使用默认 INT8 per-head；已有模型实践时优先照实践显式使用 `fp8_e4m3 + per_token`、INT8 per-token 或 MXFP4 per-block。 | 统一配置能满足三路精度时不要使用 `details` 增加复杂度。改变 dtype/scope 后要重新校准/验证；尤其 `per_head` 与 `per_token/per_block` 的统计方式和数据依赖不同。 | |
| 111 | -| `device` | 否 | 量化设备，默认 `npu` | | 74 | +| `qconfig.dtype` | Q/K/V 的数值格式。仓库实践已出现 `int8`、`fp8_e4m3`、`mxfp4`，具体合法性还取决于 scope/method 注册和部署后端。 | 没有模型专用配方时先用默认 INT8；有实践配方且目标后端支持时直接沿用其 FP8/MXFP 格式。 | dtype 是部署目标，不是简单“精度旋钮”。切换格式时同时检查 scope、量化方法、硬件/算子支持，并重做量化评测。 | |
| 112 | -| `model_type` | 是 | 模型名称，与支持矩阵一致 | | 75 | +| `qconfig.scope` | 决定 FA 张量尺度粒度。当前 FA3 后处理明确支持 `per_head`、`per_token`、`per_block`。`per_head` 为每个注意力头保存统计尺度；`per_token/per_block` 更偏运行时或格式化局部尺度。 | 通用默认为 `per_head`；仓库多个 FA3 实践使用 `per_token`，MXFP4 实践使用 `per_block`。 | `per_head` 需要校准统计并能捕获不同 Head 的范围差异；源码中仅当所有启用分支都是 per-token/per-block 时可走 data-free 路径。优先按模型实践和部署格式选，不要只依据粒度“越细越好”。 | |
| 113 | -| `config_path` | 是 | 步骤 1 编写的 YAML 配置路径 | | 76 | +| `qconfig.symmetric` / `method` | 决定是否有 zero-point 以及如何估计尺度。现有默认与主要实践均使用对称 + MinMax。 | 优先 `symmetric: true`、`method: minmax`。 | 只有注册组合和部署端明确支持其他设置时才偏离；不要把不支持的通用 QConfig 枚举直接用于 FA3。 | |
| 114 | -| `trust_remote_code` | 否 | 是否信任远程代码，默认 `False` | | 77 | +| `details` | 允许 `fa_q`、`fa_k`、`fa_v` 分别配置，适合三路敏感性或目标格式不同的场景；某一路配置为 `null` 时当前处理逻辑可跳过该分支。 | 入门不设置。只有统一 `qconfig` 无法兼顾三路时再拆分。 | 先用 Attention MSE 或量化评测定位是 Q、K 还是 V 更敏感，再只提高敏感分支精度/更换粒度。不要一开始就给三路都不同配置，否则很难归因。 | |
| 78 | +| `include` | 作用范围白名单，使用模块名模式决定哪些匹配到的模块进入当前算法。它只决定“在哪些模块做”，不会改变算法内部公式。 | 无模型专用配方时从 `["*"]` 开始；已有 `lab_practice` 时直接沿用其模块范围。 | 先保证范围覆盖预期模块，再看精度。范围过宽时，少数结构不兼容或敏感层会放大整体风险；范围过窄则可能让算法收益看不出来。收窄范围时优先按结构族或已知敏感层调整，不建议仅凭层号大面积删除。 | | ||
| 79 | +| `exclude` | 作用范围黑名单，命中后从 `include` 的候选中排除，优先级高于 `include`。适合保护敏感层、首尾层或模型专用不兼容结构。 | 默认先保持空列表；只有实践配方、兼容性约束或敏感性结果给出明确证据时再加入。 | 局部精度问题优先通过 `exclude` 做小范围回退，比提高全模型位宽或关闭整个算法更容易保留收益。每次增加排除项后应确认通配符没有误伤相邻模块。 | | ||
| 115 | 80 | ||
| 116 | -执行流程说明： | 81 | +### 参数组合与选择顺序 |
| 117 | 82 | ||
| 118 | -1. 工具加载 YAML 配置，解析 `fa3_quant` 处理器。 | 83 | +1. **先锁定部署目标与支持组合**：先确定最终位宽/数值格式，再确认当前量化器实际注册了对应的 `dtype + scope + symmetric + method` 组合；不要为了追求某个参数值而越过支持约束。 |
| 119 | -2. 注入阶段在 MLA 计算关键位置插入占位器。 | 84 | +2. **再固定作用范围**：使用已有模型配方时，先复用其 `include/exclude` 或子图类型；没有配方时先建立覆盖范围明确的基线，确认算法确实作用到了预期模块。 |
| 120 | -3. 校准阶段收集每个 head 的激活统计信息，使用 Recall Window 算法寻找量化范围。 | 85 | +3. **最后只调一个主要旋钮**：数值搜索步数、平滑强度、分组大小等一次只改一项，并保持同一校准集和评测集。若调整后没有稳定收益，回到上一个基线，而不是继续叠加多个变化。 |
| 121 | -4. 部署阶段计算量化参数并替换监听器，随后保存量化权重。 | ||
| 122 | 86 | ||
| 123 | -**输出**：量化权重目录 `${SAVE_PATH}`，包含量化描述文件与权重分片。 | 87 | +FA3 的首要决策是 `qconfig` 统一配置还是 `details` 分路配置。先统一，再定位敏感分支；只有证据表明 Q/K/V 需求不同才拆分。 |
| 124 | 88 | ||
| 125 | -### 步骤 3：验证量化结果 | 89 | +**输出**：一份完成单变量调整的算法参数方案，关键字段均有明确的选择依据和调整方向。 |
| 126 | 90 | ||
| 127 | -**目标**：确认量化权重文件完整且可加载。 | 91 | +### 步骤 4：根据结果收敛参数方案 |
| 128 | 92 | ||
| 129 | **操作**： | 93 | **操作**： |
| 130 | 94 | ||
| 131 | -1. 检查输出目录是否包含 `quant_model_description.json` 文件。 | 95 | +调参时建议先记录一份完整基线，包括使用的数据集、量化范围、关键参数和端到端指标。每轮只改变一个变量，并把变化结果与基线直接比较；如果某项调整带来收益，再继续小步搜索其邻近取值。对于只有少数层或模块异常的情况，优先采用局部排除、局部回退或混合精度，而不是直接提高全模型精度配置，这通常更容易保留压缩和性能收益。 |
| 132 | -2. 检查日志确认校准阶段正常完成。 | ||
| 133 | -3. 使用推理框架加载量化权重进行冒烟测试。 | ||
| 134 | 96 | ||
| 135 | -**输出**：量化权重验证通过。 | 97 | +- **先跑推荐基线，再调单变量。** 不要同时修改位宽、粒度、算法参数和层范围，否则很难判断精度变化来自哪一项。 |
| 98 | +- **优先回退局部，而不是整体提高精度。** 如果只有少数层敏感，优先通过 `exclude` 或混合策略保留高精度，通常比整体升位宽更划算。 | ||
| 99 | +- **最终以模型实践配置和部署能力为准。** 入门推荐用于建立稳定起点；目标模型已有 `lab_practice` 配方时，应优先复用已验证组合。 | ||
| 136 | 100 | ||
| 137 | -## 6. 验收条件 | 101 | +**输出**：一份可进入后续量化流程的最终参数方案，并保留相对于推荐基线的调整记录。 |
| 138 | 102 | ||
| 139 | -- 量化权重目录包含 `quant_model_description.json` 及所有必需的 `*.safetensors` 分片文件。 | 103 | +## 5. 术语 |
| 140 | -- 日志无配置冲突（`qconfig` 与 `details` 同时配置）告警。 | ||
| 141 | -- 量化后模型推理精度不低于未使用 FA3 Quant 的基线。 | ||
| 142 | - | ||
| 143 | -## 7. 异常处置 | ||
| 144 | - | ||
| 145 | -- **配置冲突**：`qconfig` 与 `details` 字段不支持同时配置，检查 YAML 只保留其一。 | ||
| 146 | -- **模型不适配**：确认模型基于 MLA 架构且适配器实现了 `FA3QuantAdapterInterface`。 | ||
| 147 | -- **精度下降**：检查 `quant_type` 配置，必要时调整 Q/K/V 各自的量化粒度与格式。 | ||
| 148 | - | ||
| 149 | -## 8. 术语 | ||
| 150 | 104 | ||
| 151 | | 术语 | 简述 | 链接 | | 105 | | 术语 | 简述 | 链接 | |
| 152 | | --- | --- | --- | | 106 | | --- | --- | --- | |
| 153 | -| FA3 Quant | 针对注意力激活的 per-head 量化算法 | [FA3 Quant 词条](./term_fa3_quant.md) | | 107 | +| FA3 Quant 注意力激活量化算法 | 说明该算法的定义、核心原理、关键性质、适用场景与限制。 | 《[FA3 Quant 注意力激活量化算法 量化术语百科词条](./term_fa3_quant.md)》 | |
| 154 | -| per-head 量化 | 对每个注意力头独立计算量化参数 | [FA3 Quant 词条](./term_fa3_quant.md) | | ||
| 155 | -| quant_type | 各激活值的量化格式与策略组合标识 | [FA3 Quant 词条](./term_fa3_quant.md) | | ||
| 156 | 108 | ||
| 157 | -## 9. 接口文档列表 | 109 | +## 6. 接口文档列表 |
| 158 | 110 | ||
| 159 | | 接口或能力 | 简述 | 链接 | | 111 | | 接口或能力 | 简述 | 链接 | |
| 160 | | --- | --- | --- | | 112 | | --- | --- | --- | |
| 161 | -| `fa3_quant` 处理器 | 用于执行 FA3 量化的 Processor 配置 | [FA3 Quant 词条](./term_fa3_quant.md) | | 113 | +| fa3_quant 配置说明 | 字段类型、默认值、合法取值与完整配置约束。 | 《[fa3_quant 配置说明](../../../api_reference/config/processor/fa3_quant.md)》 | |
| 162 | -| `FA3QuantAdapterInterface` | 模型适配器需实现的 FA3 注入接口 | [FA3 Quant 词条](./term_fa3_quant.md) | | 114 | +| modelslim_v1 配置说明 | 需要继续探索 runner、prior、save、dataset 等任务级高级配置时查阅。 | 《[modelslim_v1 配置说明](../../../api_reference/config/task/modelslim_v1.md)》 | |
| @@ -1,15 +1,14 @@ | |||
| 1 | -# Flex AWQ SSZ 灵活激活感知权重量化平滑算法词条 | 1 | +# Flex AWQ SSZ 灵活激活感知权重量化平滑算法 量化术语百科词条 |
| 2 | 2 | ||
| 3 | -> **词条类别**：离群值抑制算法 | 3 | +> **词条类别**：[离群值抑制算法](../README.md#1-离群值抑制算法)<br> |
| 4 | -> **英文名称**：Flex AWQ SSZ | 4 | +> **英文名称**：flex_awq_ssz<br> |
| 5 | -> **应用领域**：大语言模型量化压缩、低比特量化精度优化 | 5 | +> **应用领域**：大语言模型量化压缩、低比特量化精度优化<br> |
| 6 | -> **msModelSlim 实现**：`msmodelslim/processor/anti_outlier/flex_smooth/` | ||
| 7 | 6 | ||
| 8 | --- | 7 | --- |
| 9 | 8 | ||
| 10 | ## 1. 概述 | 9 | ## 1. 概述 |
| 11 | 10 | ||
| 12 | -Flex AWQ SSZ（灵活激活感知权重量化平滑）是一种用于大语言模型量化过程中抑制激活离群值的算法。它结合了 [AWQ](../awq_smooth/term_awq_smooth.md) 与 [SSZ](../ssz/term_ssz.md) 的思想，使用真实量化器（LinearQuantizer）评估不同 `alpha` 参数下的量化误差，自动搜索最优缩放因子，并固定 `beta` 为 `0`、以激活均值而非最大值计算激活尺度。其核心特征是：真实量化器评估、激活均值尺度、自动参数搜索。 | 11 | +Flex AWQ SSZ 是一种结合激活感知缩放与低比特权重量化误差评估的离群值抑制算法。它以激活统计构造通道缩放，并使用 [SSZ](../ssz/term_ssz.md) 等真实量化过程比较候选参数，从而搜索更适合目标低比特配置的缩放因子；核心特征是量化器感知评估、自动参数搜索和对 W4 等低比特场景的适配。 |
| 13 | 12 | ||
| 14 | --- | 13 | --- |
| 15 | 14 | ||
| @@ -17,145 +16,114 @@ Flex AWQ SSZ（灵活激活感知权重量化平滑）是一种用于大语言 | |||
| 17 | 16 | ||
| 18 | [Flex Smooth Quant](../flex_smooth_quant/term_flex_smooth_quant.md) 使用模拟量化评估参数，无法精确反映真实量化后的效果。Flex AWQ SSZ 改用真实的量化器评估不同参数下的量化误差，并针对低比特量化场景使用激活均值（而非最大值）计算激活尺度，从而在不同量化配置下获得更准确的参数选择。 | 17 | [Flex Smooth Quant](../flex_smooth_quant/term_flex_smooth_quant.md) 使用模拟量化评估参数，无法精确反映真实量化后的效果。Flex AWQ SSZ 改用真实的量化器评估不同参数下的量化误差，并针对低比特量化场景使用激活均值（而非最大值）计算激活尺度，从而在不同量化配置下获得更准确的参数选择。 |
| 19 | 18 | ||
| 20 | ---- | 19 | +从量化流程中的定位看，该算法更接近量化前的分布整形步骤：先降低离群值对量化尺度的支配，再由后续量化算法完成真正的离散化。这种思路的价值在于不必简单扩大位宽，而是通过重分配、旋转或平滑数值幅度，提高有限量化区间对主体数据分布的利用率。 |
| 21 | 20 | ||
| 22 | -## 3. 原理 | 21 | +### 2.1 核心思想 |
| 23 | 22 | ||
| 24 | -### 1. 核心思想 | 23 | +Flex AWQ SSZ 的核心思想是“先做激活感知的等价缩放，再用目标权重量化器直接判断缩放是否值得保留”。对输入通道引入正缩放向量 $s$，将激活变为 $X'=X/s$、权重变为 $W'=W\cdot s$，因此浮点域中的线性计算 $XW^T$ 保持不变。与只依赖解析统计量的平滑方法不同，Flex AWQ SSZ 会让候选缩放真正经过目标量化器，再以量化后线性输出相对浮点输出的重构误差选择 $\alpha$。 |
| 25 | 24 | ||
| 26 | -Flex AWQ SSZ 的核心思想是“以真实量化器评估参数有效性”：对每个候选 `alpha` 值，计算缩放因子、应用缩放、创建真实量化器（LinearQuantizer）完成量化-反量化，并计算与浮点结果的归一化 MSE，选择使量化误差最小的 `alpha`。`beta` 固定为 `0`，激活尺度使用均值绝对值 `mean(abs(act))` 计算。 | 25 | +该方法只搜索激活侧指数 $\alpha$，并固定 $\beta=0$。在候选缩放的评估中，激活统计量取逐输入通道的 $\max(|X|)$；$\alpha$ 越大，越倾向于压低激活通道的峰值，同时把相应幅度迁移到权重侧。这样既保留了 AWQ 类方法“重要通道需要保护”的直觉，又把最终判断标准交给实际采用的权重量化方案。 |
| 27 | 26 | ||
| 28 | -### 2. 数学描述 | 27 | +它有效的原因在于参数搜索目标与最终权重量化器一致。 |
| 29 | 28 | ||
| 30 | -缩放因子计算公式： | 29 | +### 2.2 工作机制 |
| 30 | + | ||
| 31 | +对每个候选 $\alpha$，先根据校准激活逐输入通道的峰值构造 $s_j=\max|X_j|^{\alpha}$，再做 $X'_j=X_j/s_j$、$W'_j=W_j s_j$。由于 $\beta=0$，尺度不再显式除以权重统计量，搜索空间从二维缩减为一维；$\alpha=0$ 表示不做迁移，$\alpha$ 增大则逐步加强对激活峰值的压缩。 | ||
| 32 | + | ||
| 33 | +关键点在于候选尺度不是通过代理公式打分，而是把缩放后的权重交给目标低比特量化器，得到实际量化线性输出，再与浮点输出比较归一化 RMSE。这样，SSZ 或其他目标权重量化器自身的尺度优化、舍入与分组特征都会进入 $\alpha$ 的选择标准，使平滑参数与最终权重量化误差形成闭环。 | ||
| 34 | + | ||
| 35 | +### 2.3 数学描述 | ||
| 36 | + | ||
| 37 | +设线性层输入为 $X$、权重为 $W$，逐输入通道尺度为 $s$。Flex AWQ SSZ 使用互逆缩放： | ||
| 31 | 38 | ||
| 32 | $$ | 39 | $$ |
| 33 | -s = \left( \frac{\text{Act\_Mean\_Abs}^{\alpha}}{\text{Weight\_Max\_Abs}^{\beta}} \right) \cdot \operatorname{clamp}(\min=10^{-5}), \quad \beta = 0 | 40 | +X' = X \operatorname{diag}(s)^{-1}, \qquad W' = W\operatorname{diag}(s) |
| 34 | $$ | 41 | $$ |
| 35 | 42 | ||
| 36 | -- $\text{Act\_Mean\_Abs}$：激活值的均值绝对值，即 $mean(|act|)$ | 43 | +因此浮点输出保持不变： |
| 37 | -- $\text{Weight\_Max\_Abs}$：权重的最大绝对值（取每列的最大值） | ||
| 38 | -- $\alpha$：激活缩放系数，$0$~$1$，可自动搜索或手动配置 | ||
| 39 | -- $\beta$：权重缩放系数，固定为 $0$ | ||
| 40 | -- $10^{-5}$：缩放因子的最小值 | ||
| 41 | 44 | ||
| 42 | -当未配置 `alpha` 时，算法在 $[0.0, 1.0]$ 范围内以 $0.05$ 为步长搜索使量化 MSE 最小的 `alpha`。 | 45 | +$$ |
| 46 | +X'W'^T = XW^T | ||
| 47 | +$$ | ||
| 43 | 48 | ||
| 44 | -### 3. 关键性质 | 49 | +在候选参数评估中，尺度由逐输入通道激活峰值构造： |
| 45 | 50 | ||
| 46 | -- **真实量化器评估**：使用 LinearQuantizer 评估量化误差，结果更接近真实部署效果。 | 51 | +$$ |
| 47 | -- **激活均值尺度**：使用 `mean(abs(act))` 而非最大值，更适合低比特量化场景。 | 52 | +s_j = \operatorname{clamp}\left(A_j^{\alpha},\; \min=10^{-5}\right), |
| 48 | -- **参数空间精简**：固定 `beta=0`，仅搜索 `alpha`，降低搜索复杂度。 | 53 | +\qquad A_j = \max |X_j|, \qquad \beta=0 |
| 49 | -- **自动参数搜索**：未配置 `alpha` 时自动搜索最优值，减少人工调参。 | 54 | +$$ |
| 55 | + | ||
| 56 | +- $A_j$：第 $j$ 个输入通道在校准激活上的绝对最大值。 | ||
| 57 | +- $\alpha$：激活迁移强度，搜索区间通常为 $[0,1]$。 | ||
| 58 | +- $\beta$：固定为 $0$，即尺度不显式使用权重项 $W_j^{-\beta}$。 | ||
| 59 | +- $s_j$：最终施加在激活与权重两侧的等价缩放。 | ||
| 60 | + | ||
| 61 | +候选 $\alpha$ 的目标不是直接最小化 $\|W-W_q\|$，而是让目标量化器产生的线性输出尽量接近浮点输出。以归一化 RMSE 表示： | ||
| 62 | + | ||
| 63 | +$$ | ||
| 64 | +E(\alpha)= | ||
| 65 | +\frac{\sqrt{\operatorname{mean}\left((Y_q(\alpha)-Y_{fp})^2\right)}} | ||
| 66 | +{\sqrt{\operatorname{mean}(Y_{fp}^2)}} | ||
| 67 | +$$ | ||
| 68 | + | ||
| 69 | +最终选择 $E(\alpha)$ 最小的候选。 | ||
| 70 | + | ||
| 71 | +更完整地可把搜索写成： | ||
| 72 | + | ||
| 73 | +$$ | ||
| 74 | +\alpha^*=\arg\min_{\alpha\in\mathcal A}\;\frac{\|XW^T-(XD_\alpha^{-1})\,\mathcal Q_{\theta^*(\alpha)}(WD_\alpha)^T\|_F}{\|XW^T\|_F}, | ||
| 75 | +$$ | ||
| 76 | + | ||
| 77 | +其中 $D_\alpha=\operatorname{diag}(s(\alpha))$，而内层量化参数满足： | ||
| 78 | + | ||
| 79 | +$$ | ||
| 80 | +\theta^*(\alpha)=\arg\min_{\theta}\|WD_\alpha-\hat W(\theta)\|^2. | ||
| 81 | +$$ | ||
| 82 | + | ||
| 83 | +这两个式子表达了“先给定缩放，再让目标量化器达到自身较优状态，最后按真实输出误差比较缩放候选”的逻辑。 | ||
| 84 | + | ||
| 85 | +### 2.4 关键性质 | ||
| 86 | + | ||
| 87 | +- **真实量化器评估**：使用目标权重量化器直接评估候选缩放后的重构误差。 | ||
| 88 | +- **参数空间精简**：固定 $\beta=0$，仅搜索 $\alpha$，降低搜索复杂度。 | ||
| 89 | +- **一维参数搜索**：只需比较不同 $\alpha$ 候选，搜索空间比同时优化两个指数更小。 | ||
| 50 | - **计算等价性**：协同缩放保持整体计算等价，不改变模型输出。 | 90 | - **计算等价性**：协同缩放保持整体计算等价，不改变模型输出。 |
| 91 | +- **与目标量化器耦合**：最佳 $\alpha$ 会随位宽、group size 和目标权重量化器变化。 | ||
| 51 | 92 | ||
| 52 | ---- | 93 | +风险在于一维 $\alpha$ 搜索表达能力有限，并且最佳值强依赖校准数据与目标量化方案；更换位宽、group size 或量化器后，原来的最优 $\alpha$ 不一定仍然成立。 |
| 53 | 94 | ||
| 54 | -## 4. 流程示意 | 95 | +### 2.5 适用场景 |
| 55 | - | ||
| 56 | -> 以下为本算法在 msModelSlim 中的简化流程概览。 | ||
| 57 | - | ||
| 58 | -```mermaid | ||
| 59 | -flowchart LR | ||
| 60 | - A[校准数据] --> B[子图发现] | ||
| 61 | - B --> C[收集激活均值] | ||
| 62 | - C --> D[搜索最优 alpha] | ||
| 63 | - D --> E[融合缩放] | ||
| 64 | - E --> F[交付量化] | ||
| 65 | -``` | ||
| 66 | - | ||
| 67 | ---- | ||
| 68 | - | ||
| 69 | -## 5. 在 msModelSlim 中的实现 | ||
| 70 | - | ||
| 71 | -### 1. 实现位置 | ||
| 72 | - | ||
| 73 | -算法在 `msmodelslim/processor/anti_outlier/flex_smooth/processor.py` 中实现，通过 `type: "flex_awq_ssz"` 处理器使用，依赖 `qconfig` 中的真实量化器配置。 | ||
| 74 | - | ||
| 75 | -### 2. 处理流程 | ||
| 76 | - | ||
| 77 | -- **预处理阶段**：通过 `SubgraphProcessor` 获取子图信息，按 `include/exclude` 过滤，为线性模块安装前向钩子收集激活统计信息（使用子图 `targets` 中第一个线性层的激活统计）。 | ||
| 78 | -- **后处理阶段**：按优先级顺序处理各子图，创建 `FlexAWQSSZAlphaBetaSearcher` 搜索最优 `alpha`，应用缩放并融合；最后清理钩子并恢复模型。 | ||
| 79 | - | ||
| 80 | -### 3. 配置示例 | ||
| 81 | - | ||
| 82 | -> 以下为最小可用的 YAML 配置片段。各字段的详细含义如下表所示。 | ||
| 83 | - | ||
| 84 | -```yaml | ||
| 85 | -spec: | ||
| 86 | - process: | ||
| 87 | - - type: "flex_awq_ssz" | ||
| 88 | - alpha: 0.8 | ||
| 89 | - qconfig: | ||
| 90 | - act: | ||
| 91 | - scope: "per_token" | ||
| 92 | - dtype: "int8" | ||
| 93 | - symmetric: True | ||
| 94 | - method: "minmax" | ||
| 95 | - weight: | ||
| 96 | - scope: "per_channel" | ||
| 97 | - dtype: "int4" | ||
| 98 | - symmetric: True | ||
| 99 | - method: "ssz" | ||
| 100 | - enable_subgraph_type: | ||
| 101 | - - 'norm-linear' | ||
| 102 | - - 'linear-linear' | ||
| 103 | - - 'ov' | ||
| 104 | - - 'up-down' | ||
| 105 | - include: ["*"] | ||
| 106 | - exclude: ["*self_attn*"] | ||
| 107 | -``` | ||
| 108 | - | ||
| 109 | -**字段说明**： | ||
| 110 | - | ||
| 111 | -| 字段名 | 作用 | 说明 | | ||
| 112 | -| --- | --- | --- | | ||
| 113 | -| type | 处理器类型标识 | 固定为 `"flex_awq_ssz"`。 | | ||
| 114 | -| alpha | 激活缩放权重系数 | 0~1 之间的浮点数，默认 `None`（自动搜索）。 | | ||
| 115 | -| qconfig | 量化配置 | 必填参数，包含激活值（`act`）和权重（`weight`）的量化配置，用于真实量化器评估。 | | ||
| 116 | -| enable_subgraph_type | 开启的子图类型 | 支持 `norm-linear`、`linear-linear`、`ov`、`up-down`。 | | ||
| 117 | -| include | 包含的层 | 字符串列表，支持通配符匹配。 | | ||
| 118 | -| exclude | 排除的层 | 字符串列表，支持通配符匹配。 | | ||
| 119 | - | ||
| 120 | -### 4. 模型适配接口 | ||
| 121 | - | ||
| 122 | -模型适配需实现 `FlexSmoothQuantInterface` 接口（与 Flex Smooth Quant 相同）的 `get_adapter_config_for_subgraph()` 方法。参考实现：`msmodelslim/model/qwen3/model_adapter.py`。 | ||
| 123 | - | ||
| 124 | ---- | ||
| 125 | - | ||
| 126 | -## 6. 适用场景与限制 | ||
| 127 | - | ||
| 128 | -### 1. 适用场景 | ||
| 129 | 96 | ||
| 130 | - 需要对平滑参数进行真实量化器评估、追求更高精度的低比特量化场景。 | 97 | - 需要对平滑参数进行真实量化器评估、追求更高精度的低比特量化场景。 |
| 131 | - 需要同时对注意力 `ov`、MLP `up-down`、连续线性层等多种结构做离群值抑制的场景。 | 98 | - 需要同时对注意力 `ov`、MLP `up-down`、连续线性层等多种结构做离群值抑制的场景。 |
| 132 | 99 | ||
| 133 | -### 2. 使用限制 | 100 | +更具体地说，这类算法适合“量化误差主要由少数大幅值通道或 token 拉高尺度”的情况。若问题来源并不是离群值，而是模型本身对低比特表示普遍敏感，则单独增加平滑或旋转强度通常收益有限，应结合更高精度量化或敏感层回退。 |
| 134 | 101 | ||
| 135 | -- 模型必须实现 `FlexSmoothQuantInterface` 接口并正确配置子图映射。 | 102 | +### 2.6 使用限制 |
| 136 | -- `qconfig` 为必填参数，需提供激活与权重的量化配置（权重通常使用 SSZ 方法）。 | 103 | + |
| 137 | -- 目标模块必须存在且具备可写的 `weight`，模块名须与 `named_modules()` 返回的完整路径一致。 | 104 | +- 目标子图需要满足可做等价协同缩放的结构关系，例如连续线性层、注意力 O/V 投影或 MLP Up/Down 投影。 |
| 105 | +- 搜索候选时应使用与最终目标一致的激活/权重量化方式；权重侧常与 [SSZ](../ssz/term_ssz.md) 配合。 | ||
| 106 | +- 自动搜索会多次执行候选量化与误差比较，精度收益以更高的校准时间为代价。 | ||
| 107 | + | ||
| 108 | +这些限制反映了算法对模型结构和等价变换条件的依赖。若目标模型不满足相应结构假设，强行套用可能破坏原有计算关系；因此遇到不兼容结构时应优先缩小作用范围或使用模型已验证的配方，而不是盲目增大平滑强度。 | ||
| 138 | 109 | ||
| 139 | --- | 110 | --- |
| 140 | 111 | ||
| 141 | -## 7. 关联流程 | 112 | +## 3. 关联词条 |
| 142 | 113 | ||
| 143 | -- 《[一键量化 (V1)](../../../user_guide/usage_quick_quantization.md)》：默认集成本算法作为离群值抑制前置步骤。 | 114 | +可以从“同类方法、前后处理关系和应用对象”三个方向理解本词条与其他算法的关系。下面的关联项既用于横向比较不同技术路线，也用于帮助定位该算法在完整量化方案中的位置。 |
| 144 | -- 《[量化精度调优指南](../../../user_guide/process_quantization_precision_tuning.md)》：精度不达标时可考虑启用本算法。 | ||
| 145 | - | ||
| 146 | ---- | ||
| 147 | - | ||
| 148 | -## 8. 关联词条 | ||
| 149 | 115 | ||
| 150 | - [AWQ](../awq_smooth/term_awq_smooth.md)：上位概念，本算法结合 AWQ 的激活感知思想。 | 116 | - [AWQ](../awq_smooth/term_awq_smooth.md)：上位概念，本算法结合 AWQ 的激活感知思想。 |
| 151 | - [Flex Smooth Quant](../flex_smooth_quant/term_flex_smooth_quant.md)：同类算法，使用模拟量化评估参数。 | 117 | - [Flex Smooth Quant](../flex_smooth_quant/term_flex_smooth_quant.md)：同类算法，使用模拟量化评估参数。 |
| 152 | -- [SSZ](../ssz/term_ssz.md)：配套术语，本算法的 `qconfig.weight` 通常使用 SSZ 权重量化方法。 | 118 | +- [SSZ](../ssz/term_ssz.md)：配套术语，本算法的权重侧通常配合 SSZ 权重量化方法。 |
| 153 | - [SmoothQuant](../smooth_quant/term_smooth_quant.md)：上位概念，本算法属于平滑类离群值抑制算法族。 | 119 | - [SmoothQuant](../smooth_quant/term_smooth_quant.md)：上位概念，本算法属于平滑类离群值抑制算法族。 |
| 154 | - [AutoRound](../autoround/term_autoround.md)：配套术语，低比特量化前常配合本算法使用。 | 120 | - [AutoRound](../autoround/term_autoround.md)：配套术语，低比特量化前常配合本算法使用。 |
| 155 | 121 | ||
| 156 | --- | 122 | --- |
| 157 | 123 | ||
| 158 | -## 9. 参考资料 | 124 | +## 4. 参考文档 |
| 125 | + | ||
| 126 | +参考文档优先列出算法原始论文或权威出处，并补充仓库内对应使用指南。需要进一步理解参数选择时，可先阅读使用指南，再回到原论文核对算法假设和推导。 | ||
| 159 | 127 | ||
| 160 | 1. Lin J et al. AWQ: Activation-aware Weight Quantization for LLM Compression and Acceleration. MLSys 2024. https://arxiv.org/abs/2306.00978 | 128 | 1. Lin J et al. AWQ: Activation-aware Weight Quantization for LLM Compression and Acceleration. MLSys 2024. https://arxiv.org/abs/2306.00978 |
| 161 | -2. 《Flex AWQ SSZ 使用指南》([./usage_flex_awq_ssz.md](./usage_flex_awq_ssz.md)) | 129 | +2. 《[Flex AWQ SSZ 参数配置流程指南](./usage_flex_awq_ssz.md)》 |
| @@ -1,179 +1,129 @@ | |||
| 1 | -# Flex AWQ SSZ 使用指南 | 1 | +# Flex AWQ SSZ 参数配置流程指南 |
| 2 | 2 | ||
| 3 | ## 1. 适用范围 | 3 | ## 1. 适用范围 |
| 4 | 4 | ||
| 5 | -本流程适用于在 msModelSlim 中配置和使用 Flex AWQ SSZ 灵活激活感知权重量化平滑算法。Flex AWQ SSZ 作为离群值抑制算法，通常作为量化前的预处理步骤，通过真实量化器评估参数、自动搜索最优 `alpha` 抑制激活离群值，提升低比特量化的精度。 | 5 | +Flex AWQ SSZ 灵活激活感知权重量化平滑算法。Flex AWQ SSZ 作为离群值抑制算法，通常作为量化前的预处理步骤，通过真实量化器评估参数、自动搜索最优 `alpha` 抑制激活离群值，提升低比特量化的精度。 |
| 6 | 6 | ||
| 7 | -适用角色：算法工程师、模型部署工程师 | 7 | +本指南面向首次配置 Flex AWQ SSZ 的用户，重点不是展开完整执行命令，而是说明推荐配置为什么适合作为起点、哪些参数真正需要调，以及出现精度或资源问题时应优先改哪一项。这类算法的主要作用是先改善待量化张量的数值分布，再交给后续量化步骤处理，本身通常不是最终的量化格式。因此判断配置是否合适时，不仅要看平滑或旋转后的张量范围，还要看与后续量化组合后的端到端精度；建议保持后续量化配置不变，只调整当前算法参数。 |
| 8 | 8 | ||
| 9 | -适用场景： | 9 | +如果目标模型已经有完整且已验证的量化配方，应优先复用该配方；若当前算法与目标模型结构、数值格式或部署后端不兼容，不应通过增大搜索强度或扩大作用范围来绕过支持约束。 |
| 10 | 10 | ||
| 11 | -- 需要对平滑参数进行真实量化器评估、追求更高精度的低比特量化场景。 | 11 | +## 2. 输入和交付件 |
| 12 | -- 需要同时对注意力 `ov`、MLP `up-down`、连续线性层等多种结构做离群值抑制的场景。 | ||
| 13 | - | ||
| 14 | -不适用场景： | ||
| 15 | - | ||
| 16 | -- 模型未实现 `FlexSmoothQuantInterface` 接口，或无子图映射配置。 | ||
| 17 | -- 未配置 `qconfig`（必填参数）。 | ||
| 18 | - | ||
| 19 | -## 2. 流程关系与前置条件 | ||
| 20 | - | ||
| 21 | -**上级流程**：模型适配与验证通过后，确定量化方案阶段。 | ||
| 22 | - | ||
| 23 | -**前置条件**： | ||
| 24 | - | ||
| 25 | -- 已安装兼容版本的 msModelSlim 工具（详见《[msModelSlim 工具安装指南](../../../install_guide/install_guide.md)》）。 | ||
| 26 | -- 已确认目标模型适配器实现了 `FlexSmoothQuantInterface` 接口，并正确配置子图映射。 | ||
| 27 | -- 已确定下游量化方案（如 W4A4、W8A8），以便配置 `qconfig` 与 `alpha`。 | ||
| 28 | -- 已准备好校准数据集，用于收集激活统计信息。 | ||
| 29 | - | ||
| 30 | -**后续操作**：量化流程执行 → 精度验证 → 部署上线或进入调优。 | ||
| 31 | - | ||
| 32 | -## 3. 输入和交付件 | ||
| 33 | 12 | ||
| 34 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | | 13 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | |
| 35 | | --- | --- | --- | --- | --- | | 14 | | --- | --- | --- | --- | --- | |
| 36 | -| 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被目标 Transformers 版本加载 | | 15 | +| 输入 | 目标模型与量化目标 | 待量化模型及部署/评测方案 | 明确目标数值格式或位宽、作用模块、精度/性能目标以及部署约束 | 能说明为什么选择本算法以及它在整体量化方案中的位置 | |
| 37 | -| 输入 | 校准数据集 | 工具默认或用户指定 | JSONL 格式，每条含文本 prompt | 可被工具加载并完成前向推理 | | 16 | +| 输入 | 配置约束与实践基线 | 本算法配置说明、目标模型已有 `lab_practice` 配方（如有） | 字段名、支持组合、作用范围和模型适配与当前版本一致 | 推荐起点能够追溯到当前配置定义或已验证实践 | |
| 38 | -| 输入 | 量化 YAML 配置文件 | 用户编写 | 符合 msModelSlim YAML 规范，含 `flex_awq_ssz` 处理器及 `qconfig` 配置 | 可通过工具 `--config_path` 参数加载 | | 17 | +| 输入 | 校准数据（算法需要时） | 任务 `dataset`、校准集或模型实践配方 | 数据应能代表真实输入分布；多阶段算法尽量保持各阶段数据分布一致 | 能被当前量化流程正常读取，并覆盖主要输入形态 | |
| 39 | -| 交付件 | 平滑后的量化权重目录 | `--save_path` 指定路径 | 含 `quant_model_description.json` 及 `*.safetensors`，已应用平滑缩放 | 推理冒烟通过 | | 18 | +| 交付件 | Flex AWQ SSZ 参数配置方案 | 用户量化 YAML 或任务配置 | 参数取值合法、作用范围明确；关键参数说明选择依据 | 可作为后续量化流程的算法配置输入，并可复现本指南中的基线选择 | |
| 40 | 19 | ||
| 41 | -## 4. 流程总览 | 20 | +## 3. 流程总览 |
| 21 | + | ||
| 22 | +入门时建议先用一组稳定配置建立基线，再围绕影响最大的参数做单变量调整。下面的流程强调“先选参数、再看效果”，不展开量化命令本身。 | ||
| 42 | 23 | ||
| 43 | ```mermaid | 24 | ```mermaid |
| 44 | flowchart LR | 25 | flowchart LR |
| 45 | - A[编写 YAML 配置] --> B[执行量化命令] | 26 | + A[确定 W4A8 等目标格式] --> B[用真实量化器评估候选缩放] |
| 46 | - B --> C[收集激活均值] | 27 | + B[用真实量化器评估候选缩放] --> C[搜索 alpha] |
| 47 | - C --> D[搜索并融合缩放] | 28 | + C[搜索 alpha] --> D[融合缩放] |
| 48 | - D --> E[验证量化结果] | 29 | + D[融合缩放] --> E[进入后续量化] |
| 49 | ``` | 30 | ``` |
| 50 | 31 | ||
| 51 | -## 5. 操作步骤 | 32 | +实际使用时建议把流程理解为“建立基线—观察结果—单变量调整—再次验证”的闭环。流程图中的前几个节点用于固定量化对象、统计信息或初始参数，后几个节点用于应用算法并检查结果；如果效果不理想，应优先回到最近一次修改的参数，而不是同时更换位宽、粒度、作用范围和算法强度。这样可以明确每次变化的因果关系，也便于把有效配置沉淀为后续模型配方。 |
| 52 | 33 | ||
| 53 | -### 步骤 1：编写 YAML 配置文件 | 34 | +## 4. 操作步骤 |
| 54 | 35 | ||
| 55 | -**目标**：编写包含 `flex_awq_ssz` 处理器与 `qconfig` 配置的 YAML 文件。 | 36 | +### 步骤 1：确认目标与约束 |
| 37 | + | ||
| 38 | +**操作**：先固定目标模型、最终量化格式/位宽、作用对象和评测基线，再确认当前版本支持的参数组合。目标模型已有 `lab_practice` 配方时，优先把该配方作为实践基线；没有模型专用配方时，再使用本指南给出的通用推荐起点。若算法依赖校准统计或优化数据，还应在调参前固定代表性数据，避免把数据分布变化误判为参数收益。 | ||
| 39 | + | ||
| 40 | +**输出**：一份明确的配置目标：目标位宽/格式、处理范围、校准条件、评测基线和部署约束。 | ||
| 41 | + | ||
| 42 | +### 步骤 2：建立推荐基线 | ||
| 56 | 43 | ||
| 57 | **操作**： | 44 | **操作**： |
| 58 | 45 | ||
| 59 | -1. 在 `spec.process` 下配置 `flex_awq_ssz` 处理器，指定 `type: "flex_awq_ssz"`。 | 46 | +下面配置用于建立**第一版可比较基线**。如果目标模型已有 `lab_practice` 配方，优先使用已验证配方，再参考本节理解每个参数为什么这样选。 |
| 60 | -2. 配置必填的 `qconfig`，包含 `act` 与 `weight` 的量化配置（权重通常使用 `method: "ssz"`）。 | ||
| 61 | -3. 可选配置 `alpha`（默认自动搜索）以及 `enable_subgraph_type`、`include`/`exclude`。 | ||
| 62 | - | ||
| 63 | -YAML 配置示例： | ||
| 64 | 47 | ||
| 65 | ```yaml | 48 | ```yaml |
| 66 | spec: | 49 | spec: |
| 67 | process: | 50 | process: |
| 68 | - - type: "flex_awq_ssz" # 固定为 `flex_awq_ssz`，用于指定 Processor。 | 51 | + - type: "flex_awq_ssz" |
| 69 | - alpha: 0.8 # 激活缩放的系数，取值范围为0-1之间，默认值为None（自动搜索），也支持用户自行配置。 | 52 | + # alpha 省略时自动搜索，通常比手工固定值更稳妥。 |
| 70 | - qconfig: # 量化配置，为必填参数。 | 53 | + qconfig: |
| 71 | - act: # 激活值量化配置。 | 54 | + act: |
| 72 | - scope: "per_token" # 量化范围：per_token 或 per_tensor。 | 55 | + scope: "per_token" |
| 73 | - dtype: "int8" # 量化数据类型：int8。 | 56 | + dtype: "int8" |
| 74 | - symmetric: True # 是否对称量化：True 或 False。 | 57 | + symmetric: true |
| 75 | - method: "minmax" # 量化方法：minmax 或其他方法。 | 58 | + method: "minmax" |
| 76 | - weight: # 权重量化配置。 | 59 | + weight: |
| 77 | - scope: "per_channel" # 量化范围：per_channel。 | 60 | + scope: "per_channel" |
| 78 | - dtype: "int4" # 量化数据类型：int4 或 int8。 | 61 | + dtype: "int4" |
| 79 | - symmetric: True # 是否对称量化：True。 | 62 | + symmetric: true |
| 80 | - method: "ssz" # 量化方法：ssz（Smooth Scale Zero）。 | 63 | + method: "ssz" |
| 81 | - ext: # 扩展配置（可选）。 | 64 | + ext: |
| 82 | - step: 10 # SSZ方法的步长参数。 | 65 | + step: 10 |
| 83 | - enable_subgraph_type: # 字符串列表，指定启用的子图类型，默认启用所有四种类型。 | 66 | + enable_subgraph_type: |
| 84 | - - 'norm-linear' | 67 | + - "norm-linear" |
| 85 | - - 'linear-linear' | 68 | + - "linear-linear" |
| 86 | - - 'ov' | 69 | + - "ov" |
| 87 | - - 'up-down' | 70 | + - "up-down" |
| 88 | - include: ["*"] # 包含的层，支持通配符。 | 71 | + include: ["*"] |
| 89 | - exclude: ["*self_attn*"] # 排除的层，支持通配符。 | 72 | + exclude: [] |
| 90 | ``` | 73 | ``` |
| 91 | 74 | ||
| 92 | -YAML 配置字段详解如下： | 75 | +上面的推荐值用于建立第一版可复现基线，其中最值得关注的配置包括 `type`, `alpha`, `qconfig`, `enable_subgraph_type`。推荐值并不表示所有模型都只能使用该组合，而是优先选择仓库默认值、已验证实践或较稳健的中间取值，以降低第一次使用时同时遇到精度和兼容性问题的概率。如果目标模型已经有 `lab_practice` 配方，应优先复用该配方；只有在基线精度、显存或吞吐不满足目标时，再按照下一节的参数说明逐项调整。 |
| 93 | 76 | ||
| 94 | -| 字段名 | 作用 | 说明 | | 77 | +**输出**：一份可复现的推荐基线配置，后续所有参数调整均以此为比较对象。 |
| 95 | -| --- | --- | --- | | ||
| 96 | -| type | 处理器类型标识 | 固定为 `"flex_awq_ssz"`。 | | ||
| 97 | -| alpha | 激活缩放权重系数 | 0~1 之间的浮点数，默认 `None`（自动搜索）。 | | ||
| 98 | -| qconfig | 量化配置 | 必填参数，包含激活值（`act`）和权重（`weight`）的量化配置，用于真实量化器评估。 | | ||
| 99 | -| enable_subgraph_type | 开启的子图类型 | 支持 `norm-linear`、`linear-linear`、`ov`、`up-down`。 | | ||
| 100 | -| include | 包含的层 | 字符串列表，支持通配符匹配。 | | ||
| 101 | -| exclude | 排除的层 | 字符串列表，支持通配符匹配。 | | ||
| 102 | 78 | ||
| 103 | -**输出**：YAML 配置文件 `${CONFIG_PATH}`。 | 79 | +### 步骤 3：选择并调整参数 |
| 104 | - | ||
| 105 | -### 步骤 2：执行量化命令 | ||
| 106 | - | ||
| 107 | -**目标**：使用上一步编写的 YAML 配置文件启动量化流程。 | ||
| 108 | 80 | ||
| 109 | **操作**： | 81 | **操作**： |
| 110 | 82 | ||
| 111 | -```bash | 83 | +参数选择建议按三个层次理解：首先确认 `dtype/scope/method` 等**算法支持约束**，这类字段不是任意可调；其次确定 `include/exclude`、子图类型等**作用范围**；最后再调整会改变误差与开销的数值参数。下面的推荐值区分了代码默认值、仓库 `lab_practice` 中已验证的实践值和适合首次使用的推荐起点。如果目标模型已有实践配置，优先沿用实践配置，再根据本节说明做单变量调整。 |
| 112 | -msmodelslim quant \ | ||
| 113 | - --model_path ${MODEL_PATH} \ | ||
| 114 | - --save_path ${SAVE_PATH} \ | ||
| 115 | - --device npu \ | ||
| 116 | - --model_type ${MODEL_TYPE} \ | ||
| 117 | - --config_path ${CONFIG_PATH} \ | ||
| 118 | - --trust_remote_code True | ||
| 119 | -``` | ||
| 120 | 84 | ||
| 121 | -参数说明： | 85 | +| 配置项 | 含义（原理） | 推荐配置 | 选择与调整建议 | |
| 86 | +| --- | --- | --- | --- | | ||
| 87 | +| `type` | 处理器标识，固定为 `flex_awq_ssz`。 | 固定。 | 不调。 | | ||
| 88 | +| `alpha` | 控制激活统计在平滑尺度中的指数权重。当前实现如果未提供 `alpha` 会用真实 `qconfig` 模拟量化误差搜索 alpha；因此省略它会把选择交给数据驱动搜索。 | 推荐省略 `alpha` 让算法搜索；有经过同模型同 qconfig 验证的固定值时才手工设置。 | 手工值只对当前校准分布、子图和 qconfig 有意义。最终权重位宽、SSZ 设置或子图范围变化后，应重新搜索而不是照搬旧 alpha。 | | ||
| 89 | +| `beta` | 配置层面提供 0~1 的系数，但当前 FlexAWQSSZ 搜索/应用路径把 beta 固定为 `0`，主要优化 alpha；它与 FlexSmoothQuant 的双参数搜索行为不同。 | 通常省略/保持默认，不把 beta 当作当前版本的主要调参旋钮。 | 除非后续实现/模型配方明确使用 beta，否则不要根据 FlexSmoothQuant 的经验手动调 beta；当前算法的主要选择依据是 alpha + 真实 qconfig。 | | ||
| 90 | +| `qconfig` | 搜索时直接构造最终线性量化器来评价候选平滑尺度，因此 qconfig 是 AWQ 搜索目标的一部分。DeepSeek/GLM W4A8 实践统一使用激活 INT8 per-token MinMax + 权重 INT4 per-channel SSZ，并在 SSZ 中配置 `step: 10`。 | W4A8 目标可优先使用仓库验证组合；其他目标必须改成真正的最终 qconfig。 | qconfig 任一关键项改变都应重新搜索 alpha。特别是权重从 MinMax 换 SSZ、INT8 换 INT4，会改变候选尺度的真实量化误差。 | | ||
| 91 | +| `qconfig.weight.ext.step` | 传给 SSZ 的最大迭代次数。SSZ 内部默认最多 50 次并支持提前收敛，仓库 FlexAWQSSZ 实践使用 `10` 来平衡搜索代价。 | 复用 W4A8 实践时用 `10`；独立模型精度优先且时间允许时可省略，让 SSZ 使用默认最多 50 次。 | step 太小可能让每个 alpha 候选下的 SSZ 还未充分优化，进而影响 alpha 排序；但过大也会显著放大“外层 alpha 搜索 × 内层 SSZ”成本。先固定 qconfig，再在时间/收敛之间选择。 | | ||
| 92 | +| `enable_subgraph_type` | 决定在哪类可融合子图上执行。虽然默认支持四类，但当前仓库 5 个 FlexAWQSSZ 实践均只启用 `["up-down"]`，说明模型配方常会有意收窄范围。 | 有实践配方时完全照其子图类型；无配方时不要机械照抄“默认四类”，先根据模型结构和目标层选择。 | 扩大子图类型会增加搜索与变换范围，也可能引入不适配结构。若算法本来只为 MLP up/down 低比特优化，先从 `up-down` 建立基线更容易解释。 | | ||
| 93 | +| `include` | 作用范围白名单，使用模块名模式决定哪些匹配到的模块进入当前算法。它只决定“在哪些模块做”，不会改变算法内部公式。 | 无模型专用配方时从 `["*"]` 开始；已有 `lab_practice` 时直接沿用其模块范围。 | 先保证范围覆盖预期模块，再看精度。范围过宽时，少数结构不兼容或敏感层会放大整体风险；范围过窄则可能让算法收益看不出来。收窄范围时优先按结构族或已知敏感层调整，不建议仅凭层号大面积删除。 | | ||
| 94 | +| `exclude` | 作用范围黑名单，命中后从 `include` 的候选中排除，优先级高于 `include`。适合保护敏感层、首尾层或模型专用不兼容结构。 | 默认先保持空列表；只有实践配方、兼容性约束或敏感性结果给出明确证据时再加入。 | 局部精度问题优先通过 `exclude` 做小范围回退，比提高全模型位宽或关闭整个算法更容易保留收益。每次增加排除项后应确认通配符没有误伤相邻模块。 | | ||
| 122 | 95 | ||
| 123 | -| 参数 | 必选 | 说明 | | 96 | +### 参数组合与选择顺序 |
| 124 | -| --- | --- | --- | | ||
| 125 | -| `model_path` | 是 | 浮点模型权重路径 | | ||
| 126 | -| `save_path` | 是 | 量化权重保存路径 | | ||
| 127 | -| `device` | 否 | 量化设备，默认 `npu` | | ||
| 128 | -| `model_type` | 是 | 模型名称，与支持矩阵一致 | | ||
| 129 | -| `config_path` | 是 | 步骤 1 编写的 YAML 配置路径 | | ||
| 130 | -| `trust_remote_code` | 否 | 是否信任远程代码，默认 `False` | | ||
| 131 | 97 | ||
| 132 | -执行流程说明： | 98 | +1. **先锁定部署目标与支持组合**：先确定最终位宽/数值格式，再确认当前量化器实际注册了对应的 `dtype + scope + symmetric + method` 组合；不要为了追求某个参数值而越过支持约束。 |
| 99 | +2. **再固定作用范围**：使用已有模型配方时，先复用其 `include/exclude` 或子图类型；没有配方时先建立覆盖范围明确的基线，确认算法确实作用到了预期模块。 | ||
| 100 | +3. **最后只调一个主要旋钮**：数值搜索步数、平滑强度、分组大小等一次只改一项，并保持同一校准集和评测集。若调整后没有稳定收益，回到上一个基线，而不是继续叠加多个变化。 | ||
| 133 | 101 | ||
| 134 | -1. 工具加载 YAML 配置，解析 `flex_awq_ssz` 处理器与 `qconfig`。 | 102 | +FlexAWQSSZ 的参数耦合非常强：**先锁定最终 qconfig → 再锁定子图 → 最后搜索 alpha**。SSZ `step` 同时影响每个候选的评价质量和总搜索时间，因此不要和 alpha 手工值同时大幅修改。 |
| 135 | -2. 预处理阶段发现子图并收集激活统计信息。 | ||
| 136 | -3. 后处理阶段使用真实量化器搜索最优 `alpha` 并融合缩放。 | ||
| 137 | -4. 继续执行下游量化处理器并保存量化权重。 | ||
| 138 | 103 | ||
| 139 | -**输出**：量化权重目录 `${SAVE_PATH}`，包含量化描述文件与权重分片。 | 104 | +**输出**：一份完成单变量调整的算法参数方案，关键字段均有明确的选择依据和调整方向。 |
| 140 | 105 | ||
| 141 | -### 步骤 3：验证量化结果 | 106 | +### 步骤 4：根据结果收敛参数方案 |
| 142 | - | ||
| 143 | -**目标**：确认量化权重文件完整且可加载。 | ||
| 144 | 107 | ||
| 145 | **操作**： | 108 | **操作**： |
| 146 | 109 | ||
| 147 | -1. 检查输出目录是否包含 `quant_model_description.json` 文件。 | 110 | +调参时建议先记录一份完整基线，包括使用的数据集、量化范围、关键参数和端到端指标。每轮只改变一个变量，并把变化结果与基线直接比较；如果某项调整带来收益，再继续小步搜索其邻近取值。对于只有少数层或模块异常的情况，优先采用局部排除、局部回退或混合精度，而不是直接提高全模型精度配置，这通常更容易保留压缩和性能收益。 |
| 148 | -2. 检查日志确认无层匹配告警。 | ||
| 149 | -3. 使用推理框架加载量化权重进行冒烟测试。 | ||
| 150 | 111 | ||
| 151 | -**输出**：量化权重验证通过。 | 112 | +- **先跑推荐基线，再调单变量。** 不要同时修改位宽、粒度、算法参数和层范围，否则很难判断精度变化来自哪一项。 |
| 113 | +- **优先回退局部，而不是整体提高精度。** 如果只有少数层敏感，优先通过 `exclude` 或混合策略保留高精度，通常比整体升位宽更划算。 | ||
| 114 | +- **最终以模型实践配置和部署能力为准。** 入门推荐用于建立稳定起点；目标模型已有 `lab_practice` 配方时，应优先复用已验证组合。 | ||
| 152 | 115 | ||
| 153 | -## 6. 验收条件 | 116 | +**输出**：一份可进入后续量化流程的最终参数方案，并保留相对于推荐基线的调整记录。 |
| 154 | 117 | ||
| 155 | -- 量化权重目录包含 `quant_model_description.json` 及所有必需的 `*.safetensors` 分片文件。 | 118 | +## 5. 术语 |
| 156 | -- 日志无 `qconfig` 缺失或模块名不匹配告警。 | ||
| 157 | -- 量化后模型推理精度不低于未使用 Flex AWQ SSZ 的基线。 | ||
| 158 | - | ||
| 159 | -## 7. 异常处置 | ||
| 160 | - | ||
| 161 | -- **qconfig 配置缺失**：报错提示 `qconfig` 为必填参数，在 YAML 配置中添加 `qconfig` 字段（含 `act` 与 `weight`）。 | ||
| 162 | -- **模块名不匹配**：`include/exclude` 未命中时日志提示未匹配模式，核对完整模块名是否与 `named_modules()` 返回的路径一致。 | ||
| 163 | -- **子图类型不支持**：确保配置的子图类型在支持列表中（`norm-linear`、`linear-linear`、`ov`、`up-down`）。 | ||
| 164 | -- **映射关系错误**：检查 `MappingConfig` 中的 `source` 与 `targets` 是否指向正确的模块。 | ||
| 165 | - | ||
| 166 | -## 8. 术语 | ||
| 167 | 119 | ||
| 168 | | 术语 | 简述 | 链接 | | 120 | | 术语 | 简述 | 链接 | |
| 169 | | --- | --- | --- | | 121 | | --- | --- | --- | |
| 170 | -| Flex AWQ SSZ | 结合 AWQ 与 SSZ、使用真实量化器评估参数的平滑算法 | [Flex AWQ SSZ 词条](./term_flex_awq_ssz.md) | | 122 | +| Flex AWQ SSZ 灵活激活感知权重量化平滑算法 | 说明该算法的定义、核心原理、关键性质、适用场景与限制。 | 《[Flex AWQ SSZ 灵活激活感知权重量化平滑算法 量化术语百科词条](./term_flex_awq_ssz.md)》 | |
| 171 | -| qconfig | 激活与权重的量化配置，供真实量化器评估使用 | [Flex AWQ SSZ 词条](./term_flex_awq_ssz.md) | | ||
| 172 | -| 离群值抑制 | 通过数值变换减少激活离群值、降低量化误差 | [量化算法总览](../README.md) | | ||
| 173 | 123 | ||
| 174 | -## 9. 接口文档列表 | 124 | +## 6. 接口文档列表 |
| 175 | 125 | ||
| 176 | | 接口或能力 | 简述 | 链接 | | 126 | | 接口或能力 | 简述 | 链接 | |
| 177 | | --- | --- | --- | | 127 | | --- | --- | --- | |
| 178 | -| `flex_awq_ssz` 处理器 | 用于执行灵活激活感知平滑的 Processor 配置 | [Flex AWQ SSZ 词条](./term_flex_awq_ssz.md) | | 128 | +| flex_awq_ssz 配置说明 | 字段类型、默认值、合法取值与完整配置约束。 | 《[flex_awq_ssz 配置说明](../../../api_reference/config/processor/flex_awq_ssz.md)》 | |
| 179 | -| `FlexSmoothQuantInterface` | 模型适配器需实现的平滑接口（与 Flex Smooth Quant 相同） | [Flex AWQ SSZ 词条](./term_flex_awq_ssz.md) | | 129 | +| modelslim_v1 配置说明 | 需要继续探索 runner、prior、save、dataset 等任务级高级配置时查阅。 | 《[modelslim_v1 配置说明](../../../api_reference/config/task/modelslim_v1.md)》 | |
| @@ -1,15 +1,14 @@ | |||
| 1 | -# Flex Smooth Quant 灵活平滑量化算法词条 | 1 | +# Flex Smooth Quant 灵活平滑量化算法 量化术语百科词条 |
| 2 | 2 | ||
| 3 | -> **词条类别**：离群值抑制算法 | 3 | +> **词条类别**：[离群值抑制算法](../README.md#1-离群值抑制算法)<br> |
| 4 | -> **英文名称**：Flex Smooth Quant | 4 | +> **英文名称**：flex_smooth_quant<br> |
| 5 | -> **应用领域**：大语言模型量化压缩、推理加速 | 5 | +> **应用领域**：大语言模型量化压缩、推理加速<br> |
| 6 | -> **msModelSlim 实现**：`msmodelslim/processor/anti_outlier/flex_smooth/` | ||
| 7 | 6 | ||
| 8 | --- | 7 | --- |
| 9 | 8 | ||
| 10 | ## 1. 概述 | 9 | ## 1. 概述 |
| 11 | 10 | ||
| 12 | -Flex Smooth Quant（灵活平滑量化）是一种用于大语言模型量化过程中抑制激活离群值的算法。它通过二阶段网格搜索自动寻找最优的 `alpha` 与 `beta` 参数，在激活与权重之间实现更精细的缩放平衡，从而适配不同模型架构与量化需求。其核心特征是：参数可自动搜索、支持 `norm-linear`、`linear-linear`、`ov`、`up-down` 多子图类型，并支持对独立线性层做非融合平滑，是 [SmoothQuant](../smooth_quant/term_smooth_quant.md) 的灵活扩展。 | 11 | +Flex Smooth Quant 是 [SmoothQuant](../smooth_quant/term_smooth_quant.md) 的可搜索扩展，用于在激活与权重之间自动寻找更合适的缩放平衡。它通过分阶段搜索 `alpha`、`beta` 等参数，适配不同子图结构和数据分布，以降低平滑后量化误差；核心特征是多子图支持、参数自动搜索和可配置的融合/非融合平滑。 |
| 13 | 12 | ||
| 14 | --- | 13 | --- |
| 15 | 14 | ||
| @@ -17,15 +16,21 @@ Flex Smooth Quant（灵活平滑量化）是一种用于大语言模型量化过 | |||
| 17 | 16 | ||
| 18 | 传统 [SmoothQuant](../smooth_quant/term_smooth_quant.md) 使用固定的 `alpha` 且仅支持 `norm-linear` 子图，对复杂结构适配不足。Flex Smooth Quant 将缩放公式推广为激活与权重分别使用 `alpha` 与 `beta` 两个指数，并通过网格搜索自动寻找最优参数，避免了人工调参，同时扩展了对多子图类型的支持。 | 17 | 传统 [SmoothQuant](../smooth_quant/term_smooth_quant.md) 使用固定的 `alpha` 且仅支持 `norm-linear` 子图，对复杂结构适配不足。Flex Smooth Quant 将缩放公式推广为激活与权重分别使用 `alpha` 与 `beta` 两个指数，并通过网格搜索自动寻找最优参数，避免了人工调参，同时扩展了对多子图类型的支持。 |
| 19 | 18 | ||
| 20 | ---- | 19 | +从量化流程中的定位看，该算法更接近量化前的分布整形步骤：先降低离群值对量化尺度的支配，再由后续量化算法完成真正的离散化。这种思路的价值在于不必简单扩大位宽，而是通过重分配、旋转或平滑数值幅度，提高有限量化区间对主体数据分布的利用率。 |
| 21 | 20 | ||
| 22 | -## 3. 原理 | 21 | +### 2.1 核心思想 |
| 23 | 22 | ||
| 24 | -### 1. 核心思想 | 23 | +Flex Smooth Quant 的核心思想是把平滑缩放从受约束的单指数关系扩展为 $\alpha$ 与 $\beta$ 两个相对独立的指数，使激活峰值和权重峰值对最终尺度的影响可以分别调节。算法通过两阶段候选搜索寻找联合量化输出误差较小的组合，从而适应不同层、不同计算子图中不一致的激活/权重离群程度。 |
| 25 | 24 | ||
| 26 | -Flex Smooth Quant 的核心思想是把平滑缩放公式从“单一 `alpha`”扩展为“`alpha` + `beta` 双指数”：当用户不指定参数时，通过二阶段网格搜索在激活与权重之间寻找最优的缩放平衡，使不同子图结构都能获得接近最优的离群值抑制效果。 | 25 | +双指数自由度能处理“激活离群程度”和“权重离群程度”并不满足固定互补关系的层。 |
| 27 | 26 | ||
| 28 | -### 2. 数学描述 | 27 | +### 2.2 工作机制 |
| 28 | + | ||
| 29 | +Flex Smooth Quant 将标准 SmoothQuant 中相互绑定的指数关系拆开。尺度可写成 $s_j=A_j^{\alpha}W_j^{-\beta}$：$\alpha$ 控制激活峰值对尺度的推动程度，$\beta$ 控制权重峰值对尺度的抑制程度。这样可以在更大的二维区域内寻找“激活更好量化、权重也不过度恶化”的平衡，而不是限定在 $\beta=1-\alpha$ 的单条曲线上。 | ||
| 30 | + | ||
| 31 | +自动搜索通常先沿 $\beta=1-\alpha$ 的受约束路径寻找一个稳定起点，再固定较优 $\alpha$ 搜索 $\beta$。每个候选都会先执行等价缩放，再分别对缩放后的激活和权重做模拟量化，最后比较线性输出的归一化误差。两阶段搜索减少了直接二维穷举的成本，也让第二阶段能够在已找到合理激活迁移强度的基础上放松权重侧约束。 | ||
| 32 | + | ||
| 33 | +### 2.3 数学描述 | ||
| 29 | 34 | ||
| 30 | 缩放因子计算公式： | 35 | 缩放因子计算公式： |
| 31 | 36 | ||
| @@ -40,103 +45,52 @@ $$ | |||
| 40 | - $\beta$：权重缩放系数，控制权重对缩放因子的影响程度（$0$~$1$） | 45 | - $\beta$：权重缩放系数，控制权重对缩放因子的影响程度（$0$~$1$） |
| 41 | - $10^{-5}$：缩放因子的最小值，防止数值不稳定 | 46 | - $10^{-5}$：缩放因子的最小值，防止数值不稳定 |
| 42 | 47 | ||
| 43 | -当 `alpha`/`beta` 未配置时，算法在参数空间内以网格搜索方式评估候选组合，选择量化误差最小的参数。 | 48 | +算法可在 $\alpha$、$\beta$ 候选空间中比较联合量化后的输出误差，以数据驱动方式确定平滑强度。 |
| 44 | 49 | ||
| 45 | -### 3. 关键性质 | 50 | +设逐通道激活峰值为 $A_j$、权重峰值为 $W_j$，一般化尺度可写为： |
| 46 | 51 | ||
| 47 | -- **双指数缩放**：激活与权重分别使用 `alpha` 与 `beta`，缩放更精细。 | 52 | +$$ |
| 48 | -- **自动搜索**：未配置参数时自动搜索最优 `alpha`/`beta`，减少人工调参。 | 53 | +s_j=\frac{A_j^{\alpha}}{W_j^{\beta}},\qquad X'_j=X_j/s_j,\qquad W'_{:,j}=W_{:,j}s_j. |
| 49 | -- **子图类型多样**：支持 `norm-linear`、`linear-linear`、`ov`、`up-down` 四种子图。 | 54 | +$$ |
| 50 | -- **非融合能力**：`source=None` 时对独立线性层做输入侧 pre-hook 缩放。 | 55 | + |
| 56 | +浮点域仍满足 $X'W'^T=XW^T$。若激活和权重都量化，则输出误差近似包含： | ||
| 57 | + | ||
| 58 | +$$ | ||
| 59 | +\Delta Y\approx E_XW'^T+X'E_W^T+E_XE_W^T, | ||
| 60 | +$$ | ||
| 61 | + | ||
| 62 | +其中 $E_X=\mathcal Q(X')-X'$、$E_W=\mathcal Q(W')-W'$。这说明两侧误差不仅各自存在，还会出现交叉项，因此联合搜索比单看某一侧张量误差更有意义。 | ||
| 63 | + | ||
| 64 | +### 2.4 关键性质 | ||
| 65 | + | ||
| 66 | +- **双指数缩放**：激活与权重统计分别由 $\alpha$ 与 $\beta$ 控制，尺度自由度更高。 | ||
| 67 | +- **两阶段搜索**：先沿受约束关系搜索稳定起点，再放松另一个指数以扩大可选解空间。 | ||
| 68 | +- **图结构可扩展**：只要缩放能在相邻算子之间被等价吸收，就可以把同一平滑思想应用到不同线性子图。 | ||
| 69 | +- **独立层平滑**：除可融合的相邻子图外，也可对缺少前置融合源的独立线性层做输入侧缩放。 | ||
| 51 | - **计算等价性**：协同缩放保持整体计算等价，不改变模型输出。 | 70 | - **计算等价性**：协同缩放保持整体计算等价，不改变模型输出。 |
| 71 | +- **双指数自由度**：允许激活侧与权重侧的尺度影响独立调节，不受 $\beta=1-\alpha$ 的固定关系限制。 | ||
| 52 | 72 | ||
| 53 | ---- | 73 | +但自由度增加也意味着搜索更依赖数据。过大的 $\alpha$ 会使激活更平滑却放大权重，过大的 $\beta$ 则可能把尺度压得过小、反向增加激活幅度。 |
| 54 | 74 | ||
| 55 | -## 4. 流程示意 | 75 | +### 2.5 适用场景 |
| 56 | - | ||
| 57 | -> 以下为本算法在 msModelSlim 中的简化流程概览。 | ||
| 58 | - | ||
| 59 | -```mermaid | ||
| 60 | -flowchart LR | ||
| 61 | - A[校准数据] --> B[子图发现] | ||
| 62 | - B --> C[统计激活与权重] | ||
| 63 | - C --> D[搜索 alpha/beta] | ||
| 64 | - D --> E[融合缩放] | ||
| 65 | - E --> F[交付量化] | ||
| 66 | -``` | ||
| 67 | - | ||
| 68 | ---- | ||
| 69 | - | ||
| 70 | -## 5. 在 msModelSlim 中的实现 | ||
| 71 | - | ||
| 72 | -### 1. 实现位置 | ||
| 73 | - | ||
| 74 | -算法在 `msmodelslim/processor/anti_outlier/flex_smooth/processor.py` 中实现，通过 `type: "flex_smooth_quant"` 处理器使用。 | ||
| 75 | - | ||
| 76 | -### 2. 处理流程 | ||
| 77 | - | ||
| 78 | -- **预处理阶段**：通过 `SubgraphProcessor` 获取子图信息，按 `include/exclude` 过滤，为线性模块安装前向钩子收集激活张量与每通道绝对最大值。 | ||
| 79 | -- **后处理阶段**：按优先级顺序处理各子图；对非融合子图做 `alpha`/`beta` 搜索（或使用配置值）后对权重做缩放并注册输入侧 pre-hook；最后清理钩子并恢复模型。 | ||
| 80 | - | ||
| 81 | -### 3. 配置示例 | ||
| 82 | - | ||
| 83 | -> 以下为最小可用的 YAML 配置片段。各字段的详细含义如下表所示。 | ||
| 84 | - | ||
| 85 | -```yaml | ||
| 86 | -spec: | ||
| 87 | - process: | ||
| 88 | - - type: "flex_smooth_quant" | ||
| 89 | - alpha: 0.8 | ||
| 90 | - beta: 0.7 | ||
| 91 | - enable_subgraph_type: | ||
| 92 | - - 'norm-linear' | ||
| 93 | - - 'linear-linear' | ||
| 94 | - - 'ov' | ||
| 95 | - - 'up-down' | ||
| 96 | - include: ["*"] | ||
| 97 | - exclude: ["*self_attn*"] | ||
| 98 | -``` | ||
| 99 | - | ||
| 100 | -**字段说明**： | ||
| 101 | - | ||
| 102 | -| 字段名 | 作用 | 说明 | | ||
| 103 | -| --- | --- | --- | | ||
| 104 | -| type | 处理器类型标识 | 固定为 `"flex_smooth_quant"`。 | | ||
| 105 | -| alpha | 激活缩放权重系数 | 0~1 之间的浮点数，控制激活对缩放因子的影响程度，默认 `None`（自动搜索）。 | | ||
| 106 | -| beta | 权重缩放权重系数 | 0~1 之间的浮点数，控制权重对缩放因子的影响程度，默认 `None`（自动搜索）。 | | ||
| 107 | -| enable_subgraph_type | 开启的子图类型 | 支持 `norm-linear`、`linear-linear`、`ov`、`up-down`。 | | ||
| 108 | -| include | 包含的层 | 字符串列表，支持通配符匹配。 | | ||
| 109 | -| exclude | 排除的层 | 字符串列表，支持通配符匹配。 | | ||
| 110 | - | ||
| 111 | -### 4. 模型适配接口 | ||
| 112 | - | ||
| 113 | -模型适配需实现 `FlexSmoothQuantInterface` 接口的 `get_adapter_config_for_subgraph()` 方法，返回 `List[AdapterConfig]`（含 `norm-linear`、`linear-linear`、`ov`、`up-down` 等子图映射）。参考实现：`msmodelslim/model/qwen3/model_adapter.py`。 | ||
| 114 | - | ||
| 115 | ---- | ||
| 116 | - | ||
| 117 | -## 6. 适用场景与限制 | ||
| 118 | - | ||
| 119 | -### 1. 适用场景 | ||
| 120 | 76 | ||
| 121 | - 需要自动搜索最优平滑参数、减少人工调参的量化场景。 | 77 | - 需要自动搜索最优平滑参数、减少人工调参的量化场景。 |
| 122 | - 需要同时对注意力 `ov`、MLP `up-down`、连续线性层等多种结构做离群值抑制的场景。 | 78 | - 需要同时对注意力 `ov`、MLP `up-down`、连续线性层等多种结构做离群值抑制的场景。 |
| 123 | 79 | ||
| 124 | -### 2. 使用限制 | 80 | +更具体地说，这类算法适合“量化误差主要由少数大幅值通道或 token 拉高尺度”的情况。若问题来源并不是离群值，而是模型本身对低比特表示普遍敏感，则单独增加平滑或旋转强度通常收益有限，应结合更高精度量化或敏感层回退。 |
| 125 | 81 | ||
| 126 | -- 模型必须实现 `FlexSmoothQuantInterface` 接口并正确配置子图映射。 | 82 | +### 2.6 使用限制 |
| 127 | -- 目标模块必须存在且具备可写的 `weight`，模块名须与 `named_modules()` 返回的完整路径一致。 | 83 | + |
| 128 | -- 非融合子图不支持 `shift`（偏置平移）。 | 84 | +- 目标结构需要能够识别为 `norm-linear`、`linear-linear`、`ov`、`up-down` 等可保持计算等价的子图。 |
| 85 | +- 对无法与前置算子融合的独立线性层，只适合做乘性缩放，不适合同时做偏置平移。 | ||
| 86 | + | ||
| 87 | +这些限制反映了算法对模型结构和等价变换条件的依赖。若目标模型不满足相应结构假设，强行套用可能破坏原有计算关系；因此遇到不兼容结构时应优先缩小作用范围或使用模型已验证的配方，而不是盲目增大平滑强度。 | ||
| 129 | 88 | ||
| 130 | --- | 89 | --- |
| 131 | 90 | ||
| 132 | -## 7. 关联流程 | 91 | +## 3. 关联词条 |
| 133 | 92 | ||
| 134 | -- 《[一键量化 (V1)](../../../user_guide/usage_quick_quantization.md)》：默认集成本算法作为离群值抑制前置步骤。 | 93 | +可以从“同类方法、前后处理关系和应用对象”三个方向理解本词条与其他算法的关系。下面的关联项既用于横向比较不同技术路线，也用于帮助定位该算法在完整量化方案中的位置。 |
| 135 | -- 《[量化精度调优指南](../../../user_guide/process_quantization_precision_tuning.md)》：精度不达标时可考虑启用本算法。 | ||
| 136 | - | ||
| 137 | ---- | ||
| 138 | - | ||
| 139 | -## 8. 关联词条 | ||
| 140 | 94 | ||
| 141 | - [SmoothQuant](../smooth_quant/term_smooth_quant.md)：上位概念，本算法是 SmoothQuant 的灵活扩展。 | 95 | - [SmoothQuant](../smooth_quant/term_smooth_quant.md)：上位概念，本算法是 SmoothQuant 的灵活扩展。 |
| 142 | - [Iterative Smooth](../iterative_smooth/term_iterative_smooth.md)：同类算法，同样支持多子图类型的平滑。 | 96 | - [Iterative Smooth](../iterative_smooth/term_iterative_smooth.md)：同类算法，同样支持多子图类型的平滑。 |
| @@ -146,7 +100,9 @@ spec: | |||
| 146 | 100 | ||
| 147 | --- | 101 | --- |
| 148 | 102 | ||
| 149 | -## 9. 参考资料 | 103 | +## 4. 参考文档 |
| 104 | + | ||
| 105 | +参考文档优先列出算法原始论文或权威出处，并补充仓库内对应使用指南。需要进一步理解参数选择时，可先阅读使用指南，再回到原论文核对算法假设和推导。 | ||
| 150 | 106 | ||
| 151 | 1. Xiao G et al. SmoothQuant: Accurate and Efficient Post-Training Quantization for Large Language Models. ICML 2023. https://arxiv.org/abs/2211.10438 | 107 | 1. Xiao G et al. SmoothQuant: Accurate and Efficient Post-Training Quantization for Large Language Models. ICML 2023. https://arxiv.org/abs/2211.10438 |
| 152 | -2. 《Flex Smooth Quant 使用指南》([./usage_flex_smooth_quant.md](./usage_flex_smooth_quant.md)) | 108 | +2. 《[Flex Smooth Quant 参数配置流程指南](./usage_flex_smooth_quant.md)》 |
| @@ -1,166 +1,118 @@ | |||
| 1 | -# Flex Smooth Quant 使用指南 | 1 | +# Flex Smooth Quant 参数配置流程指南 |
| 2 | 2 | ||
| 3 | ## 1. 适用范围 | 3 | ## 1. 适用范围 |
| 4 | 4 | ||
| 5 | -本流程适用于在 msModelSlim 中配置和使用 Flex Smooth Quant 灵活平滑量化算法。Flex Smooth Quant 作为离群值抑制算法，通常作为量化前的预处理步骤，通过自动搜索最优 `alpha`/`beta` 参数抑制激活离群值，提升低比特量化的精度。 | 5 | +Flex Smooth Quant 灵活平滑量化算法。Flex Smooth Quant 作为离群值抑制算法，通常作为量化前的预处理步骤，通过自动搜索最优 `alpha`/`beta` 参数抑制激活离群值，提升低比特量化的精度。 |
| 6 | 6 | ||
| 7 | -适用角色：算法工程师、模型部署工程师 | 7 | +本指南面向首次配置 Flex Smooth Quant 的用户，重点不是展开完整执行命令，而是说明推荐配置为什么适合作为起点、哪些参数真正需要调，以及出现精度或资源问题时应优先改哪一项。这类算法的主要作用是先改善待量化张量的数值分布，再交给后续量化步骤处理，本身通常不是最终的量化格式。因此判断配置是否合适时，不仅要看平滑或旋转后的张量范围，还要看与后续量化组合后的端到端精度；建议保持后续量化配置不变，只调整当前算法参数。 |
| 8 | 8 | ||
| 9 | -适用场景： | 9 | +如果目标模型已经有完整且已验证的量化配方，应优先复用该配方；若当前算法与目标模型结构、数值格式或部署后端不兼容，不应通过增大搜索强度或扩大作用范围来绕过支持约束。 |
| 10 | 10 | ||
| 11 | -- 需要自动搜索最优平滑参数、减少人工调参的量化场景。 | 11 | +## 2. 输入和交付件 |
| 12 | -- 需要同时对注意力 `ov`、MLP `up-down`、连续线性层等多种结构做离群值抑制的场景。 | ||
| 13 | - | ||
| 14 | -不适用场景： | ||
| 15 | - | ||
| 16 | -- 模型未实现 `FlexSmoothQuantInterface` 接口，或无子图映射配置。 | ||
| 17 | -- 目标模块无 `weight` 属性或模块名无法通过 `named_modules()` 定位。 | ||
| 18 | - | ||
| 19 | -## 2. 流程关系与前置条件 | ||
| 20 | - | ||
| 21 | -**上级流程**：模型适配与验证通过后，确定量化方案阶段。 | ||
| 22 | - | ||
| 23 | -**前置条件**： | ||
| 24 | - | ||
| 25 | -- 已安装兼容版本的 msModelSlim 工具（详见《[msModelSlim 工具安装指南](../../../install_guide/install_guide.md)》）。 | ||
| 26 | -- 已确认目标模型适配器实现了 `FlexSmoothQuantInterface` 接口，并正确配置子图映射。 | ||
| 27 | -- 已准备好校准数据集，用于收集激活统计信息。 | ||
| 28 | - | ||
| 29 | -**后续操作**：量化流程执行 → 精度验证 → 部署上线或进入调优。 | ||
| 30 | - | ||
| 31 | -## 3. 输入和交付件 | ||
| 32 | 12 | ||
| 33 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | | 13 | | 类型 | 名称 | 来源或保存位置 | 格式或约束 | 验收方式 | |
| 34 | | --- | --- | --- | --- | --- | | 14 | | --- | --- | --- | --- | --- | |
| 35 | -| 输入 | 浮点模型权重目录 | 模型下载或本地路径 | HuggingFace 格式，含 `config.json` 及 `*.safetensors` | 可被目标 Transformers 版本加载 | | 15 | +| 输入 | 目标模型与量化目标 | 待量化模型及部署/评测方案 | 明确目标数值格式或位宽、作用模块、精度/性能目标以及部署约束 | 能说明为什么选择本算法以及它在整体量化方案中的位置 | |
| 36 | -| 输入 | 校准数据集 | 工具默认或用户指定 | JSONL 格式，每条含文本 prompt | 可被工具加载并完成前向推理 | | 16 | +| 输入 | 配置约束与实践基线 | 本算法配置说明、目标模型已有 `lab_practice` 配方（如有） | 字段名、支持组合、作用范围和模型适配与当前版本一致 | 推荐起点能够追溯到当前配置定义或已验证实践 | |
| 37 | -| 输入 | 量化 YAML 配置文件 | 用户编写 | 符合 msModelSlim YAML 规范，含 `flex_smooth_quant` 处理器配置 | 可通过工具 `--config_path` 参数加载 | | 17 | +| 输入 | 校准数据（算法需要时） | 任务 `dataset`、校准集或模型实践配方 | 数据应能代表真实输入分布；多阶段算法尽量保持各阶段数据分布一致 | 能被当前量化流程正常读取，并覆盖主要输入形态 | |
| 38 | -| 交付件 | 平滑后的量化权重目录 | `--save_path` 指定路径 | 含 `quant_model_description.json` 及 `*.safetensors`，已应用平滑缩放 | 推理冒烟通过 | | 18 | +| 交付件 | Flex Smooth Quant 参数配置方案 | 用户量化 YAML 或任务配置 | 参数取值合法、作用范围明确；关键参数说明选择依据 | 可作为后续量化流程的算法配置输入，并可复现本指南中的基线选择 | |
| 39 | 19 | ||
| 40 | -## 4. 流程总览 | 20 | +## 3. 流程总览 |
| 21 | + | ||
| 22 | +入门时建议先用一组稳定配置建立基线，再围绕影响最大的参数做单变量调整。下面的流程强调“先选参数、再看效果”，不展开量化命令本身。 | ||
| 41 | 23 | ||
| 42 | ```mermaid | 24 | ```mermaid |
| 43 | flowchart LR | 25 | flowchart LR |
| 44 | - A[编写 YAML 配置] --> B[执行量化命令] | 26 | + A[确定目标子图范围] --> B[自动搜索 alpha/beta] |
| 45 | - B --> C[收集激活统计] | 27 | + B[自动搜索 alpha/beta] --> C[计算平滑尺度] |
| 46 | - C --> D[搜索并融合缩放] | 28 | + C[计算平滑尺度] --> D[融合尺度] |
| 47 | - D --> E[验证量化结果] | 29 | + D[融合尺度] --> E[进入后续量化] |
| 48 | ``` | 30 | ``` |
| 49 | 31 | ||
| 50 | -## 5. 操作步骤 | 32 | +实际使用时建议把流程理解为“建立基线—观察结果—单变量调整—再次验证”的闭环。流程图中的前几个节点用于固定量化对象、统计信息或初始参数，后几个节点用于应用算法并检查结果；如果效果不理想，应优先回到最近一次修改的参数，而不是同时更换位宽、粒度、作用范围和算法强度。这样可以明确每次变化的因果关系，也便于把有效配置沉淀为后续模型配方。 |
| 51 | 33 | ||
| 52 | -### 步骤 1：编写 YAML 配置文件 | 34 | +## 4. 操作步骤 |
| 53 | 35 | ||
| 54 | -**目标**：编写包含 `flex_smooth_quant` 处理器配置的 YAML 文件。 | 36 | +### 步骤 1：确认目标与约束 |
| 37 | + | ||
| 38 | +**操作**：先固定目标模型、最终量化格式/位宽、作用对象和评测基线，再确认当前版本支持的参数组合。目标模型已有 `lab_practice` 配方时，优先把该配方作为实践基线；没有模型专用配方时，再使用本指南给出的通用推荐起点。若算法依赖校准统计或优化数据，还应在调参前固定代表性数据，避免把数据分布变化误判为参数收益。 | ||
| 39 | + | ||
| 40 | +**输出**：一份明确的配置目标：目标位宽/格式、处理范围、校准条件、评测基线和部署约束。 | ||
| 41 | + | ||
| 42 | +### 步骤 2：建立推荐基线 | ||
| 55 | 43 | ||
| 56 | **操作**： | 44 | **操作**： |
| 57 | 45 | ||
| 58 | -1. 在 `spec.process` 下配置 `flex_smooth_quant` 处理器，指定 `type: "flex_smooth_quant"`。 | 46 | +下面配置用于建立**第一版可比较基线**。如果目标模型已有 `lab_practice` 配方，优先使用已验证配方，再参考本节理解每个参数为什么这样选。 |
| 59 | -2. 可选配置 `alpha`（激活缩放系数，默认自动搜索）与 `beta`（权重缩放系数，默认自动搜索）。 | ||
| 60 | -3. 按需配置 `enable_subgraph_type` 与 `include`/`exclude`。 | ||
| 61 | - | ||
| 62 | -YAML 配置示例： | ||
| 63 | 47 | ||
| 64 | ```yaml | 48 | ```yaml |
| 65 | spec: | 49 | spec: |
| 66 | process: | 50 | process: |
| 67 | - - type: "flex_smooth_quant" # 固定为 `flex_smooth_quant`，用于指定 Processor。 | 51 | + - type: "flex_smooth_quant" |
| 68 | - alpha: 0.8 # 激活缩放的权重系数，0-1之间，默认 None，通过算法自动搜索最佳alpha，也支持用户自行配置。 | 52 | + # 入门建议不显式设置 alpha/beta，让算法自动搜索。 |
| 69 | - beta: 0.7 # 权重缩放的权重系数，0-1之间，默认 None，通过算法自动搜索最佳beta，也支持用户自行配置。 | 53 | + enable_subgraph_type: |
| 70 | - enable_subgraph_type: # 字符串列表，指定启用的子图类型，默认启用所有四种类型。 | 54 | + - "norm-linear" |
| 71 | - - 'norm-linear' | 55 | + - "linear-linear" |
| 72 | - - 'linear-linear' | 56 | + - "ov" |
| 73 | - - 'ov' | 57 | + - "up-down" |
| 74 | - - 'up-down' | 58 | + include: ["*"] |
| 75 | - include: ["*"] # 包含的层，支持通配符。 | 59 | + exclude: [] |
| 76 | - exclude: ["*self_attn*"] # 排除的层，支持通配符。 | ||
| 77 | ``` | 60 | ``` |
| 78 | 61 | ||
| 79 | -YAML 配置字段详解如下： | 62 | +上面的推荐值用于建立第一版可复现基线，其中最值得关注的配置包括 `type`, `alpha`, `beta`, `enable_subgraph_type`。推荐值并不表示所有模型都只能使用该组合，而是优先选择仓库默认值、已验证实践或较稳健的中间取值，以降低第一次使用时同时遇到精度和兼容性问题的概率。如果目标模型已经有 `lab_practice` 配方，应优先复用该配方；只有在基线精度、显存或吞吐不满足目标时，再按照下一节的参数说明逐项调整。 |
| 80 | 63 | ||
| 81 | -| 字段名 | 作用 | 说明 | | 64 | +**输出**：一份可复现的推荐基线配置，后续所有参数调整均以此为比较对象。 |
| 82 | -| --- | --- | --- | | ||
| 83 | -| type | 处理器类型标识 | 固定为 `"flex_smooth_quant"`。 | | ||
| 84 | -| alpha | 激活缩放权重系数 | 0~1 之间的浮点数，控制激活对缩放因子的影响程度，默认 `None`（自动搜索）。 | | ||
| 85 | -| beta | 权重缩放权重系数 | 0~1 之间的浮点数，控制权重对缩放因子的影响程度，默认 `None`（自动搜索）。 | | ||
| 86 | -| enable_subgraph_type | 开启的子图类型 | 支持 `norm-linear`、`linear-linear`、`ov`、`up-down`。 | | ||
| 87 | -| include | 包含的层 | 字符串列表，支持通配符匹配。 | | ||
| 88 | -| exclude | 排除的层 | 字符串列表，支持通配符匹配。 | | ||
| 89 | 65 | ||
| 90 | -**输出**：YAML 配置文件 `${CONFIG_PATH}`。 | 66 | +### 步骤 3：选择并调整参数 |
| 91 | - | ||
| 92 | -### 步骤 2：执行量化命令 | ||
| 93 | - | ||
| 94 | -**目标**：使用上一步编写的 YAML 配置文件启动量化流程。 | ||
| 95 | 67 | ||
| 96 | **操作**： | 68 | **操作**： |
| 97 | 69 | ||
| 98 | -```bash | 70 | +ModelSlim 实现入口： |
| 99 | -msmodelslim quant \ | 71 | +[查看对应实现目录](../../../../../msmodelslim/processor/anti_outlier/flex_smooth) |
| 100 | - --model_path ${MODEL_PATH} \ | ||
| 101 | - --save_path ${SAVE_PATH} \ | ||
| 102 | - --device npu \ | ||
| 103 | - --model_type ${MODEL_TYPE} \ | ||
| 104 | - --config_path ${CONFIG_PATH} \ | ||
| 105 | - --trust_remote_code True | ||
| 106 | -``` | ||
| 107 | 72 | ||
| 108 | -参数说明： | 73 | +参数选择建议按三个层次理解：首先确认 `dtype/scope/method` 等**算法支持约束**，这类字段不是任意可调；其次确定 `include/exclude`、子图类型等**作用范围**；最后再调整会改变误差与开销的数值参数。下面的推荐值区分了代码默认值、仓库 `lab_practice` 中已验证的实践值和适合首次使用的推荐起点。如果目标模型已有实践配置，优先沿用实践配置，再根据本节说明做单变量调整。 |
| 109 | 74 | ||
| 110 | -| 参数 | 必选 | 说明 | | 75 | +| 配置项 | 含义（原理） | 推荐配置 | 选择与调整建议 | |
| 111 | -| --- | --- | --- | | 76 | +| --- | --- | --- | --- | |
| 112 | -| `model_path` | 是 | 浮点模型权重路径 | | 77 | +| `type` | 处理器标识，固定为 `flex_smooth_quant`。 | 固定。 | 不调。 | |
| 113 | -| `save_path` | 是 | 量化权重保存路径 | | 78 | +| `alpha` | 激活统计在平滑尺度中的指数权重。当前实现若 `alpha` 或 `beta` 任一缺失，会进入自动 alpha/beta 搜索；第一阶段以 `beta=1-alpha` 扫描 alpha。 | 入门建议不显式配置，让算法自动搜索。 | 只有已有稳定模型配方、希望复现固定尺度时才手工设置。若只填写 alpha 而 beta 留空，当前逻辑仍会搜索参数，不等于“固定 alpha”。 | |
| 114 | -| `device` | 否 | 量化设备，默认 `npu` | | 79 | +| `beta` | 权重统计在平滑尺度中的指数权重。自动搜索第二阶段会在最佳 alpha 下继续扫描 beta，以输出归一化 RMSE 选择组合。 | 与 alpha 一起省略，让搜索同时决定。 | 想完全固定手工参数时应同时提供 alpha 和 beta；只改一个可能触发重新搜索。alpha/beta 都在 0~1，不能简单理解为二者必须相加等于 1，因为第二阶段会独立优化 beta。 | |
| 115 | -| `model_type` | 是 | 模型名称，与支持矩阵一致 | | 80 | +| `enable_subgraph_type` | 选择 `norm-linear`、`linear-linear`、`ov`、`up-down` 等平滑结构。仓库 24 个实践中最常见的是 `[norm-linear, ov]`，也有仅 norm-linear 或加入 up-down 的模型专用组合。 | 优先复用模型实践；没有配方时从与模型量化目标最相关的少量子图开始，而不是默认全开后再猜问题。 | 子图类型会改变搜索所看到的激活/权重和可融合路径。扩大范围后应重新校准；若某类结构收益不稳定，单独去掉该类而不是修改 alpha/beta 来掩盖结构不匹配。 | |
| 116 | -| `config_path` | 是 | 步骤 1 编写的 YAML 配置路径 | | 81 | +| `include` | 作用范围白名单，使用模块名模式决定哪些匹配到的模块进入当前算法。它只决定“在哪些模块做”，不会改变算法内部公式。 | 无模型专用配方时从 `["*"]` 开始；已有 `lab_practice` 时直接沿用其模块范围。 | 先保证范围覆盖预期模块，再看精度。范围过宽时，少数结构不兼容或敏感层会放大整体风险；范围过窄则可能让算法收益看不出来。收窄范围时优先按结构族或已知敏感层调整，不建议仅凭层号大面积删除。 | |
| 117 | -| `trust_remote_code` | 否 | 是否信任远程代码，默认 `False` | | 82 | +| `exclude` | 作用范围黑名单，命中后从 `include` 的候选中排除，优先级高于 `include`。适合保护敏感层、首尾层或模型专用不兼容结构。 | 默认先保持空列表；只有实践配方、兼容性约束或敏感性结果给出明确证据时再加入。 | 局部精度问题优先通过 `exclude` 做小范围回退，比提高全模型位宽或关闭整个算法更容易保留收益。每次增加排除项后应确认通配符没有误伤相邻模块。 | |
| 118 | 83 | ||
| 119 | -执行流程说明： | 84 | +### 参数组合与选择顺序 |
| 120 | 85 | ||
| 121 | -1. 工具加载 YAML 配置，解析 `flex_smooth_quant` 处理器。 | 86 | +1. **先锁定部署目标与支持组合**：先确定最终位宽/数值格式，再确认当前量化器实际注册了对应的 `dtype + scope + symmetric + method` 组合；不要为了追求某个参数值而越过支持约束。 |
| 122 | -2. 预处理阶段发现子图并收集激活统计信息。 | 87 | +2. **再固定作用范围**：使用已有模型配方时，先复用其 `include/exclude` 或子图类型；没有配方时先建立覆盖范围明确的基线，确认算法确实作用到了预期模块。 |
| 123 | -3. 后处理阶段搜索最优 `alpha`/`beta`（或使用配置值）并融合缩放。 | 88 | +3. **最后只调一个主要旋钮**：数值搜索步数、平滑强度、分组大小等一次只改一项，并保持同一校准集和评测集。若调整后没有稳定收益，回到上一个基线，而不是继续叠加多个变化。 |
| 124 | -4. 继续执行下游量化处理器并保存量化权重。 | ||
| 125 | 89 | ||
| 126 | -**输出**：量化权重目录 `${SAVE_PATH}`，包含量化描述文件与权重分片。 | 90 | +如果使用自动搜索，**不要只填一个 alpha 或 beta 来期待“半固定”行为**：当前实现任一缺失都会进入搜索。复现固定配方时同时给两者；探索新模型时两者都省略。 |
| 127 | 91 | ||
| 128 | -### 步骤 3：验证量化结果 | 92 | +**输出**：一份完成单变量调整的算法参数方案，关键字段均有明确的选择依据和调整方向。 |
| 129 | 93 | ||
| 130 | -**目标**：确认量化权重文件完整且可加载。 | 94 | +### 步骤 4：根据结果收敛参数方案 |
| 131 | 95 | ||
| 132 | **操作**： | 96 | **操作**： |
| 133 | 97 | ||
| 134 | -1. 检查输出目录是否包含 `quant_model_description.json` 文件。 | 98 | +调参时建议先记录一份完整基线，包括使用的数据集、量化范围、关键参数和端到端指标。每轮只改变一个变量，并把变化结果与基线直接比较；如果某项调整带来收益，再继续小步搜索其邻近取值。对于只有少数层或模块异常的情况，优先采用局部排除、局部回退或混合精度，而不是直接提高全模型精度配置，这通常更容易保留压缩和性能收益。 |
| 135 | -2. 检查日志确认无层匹配告警。 | ||
| 136 | -3. 使用推理框架加载量化权重进行冒烟测试。 | ||
| 137 | 99 | ||
| 138 | -**输出**：量化权重验证通过。 | 100 | +- 自动搜索通常优于跨模型复用固定 alpha/beta。只有为了复现已验证配方，才建议显式固定搜索结果。 |
| 101 | +- **先跑推荐基线，再调单变量。** 不要同时修改位宽、粒度、算法参数和层范围，否则很难判断精度变化来自哪一项。 | ||
| 102 | +- **优先回退局部，而不是整体提高精度。** 如果只有少数层敏感，优先通过 `exclude` 或混合策略保留高精度，通常比整体升位宽更划算。 | ||
| 103 | +- **最终以模型实践配置和部署能力为准。** 入门推荐用于建立稳定起点；目标模型已有 `lab_practice` 配方时，应优先复用已验证组合。 | ||
| 139 | 104 | ||
| 140 | -## 6. 验收条件 | 105 | +**输出**：一份可进入后续量化流程的最终参数方案，并保留相对于推荐基线的调整记录。 |
| 141 | 106 | ||
| 142 | -- 量化权重目录包含 `quant_model_description.json` 及所有必需的 `*.safetensors` 分片文件。 | 107 | +## 5. 术语 |
| 143 | -- 日志无子图配置错误或模块名不匹配告警。 | ||
| 144 | -- 量化后模型推理精度不低于未使用 Flex Smooth Quant 的基线。 | ||
| 145 | - | ||
| 146 | -## 7. 异常处置 | ||
| 147 | - | ||
| 148 | -- **模块名不匹配**：`include/exclude` 未命中时日志提示未匹配模式，核对完整模块名是否与 `named_modules()` 返回的路径一致。 | ||
| 149 | -- **子图类型不支持**：确保配置的子图类型在支持列表中。 | ||
| 150 | -- **映射关系错误**：检查 `MappingConfig` 中的 `source` 与 `targets` 是否指向正确的模块。 | ||
| 151 | -- **模块不存在**：通过 `model.named_modules()` 验证配置中指定的模块名称。 | ||
| 152 | - | ||
| 153 | -## 8. 术语 | ||
| 154 | 108 | ||
| 155 | | 术语 | 简述 | 链接 | | 109 | | 术语 | 简述 | 链接 | |
| 156 | | --- | --- | --- | | 110 | | --- | --- | --- | |
| 157 | -| Flex Smooth Quant | 支持 alpha/beta 自动搜索的灵活平滑算法 | [Flex Smooth Quant 词条](./term_flex_smooth_quant.md) | | 111 | +| Flex Smooth Quant 灵活平滑量化算法 | 说明该算法的定义、核心原理、关键性质、适用场景与限制。 | 《[Flex Smooth Quant 灵活平滑量化算法 量化术语百科词条](./term_flex_smooth_quant.md)》 | |
| 158 | -| 离群值抑制 | 通过数值变换减少激活离群值、降低量化误差 | [量化算法总览](../README.md) | | ||
| 159 | -| 网格搜索 | 在参数空间内遍历候选组合寻找最优参数 | [Flex Smooth Quant 词条](./term_flex_smooth_quant.md) | | ||
| 160 | 112 | ||
| 161 | -## 9. 接口文档列表 | 113 | +## 6. 接口文档列表 |
| 162 | 114 | ||
| 163 | | 接口或能力 | 简述 | 链接 | | 115 | | 接口或能力 | 简述 | 链接 | |
| 164 | | --- | --- | --- | | 116 | | --- | --- | --- | |
| 165 | -| `flex_smooth_quant` 处理器 | 用于执行灵活平滑量化的 Processor 配置 | [Flex Smooth Quant 词条](./term_flex_smooth_quant.md) | | 117 | +| flex_smooth_quant 配置说明 | 字段类型、默认值、合法取值与完整配置约束。 | 《[flex_smooth_quant 配置说明](../../../api_reference/config/processor/flex_smooth_quant.md)》 | |
| 166 | -| `FlexSmoothQuantInterface` | 模型适配器需实现的灵活平滑接口 | [Flex Smooth Quant 词条](./term_flex_smooth_quant.md) | | 118 | +| modelslim_v1 配置说明 | 需要继续探索 runner、prior、save、dataset 等任务级高级配置时查阅。 | 《[modelslim_v1 配置说明](../../../api_reference/config/task/modelslim_v1.md)》 | |