LLaMA-Factory微调大模型实战指南

LLaMA-Factory微调大模型实战指南

在生成式AI迅速普及的今天，如何让一个通用大模型真正“懂行”，成为某个垂直领域的专家？答案就是——微调。然而，传统微调流程复杂、依赖繁多、门槛极高，常常让人望而却步。

直到LLaMA-Factory的出现。它像一座自动化程度极高的工厂流水线，把从数据准备、模型训练到部署上线的整个过程封装得严丝合缝。无论你是想用 Qwen 做中文客服，还是拿 Llama 构建代码助手，只需几步配置，就能产出一个专属的领域模型。

更关键的是，它提供了直观的 WebUI 界面，甚至支持命令行与 YAML 配置双轨操作，兼顾新手友好性与高级用户的灵活性。本文将带你完整走一遍这个“大模型定制工厂”的核心流程，手把手实现一次 LoRA 微调实战。

从零搭建：环境准备与服务启动

我们先从最基础的环境搭建开始。推荐使用conda来管理 Python 环境，避免版本冲突带来的“玄学问题”。

conda create -n llamafactory python=3.10 conda activate llamafactory

接下来安装 PyTorch。如果你有 NVIDIA 显卡，务必安装带 CUDA 支持的版本：

conda install pytorch==2.3.1 torchvision==0.18.1 torchaudio==2.3.1 pytorch-cuda=12.1 -c pytorch -c nvidia

没有 GPU 的同学也不用担心，可以安装 CPU 版本（只是训练会慢很多）：

conda install pytorch==2.3.1 torchvision==0.18.1 torchaudio==2.3.1 cpuonly -c pytorch

然后克隆项目并安装依赖：

git clone https://github.com/hiyouga/LLaMA-Factory.git cd LLaMA-Factory pip install -r requirements.txt pip install -e ".[metrics]"

这里-e ".[metrics]"表示以可编辑模式安装，并包含评测组件（如 BLEU、ROUGE 计算），对后续评估非常有用。

一切就绪后，启动 WebUI：

llamafactory-cli webui

默认打开http://127.0.0.1:7860。如果需要远程访问或修改端口，可以通过环境变量控制：

USE_MODELSCOPE_HUB=1 CUDA_VISIBLE_DEVICES=0 GRADIO_SHARE=true GRADIO_SERVER_PORT=8080 llamafactory-cli webui

值得一提的是，LLaMA-Factory 原生支持 Hugging Face 和 ModelScope 双平台模型源，对于国内用户来说，切换到 ModelScope 能显著提升模型下载速度，减少超时失败的概率。

模型加载：本地化与加速下载

虽然框架支持在线加载 HF 或 MS 上的模型，但在实际使用中，建议提前下载到本地，避免每次启动都重新拉取。

推荐方式：通过 ModelScope 下载（适合国内）

from modelscope.hub.snapshot_download import snapshot_download model_dir = snapshot_download('qwen/Qwen-1_8B-Chat', revision='master') print(model_dir)

这种方式稳定且快速。下载完成后，路径通常类似./models/qwen-1.8b-chat，之后在 WebUI 中直接填写该路径即可。

你也可以手动创建目录结构：

LLaMA-Factory/ └── models/ └── qwen-1.8b-chat/ ├── config.json ├── pytorch_model.bin └── tokenizer.model

只要文件齐全，框架就能正确识别并加载。

数据集准备：格式规范与自定义注册

数据是微调的灵魂。LLaMA-Factory 支持多种标准格式，最常见的是alpaca和sharegpt。

alpaca 格式（适用于 SFT 监督微调）

{ "instruction": "解释什么是光合作用", "input": "", "output": "光合作用是植物利用阳光将二氧化碳和水转化为有机物的过程..." }

这种三元组结构清晰明了，非常适合构建指令类任务。

sharegpt 格式（用于 DPO 偏好优化）

{ "conversations": [ {"from": "human", "value": "写一首关于春天的诗"}, {"from": "assistant", "value": "春风拂面花自开..."} ], "chosen": "春风拂面花自开...", "rejected": "好的，我来写一首诗：春风吹..." }

DPO 是当前主流的对齐方法之一，它不需要额外训练奖励模型，直接基于人类偏好进行优化，效果出色。

如何注册自己的数据集？

很简单，三步走：

1. 将你的数据文件（如mydata.json）放入data/目录；
2. 修改data/dataset_info.json，添加新条目：

