大模型量化是推理优化的关键能力之一。通过降低权重和激活的数值精度，量化可以减少模型存储、显存占用和计算开销，是大模型在实际业务中高效部署的重要手段。

AMCT 是 CANN 社区提供的模型压缩与量化工具，面向昇腾 AI 处理器支持 LLM 模型高效量化，覆盖 BF16 基线评估、PTQ 离线数据提取、PTQ 参数训练、fake quant 精度评估等典型流程。

本文与 社区任务：贡献 LLM 量化样例 配套使用，提供一份可参考、可跑通的 AMCT-LLM 量化操作流程，帮助开发者快速理解基本工作流，降低上手成本。参与社区任务时，可以先按本文跑通示例，再结合自己领取的模型、量化规格和算法进行修改适配，形成可复现的实践样例并提交到 AMCT 仓库。

本文不是社区任务的最终交付件，而是完成社区任务的起步参考。开发者先按本文跑通示例，再按任务要求修改模型、量化规格、算法、脚本和 README，最终提交自己的可复现样例。

如果只想先跑通示例，可以直接从“本文示例流程”开始；如果已经准备领取社区任务，建议先阅读“领取任务后要改哪里”。

社区任务与参与入口

任务说明、奖品信息和验收标准以 AtomGit Issue 为准：

• 任务与奖品说明：社区任务：贡献 LLM 量化样例
• AMCT 仓库地址：https://atomgit.com/cann/amct
• 提交渠道：AMCT Pull Requests，样例提交到仓库 examples/models/ 目录
• 帖子入口：AMCT AtomGit Discussions
• 微信群二维码：二维码过期时，可在帖子中查看，也可以在Issue中留言。
  
  本次社区任务面向所有开发者开放，没有参与门槛。无论是第一次接触 AMCT，还是已经有大模型量化经验，都可以从本文示例开始，逐步完成自己的任务实践。欢迎大家领取任务、提交样例；遇到环境配置、运行命令、精度结果或交付格式问题，也欢迎进群讨论或在 Issue 中交流。

当前任务清单如下，完整要求请以任务 Issue 为准：

任务	难度	模型	数据类型	算法	奖品
1	L1	Qwen3-0.6B	w4a8	lwc + lac	螺丝刀工具套组
2	L1	Qwen3-0.6B	w4a8	flatquant	螺丝刀工具套组
3	L1	Qwen3-0.6B	w4a8	omniquant	螺丝刀工具套组
4	L1	Qwen3-0.6B	w4a8	autoround	螺丝刀工具套组
5	L1	Qwen3-0.6B	w4a4	lwc + lac	螺丝刀工具套组
6	L1	Qwen3-0.6B	w4a4	flatquant	螺丝刀工具套组
7	L1	Qwen3-0.6B	w4a4	omniquant	螺丝刀工具套组
8	L1	Qwen3-0.6B	w4a4	autoround	螺丝刀工具套组

每个任务都需要完成 int 和 mxfp 两种量化格式验证：w4a8 对应 int4/int8 与 mxfp4/mxfp8，w4a4 对应 int4/int4 与 mxfp4/mxfp4。

领取任务后要改哪里

开发者需要围绕所领取任务补齐样例代码、配置、脚本和 README，并重点修改以下内容：

需要修改的点	说明
模型与 --model_name	替换为任务指定模型，以及 AMCT 支持的模型名
量化数据类型和配置文件	根据任务选择 w4a8 / w4a4，并准备 int、mxfp 两份配置
PTQ 算法参数 --algos	根据任务选择 lwc lac、flatquant、omniquant 或 autoround
quant_target 与参数目录	覆盖 Attention 和 MLP/MoE，并保证提取、训练、评估阶段目录一致
脚本路径和产物目录	将一次性命令整理为可复用脚本，使用相对路径和占位路径
README 中的运行说明、产物说明和结果表	按任务 Issue 要求补齐中英文 README、产物大小和 PPL 结果

新手准备清单

开始执行命令前，建议先确认以下内容：

[ ] 已进入 CANNLab 或具备可用的昇腾 NPU 环境。
[ ] npu-smi info 能正常显示 NPU。
[ ] 已进入 AMCT 仓库根目录，后续命令默认在该目录执行。
[ ] python3 -c "import amct_pytorch" 和 python3 -c "import torch_npu" 可以正常运行。
[ ] 已设置 MODEL_DIR，并确认模型权重已下载到本地。
[ ] 当前环境可以访问 HuggingFace、hf-mirror 或 ModelScope，用于下载数据集和模型。
[ ] 已预留足够磁盘空间保存模型权重、PTQ 离线数据和 PTQ 参数；实际占用随模型大小、seq_len 和量化目标变化。
[ ] 已了解 PTQ 数据提取和训练耗时与模型大小、seq_len、NPU 性能相关，首次执行可能需要较长时间。
[ ] BF16 评估、PTQ 数据提取和 PTQ 后评估使用相同的 seq_len，否则 PPL 差值不具备可比性。

