LLaMA-Factory微调与模型中断续训实战

LLaMA-Factory微调与模型中断续训实战

在大语言模型（LLM）日益渗透到企业服务、智能客服和垂直领域应用的今天，如何高效地对开源模型进行定制化训练，已成为开发者构建专属AI能力的关键一步。面对动辄数十GB的模型参数和复杂的分布式训练流程，一个真正“开箱即用”的微调框架显得尤为珍贵。

LLaMA-Factory正是为此而生——它不只是一套工具链，更像是一个完整的大模型“炼丹工厂”，将从数据准备、模型训练、评估推理到部署导出的全流程封装得井井有条。无论是科研实验还是工业落地，你都可以通过它快速完成LoRA、QLoRA甚至全参数微调，而无需深陷于PyTorch底层细节或HuggingFace Trainer的繁杂配置中。

更令人惊喜的是，它的WebUI界面让整个过程变得像搭积木一样直观：选模型、配参数、点开始，剩下的交给系统自动执行。哪怕你是第一次接触大模型微调，也能在几个小时内跑通全流程。

环境搭建：从零到一的部署实践

克隆项目并进入目录

git clone https://github.com/hiyouga/LLaMA-Factory.git cd LLaMA-Factory

建议使用git lfs安装以确保权重文件完整性，尤其是当你计划加载本地大模型时：

git lfs install

这一步虽小，却能避免后续因缺失bin文件导致的加载失败问题。

创建独立运行环境

conda create -n llama_factory python=3.10 conda activate llama_factory

Python 3.10 是目前兼容性最好的版本，几乎所有主流依赖库都已适配。跳过这一步可能会在安装transformers或accelerate时遇到难以排查的依赖冲突。

安装 PyTorch（CUDA 版本）

根据你的显卡驱动选择合适的CUDA版本。以下是推荐的CUDA 12.1配置：

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

如果你使用的是AMD显卡或仅靠CPU运行，则需参考官方文档安装ROCm支持或纯CPU版本。不过对于实际微调任务来说，至少需要一块具备8GB以上显存的NVIDIA GPU才能流畅运行QLoRA。

安装项目依赖项

pip install -r requirements.txt pip install -e .[metrics]

其中-e .[metrics]表示以可编辑模式安装额外评估指标支持包，便于后期做中文Rouge计算等任务。

⚠️ Windows用户注意：若路径包含空格或中文字符，请务必把项目移至纯英文路径下（如F:\llama_factory），否则可能在加载模型时触发路径解析错误。

验证CLI工具是否正常

llamafactory-cli train -h

如果成功输出帮助信息，说明基础环境已就绪。

启动可视化 WebUI

llamafactory-cli webui

默认访问地址为 http://127.0.0.1:7860。你可以通过设置环境变量来自定义行为：

组合使用示例：

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

这样就能在国内网络环境下快速拉取Qwen、Baichuan等国产模型，并通过Gradio提供的临时域名实现外网访问。

数据集准备：让模型学会“说人话”

LLaMA-Factory 支持多种标准格式的数据集注册机制，极大简化了自定义数据接入流程。

常见微调类型与对应格式

示例：SFT 数据（alpaca 格式）

[ { "instruction": "写一首关于春天的诗", "input": "", "output": "春风拂面花自开，柳绿桃红映山川..." } ]

示例：DPO 数据（sharegpt 格式）

[ { "chosen": [ {"role": "user", "content": "你好"}, {"role": "assistant", "content": "你好！有什么我可以帮你的吗？"} ], "rejected": [ {"role": "user", "content": "你好"}, {"role": "assistant", "content": "嗯。"} ] } ]

这类结构清晰的数据非常适合用于提升模型回复质量。

注册自己的数据集

假设我们有一个名为huanhuan.json的甄嬛体对话数据集，存放于data/huanhuan.json。

第一步：创建 dataset_info.json

在LLaMA-Factory/data/目录下新建或修改该文件：

{ "huanhuan_chat": { "file_name": "huanhuan.json" } }

支持.json,.jsonl,.parquet,.csv等多种格式，无需转换即可直接加载。

第二步：刷新 WebUI 页面

重启或刷新后，在训练界面的“数据集”下拉框中即可看到新增的huanhuan_chat选项。

第三步：预览验证数据格式

点击“预览数据集”按钮，系统会自动读取前几条样本并展示字段内容。这是非常关键的一步——很多初学者忽略格式校验，结果训练中途报错"missing key output"，白白浪费数小时GPU时间。

LoRA 微调实战：低成本打造专属模型

现在我们进入真正的“炼丹”环节。以 Qwen2.5-Coder-0.5B 为例，演示如何用LoRA快速完成一次监督微调。

如何选择底座模型？

优先考虑以下几点：
- 社区活跃度高（便于查文档、找issue）
- 中文支持良好（如 Qwen、ChatGLM、Baichuan）
- 参数量适中（0.5B~7B之间最适合单卡训练）