{ "my_custom_dataset": { "file_name": "mydata.json" } }

3. 刷新 WebUI 页面，下拉框里就会出现my_custom_dataset。

支持格式包括.json,.jsonl,.csv,.parquet，灵活度很高。推荐结构如下：

LLaMA-Factory/ └── data/ ├── mydata.json └── dataset_info.json

一个小技巧：如果你的数据量很大，建议启用preprocessing_num_workers多进程预处理，能显著加快数据加载速度。

实战演练：Qwen-1.8B + LoRA 微调全流程

我们以通义千问 Qwen-1.8B为例，使用 LoRA 对其进行监督微调（SFT）。LoRA 是目前最主流的高效微调技术之一，仅需更新低秩矩阵，显存占用极低，适合消费级显卡。

关键参数设置

启动训练（命令行方式）

llamafactory-cli train \ --stage sft \ --do_train True \ --model_name_or_path ./models/qwen-1.8b-chat \ --preprocessing_num_workers 8 \ --finetuning_type lora \ --template qwen \ --dataset_dir data \ --dataset my_custom_dataset \ --cutoff_len 1024 \ --learning_rate 5e-5 \ --num_train_epochs 3.0 \ --max_samples 10000 \ --per_device_train_batch_size 2 \ --gradient_accumulation_steps 8 \ --lr_scheduler_type cosine \ --warmup_steps 0 \ --logging_steps 10 \ --save_steps 100 \ --output_dir saves/qwen/lora/sft \ --fp16 True \ --plot_loss True \ --lora_rank 8 \ --lora_alpha 16 \ --lora_dropout 0.05 \ --lora_target all \ --trust_remote_code True

几个关键点值得强调：

• --plot_loss True：训练结束后会自动生成损失曲线图，便于分析收敛情况；
• --lora_target all：自动识别所有可插入 LoRA 的层（对 Qwen/Llama 系列有效）；
• --trust_remote_code True：必须开启，否则无法加载 Qwen 这类非官方 HF 标准模型。

训练过程中，你可以通过 WebUI 实时查看 loss 曲线、学习率变化等信息。整个流程无需写一行代码，极大降低了上手成本。

中断续训：不怕意外崩溃

训练动辄几小时起步，万一断电或程序崩溃怎么办？别慌，LLaMA-Factory 支持断点续训。

只要保持--output_dir不变，再次运行相同的命令，框架会自动检测最新的 checkpoint 并从中恢复训练，无需手动指定：

llamafactory-cli train \ --output_dir saves/qwen/lora/sft \ # 其他参数同上...

当然，你也可以手动指定恢复路径：

llamafactory-cli train \ --resume_from_checkpoint saves/qwen/lora/sft/checkpoint-200 \ --output_dir saves/qwen/lora/sft

checkpoint 的保存频率由--save_steps决定（比如每 100 步保存一次）。建议根据训练总步数合理设置，避免磁盘被大量中间模型占满。

模型评估：量化性能表现

微调完不评估等于白干。LLaMA-Factory 提供了内置的eval命令，支持多种指标输出。

首先创建一个eval.yaml文件：

stage: sft do_eval: true model_name_or_path: ./models/qwen-1.8b-chat adapter_name_or_path: saves/qwen/lora/sft template: qwen dataset: identity,test_exam dataset_dir: data cutoff_len: 1024 per_device_eval_batch_size: 1 output_dir: saves/qwen/lora/sft overwrite_output_dir: true predict_with_generate: true

执行评估：

llamafactory-cli eval examples/eval_qwen_lora.yaml

输出结果会包含 BLEU、ROUGE、Accuracy 等常见 NLP 指标，方便你横向对比不同训练策略的效果。

此外，还可以接入第三方评测工具：

• 🧪 OpenCompass：综合性强，覆盖 MMLU、C-Eval 等权威基准；
• 🔬 lm-evaluation-harness：社区广泛使用，插件丰富。

这些工具能帮你更全面地衡量模型能力，特别是在知识理解、推理等方面的表现。

批量推理与 API 部署

训练好的模型不能只停留在本地测试，必须能对外提供服务。

批量推理：生成预测结果

可用于验证模型泛化能力，或为下游系统准备数据：

