Qlean模型量化工具（v0.2.0)-真武 PPU 云服务(ppu)-阿里云帮助中心

1. 工具介绍

QLean 提供易用、高效的模型量化与反量化能力。用户只需通过指定不同的输出格式（--output-format），即可一键切换功能模式。当前支持的转换路径包括：

源格式	目标格式	说明
BF16 / FP8_BLOCK	INT8_W8A8	权重： INT8，静态，Per-Channel 激活： INT8，动态，Per-Token
BF16 / FP8_BLOCK	FP8_BLOCK	权重： FP8，静态，Per-Block (128*128) 激活： FP8，动态，Per-Group (128)
BF16 / FP8_BLOCK	FP8_CHANNEL	权重： FP8，静态，Per-Channel 激活： FP8，动态，Per-Token
BF16 / NVFP4	MXFP4	权重： OCP MXFP4，静态激活： OCP MXFP4，动态
FP8_BLOCK / NVFP4	BF16	反量化为 BF16

为了更优性能，对于 Qwen3.5-397B-A17B、GLM-5、Kimi-K2.5、MiniMax-M2.5，设置--output-format mxfp4时，实际转换为 MOE mxfp4、部分 dense FP8_CHANNEL 的混合精度格式。

2. 工具安装

发布了whl包，可在PIP源List中查看并通过pip install方式使用。

# docker image
reg.docker.alibaba-inc.com/aisw/ppu:v2.1.0-cuda13.0-ubuntu24-py312 

pip install torch==2.9.0+v0.1.0.ppu2.1.0.oe
pip install qlean==0.2.0+v0.1.0.ppu2.1.0

3. 迅速上手

一条命令给出三个必填参数：

qlean --model_name Qwen/Qwen3-235B-A22B \
      --model_path /path/to/Qwen3-235B-A22B \
      --save_path /path/to/Qwen3-235B-A22B-INT8

未指定--output-format 时默认量化为 INT8_W8A8。
运行结束后，输出目录包含量化后的模型文件和 qlean_config.json 转换记录。

4. 核心概念

4.1 输入格式与输出格式

输入格式：模型当前的权重格式（BF16、FP8_BLOCK、NVFP4），QLean 自动从模型文件检测，通常无需指定。

输出格式：你想要的目标格式，通过 --output-format 指定。

支持的输出格式及别名（不区分大小写）：

输出格式	别名
INT8_W8A8	W8A8、INT8
FP8_BLOCK	FP8-BLOCK
FP8_DYNAMIC	FP8-DYNAMIC、FP8-CHANNEL、FP8_CHANNEL
MXFP4	—
BF16	—

4.2 Recipe

Recipe 是一个 YAML 配置文件，定义了量化的具体行为，包括：

使用什么 modifier
使用什么 scheme
哪些层被 ignore

4.3 自动模式 vs 手动模式

模式	触发方式	行为	适用场景
自动模式（默认）	只指定 `--output-format`	系统自动检测输入格式，并匹配内置 recipe	模型有内置recipe的场景
手动模式	指定 `--recipe`	完全按自定义 recipe 执行，忽略 --output-format 和内置 recipe	定制需求、路由表未覆盖的特殊组合

QLean 内置了多种模型的专属 recipe。可以通过qlean --list-models查看已支持的模型列表。对于列表中的模型，可省略 --recipe 参数，系统将自动加载最优配置。对于其他模型，系统会 fallback 到默认 recipe，但默认 recipe 并非最优实现，建议手动编写并提供 --recipe 参数。（关于 recipe 的编写方法，见“Recipe编写”部分）。

4.4 混合量化

在 W8A8-INT8 量化后，部分模型在特定用例上出现精度下降问题，原因可能为模型某些 layer 对精度敏感，可用混合量化功能将 W8A8 量化模型中的指定layer的替换回 BF16 版本。当你通过自定义 recipe 配置了混合策略时，需要 --mix_path 指定一个额外的输出目录来保存混合精度版本的模型文件。此时，save_path 对应 W8A8 模型，mix_path 保存混合量化模型。（关于混合量化的 recipe 的编写方法，见“Recipe编写”部分）。

5. 命令行参数

5.1 必填参数

参数	说明	示例
--model_name	模型标识符，用于匹配 recipe	Qwen/Qwen3-235B-A22B
--model_path	本地的源模型目录路径	/path/to/Qwen3-235B-A22B
--save_path	输出保存路径	/path/to/Qwen3-235B-A22B-INT8

注：model_name用于内置 recipe 匹配，需要确保使用源模型在Huggingface上的model_stub官方名称。

5.2 可选参数

参数	默认值	说明
--output-format	INT8_W8A8	目标输出格式
--input-format	自动检测	源模型格式，通常无需指定
--recipe	自动选择	自定义 recipe 路径，用户给出则覆盖内置 recipe
--log-level	INFO	日志级别：DEBUG / INFO / WARNING / ERROR
--mix_path	无	混合量化模型保存路径，仅在混合量化时使用

5.3 帮助参数

