Python LLM 微調深度實戰（2026）：QLoRA 全流程、調參與生產部署

AI与大数据AI Agent 生產實務（更新於 2026年7月20日）

快速預覽

全參數微調一個 7B 模型需要 4 張 A100——對絕大多數團隊不現實。QLoRA 把「4-bit 量化 + 低秩適配 + 分頁最佳化器」組合在一起，讓單張消費級顯卡就能微調大模型。

本文提供可重現的全流程：從 NF4 量化原理，到 PEFT 配置實操，到 TRL 訓練，到 vLLM 部署。每步都有程式碼，有資料，有坑點提醒。

原理深度：LoRA 和 QLoRA 到底做了什麼

LoRA：凍結基座，只訓練旁路

LoRA 不修改預訓練權重 W。它在每個注意力層旁插入兩個可訓練的低秩矩陣 A 和 B：

h = W·x + (B·A)·x
    ^^^^   ^^^^^^^^^
    凍結    可訓練（r << d，通常 8–64）

反向傳播時，只有 A 和 B 的梯度非零——W 的梯度始終為零（凍結）。優化器狀態（AdamW 的 momentum 和 variance）只需儲存 A 和 B 的參數，而不是整個 W。

初始化技巧：A 用 Kaiming / Xavier 正態初始化，B 初始化為全零矩陣。這樣訓練開始時 BA=0，模型的初始輸出與原始預訓練模型完全一致——保證了訓練穩定性。

對於 7B 模型，可訓練參數可控制在 0.1%–0.5%。

QLoRA：更進一步——把基座也壓縮

QLoRA 在 LoRA 基礎上把凍結的基座權重 W 量化為 4-bit NormalFloat (NF4)。

NF4 為什麼優於 INT4：INT4 是均勻量化（等間距），假設權重均勻分佈。但實際上預訓練權重的分佈近似零均值正態分佈——集中在均值附近，兩端稀疏。NF4 是資訊理論最優的非均勻量化方案，在機率密度高的區域分配更多量化級別，在尾部分配更少。實驗表明，NF4 的資訊損失約為 INT4 的 1/2 到 1/3。

雙重量化：對量化常數（scaling factor）本身再進行一次量化（通常用 FP8），額外節省約 0.4 bit/參數。

分頁最佳化器：當 GPU 顯存接近極限時，Paged Optimizer 把 optimizer state 分為固定大小的 page，在 CPU 和 GPU 之間自動換頁——類似作業系統的虛擬記憶體機制。

顯存帳

Llama 3.1-8B，BF16 約 16 GB 權重：

元件 全參數微調 QLoRA
模型權重 16 GB (BF16) ~3.8 GB (NF4)
優化器狀態 (AdamW) 32 GB（m+v） ~0.08 GB（僅 LoRA）
梯度 16 GB ~0.08 GB
活化值（batch=4,seq=2048） ~12 GB ~12 GB
總計 ~76 GB ❌ ~16 GB ✅

單卡 24 GB 充足，甚至能用 16 GB 卡（如 RTX 4060 Ti 16GB）跑小 batch。

環境搭建

pip install torch transformers accelerate peft bitsandbytes trl datasets tensorboard

版本要求的坑：bitsandbytes 需匹配 CUDA 版本。trl 0.9+ 使用 SFTConfig。Windows 用戶建議用 WSL2。

載入 4-bit 量化模型

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig

bnb_config = BitsAndBytesConfig(
    load_in_4bit=True, bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16, bnb_4bit_use_double_quant=True,
)

model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-8B",
    quantization_config=bnb_config, device_map="auto", torch_dtype=torch.bfloat16,
)
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-3.1-8B")
tokenizer.pad_token = tokenizer.eos_token

配置 LoRA

from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training

model = prepare_model_for_kbit_training(model)

lora_config = LoraConfig(
    r=16, lora_alpha=32, lora_dropout=0.05,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
                    "gate_proj", "up_proj", "down_proj"],
    bias="none", task_type="CAUSAL_LM",
)
model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
# trainable: ~42M / ~8B = 0.52%

超參數選擇指南

