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

在当前AI技术快速迭代的浪潮中，如何让一个通用大模型真正“懂行”，成为某个垂直领域的专家助手？这不再只是科研机构的专属课题，越来越多的开发者和中小团队也渴望拥有定制化的能力。然而，面对复杂的训练流程、繁多的依赖项和晦涩的参数配置，许多人在微调之路上望而却步。

这时候，LLaMA-Factory 的出现就像一座自动化工厂——你只需提供原料（数据）和设计图（目标），它就能帮你高效生产出专属的智能模型产品。更令人兴奋的是，它不仅支持命令行操作，还内置了直观的WebUI界面，真正做到“点几下就能训模型”。

本文将带你从零开始走完一次完整的微调实战：从环境搭建到模型部署，涵盖数据注册、LoRA微调、中断续训、评估验证与API发布等关键环节。我们不会停留在表面操作，还会穿插一些工程实践中容易踩的坑和优化建议，帮助你少走弯路。

---

环境准备：构建稳定可靠的训练基础

任何成功的训练都始于一个干净、隔离且配置正确的运行环境。别小看这一步，很多奇怪的问题其实都源于环境冲突或版本不匹配。

获取项目代码

首先克隆官方仓库：

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

建议定期拉取更新以获取最新功能和修复补丁。如果你打算长期使用，可以考虑 fork 到自己的账号下进行个性化维护。

使用 Conda 创建独立环境

Python 项目的依赖管理是个老难题，Conda 是目前最稳妥的选择之一：

conda create -n llama_factory python=3.10
conda activate llama_factory

选择 Python 3.10 是因为它是多数 PyTorch 生态兼容性最好的版本，避免因版本过高或过低引发意外问题。

安装 PyTorch（根据硬件选型）

这是最关键的一步。请务必根据你的GPU驱动版本选择对应的安装命令。例如，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

苹果M系列芯片用户则无需安装 CUDA 组件，PyTorch 已原生支持 MPS 加速：

pip install torch torchvision torchaudio

无GPU设备也不必灰心，虽然训练速度会慢不少，但用QLoRA+CPU模式依然能跑通小规模实验。

安装项目依赖

进入项目根目录后安装基本依赖：

pip install -r requirements.txt

若需要自动计算 BLEU、ROUGE 等指标，推荐安装扩展包：

pip install -e .[metrics]

这个 -e 参数意味着以“可编辑”方式安装，便于你在本地修改源码时直接生效，适合进阶调试。

启动 WebUI 图形界面

一切就绪后，启动可视化操作面板：

llamafactory-cli webui

默认访问地址为 http://127.0.0.1:7860。如果你想让更多人远程访问，或者希望生成临时公网链接，可以通过环境变量控制行为：

环境变量	作用说明
USE_MODELSCOPE_HUB=1	强制从阿里云 ModelScope 拉取模型，国内下载更稳定
CUDA_VISIBLE_DEVICES=0	指定使用的 GPU 编号（多卡场景下有用）
GRADIO_SHARE=true	Gradio 自动生成一个临时公网访问链接
GRADIO_SERVER_PORT=8080	自定义服务端口

例如：

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

这种方式特别适合在服务器上部署后通过手机或另一台电脑查看训练进度。

---

模型加载：绕开 Hugging Face 的网络瓶颈

Hugging Face 固然是开源模型的事实标准平台，但在国内访问时常受限。幸运的是，LLaMA-Factory 支持通过 ModelScope 下载模型，极大提升了可用性。

以通义千问 Qwen2.5-Coder-0.5B 为例：

👉 ModelScope 模型页

下载完成后解压至本地路径，如：

F:/models/Qwen2.5-Coder-0.5B

在 WebUI 的“Model”标签页中填写该路径即可。此外，勾选 Use ModelScope Hub 选项后，系统会在后台自动处理模型拉取逻辑，省去手动下载的麻烦。

