LLaMA-Factory微调与模型续训实战指南

LLaMA-Factory微调与模型续训实战指南

在大模型技术飞速发展的今天，越来越多的开发者和企业希望将开源模型快速适配到特定领域——无论是打造专属客服机器人、构建专业代码助手，还是训练具备行业知识的智能顾问。然而，面对复杂的训练流程、繁杂的依赖管理和不一致的数据格式，许多团队往往“望而却步”。

有没有一种方式，能让微调这件事变得像搭积木一样简单？

LLaMA-Factory正是为此而生。它不是一个简单的脚本集合，而是一个真正意义上的一站式大模型微调框架：从数据预处理、高效微调（LoRA/QLoRA）、可视化训练监控，到模型评估、批量推理乃至API服务部署，全部打通。更重要的是，它对主流架构如 Qwen、LLaMA、ChatGLM、Baichuan 等实现了统一接口支持，极大降低了使用门槛。

更惊艳的是，它内置了WebUI 可视化界面，让你无需写一行代码就能完成整个微调流程；同时又保留完整的 CLI 和 YAML 配置能力，满足高级用户的精细化控制需求。无论你是刚入门的新手，还是追求极致性能的工程师，都能在这里找到适合自己的工作流。

本文将以一次完整的实战为例，带你走通从环境搭建、数据注册、LoRA微调、中断恢复、模型评估到最终API部署的全链路流程，并穿插关键技巧与避坑指南，助你真正实现“开箱即用”的专业级模型定制。

环境准备：让安装不再成为第一道坎

很多人第一次接触这类项目时，最容易卡在环境配置上。别担心，我们一步步来，确保每一步都稳扎稳打。

首先克隆项目仓库。如果你在国内，建议使用 Gitee 镜像加速下载：

git clone https://gitee.com/mirrors_llama_factory/LLaMA-Factory.git cd LLaMA-Factory

接下来创建独立的 Conda 虚拟环境，推荐 Python 3.10，兼容性最好：

conda create -n llama_factory python=3.10 conda activate llama_factory

PyTorch 的安装要根据你的硬件选择。如果有 NVIDIA 显卡，直接装带 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

没有 GPU 的话也别灰心，CPU 版本同样可用，只是训练速度会慢不少：

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

依赖安装很简单：

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

如果提示路径错误，请确认当前目录是否正确，或改用绝对路径执行。

一切就绪后，启动 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 双源加载，这意味着你可以自由选择国内外平台上的任意兼容模型。

比如我们要用一个轻量级代码模型做测试，可以选择通义千问推出的Qwen2.5-Coder-0.5B。通过 ModelScope 下载非常方便：

from modelscope import snapshot_download model_dir = snapshot_download('qwen/Qwen2.5-Coder-0.5B') print(model_dir) # 输出本地路径

下载完成后，路径可以直接填入 WebUI 的model_name_or_path字段，也可以在 CLI 命令中引用。框架会自动识别并加载 tokenizer 和模型结构。

这里有个小建议：对于经常使用的模型，建议集中存放在一个固定目录（如./models/），便于管理和复用。

数据集注册：让私有数据轻松接入

真正的价值往往藏在私有数据里。LLaMA-Factory 提供了一套简洁的数据集注册机制，只需在data/目录下维护一个dataset_info.json文件即可。

假设你手里有一份《甄嬛传》角色对话数据huanhuan.json，想用来训练一个古风聊天机器人。步骤如下：

1. 将文件放到LLaMA-Factory/data/huanhuan.json
2. 编辑或创建data/dataset_info.json，添加条目：

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

3. 重启 WebUI，刷新后就能在“数据集”下拉框中看到huanhuan_chat

就这么简单！而且它支持多种格式：.json,.jsonl,.csv,.parquet，甚至可以指定多个文件合并训练：

"file_name": ["d1.json", "d2.json"]

至于数据格式，SFT（监督微调）推荐使用 Alpaca 格式：

