LLaMA-Factory中LoRA微调实战指南

在大模型落地日益迫切的今天，如何以较低成本将通用语言模型适配到垂直领域，成为开发者面临的核心挑战之一。全参数微调动辄需要数百GB显存，对大多数团队而言并不现实。而LoRA（Low-Rank Adaptation） 技术的出现，让在单台多卡服务器上完成8B甚至70B级别模型的高效定制成为可能。

本文将以医疗问答场景为例，带你完整走通使用 LLaMA-Factory 框架进行 LoRA 微调的全流程——从环境搭建、数据准备、训练配置，到多卡训练启动与推理部署。全程无需编写核心训练代码，真正实现“低代码化”的专业级模型定制。

---

项目获取与本地初始化

一切始于仓库克隆。LLaMA-Factory 作为当前最活跃的大模型微调框架之一，提供了统一接口支持 LLaMA、Qwen、ChatGLM 等主流架构，并集成了全参微调、LoRA、QLoRA 等多种高效训练策略。

执行以下命令拉取项目：

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

--depth 1 启用浅层克隆，仅下载最新提交记录，可显著加快速度。若你后续不打算参与开发或切换分支，可以安全删除 .git 目录以节省空间：

rm -rf .git

这一步虽小，但在资源受限的开发环境中能有效减少干扰。

---

构建稳定运行环境：版本匹配的艺术

深度学习项目的失败，十有八九源于依赖冲突。LLaMA-Factory 对 PyTorch 和 CUDA 的版本极为敏感，稍有不慎就会导致 CUDA illegal memory access 或 missing kernel 错误。

以下是经过多次实测验证的黄金组合：

组件	推荐版本
Python	3.10
CUDA	12.1
PyTorch	2.3.0+cu121
Transformers	4.43.4
vLLM	0.4.3

创建独立虚拟环境

建议使用 Conda 隔离依赖：

conda create -n lora-factory python=3.10
conda activate lora-factory

安装 PyTorch：推荐离线方式

网络波动常导致 pip 安装中断。更稳妥的方式是从 PyTorch 官方镜像 下载对应 whl 文件后本地安装：

pip install torch==2.3.0+cu121 torchvision==0.18.0+cu121 torchaudio==2.3.0+cu121 --index-url https://download.pytorch.org/whl/cu121

补充关键依赖

接下来安装框架所需的核心库：

pip install transformers==4.43.4
pip install vllm==0.4.3
pip install datasets accelerate peft gradio matplotlib rouge_score tensorboard

其中：
- vllm 是高性能推理引擎，支持 PagedAttention，大幅提升服务吞吐；
- gradio 提供 WebUI 支持，非技术人员也能参与调试；
- accelerate 和 peft 分别负责分布式训练与参数高效微调底层逻辑。

安装主框架

进入项目根目录，执行可编辑安装：

pip install -e ".[torch,metrics]"

-e 模式允许你在不重新安装的情况下修改源码，非常适合调试自定义功能。附加的 [torch,metrics] 会自动补全分布式训练和评估指标所需的组件。

---

Hugging Face 登录与模型访问

绝大多数开源大模型托管于 Hugging Face，需认证 Token 才能下载。如果你身处国内且无代理，直接访问常会超时。

正常登录流程（海外环境）

huggingface-cli login

输入你的 Access Token 即可。注意权限选择 read 足够，无需 write。

国内用户解决方案：HF Mirror 加速

为避免每次下载都卡住，可在 shell 配置中设置镜像源：

echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
source ~/.bashrc

此后所有通过 huggingface_hub 的请求都会自动走国内节点，加载速度提升数倍。这是实际工程中非常实用的小技巧。

---

自定义数据集构建：以医疗问答为例

我们希望微调一个能回答常见医学问题的助手。LLaMA-Factory 使用标准 SFT（监督式微调）格式，要求数据遵循 instruction/input/output 三元组结构。

数据文件组织