经验提示：建议统一管理模型路径，比如建立 F:/models 目录集中存放所有底座模型，方便后续切换和复用。

---

数据集注册：让框架认识你的“教材”

微调的本质是“教学”。你需要给模型一本清晰的“教材”——也就是结构化的训练数据。

LLaMA-Factory 支持多种主流格式，不同任务类型对应不同的字段要求：

微调类型	推荐格式	必需字段
SFT（监督微调）	alpaca 格式	instruction, input, output
DPO（偏好优化）	sharegpt 格式	chosen, rejected
PPO（强化学习）	多轮对话	history + response

示例：alpaca 格式数据

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

假设我们要训练一个“甄嬛传风格”的对话机器人，可以从 ModelScope 下载 huanhuan-chat 数据集：

👉 huanhuan-chat 数据集

将 huanhuan.json 放入项目下的 data/ 目录：

LLaMA-Factory/
├── data/
│   └── huanhuan.json

然后创建或编辑 data/dataset_info.json 文件，添加如下内容：

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

保存后刷新 WebUI 页面，在“Dataset”下拉框中就能看到 huanhuan_chat 选项了。

实用技巧：点击“Preview Dataset”可以预览前几条样本，确认字段是否正确解析，避免因格式错误导致训练失败。

---

开始微调：参数背后的工程权衡

打开 WebUI → Train 标签页，正式进入训练配置阶段。这里每一个参数都不是孤立存在的，它们之间存在复杂的相互影响关系。

基础设置

参数	值	说明
Model Type	Qwen	底座模型属于通义千问系列
Model Name or Path	F:/models/Qwen2.5-Coder-0.5B	本地模型路径
Finetuning Type	LoRA	推荐初学者使用，节省显存
Quantization Bit	4（可选）	启用 QLoRA 时设为 4 或 8 bit
Training Stage	SFT	监督微调阶段

为什么推荐 LoRA？

传统全参数微调动辄占用几十GB显存，而 LoRA 只训练低秩适配矩阵，通常能将显存消耗降低 70% 以上。对于消费级显卡用户来说，这是唯一可行的选择。

数据与训练参数

参数	建议值	说明
Dataset	huanhuan_chat	注册好的数据集
Dataset Dir	data	数据所在目录
Template	qwen	对应模型提示词模板
Max Length	2048	输入序列最大长度
Batch Size	2 ~ 4	根据显存调整（每卡）
Gradient Accumulation Steps	8	模拟更大 batch 效果
Learning Rate	5e-5	AdamW 默认学习率
Epochs	3.0	防止过拟合
Optimizer	adamw_torch	主流选择
Scheduler	cosine	学习率退火策略

Batch Size 和 Gradient Accumulation 的配合艺术

如果你只有单张 24GB 显卡，batch size 设置为 2 可能已经接近极限。这时可以通过梯度累积来模拟更大的 batch 效果。例如 per_device_train_batch_size=2 + gradient_accumulation_steps=8 ≈ 实际 batch size 16。

但注意：过多的累积步数会导致内存压力增大，并可能影响收敛稳定性。一般建议不超过 16 步。

LoRA 配置要点

参数	建议值	说明
LoRA Rank	8	低秩矩阵维度，越大越强但占显存
LoRA Alpha	16	缩放系数，通常为 rank 的两倍
Dropout	0.0	一般不启用
Target Modules	all	自动识别所有可插入模块（如 q_proj, v_proj）

Rank 和 Alpha 如何选择？

经验法则是：alpha = 2 * rank。常见组合有 (8,16)、(16,32)。更高的 rank 能捕捉更多细节，但也更容易过拟合小数据集。

提示：QLoRA 场景下务必启用 Quantization Bit=4 并设置 bf16=True 或 fp16=True，否则无法发挥量化优势。

输出与日志配置

参数	设置
Output Dir	saves/Qwen2.5-Coder-0.5B/lora/sft_2025-04-10
Save Steps	100
Logging Steps	10
Plot Loss	✅ 勾选