[ { "instruction": "写一个Python函数计算斐波那契数列", "input": "", "output": "def fib(n):\n if n <= 1:\n return n\n return fib(n-1) + fib(n-2)" } ]

每个样本包含指令、输入（可为空）、输出三部分，清晰明了。这种结构非常适合任务导向的微调场景。

LoRA微调实战：用消费级显卡跑出专业效果

现在进入重头戏——正式开始训练。我们以Qwen2.5-Coder-0.5B+huanhuan_chat为例，演示如何用 LoRA 实现高效微调。

为什么选 LoRA？因为它只训练少量新增参数（通常不到原模型的1%），显存占用极低，一张 16GB 显存的消费级卡就能轻松驾驭。

在 WebUI 中填写以下关键参数：

点击“开始训练”前，不妨先看看“命令预览”，你会得到一段完整的 CLI 命令。这不仅有助于理解底层逻辑，也为后续自动化脚本提供了模板：

llamafactory-cli train \ --stage sft \ --do_train True \ --model_name_or_path Qwen/Qwen2.5-Coder-0.5B \ --preprocessing_num_workers 16 \ --finetuning_type lora \ --template qwen \ --flash_attn auto \ --dataset_dir data \ --dataset huanhuan_chat \ --cutoff_len 2048 \ --learning_rate 5e-05 \ --num_train_epochs 3.0 \ --max_samples 100000 \ --per_device_train_batch_size 2 \ --gradient_accumulation_steps 8 \ --lr_scheduler_type cosine \ --max_grad_norm 1.0 \ --logging_steps 5 \ --save_steps 100 \ --warmup_steps 0 \ --packing False \ --report_to none \ --output_dir saves/Qwen2.5-Coder-0.5B/lora/train_2025-04-09-15-04-44 \ --bf16 True \ --plot_loss True \ --trust_remote_code True \ --ddp_timeout 180000000 \ --include_num_input_tokens_seen True \ --optim adamw_torch \ --lora_rank 8 \ --lora_alpha 16 \ --lora_dropout 0.1 \ --lora_target all

Windows 用户注意：把\换行符去掉，合并成单行执行。

训练过程中，WebUI 会实时显示 loss 曲线、学习率变化、显存占用等信息，一目了然。

中断续训：再也不怕意外断电

训练动辄几小时甚至几天，最怕中途崩溃。好在 LLaMA-Factory 完美支持断点续训。

只要保持--output_dir不变，再次运行相同命令时，系统会自动检测是否存在checkpoint-*目录，并从中断处继续训练：

llamafactory-cli train \ --output_dir saves/Qwen2.5-Coder-0.5B/lora/train_2025-04-09-15-04-44 \ # 其他参数同上

前提是该目录下已有保存的检查点（如checkpoint-100）。这是最常用也是最安全的方式。

如果你只想从某个特定 checkpoint 恢复，可以手动指定：

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

但要注意：一旦更换数据集或大幅调整超参，建议新建 output_dir，避免历史状态干扰新训练过程。

更进一步，你可以将这些参数保存为 YAML 文件，比如train_lora_qwen.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-05 num_train_epochs: 3.0 max_grad_norm: 1.0 logging_steps: 5 save_steps: 100 lora_rank: 8 lora_alpha: 16 lora_dropout: 0.1 bf16: true plot_loss: true

之后只需一条命令即可复现训练：

llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml

强烈建议按任务分类管理 YAML 文件，长期积累下来就是团队的知识资产。

模型评估：用数据说话

训练完不能只看 loss 下降，还得知道模型到底提升了多少。LLaMA-Factory 提供了内置的eval模块，支持自动化性能测试。

推荐做法是使用一个通用基准模型作为“裁判”，例如 Meta-Llama-3.1-8B-Instruct。先把它下载下来：

from modelscope import snapshot_download snapshot_download('LLM-Research/Meta-Llama-3.1-8B-Instruct', cache_dir='./models')

然后编写评估配置文件llama3_lora_eval.yaml：

