vLLM 集成 BitsAndBytes：预量化读取与运行期 4bit 量化的完整实战指南

本文讲解 vLLM 如何通过官方 out-of-tree 插件 vllm-bnb-plugin 接入 BitsAndBytes（bitsandbytes）量化方案，覆盖插件安装、预量化 checkpoint 的自动识别加载、运行期（inflight）4bit 量化两种使用模式，以及 OpenAI 兼容服务器上的命令行配置方式，并深入结合 vLLM 源码说明量化方法自动探测与插件注册的底层原理。读完本文，你将能够在 vLLM 中直接加载 Hugging Face 上的 bnb 4bit 模型，或把未量化的原模型在加载时一键量化为 4bit 权重以降低显存占用。

BitsAndBytes 量化在 vLLM 中的定位与价值

BitsAndBytes 是一种以降低模型权重精度（典型为 4bit）来换取显存占用下降与推理效率提升的量化方法，其核心优势在于精度损失较小且无需使用输入数据对量化后的模型做校准（calibration）——这与 AutoAWQ、GPTQ 等需要基于校准数据集挑选量化参数的方法形成鲜明对比。在 vLLM 中接入 BitsAndBytes 后，模型加载与推理流程与普通模型保持一致，用户无需感知底层量化细节。

需要特别说明的是，BitsAndBytes 对 vLLM 的支持并非内置于 vLLM 主仓库，而是由独立的 out-of-tree 项目 vllm-bnb-plugin 以插件形式提供。从 vLLM 量化模块的源码可以看到，内置量化方法集合 QUANTIZATION_METHODS 中并不包含 bitsandbytes（参见 vllm/model_executor/layers/quantization/init.py），因此使用前必须先完成插件的安装，让插件在引擎初始化前完成量化配置类的注册。

安装 vllm-bnb-plugin 插件

在已安装 vLLM 的 Python 环境中，使用 uv 安装插件：

uv pip install vllm-bnb-plugin

安装完成后，vLLM 通过其插件系统自动发现并加载该插件。从插件机制上看，vLLM 的量化插件通过 Python 标准的 entry_points 机制注册（vLLM 会在每个进程启动时调用 vllm.plugins 模块中的加载函数），插件的注册函数内部调用 @register_quantization_config("bitsandbytes") 装饰器，将自定义量化配置类挂入 vLLM 的量化注册表（详见 docs/design/plugin_system.md 与 docs/features/quantization/README.md 中关于 Out-of-Tree Quantization Plugins 的说明）。注册之后，bitsandbytes 会被追加到 QUANTIZATION_METHODS 列表，随后才能通过本文介绍的各种入口正常使用。

两种使用模式概览

vLLM 读取模型的 config 文件，同时支持两种 BitsAndBytes 接入路径：

使用模式	适用场景	是否需要显式指定 quantization 参数
读取预量化 checkpoint（Pre-quantized Checkpoint）	模型仓库本身已存放 bnb 4bit 量化权重	不需要，vLLM 依据 config.json 自动推断
运行期量化（Inflight Quantization，4bit）	从原始未量化权重在加载时动态量化	需要，显式传 quantization="bitsandbytes"

关于运行期量化的一句话澄清：这里的 “inflight” 指模型加载过程中由 vLLM/bitsandbytes 现场完成从原始权重到 4bit 权重的转换，而非训练或微调阶段的量化感知。

在 Hugging Face 上可以检索到大量 bitsandbytes 量化模型，这类模型仓库通常会在 config.json 中携带一个 quantization_config 字段，其中记录了量化方法等元信息——这正是 vLLM 实现“免参数自动识别”的依据。

自动识别原理：vLLM 如何推断量化方法

vLLM 对量化方法的判定集中在模型配置校验阶段。在 vllm/config/model.py 的 _verify_quantization() 方法中，vLLM 会执行如下逻辑：