本文示例流程

本文以 Qwen/Qwen3-0.6B 为例，演示如何在 CANNLab 环境中使用 AMCT fake quant 模型，验证 W4A8 在 int 和 mxfp 两种数据类型下的量化精度。

整体思路是：先评估 BF16 模型作为精度基线，再提取 PTQ 离线数据并训练量化参数，最后加载 PTQ 参数评估量化模型，与 BF16 PPL 对比。

环境检查 -> 检查 AMCT Python 环境 -> 准备模型权重 -> BF16 基线
-> 分别提取 attention/MLP PTQ 数据 -> 分别训练 PTQ 参数
-> 分别评估 W4A8-int / W4A8-mxfp fake quant 精度

项	示例值
模型	Qwen/Qwen3-0.6B
AMCT 模型名	qwen3
量化目标	attn-linear 和 mlp
量化配置	amct_pytorch/configs/w4a8.yaml
量化数据类型	int、mxfp
PTQ 算法	lwc lac
评估口径	WikiText2 PPL, seq_len=4096

说明：W4A8 由 amct_pytorch/configs/w4a8.yaml 指定；--quant_dtype int 和 --quant_dtype mxfp 用于切换量化数据类型。两种数据类型的 PTQ 输出目录需要分开保存。

常用参数速查：

参数	含义	示例或注意事项
--model	本地模型权重目录	本文使用 $MODEL_DIR
--model_name	AMCT 内部模型适配名称	Qwen3 使用 qwen3
--seq_len	评估和数据提取序列长度	BF16、PTQ 数据提取和量化评估必须一致
--granularity	量化粒度	本文使用 block
--device	运行设备	本文使用 npu:0
--quant_target	量化目标模块	本文分别处理 attn-linear 和 mlp
--quant_dtype	量化数据格式	int 或 mxfp
--algos	PTQ 算法	本文使用 lwc lac
--bit_config	量化配置文件	W4A8 使用 amct_pytorch/configs/w4a8.yaml
--data_dir	PTQ 离线数据目录	提取和 PTQ 训练阶段必须一致
--output_dir	PTQ 参数输出目录	int 和 mxfp 建议分开保存

1. 进入 CANNLab / AMCT 环境

1.1 进入仓库并加载 CANN 环境

CANNLab 已预置运行环境，无需拉取 docker 镜像。登录 CANNLab 实例后，打开终端并进入 AMCT 仓库。本文后续命令默认在 AMCT 仓库根目录执行：

cd /home/code/amct

加载 CANN 环境变量：

export ASCEND_HOME_PATH=/home/developer/Ascend/cann
source "$ASCEND_HOME_PATH/set_env.sh"

1.2 检查 NPU

检查 NPU 是否可用：

npu-smi info

参考环境：

项	值
产品型号	Atlas A3 Pod 系列
操作系统	Linux ARM
镜像	amct_llm_images:v1
驱动	Ascend HDK 25.5.1
CANN 路径	/home/developer/Ascend/cann

1.3 配置数据源

数据集默认从 HuggingFace 官方源访问。若当前环境无法直连 huggingface.com，可切换到镜像源。两种方式二选一：

# 1. 使用 huggingface.com 官方源
unset HF_ENDPOINT
export HF_HUB_DISABLE_XET=1

# 2. 使用 hf-mirror 镜像源
export HF_ENDPOINT=https://hf-mirror.com
export HF_HUB_DISABLE_XET=1

后续命令默认用 MODEL_DIR 表示本地模型目录。seq_len 可按显存调整，但 BF16、PTQ 数据提取和 PTQ 后评估必须保持一致。

2. 检查 AMCT Python 环境

CANNLab / AMCT 开发环境通常已预置 AMCT 仓库和 Python 运行依赖。确认当前环境可用：

python3 -c "import amct_pytorch; print('AMCT ok')"
python3 -c "import torch_npu; print('torch_npu ok')"

仅在 import amct_pytorch 失败时，从源码构建并安装：

pip3 install -r requirements.txt
bash build.sh --torch
ls build_out/
pip3 install build_out/amct_pytorch-<version>-py3-none-linux_aarch64.tar.gz --user

若 pip 版本高于 25.2，安装包时追加 --no-build-isolation。安装后重新执行上面的验证命令。

3. 准备模型权重

设置本地模型目录。如果模型已存在，不需要重新下载：

export MODEL_DIR=/mnt/workspace/models/Qwen3-0.6B

如果本地还没有权重，再下载到 $MODEL_DIR。需要认证时先执行 modelscope login --token "$MODELSCOPE_API_TOKEN"。