llamafactory-cli train \ --stage sft \ --do_predict \ --model_name_or_path ./models/qwen-1.8b-chat \ --adapter_name_or_path saves/qwen/lora/sft \ --dataset test_data \ --dataset_dir data \ --template qwen \ --finetuning_type lora \ --output_dir saves/qwen/lora/predict \ --cutoff_len 1024 \ --per_device_eval_batch_size 1 \ --max_samples 100 \ --predict_with_generate

输出文件为predictions.jsonl，每一行是一个 JSON 对象，包含原始输入和模型生成文本，结构清晰，易于解析。

启动 API 服务（兼容 OpenAI 协议）

这是生产部署的关键一步。LLaMA-Factory 支持一键启动符合 OpenAI 接口规范的 API 服务：

CUDA_VISIBLE_DEVICES=0 API_PORT=8000 llamafactory-cli api \ --model_name_or_path ./models/qwen-1.8b-chat \ --adapter_name_or_path saves/qwen/lora/sft \ --template qwen \ --finetuning_type lora \ --use_fast_tokenizer false

服务启动后监听http://127.0.0.1:8000，可通过 curl 测试：

curl http://127.0.0.1:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-1.8b-lora", "messages": [ {"role": "user", "content": "请解释量子纠缠"} ], "temperature": 0.7 }'

最大亮点是：完全兼容 OpenAI SDK！这意味着你可以直接替换openai.api_base地址，无缝接入 LangChain、LlamaIndex、FastAPI 等生态工具，极大简化集成成本。

模型导出：合并与量化

微调后的 LoRA 模型本质上是“差分权重”，不能独立运行。要真正部署，通常需要将其合并到原模型中。

合并 LoRA 权重（生成全量模型）

llamafactory-cli export \ --model_name_or_path ./models/qwen-1.8b-chat \ --adapter_name_or_path saves/qwen/lora/sft \ --export_dir ./exports/qwen-1.8b-sft-merged \ --export_size 2 \ --export_legacy_format false \ --finetuning_type lora

输出目录包含完整的config.json,pytorch_model.bin,tokenizer_config.json等文件，可以直接用 HuggingFace 的AutoModelForCausalLM加载，也可打包发布。

导出 4-bit GGUF 量化模型

如果你想在 CPU 或 MacBook 上运行，推荐导出为 GGUF 格式：

llamafactory-cli export \ --model_name_or_path ./models/qwen-1.8b-chat \ --adapter_name_or_path saves/qwen/lora/sft \ --export_dir ./exports/qwen-1.8b-gguf \ --export_quantization_bit 4 \ --export_quantization_dataset alpaca_en \ --export_quantization_method gguf \ --export_size 2

优点非常明显：
- 体积缩小约 75%；
- 内存占用大幅降低；
- 可在无 GPU 环境下流畅运行（配合 llama.cpp）；

特别适合边缘设备、个人知识库、本地 Agent 应用等场景。

踩坑记录与最佳实践

❌ Windows 报错：“页面文件太小”

这是典型的虚拟内存不足问题。解决方案：

1. 【控制面板】→【系统】→【高级系统设置】→【性能】→【设置】
2. 【高级】→【虚拟内存】→【更改】
3. 取消自动管理，设为自定义大小：初始 16384 MB，最大 32768 MB
4. 重启生效

建议 SSD 至少预留 50GB 空间。

❌ 缺少optimum>=1.17.0包

导出时报错，解决方法：

pip install "optimum>=1.17.0" onnx onnxruntime-gpu

然后重启 WebUI。

❌ CUDA out of memory

显存溢出是最常见的问题，应对策略如下：

特别是 QLoRA，在 8GB 显存下也能跑 7B 级模型，堪称“穷人之光”。

✅ 经验总结：不同场景下的推荐配置

这套流程下来，你会发现大模型微调并没有想象中那么遥不可及。LLaMA-Factory 通过高度抽象和工程优化，把复杂的底层细节封装起来，让你能专注于数据质量和业务逻辑本身。

下一步你可以尝试：
- 使用 DPO 进行偏好对齐，让模型输出更符合人类意图；
- 构建行业专属问答数据集，打造医疗、法律、金融等专业助手；
- 将微调模型接入 RAG 系统，实现“检索+生成”双轮驱动；
- 部署为 Agent 工具，参与自动化工作流。

🚀 开源地址：https://github.com/hiyouga/LLaMA-Factory
📘 官方文档：https://llamafactory.readthedocs.io

现在就开始吧，属于你的领域专家模型，只差一次微调的距离。