1. 读取 Hugging Face 模型 config 中的 quantization_config 字典，取出其中的 quant_method 字段作为候选量化方法；
2. 遍历注册表中的量化方法，调用各方法的 override_quantization_method() 探测 checkpoint 实际所属的量化格式（GPTQ、AWQ 等格式存在多别名场景，需要按优先级探测）；
3. 若用户未通过 quantization 参数显式指定方法，则采用从 checkpoint 推断出的方法；
4. 若用户显式指定的方法与 checkpoint 中的方法不一致，则抛出 ValueError 报错提示不匹配；
5. 最终方法若未出现在注册表 QUANTIZATION_METHODS 中，同样会抛出 “Unknown quantization method” 错误。

这段逻辑印证了两个实践要点：其一，加载预量化 checkpoint 时无需也不应再手动指定量化参数（指定错误反而会触发校验失败）；其二，bitsandbytes 不在内置方法列表中，因此必须先安装 vllm-bnb-plugin 完成注册，否则在校验阶段就会因 “Unknown quantization method” 而终止。

模式一：读取预量化 checkpoint（自动识别）

对于已量化好的 checkpoint，vLLM 会从模型 config 文件中自动推断量化方法，无需显式指定 quantization 参数。下面以社区常用的预量化模型 unsloth/tinyllama-bnb-4bit 为例：

from vllm import LLM
import torch

# unsloth/tinyllama-bnb-4bit 是一个预量化 checkpoint
model_id = "unsloth/tinyllama-bnb-4bit"
llm = LLM(
    model=model_id,
    dtype=torch.bfloat16,
    trust_remote_code=True,
)

参数说明：

• model：Hugging Face 模型 ID 或本地模型目录路径；
• dtype=torch.bfloat16：指定权重与激活的数据类型（LLM 类的说明中同时支持 float32、float16、bfloat16，参见 vllm/entrypoints/llm.py），对 bnb 量化权重推荐使用 bfloat16 或 float16；
• trust_remote_code=True：允许执行模型仓库中自定义的 Python 建模代码，这类社区量化模型通常依赖自定义 modeling 实现，需要开启。

模式二：运行期量化，把原模型加载为 4bit

若你手中的模型是未量化原始权重（如 huggyllama/llama-7b），希望在加载过程中由 vLLM 配合 bitsandbytes 现场完成 4bit 量化，则必须显式指定 quantization 参数：

from vllm import LLM
import torch

model_id = "huggyllama/llama-7b"
llm = LLM(
    model=model_id,
    dtype=torch.bfloat16,
    trust_remote_code=True,
    quantization="bitsandbytes",
)

当 quantization 被显式赋值时，它会覆盖 checkpoint 中携带的（或缺失的）量化配置——这正是运行期量化的入口。结合前文提到的 _verify_quantization() 逻辑：若该原始模型 config 中没有 quantization_config 字段，用户指定的 bitsandbytes 将直接生效；而校验阶段也依赖插件注册表能解析出名为 bitsandbytes 的量化配置类，因此插件未安装时会在此处报错。

从量化机制上看，运行期量化省去了离线校准环节，权重在加载时被转换为低比特表示，从而在保持较高精度的同时显著削减模型驻留显存，让更大的模型或更大的 KV Cache 得以在既定 GPU 上运行。

OpenAI 兼容服务器：命令行方式启用

在启动 vLLM 的 OpenAI 兼容 API 服务时，向模型参数（model arguments）追加如下参数即可启用 4bit 运行期量化：

--quantization bitsandbytes

一个完整的启动示例（组合常用参数）形如：

vllm serve huggyllama/llama-7b \
    --quantization bitsandbytes \
    --dtype bfloat16 \
    --trust-remote-code \
    --gpu-memory-utilization 0.9