点击 “Start” 即可开始训练！训练过程中可在页面实时查看 loss 曲线变化，判断是否收敛正常。

---

中断续训：应对意外中断的三种策略

训练动辄数小时甚至数天，中途断电或崩溃几乎是不可避免的。好在 LLaMA-Factory 提供了完善的恢复机制。

方法一：WebUI 自动恢复

只要你不更改 Output Dir，重启训练时系统会自动检测是否存在 checkpoint 并从中断处继续。

⚠️ 注意：必须确保 resume_from_checkpoint 未被禁用。

方法二：手动 CLI 命令恢复

在终端中运行以下命令（Windows 下请合并为单行）：

llamafactory-cli train \
    --stage sft \
    --do_train True \
    --model_name_or_path F:/models/Qwen2.5-Coder-0.5B \
    --finetuning_type lora \
    --template qwen \
    --dataset_dir data \
    --dataset huanhuan_chat \
    --cutoff_len 2048 \
    --learning_rate 5e-5 \
    --num_train_epochs 3.0 \
    --per_device_train_batch_size 2 \
    --gradient_accumulation_steps 8 \
    --lr_scheduler_type cosine \
    --output_dir saves/Qwen2.5-Coder-0.5B/lora/sft_2025-04-10 \
    --save_steps 100 \
    --logging_steps 10 \
    --lora_rank 8 \
    --lora_alpha 16 \
    --lora_dropout 0.0 \
    --plot_loss \
    --bf16 True \
    --trust_remote_code True

如果要从特定 checkpoint 恢复，添加参数：

--resume_from_checkpoint saves/Qwen2.5-Coder-0.5B/lora/sft_2025-04-10/checkpoint-100

方法三：YAML 配置文件方式（推荐）

将上述参数写入 YAML 文件（如 train_lora_qwen.yaml）：

stage: sft
do_train: true
model_name_or_path: F:/models/Qwen2.5-Coder-0.5B
finetuning_type: lora
template: qwen
dataset_dir: data
dataset: huanhuan_chat
cutoff_len: 2048
learning_rate: 5e-5
num_train_epochs: 3.0
per_device_train_batch_size: 2
gradient_accumulation_steps: 8
output_dir: saves/Qwen2.5-Coder-0.5B/lora/sft_2025-04-10
save_steps: 100
logging_steps: 10
lora_rank: 8
lora_alpha: 16
lora_dropout: 0.0
plot_loss: true
bf16: true
trust_remote_code: true

然后执行：

llamafactory-cli train train_lora_qwen.yaml

这种方式最大的好处是可版本化管理。你可以把 YAML 文件提交到 Git，实现训练配置的追踪与协作。

---

模型评估：不只是看 loss 下降

训练完成不代表万事大吉，我们必须验证模型是否真的学会了“说话”。

准备评估配置

复制示例文件并修改：

cp examples/train_lora/llama3_lora_eval.yaml eval_qwen.yaml

关键字段：

model_name_or_path: F:/models/Qwen2.5-Coder-0.5B
adapter_name_or_path: saves/Qwen2.5-Coder-0.5B/lora/sft_2025-04-10
eval_dataset: huanhuan_chat
max_samples: 100

执行评估：

llamafactory-cli eval eval_qwen.yaml

输出包括：

• 生成文本样例
• BLEU、ROUGE 分数（如有 metrics 安装）
• 推理延迟统计

进阶建议：结合 OpenCompass 或 lm-eval-harness 进行跨任务综合评测，获得更全面的能力画像。

---

批量推理与结果导出

除了评估，还可以进行 Zero-Shot 推理预测，用于对比原始模型与微调后的效果差异。

llamafactory-cli train \
    --stage sft \
    --do_predict \
    --model_name_or_path F:/models/Qwen2.5-Coder-0.5B \
    --adapter_name_or_path saves/Qwen2.5-Coder-0.5B/lora/sft_2025-04-10 \
    --dataset_dir data \
    --dataset huanhuan_chat \
    --template qwen \
    --finetuning_type lora \
    --output_dir saves/Qwen2.5-Coder-0.5B/lora/predict \
    --per_device_eval_batch_size 1 \
    --max_samples 20 \
    --predict_with_generate

