LLaMA-Factory：高效大模型微调框架实战

FreeGuideOnline 最新 2026-06-22

bash conda create -n llama_factory python=3.10 conda activate llama_factory


### 源码安装 LLaMA-Factory
```bash
git clone https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory
pip install -e ".[torch,metrics]"

如需使用量化技术，可额外安装：

pip install -e ".[bitsandbytes]"  # QLoRA 依赖

快速验证安装

llamafactory-cli version

输出类似 llamafactory: 0.9.1.dev0 即表示安装成功。

数据准备与格式化

支持的数据格式

LLaMA-Factory 使用统一的 dataset_info.json 注册数据集，原始文件支持两种格式：

Alpaca 格式（指令-输入-输出）：

[
  {
    "instruction": "将以下句子翻译成英文。",
    "input": "今天天气真好。",
    "output": "The weather is really nice today."
  }
]

ShareGPT 格式（多轮对话）：

[
  {
    "conversations": [
      {"from": "human", "value": "介绍一下北京"},
      {"from": "gpt", "value": "北京是中国的首都..."},
      {"from": "human", "value": "有哪些著名景点？"},
      {"from": "gpt", "value": "故宫、长城..."}
    ]
  }
]

准备自定义数据集

将你的 JSON 文件放入 data/ 目录。
编辑 data/dataset_info.json，添加自定义条目：

"my_dataset": {
  "file_name": "my_data.json",
  "formatting": "alpaca",   // 或 "sharegpt"
  "columns": {
    "prompt": "instruction",
    "query": "input",
    "response": "output"
  }
}

启动 Web UI 进行可视化微调

命令行执行：

llamafactory-cli webui

浏览器打开 http://localhost:7860，即可进入可视化操作界面。以下介绍 Web UI 中的关键配置。

选择模型与训练方式

模型选择：下拉列表包含已支持的预训练模型，如 LLaMA-3-8B、Qwen2-7B 等。首次使用会自动从 Hugging Face 下载。
微调方法：推荐初学者选择 lora，若显存紧张选 qlora。
精度：fp16 或 bf16 可节省显存，QLoRA 通常搭配 4bit 量化。

数据集与模板配置

数据集：勾选你注册的数据集（如 my_dataset）。
模板：根据基座模型选择对应聊天模板，例如 LLaMA-3 选 llama3，Qwen 选 qwen。这决定了输入如何被结构化。

核心训练参数（初学者建议）

学习率：5e-5（LoRA）
训练轮数（epochs）：3～5
批大小（batch_size）：按显存调整，一般 per_device_train_batch_size=2，配合梯度累积步数 gradient_accumulation_steps=4
最大序列长度：1024 或 2048
LoRA 秩（r）：8 或 16，alpha 设为 r 的 2 倍

开始训练

点击“开始”按钮，右侧日志窗会显示损失变化。训练完成后，LoRA 权重将保存在预设的输出目录。

命令行微调（进阶）

对于批量实验或服务器环境，推荐使用命令行方式。

编写 YAML 配置文件

创建 qwen2_lora_sft.yaml：

### model
model_name_or_path: Qwen/Qwen2-7B-Instruct

### method
stage: sft
do_train: true
finetuning_type: lora
lora_target: all

### dataset
dataset: my_dataset
template: qwen
cutoff_len: 2048
overwrite_cache: true
preprocessing_num_workers: 16

### output
output_dir: saves/qwen2-7b/lora
logging_steps: 10
save_steps: 500
plot_loss: true

### train
per_device_train_batch_size: 2
gradient_accumulation_steps: 4
learning_rate: 5.0e-5
num_train_epochs: 3.0
lr_scheduler_type: cosine
warmup_ratio: 0.1
bf16: true
ddp_timeout: 180000000

### eval
val_size: 0.1
per_device_eval_batch_size: 2
eval_strategy: steps
eval_steps: 500

启动训练

llamafactory-cli train qwen2_lora_sft.yaml

支持多卡训练（自动启用 DeepSpeed 或 FSDP），只需在命令前加 accelerate launch 或使用 torchrun。

合并模型与导出

LoRA 训练得到的是适配器权重，需要与基座模型合并才能用于推理。

Web UI 合并

在 Web UI 中切换到“合并导出”选项卡：

指定基座模型路径
选择待合并的 LoRA 权重（检查点目录）
设置导出目录
可选择导出量化版本（如 GPTQ）

命令行导出

llamafactory-cli export \
    --model_name_or_path Qwen/Qwen2-7B-Instruct \
    --adapter_name_or_path saves/qwen2-7b/lora/checkpoint-1000 \
    --template qwen \
    --finetuning_type lora \
    --export_dir models/qwen2-7b-merged \
    --export_size 2 \
    --export_device cpu \
    --export_legacy_format false

export_size 为分片数，2 代表分两个文件，便于分享。

模型推理与测试

命令行交互推理

llamafactory-cli chat \
    --model_name_or_path models/qwen2-7b-merged \
    --template qwen

输入对话即可测试模型效果。

API 服务部署

可以快速部署 OpenAI 兼容的 API：

llamafactory-cli api \
    --model_name_or_path models/qwen2-7b-merged \
    --template qwen \
    --api_port 8000

然后使用 curl 调用：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen2-7b","messages":[{"role":"user","content":"你好"}]}'

性能评估

LLaMA-Factory 内嵌了多项评估基准，可在 Web UI 的“评估”页或通过命令行运行。

快速评估示例

llamafactory-cli eval \
    --model_name_or_path models/qwen2-7b-merged \
    --template qwen \
    --task mmlu,ceval \
    --lang zh