创建目录结构：

data/
├── dataset_info.json        # 全局注册表
└── medical_qa.json          # 实际训练数据

编写 data/medical_qa.json：

[
  {
    "instruction": "请根据医学知识回答以下问题。",
    "input": "高血压患者日常饮食应注意什么？",
    "output": "高血压患者应低盐饮食，每日食盐摄入量控制在5克以内；多吃富含钾的食物如香蕉、土豆；限制饮酒，避免高脂肪食物，保持均衡膳食。"
  },
  {
    "instruction": "请根据医学知识回答以下问题。",
    "input": "糖尿病的典型症状有哪些？",
    "output": "糖尿病典型三多一少症状：多饮、多食、多尿、体重减少。部分患者还可出现视力模糊、皮肤瘙痒、伤口愈合慢等症状。"
  }
]

注意：instruction 字段用于构造 prompt 模板，input 是具体问题，output 是期望回复。三者缺一不可。

注册数据集

编辑 data/dataset_info.json，添加条目：

{
  "medical_qa": {
    "file_name": "medical_qa.json"
  }
}

这里的 "medical_qa" 将在 YAML 配置中作为 dataset 参数引用。这是一种解耦设计，便于后期复用多个数据集。

---

编写 LoRA 训练配置：YAML 驱动的灵活性

LLaMA-Factory 使用 YAML 文件定义整个训练流水线。我们在 examples/train_lora/ 下新建 medical_lora_sft.yaml：

# 模型基础配置
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: null
cache_dir: cache/
use_fast_tokenizer: false

# 微调方法设置
finetuning_type: lora
lora_target: all
lora_rank: 64
lora_alpha: 128
lora_dropout: 0.1
additional_target: []

# 训练任务定义
stage: sft
do_train: true
dataset: medical_qa
template: llama3
max_source_length: 512
max_target_length: 512
cutoff_len: 1024
max_samples: 1000
overwrite_cache: true
preprocessing_num_workers: 8

# 训练超参
per_device_train_batch_size: 2
gradient_accumulation_steps: 4
optim: adamw_torch
learning_rate: 2e-4
num_train_epochs: 3
max_grad_norm: 1.0
lr_scheduler_type: cosine
warmup_ratio: 0.1

# 输出控制
output_dir: saves/llama3-8b-lora-medical/
logging_steps: 10
save_steps: 500
save_total_limit: 2
plot_loss: true
overwrite_output_dir: true

几个关键点值得强调：

• lora_target: all 表示对所有线性层注入 LoRA 模块，适合通用任务。若想节省显存，可改为 q_proj,v_proj 等关键注意力层。
• per_device_train_batch_size × gradient_accumulation_steps = effective batch size。例如 2×4=8，相当于全局 batch size 为 8。
• plot_loss: true 会在训练结束后生成损失曲线图，位于输出目录中，方便直观判断收敛情况。

这种声明式配置极大降低了使用门槛，同时也保留了足够的控制粒度。

---

启动训练：多卡并行实战

确保 GPU 可用后，执行训练命令：

CUDA_VISIBLE_DEVICES=0,1 llamafactory-cli train examples/train_lora/medical_lora_sft.yaml

框架会自动启用 Accelerate 进行数据并行训练。终端将实时输出 loss、学习率、epoch 进度等信息。

训练完成后，模型权重保存在 saves/llama3-8b-lora-medical/ 中，核心文件包括：
- adapter_model.bin：LoRA 适配器权重（通常几十到几百MB）
- training_args.bin：训练参数快照
- README.md：自动生成的模型卡片

若遇到 OOM（Out of Memory），优先尝试：
- 减小 per_device_train_batch_size
- 改用 QLoRA：将 finetuning_type 设为 qlora，并添加 quantization_bit: 4

QLoRA 能进一步将显存占用降低 60% 以上，特别适合资源紧张的场景。

---

推理部署：两种模式的选择

