大模型量化实战手册：从零开始，四条路线全覆盖

你想做什么？
│
├─ 路线一：我就想拉一个模型来玩玩（零门槛）
│   → 直接下载社区预量化模型，用 Ollama / LM Studio 一键跑起来
│
├─ 路线二：我要自己量化一个模型（极客必修课）
│   → 用 AWQ / GPTQ / GGUF 工具手动量化，完全掌控精度和体积
│
├─ 路线三：我要在服务端部署高吞吐推理服务（生产级）
│   → vLLM + FP8 全量化，零校准或静态校准，极限压榨 H100
│
└─ 路线四：我要在有限显存下微调大模型（QLoRA）
    → BitsAndBytes NF4 量化基座 + LoRA 适配器，24GB 显卡微调 70B

模型名字里的密码：

Qwen3-32B-AWQ              → AWQ 格式，默认 4-bit 权重量化
Qwen3-32B-GPTQ-Int4        → GPTQ 格式，4-bit 整数权重量化
Qwen3-32B-GGUF             → GGUF 格式（文件内会有多个精度版本）
Qwen3-32B-FP8              → FP8 全量化（权重+激活值都是 FP8）

GGUF 文件名里的密码：
  Q2_K    → 2-bit （极限压缩，智商有明显退化）
  Q3_K_S  → 3-bit small（空间优先）
  Q4_K_M  → 4-bit medium（⭐ 最推荐的平衡点）
  Q5_K_M  → 5-bit medium（追求更高精度）
  Q6_K    → 6-bit （接近无损）
  Q8_0    → 8-bit （几乎无损，但体积较大）

# 安装 Ollama（如果还没装）
curl -fsSL https://ollama.com/install.sh | sh

# 一行命令拉取并运行量化模型
ollama run qwen3:32b

# 想用特定精度？搜索 Ollama 库里的 tag
ollama run qwen3:32b-q4_K_M

# 直接从 HuggingFace 下载 GGUF 文件
huggingface-cli download bartowski/Qwen3-32B-GGUF \
  --include "Qwen3-32B-Q4_K_M.gguf" \
  --local-dir ./models

# 用 llama.cpp 的 server 模式启动 OpenAI 兼容 API
llama-server \
  -m ./models/Qwen3-32B-Q4_K_M.gguf \
  --port 8080 \
  -ngl 99    # 尽可能多地把层放到 GPU 上

# 安装 AutoAWQ
pip install autoawq

from awq import AutoAWQForCausalLM
from transformers import AutoTokenizer
from datasets import load_dataset

# ====== 配置 ======
model_path = "Qwen/Qwen3-8B"           # HuggingFace 模型 ID 或本地路径
quant_path = "./Qwen3-8B-AWQ"           # 量化后的输出目录
quant_config = {
    "zero_point": True,                  # 启用零点量化（精度更高）
    "q_group_size": 128,                 # 每 128 个权重共享一个缩放因子
    "w_bit": 4,                          # 量化到 4-bit
    "version": "GEMM",                   # 使用 GEMM 内核（兼容性最好）
}

# ====== 加载模型和分词器 ======
model = AutoAWQForCausalLM.from_pretrained(model_path)
tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)

# ====== 准备校准数据 ======
# AWQ 非常高效，128~256 条样本就够了！
def get_calibration_data():
    data = load_dataset(
        "databricks/databricks-dolly-15k",
        split="train[:128]"
    )
    return [
        f"{x['instruction']}\n{x['context']}\n{x['response']}"
        for x in data
    ]

calib_data = get_calibration_data()

# ====== 执行量化 ======
model.quantize(
    tokenizer=tokenizer,
    quant_config=quant_config,
    calib_data=calib_data,
)

# ====== 保存结果 ======
model.save_quantized(quant_path)
tokenizer.save_pretrained(quant_path)
print(f"✅ AWQ 量化完成，已保存到 {quant_path}")

# 安装 GPTQModel
pip install -U gptqmodel --no-build-isolation

