LoRA 微调 — 用一张消费级 GPU 让开源模型学会垂直任务

基于 HuggingFace PEFT + Transformers 的 LoRA 低秩微调完整工程：数据准备 → LoRA 训练（可选 QLoRA 4bit）→ 评估（Loss / PPL / 生成样例）→ 交互推理。

原始数据 ──► 格式化为 ChatML ──► 训练（仅更新 LoRA 低秩矩阵）──► 评估 ──► 推理
                        ▲                                      │
                  冻结主干模型                               合并权重（可选）

✨ 功能特性

• 🧩 LoRA 微调：只训练 0.1%~1% 的参数，Adapter 仅几十 MB
• ⚡ QLoRA 就绪：quantization: 4bit 即可 4-bit NF4 量化训练，7B 模型单卡可跑
• 📊 评估闭环：验证集 Loss / 困惑度 + 可控生成示例
• 🗂️ 数据集管线：Alpaca 格式 → ChatML 文本 → train/val 切分（可复现、带种子）
• 🖥️ 交互推理：加载 Adapter 直接对话
• 🔀 权重合并：--merge 输出完整模型，便于部署
• 📓 Jupyter 演示：端到端 Notebook

🧱 技术栈

Transformers · PEFT · Accelerate · Datasets · BitsAndBytes · PyTorch · TensorBoard

🚀 快速开始

1. 准备数据

pip install -r requirements.txt
python scripts/prepare_dataset.py \
  --input data/sample_instructions.json \
  --output-dir data/processed \
  --validation-split 0.1

2. 训练（LoRA）

python scripts/train_lora.py --config configs/lora_config.yaml

训练曲线：tensorboard --logdir output/lora-checkpoint

3. 评估

python scripts/evaluate.py --adapter output/lora-checkpoint

4. 推理

python scripts/inference.py --adapter output/lora-checkpoint

5.（可选）合并权重 + 推送 Hub

python scripts/train_lora.py --config configs/lora_config.yaml --merge

🔧 常用超参数速查

参数	说明	常见取值
lora_r	低秩维度	8 / 16 / 32
lora_alpha	缩放因子（通常为 r 的 2 倍）	16 / 32 / 64
lora_dropout	防过拟合	0.05 ~ 0.1
learning_rate	LoRA 常用较大 LR	1e-4 ~ 3e-4
quantization	null / "4bit"	小模型用 null，大模型用 4bit

📁 项目结构

lora-finetuning/
├── configs/lora_config.yaml   # 模型 / LoRA / 训练参数
├── scripts/
│   ├── prepare_dataset.py     # 数据格式化与切分
│   ├── train_lora.py          # LoRA/QLoRA 训练
│   ├── evaluate.py            # Loss/PPL/生成评估
│   └── inference.py           # 交互式推理
├── data/
│   ├── sample_instructions.json
│   └── processed/             # 生成的 train/val JSONL
├── notebooks/finetune_demo.ipynb
├── tests/                     # 数据集管线测试
└── requirements.txt

🧪 测试（无需 GPU）

pip install pytest && pytest tests/ -v

📄 License

MIT