Llama-Factory LoRA微调实战指南

在大模型时代，我们不再只是使用通用语言模型来回答问题或写文章。越来越多的场景要求模型具备特定领域的知识表达能力——比如医疗问答、法律文书生成、金融摘要提取等。全参数微调虽然效果好，但动辄上百GB显存的需求让大多数开发者望而却步。

于是，轻量级微调方法如 LoRA（Low-Rank Adaptation） 成为了主流选择：它通过仅训练低秩矩阵的方式，在几乎不损失性能的前提下，将可训练参数减少90%以上。然而，从环境配置到数据处理、再到训练与部署，整个流程依然繁琐且容易踩坑。

这时候，一个真正开箱即用的工具就显得尤为重要。Llama-Factory 正是为此而生——它不仅支持 LLaMA、Qwen、Baichuan、ChatGLM 等数十种主流架构，还统一了训练、评估和推理接口，并提供了命令行与 WebUI 双模式操作。本文将带你完整走通一次基于 Llama-Factory 的 LoRA 微调实战，涵盖环境搭建、数据准备、训练启动到推理部署全流程。

---

项目初始化与环境配置

首先克隆仓库：

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

--depth 1 能显著加快下载速度。如果你不需要后续同步上游更新，可以删除 .git 目录节省空间：

rm -rf .git

建议使用 Conda 创建独立环境以避免依赖冲突。以下是经过验证的稳定组合：

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

创建并激活环境：

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

由于网络限制，直接 pip install torch 常常失败。推荐前往 PyTorch 官方下载页 下载对应 .whl 文件进行本地安装。例如，在 Linux + CUDA 12.1 环境下：

pip install torch-2.3.0+cu121-cp310-cp310-linux_x86_64.whl
pip install torchaudio-2.3.0+cu121-cp310-cp310-linux_x86_64.whl
pip install torchvision-0.18.0+cu121-cp310-cp310-linux_x86_64.whl

接着安装其他必要依赖：

pip install transformers==4.43.4
pip install vllm==0.4.3
pip install datasets accelerate peft gradio einops

最后执行可编辑安装，便于调试修改源码：

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

安装完成后可通过以下命令验证是否成功：

llamafactory-cli -h

如果看到帮助信息输出，则说明安装无误。

---

HuggingFace 登录与加速访问

多数大模型托管于 HuggingFace 平台，需登录账户获取访问权限。

先升级 huggingface_hub 工具至最新版：

pip install --upgrade huggingface_hub

然后前往 HuggingFace Settings → Access Tokens，生成一个具有 read 权限的 Token。执行登录命令：

huggingface-cli login

输入你的 Token 完成认证。

若无法科学上网，建议切换为国内镜像站以避免超时：

export HF_ENDPOINT=https://hf-mirror.com

将其写入 shell 配置文件中以便持久生效：

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

此后所有模型拉取都会自动走镜像通道，下载速度提升明显。

---

自定义数据集构建与注册

Llama-Factory 支持标准 SFT（监督式微调）任务格式，核心是 "instruction", "input", "output" 三元组结构。

典型的项目目录如下：

LLaMA-Factory/
├── data/
│   ├── dataset_info.json
│   └── news_summary.json
├── examples/
│   ├── train_lora/
│   │   └── news_summary_lora.yaml
│   ├── inference/
│   │   └── news_summary_api.yaml
└── saves/
    └── llama3-8b-lora-news-summary/

假设我们要微调一个“新闻摘要生成”任务，示例数据如下：

[
  {
    "instruction": "请根据以下新闻内容生成一段简洁的摘要。",
    "input": "近日，我国自主研发的新一代高速列车‘复兴号’智能动车组在京沪高铁实现常态化运营……",
    "output": "我国‘复兴号’智能动车组在京沪高铁实现常态化运营，具备全自动驾驶能力……"
  },
  {
    "instruction": "请根据以下新闻内容生成一段简洁的摘要。",
    "input": "国家统计局发布数据显示，2024年上半年全国GDP同比增长5.3%……",
    "output": "2024年上半年我国GDP同比增长5.3%，经济持续回升向好……"
  }
]

保存为 ./data/news_summary.json。

接下来在 data/dataset_info.json 中注册该数据集：

"news_summary": {
  "file_name": "news_summary.json"
}

注意：这里的 key 名称（如 news_summary）将在后续 YAML 配置中作为 dataset 参数引用，务必保持一致。

---

LoRA 微调配置与训练启动

进入 examples/train_lora/ 目录，新建 news_summary_lora.yaml：

### model
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path:
cache_dir:
use_fast_tokenizer: true

### method
finetuning_type: lora
lora_target: all
lora_rank: 64
lora_alpha: 128
lora_dropout: 0.05
trainable: "all"
modules_to_save: []
additional_target: []

### training
stage: sft
do_train: true
dataset: news_summary
template: llama3
cutoff_len: 1024
buffer_size: 10000
max_samples: 10000
overwrite_cache: true
preprocessing_num_workers: 16

### output
output_dir: saves/llama3-8b-lora-news-summary/
logging_steps: 10
save_steps: 500
eval_steps: 500
evaluation_strategy: steps
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
max_grad_norm: 1.0
num_train_epochs: 3
optim: adamw_torch
learning_rate: 2e-4
warmup_steps: 100
lr_scheduler_type: cosine
fp16: true
bf16: false
ddp_timeout: 180000000
save_total_limit: 2
load_best_model_at_end: true
compute_dtype: fp16