stage: sft do_predict: true model_name_or_path: ./models/LLM-Research/Meta-Llama-3.1-8B-Instruct adapter_name_or_path: saves/Qwen2.5-Coder-0.5B/lora/train_2025-04-09-15-04-44 template: llama3 dataset: alpaca_gpt4_zh dataset_dir: data output_dir: ./eval_results per_device_eval_batch_size: 1 cutoff_len: 1024 max_samples: 100 predict_with_generate: true

执行评估：

llamafactory-cli eval examples/train_lora/llama3_lora_eval.yaml

结果会生成在eval_results/generated_predictions.jsonl，可用于计算 BLEU、ROUGE、Accuracy 等指标。

当然，更全面的评测还可以结合 OpenCompass 或 lm-evaluation-harness，进行跨维度的能力打分。

推理与部署：让模型真正用起来

模型训练出来是为了服务业务的。LLaMA-Factory 提供了两种主要输出方式：批量推理和 API 服务。

批量推理：用于测试集分析或 A/B 测试

适用于生成大量预测结果进行人工审核或自动评分：

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

输出文件generated_predictions.jsonl包含原始 input 和 model output，方便后续处理。

API 服务：对接 LangChain/AutoGen 生态

这才是生产级玩法。启动一个 OpenAI 兼容的 RESTful 接口：

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

启动后，任何支持 OpenAI SDK 的工具都可以无缝调用：

from openai import OpenAI client = OpenAI(base_url="http://localhost:8000/v1", api_key="none") response = client.chat.completions.create( model="qwen2.5-coder-lora", messages=[{"role": "user", "content": "写一个快排函数"}] ) print(response.choices[0].message.content)

支持 streaming、function calling、并行采样等特性，完全可以替代官方 API 做本地化部署。

模型合并：产出独立可用的成品

训练结束后的 LoRA 权重只是一个“补丁”，要想独立分发或上线，需要将其合并回原模型。

在 WebUI 的「导出」页面填写：
- 模型路径：原模型（如Qwen/Qwen2.5-Coder-0.5B）
- 适配器路径：LoRA 输出目录
- 输出路径：新模型存储位置
- 导出精度：可选float16或int4量化

点击导出即可生成完整模型。

更推荐用 CLI 脚本化操作：

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/qwen2.5-coder-huanhuan \ --export_quantization_bit 4 \ --export_quantization_method bitsandbytes

导出后的模型可以用标准transformers方式加载：

from transformers import AutoModelForCausalLM, AutoTokenizer tokenizer = AutoTokenizer.from_pretrained("./merged_models/qwen2.5-coder-huanhuan") model = AutoModelForCausalLM.from_pretrained("./merged_models/qwen2.5-coder-huanhuan")

此时模型已完全独立，无需额外依赖 LoRA 组件，可直接部署至生产环境。

避坑指南：那些你可能会遇到的问题

❌ 虚拟内存不足（Windows）

现象：训练时报错“页面文件太小”

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

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

❌ 缺少optimum>=1.17.0

错误信息表明导出功能依赖未安装：

pip install optimum>=1.17.0

装完后重启 WebUI 即可。

❌ CUDA Out of Memory

常见于 batch size 过大或序列过长。

解决策略：
- 降低per_device_train_batch_size至 1
- 启用gradient_checkpointing
- 改用qlora+ int4 量化
- 添加--fp16或--bf16减少显存占用

✅ 最佳实践总结

LLaMA-Factory 的强大之处，不在于它实现了多么前沿的技术，而在于它把复杂留给了自己，把简单交给了用户。从零开始搭建一套可复现、可维护、可交付的大模型微调 pipeline，如今只需要几个命令、几次点击。

无论你想打造垂直领域的知识引擎、个性化的对话伙伴，还是高效的代码生成器，这套工具链都能帮你把想法快速变成现实。技术的边界正在不断扩展，而真正决定成败的，往往是那个敢于动手的人。

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

现在，就差你按下回车键了。