跳到主要内容
LLaMA-Factory 实战指南:从环境搭建到模型微调与评测 | 极客日志
Python AI 算法
LLaMA-Factory 实战指南:从环境搭建到模型微调与评测 综述由AI生成 LLaMA-Factory 是一个整合了主流高效微调技术的开源框架,支持多阶段训练、推理及评测。本文基于 Linux + RTX 4090 环境,以 Meta-Llama-3-8B-Instruct 模型为例,详细演示了从环境校验、数据集构建、LoRA 指令微调,到动态合并推理、批量预测评估及 API Server 启动的全流程。内容涵盖命令行操作与 WebUI 可视化界面,旨在帮助开发者快速上手大模型垂直领域应用开发。
嘘 发布于 2026/4/5 更新于 2026/4/26 4 浏览1. 项目背景
开源大模型如 LLaMA、Qwen、Baichuan 等主要基于通用数据训练,在特定下游场景和垂直领域的效果仍有提升空间,这催生了微调训练的需求,涵盖预训练(pt)、指令微调(sft)、基于人工反馈的对齐(rlhf)等全链路。不过,大模型训练对显存和算力要求较高,且开发者需具备一定的技术基础。
LLaMA-Factory 旨在整合主流高效训练微调技术,适配市场主流开源模型,构建功能丰富、适配性强的训练框架。它提供了多阶段训练、推理测试、Benchmark 评测及 API Server 等高层抽象接口,支持开箱即用。此外,借鉴 Stable Diffusion WebUI 的设计理念,本项目提供了基于 Gradio 的网页版工作台,方便初学者快速上手。
2. 教程目标
本教程以 Meta-Llama-3-8B-Instruct 模型配合 Linux + RTX 4090 (24GB) 环境为例,聚焦 LoRA + SFT 训练阶段,帮助开发者实践以下常见功能:
原始模型直接推理
自定义数据集构建
基于 LoRA 的 SFT 指令微调
动态合并 LoRA 的推理
批量预测和训练效果评估
LoRA 模型合并导出
一站式 WebUI Board 的使用
API Server 的启动与调用
大模型主流评测 Benchmark
大部分内容可在 LLaMA-Factory 的 README.md、data/README.md 及 examples 文件夹下的示例脚本中找到。遇到问题建议优先查阅项目原始资料。关于全参训练、Flash-Attention 加速、DeepSpeed、RLHF 及多模态模型训练等高阶特性,后续会有额外教程介绍。
3. 前置准备
确保训练顺利运行需要满足四个条件:机器硬件驱动支持、依赖库正确安装、目标模型文件就绪、训练数据集构造完成。
3.1 硬件环境校验
显卡驱动和 CUDA 的安装可参考相关网络教程。使用以下命令进行简单校验:
nvidia-smi
预期输出应显示 GPU 当前状态和配置信息。关于不同模型规模所需的 GPU 资源,可参考官方文档的硬件需求部分。新手建议从 3090 或 4090 起步,便于训练主流的 7B 和 8B 级别模型。
3.2 CUDA 和 PyTorch 环境校验
请参考项目 README 进行安装。2024 年 5 月期间系统版本有较大升级,以下是推荐的安装命令(请注意 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]
安装后使用以下命令做简单的正确性校验:
校验 1
import torch
torch.cuda.current_device()
torch.cuda.get_device_name(0 )
torch.__version__
如果识别不到可用 GPU,说明环境准备仍有问题,需先处理后再继续。
校验 2
同时对本库的基础安装做一下校验,输入以下命令获取训练相关的参数指导,否则说明库未安装成功:
llamafactory-cli train -h
3.3 模型下载与可用性校验
项目支持通过模型名称直接从 HuggingFace 和 ModelScope 下载,但为了统一管理,建议使用手动下载并通过绝对路径控制。以 Meta-Llama-3-8B-Instruct 为例:
HuggingFace 下载(可能需要申请权限):
git clone https://huggingface.co/meta-llama/Meta-Llama-3-8B-Instruct
ModelScope 下载(适合中国大陆网络环境):
git clone https://www.modelscope.cn/LLM-Research/Meta-Llama-3-8B-Instruct.git
from modelscope import snapshot_download
model_dir = snapshot_download('LLM-Research/Meta-Llama-3-8B-Instruct' )
由于网络原因,下载后可能存在文件不完整的情况。建议先检查文件大小和数量是否与原始页面一致,再跑一下官方提供的推理 Demo 验证模型文件和 Transformers 库的可用性。
import transformers
import torch
model_id = "/path/to/Meta-Llama-3-8B-Instruct"
pipeline = transformers.pipeline(
"text-generation" ,
model=model_id,
model_kwargs={"torch_dtype" : torch.bfloat16},
device_map="auto" ,
)
messages = [
{"role" : "system" , "content" : "You are a pirate chatbot who always responds in pirate speak!" },
{"role" : "user" , "content" : "Who are you?" }
]
prompt = pipeline.tokenizer.apply_chat_template(
messages, tokenize=False , add_generation_prompt=True
)
terminators = [
pipeline.tokenizer.eos_token_id,
pipeline.tokenizer.convert_tokens_to_ids("<|eot_id|>" )
]
outputs = pipeline(
prompt,
max_new_tokens=256 ,
eos_token_id=terminators,
do_sample=True ,
temperature=0.6 ,
top_p=0.9 ,
)
print (outputs[0 ]["generated_text" ][len (prompt):])
3.4 数据集部分放到后面一起说明
4. 原始模型直接推理 在进行后续环节之前,我们先使用推理模式验证 LLaMA-Factory 的推理部分是否正常。LLaMA-Factory 内置了基于 Gradio 开发的 ChatBot 推理页面,可用于模型效果的人工测试。
在 LLaMA-Factory 目录下执行以下命令:
CUDA_VISIBLE_DEVICES=0 llamafactory-cli webchat \
--model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
--template llama3
CUDA_VISIBLE_DEVICES=0 指定程序使用第 0 张卡,这是全局变量设置,也可以不使用。需要注意的是,所有程序的入口都是 llamafactory-cli,通过不同参数控制功能。例如 webchat 表示前端版本纯推理的 Chat 页面。
参数名称 参数说明 model_name_or_path模型名称(HuggingFace 或 ModelScope 标准定义),或本地下载的绝对路径 template模型问答时使用的 Prompt 模板,不同模型不同,不指定可能导致回答异常
你也可以将参数提前存在 YAML 文件中管理,例如 examples/inference/llama3.yaml:
model_name_or_path: /path/to/Meta-Llama-3-8B-Instruct
template: llama3
llamafactory-cli webchat examples/inference/llama3.yaml
效果如图,可通过 http://localhost:7860/ 访问。如果是云端用户,可能无法直接通过本地笔记本访问,需要联系云厂商配置域名和端口映射,例如阿里云用户可能需要配置环境变量:
export GRADIO_ROOT_PATH=/${JUPYTER_NAME} /proxy/7860/
5. 自定义数据集构建 数据集格式在不同阶段有所不同。本教程以 SFT 阶段为例,结合系统自带的 identity 数据集和自定义的商品文案生成数据集,介绍数据集的使用。更多详情可参考 data/README_zh.md。
目前支持 Alpaca 和 ShareGPT 两种数据格式。以 Alpaca 为例,整个数据集是一个 JSON 对象的列表:
[
{
"instruction" : "用户指令(必填)" ,
"input" : "用户输入(选填)" ,
"output" : "模型回答(必填)" ,
"system" : "系统提示词(选填)" ,
"history" : [ [ "第一轮指令" , "第一轮回答" ] ]
}
]
单轮示例(alpaca_data_zh_51k.json):
{
"instruction" : "写一个有效的比较语句" ,
"input" : "篮球和足球" ,
"output" : "篮球和足球都是受欢迎的运动。"
}
{
"instruction" : "谢谢" ,
"input" : "" ,
"output" : "不用谢!很高兴我提供的信息能够帮助到你!" ,
"history" : [
[
"请你给我写一个面试准备计划..." ,
"首先,你可以去微软官网寻找招聘信息..."
]
]
}
我们需要将训练数据转换成这种格式,并在 data/dataset_info.json 中注册。如果不做字段名称转换,则需要在注册时在 columns 字段中做映射配置。
系统自带 identity.json 数据集 :已默认注册为 identity。我们可以通过文本编辑器替换其中的 NAME 和 AUTHOR 字段。
替换前:I am NAME, an AI assistant developed by AUTHOR.
替换后:I am PonyBot, an AI assistant developed by LLaMA Factory.
商品文案生成数据集 :假设原始格式为 content 和 summary。要将其放入系统使用,需执行两步操作:
复制数据集到 data 目录下。
修改 data/dataset_info.json 新增内容完成注册,定义数据集名称、文件位置及输入输出映射关系。
6. 基于 LoRA 的 SFT 指令微调 准备好数据集后,即可开始训练。我们的目标是让 LLaMA3 模型学会定义的'你是谁'以及商品文案的生成逻辑。这里先用命令行版本,更容易理解原理。
CUDA_VISIBLE_DEVICES=0 llamafactory-cli train \
--stage sft \
--do_train \
--model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
--dataset alpaca_gpt4_zh,identity,adgen_local \
--dataset_dir ./data \
--template llama3 \
--finetuning_type lora \
--lora_target q_proj,v_proj \
--output_dir ./saves/LLaMA3-8B/lora/sft \
--overwrite_cache \
--overwrite_output_dir \
--cutoff_len 1024 \
--preprocessing_num_workers 16 \
--per_device_train_batch_size 2 \
--per_device_eval_batch_size 1 \
--gradient_accumulation_steps 8 \
--lr_scheduler_type cosine \
--logging_steps 50 \
--warmup_steps 20 \
--save_steps 100 \
--eval_steps 50 \
--evaluation_strategy steps \
--load_best_model_at_end \
--learning_rate 5e-5 \
--num_train_epochs 5.0 \
--max_samples 1000 \
--val_size 0.1 \
--plot_loss \
--fp16
参数名称 参数说明 stage训练阶段,如 sft、pt、rw、ppo 等 do_train是否开启训练模式 dataset使用的数据集列表,多个用逗号分隔 finetuning_type微调类型,如 lora、full、freeze 等 lora_targetLoRA 训练的目标模块,不同模型不同 output_dir训练结果保存位置 cutoff_len训练数据集长度截断 fp16使用半精度混合精度训练
注意:精度相关参数还有 bf16 和 pure_bf16,但老显卡(如 V100)可能不支持 bf16,会导致报错。
训练过程中,系统会按 logging_steps 定时输出日志,包含当前 loss 和进度。训练完成后,在 output_dir 下会看到 adapter 开头的 LoRA 结果、training_loss 记录及其他参数备份。正常情况下,loss 会随着训练时间慢慢变小,最终下降到 1 以下会有较好效果。
7. 动态合并 LoRA 的推理 LoRA 训练结束后,如果想动态验证效果,可以在网页端与新模型对话。与原始模型推理相比,区别在于通过 finetuning_type 参数告知系统使用了 LoRA,并通过 adapter_name_or_path 指定 LoRA 模型位置。
CUDA_VISIBLE_DEVICES=0 llamafactory-cli webchat \
--model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
--adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \
--template llama3 \
--finetuning_type lora
此时模型已学习新数据知识。如果不加 LoRA 参数重启测试,模型仍会按通用方式回答。
CUDA_VISIBLE_DEVICES=0 llamafactory-cli chat \
--model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
--adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \
--template llama3 \
--finetuning_type lora
8. 批量预测和训练效果评估 人工交互偏感性,批量预测可使用自动化的 BLEU 和 ROUGE 等指标评估。请先安装相关库:
pip install jieba rouge-chinese nltk
CUDA_VISIBLE_DEVICES=0 llamafactory-cli train \
--stage sft \
--do_predict \
--model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
--adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \
--dataset alpaca_gpt4_zh,identity,adgen_local \
--dataset_dir ./data \
--template llama3 \
--finetuning_type lora \
--output_dir ./saves/LLaMA3-8B/lora/predict \
--overwrite_cache \
--overwrite_output_dir \
--cutoff_len 1024 \
--preprocessing_num_workers 16 \
--per_device_eval_batch_size 1 \
--max_samples 20 \
--predict_with_generate
主要区别在于 do_predict(预测模式)和 predict_with_generate(生成文本)。输出结果中,generated_predictions.jsonl 包含原始 Label 和模型预测结果,predict_results.json 则给出自动计算的指标。
指标 含义 BLEU-4 衡量四元语法匹配程度,值越高越相似 predict_rouge-1/2 衡量一元/二元序列匹配程度 predict_rouge-l 衡量最长公共子序列匹配程度 predict_runtime 预测运行总时间 predict_samples_per_second 每秒生成样本数
9. LoRA 模型合并导出 若要将训练的 LoRA 与原始大模型融合,输出完整模型文件,可使用以下命令。合并后的模型可像原始模型一样应用,也可递归用于训练。
CUDA_VISIBLE_DEVICES=0 llamafactory-cli export \
--model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
--adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \
--template llama3 \
--finetuning_type lora \
--export_dir merged-model-path \
--export_size 2 \
--export_device cpu \
--export_legacy_format False
10. 一站式 WebUI Board 的使用 除了命令行,LLaMA-Factory 还支持模型训练全链路的一站式 WebUI Board。它将主要链路和操作整合在一个页面中,参数可可视化编辑。
*注意:目前 WebUI 版本只支持单机单卡,多卡请使用命令行版本。
WebUI 通过不同 Tab 整合了多个功能模块。在 Train 页面配置好参数后,可通过预览命令功能导出训练脚本,支持多 GPU 训练。点击开始按钮,网页端和服务器端会同步输出日志。训练完毕后,点击'刷新适配器'即可找到历史训练的 LoRA 模型文件,后续训练或聊天时会自动加载。
11. API Server 的启动与调用 训练好后,可将模型能力封装为网络接口,接入 LangChain 或其他业务。API 实现参考 OpenAI 协议,基于 Uvicorn 开发。
CUDA_VISIBLE_DEVICES=0 API_PORT=8000 llamafactory-cli api \
--model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
--adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \
--template llama3 \
--finetuning_type lora
项目也支持基于 vLLM 的推理后端,但需提前将 LoRA 模型 Merge。服务启动后,按 OpenAI API 格式远程访问,只需替换 base_url 指向部署机器 URL 和端口。
12. 进阶 - 大模型主流评测 Benchmark 对于更高要求的场景,如刷榜单或评估微调后通用知识的泛化能力,可使用本项目提供的 MMLU、CMMLU、Ceval 等自动评测脚本。
CUDA_VISIBLE_DEVICES=0 llamafactory-cli eval \
--model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
--template llama3 \
--task mmlu \
--split validation \
--lang en \
--n_shot 5 \
--batch_size 1
Base 版本模型,template 改为 fewshot 即可。输出结果包含各项任务的指标,具体定义可参考任务原始资料。
相关免费在线工具 加密/解密文本 使用加密算法(如AES、TripleDES、Rabbit或RC4)加密和解密文本明文。 在线工具,加密/解密文本在线工具,online
RSA密钥对生成器 生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
Mermaid 预览与可视化编辑 基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
随机西班牙地址生成器 随机生成西班牙地址(支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选),支持数量快捷选择、显示全部与下载。 在线工具,随机西班牙地址生成器在线工具,online
Gemini 图片去水印 基于开源反向 Alpha 混合算法去除 Gemini/Nano Banana 图片水印,支持批量处理与下载。 在线工具,Gemini 图片去水印在线工具,online
curl 转代码 解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具,curl 转代码在线工具,online