### logging & distributed
dataloader_num_workers: 0
ddp_find_unused_parameters: false

几个关键参数值得特别说明：

• lora_target: all 表示对所有线性层注入 LoRA 模块；你也可以精细控制为 q_proj,v_proj 等。
• lora_rank: 64 是低秩矩阵的维度，越大拟合能力越强，但也更耗显存。实践中 8~64 是常见范围。
• lora_alpha: 128 是缩放因子，通常设为 rank 的两倍，用于维持原始激活幅度。
• cutoff_len: 1024 控制最大上下文长度，影响显存占用和训练效率。
• gradient_accumulation_steps: 8 配合 per_device_train_batch_size: 1 实现全局 batch size = 8，适合多卡小批量场景。
• fp16: true 启用混合精度训练，既能节省显存又能加速计算。

开始训练：

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

如果是单卡，改为 CUDA_VISIBLE_DEVICES=0 即可。训练过程中会实时输出 loss 曲线、学习率变化等信息，最终模型权重保存在 saves/llama3-8b-lora-news-summary/。

---

多样化推理方式：API服务与批量预测

启动 OpenAI 兼容 API 服务

适用于在线服务部署。在 examples/inference/ 下创建 news_summary_api.yaml：

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b-lora-news-summary/
template: llama3
infer_backend: vllm
vllm_enforce_eager: true
dtype: half
gpu_memory_utilization: 0.9
max_model_len: 2048
tensor_parallel_size: 2

其中 tensor_parallel_size: 2 表示使用两张 GPU 进行张量并行推理。

启动服务：

CUDA_VISIBLE_DEVICES=0,1 API_PORT=8000 llamafactory-cli api examples/inference/news_summary_api.yaml

服务默认监听 http://localhost:8000/v1。

Python 调用示例：

from openai import OpenAI

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

response = client.chat.completions.create(
    model="meta-llama/Meta-Llama-3-8B-Instruct",
    messages=[
        {"role": "user", "content": "请根据以下新闻内容生成一段简洁的摘要。\n\n近日，我国自主研发的新一代高速列车……"}
    ],
    temperature=0.7,
    max_tokens=150
)

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

这种设计极大降低了接入成本——任何兼容 OpenAI 接口的客户端都能无缝对接。

---

批量推理：高效评估测试集

对于离线评估或批量生成任务，推荐使用内置的 do_predict 模式。

准备测试数据 data/inference_news.json，格式同上，但 output 字段可省略：

{
  "instruction": "请根据以下新闻内容生成一段简洁的摘要。",
  "input": "国家统计局发布数据显示，2024年上半年全国GDP同比增长5.3%……"
}

在 dataset_info.json 中注册：

"inference_news": {
  "file_name": "inference_news.json"
}

新建 examples/train_lora/news_summary_predict.yaml：

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

stage: sft
do_predict: true
predict_with_generate: true

dataset: inference_news
cutoff_len: 1024
max_samples: 500
preprocessing_num_workers: 8

output_dir: saves/llama3-8b-lora-news-summary/predict/
overwrite_output_dir: true
per_device_eval_batch_size: 4
generation_max_length: 150
generation_num_beams: 1
predict_pad_token_id: 128001

执行批量推理：

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

结果将以 JSONL 格式保存在 generated_predictions.jsonl 中，每行为一条生成文本，方便后续分析与评测。

---

进阶技巧与常见问题应对

显存不足怎么办？

这是最常见的痛点之一。几种有效缓解策略包括：

• 启用 QLoRA：在配置中添加 quantization_bit: 4，结合 fp16 或 bf16，可在消费级显卡上运行 7B 级模型。
• 降低 batch size：将 per_device_train_batch_size 设为 1，并增加 gradient_accumulation_steps 来补偿总批量。
• 启用 bf16：若硬件支持（Ampere 架构及以上），设置 bf16: true 比 fp16 更稳定，尤其在多节点训练时。

如何更换模型？支持哪些？

Llama-Factory 兼容性强，只需更改 model_name_or_path 即可切换模型。常见支持列表如下：

模型系列	示例路径
Qwen	Qwen/Qwen-7B-Instruct
Baichuan	baichuan-inc/Baichuan2-7B-Chat
ChatGLM	THUDM/chatglm3-6b
InternLM	internlm/internlm2-chat-7b
Yi	01-ai/Yi-6B-Chat

只要模型能在 HuggingFace Hub 上公开访问或你有权限拉取，基本都可以无缝接入。

是否支持图形界面操作？

当然！Llama-Factory 内置基于 Gradio 的 WebUI，启动命令：

CUDA_VISIBLE_DEVICES=0 llamafactory-cli webui

浏览器访问 http://localhost:7860，即可通过拖拽上传数据、可视化设置参数、一键启动训练与交互式测试模型，真正做到“零代码微调”。

这对于非技术人员快速验证想法、产品经理做原型演示都非常友好。

---

结语

Llama-Factory 不只是一个微调框架，更是一套面向生产落地的完整解决方案。它把原本复杂的大模型定制流程封装成清晰的配置驱动模式，同时兼顾灵活性与易用性。

无论是科研实验中的快速迭代，还是企业级应用中的稳定部署，这套工具链都展现出极高的实用价值。更重要的是，它的活跃社区和持续更新保证了长期可用性。

现在就开始动手吧，用几百行 YAML 和一份业务数据，打造属于你自己的领域专家模型。