预测结果保存在 generated_predictions.jsonl 中，可用于人工审核或构建测试报告。

---

发布 API 服务：让模型真正可用

训练好的模型只有对外提供服务才有价值。LLaMA-Factory 内置的 API 模块兼容 OpenAI 协议，可无缝接入 LangChain、LlamaIndex 等生态工具。

启动服务：

CUDA_VISIBLE_DEVICES=0 llamafactory-cli api \
    --model_name_or_path F:/models/Qwen2.5-Coder-0.5B \
    --adapter_name_or_path saves/Qwen2.5-Coder-0.5B/lora/sft_2025-04-10 \
    --template qwen \
    --finetuning_type lora \
    --api_port 8000

调用示例：

curl http://127.0.0.1:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
      "model": "qwen",
      "messages": [
        {"role": "user", "content": "皇上，臣妾做不到啊！"}
      ],
      "temperature": 0.7
    }'

响应示例：

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "那就让本宫替你说出来吧……"
    }
  }]
}

支持 streaming、function calling（视模板而定）、多轮对话等特性，满足实际应用需求。

---

模型合并与导出：打造独立可用的成品

若需将 LoRA 权重合并进原始模型，生成一个可以直接加载的完整模型，可通过 Export 功能实现。

WebUI 导出步骤：

1. 进入 Export 标签页
2. 填写：
   - Base Model: F:/models/Qwen2.5-Coder-0.5B
   - Adapter Path: saves/Qwen2.5-Coder-0.5B/lora/sft_2025-04-10
   - Export Directory: merged_models/qwen_huanhuan_v1
3. 勾选 fp16（可选压缩）
4. 点击 “Export”

导出后的模型可用 Transformers 直接加载：

from transformers import AutoTokenizer, AutoModelForCausalLM

tokenizer = AutoTokenizer.from_pretrained("merged_models/qwen_huanhuan_v1")
model = AutoModelForCausalLM.from_pretrained("merged_models/qwen_huanhuan_v1")

若提示缺少 optimum>=1.17.0，请先安装：

bash pip install optimum>=1.17.0

然后重启 WebUI。

---

常见问题与实战避坑指南

❌ 页面文件太小，无法完成操作（Windows）

现象：训练时报错虚拟内存不足。

原因：Windows 默认虚拟内存设置偏低，尤其在处理大模型时容易触发。

解决方案：

1. 打开“高级系统设置” → 性能 → 设置 → 高级 → 虚拟内存 → 更改
2. 取消自动管理，设置初始大小为 32768 MB，最大为 65536 MB
3. 重启生效

❌ 导出模型时报错缺少 optimum

解决方法：

pip install optimum>=1.17.0

安装后重启 WebUI 即可。

❌ 显存溢出（CUDA Out of Memory）

建议措施：

• 使用 QLoRA（quantization_bit=4）
• 降低 per_device_train_batch_size 至 1 或 2
• 启用 gradient_checkpointing
• 减少 cutoff_len（如改为 1024）

这些手段组合使用，往往能让原本无法运行的任务变得可行。

---

LLaMA-Factory 不只是一个工具，它代表了一种理念：让大模型微调变得更简单、更普惠。无论是打造行业知识助手、个性化角色对话机器人，还是构建企业私有问答系统，它都能显著降低技术门槛，提升迭代效率。

下一步你可以尝试：

• 使用 DPO 对齐用户偏好
• 结合 RAG 构建检索增强模型
• 将 API 接入 LangChain 构建智能代理

开源地址：https://github.com/hiyouga/LLaMA-Factory
文档中心：https://llamafactory.readthedocs.io

立即动手，开启你的专属大模型之旅吧！