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
环境变量说明
USE_MODELSCOPE_HUB=1使用魔搭（ModelScope）作为模型源，国内下载更快
CUDA_VISIBLE_DEVICES=0指定使用的 GPU 编号
GRADIO_SHARE=true开启公网分享链接（Gradio 的 share 功能）
GRADIO_SERVER_PORT=8080自定义服务端口

值得一提的是，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"
  }
}
  1. 刷新 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 是目前最主流的高效微调技术之一，仅需更新低秩矩阵，显存占用极低，适合消费级显卡。

关键参数设置

参数推荐值说明
模型路径./models/qwen-1.8b-chat必须确保路径正确
对话模板qwen与模型类型严格匹配
微调方法LoRA显存友好，适合 16GB 以下显卡
批大小per_device_train_batch_size=2根据显存调整
梯度累积gradient_accumulation_steps=8等效 batch size 达 16
学习率5e-5常规推荐范围 1e-5 ~ 5e-5
Epoch 数3.0防止过拟合
最大长度cutoff_len=1024控制上下文长度
LoRA Rank8低秩维度，影响表达能力
LoRA Alpha16一般为 rank 的两倍
输出目录saves/qwen/lora/sft/权重保存路径

启动训练（命令行方式）

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 指标，方便你横向对比不同训练策略的效果。

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

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

批量推理与 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

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

方法操作
降低 Batch Sizeper_device_train_batch_size=1
启用梯度检查点添加 --gradient_checkpointing True
使用 QLoRA--quantization_bit 4 + --finetuning_type lora
减少序列长度--cutoff_len 512

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

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

场景推荐方案
显卡 ≤ 16GBLoRA + fp16
显卡 ≤ 8GBQLoRA（4-bit）
多卡训练添加 --ddp_timeout 180000000 防超时
中文任务使用 zh_toolkit 插件提升分词质量
生产部署合并权重后转为 GGUF/GPTQ 格式

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

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

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

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

# LLaMA-Factory
Logo
码道开发者社区

码道开发者社区，聚焦华为云码道 CodeArts 代码智能体，沉淀 Agent、Skill、鸿蒙开发实战内容，供开发者查阅资料、交流技术、分享工程实践

更多推荐

cover

状态丢失排障：Claude 持久记忆的跨会话局限与知芽 Notebook Skill 单元记忆如何沉淀可复用知识资产

avatar 码道开发者社区
cover

AI外贸建站06｜给网站穿上“公司制服”：配色、字体、logo和favicon，Codex一次应用全站

avatar 码道开发者社区
cover

Workbuddy中运行NetSuite MCP

avatar 码道开发者社区