Skip to content

PTQ-Level Efficiency, QAT-Level Accuracy | 训练后量化的效率,量化感知训练的精度

28.9 KB
Raw Blame

AutoRound Overview

训练后量化的效率,量化感知训练的精度

python version nightly license Model Checkpoints PyPI Downloads

简体中文 | English        

用户指南 | User Guide  


🚀 AutoRound 是什么?

AutoRound 是一个面向大语言模型(LLMs)和视觉-语言模型(VLMs)的易用型训练后量化工具包。它支持多种实用的低比特和自适应比特量化算法,特别是主推的 SignRoundV1 和 SignRoundV2算法。 AutoRound 旨在以合理的量化成本在低比特场景下实现出色的精度表现。它支持常用的数据类型和量化方案,包括 WNA16、MXFP4、NVFP4 和 FP8,以及 GGUF 等低比特模型格式。 它已集成到 Transformers、vLLM 和 SGLang 等主流生态中,并支持在 Intel CPU、XPU、Gaudi 加速器以及 NVIDIA GPU 上部署。 更多使用细节请参阅用户指南。

AutoRound Overview

🆕 最新进展

  • [WIP] 对于 4 bit 及以上的量化,我们目前建议采用 75% UltraChat + 25% OpenCode 的混合数据集,以提升模型的推理能力和 Agentic 任务能力。使用默认配置 nsamples=128 时,请指定 --dataset "HuggingFaceH4/ultrachat_200k:num=96,nvidia/OpenCodeInstruct:num=32"。详情请参阅校准数据集文档。待评测全部完成后,我们将更新默认校准数据集。

  • [2026/10] 我们现在展示:W2A16 的精度会随着调优成本的增加而稳步提升。详细精度数据见 W2A16 精度数据。

  • [2026/09] 我们将 MoE量化速度提升了 3 倍以上,并显著降低了 RAM 使用量。详细结果请参阅文档。请注意,该优化可能会引入一些回归问题或其他问题。

  • [2026/09] 现在支持在 CUDA 设备上通过 vLLM 和 Transformers 使用 5/6/7-bit WOQ 模型,感谢 Humming Kernel 的支持。

  • [2026/09] 面向免标定量化的 NeUQI 网格搜索(arXiv 2505.17595)现已可用:--enable_neuqi 配合 --iters 0 时,非对称层执行联合 (scale, zero-point) 搜索、对称层执行两阶段 scale 搜索;iters > 0 时搜索结果将作为调优网格的锚点:结果。

  • [2026/08] 我们实验性地支持算法组合(例如 --algs awq,signround 或 --algs hadamard,awq,signround),以提升精度:总览. 我们欢迎能真正落地的任何算法组合,欢迎提交 PR 或在 Issues 中留言。

  • [2026/08] 感谢 Humming Kernel,AutoScheme WOQ 在 vLLM 上的部署已实验性恢复:vLLM PR,示例模型。注意:共享层需按 vLLM 的融合模式进行配置。

  • [2026/07] 在大多数场景默认启用 torch.compile,以加速量化,代价是~10G的额外内存使用。由于编译器优化,与未编译路径相比可能会出现细微的数值差异,这是符合预期的。如需关闭,可在 Python API 中传入 enable_torch_compile=False,或在命令行中使用 --disable_torch_compile。

  • [2026/06] AutoScheme对gguf格式优化,精度有所提升。具体结果请参考文档。不过这些精度提升是以更高的调优时间和计算开销为代价的。

  • [2026/06] vLLM-Omni 现已完全集成 AutoRound: vLLM 博客

  • [2026/05] 我们提供免费的硬件资源进行模型量化。更多详情请访问 Intel Low Bit Open LLM Leaderboard。

  • [2026/05] 现已支持免模型架构量化模式, auto-round-rtn 现在会默认启用免模型方式: 文档.

  • [2026/03] 支持Block-wise FP8,只需要将scheme改成 --scheme FP8_BLOCK.为了更快的量化,我们推荐使用RTN模式,即auto-round-rtn

  • [2026/03] 支持MTP层量化

  • [2025/12] 发布 SignRoundV2 论文。如果要复现论文成果,可启用算法扩展(--algorithm auto_round_v2,原 enable_alg_ext),并使用 AutoScheme API 对模型进行混合精度量化。相关链接:论文,LLaMA 模型评估说明。

  • [2025/11] LLM-Compressor 已支持 AutoRound 算法。相关链接:使用方法,vLLM 博客,RedHat 博客,X 推文,Intel 博客,LinkedIn,微信,知乎。

  • [2025/11] 推出 增强版 GGUF 量化算法,启用算法扩展(--algorithm auto_round_v2,原 --enable_alg_ext)即可。相关链接:Accuracy。

  • [2025/10] SGLang 已集成 AutoRound。相关链接:使用方法,LMSYS 博客,X 推文,Intel 博客,LinkedIn。

  • [2025/10] 推出 混合精度 算法,可在几分钟内自动生成混合精度方案。相关链接:使用方法,Accuracy。

  • [2025/09] 新增对 MXFP4 和 NVFP4 数据类型的支持。相关链接:Accuracy。

  • [2025/08] 提供 改进版 INT2 算法,启用算法扩展(--algorithm auto_round_v2,原 --enable_alg_ext)即可。相关链接:Accuracy。

  • [2025/07] 新增 GGUF 格式导出。相关链接:使用方法。

  • [2025/05] vLLM 现已集成 AutoRound。相关链接:使用方法,Medium 博客,小红书。

  • [2025/05] Transformers 已集成 AutoRound。相关链接:博客。

  • [2025/03] 约 200GB 的 DeepSeek-R1 模型经量化(INT2混合精度)后精度仍高达 97.9%。相关链接:模型。

