Llama-Factory 部署常见错误与解决方案

调整为：

--lora_target q_proj,v_proj \
--rank 32 \
--learning_rate 1e-4

训练完成后需合并权重：

python src/merge_lora_weights.py \
--model_name_or_path meta-llama/Llama-2-7b-hf \
--adapter_name_or_path ./output/lora_tuning \
--output_dir ./merged_model

否则推理时需同时加载 base model 和 adapter，影响性能。合并后的模型可直接用于 vLLM 或 Triton 部署。

QLoRA：消费级显卡上的微调方案

QLoRA 通过 NF4 量化基础模型并将优化器状态压缩到 4-bit，借助 bitsandbytes 库实现，使得 LLaMA-7B 的显存占用从 80GB 骤降到 25GB 以内。

典型命令：

python src/train_bash.py \
--model_name_or_path meta-llama/Llama-2-7b-hf \
--finetuning_type lora \
--quantization_bit 4 \
--lora_target q_proj,v_proj \
--rank 64 \
--per_device_train_batch_size 4 \
--gradient_accumulation_steps 16

注意 batch size 虽为 4，但通过累积 16 步等效达到 64。由于量化带来数值敏感性上升，学习率通常控制在 1e-4~3e-4 之间。

环境安装常见报错：

CUDA error: no kernel image is available for execution on the device

这通常是因为安装了 CPU 版 bitsandbytes 或版本不匹配。正确做法：

pip uninstall bitsandbytes
pip install bitsandbytes-cuda11x -f https://jllllll.github.io/bitsandbytes-windows-webui

注意替换为对应 CUDA 版本（如 cuda12x）。NF4 比 int4 更适合 LLM 微调，框架默认即可。

部分国产模型尚未适配 QLoRA。例如早期版本的 ChatGLM-6B 因结构特殊，直接量化会导致 NaN 输出。解决方法要么升级到最新 transformers>=4.36，要么退回到纯 LoRA 模式。

QLoRA 训练完不能直接合并权重，必须先反量化：

--output_dir ./dequantized_model \
--quantization_bit 0

再执行 merge 操作，否则会丢失精度。

WebUI：降低非技术人员参与门槛

Llama-Factory 提供基于 Gradio + FastAPI 的轻量服务，前端提交 JSON 配置，后端解析成 TrainingArguments 对象，异步执行子进程并实时返回日志流。

潜在问题：

• 浏览器超时断连：长时间训练（>12 小时）容易因网络波动中断；
• 多用户资源争抢：多人共用一台服务器时，可能同时启动多个训练任务；
• 权限管理缺失：默认绑定 0.0.0.0 存在安全风险。

应对方案：

1. 使用 nohup python app.py --host 127.0.0.1 & 限制本地访问；
2. 配合 nginx 做反向代理 + basic auth 认证；
3. 用 screen 或 tmux 托管训练进程；
4. 前端增加'离线训练'提示。

建议每次训练后自动导出 YAML 配置文件，方便复现和归档。

实战案例：单卡 3090 微调 7B 模型

针对资源受限场景，具体步骤如下：

第一步：环境准备

# 必须安装支持 CUDA 的 bitsandbytes
pip install "transformers>=4.36" "accelerate>=0.26" bitsandbytes-cuda118

第二步：启用 QLoRA

python src/train_bash.py \
--model_name_or_path meta-llama/Llama-2-7b-hf \
--dataset your_data.jsonl \
--finetuning_type lora \
--quantization_bit 4 \
--lora_target q_proj,v_proj \
--rank 32 \
--lora_alpha 64 \
--per_device_train_batch_size 2 \
--gradient_accumulation_steps 32 \
--learning_rate 2e-4 \
--num_train_epochs 3 \
--output_dir ./output/qlora_7b \
--fp16

这样下来，峰值显存稳定在 23.8GB 左右。

第三步：监控与调优

开启 TensorBoard 查看 loss 趋势：

tensorboard --logdir=output/qlora_7b

若发现前期震荡剧烈，可增加 warmup_steps 至 500；若收敛缓慢，则适当提升 rank 至 64。

第四步：导出可用模型

# 先反量化
python src/export_model.py \
--model_name_or_path meta-llama/Llama-2-7b-hf \
--adapter_name_or_path ./output/qlora_7b \
--output_dir ./final_model \
--quantization_bit 0

# 再合并 LoRA 权重
python src/merge_lora_weights.py \
--model_name_or_path ./final_model \
--output_dir ./merged_serving_model

最终得到的 merged_serving_model 为标准 HF 格式模型，可直接用于 API 服务。

总结

Llama-Factory 将全参微调、LoRA、QLoRA、WebUI 这些能力有机整合，形成覆盖'性能—效率—易用性'的完整工具链。

可根据资源情况灵活选择：

• 资源充足 → 全参数微调，冲击 SOTA；
• 单卡专业卡 → LoRA，平衡效果与成本；
• 消费级显卡 → QLoRA，极限压缩显存；
• 团队协作 → WebUI，降低使用门槛。

只要掌握正确的方法，哪怕只有一张 3090，也能完成高质量的领域适配。真正的价值在于知道什么时候该用什么工具，以及如何避开那些别人已经踩过的坑。