from datasets import load_dataset
from gptqmodel import GPTQModel, QuantizeConfig

# ====== 配置 ======
model_id = "Qwen/Qwen3-8B"
quant_path = "./Qwen3-8B-GPTQ-Int4"

# ====== 准备校准数据 ======
# GPTQ 通常需要更多数据（512~1024 条）来计算 Hessian 矩阵
calibration_dataset = load_dataset(
    "allenai/c4",
    data_files="en/c4-train.00001-of-01024.json.gz",
    split="train"
).select(range(1024))["text"]

# ====== 量化配置 ======
quant_config = QuantizeConfig(
    bits=4,                # 量化位数
    group_size=128,        # 分组大小
)

# ====== 加载并量化 ======
model = GPTQModel.load(model_id, quant_config)
model.quantize(calibration_dataset, batch_size=2)

# ====== 保存 ======
model.save(quant_path)
print(f"✅ GPTQ 量化完成，已保存到 {quant_path}")

# 克隆 llama.cpp
git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp

# 编译（开启 CUDA 加速转换速度）
mkdir build && cd build
cmake .. -DGGML_CUDA=ON
cmake --build . --config Release -j$(nproc)

# 安装 Python 依赖（用于格式转换）
pip install -r ../requirements.txt

# 假设你的模型在 ./models/Qwen3-8B/
python convert_hf_to_gguf.py ../models/Qwen3-8B/ \
  --outtype f16 \
  --outfile ../models/Qwen3-8B-f16.gguf

# 量化为 Q4_K_M（最推荐的平衡点）
./bin/llama-quantize \
  ../models/Qwen3-8B-f16.gguf \
  ../models/Qwen3-8B-Q4_K_M.gguf \
  Q4_K_M

# 其他常用量化级别
# Q8_0    → 几乎无损，体积约为 FP16 的 50%
# Q6_K    → 接近无损，适合显存有余裕时使用
# Q5_K_M  → 高精度，略大于 Q4
# Q4_K_M  → ⭐ 性价比之王
# Q3_K_M  → 显存紧张时的妥协
# Q2_K    → 极限压缩，智商有明显退化

# 先生成重要性矩阵（需要一些代表性文本）
./bin/llama-imatrix \
  -m ../models/Qwen3-8B-f16.gguf \
  -f ../calibration_data.txt \
  -o ../models/imatrix.dat

# 用 imatrix 辅助量化
./bin/llama-quantize \
  --imatrix ../models/imatrix.dat \
  ../models/Qwen3-8B-f16.gguf \
  ../models/Qwen3-8B-Q3_K_M-imat.gguf \
  Q3_K_M

# 一行参数搞定 FP8 量化
vllm serve Qwen/Qwen3-32B-Instruct \
  --quantization fp8 \
  --dtype auto \
  --gpu-memory-utilization 0.90 \
  --enable-prefix-caching

# 安装
pip install llmcompressor

from llmcompressor.modifiers.quantization import QuantizationModifier
from llmcompressor import oneshot
from datasets import load_dataset
from transformers import AutoTokenizer

model_id = "Qwen/Qwen3-32B-Instruct"
output_dir = "./Qwen3-32B-FP8-Static"

# 准备少量校准数据（512 条即可）
tokenizer = AutoTokenizer.from_pretrained(model_id)
ds = load_dataset("HuggingFaceFW/fineweb-edu", split="train", streaming=True)
calibration_data = [tokenizer.apply_chat_template(
    [{"role": "user", "content": x["text"][:2000]}],
    tokenize=False
) for x in list(ds.take(512))]

# 执行 FP8 静态量化
recipe = QuantizationModifier(
    targets="Linear",
    scheme="FP8",
    ignore=["lm_head"],  # 输出层保持高精度
)

oneshot(
    model=model_id,
    dataset=calibration_data,
    recipe=recipe,
    output_dir=output_dir,
    max_seq_length=4096,
    num_calibration_samples=512,
)

vllm serve ./Qwen3-32B-FP8-Static \
  --dtype auto \
  --gpu-memory-utilization 0.90
