bitsandbytes：8-bit/4-bit大模型量化优化库安装与使用指南

bitsandbytes

官方信息

项目名称	bitsandbytes
仓库地址	https://github.com/TimDettmers/bitsandbytes
官方网站	GitHub README
最新更新时间	2026-09-07
Star 数	9k+
项目定位	8-bit/4-bit 量化训练与推理库，让消费级显卡也能跑大模型

项目背景

bitsandbytes 由华盛顿大学博士生 Tim Dettmers 创建，是大模型量化领域最具影响力的开源库之一。它最初实现了 8-bit 优化器状态量化，把训练大模型的显存需求直接砍掉一半；后来加入的 4-bit NormalFloat（NF4）量化技术，更是让单张 24GB 显卡微调 33B 模型成为可能。

在大模型时代，显存永远是稀缺资源。一个 7B 模型 BF16 加载需要约 14GB 显存，加上梯度、优化器状态，全参数训练需要 60GB+；70B 模型更是需要数百 GB。bitsandbytes 的出现，让研究者能用单张 3090/4090 做 LoRA 微调，让普通用户能在消费级显卡上跑 70B 推理。它已经成为 HuggingFace Transformers、PEFT、TRL 等生态的默认量化后端。

从技术角度，bitsandbytes 实现了创新的分块量化、动态量化统计、混合精度训练等算法，在几乎不损失模型效果的前提下，把权重从 16-bit 压缩到 4-bit，显存降低 75%。

核心特性

8-bit 优化器：AdamW8bit、Lion8bit，优化器状态显存减少 75%，训练效果与 32-bit 几乎无差。
4-bit NormalFloat（NF4）：专为正态分布神经网络权重设计的量化格式，QLoRA 论文核心技术。
8-bit 张量核心：利用 NVIDIA Tensor Core 加速 8-bit 矩阵乘法，推理速度接近 BF16。
自动序列化：量化后的模型可以直接 save_pretrained / from_pretrained，无缝切换。
HuggingFace 原生集成：AutoModel.from_pretrained 加一个 load_in_4bit=True 参数即可。
CPU 内存卸载：结合 accelerate，可以把暂时不用的权重放到 CPU 内存。
多后端支持：CUDA、ROCm（AMD）、MPS（Apple Silicon）。

环境要求

项目	最低要求	推荐配置
操作系统	Linux（Ubuntu 20.04+）	Ubuntu 22.04 LTS
Python	3.9	3.10 / 3.11
GPU	NVIDIA GTX 10系列以上	RTX 3090 / 4090 / A100
CUDA	11.0	12.1+
PyTorch	1.13+	2.1+

详细部署步骤

第一步：环境准备

conda create -n bnb python=3.10 -y
conda activate bnb

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

nvidia-smi
nvcc --version

第二步：安装 bitsandbytes

方式一：pip 安装（推荐，Linux）

pip install bitsandbytes

# 验证安装
python -c "import bitsandbytes as bnb; print(bnb.__version__); print(bnb.__cuda_version__)"

方式二：Windows 专用版本

# Windows 需要安装非官方编译版
pip install bitsandbytes-windows
# 或使用 0.43+ 后官方已原生支持 Windows
pip install bitsandbytes --upgrade

方式三：源码编译

git clone https://github.com/TimDettmers/bitsandbytes.git
cd bitsandbytes

# 编译 CUDA 算子
cmake -DBNB_BUILD_CUDA=ON -S . -B build
cmake --build build -j 16 --target bitsandbytes

pip install -e .

方式四：Docker

docker pull pytorch/pytorch:2.1.0-cuda12.1-cudnn8-devel

docker run -it --gpus all --shm-size=10g \
  -v /your/data:/workspace \
  pytorch/pytorch:2.1.0-cuda12.1-cudnn8-devel bash

pip install bitsandbytes transformers accelerate peft

第三步：4-bit 量化加载模型（QLoRA 推理）

from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
import torch

# 配置 4-bit 量化
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",        # 使用 NF4 量化
    bnb_4bit_use_double_quant=True,   # 双重量化，再省一点显存
    bnb_4bit_compute_dtype=torch.bfloat16  # 计算时用 BF16
)

# 加载模型（7B 模型仅需 ~5GB 显存）
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-7B-Instruct",
    quantization_config=bnb_config,
    device_map="auto",
    trust_remote_code=True
)

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-7B-Instruct")

# 推理
messages = [{"role": "user", "content": "你好"}]
text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = tokenizer(text, return_tensors="pt").to("cuda")
outputs = model.generate(**inputs, max_new_tokens=200)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

