LLaMA-Factory微调实战：从环境到训练全指南

e名牙医

751人浏览 · 2025-12-15 10:45:14

e名牙医 · 2025-12-15 10:45:14 发布

LLaMA-Factory微调实战：从环境到训练全指南

在当前大模型技术飞速发展的背景下，如何将通用语言模型精准适配到具体业务场景，已成为开发者面临的核心挑战。尽管像 Llama、Qwen、Baichuan 等开源模型提供了强大的基础能力，但若未经定制化调整，它们往往难以满足垂直领域对专业术语、风格一致性或任务特定逻辑的严苛要求。

正是在这样的需求驱动下，LLaMA-Factory 脱颖而出——它不仅仅是一个微调框架，更是一套覆盖“数据准备 → 模型训练 → 效果评估 → 部署上线”全流程的完整解决方案。该项目支持超过百种主流开源架构，兼容全参数微调、LoRA、QLoRA 等多种高效训练策略，并通过 Gradio 构建的可视化界面大幅降低使用门槛。无论是刚入门的新手，还是追求极致性能优化的资深工程师，都能借助这套工具快速打造专属的大模型应用。

本文将以 Meta-Llama-3-8B-Instruct 模型为例，在配备 RTX 4090 显卡的 Linux 环境中，完整演示如何利用 LLaMA-Factory 实现 LoRA 指令微调（SFT）。我们将深入每一个关键环节：从环境搭建、模型加载、数据构建，到命令行与 WebUI 双模式训练、推理测试、批量评估、模型合并导出，再到 API 服务部署和基准评测，力求为读者提供一条可复用、可迁移的端到端实践路径。

环境准备与系统校验

任何成功的微调任务都始于一个稳定可靠的运行环境。我们首先需要确认硬件资源、CUDA 驱动、Python 依赖等基础条件均已就绪。

GPU 识别与显存检查

执行以下命令查看 NVIDIA 显卡状态：

nvidia-smi

预期输出应包含 GPU 型号、显存容量及 CUDA 版本。以 RTX 4090 为例，其 24GB 显存足以支撑 7B~13B 规模模型的 LoRA/QLoRA 微调任务。尤其值得注意的是，该卡原生支持 bf16 和 float16 运算，这对减少显存占用、提升训练效率至关重要。

⚠️ 提示：对于更大规模模型或全参微调，建议考虑多卡分布式方案（如 Deepspeed），本文暂不涉及。

推荐配置参考：
- GPU：NVIDIA 3090 / 4090（≥24GB 显存）
- 内存：≥32GB
- 存储空间：≥100GB（用于缓存模型权重和中间文件）

安装 LLaMA-Factory 与核心依赖

为了避免依赖冲突，强烈建议使用 Conda 创建独立虚拟环境：

git clone https://github.com/hiyouga/LLaMA-Factory.git
conda create -n llama_factory python=3.10
conda activate llama_factory
cd LLaMA-Factory
pip install -e .[metrics]

安装完成后，务必验证 PyTorch 是否能正常调用 GPU：

import torch
print(torch.cuda.is_available())           # 应返回 True
print(torch.cuda.get_device_name(0))      # 输出 GPU 名称
print(torch.__version__)                  # 查看版本

同时检查 CLI 工具是否注册成功：

llamafactory-cli train -h

若能打印出训练参数帮助信息，则说明安装无误。

模型获取与本地验证

虽然 LLaMA-Factory 支持自动从 Hugging Face 或 ModelScope 拉取模型，但为了便于管理、避免重复下载，手动下载并指定本地路径是更优选择。

下载方式对比

方式一：Hugging Face（需申请权限）

git clone https://huggingface.co/meta-llama/Meta-Llama-3-8B-Instruct

方式二：ModelScope（国内推荐）

from modelscope import snapshot_download
model_dir = snapshot_download('LLM-Research/Meta-Llama-3-8B-Instruct')

下载后建议进行完整性校验，确保文件数量、大小与原始仓库一致，并可通过 Transformers 正常加载。

手动加载测试

from transformers import pipeline

model_path = "/path/to/your/Meta-Llama-3-8B-Instruct"

pipe = pipeline(
    "text-generation",
    model=model_path,
    model_kwargs={"torch_dtype": "auto"},
    device_map="auto"
)

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "介绍一下你自己"}
]

prompt = pipe.tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
outputs = pipe(prompt, max_new_tokens=128)
print(outputs[0]["generated_text"][len(prompt):])

如果能够顺利生成回答，说明模型文件完整可用。

数据集构建与格式规范

LLaMA-Factory 支持 alpaca 和 sharegpt 两种主流数据格式。本教程采用 alpaca 格式，其结构清晰、易于扩展。

alpaca 数据结构（JSON List）