✨ 核心特性

✅ 模型精度卓越 在 2–3 bit 的极低精度下,模型也能保持强劲性能(示例模型);在 4 bit 量化上,模型的基准测试成绩也处在领先水平。

✅ 生态集成度好 与 Transformers、vLLM、SGLang 等主流框架无缝衔接。

✅ 导出格式丰富 支持导出为 ​AutoRound、AutoAWQ、AutoGPTQ 及 GGUF​ 格式。相关链接:导出格式

✅ 自动混合精度 可在几分钟内自动生成混合 bit 策略(但需要额外占用模型在 BF16 格式下内存占用量的 1.1-1.5 倍)。详见:Accuracy 结果 和 用户指南

✅ 优化的 RTN 模式 使用 --iters 0​ 参数可启用优化的 Round-to-Nears 模式,实现快速量化(但在 4 bit 下准确度会有一定降低)。详见:opt_rtn 模式。

✅ 可接受的量化成本 在单张 GPU 上量化一个 7B 的模型只需约十分钟。详见:量化成本

✅ 支持十余种 VLM 模型 已支持十余种视觉语言模型,让用户有“开盖即食”般的量化体验。详见:示例模型,支持矩阵

✅ 多种量化方案可选 提供 auto-round-best​、auto-round​、auto-round-light​、auto-round-opt-rtn(优化版 RTN)以及 auto-round-rtn(原始 RTN,最快基线)等多种预设方案,能够满足多样化需求。详见:量化方案

Python 可通过 AutoRound(..., recipe="auto-round-best") 使用同一方案,CLI 可使用 --recipe auto-round-best。不传 recipe 默认选择 auto-round,已有命令保留为快捷入口。详见内置 Recipe 与覆盖规则。

✅ 实用额外特性 支持多 GPU 量化和多标定数据集,并兼容十余种推理后端。

✅ 不局限于权重量化 我们正积极扩展对 MXFP、NVFP、W8A8 等更多数据类型的支持。

安装

从 PyPI 安装

# CPU(Xeon)/GPU(CUDA)
pip install auto-round

# CPU(Xeon)/GPU(CUDA) nightly
pip install auto-round-nightly

# HPU(Gaudi)
# 在 hpu docker container 中安装, e.g. vault.habana.ai/gaudi-docker/1.23.0/ubuntu24.04/habanalabs/pytorch-installer-2.9.0:latest  
pip install auto-round-hpu