第四步：8-bit 量化加载

bnb_config = BitsAndBytesConfig(load_in_8bit=True)

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-7B-Instruct",
    quantization_config=bnb_config,
    device_map="auto"
)
# 7B 模型 8-bit 约需 7-8GB 显存

第五步：使用 8-bit AdamW 优化器训练

import bitsandbytes as bnb

# 把普通 AdamW 换成 8-bit 版本
optimizer = bnb.optim.AdamW8bit(
    model.parameters(),
    lr=1e-4,
    weight_decay=0.01
)

# 后续训练循环完全一样
for batch in dataloader:
    outputs = model(**batch)
    loss = outputs.loss
    loss.backward()
    optimizer.step()
    optimizer.zero_grad()

第六步：QLoRA 微调完整示例

from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training
import torch

# 1. 4-bit 量化加载
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_use_double_quant=True,
    bnb_4bit_compute_dtype=torch.bfloat16
)
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-7B-Instruct",
    quantization_config=bnb_config,
    device_map="auto"
)

# 2. 准备 k-bit 训练（开启梯度检查点、冻结 LayerNorm）
model = prepare_model_for_kbit_training(model)

# 3. 加 LoRA
lora_config = LoraConfig(
    r=16, lora_alpha=32, lora_dropout=0.05,
    target_modules=["q_proj", "v_proj"],
    task_type="CAUSAL_LM"
)
model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
# 输出：trainable params: 20,971,520 || all params: 7,652,557,824 || trainable%: 0.27%

常见坑与解决

Function incorrectly linked: libcudart.so：CUDA 版本不匹配，确保 pip 安装的 bitsandbytes 和系统 CUDA、PyTorch CUDA 版本一致。运行 python -m bitsandbytes 诊断。
Windows 上报错：0.43 之前的版本 Windows 不支持，升级到最新版或用 WSL2。
4-bit 模型不能直接全参数训练：量化后的权重是冻结的，只能训练 LoRA 适配器或输出层。
推理速度慢：确保用 bfloat16 计算 dtype，不要用 float32；开启 device_map="auto"。

使用方法示例

量化前后显存对比（7B 模型）：

精度	权重显存	总显存（含推理）	效果损失
FP32	~28 GB	~40 GB	基线
BF16	~14 GB	~20 GB	无
8-bit	~7 GB	~10 GB	<1%
4-bit NF4	~3.5 GB	~6 GB	1-2%

用单张 RTX 4090（24GB）即可流畅推理 34B 模型（4-bit）或微调 7B 模型（QLoRA）。

常见问题 FAQ

Q1：4-bit 量化会损失多少效果？
A：QLoRA 论文和大量实测表明，NF4 量化 + 双重量化在大多数任务上效果下降在 1% 以内，基本不可感知。

Q2：bitsandbytes 和 GPTQ / AWQ 有什么区别？
A：bitsandbytes 主要用于训练（QLoRA）和动态量化加载；GPTQ/AWQ 是训练后的静态量化，推理速度更快，适合部署。生产部署推荐 AWQ/GPTQ，研究微调用 bitsandbytes。

Q3：支持 AMD 显卡吗？
A：支持 ROCm 后端，安装 bitsandbytes-rocm。

Q4：能在 Apple M 系列芯片上用吗？
A：0.43+ 支持 MPS 后端，但功能有限，4-bit 训练暂不支持。

Q5：量化后的模型能导出给 Ollama / vLLM 用吗？
A：bitsandbytes 量化格式主要用于研究和训练，生产部署请用 GPTQ 或 AWQ 格式。

跳转链接

GitHub 仓库：https://github.com/TimDettmers/bitsandbytes
QLoRA 论文：QLoRA: Efficient Finetuning of Quantized LLMs
HuggingFace 量化文档：官方教程
诊断工具：python -m bitsandbytes

bitsandbytes：8-bit/4-bit大模型量化优化库安装与使用指南

bitsandbytes：8-bit/4-bit大模型量化优化库安装与使用指南

官方信息

项目背景

核心特性

环境要求

详细部署步骤

第一步：环境准备

第二步：安装 bitsandbytes

第三步：4-bit 量化加载模型（QLoRA 推理）

第四步：8-bit 量化加载

第五步：使用 8-bit AdamW 优化器训练

第六步：QLoRA 微调完整示例

常见坑与解决

使用方法示例

常见问题 FAQ

跳转链接

周若琳

文章目录