[
  {
    "instruction": "写一个有效的比较语句",
    "input": "篮球和足球",
    "output": "篮球和足球都是受欢迎的运动。",
    "system": "你是一个严谨的语言专家",
    "history": [
      ["上一轮问题", "上一轮回答"]
    ]
  }
]

字段	是否必填	说明
`instruction`	✅ 必填	用户指令
`input`	❌ 选填	输入上下文
`output`	✅ 必填	期望输出
`system`	❌ 选填	系统提示词
`history`	❌ 选填	多轮对话历史

自定义数据集实战案例

下面我们通过两个典型场景展示如何构建并注册自定义数据集。

示例一：身份认知微调（identity.json）

修改系统自带的身份数据集 data/identity.json：

原始内容：

{
  "instruction": "Who are you?",
  "output": "I am NAME, an AI assistant developed by AUTHOR."
}

替换为：

{
  "instruction": "你是谁？",
  "output": "我是小智，由 LLaMA-Factory 训练的专属助手。"
}

该数据集已在 data/dataset_info.json 中注册为 identity，无需额外配置。

示例二：商品文案生成（adgen_local）

假设我们有一个商品属性生成文案的数据集，原始格式如下：

{
  "content": "类型#连衣裙*风格#复古*颜色#红色",
  "summary": "这款红色复古连衣裙采用高腰设计..."
}

转换为 alpaca 格式并保存为 data/adgen_local.json：

[
  {
    "instruction": "根据商品标签生成一段营销文案",
    "input": "类型#连衣裙*风格#复古*颜色#红色",
    "output": "这款红色复古连衣裙采用高腰设计..."
  }
]

然后在 data/dataset_info.json 中添加注册项：

"adgen_local": {
  "file_name": "adgen_local.json",
  "columns": {
    "instruction": "instruction",
    "input": "input",
    "output": "output"
  }
}

至此，adgen_local 即可在训练中作为数据集名称直接引用。

使用 LoRA 进行 SFT 微调

准备工作完成后，即可启动正式训练。我们将采用 LoRA 技术对 Llama-3-8B-Instruct 进行轻量化微调，仅更新低秩矩阵，显著降低显存消耗。

命令行训练脚本

CUDA_VISIBLE_DEVICES=0 llamafactory-cli train \
    --stage sft \
    --do_train \
    --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
    --dataset identity,adgen_local \
    --dataset_dir ./data \
    --template llama3 \
    --finetuning_type lora \
    --lora_target q_proj,v_proj \
    --output_dir ./saves/llama3-lora-sft \
    --overwrite_cache \
    --overwrite_output_dir \
    --cutoff_len 1024 \
    --per_device_train_batch_size 2 \
    --gradient_accumulation_steps 8 \
    --lr_scheduler_type cosine \
    --logging_steps 10 \
    --save_steps 50 \
    --eval_steps 25 \
    --evaluation_strategy steps \
    --learning_rate 2e-4 \
    --num_train_epochs 3 \
    --max_samples 500 \
    --val_size 0.1 \
    --plot_loss \
    --fp16

关键参数说明

参数	说明
`--stage sft`	监督式指令微调阶段
`--dataset`	使用的数据集名称列表（需提前注册）
`--finetuning_type lora`	启用 LoRA 微调
`--lora_target`	注入目标模块，Llama 系列常用 `q_proj,v_proj`
`--output_dir`	权重保存路径
`--per_device_train_batch_size`	单卡 batch size，根据显存调整
`--gradient_accumulation_steps`	梯度累积步数，模拟更大 batch
`--learning_rate`	学习率，LoRA 推荐范围 1e-4 ~ 5e-4
`--num_train_epochs`	训练轮数
`--plot_loss`	训练结束后自动生成 loss 曲线图

观察日志中的 loss 变化趋势是判断训练是否正常的关键。理想情况下，最终 loss 应低于 1.0，且验证集指标持续改善。

动态加载 LoRA 权重进行推理

训练完成后，可通过多种方式实时测试效果。

方法一：启动 WebChat 页面

llamafactory-cli webchat \
    --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
    --adapter_name_or_path ./saves/llama3-lora-sft \
    --template llama3 \
    --finetuning_type lora

访问 http://localhost:7860 即可与模型对话。你会发现模型已学会新的身份设定和文案生成风格。

💡 提示：云服务器用户需设置 GRADIO_ROOT_PATH 才能通过公网访问。

方法二：命令行交互模式

llamafactory-cli chat \
    --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
    --adapter_name_or_path ./saves/llama3-lora-sft \
    --template llama3 \
    --finetuning_type lora

输入问题后即可看到带 LoRA 权重的响应结果。

批量预测与自动化评估

人工测试主观性强，建议结合量化指标客观评估模型表现。

