Transformers documentation
概述
概述
量化（Quantization）以更少的比特数存储模型的权重，有时也包括其激活值，从而降低模型的内存需求。模型通常以 bf16 格式加载，每个参数占用 2 字节。一个 8B 模型在 bf16 下权重约占 16GB，8 位量化下约占 8GB，4 位量化下约占 4–5GB。比特数减少会带来一定的精度损失，且每种量化方法在内存、速度和精度之间做出的权衡各不相同。
Transformers 通过 from_pretrained() 集成了 20 多种量化方法，因此无论您选择哪种方法，都可以使用相同的加载代码。
使用量化模型的两种方法
如何使用量化取决于您的检查点是否已经过量化。
| 您已 | 你的操作 | 方法 |
|---|---|---|
| 全精度检查点 | 将量化配置传递给 from_pretrained，权重将在加载时进行量化。 | 在加载时量化模型 |
| 已经量化的检查点 | 调用 from_pretrained 时不传入量化配置。Transformers 会从检查点的 config.json 或您指定的 GGUF 文件中读取量化方法。 | 加载预量化检查点 |
某些方法（例如 AWQ、AutoRound、AQLM、compressed-tensors 和 GGUF）只能从检查点加载。您需要先使用该方法自身的库对模型进行量化，然后在 Transformers 中加载量化后的结果。
在加载时量化模型
创建该方法的配置类并将其传递给 quantization_config。下面的示例使用 bitsandbytes 以 4 位加载一个 8B 模型。
import torch
from transformers import AutoModelForCausalLM, BitsAndBytesConfig
quantization_config = BitsAndBytesConfig(
load_in_4bit=True,
bnb_4bit_compute_dtype=torch.bfloat16,
)
model = AutoModelForCausalLM.from_pretrained(
"meta-llama/Llama-3.1-8B-Instruct",
quantization_config=quantization_config,
device_map="auto",
)该组中的每个方法都有自己独立的配置类，例如 TorchAoConfig 或 BitsAndBytesConfig。其中大多数方法不需要校准数据集。GPTQ 是例外，因为它在模型加载过程中会使用数据集进行校准。
加载预量化检查点
预量化检查点会在其 config.json 中存储一个 quantization_config。当 from_pretrained 找到该配置时，会自动选择对应的量化器。
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained(
"TheBloke/zephyr-7B-alpha-AWQ",
device_map="auto",
)
print(model.config.quantization_config.quant_method)在加载检查点之前，请先安装该方法所依赖的库。每个方法页面都会列出需要安装的内容。若要更改加载选项（例如指定运行哪个内核后端），请传入一个相同类型的配置。其选项将与检查点中存储的选项合并。
GGUF 检查点
GGUF 检查点是一个包含权重、配置和分词器的单一文件，没有供 from_pretrained 读取的 config.json。请使用 gguf_file 来指定该文件。
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained(
"unsloth/Qwen3.5-4B-GGUF",
gguf_file="Qwen3.5-4B-Q4_K_M.gguf",
)大多数 GGUF 模型在加载时会被反量化为全精度，因此其内存占用与未量化模型相当。只有在安装了 kernels 包且使用 MPS 的情况下，Qwen3.5 和 Qwen3.5 MoE 的权重才会保持打包状态。详情请参阅 GGUF。
保存量化模型
调用 save_pretrained() 或 push_to_hub() 以保存量化权重及其 quantization_config。并非所有方法都能保存其量化权重。
选择一种方法
选择方法 针对常见目标推荐了起点，并从硬件、位宽、节省空间、微调以及 torch.compile 支持等方面对每种方法进行了对比。使用 量化选择器 可以检查模型在每种精度下是否适合您的硬件内存。
其他工具
这些工具在 Transformers 之外对模型进行量化。
- Optimum 针对特定硬件和运行时（如 Intel CPU 和 ONNX Runtime）对模型进行量化。
- Hub Spaces 会对模型进行量化，并将结果推送到您的账户：bitsandbytes、GGUF 和 MLX。
资源
- 使用 Hugging Face 学习量化基础 课程
- 深入量化 课程