# XPU(Intel GPU)
pip install torch --index-url https://download.pytorch.org/whl/xpu
pip install auto-round
从源码编译安装
# CPU(Xeon)/GPU(CUDA)
pip install .

# HPU(Gaudi)
python setup.py install hpu

# XPU(Intel GPU)
pip install torch --index-url https://download.pytorch.org/whl/xpu
pip install .

模型量化(CPU / Intel GPU / Gaudi / CUDA)

如果在量化过程中遇到问题,可尝试启动纯 RTN 模式,具体是指将 iters 设置为 0 并打开 disable_opt_rtn=True。另外,使用 group_size=32 或混合比特也有助于提升效果。

CLI 用法

终端运行 auto-round -h 可以查看 auto-round 完整的参数列表。

支持通过 ModelScope 下载模型(只需设置 ​​AR_USE_MODELSCOPE=1​ )。

auto-round \
    --model Qwen/Qwen3-0.6B \
    --scheme "W4A16" \
    --format "auto_round" \
    --output_dir ./tmp_autoround

另外,我们还提供 auto-round-best​ 和 auto-round-light 两种方案,前者旨在追求更高的模型精度,后者则专注于提升量化速度。具体细节如下:

其他方案
# 最佳精度,速度慢 3 倍,low_gpu_mem_usage 可节省 ~20G 显存,但会慢 ~30%-100%
auto-round-best \
  --model Qwen/Qwen3-0.6B \
  --scheme "W4A16" \
  --low_gpu_mem_usage
# 2–3 倍加速,W4 下准确度略降,W2 下准确度下降更明显
auto-round-light \
  --model Qwen/Qwen3-0.6B \
  --scheme "W4A16"
# 无需标定的优化版 RTN(iters=0,启用 opt_rtn),快速基线方案
auto-round-opt-rtn \
  --model Qwen/Qwen3-0.6B \
  --scheme "W4A16"
# 原始 RTN(iters=0,不做任何 AutoRound 优化),速度最快、显存占用最低
# 对受支持的 INT WOQ scheme 会自动路由到 model-free 模式
auto-round-rtn \
  --model Qwen/Qwen3-0.6B \
  --scheme "W4A16"

小结:对于 ​W4A16 量化,我们建议使用默认的 auto-round;而 W2A16 量化我们则推荐启用 ​--algorithm auto_round_v2​ 的 auto-round-best​。当然,您也可以根据自身需求和手头上的算力灵活调整配置。

[!TIP] 对于 INT2(W2A16),精度会随着调优成本的增加而稳步提升。增大 --iters(例如 1000 → 2000)、--nsamples、--seqlen 等参数,或改用带 --enable_alg_ext 的 auto-round-best 配方,都能以额外的调优时间换取持续更高的精度。随着校准数据量的增大(更大的 --nsamples/--seqlen),将学习率提高到 4.0/iters(例如 --iters 1000 时取 4e-3)通常会有帮助。详细结果请参阅 W2A16 精度数据。

API 用法

from auto_round import AutoRound

# 加载模型(支持 FP8 / BF16 / FP16 / FP32)
model_name_or_path = "Qwen/Qwen3-0.6B"

# 可选量化配置:
# "W2A16", "W3A16", "W4A16", "W8A16", "NVFP4", "MXFP4"(无真实 kernel), "GGUF:Q4_K_M" 等
ar = AutoRound(model_name_or_path, scheme="W4A16")

# 追求高模型精度(速度会慢 4–5 倍)
# `low_gpu_mem_usage=True` 可节省 ~20GB 显存,但会慢 ~30%
# ar = AutoRound(model_name_or_path, nsamples=512, iters=1000, low_gpu_mem_usage=True)

# 追求量化速度(提速 2–3 倍),但在 W4G128 下精度会略微下降
# ar = AutoRound(model_name_or_path, nsamples=128, iters=50, lr=5e-3)