安装评估依赖

pip install jieba rouge-chinese nltk

执行批量预测

llamafactory-cli train \
    --stage sft \
    --do_predict \
    --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
    --adapter_name_or_path ./saves/llama3-lora-sft \
    --dataset adgen_local \
    --dataset_dir ./data \
    --template llama3 \
    --finetuning_type lora \
    --output_dir ./predict_results \
    --per_device_eval_batch_size 1 \
    --max_samples 20 \
    --predict_with_generate

结果分析

生成文件位于 ./predict_results/generated_predictions.jsonl，每行为 (label, prediction) 对。

主要评估指标包括：

指标	含义
`BLEU-4`	n-gram 匹配度，越高越好（最大100）
`ROUGE-1/2/L`	召回率导向的文本相似性评分
`samples_per_second`	推理吞吐量，反映效率

这些数据可用于横向对比不同训练策略的效果。

LoRA 模型合并导出

若需将 LoRA 权重与基础模型融合为一个独立模型，便于部署或继续训练，可使用导出功能：

llamafactory-cli export \
    --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
    --adapter_name_or_path ./saves/llama3-lora-sft \
    --template llama3 \
    --finetuning_type lora \
    --export_dir ./merged_model \
    --export_device cpu \
    --export_legacy_format false

导出后的模型可像普通 HF 模型一样加载：

from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("./merged_model")

⚠️ 注意：合并会显著增加模型体积（如 4.7GB → 14GB），请预留足够磁盘空间。

WebUI 可视化训练平台

LLaMA-Factory 提供了集成化的 WebUI 工作台，极大简化操作流程。

启动命令：

llamafactory-cli webui

访问 http://localhost:7860/ui，即可使用以下功能模块：

Train：图形化配置训练参数，支持 YAML 导出
Evaluate：一键运行 MMLU/C-Eval 等 benchmark
Inference：实时聊天测试
Export：模型合并导出
API Server：启动 OpenAI 兼容接口

所有操作均可通过点击完成，非常适合新手快速上手。

启动 API 服务供外部调用

为了让模型接入 LangChain、Agent 系统或其他业务系统，可启动 RESTful API 服务。

基于原生后端启动

API_PORT=8000 llamafactory-cli api \
    --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
    --adapter_name_or_path ./saves/llama3-lora-sft \
    --template llama3 \
    --finetuning_type lora

服务启动后，可通过标准 OpenAI SDK 调用：

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="none")

response = client.chat.completions.create(
    model="llama-3-lora",
    messages=[{"role": "user", "content": "你是谁？"}]
)
print(response.choices[0].message.content)

使用 vLLM 加速推理（需先合并模型）

API_PORT=8000 llamafactory-cli api \
    --model_name_or_path ./merged_model \
    --infer_backend vllm \
    --vllm_enforce_eager

vLLM 在高并发场景下表现出色，适合生产级部署。

大模型 Benchmark 评测

为评估微调后模型是否保留通用能力，可运行标准 benchmark 测试。

MMLU 英文知识评测

llamafactory-cli eval \
    --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
    --adapter_name_or_path ./saves/llama3-lora-sft \
    --template llama3 \
    --task mmlu \
    --split validation \
    --lang en \
    --n_shot 5 \
    --batch_size 1

输出示例：

Average: 62.45
       STEM: 51.23
Social Sciences: 75.67
     Humanities: 58.90
          Other: 72.11

C-Eval 中文综合能力评测

llamafactory-cli eval \
    --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
    --adapter_name_or_path ./saves/llama3-lora-sft \
    --template llama3 \
    --task ceval \
    --split val \
    --lang zh \
    --n_shot 3

这些评测可用于判断微调是否导致“灾难性遗忘”——即在适应新任务的同时，是否严重损失了原有通用知识。

这种高度集成的设计思路，正引领着智能应用开发向更可靠、更高效的方向演进。未来我们还将推出 QLoRA 量化微调、多 GPU 分布式训练、Deepspeed 集成优化以及 RLHF 强化学习对齐等专题内容，持续为开发者提供前沿技术实践指南。

加入AMD AI开发者计划！

免费领 200 小时云算力，进群参与显卡、AI PC 幸运抽奖

更多推荐

FlagOS Day 0 跨芯适配 GLM-5.2：发布即覆盖四款芯片，支持 vLLM + SGLang双插件

同时，FlagGems 新增 6 大领域算子库——FlagDNN、FlagBlas、FlagSparse、FlagFFT、FlagTensor、FlagAudio，覆盖科学计算与信号处理场景，共计 102 个领域算子，从"大模型专用"走向全领域覆盖。厂商目录放置后由插件自动发现加载，vLLM-Plugin-FL、SGLang-Plugin-FL、Megatron-LM-FL、Transformer