Skip to content

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

Add Links; Add step_by_step_CN; Fix several grammatical issues (#1366)

ZaneMark3b7b87ece607
diff --git a/README.md b/README.md
index 11edde19b..82f712023 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,9 @@
<img alt="Model Checkpoints" src="https://img.shields.io/badge/%F0%9F%A4%97%20HF-Models-F57C00">
</a>
-English | [User Guide](./docs/step_by_step.md) | [简体中文](README_CN.md)
+&nbsp;&nbsp;&nbsp;&nbsp;English | [简体中文](README_CN.md)
+
+[User Guide](./docs/step_by_step.md) | [用户指南](./docs/step_by_step_CN.md)&nbsp;&nbsp;
---
<div align="left">
diff --git a/README_CN.md b/README_CN.md
index 4f577e76a..d3054abd1 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -16,7 +16,9 @@
<img alt="Model Checkpoints" src="https://img.shields.io/badge/%F0%9F%A4%97%20HF-Models-F57C00">
</a>
-[English](README.md) | 简体中文 | [用户指南](./docs/step_by_step.md)
+&nbsp;&nbsp;&nbsp;&nbsp;[English](README.md) | 简体中文
+
+[User Guide](./docs/step_by_step.md) | [用户指南](./docs/step_by_step_CN.md)&nbsp;&nbsp;
---
<div align="left">
@@ -72,7 +74,7 @@ AutoRound 是专为大语言模型(LLMs)和视觉-语言模型(VLMs)设
✅ **支持十余种 VLM 模型** 已支持十余种视觉语言模型,让用户有“开盖即食”般的量化体验。详见:[示例模型](https://huggingface.co/collections/OPEA/vlms-autoround-675bc712fdd6a55ebaf11bfa),[支持矩阵](https://github.com/intel/auto-round/tree/main/auto_round/mllm#support-matrix)
-✅ **多种量化方案可选** 提供`auto-round-best`​、`auto-round`​、`auto-round-light`​ 等多种预设方案,能够满足多样化需求。详见:[量化方案](https://github.com/intel/auto-round/blob/main/docs/step_by_step.md#recipe-recommendation)
+✅ **多种量化方案可选** 提供 `auto-round-best`​、`auto-round`​、`auto-round-light`​ 等多种预设方案,能够满足多样化需求。详见:[量化方案](https://github.com/intel/auto-round/blob/main/docs/step_by_step.md#recipe-recommendation)
✅ **实用额外特性** 支持[多 GPU 量化](https://github.com/intel/auto-round/blob/main/docs/step_by_step.md#devicemulti-gpu-setting-in-quantization)和[多标定数据集](https://github.com/intel/auto-round/blob/main/docs/step_by_step.md#default-dataset),并兼容[十余种推理后端](https://github.com/intel/auto-round/blob/main/docs/step_by_step.md#specify-inference-backend)。
@@ -88,7 +90,7 @@ AutoRound 是专为大语言模型(LLMs)和视觉-语言模型(VLMs)设
pip install auto-round
# HPU
-pip install auto-round-lib
+pip install auto-round-hpu
```
<details>
@@ -99,7 +101,7 @@ pip install auto-round-lib
pip install .
# HPU
- python setup.py install lib
+ python setup.py install hpu
```
</details>
@@ -120,7 +122,7 @@ auto-round \
--output_dir ./tmp_autoround
```
-另外,我们还提供`auto-round-best`​ 和 `auto-round-light`两种方案,前者旨在追求更高的模型精度,后者则专注于提升量化速度。具体细节如下:
+另外,我们还提供 `auto-round-best`​ 和 `auto-round-light` 两种方案,前者旨在追求更高的模型精度,后者则专注于提升量化速度。具体细节如下:
<details>
@@ -255,7 +257,7 @@ ar.quantize_and_save()
##### AutoScheme 超参数
- ​**​`avg_bits`​**​ **(float)** :整个模型的目标平均 bits(平均 bits 的计算仅包含被量化的层)。
-- ​**​`options`​**​ **(str | list[str] | list[QuantizationScheme])** ​:候选量化方配置集合。支持以下表示形式:单个用逗号分隔的字符串(例如 `"W4A16,W2A16"`​)、字符串列表(例如 `["W4A16", "W2A16"]`​)和 `QuantizationScheme` 。
+- ​**​`options`​**​ **(str | list[str] | list[QuantizationScheme])** ​:候选量化配置集合。支持以下表示形式:单个用逗号分隔的字符串(例如 `"W4A16,W2A16"`​)、字符串列表(例如 `["W4A16", "W2A16"]`​)和 `QuantizationScheme` 。
- ​**​`ignore_scale_zp_bits`​**​ **(bool)** ​:仅支持 API 调用场景。用于决定在计算平均 bit 时,是否忽略 scale 与 zero-point 的位数(默认 `False`)。
- ​**​`shared_layers`​**​ **(Iterable[Iterable[str]], optional)** :仅支持 API 调用场景,用于定义多个层的分组,这些层将共享相同的量化配置。
- ​**​`batch_size`​**​ **(int, optional)** ​:仅支持 API 调用场景。设为 `1` 可以降低显存占用,但同时会增加训练时间。
@@ -264,7 +266,7 @@ ar.quantize_and_save()
### 视觉语言模型(VLM)的 API 调用方法
-如果在量化过程中遇到问题可尝试启动RTN 模式,具体是指将 `iters` 设置为 `0`并打开 `disable_opt_rtn`。另外可以将 `group_size` 设为 `32` 可以提升RTN模型的精度,副作用是有一定的性能下降。
+如果在量化过程中遇到问题可尝试启动 RTN 模式,具体是指将 `iters` 设置为 `0` 并打开 `disable_opt_rtn`。另外可以将 `group_size` 设为 `32` 可以提升RTN模型的精度,副作用是有一定的性能下降。
<details>
@@ -362,9 +364,8 @@ print(tokenizer.decode(model.generate(**inputs, max_new_tokens=50)[0]))
## 致谢
-特别感谢 AutoGPTQ、AutoAWQ、GPTQModel、Triton、Marlin、ExLLaMAV2 等开源低精度库,它们提供的低精度 CUDA 内核(low-precision CUDA kernel)为 AutoRound 的实现提供了重要的支持。
+特别感谢 AutoGPTQ、AutoAWQ、GPTQModel、Triton、Marlin、ExLLaMAV2 等开源低精度库,它们提供的低精度 CUDA 内核(low-precision CUDA kernel)为 AutoRound 的实现提供了重要支持。
## 🌟 支持我们
如果觉得 AutoRound 对你有帮助,欢迎给 repo 点个 ⭐ 并转发到你的社区~
-
diff --git a/docs/step_by_step.md b/docs/step_by_step.md
index 40fff76d9..b5027dc11 100644
--- a/docs/step_by_step.md
+++ b/docs/step_by_step.md
@@ -1,6 +1,8 @@
Step-by-Step
============
+English | [简体中文](./step_by_step_CN.md)
+
This document presents step-by-step instructions for auto-round llm quantization. You can refer to [vlms user guide](../auto_round/compressors/mllm/README.md) for vlms quantization and [diffusions user guide](../auto_round/compressors/diffusion/README.md) for diffusions quantization.
* [1 Prerequisite](#1-prerequisite)
diff --git a/docs/step_by_step_CN.md b/docs/step_by_step_CN.md
new file mode 100644
index 000000000..23aa960e2
--- /dev/null
+++ b/docs/step_by_step_CN.md
@@ -0,0 +1,755 @@
+操作指南
+============
+
+[English](./step_by_step.md) | 简体中文
+
+本文档介绍了如何用 auto-round 量化大语言模型(LLM)。如需量化视觉大语言模型(VLM),请参阅[视觉大语言模型用户指南](../auto_round/compressors/mllm/README.md);如需量化扩散模型,请参阅[扩散模型用户指南](../auto_round/compressors/diffusion/README.md)。
+
+* [1 安装必要库](#1-安装必要库)
+* [2 准备标定数据集](#2-准备标定数据集)
+ + [默认数据集](#默认数据集)
+ + [自定义数据集](#自定义数据集)
+ + [数据集操作](#数据集操作)
+* [3 模型量化](#3-模型量化)
+ + [可选量化配置](#可选量化配置)
+ + [支持的导出格式](#支持的导出格式)
+ + [硬件兼容性](#硬件兼容性)
+ + [环境参数配置](#环境参数配置)
+ + [命令行使用方法](#命令行用法)
+ + [API 使用方法](#API-使用方法)
+ - [AutoRound API 基础用法](#AutoRound-API-基础用法)
+ - [混合精度量化方案](#混合精度量化)
+ - [AutoRoundBest 配置方案](#AutoRoundBest-高精度配置用法)
+ - [AutoRoundLight 配置方案](#AutoRoundLight-高速度配置用法)
+ - [超参方案推荐](#超参方案推荐)
+ + [AutoScheme 自动混合精度量化方案](#AutoScheme-自动混合精度量化方案)
+ - [命令行用法](#命令行用法-1)
+ - [API 用法](#API-用法)
+ - [AutoScheme 中的超参数](#AutoScheme-超参数说明)
+ + [OPT RTN 模式](#OPT-RTN-模式)
+ + [GGUF 格式](#GGUF-格式量化)
+ + [量化成本](#量化成本)
+ + [设备及多卡量化设置](#设备及多卡量化设置)
+ - [lm_head 量化中开启多 GPU 标定](#lm_head-量化中开启多-GPU-标定)
+ - [手动配置设备映射](#手动配置设备映射)
+ + [超参数调整](#超参数调整)
+* [4 推理部署](#4-推理部署)
+ + [CPU](#CPU)
+ + [英特尔 GPU](#英特尔-GPU)
+ + [CUDA](#CUDA)
+ + [HPU](#HPU)
+ + [指定推理后端](#指定推理后端)
+ + [将 GPTQ/AWQ 模型转换为 AutoRound 格式](#将-GPTQ-或-AWQ-模型转换为-AutoRound-格式)
+* [5 效果评估](#5-效果评估)
+ + [单卡评估](#单-GPU-评估)
+ + [多卡评估](#多-GPU-评估)
+ + [注意事项](#注意事项)
+* [6 已知问题](#6-已知问题)
+
+## 1 安装必要库
+
+请执行下面的指令安装 auto-round 库(或从源码编译安装)
+
+```bash
+pip install auto-round
+```
+
+## 2 准备标定数据集
+
+### 默认数据集
+**对于中国大陆用户推荐使用 ModelScope 中的 swift/pile-val-backup 以解决 Huggingface 不能访问的问题**
+
+默认标定数据集为 Hugging Face 上的 [NeelNanda/pile-10k](https://huggingface.co/datasets/NeelNanda/pile-10k) ,该数据集会自动从 Huggingface Hub 下载。同时也支持使用以下数据集:
+- ModelScope 中的 `swift/pile-val-backup`:用于解决 HF 访问问题
+- `BAAI/CCI3-HQ`:用于中文场景
+- `codeparrot/github-code-clean`:用于代码场景
+- `HuggingFaceH4/ultrachat_200k`:用于对话数据
+- `madao33/new-title-chinese`:用于中文场景
+- `mbpp`:用于代码场景
+- `openbmb/Ultra-FineWeb`
+
+### 自定义数据集
+**建议用户还是尽量不使用 padding 的数据**。虽然对于 padding 过的数据我们有做特殊处理,但是目前验证的比较少。
+可通过以下方式指定:
+- 用法一:向 `dataset` 参数传入本地 JSON 文件路径
+- 用法二:参照[示例代码](../auto_round/calib_dataset.py)注册数据集,然后使用新的数据集初始化 AutoRound 对象。示例: `autoround=Autoround(dataset="NeelNanda/pile-10k:train", ...)`
+- 用法三:向 `dataset` 参数传入字符串列表或者 input_ids 列表
+
+ ~~~python
+ def customized_data():
+ # 注意!!!AutoRound 会舍弃长度小于 args.seqlen 的数据,并将超过该长度的数据截断至 args.seqlen 长度
+ data = ["AutoRound 是面向大语言模型的先进量化算法" * 240]
+ return data
+
+
+ def customized_data_with_tokenizer(tokenizer, seqlen=2048):
+ # 注意!!!AutoRound 会舍弃长度小于 args.seqlen 的数据
+ data = ["AutoRound 是面向大语言模型的先进量化算法" * 240]
+ tokens = []
+ for d in data:
+ token = tokenizer(d, truncation=True, max_length=seqlen, return_tensors="pt").data
+ tokens.append(token)
+ return tokens
+ ~~~
+
+### 数据集操作
+
+**数据集组合**:可使用 `--dataset` 参数组合不同数据集并设置其他的参数。示例代码 `--dataset ./tmp.json,NeelNanda/pile-10k:num=256,mbpp:num=128`。此参数同时支持本地标定文件和 Hugging Face 数据集,同时还可用 `split = split1+split2` 指定某个数据集的多个拆分子集。
+
+**样本拼接**:可使用 `--dataset NeelNanda/pile-10k:concat=True` 拼接标定样本。在该模式下,会先将所有样本拼接成完整文本,再按 seqlen 长度切分出来。
+
+**启用对话模板**:可使用 `--dataset NeelNanda/pile-10k:apply_chat_template` 在分词前为标定数据应用对话模板,这在指令式模型的生成任务中比较常用。若需自定义系统提示词,可使用 `--dataset 'NeelNanda/pile-10k:apply_chat_template:system_prompt="你是一个乐于助人的智能助手。"'`
+
+注意:如果没有开启拼接选项,长度小于 args.seqlen 的样本会被舍弃。
+
+数据集之间请用英文逗号`,`分隔;单个数据集的参数请用英文冒号`:`分隔;同一参数的多个取值请用英文加号`+`连接。
+
+
+## 3 模型量化
+
+### 可选量化配置
+
+AutoRound 支持多种量化配置:
+- **W4A16**(bits:4, group_size:128, sym:True, act_bits:16) # 4位权重,分组大小为128,对称量化,16位激活,
+- **W8A16**(bits:8, group_size:128, sym:True, act_bits:16)
+- **W3A16**(bits:3, group_size:128, sym:True, act_bits:16)
+- **W2A16**(bits:2, group_size:128, sym:True, act_bits:16)
+- **GGUF:Q4_K_M**(支持 llamacpp 提供的所有 Q*_K、Q*_0、Q*_1 量化类型)
+- **混合bit**: (实验性功能)请使用 AutoScheme 接口或者使用 API 中的 `layer_config` 参数自己自定义
+- **NVFP4**(实验性功能)推荐导出为`llm_compressor`格式,参数:data_type=nvfp4, act_data_type=nvfp4, static_global_scale, group_size=16
+- **MXFP4**(研究性功能,暂无实际内核):标准 MXFP4 量化,参数:data_type=mxfp, act_data_type=mxfp, bits=4, act_bits=4, group_size=32
+- **MXFP4_RCEIL**(研究性功能,暂无实际内核):NVIDIA变体,参数:data_type=mxfp, act_data_type=mxfp_rceil, bits=4, act_bits=4, group_size=32
+- **MXFP8**(研究性功能,暂无实际内核),参数:data_type=mxfp, act_data_type=mxfp_rceil, group_size=32
+- **FPW8A16**(研究性功能,暂无实际内核),参数:data_type=fp8, group_size=0 -> 每张量
+- **FP8_STATIC**(研究性功能,暂无实际内核),参数:data_type:fp8, act_data_type:fp8, group_size=-1(每通道),act_group_size=0(每张量)
+
+你也可以根据需求修改`group_size`(分组大小)、`bits`(精度)、`sym`(是否对称量化)等其他配置,但某些目前可能尚无对应的高性能计算内核支持。
+
+
+### 支持的导出格式
+
+执行 `auto_round list format` 可查看所有支持的导出格式及其对应的量化方案。
+
+**AutoRound 原生格式**:适用于 CPU、英特尔 GPU、CUDA、HPU 等设备,支持2位宽及混合精度推理,**兼容 [2、3、4、8] bits**。使用时需设置 `--format auto_round`。
+
+**GGUF 格式**:实验性功能,适用于 CPU 设备,是社区主流格式之一,支持 `q*_k`、`q*_0`、`q*_1` 系列的量化。需设置 `--format gguf:q4_k_m`、`--format gguf:q2_k_s`等具体格式。
+
+**AutoGPTQ 格式**:适用于 CUDA 设备的对称量化,在社区中广泛应用,**兼容 [2、3、4、8] bits **(但其**非对称推理核存在问题**,可能导致模型的精度大幅下降,尤其是在 2-bit 量化和小模型的场景;近期 Transformers 框架中 3-bits 量化也存在类似问题)。配置时需设置 `--format auto_gptq`。
+
+**AutoAWQ 格式**:适用于 CUDA 设备的 4 位非对称量化,在社区中也广泛应用。**仅支持 4-bit 量化**。需设置 `--format auto_awq`。
+
+**LLM-Compressor 格式**:**支持 NVFP4、MXFP4(kernel 开发中)、MXFP8** 等。需设置 `--format llm_compressor`。
+
+#### 格式与方案支持对照表
+
+> 灰色背景的 schemes 表示它没有专门优化的内核,或只有效率极低的参考内核。
+
+| 格式 | 支持的量化方案 |
+|:-------------- |:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **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` |
+| **gguf** | GGUF:Q4_K_M、GGUF: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** | `所有方案(仅用于研究场景)` |
+
+### 硬件兼容性
+
+量化和推理均支持 CPU、英特尔 GPU、HPU 和 CUDA。
+
+### 环境参数配置
+
+为优化运行性能,量化前建议配置 AutoRound 的环境变量。关于日志级别、ModelScope 集成、工作区设置等可用的环境变量等更多细节,可参考[环境变量指南](./environments.md)。
+
+### 命令行用法
+
+
+- **AutoRound 默认超参**:
+
+ 该方案很好地兼顾了精度和训练耗时,**推荐在绝大多数场景下使用**。
+
+ ```bash
+ auto-round --model Qwen/Qwen3-0.6B --scheme "W4A16" --format "auto_gptq,auto_awq,auto_round"
+ ```
+
+- **AutoRoundBest 高精度超参**:
+
+ 绝大多数场景下,该方案能实现最好的模型精度,缺点是训练耗时是基础方案的 4~5 倍;**特别适合 2-bit 量化**,若算力充足,可作为首选。跟默认参数的区别是调整了样本数量,从128提高了512.另外迭代次数从200次提高了1000.
+
+ ```bash
+ auto-round-best --model Qwen/Qwen3-0.6B --scheme "W4A16" --format "auto_gptq,auto_awq,auto_round"
+ ```
+
+- **AutoRoundLight 轻量级超参**:
+
+ 该方案训练速度最快(比基础方案快 2~3 倍),但小模型和 2-bit 量化下可能导致模型精度显著下降。所以**推荐在 4-bit 量化或参数量大于 3B 的模型的场景下使用**。
+
+ ```bash
+ auto-round-light --model Qwen/Qwen3-0.6B --scheme "W4A16" --format "auto_gptq,auto_awq,auto_round"
+ ```
+
+### API 使用方法
+#### AutoRound API 基础用法
+该方案兼顾精度和训练耗时,**绝大多数场景下使用,2bit 等量化损失很大的场景尽量不要使用**。
+
+```python
+from auto_round import AutoRound
+
+model_name_or_path = "Qwen/Qwen3-0.6B"
+ar = AutoRound(
+ model_name_or_path,
+ scheme="W4A16",
+ # 可选开启torch编译加速:enable_torch_compile=True,
+)
+
+output_dir = "./tmp_autoround"
+# 可指定导出格式,支持auto_round(默认)、auto_gptq、auto_awq,多格式用英文逗号分隔
+ar.quantize_and_save(output_dir, format="auto_gptq,auto_awq,auto_round")
+```
+
+#### 混合精度量化
+自 0.8 版本起,AutoRound 提供了 AutoScheme 功能,可自动生成混合精度方案,详情请参阅 [Auto Scheme自动方案](#autoscheme)章节。
+
+Auto-GPTQ 和 Auto-AWQ 仅支持有限的混合精度。如果您不熟悉具体细节,**建议导出 AutoRound 格式**。
+
+由于 vLLM 和 SGLang 框架会对 MoE 层、QKV 层进行融合以加速推理,所以**不建议给这些层设置不同的 bit **。
+
+```python
+from auto_round import AutoRound
+
+model_name_or_path = "Qwen/Qwen3-0.6B"
+
+# 层配置:支持完整层名匹配和模糊(部分)匹配
+layer_config = {
+ "model.decoder.layers.6.self_attn.out_proj": {"bits": 8, "group_size": 32},
+ "model.decoder.layers.*k_proj": {"bits": 2, "group_size": 32},
+}
+ar = AutoRound(
+ model_name_or_path,
+ layer_config=layer_config,
+)
+
+output_dir = "./tmp_autoround"
+ar.quantize_and_save(output_dir, format="auto_round")
+```
+
+#### AutoRoundBest 高精度配置用法
+绝大多数场景下,该方案能实现最好的模型精度,缺点是训练耗时是基础方案的 4~5 倍;**特别适合 2-bit 量化**,若算力充足,可作为首选。
+
+```python
+from auto_round import AutoRound
+
+model_name_or_path = "Qwen/Qwen3-0.6B"
+ar = AutoRound(model=model_name_or_path, scheme="W4A16", nsamples=512, iters=1000, low_gpu_mem_usage=True)
+
+output_dir = "./tmp_autoround"
+ar.quantize_and_save(output_dir, format="auto_round")
+```
+
+#### AutoRoundLight 高速度配置用法
+该方案训练速度最快(比基础方案快 2~3 倍),但小模型和 2-bit 量化下可能导致模型精度显著下降。所以**推荐在 4-bit 量化或参数量大于 3B 的模型的场景下使用**。
+
+```python
+from auto_round import AutoRound
+
+model_name_or_path = "Qwen/Qwen3-0.6B"
+
+ar = AutoRound(
+ model=model_name_or_path,
+ scheme="W4A16",
+ iters=50,
+ lr=5e-3,
+)
+
+output_dir = "./tmp_autoround"
+ar.quantize_and_save(output_dir, format="auto_round")
+```
+
+#### 超参方案推荐
+综上所述,**4-bits(W4A16)推荐使用基础方案(auto-round),2-bits(W2A16)推荐使用高精度方案(auto-round-best)**;你也可根据实际需求和算力,灵活调整相关的配置。
+
+<details>
+ <summary>各配置方案详细参数</summary>
+
+| 配置方案 | 批次大小 | 迭代次数 | 序列长度 | 标定样本数 | 学习率 |
+|---------|----------|----------|----------|-------|--------|
+| 基础版 | 8 | 200 | 2048 | 128 | 自动适配 |
+| 高精度版 | 8 | 1000 | 2048 | 512 | 自动适配 |
+| 高速版 | 8 | 50 | 2048 | 128 | 5e-3 |
+
+</details>
+
+W4G128 在 13 个任务上的平均精度与耗时
+(测试环境:NVIDIA A100 80G,PyTorch 2.6.0,启用 enable_torch_compile)
+
+| 模型 | Qwen2.5-0.5B-Instruct | Falcon3-3B | Qwen2.5-7B-Instruct | Meta-Llama-3.1-8B-Instruct | Falcon3-10B | Qwen2.5-72B-Instruct |
+|-----------------------|------------------------|------------|----------------------|-----------------------|-------------|-----------------------|
+| 16位原精度 | 0.4192 | 0.5203 | 0.6470 | 0.6212 | 0.6151 | 0.7229 |
+| 高精度方案(Best) | **0.4137**(7分钟) | **0.5142**(23分钟) | 0.6426(58分钟) | **0.6116**(65分钟) | **0.6092**(81分钟) | 0.7242(575分钟) |
+| 基础方案(Default) | 0.4129(2分钟) | 0.5133(6分钟) | **0.6441**(13分钟) | 0.6106(13分钟) | 0.6080(18分钟) | **0.7252**(118分钟) |
+| 高速方案(Light) | 0.4052(2分钟) | 0.5108(3分钟) | 0.6453(5分钟) | 0.6104(6分钟) | 0.6063(6分钟) | 0.7243(37分钟) |
+
+<details>
+ <summary>W2G64测试结果</summary>
+W2G64 在 13 个任务上的平均精度与耗时
+(测试环境:NVIDIA A100 80G,PyTorch 2.6.0,启用 enable_torch_compile)
+为缓解模型精度显著下降,建议对 head、tail 以及非 expert 模块使用更高精度的量化配置。
+
+| 模型 | Qwen2.5-0.5B-Instruct | Falcon3-3B | Qwen2.5-7B-Instruct | Falcon3-10B | Qwen2.5-72B-Instruct |
+|-----------------------|------------------------|------------|----------------------|-------------|-----------------------|
+| 16位原精度 | 0.4192 | 0.5203 | 0.6470 | 0.6151 | 0.7229 |
+| 高精度方案(Best) | **0.2989**(6分钟) | **0.4267**(24分钟) | **0.5343**(56分钟) | **0.5207**(79分钟) | **0.6715**(564分钟) |
+| 基础方案(Default) | 0.2878(2分钟) | 0.4219(6分钟) | 0.5209(13分钟) | 0.5133(18分钟) | 0.6713(122分钟) |
+| 高速方案(Light) | 0.2760(2分钟) | 0.4063(3分钟) | 0.4764(5分钟) | 0.4810(7分钟) | 0.6581(38分钟) |
+
+</details>
+
+### AutoScheme 自动混合精度量化方案
+AutoScheme 采用自动化算法,可生成 **自适应的混合精度与数据类型** 的量化方案(mixed bits/data type quantization recipes)。相关测试结果请参考[《AutoScheme精度报告》](./auto_scheme_acc.md)。
+
+**注意**:混合数据类型方案在训练阶段可用,但当前版本还不支持导出至实际模型。
+
+#### 命令行用法
+如需启动训练建议设置 `iters=200`
+~~~bash
+auto_round \
+ --model_name $model_name \
+ --avg_bits 6 \
+ --options "mxfp4,mxfp8" \
+ --ignore_scale_zp_bits \
+ --iters 0 \
+ --format fake
+~~~
+
+#### API 用法
+~~~python
+avg_bits= 3.0
+scheme = AutoScheme(avg_bits=avg_bits, options=("W2A16G64", "W4A16","W8A16"))
+ar = AutoRound(model=model_name, scheme=scheme, iters=0, nsamples=1)
+ar.quantize_and_save()
+~~~
+
+
+#### AutoScheme 超参数说明
+`avg_bits(float)`:模型整体的目标平均 bits;计算时仅计入待量化的层。
+
+`options(Union[str, list[Union[QuantizationScheme, str]]])`:候选量化配置集合。支持以下表示形式:单个用逗号分隔的字符串(例如 `"W4A16,W2A16"`​)、字符串列表(例如 `["W4A16", "W2A16"]`​)和 `QuantizationScheme` 。
+
+`ignore_scale_zp_bits(bool)`:仅支持 API 调用场景。用于决定在计算平均 bit 时,是否忽略 scale 与 zero-point 的位数(默认 `False`)。
+
+`device_map (Optional[str,dict,torch.device])`:仅支持 API 场景。由于 AutoScheme 会比标准 AutoRound 会占用更多显存,故可通过此参数为其指定不同的设备映射。
+
+`shared_layers (Optional[Iterable[Iterable[str]]])`:仅支持 API 场景,用于定义多个层的分组,这些层将共享相同的量化配置。
+
+`batch_size (Optional[int])`:设为 `1` 可以降低显存占用,但会增加训练时间。
+
+`low_gpu_mem_usage(bool=True)`:开启后可减少 GPU 显存占用,但会增加训练时间。默认开启。
+
+为加速推理,在部分框架中,会对特定层(如QKV、MoE)进行融合。这些融合层必须是相同的数据类型和量化配置。`shared_layers` 参数可以简化该配置,**同时支持正则表达式匹配和完整层名匹配**。注意**正则匹配按块匹配规则生效**。
+
+示例代码如下:
+```python
+from auto_round import AutoRound, AutoScheme
+
+shared_layers = [
+ ["*.self_attn.k_proj", "v_proj", "q_proj", "out_proj"],
+ ("model.decoder.layers.6.fc1", "model.decoder.layers.6.fc2"),
+ ("fc1", "fc2"),
+]
+target_bits = 5.0
+model_name = "Qwen/Qwen3-0.6B"
+scheme = AutoScheme(avg_bits=target_bits, options=("W4A16", "MXFP8"), shared_layers=shared_layers)
+ar = AutoRound(model=model_name, scheme=scheme, iters=0, nsamples=1)
+model, layer_config = ar.quantize()
+```
+
+此外,若需为特定的层固定量化方案,可使用 AutoRound API 中的`layer_config`参数,用法示例如下:
+```python
+from auto_round import AutoRound, AutoScheme
+
+model_name = "Qwen/Qwen3-8B"
+avg_bits = 3.0
+scheme = AutoScheme(avg_bits=avg_bits, options=("GGUF:Q2_K_S", "GGUF:Q4_K_S"), ignore_scale_zp_bits=True)
+layer_config = {"lm_head": "GGUF:Q6_K"}
+
+ar = AutoRound(model=model_name, scheme=scheme, layer_config=layer_config, iters=0)
+ar.quantize_and_save()
+```
+
+#### AutoScheme 耗时与显存成本
+测试基于 Nvidia A100 80G、PyTorch 2.8。
+
+后续我们会进一步优化显存占用。当前该方案的显存占用约为模型以 BF16 精度加载时的 1.1~1.5 倍。
+
+| 模型 | 量化方案 | 显存占用 | 耗时 |
+|---------------| ----------------------- | -------- | --------------------- |
+| Qwen3-8B | W2A16 / W4A16 / W8A16 | 14G | 60秒 × 可选方案数量 |
+| Qwen3-8B | MXFP4 / MXFP8 | 18G | 60秒 × 可选方案数量 |
+| Qwen3-8B | GGUF系列 | 14G | 80秒 × 可选方案数量 |
+| Qwen3-32B | W2A16 / W4A16 / W8A16 | 29G | 180秒 × 可选方案数量 |
+| Qwen3-32B | MXFP4 / MXFP8 | 29G | 180秒 × 可选方案数量 |
+| Qwen3-32B | GGUF系列 | 18G | 300秒 × 可选方案数量 |
+| Llama-3.3-70B | W2A16 / W4A16 / W8A16 | 32G | 420秒 × 可选方案数量 |
+
+<details>
+<summary>关闭 low_gpu_mem_usage 后的结果</summary>
+
+| 模型 | 量化方案 | 显存占用(开启torch compile) | 耗时(开启torch compile) | 显存占用(关闭torch compile) | 耗时(关闭torch compile) |
+| ------------- | --------------------- | ----------------------------- | ------------------------- | ------------------------------ | ------------------------- |
+| Qwen3-8B | W2A16/W4A16/W8A16 | 34G | 30秒 × 可选方案数量 | 61G | 40秒 × 可选方案数量 |
+| Qwen3-8B | MXFP4/MXFP8 | 36G | 60秒 × 可选方案数量 | 54G | 120秒 × 可选方案数量 |
+| Qwen3-8B | GGUF系列 | 54G | 30秒 × 可选方案数量 | 50G | 23秒 × 可选方案数量 |
+| Qwen3-32B | W2A16/W4A16/W8A16 | 240G显存溢出 | —— | 240G显存溢出 | —— |
+| Qwen3-32B | MXFP4/MXFP8 | 160G | 200秒 × 可选方案数量 | 200G | 240秒 × 可选方案数量 |
+| Qwen3-32B | GGUF系列 | 210G | 80秒 × 可选方案数量 | 200G | 60秒 × 可选方案数量 |
+
+</details>
+
+#### 局限性
+AutoScheme 目前还**不支持对嵌入层(Embedding layer)进行自动量化**。该层将直接采用候选方案中精度最高的配置。
+
+## OPT-RTN 模式
+AutoRound 还提供优化版 RTN(Round-To-Nearest,就近舍入)模式,无需标定数据即可实现快速基线量化。**启用方式为 `iters=0`**。同时为获得更好的效果,推荐搭配 `group_size=32` 。RTN 与 OPT RTN 模式的精度对比详见[《精度对比报告》](./opt_rtn.md)。
+
+对于 GGUF 格式,我们参考 llamacpp 的思路,优化了 RTN 算法。若需使用原始(非优化)RTN 算法,开启 `--disable_opt_rtn` 即可。
+```python
+from auto_round import AutoRound
+
+model_name_or_path = "Qwen/Qwen3-0.6B"
+ar = AutoRound(
+ model=model_name_or_path,
+ scheme="W4A16",
+ iters=0,
+)
+
+output_dir = "./tmp_autoround"
+ar.quantize_and_save(output_dir, format="auto_round")
+```
+
+### GGUF 格式量化
+实验性功能。该格式适用 CPU 设备,在社区应用广泛。
+
+除 3-bits 外的各精度均建议使用优化版 RTN 模式(开启 `--iters 0` )。
+
+```python
+from auto_round import AutoRound
+
+model_name_or_path = "Qwen/Qwen3-0.6B"
+ar = AutoRound(
+ model=model_name_or_path,
+)
+output_dir = "./tmp_autoround"
+ar.quantize_and_save(output_dir, format="gguf:q4_k_m") # gguf:q*_k_s、gguf:q*_k_0、gguf:q*_k_1
+```
+
+### 量化成本
+该数据有点过时,目前量化显存会比下面表格报告的要少点。
+测试基于 Nvidia A100 80G、PyTorch 2.6.0.dev20241029+cu124。注意评测未计入数据加载和打包耗时。**建议在 PyTorch 2.6 及以上版本中开启 torch.compile 以加速**。
+
+若要降低 GPU 显存占用,除开启`low_gpu_mem_usage`外,还可以设置`gradient_accumulate_steps=8`和`batch_size=1`,但这会增加训练耗时。
+
+所有测试均基于 W4G128 量化方案。测试中使用的 3B 、14B 参数的模型为 Qwen 2.5系列,8X7B 的模型为 Mixtral,其余模型为 Llama-3.1 系列。
+
+
+| Torch version/Config W4G128 | 3B | 8B | 14B | 70B | 8X7B |
+|----------------------------------------------------------------------------------|---------------|----------------|----------------|-----------------|----------------|
+| 2.6 + 开启 torch compile | 7min<br/>10GB | 12min<br/>18GB | 23min<br/>22GB | 120min<br/>42GB | 28min<br/>46GB |
+| 2.6 + 开启 torch compile + 开启低显存模式<br/>low_gpu_mem_usage=True | 12min<br/>6GB | 19min<br/>10GB | 33min<br/>11GB | 140min<br/>25GB | 38min<br/>36GB |
+| 2.6 + 开启 torch compile + 低显存模式 + 梯度累积8步、批次1<br/>gradient_accumulate_steps=8,bs=1 | 15min<br/>3GB | 25min<br/>6GB | 45min<br/>7GB | 187min<br/>19GB | 75min<br/>36GB |
+| 2.5 + 关闭 torch compile | 8min<br/>10GB | 16min<br/>20GB | 30min<br/>25GB | 140min<br/>49GB | 50min<br/>49GB |
+
+
+
+### 设备及多卡量化设置
+**AutoRound API 的 `device_map` 参数可指定训练设备(注意不是用 Transformers.from_pretrained 中的 `device_map` 参数)**。
+
+AutoRound 采用 block(分块)逐块训练的方式处理模型,尽管单个 block 的规模远小于完整模型,但在训练过程中仍需要占用大量 GPU 显存(通常约为 block 大小的 10 倍)。在处理超大模型时,这可能会导致显存不足(OOM)错误。
+
+也可通过调整相关参数降低显存占用,详情请参阅下文的[超参数调整](#超参数调整)章节,。
+
+若调整参数后依旧无法解决显存问题,最简单的解决方法是在 `device_map` 中增加更多设备,示例如下:
+
+Python API示例:
+~~~python
+from auto_round import AutoRound
+
+model_name_or_path = "Qwen/Qwen3-0.6B"
+ar = AutoRound(
+ model=model_name_or_path,
+ device_map="0,1,2,3" # 指定使用0、1、2、3号GPU
+)
+~~~
+
+命令行示例:
+~~~bash
+CUDA_VISIBLE_DEVICES=0,1,2,3 auto-round --model "Qwen/Qwen3-0.6B" --scheme "W4A16" --device_map "auto"
+~~~
+
+
+通常有两种情况需要启用多 GPU 训练:一是主要针对 lm-head 量化的标定阶段,二是参数量极大(如显存占用超 100GB)的模型。
+
+#### lm_head 量化中开启多 GPU 标定
+量化 lm-head 时,AutoRound 需要缓存其输入数据以进行高效的标定,这要求**整个模型驻留在 GPU 显存中** ;若 GPU 显存不足,部分层会退回至 Pure RTN 模式。
+
+<a id="llm-head-multi-gpu"></a>
+#### 手动配置设备映射
+<details>
+<summary>自定义设备映射(device_map)</summary>
+若 `device_map=auto` 未能正确分配,还可以通过 AutoRound API 的 `device_map` ,将同一 bolck 内的不同层映射到不同设备。这里我们提供一个参考示例:如何在 5 张 80GB GPU 上量化 DeepSeekV3-BF16(1.4T)模型。
+
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model_name = "opensourcerelease/DeepSeek-R1-bf16"
+
+# 加载分词器和模型
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+model = AutoModelForCausalLM.from_pretrained(model_name, trust_remote_code=True, torch_dtype="auto")
+
+block = model.model.layers
+device_map = {}
+
+for n, m in block.named_modules():
+ if type(m) == torch.nn.Linear:
+ if "experts" in n and ("shared_experts" not in n) and int(n.split(".")[-2]) < 63:
+ device = "cuda:1"
+ elif (
+ "experts" in n
+ and ("shared_experts" not in n)
+ and int(n.split(".")[-2]) >= 63
+ and int(n.split(".")[-2]) < 128
+ ):
+ device = "cuda:2"
+ elif (
+ "experts" in n
+ and ("shared_experts" not in n)
+ and int(n.split(".")[-2]) >= 128
+ and int(n.split(".")[-2]) < 192
+ ):
+ device = "cuda:3"
+ elif "experts" in n and ("shared_experts" not in n) and int(n.split(".")[-2]) >= 192:
+ device = "cuda:4"
+ else:
+ device = "cuda:0"
+ n = n[2:]
+
+ device_map.update({n: device})
+
+from auto_round import AutoRound
+
+autoround = AutoRound(
+ model=model,
+ tokenizer=tokenizer,
+ device_map=device_map,
+ nsamples=512,
+ batch_size=4,
+ low_gpu_mem_usage=True,
+ seqlen=2048,
+)
+autoround.quantize()
+autoround.save_quantized(format="auto_awq", output_dir="tmp_autoround")
+```
+</details>
+
+### 超参数调整
+#### 降低 GPU 显存占用
+以下方法可单独或组合使用,其中部分方式会增加训练耗时或带来轻微的精度损失:
+- 将 `enable_torch_compile` 设为 True(开启 PyTorch 编译加速,不损失精度)
+- 开启 `low_gpu_mem_usage`(低显存模式,**增加训练耗时**)
+- 设置 `--bs 1 --gradient_accumulate_steps 8`(批次1+梯度累积8步,**增加训练耗时**)
+- 将 `bs` 降至 4(**可能会有轻微的精度损失**)
+- 将 `seqlen` 降至 512(**可能会有精度损失**)
+
+#### 降低 CPU 内存占用
+- 开启 `low_cpu_mem_usage`(实验性功能):仅支持**导出指定一种格式**。每个 block 量化封装完成后会立即保存,从而降低峰值内存占用。
+- 触发立即封装:使用命令行或 `quantize_and_save` API 时,只要指定**单一导出格式**,就会自动触发即时打包,无需额外配置。
+
+#### 提升训练速度
+以下方法可单独或组合使用,其中部分方式可能带来精度损失:
+- 将 `enable_torch_compile` 设为 True(无精度损失)
+- 使用 `auto-round-light` (小模型/ 2-bits 场景可能有明显精度损失)
+- 将 `seqlen` 降至 512(**部分场景可能出现大幅精度损失**)
+- 将 `bs` 降至 4(**仅有轻微精度损失**)
+
+#### 开启 lm-head 层量化
+该配置目前**仅支持 AutoRound 原生格式的推理**,命令行启用方式如下:
+```bash
+auto-round --model_name Qwen/Qwen3-0.6B --scheme "W4A16" --quant_lm_head --format "auto_round"
+```
+
+#### 使用 AdamW 优化器
+添加 `--adam` 参数即可启用;**注意**:在我们的多项测试场景中,AdamW 优化器的效果均不如符号梯度下降(sign gradient descent)。
+
+
+
+## 4 推理部署
+AutoRound 支持十余种推理后端,并会根据已安装的库自动选择最优后端;如果检测到系统中存在更优后端但缺少相关依赖,也会主动提示用户安装。
+
+​**请勿在推理过程中手动将量化后的模型迁移到其他设备**​(例如执行 `model.to('cpu')`),否则可能导致意外错误。
+
+### CPU
+支持 2、4、8 bits 模型,其中 **4-bits 推理推荐搭配 intel-extension-for-pytorch(IPEX)** 使用,示例:
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model_name = "OPEA/Qwen2.5-1.5B-Instruct-int4-sym-inc"
+model = AutoModelForCausalLM.from_pretrained(model_name, device_map="cpu", 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, do_sample=False)[0]))
+```
+
+### 英特尔 GPU
+**仅支持 4-bits 模型**,推荐搭配 **IPEX** 使用,示例:
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model_name = "OPEA/Qwen2.5-1.5B-Instruct-int4-sym-inc"
+model = AutoModelForCausalLM.from_pretrained(model_name, device_map="xpu", 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, do_sample=False)[0]))
+```
+
+### CUDA
+支持 2、3、4、8 bits 量化模型,**4-bits/8-bits 推理推荐使用 GPTQModel 后端**,使用示例:
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model_name = "OPEA/Qwen2.5-1.5B-Instruct-int4-sym-inc"
+model = AutoModelForCausalLM.from_pretrained(model_name, device_map="cuda", 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, do_sample=False)[0]))
+```
+
+### HPU
+推荐使用集成 Habana 软件栈的 Docker 镜像,详情请参阅[Habana官方指南](https://docs.habana.ai/en/latest/),使用示例:
+```python
+import habana_frameworks.torch.core as htcore
+import habana_frameworks.torch.hpu as hthpu
+from transformers import AutoModelForCausalLM, AutoTokenizer
+import torch
+
+model_name = "Intel/Qwen2-7B-int4-inc"
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+model = AutoModelForCausalLM.from_pretrained(model_name).to("hpu").to(torch.bfloat16)
+
+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, do_sample=False)[0]))
+```
+
+### 指定推理后端
+AutoRound 会根据兼容性为每个层自动选择推理后端,默认优先级大致为:Marlin > ExLLaMAV2 > Triton。最终的选择会受到 **group size、bit width、packing format、hardware device** 等多种因素的影响。
+
+默认选择的后端并非在所有设备上都是最优的,你可根据需求或硬件兼容性手动指定后端:
+- CPU/英特尔 GPU:推荐`ipex`
+- CUDA:可指定`marlin`/`exllamav2`/`triton`
+
+**注意**:手动指定后端的话,可能要安装相关依赖。
+
+指定后端的示例:
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer, AutoRoundConfig
+
+model_name = "OPEA/Qwen2.5-1.5B-Instruct-int4-sym-inc"
+quantization_config = AutoRoundConfig(backend="ipex")
+model = AutoModelForCausalLM.from_pretrained(
+ model_name, device_map="cpu", quantization_config=quantization_config, 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, do_sample=False)[0]))
+```
+
+#### 各推理后端的详细支持说明
+| 后端名称 | 支持设备 | 支持位宽 | 支持数据类型 | 优先级 | 打包格式 | 依赖库要求 |
+|-------------------------|----------------|----------------|--------------|--------|-----------------|--------------------------------|
+| ipex | cpu/xpu | 4 | BF16/FP16 | 5 | gptq_zp+-1/awq | intel-extension-for-pytorch |
+| marlin | cuda | 4、8 | BF16/FP16 | 6 | gptq/gptq_zp+-1 | gptqmodel |
+| exllamav2/<br/>gptqmodel:exllamav2 | cuda | 4 | BF16/FP16 | 5 | gptq | gptqmodel |
+| exllamav2/<br/>gptq:exllamav2 | cuda | 4 | FP16 | 5 | gptq_zp+-1 | auto-gptq |
+| gptq:cuda | cuda | 2、3、4、8 | FP16 | 1 | gptq_zp+-1 | auto-gptq |
+| triton | xpu/cuda | 2、4、8 | BF16/FP16 | 2 | gptq/gptq_zp+-1 | auto-round |
+| awq | cuda | 4 | FP16 | 5 | awq | auto-awq |
+| hpu | hpu | 4 | BF16 | 0 | gptq/gptq_zp+-1 | auto-round |
+| torch | xpu/cpu/cuda | 2、3、4、8 | BF16/FP16 | 0 | gptq/gptq_zp+-1 | auto-round |
+
+### 将 GPTQ 或 AWQ 模型转换为 AutoRound 格式
+为了提升兼容性(尤其是英特尔设备),大部分 GPTQ/AWQ 量化模型均可转换为 AutoRound 格式。**注意**:若模型再次存储,其量化配置可能会发生变更, 由 gptq/awq 量化变化成 auto-round 量化。
+
+转换并推理的示例:
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer, AutoRoundConfig
+
+model_name = "ybelkada/opt-125m-gptq-4bit"
+quantization_config = AutoRoundConfig()
+model = AutoModelForCausalLM.from_pretrained(
+ model_name, device_map="cpu", quantization_config=quantization_config, 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, do_sample=False)[0]))
+```
+
+
+
+## 5 效果评估
+
+AutoRound 借助 [lm-eval-harness](https://github.com/EleutherAI/lm-evaluation-harness) 来评估模型。如果没有指定评估任务(`--task`),会使用默认的任务集(十余个常用评测任务)。
+
+### 单 GPU 评估
+
+**HF 后端(默认):**
+```bash
+auto-round --model Qwen/Qwen3-0.6B --bits 4 --format "auto_round,auto_gptq" --tasks mmlu
+```
+
+**vLLM 后端:**
+```bash
+auto-round --model Qwen/Qwen3-0.6B --bits 4 --format "auto_round,auto_gptq" --tasks mmlu --eval_backend vllm
+```
+
+### 多 GPU 评估
+
+**HF 后端:**
+```bash
+auto-round --model="your_model_path" --eval --device_map 0,1 --tasks lambada_openai --eval_bs 16
+```
+
+**vLLM 后端(用法一:用 `--device_map` 参数)**
+```bash
+auto-round "your_model_path" --eval --device_map 0,1 --tasks lambada_openai --eval_backend vllm
+```
+
+**vLLM 后端(用法二:手动配置):**
+```bash
+CUDA_VISIBLE_DEVICES=0,1 auto-round "your_model_path" --eval --tasks lambada_openai --eval_backend vllm --vllm_args="tensor_parallel_size=2,gpu_memory_utilization=0.8"
+```
+
+### 注意事项
+
+- 对于原始模型和量化后的模型,都支持用 `--eval` 参数直接评估。
+- 为应对部分任务运行失败的情况,可使用 `--eval_task_by_task` 参数,按顺序执行评测任务(该参数目前只适用于 HF 后端)。
+- 若导出了多种格式,会自动选用列表中的**最后一种格式**的模型评估。
+- 对于 vLLM 后端,可通过 `--device 0,1,2` 指定 GPU 设备。该参数会自动设置 `CUDA_VISIBLE_DEVICES`,并根据设备数量配置 `tensor_parallel_size` 。此外,也支持通过环境变量和 `--vllm_args` 参数进行手动设置。
+
+
+## 6 已知问题
+量化过程存在的随机性可能会影响到部分模型的训练效果。若要保证实验结果可复现,可开启确定性算法( `enable_deterministic_algorithms=True` )。
+
+部分视觉语言模型(VLM)需要手动适配。
+
+暂不支持 Mamba 架构的模型。