# 支持的导出格式:"auto_round"(默认), "auto_gptq", "auto_awq", "llm_compressor", "gguf:q4_k_m" 等
ar.quantize_and_save(output_dir="./qmodel", format="auto_round")
核心超参数
量化方案 & 配置
  • ​​scheme​​(str | dict | AutoScheme):预定义的如 W4A16​、MXFP4​、NVFP4​、GGUF:Q4_K_M等量化配置标识。其中对于 MXFP4/NVFP4 方案,我们推荐导出为 LLM-Compressor 格式。
  • ​​bits​​(int):量化目标精度(默认值为 None)。若指定此参数,将覆盖 scheme 中的设置。
  • ​​group_size​​(int):量化分组大小(默认值为 None)。若指定此参数,将覆盖 scheme 中的设置。
  • ​​sym​​(bool):是否使用对称量化(默认值为 None)。若指定此参数,将覆盖 scheme 中的设置。
  • ​​layer_config​​(dict):层级自定义配置(默认值为 None)。主要用于自定义混合化方案,可以对每一层设置专门的量化参数。
算法相关设置
  • ​​enable_alg_ext​​(bool):[已弃用] 请改用 auto_round_v2 算法。[实验性功能] 仅在 iters > 0​ 时生效。在特定 scheme(如 MXFP4 / W2A16)下启用算法扩展,可显著提升量化效果。默认值为 False。
  • alg_configs(str | Config | list):选择一个或多个算法,例如 "awq"、"auto_round"、"auto_round_v2"、"rtn"、"opt-rtn" 或 ['auto_round', 'quarot']。预处理算法按照列表顺序执行,block quantizer 始终最后执行。算法专用参数可以通过对应的 config 对象传入,例如 SignRoundConfig(iters=50)。
  • ​​disable_opt_rtn​​(bool | None):是否对特定方案(如 GGUF 与权重量化方案)禁用优化的 RTN 模式。优化的 RTN 模式需要标定数据和更多的算力来提升精度。默认值为 None:在大多数情况下,为提升精度,算法会自动采用优化的 RTN 模式(即 False);仅在已知存在兼容性问题时,才会自动禁用(即 True)。算法名 rtn 表示纯 RTN,opt-rtn 表示优化 RTN,命令行(--algorithm rtn)与 Python API(alg_configs="rtn")一致;算法名优先于该开关。
训练参数
  • ​​iters​​(int):训练迭代次数(tuning iterations)(默认值为 200​)。常用取值:0(RTN 模式)、50(推荐搭配 lr=5e-3)、1000(更高精度但量化速度慢)。也就是说迭代次数越多,准确度越高,但速度越慢。
  • ​​lr​​(float):舍入值(rounding rate)的学习率(默认值为 None​)。当为 None 时,将自动设为 1.0/iters。
  • ​​batch_size​​(int):训练批次大小(batch size)。默认为 8​,也常用 4。
  • ​​enable_deterministic_algorithms​​(bool):若想保证结果可以复现,可以设为 True 来启用确定性算法(默认 False)。
标定数据集
  • ​​dataset​​(str | list | tuple | DataLoader):量化中用于校准的数据集(默认 "NeelNanda/pile-10k"​)。支持本地 JSON 文件和数据集组合使用,如 "./tmp.json,NeelNanda/pile-10k:train,mbpp:train+validation+test"。
  • I2V 标定默认使用与 COCO2014 caption 配对的真实图片。采样前会关联 COCO 官方元数据,仅保留知识共享署名 2.0(CC BY 2.0,license ID 4)图片;筛选后的清单会保留许可证和 Flickr 来源 URL。清单和选中的图片均缓存在 ~/.cache/auto_round/datasets/coco2014;设置 AUTO_ROUND_CACHE 后则缓存在 $AUTO_ROUND_CACHE/datasets/coco2014。T2V 仍只在内存中解析 caption 清单,不使用该缓存。也可使用包含 id、caption 和 image 列的本地 TSV;image 支持绝对路径或相对于 TSV 的路径。
  • ​​nsamples​​(int):校准时使用的样本数(默认 128)。
  • ​​seqlen​​(int):每条样本在校准时使用 token 的序列长度(默认 2048)。