--quantization bitsandbytes 与 Python 侧 LLM(quantization="bitsandbytes") 一一对应，均作用于模型权重加载阶段的量化处理；--gpu-memory-utilization 用于控制 GPU 显存中分配给模型权重、激活与 KV Cache 的占用比例（参见 vllm/entrypoints/llm.py 的相关说明）。同样地，若要加载的是预量化 checkpoint，则省略 --quantization 参数，交由服务自动识别即可。

硬件支持范围

依据 docs/features/quantization/README.md 中给出的硬件兼容矩阵，bitsandbytes 实现支持的硬件范围如下：

实现	Volta	Turing	Ampere	Ada	Hopper	AMD GPU	Intel GPU	x86 CPU	Arm CPU
bitsandbytes	✅	✅	✅	✅	✅	❌	❌	❌	❌

• Volta 对应 SM 7.0，Turing 对应 SM 7.5，Ampere 对应 SM 8.0/8.6，Ada 对应 SM 8.9，Hopper 对应 SM 9.0；
• ✅ 表示该方法在该硬件上受支持，❌ 表示不支持。

可以看到，BitsAndBytes 方案覆盖了 NVIDIA 从 Volta 到 Hopper 的主流计算架构，覆盖范围比 FP8（W8A8）类方案（仅 Ada/Hopper 起步）更广，特别适合在较老一代的 NVIDIA 显卡上以低比特方式运行大模型；但它不支持 AMD GPU、Intel GPU 及 CPU 平台。需要说明的是，该兼容性表格会随 vLLM 的版本演进而变化，最准确的硬件支持状态请以当前仓库 vllm/model_executor/layers/quantization 目录中的实现与上游 bitsandbytes 的支持情况为准。

从源码理解扩展机制：注册一个自定义量化方法

vLLM 支持通过 @register_quantization_config 装饰器在树外注册自定义量化方法，vllm-bnb-plugin 正是基于这一机制实现的。在 vllm/model_executor/layers/quantization/init.py 中可以看到其核心逻辑：

• 被装饰的类必须是 QuantizationConfig 的子类，否则抛出 ValueError；
• 若量化方法名尚未存在于 QUANTIZATION_METHODS，则自动追加，使后续的 get_quantization_config(name) 查找与配置校验能够通过；
• 注册结果写入 _CUSTOMIZED_METHOD_TO_QUANT_CONFIG 字典，并在 get_quantization_config() 返回配置类时优先合并自定义项。

自定义配置类需要实现 get_name()、get_supported_act_dtypes()、get_min_capability()、get_config_filenames()、from_config() 以及按层类型分发的 get_quant_method() 等方法（完整模板示例见 docs/features/quantization/README.md）。对于像 BitsAndBytes 这样不便于直接并入 vLLM 主仓库的方案，插件化既保持了主仓库的轻量，也让用户可以随时跟进 bitsandbytes 上游的能力演进——安装新版本插件即可获得更新，无需等待 vLLM 发版。

实践注意事项

• 先装插件再启动引擎：bitsandbytes 属于树外方法，未安装 vllm-bnb-plugin 时，任何形式的显式指定都会因方法不在注册表而失败；
• 预量化模型不要重复指定参数：vLLM 会在配置校验时比对 checkpoint 中的 quant_method 与用户显式传入的 quantization，两者不一致会直接报错；
• dtype 搭配：文档示例统一使用 torch.bfloat16，若模型 config 声明为 float32，按 LLM 入口说明 vLLM 会回落选用 float16；
• 社区模型注意开启 trust_remote_code：许多 bnb 预量化仓库包含自定义代码，需要在 LLM() 或启动参数中显式授权；
• 硬件前提：BitsAndBytes 路径需要 NVIDIA GPU（Volta 及以上），CPU 与 AMD/Intel GPU 平台不支持；
• 版本配套：插件与 vLLM 主版本需保持兼容（vLLM 保证文档化插件接口的可用性，但插件开发者需对版本兼容负责），升级 vLLM 时建议同步升级插件。