參數 建議 原理
r 8–32 r 控制低秩矩陣的秩。r=8 等價於用 8 個基向量表達 ΔW，大多數任務已足夠。
lora_alpha r × 1–2 實際學習率 ∝ alpha / r。設 alpha=32 且 r=16，等效縮放為 2.0。
lora_dropout 0.05 正則化。小資料集 (<500) 設 0.1。大資料集設 0。
target_modules 越多越好 Llama: q/k/v/o + gate/up/down。Mistral/GLM 需查 state_dict。

準備資料集

from datasets import load_dataset

dataset = load_dataset("tatsu-lab/alpaca")

def format_instruction(example):
    if example.get("input"):
        prompt = f"""### Instruction:\n{example["instruction"]}\n\n### Input:\n{example["input"]}\n\n### Response:\n{example["output"]}"""
    else:
        prompt = f"""### Instruction:\n{example["instruction"]}\n\n### Response:\n{example["output"]}"""
    return {"text": prompt}

dataset = dataset.map(format_instruction)

💡 200–500 條跑通 → 驗證 loss 下降 → 2k–5k 條開始看到效果 → 10k+ 條進入競爭力區間。品質遠大於數量。

訓練：TRL SFTTrainer

from trl import SFTTrainer, SFTConfig

training_args = SFTConfig(
    output_dir="./qlora-llama3-chat",
    per_device_train_batch_size=4, gradient_accumulation_steps=4,
    num_train_epochs=3, max_seq_length=2048,
    logging_steps=10, save_steps=200,
    learning_rate=2e-4, lr_scheduler_type="cosine", warmup_ratio=0.03,
    optim="paged_adamw_8bit", bf16=True, gradient_checkpointing=True,
    report_to="tensorboard",
)

trainer = SFTTrainer(model=model, args=training_args,
                     train_dataset=dataset["train"], tokenizer=tokenizer)
trainer.train()

tensorboard --logdir ./qlora-llama3-chat 監控：loss（穩定下降到 0.5–1.5）、grad_norm（理想 0.1–1.0）、GPU 利用率（接近 100%）。

評估

from peft import PeftModel

base = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-8B", torch_dtype=torch.bfloat16, device_map="auto"
)
base = PeftModel.from_pretrained(base, "./qlora-llama3-chat/checkpoint-600")
base = base.merge_and_unload()

def generate(prompt, max_new=256):
    inputs = tokenizer(prompt, return_tensors="pt").to("cuda")
    outputs = base.generate(**inputs, max_new_tokens=max_new, temperature=0.7, do_sample=True)
    return tokenizer.decode(outputs[0], skip_special_tokens=True)

定量：用 GPT-4 做 judge，按準確性/完整性/有幫助程度 1–5 評分，平均 > 4.0 即可。

儲存與部署

trainer.save_model("./qlora-llama3-chat-final")  # 約 60 MB

model = PeftModel.from_pretrained(base, "./qlora-llama3-chat-final")
model = model.merge_and_unload()
model.save_pretrained("./merged-model")
tokenizer.save_pretrained("./merged-model")

vLLM 部署

python -m vllm.entrypoints.openai.api_server \
  --model ./merged-model --dtype bfloat16 \
  --max-model-len 4096 --port 8000 --gpu-memory-utilization 0.90

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
resp = client.chat.completions.create(
    model="./merged-model",
    messages=[{"role": "user", "content": "解釋一下 NF4 量化原理"}],
)

FAQ

Q1：QLoRA 和全參數微調的品質差距？——大多數領域適配任務中達到 96–99%。僅極端任務需全參數。

Q2：r=8 和 r=64 差別大嗎？——中等資料集上 r=8 足夠，邊際遞減明顯。先保證資料品質，不是調 r。

Q3：多 LoRA 同時用？——model.set_adapter() 毫秒切換，不重載基座。

Q4：loss 低但回答差？——過擬合到 prompt 模板。增多樣性、降 epoch、加 dropout。

Q5：CPU 訓練？——極慢。用 Colab 免費 T4 / Kaggle 免費 P100。

總結

推薦路徑：200 條驗證 → TensorBoard 調參 → 手動測試 → 加資料（不是加 r） → merge → vLLM 部署。

#LLM#微调#QLoRA#LoRA#PEFT#量化