命令	用途
qlean --list-formats	查看所有支持的格式转换路径和别名
qlean --list-models	列出所有有专属 recipe 的模型
qlean --list-models MODEL_NAME	查看特定模型的 recipe 支持情况
qlean --examples	查看使用示例
qlean -h	查看帮助信息

6. 使用示例

6.1 BF16 模型量化为 INT8

qlean --model_name Qwen/Qwen3-235B-A22B \
      --model_path /path/to/Qwen3-235B-A22B \
      --save_path /path/to/Qwen3-235B-A22B-INT8

6.2 FP8 模型转换为 INT8

qlean --model_name deepseek-ai/DeepSeek-V3.2 \
      --model_path /path/to/DeepSeek-V3.2 \
      --save_path /path/to/DeepSeek-V3.2-INT8

系统自动检测到输入为 FP8，执行"FP8 反量化 → INT8 量化"两步

6.3 指定输出格式

qlean --model_name Qwen/Qwen3-30B-A3B \
      --model_path /path/to/Qwen3-30B-A3B \
      --save_path /path/to/Qwen3-30B-A3B-FP8Block \
      --output-format FP8_BLOCK

指定输出格式为 FP8_BLOCK。

qlean --model_name Qwen/Qwen3.5-397B-A17B \
      --model_path /path/to/Qwen3.5-397B-A17B \
      --save_path /path/to/Qwen3.5-397B-A17B-MXFP4 \
      --output-format MXFP4

指定输出格式为 MXFP4。

6.4 使用自定义 recipe

qlean --model_name Qwen/Qwen3-8B \
      --model_path /path/to/Qwen3-8B \
      --save_path /path/to/Qwen3-8B-custom \
      --recipe /path/to/recipe.yaml

使用 --recipe 后，--output-format 和内置 recipe 都会被忽略，完全按你的配置执行。

7. Recipe 编写

若需对已支持的模型列表外的模型进行量化，用户可参考以下 recipe 编写 yaml 文件，仅需改动 ignore 和 scheme 部分。

quant_stage:
  quant_modifiers:
    generalDay0Modifier:
      ignore: ["module_to_ignore"] # 请根据实际进行修改
      scheme: W8A8 # 请根据实际进行修改

在编写量化配置中的ignore列表时，应加入所有对于量化敏感的模块。通常不应量化的模块包括："re:.*lm_head"、"re:.*embed_tokens"、"re:.*mlp.gate$"。注意，不同架构的模型需要 ignore 的模块不同，应当按需添加。
scheme 使用 COMPRESSED-TENSORS 格式，目前已支持的格式包括：W8A8、FP8_BLOCK、FP8_DYNAMIC、MXFP4。

若需对“支持一键量化的模型”表外的模型进行混合量化，用户需在上述 recipe 基础上额外增加 mixedPrecisionModifier 部分。layers 给出需要替换为 BF16 的layer id，num_layers 给出模型的总层数。

quant_stage:
  quant_modifiers:
    generalDay0Modifier:
      ignore: ["re:.*lm_head", "re:.*embed_tokens", "re:.*mlp.gate$"] # 请根据实际进行修改
      scheme: W8A8
    mixedPrecisionModifier:
      layers: ['88', '89', '92-93']  # 请根据实际进行修改
      num_layers: 94                 # 请根据实际进行修改

编写完 yaml 文件后使用 --recipe 参数传入该文件地址。

qlean --model_name /name/of/model/ --model_path /path/to/original_model/ --save_path /path/to/result_model/ --mix_path /path/to/mix_model/ --recipe /path/to/your/recipe/

8. DeepSeek V4

Base版本的模型转W8A8 INT8

qlean --model_name deepseek-ai/DeepSeek-V4-Flash-Base --model_path /path/to/DeepSeek-V4-Flash-Base --save_path /path/to/DeepSeek-V4-Flash-Base-int8

9. 已知问题

DeepSeek V4架构较新，推理框架对该架构的 INT8 支持仍在适配中，量化精度待验证。
DeepSeek-V3.2 FP8-CHANNEL、GLM-5.1 MXFP4 在PPU上的性能仍需优化。

10. 常见问题与排查

10.1 如何确认我的模型名称是否正确？

qlean --list-models 或 qlean --list-models MODEL_NAME

如果模型不在列表中，系统会使用默认 recipe，建议手动提供 --recipe 以获得最佳效果。

10.2 自动检测输入格式失败怎么办？

当模型结构特殊或文件不完整时，自动检测可能失败。此时可手动指定 --input-format：

qlean --model_name xxx \
      --model_path /path/to/model \
      --save_path /path/to/output \
      --input-format FP8 \
      --output-format INT8_W8A8

10.3 转换后精度下降明显，如何排查？

检查是否使用了内置 recipe（确认 --model_name 与 --list-models 中的名称一致）。
考虑编写自定义 recipe，对敏感层设置 ignore。

10.4 输出目录里 qlean_config.json 是什么？

这是转换记录文件，记录了输入格式、输出格式、使用的 recipe、各层配置等信息。用于：

追溯转换历史。
在其他环境中复现相同转换。
排查问题时提供给维护人员。