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

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": [ ["上一轮问题", "上一轮回答"] ] } ]

自定义数据集实战案例

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

示例一：身份认知微调（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

关键参数说明

观察日志中的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)对。

主要评估指标包括：

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

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 强化学习对齐等专题内容，持续为开发者提供前沿技术实践指南。