设备 / 速度配置
  • ​​enable_torch_compile​(bool):启用 torch.compile 可能提升量化速度,但编译开销会改变峰值内存,某些模型或量化方案的峰值内存可能增加。除 Windows 外默认开启;Windows 上默认关闭,因为 TorchInductor 需要 MSVC 的 cl.exe 编译器。在 Windows 上可通过 Python 参数 enable_torch_compile=True 或命令行参数 --enable_torch_compile 强制开启;其他平台可使用 enable_torch_compile=False 或 --disable_torch_compile 关闭。
  • ​​low_gpu_mem_usage​​(bool):若要节省显存,可以设为 True 。它会将中间特征卸载到 CPU,但会增加 30%-100% 的时间(默认 False)。
  • ​​low_cpu_mem_usage​​(bool):[实验性功能] 用于启用即时保存以减少内存占用。该功能默认开启;在 CLI 中可使用 --disable_low_cpu_mem_usage 关闭(--low_cpu_mem_usage 仅为兼容旧参数保留)。
  • ​​device_map​​(str | dict | int):计算设备指定,如 auto​、cpu​、cuda​、0,1,2​(默认 0​)。使用 auto 时会尝试利用所有可用 GPU。
  • calibration_data_device(str):多 GPU 运行时块校准数据的存放位置:auto(默认)| cpu | off | 1,2 | cuda:1,cuda:2。

支持的量化方案

详细说明 可以看到有些 schemes 为灰色背景,这通常表示它没有专门优化的内核,或只有效率极低的参考内核。 其中, BF16 主要适用于 AutoScheme(其他方案一般不用)。
格式 支持的scheme
auto_round W4A16(推荐)、W2A16、W3A16、W8A16、W2A16G64、W2A16G32、MXFP4​、MXFP8​、MXFP4_RCEIL​、MXFP8_RCEIL​、NVFP4​、FPW8A16​、FP8_STATIC​、BF16
auto_awq W4A16(推荐)、BF16
auto_gptq W4A16(推荐)、W2A16、W3A16、W8A16、W2A16G64、W2A16G32、BF16
llm_compressor NVFP4(推荐)、MXFP4​、MXFP8​、FPW8A16​、FP8_STATIC、FP8_BLOCK、INT8、W4A16、W8A16
gguf GGUF:Q4_K_M(推荐)、Auto-RoundGGUF:Q2_K_S、GGUF:Q3_K_S、GGUF:Q3_K_M、GGUF:Q3_K_L、GGUF:Q4_K_S、GGUF:Q5_K_S、GGUF:Q5_K_M、GGUF:Q6_K、GGUF:Q4_0、GGUF:Q4_1、GGUF:Q5_0、GGUF:Q5_1、GGUF:Q8_0
fake ​所有方案(仅用于研究)

自适应量化方案(AutoScheme)(实验性功能)

AutoScheme 提供了一种自动生成算法,用于生成 自适应的混合精度/数据类型 的量化方案(mixed bits/data type quantization recipes)。关于 AutoScheme 的更多细节可参考用户指南。

from auto_round import AutoRound

model_name = "Qwen/Qwen3-8B"
layer_config = {"lm_head": "GGUF:Q6_K"}

# 对于非 GGUF 方案,将 iters 改为 200
ar = AutoRound(
    model=model_name,
    schemes=("GGUF:Q2_K_S", "GGUF:Q4_K_S"),
    bits=3.0,
    ignore_scale_zp_bits=True,
    layer_config=layer_config,
    iters=0,
)
ar.quantize_and_save()
AutoScheme 核心超参数说明
AutoScheme 超参数
  • ​​bits​​ (float) :传入 schemes 时,为整个模型的目标平均 bits(平均 bits 的计算仅包含被量化的层)。未提供 schemes 时,bits 为普通权重量化位宽,必须为整数。
  • ​​schemes​​ (str | list[str] | list[QuantizationScheme]) ​:候选量化配置集合。支持以下表示形式:单个用逗号分隔的字符串(例如 "W4A16,W2A16"​)、字符串列表(例如 ["W4A16", "W2A16"]​)和 QuantizationScheme 。传入 schemes 即启用 AutoScheme。
  • ​​ignore_scale_zp_bits​​ (bool) ​:仅支持 API 调用场景。用于决定在计算平均 bit 时,是否忽略 scale 与 zero-point 的位数(默认 False)。
  • ​​shared_layers​​ (Iterable[Iterable[str]], optional) :仅支持 API 调用场景,用于定义多个层的分组,这些层将共享相同的量化配置。
  • ​​batch_size​​ (int, optional) ​:仅支持 API 调用场景。设为 1 可以降低显存占用,但同时会增加训练时间。