# 不需要加 --quantization fp8，vLLM 会自动检测 checkpoint 中的 FP8 配置

vllm serve Qwen/Qwen3-32B-Instruct \
  --quantization fp8 \
  --kv-cache-dtype fp8_e5m2 \   # KV Cache 从 BF16 压缩为 FP8
  --enable-prefix-caching

QLoRA 的天才设计：
  1. 用 NF4（NormalFloat 4-bit）量化基座模型 → 70B 模型从 140GB 压缩到 ~35GB
  2. 冻结量化后的基座权重（不训练！）
  3. 在旁边附加微小的 LoRA 适配器（通常只有几十 MB）
  4. 只训练 LoRA 适配器，显存开销极低
  5. 训练过程中，量化的权重会临时解压回 BF16 参与计算（保持精度）

from transformers import (
    AutoModelForCausalLM,
    AutoTokenizer,
    BitsAndBytesConfig,
    TrainingArguments,
)
from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training
from trl import SFTTrainer
from datasets import load_dataset

# ====== 4-bit 量化配置 ======
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,                  # 启用 4-bit 加载
    bnb_4bit_quant_type="nf4",          # 使用 NF4（信息论最优）
    bnb_4bit_compute_dtype="bfloat16",  # 计算时反量化到 BF16
    bnb_4bit_use_double_quant=True,     # 双重量化（进一步省 ~0.4 bit/参数）
)

# ====== 加载量化后的基座模型 ======
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-8B",
    quantization_config=bnb_config,
    device_map="auto",
)
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-8B")

# ====== 准备模型用于训练 ======
model = prepare_model_for_kbit_training(model)

# ====== LoRA 配置 ======
lora_config = LoraConfig(
    r=16,                    # LoRA 秩（常用 8~64）
    lora_alpha=32,           # 缩放因子（通常设为 r 的 2 倍）
    target_modules=[         # 要附加 LoRA 的层
        "q_proj", "k_proj",
        "v_proj", "o_proj",
        "gate_proj", "up_proj", "down_proj",
    ],
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
)

model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
# → trainable params: 13,631,488 || all params: 8,043,235,328
# → trainable%: 0.1695%   ← 只训练 0.17% 的参数！

# ====== 加载训练数据 ======
dataset = load_dataset("your-dataset-here", split="train")

# ====== 开始训练 ======
trainer = SFTTrainer(
    model=model,
    train_dataset=dataset,
    tokenizer=tokenizer,
    args=TrainingArguments(
        output_dir="./qlora-output",
        per_device_train_batch_size=4,
        gradient_accumulation_steps=4,
        num_train_epochs=3,
        learning_rate=2e-4,
        bf16=True,
        logging_steps=10,
        save_strategy="epoch",
    ),
)
trainer.train()

./bin/llama-perplexity \
  -m ./models/Qwen3-8B-Q4_K_M.gguf \
  -f ./test_data.txt \
  --chunks 32

# 安装
pip install lm-eval

# 对量化后的 GPTQ/AWQ 模型跑基准
lm_eval --model hf \
  --model_args pretrained=./Qwen3-8B-AWQ \
  --tasks mmlu,hellaswag,arc_challenge \
  --batch_size auto \
  --output_path ./eval_results/

# 对 GGUF 模型跑基准（通过 llama.cpp server）
# 先启动 server，再对 API 做评估

# 最简单粗暴但最有效的方法：
# 准备 50~100 条你的真实业务问题 + 标准答案
# 分别用原始模型和量化模型跑一遍
# 人工或用 LLM-as-a-Judge 对比评分

import json

test_cases = json.load(open("business_test_cases.json"))
# [{"question": "...", "expected_answer": "..."}, ...]

for case in test_cases:
    original_answer = call_model(original_model, case["question"])
    quantized_answer = call_model(quantized_model, case["question"])
    # 比较两者的差异

ModuleNotFoundError: No module named 'auto_gptq'

pip uninstall auto-gptq
pip install -U gptqmodel --no-build-isolation