pip3 install -U modelscope
mkdir -p "$MODEL_DIR"
modelscope download --model Qwen/Qwen3-0.6B --local_dir "$MODEL_DIR"

检查权重完整性：

test -f "$MODEL_DIR/config.json" && echo "config ok"
find "$MODEL_DIR" -maxdepth 1 -name "*.safetensors" | head

如果模型权重不是 safetensors 格式，请按实际权重文件类型检查；至少需要确认 config.json 和模型权重文件都已存在。

4. BF16 基线评估

python3 -m amct_pytorch.eval \
  --model "$MODEL_DIR" \
  --model_name qwen3 \
  --seq_len 4096 \
  --granularity block \
  --device npu:0 \
  --eval_mode bf16 \
  --bit_config amct_pytorch/configs/bf16.yaml

参考结果以本地实测为准：

Wikitext2-ppl=<ppl_bf16>

5. 提取 PTQ 数据

attn-linear 表示量化 Attention 线性层，mlp 表示量化 dense MLP。extract_ptq_data 一次只能处理一个 quant_target，因此需要分别提取两类目标的 PTQ 数据。

Attention 线性层：

python3 -m amct_pytorch.extract_ptq_data \
  --model "$MODEL_DIR" \
  --model_name qwen3 \
  --seq_len 4096 \
  --granularity block \
  --device npu:0 \
  --data_dir ptq_data/qwen3/attn-linear \
  --quant_target attn-linear

Dense MLP：

python3 -m amct_pytorch.extract_ptq_data \
  --model "$MODEL_DIR" \
  --model_name qwen3 \
  --seq_len 4096 \
  --granularity block \
  --device npu:0 \
  --data_dir ptq_data/qwen3/mlp \
  --quant_target mlp

检查数据：

find ptq_data/qwen3/attn-linear -maxdepth 1 -type f -name 'block_*_attn_in.pkl' | wc -l
find ptq_data/qwen3/mlp -maxdepth 1 -type f -name 'block_*_mlp_in.pkl' | wc -l

以上两条命令期望都输出 28。注意：attn-linear 的数据文件名使用内部 unit 名称，实际形如 block_*_attn_in.pkl，不是 block_*_attn-linear_in.pkl。

6. PTQ 训练

PTQ 数据可以复用；W4A8 的 int 和 mxfp 两种数据类型需要分别训练 PTQ 参数。以下命令使用 lwc lac 作为 PTQ 算法。

6.1 int

Attention 线性层：

python3 -m amct_pytorch.ptq \
  --model "$MODEL_DIR" \
  --model_name qwen3 \
  --seq_len 4096 \
  --granularity block \
  --device npu:0 \
  --data_dir ptq_data/qwen3/attn-linear \
  --quant_dtype int \
  --algos lwc lac \
  --bit_config amct_pytorch/configs/w4a8.yaml \
  --quant_target attn-linear \
  --output_dir ptq_result/int

Dense MLP：

python3 -m amct_pytorch.ptq \
  --model "$MODEL_DIR" \
  --model_name qwen3 \
  --seq_len 4096 \
  --granularity block \
  --device npu:0 \
  --data_dir ptq_data/qwen3/mlp \
  --quant_dtype int \
  --algos lwc lac \
  --bit_config amct_pytorch/configs/w4a8.yaml \
  --quant_target mlp \
  --output_dir ptq_result/int

默认参数目录：

ptq_result/int/ptq_params/qwen3/attn-linear
ptq_result/int/ptq_params/qwen3/mlp

检查 int 量化参数：

find ptq_result/int/ptq_params/qwen3 -maxdepth 3 -type f | head
du -sh ptq_result/int

6.2 mxfp

Attention 线性层：

python3 -m amct_pytorch.ptq \
  --model "$MODEL_DIR" \
  --model_name qwen3 \
  --seq_len 4096 \
  --granularity block \
  --device npu:0 \
  --data_dir ptq_data/qwen3/attn-linear \
  --quant_dtype mxfp \
  --algos lwc lac \
  --bit_config amct_pytorch/configs/w4a8.yaml \
  --quant_target attn-linear \
  --output_dir ptq_result/mxfp

Dense MLP：

python3 -m amct_pytorch.ptq \
  --model "$MODEL_DIR" \
  --model_name qwen3 \
  --seq_len 4096 \
  --granularity block \
  --device npu:0 \
  --data_dir ptq_data/qwen3/mlp \
  --quant_dtype mxfp \
  --algos lwc lac \
  --bit_config amct_pytorch/configs/w4a8.yaml \
  --quant_target mlp \
  --output_dir ptq_result/mxfp

默认参数目录：

ptq_result/mxfp/ptq_params/qwen3/attn-linear
ptq_result/mxfp/ptq_params/qwen3/mlp

检查 mxfp 量化参数：

find ptq_result/mxfp/ptq_params/qwen3 -maxdepth 3 -type f | head
du -sh ptq_result/mxfp