视觉语言模型(VLM)的 API 调用方法

点击展开

该功能仍在实验阶段

默认情况下,AutoRound 只会量化 VLM 的文本模块,并默认采用 NeelNanda/pile-10k​ 作为标定数据集。若需量化整个模型,可设置 quant_nontext_module = True (但目前为止该功能的适用范围仍较为有限)。更多信息请参考 readme

from auto_round import AutoRound

# 加载模型
model_name_or_path = "Qwen/Qwen2.5-VL-7B-Instruct"
# 量化模型
ar = AutoRound(model_name_or_path, scheme="W4A16")
output_dir = "./qmodel"
ar.quantize_and_save(output_dir)

模型推理

vLLM(CPU / Intel GPU / CUDA)

from vllm import LLM, SamplingParams

prompts = [
    "Hello, my name is",
]
sampling_params = SamplingParams(temperature=0.6, top_p=0.95)
model_name = "Intel/DeepSeek-R1-0528-Qwen3-8B-int4-AutoRound"
llm = LLM(model=model_name)

outputs = llm.generate(prompts, sampling_params)

for output in outputs:
    prompt = output.prompt
    generated_text = output.outputs[0].text
    print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")

SGLang(Intel GPU / CUDA)

注意:目前对混合专家模型(MoE)模型和视觉语言(VLM)模型的支持尚不完善。

import sglang as sgl

llm = sgl.Engine(model_path="Intel/DeepSeek-R1-0528-Qwen3-8B-int4-AutoRound")
prompts = [
    "Hello, my name is",
]
sampling_params = {"temperature": 0.6, "top_p": 0.95}

outputs = llm.generate(prompts, sampling_params)
for prompt, output in zip(prompts, outputs):
    print(f"Prompt: {prompt}\nGenerated text: {output['text']}")

Transformers(CPU / Intel GPU / Gaudi / CUDA)

AutoRound 支持十余种推理后端,并会根据已安装的库自动选择最优后端;如果检测到系统中存在更优后端但缺少相关依赖,也会主动提示用户安装。

​请勿在推理过程中手动将量化后的模型迁移到其他设备​(例如执行 model.to('cpu')),否则可能导致意外错误。

目前对 Gaudi 设备的支持尚不完善。

from transformers import AutoModelForCausalLM, AutoTokenizer

model_name = "Intel/DeepSeek-R1-0528-Qwen3-8B-int4-AutoRound"
model = AutoModelForCausalLM.from_pretrained(model_name, device_map="auto", torch_dtype="auto")
tokenizer = AutoTokenizer.from_pretrained(model_name)
text = "There is a girl who likes adventure,"
inputs = tokenizer(text, return_tensors="pt").to(model.device)
print(tokenizer.decode(model.generate(**inputs, max_new_tokens=50)[0]))

研究成果 & 其他活动

SignRoundV2: Closing the Performance Gap in Extremely Low-Bit Post-Training Quantization for LLMs(202512 论文)

Optimize Weight Rounding via Signed Gradient Descent for the Quantization of LLM(202309 论文)

TEQ: Trainable Equivalent Transformation for Quantization of LLMs(202310 论文)

Effective Post-Training Quantization for Large Language Models(202304 博客)

更多内容请查看 完整论文列表.

致谢

特别感谢 AutoGPTQ、AutoAWQ、GPTQModel、Triton、Marlin、ExLLaMAV2 等开源低精度库,它们提供的低精度 CUDA 内核(low-precision CUDA kernel)为 AutoRound 的实现提供了重要支持。

🌟 支持我们

如果觉得 AutoRound 对你有帮助,欢迎给 repo 点个 ⭐ 并转发到你的社区~