例如：
-Qwen/Qwen2.5-Coder-0.5B
-LLM-Research/Meta-Llama-3-8B-Instruct
-baichuan-inc/Baichuan2-7B-Base

这些模型均可通过 HuggingFace 或 ModelScope 平台一键缓存至本地。

WebUI 参数配置指南

勾选Plot Loss可在训练结束后查看loss曲线变化趋势。

点击“开始训练”，后台将自动生成完整命令并执行。整个过程无需手动敲任何CLI指令。

断点续训：应对意外中断的必备技能

训练过程中遭遇断电、显存溢出或手动暂停几乎是不可避免的。好在LLaMA-Factory内置了强大的断点恢复机制，让你不必重头再来。

Checkpoint 保存原理

默认每save_steps=100步保存一次checkpoint。即使在第153步中断，系统也会从最近的checkpoint-100恢复，并自动还原优化器状态、学习率调度器进度和全局step计数。

这意味着你不会丢失超过100步的训练成果。

方法一：自动检测最新Checkpoint（推荐）

只需保持--output_dir不变，系统会自动识别是否存在已有checkpoint并从中恢复：

llamafactory-cli train \ --stage sft \ --do_train True \ --model_name_or_path Qwen/Qwen2.5-Coder-0.5B \ --finetuning_type lora \ --template qwen \ --dataset huanhuan_chat \ --dataset_dir data \ --output_dir saves/Qwen2.5-Coder-0.5B/lora/train_2025-04-09-15-04-44 \ --per_device_train_batch_size 2 \ --gradient_accumulation_steps 8 \ --learning_rate 5e-5 \ --num_train_epochs 3.0 \ --max_grad_norm 1.0 \ --save_steps 100 \ --logging_steps 5 \ --plot_loss \ --bf16 True \ --trust_remote_code True

注意：不要添加--resume_from_checkpoint参数，让系统自行判断。

方法二：指定特定Checkpoint路径

如果你想从某个历史节点重新分支训练（比如尝试不同学习率），可以显式指定：

--resume_from_checkpoint saves/Qwen2.5-Coder-0.5B/lora/train_2025-04-09-15-04-44/checkpoint-100

同时建议更改输出目录以区分新旧训练流：

--output_dir saves/Qwen2.5-Coder-0.5B/lora/resume_from_100

这种方式特别适用于A/B测试或多轮迭代调优。

推荐做法：使用 YAML 配置文件管理任务

与其记住冗长的命令行参数，不如将其写入YAML文件，便于复现和版本控制。

创建examples/train_lora/qwen_lora_sft.yaml：

stage: sft do_train: true model_name_or_path: Qwen/Qwen2.5-Coder-0.5B finetuning_type: lora template: qwen dataset: huanhuan_chat dataset_dir: data output_dir: saves/Qwen2.5-Coder-0.5B/lora/train_2025-04-09-15-04-44 per_device_train_batch_size: 2 gradient_accumulation_steps: 8 learning_rate: 5e-5 num_train_epochs: 3.0 max_grad_norm: 1.0 save_steps: 100 logging_steps: 5 plot_loss: true bf16: true trust_remote_code: true

运行只需一行：

llamafactory-cli train examples/train_lora/qwen_lora_sft.yaml

每次修改参数只需编辑YAML文件，再也不用手动拼接命令。

模型评估与批量推理：检验“炼丹”成果

训练完成后，不能只看loss下降了多少，更要验证模型是否真的学会了我们想要的能力。

自动化评估配置

准备一个评估专用YAML文件：qwen_lora_eval.yaml

stage: sft do_predict: true model_name_or_path: Qwen/Qwen2.5-Coder-0.5B adapter_name_or_path: saves/Qwen2.5-Coder-0.5B/lora/train_2025-04-09-15-04-44 template: qwen dataset: identity,test_exam dataset_dir: data output_dir: saves/Qwen2.5-Coder-0.5B/lora/eval_output per_device_eval_batch_size: 1 predict_with_generate: true

执行评估：

llamafactory-cli eval examples/train_lora/qwen_lora_eval.yaml

结果会保存在output_dir下，包含生成文本与真实标签的对比，可用于人工抽查或自动化评分。

小技巧：构建行业专属测试集（如法律问答、医疗术语理解）来精准衡量垂类表现。

批量推理：生成内容或填充知识库

可用于自动写作、客服应答生成、数据库补全等场景。

先安装中文评估依赖：

pip install jieba rouge-chinese nltk

然后执行推理命令：

llamafactory-cli train \ --stage sft \ --do_predict \ --model_name_or_path Qwen/Qwen2.5-Coder-0.5B \ --adapter_name_or_path saves/Qwen2.5-Coder-0.5B/lora/train_2025-04-09-15-04-44 \ --template qwen \ --dataset adgen_local \ --dataset_dir data \ --output_dir saves/Qwen2.5-Coder-0.5B/lora/predict \ --per_device_eval_batch_size 1 \ --max_samples 50 \ --predict_with_generate \ --overwrite_cache \ --overwrite_output_dir