训练好的模型需要投入应用。LLaMA-Factory 提供两种主流推理路径。

方式一：启动 OpenAI 兼容 API 服务

适用于系统集成。先创建 examples/inference/medical_inference.yaml：

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b-lora-medical/
template: llama3
infer_backend: vllm
vllm_enforce_eager: true
finetuning_type: lora

启动服务：

CUDA_VISIBLE_DEVICES=0 API_PORT=8000 llamafactory-cli api examples/inference/medical_inference.yaml

随后可通过 OpenAI SDK 调用：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="EMPTY"
)

response = client.chat.completions.create(
    model="Meta-Llama-3-8B-Instruct",
    messages=[
        {"role": "user", "content": "冠心病的主要危险因素有哪些？"}
    ],
    temperature=0.7,
    max_tokens=512
)

print(response.choices[0].message.content)

这种方式兼容性强，易于嵌入现有 AI 应用架构，但目前 vLLM + LoRA 在多卡推理上的支持仍有局限。

方式二：批量预测（推荐用于评估）

当你需要对大量样本进行测试或生成报告时，直接预测更高效。

准备测试集

创建 data/eval_medical.json：

[
  {
    "instruction": "请根据医学知识回答以下问题。",
    "input": "什么是脑卒中？如何预防？"
  }
]

注册至 dataset_info.json：

"eval_medical": {
  "file_name": "eval_medical.json"
}

编写预测配置 predict_medical.yaml

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b-lora-medical/
template: llama3

stage: sft
do_predict: true
finetuning_type: lora

dataset: eval_medical
max_samples: 100
cutoff_len: 1024
predict_with_generate: true

output_dir: saves/llama3-8b-lora-medical/predict/
overwrite_output_dir: true

执行预测

CUDA_VISIBLE_DEVICES=0,1 llamafactory-cli train examples/train_lora/predict_medical.yaml

结果将保存为 generated_predictions.jsonl，每行一条生成文本，便于后续分析或评测。

---

（可选）WebUI 图形界面：零代码操作体验

对于不想碰命令行的用户，LLaMA-Factory 内置了基于 Gradio 的可视化界面：

CUDA_VISIBLE_DEVICES=0 python src/webui.py

访问 http://localhost:7860 即可看到完整面板，支持：
- 模型选择与量化选项
- LoRA 参数交互式配置
- 数据集上传与预览
- 实时训练日志查看
- 在线对话测试

虽然生产环境仍建议脚本化自动化，但 WebUI 极大降低了快速验证想法的成本，尤其适合产品经理或临床专家参与原型迭代。

---

实践建议与避坑指南

结合工程经验，总结出以下几点最佳实践：

• 环境稳定性优先：Python 3.10 + PyTorch 2.3.0 + CUDA 12.1 是目前最稳定的组合，避免盲目追新。
• 数据格式必须规范：严格遵循 instruction/input/output 结构，否则预处理阶段会报错。
• LoRA 初始配置建议设为 all：首次训练不必过度优化目标模块，待效果 baseline 建立后再精简。
• 显存不足时先调 batch size：比修改 rank 更直接有效；若仍不行，果断转向 QLoRA。
• 推理模式按需选择：小规模交互用 API，大批量输出用 direct predict。
• WebUI 适合快速验证：但不要用于生产部署，缺乏监控和容错机制。

---

写在最后

LLaMA-Factory 不只是一个工具，它代表了一种“工业化”微调的新范式：通过标准化流程、模块化解耦和多模式交互，将原本复杂的模型定制变得可复制、可维护。

借助 LoRA 等高效技术，我们不再需要动用集群就能完成高质量领域适配。无论是构建金融顾问、法律助手，还是医疗问答系统，这套方法论都能快速落地。

现在就动手试试吧，你的第一个专业化大模型也许只需一次 llamafactory-cli train。

GitHub 地址：https://github.com/hiyouga/LLaMA-Factory