上述命令使用 AMCT 默认 PTQ 训练超参。评估阶段的 --algos 必须与对应数据类型的 PTQ 训练阶段保持一致。

7. PTQ 后评估

同时加载 attention 和 MLP 的 PTQ 参数，分别验证 W4A8-int 和 W4A8-mxfp fake quant 精度。

int：

python3 -m amct_pytorch.eval \
  --model "$MODEL_DIR" \
  --model_name qwen3 \
  --seq_len 4096 \
  --granularity block \
  --device npu:0 \
  --eval_mode quant \
  --quant_target attn-linear mlp \
  --quant_dtype int \
  --bit_config amct_pytorch/configs/w4a8.yaml \
  --algos lwc lac \
  --attn_linear_param_dir ptq_result/int/ptq_params/qwen3/attn-linear \
  --moe_mlp_param_dir ptq_result/int/ptq_params/qwen3/mlp

mxfp：

python3 -m amct_pytorch.eval \
  --model "$MODEL_DIR" \
  --model_name qwen3 \
  --seq_len 4096 \
  --granularity block \
  --device npu:0 \
  --eval_mode quant \
  --quant_target attn-linear mlp \
  --quant_dtype mxfp \
  --bit_config amct_pytorch/configs/w4a8.yaml \
  --algos lwc lac \
  --attn_linear_param_dir ptq_result/mxfp/ptq_params/qwen3/attn-linear \
  --moe_mlp_param_dir ptq_result/mxfp/ptq_params/qwen3/mlp

建议记录 BF16 PPL、W4A8-int PTQ PPL 和 W4A8-mxfp PTQ PPL：

delta_int = ppl_int - ppl_bf16
delta_mxfp = ppl_mxfp - ppl_bf16

结果记录模板：

模型	数据类型	量化格式	BF16 PPL	量化 PPL	PPL 差值	备注
Qwen3-0.6B	w4a8	int4/int8	<ppl_bf16>	<ppl_int>	<delta_int>	-
Qwen3-0.6B	w4a8	mxfp4/mxfp8	<ppl_bf16>	<ppl_mxfp>	<delta_mxfp>	-

本示例重点是通过 BF16 与两种 W4A8 fake quant 模型的 PPL 对比验证量化精度。替换其他 PTQ 算法时，需同步修改 PTQ 和评估命令中的 --algos 及参数目录。

8. 从示例整理为提交样例

跑通本文示例后，需要按社区任务要求整理为可提交样例。建议按以下顺序处理：

1. 在 examples/models/<model>/ 下新增任务样例目录。
2. 将本文中的命令整理为脚本，例如 eval_bf16.sh、extract_ptq_data.sh、ptq_attn.sh、ptq_mlp.sh、eval_quant.sh。
3. 将任务对应的量化配置放到 configs/ 目录，int 和 mxfp 两种格式分别保存。
4. 在中文和英文 README 中写清运行说明、参数含义、PTQ 离线数据目录、量化参数目录、产物大小和结果表。
5. 提交 PR 时，在 PR 描述中说明领取的任务编号、模型、数据类型、算法、BF16 PPL、量化 PPL 和 PPL 差值。

提交前建议检查：

# 将 qwen3-0.6b 替换为你的样例目录名
find examples/models/qwen3-0.6b -maxdepth 3 -type f | sort

模型权重、数据集和本地生成的 PTQ 数据不提交到仓库，只在 README 中说明准备方式和产物目录。

9. 常见问题

现象	检查项
数据集下载失败	尝试设置 HF_ENDPOINT=https://hf-mirror.com
Wikitext-2 load失败	改用 load_dataset(“Salesforce/wikitext”, “wikitext-2-raw-v1”, split=“test”)
ArrowInvalid: Index not in dictionary bounds	pip3 install --user --force-reinstall “datasets3.6.0" "pyarrow18.1.0”
找不到 CANN 环境变量	是否执行 source /home/developer/Ascend/cann/set_env.sh
torch_npu 导入失败	Python、PyTorch、torch_npu、CANN 版本是否匹配
BF16 PPL 异常	权重是否完整，--model_name 是否为 qwen3
运行过程中显存不足	降低 --seq_len，并保证 BF16、PTQ 数据提取和量化评估的 seq_len 一致
PTQ 找不到数据	--data_dir、--quant_target 是否和数据提取阶段一致
量化评估未加载 PTQ 参数	--attn_linear_param_dir 和 --moe_mlp_param_dir 是否指向正确目录
PPL 差值无法比较	BF16 和量化评估是否使用同一模型版本、同一数据集、同一 seq_len
替换 PTQ 算法后结果异常	PTQ 训练和评估命令中的 --algos 是否完全一致

更多参数说明见 AMCT PyTorch LLM 量化工具使用说明。