输出为JSONL格式，方便后续导入数据库或做统计分析。

API 服务部署：接入业务系统的桥梁

训练好的模型只有被调用才有价值。LLaMA-Factory 提供了轻量级API模块，可快速封装为REST接口。

启动 API 服务

CUDA_VISIBLE_DEVICES=0 API_PORT=8000 llamafactory-cli api \ --model_name_or_path Qwen/Qwen2.5-Coder-0.5B \ --adapter_name_or_path saves/Qwen2.5-Coder-0.5B/lora/train_2025-04-09-15-04-44 \ --template qwen \ --finetuning_type lora \ --temperature 0.7 \ --top_p 0.9

服务启动后监听http://localhost:8000。

调用示例（curl）

curl -X POST "http://localhost:8000/v1/chat/completions" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen", "messages": [ {"role": "user", "content": "请用甄嬛体写一句问候"} ], "temperature": 0.8 }'

响应示例：

{ "choices": [{ "message": { "role": "assistant", "content": "臣妾给皇上请安了，今日气色可好？" } }] }

这个接口可以直接集成进LangChain、FastAPI、Flask等框架，成为你智能应用的核心引擎。

模型合并与导出：走向独立分发

当微调效果满意后，我们可以将LoRA权重与原始模型合并，生成一个完整的、无需依赖适配器的独立模型。

合并为 HuggingFace 格式

llamafactory-cli export \ --model_name_or_path Qwen/Qwen2.5-Coder-0.5B \ --adapter_name_or_path saves/Qwen2.5-Coder-0.5B/lora/train_2025-04-09-15-04-44 \ --export_dir ./merged_models/qwen_huanhuan_v1 \ --export_device cpu \ --export_legacy_format false

导出后的模型可在任何支持Transformers的环境中加载，无需额外配置。

量化导出：适应低资源设备

为了便于部署在笔记本或边缘服务器上，支持导出为GGUF、GPTQ、AWQ等低比特格式。

示例：导出为 4-bit GPTQ 模型

llamafactory-cli export \ --model_name_or_path Qwen/Qwen2.5-Coder-0.5B \ --adapter_name_or_path saves/Qwen2.5-Coder-0.5B/lora/train_2025-04-09-15-04-44 \ --export_dir ./quantized_models/qwen_4bit \ --export_quantization_bit 4 \ --export_quantization_dataset alpaca_en \ --export_quantization_method gptq

这种量化模型通常体积缩小60%以上，推理速度也更快，非常适合移动端或嵌入式场景。

常见问题与避坑指南

❌ 页面提示“页面文件太小，无法完成操作”

原因：Windows虚拟内存不足，尤其在加载大模型时常触发。

解决方案：
1. 进入【控制面板】→【系统】→【高级系统设置】→【性能】→【设置】→【高级】→【虚拟内存】
2. 取消“自动管理”，选择“自定义大小”
3. 初始大小设为16384 MB，最大设为32768 MB
4. 重启生效

必要时可扩展至64GB。

❌ 导出时报错No package metadata was found for optimum>=1.17.0

典型错误日志：

PackageNotFoundError: No package metadata was found for The 'optimum>=1.17.0' distribution was not found... To fix: run `pip install optimum>=1.17.0`

解决方法：

pip install "optimum>=1.17.0" accelerate sentencepiece datasets

然后重启WebUI进程再尝试导出，否则仍可能失败。

❌ 训练中途崩溃，loss异常飙升

常见原因包括：
- 学习率过高
- 数据中存在超长序列（超过cutoff_len）
- 显存不足导致batch被丢弃

应对策略：
- 降低学习率至1e-5 ~ 3e-5
- 缩短cutoff_len至1024
- 减小per_device_train_batch_size或增加梯度累积步数

有时候一条长达万字的日志文本就会让整个batch归零，因此建议在数据预处理阶段就做过滤。

✅ 实战经验总结：不同场景下的最佳配置

特别是对于仅有单张RTX 3060（12GB）的开发者，QLoRA几乎是唯一可行的选择。

如今，大模型不再是科技巨头的专属玩具。借助像LLaMA-Factory这样的开源利器，每一个开发者都能拥有属于自己的“私人AI”。从环境搭建、数据注册、LoRA微调，到断点续训、评估推理、API部署乃至模型合并导出，这套工具链几乎覆盖了所有关键环节。

更重要的是，它的设计理念始终围绕“降低门槛”展开——无论是命令行还是WebUI，都在试图抹平技术鸿沟。这让即使是非深度学习背景的工程师，也能在几天内完成一次完整的模型定制流程。

如果你正打算打造企业知识助手、行业垂类模型，或是参与学术研究，那么不妨把LLaMA-Factory当作你的第一把“炼丹炉”。代码世界里最迷人的地方就在于：只要你愿意动手，总能看到火焰燃起的那一刻。

项目地址：https://github.com/hiyouga/LLaMA-Factory
文档地址：https://llamafactory.readthedocs.io