介绍使用 LLaMA-Factory 完成大模型微调的完整流程：硬件与 CUDA、PyTorch 环境校验，模型下载与可用性验证，原始模型推理，构建自定义数据集，以及预训练、指令微调与对齐等全链路训练方式。

https://llamafactory.readthedocs.io/zh-cn/latest/

1. 项目背景

开源大模型如LLaMA，Qwen，Baichuan等主要都是使用通用数据进行训练而来，其对于不同下游的使用场景和垂直领域的效果有待进一步提升，衍生出了微调训练相关的需求，包含预训练（pt），指令微调（sft），基于人工反馈的对齐（rlhf）等全链路。但大模型训练对于显存和算力的要求较高，同时也需要下游开发者对大模型本身的技术有一定了解，具有一定的门槛。

LLaMA-Factory指南的目标是整合主流的各种高效训练微调技术，适配市场主流开源模型，形成一个功能丰富，适配性好的训练框架。项目提供了多个高层次抽象的调用接口，包含多阶段训练，推理测试，benchmark评测，API Server等，使开发者开箱即用。同时借鉴 Stable Diffsion 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文件夹下的示例脚本得到，遇到问题请先阅读项目原始相关资料。

3. 前置准备

训练顺利运行需要包含4个必备条件

机器本身的硬件和驱动支持（包含显卡驱动，网络环境等）
本项目及相关依赖的python库的正确安装（包含CUDA， Pytorch等）
目标训练模型文件的正确下载
训练数据集的正确构造和配置
3.1 硬件环境校验

显卡驱动和CUDA的安装，网络教程很多，不在本教程范围以内

使用以下命令做最简单的校验

nvidia-smi

预期输出如图，显示GPU当前状态和配置信息

那多大的模型用什么训练方式需要多大的GPU呢，可参考

https://github.com/hiyouga/LLaMA-Factory?tab=readme-ov-file#hardware-requirement

新手建议是3090和4090起步，可以比较容易地训练比较主流的入门级别大模型 7B和8B版本。

Method	Bits	7B	13B	30B	70B	110B	8x7B	8x22B
Full	AMP	120GB	240GB	600GB	1200GB	2000GB	900GB	2400GB
Full	16	60GB	120GB	300GB	600GB	900GB	400GB	1200GB
Freeze	16	20GB	40GB	80GB	200GB	360GB	160GB	400GB
LoRA/GaLore/BAdam	16	16GB	32GB	64GB	160GB	240GB	120GB	320GB
QLoRA	8	10GB	20GB	40GB	80GB	140GB	60GB	160GB
QLoRA	4	6GB	12GB	24GB	48GB	72GB	30GB	96GB
QLoRA	2	4GB	8GB	16GB	24GB	48GB	18GB	48GB

3.2 CUDA和Pytorch环境校验

请参考项目的readme进行安装

https://github.com/hiyouga/LLaMA-Factory?tab=readme-ov-file#dependence-installation

2024年51期间系统版本有较大升级，2024-05-06 号的安装版本命令如下，请注意conda环境的激活。（或者直接使用pip install llmtune==0.7.1）

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]

上述的安装命令完成了如下几件事

新建一个LLaMA-Factory 使用的python环境（可选）
安装LLaMA-Factory 所需要的第三方基础库（requirements.txt包含的库）
安装评估指标所需要的库，包含nltk, jieba, rouge-chinese
安装LLaMA-Factory本身，然后在系统中生成一个命令 llamafactory-cli（具体用法见下方教程）
安装后使用以下命令做简单的正确性校验

校验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')

4. 原始模型直接推理

在进行后续的环节之前，我们先使用推理模式，先验证一下LLaMA-Factory的推理部分是否正常。LLaMA-Factory 带了基于gradio开发的ChatBot推理页面, 帮助做模型效果的人工测试。在LLaMA-Factory 目录下执行以下命令

本脚本参数参考自 LLaMA-Factory/examples/inference/llama3.yaml at main · hiyouga/LLaMA-Factory

CUDA_VISIBLE_DEVICES=0 llamafactory-cli webchat \
    --model_name_or_path /models/Meta-Llama-3-8B-Instruct \
    --template llama3

*CUDA_VISIBLE_DEVICES=0 *是指定了当前程序使用第0张卡，是指定全局变量的作用, 也可以不使用

llamafactory-cli webchat \
    --model_name_or_path /models/Meta-Llama-3-8B-Instruct \
    --template llama3

需要注意的是，本次及后续所有的程序的入口都是** llamafactory-cli**，通过不同的参数控制现在是实现什么功能，比如现在是想使用网页版本直接推理，所以第一个参数设置为webchat, 所有的可选项包括

动作参数枚举	参数说明
version	显示版本信息
train	命令行版本训练
chat	命令行版本推理chat
export	模型合并和导出
api	启动API server，供接口调用
eval	使用mmlu等标准数据集做评测
webchat	前端版本纯推理的chat页面
webui	启动LlamaBoard前端页面，包含可视化训练，预测，chat，模型合并多个子页面

另外两个关键参数解释如下，后续的基本所有环节都会继续使用这两个参数

参数名称	参数说明
model_name_or_path	参数的名称（huggingface或者modelscope上的标准定义，如“meta-llama/Meta-Llama-3-8B-Instruct”），或者是本地下载的绝对路径，如/models/Meta-Llama-3-8B-Instruct
template	模型问答时所使用的prompt模板，不同模型不同，请参考 https://github.com/hiyouga/LLaMA-Factory?tab=readme-ov-file#supported-models 获取不同模型的模板定义，否则会回答结果会很奇怪或导致重复生成等现象的出现。chat 版本的模型基本都需要指定，比如Meta-Llama-3-8B-Instruct的template 就是 llama3

当然你也可以提前把相关的参数存在yaml文件里，比如LLaMA-Factory/examples/inference/llama3.yaml at main · hiyouga/LLaMA-Factory，本地位置是 examples/inference/llama3.yaml ，内容如下

model_name_or_path: /models/Meta-Llama-3-8B-Instruct
template: llama3

这样就可以通过如下命令启动，其效果跟上面是一样的，但是更方便管理

llamafactory-cli webchat examples/inference/llama3.yaml

可通过 http://localhost:7860/ 进行访问

注意：这里的localhost:7860 指的是程序启动机器自身的7860端口，云上的用户可能无法通过本地的笔记本电脑直接访问，需要找云厂商获取域名和端口号的一些配置关系进行配置

比如阿里云用户需要做一下如下环境变量的配置才能正常运行gradio，然后再通过阿里云给的域名映射访问

export GRADIO_ROOT_PATH=/${JUPYTER_NAME}/proxy/7860/

5. 自定义数据集构建

数据集的格式要求在不同的阶段是不同的，本教程以sft阶段的数据集需求，将以系统自带的identity数据集和将自定义的一个商品文案生成数据集为例，介绍数据集的使用。更多详情可以在 https://github.com/hiyouga/LLaMA-Factory/blob/main/data/README_zh.md 中找到相关解释。

5.1 数据集的格式

系统目前支持 alpaca 和sharegpt两种数据格式，以alpaca为例，整个数据集是一个json对象的list，具体数据格式为

[
  {
    "instruction": "用户指令（必填）",
    "input": "用户输入（选填）",
    "output": "模型回答（必填）",
    "system": "系统提示词（选填）",
    "history": [
      ["第一轮指令（选填）", "第一轮回答（选填）"],
      ["第二轮指令（选填）", "第二轮回答（选填）"]
    ]
  }
]

例子比如单轮（alpaca_data_zh_51k.json 中的例子, 数据集在data/dataset_info.json中注册为alpaca_zh）

{
  "instruction": "写一个有效的比较语句",
  "input": "篮球和足球",
  "output": "篮球和足球都是受欢迎的运动。"
}

和多轮（oaast_sft_zh.json 中的例子, 数据集在data/dataset_info.json中注册为oaast_sft_zh）

{
  "instruction": "谢谢",
  "input": "",
  "output": "不用谢! 很高兴我提供的信息能够帮助到你! 如果还有什么其他问题也可以向我提问。",
  "history": [
    [
      "请你给我写一个面试准备计划，我想要去面试微软的程序员岗位",
      "首先，你可以去微软官网寻找招聘信息并申请面试。\n其次，您可以在社交媒体平台寻找微软公司对程序员的面试问题，并做好准备。\n最后，您可以自己对面试过程进行模拟，熟悉话题并减少紧张感。\n我希望你能面试成功。"
    ]
  ]
}

所以我们训练的数据最好也转换成这种格式，然后在 data/dataset_info.json中进行注册（如果不做字段名称转换，则需要在注册的时候在 columns字段中做两个数据的映射配置）

5.2 数据集的使用

接下来，我们使用两个具体的例子来说明数据集的使用

第一个是系统自带的identity.json数据集(已默认在data/dataset_info.json 注册为identity)，对应文件已经在data目录下，我们通过操作系统的文本编辑器的替换功能，可以替换其中的NAME 和 AUTHOR ，换成我们需要的内容。

替换前

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

替换后

{
  "instruction": "Who are you?",
  "input": "",
  "output": "I am PonyBot, an AI assistant developed by LLaMA Factory. How can I assist you today?"
}

第二个是一个商品文案生成数据集，原始链接为 https://cloud.tsinghua.edu.cn/f/b3f119a008264b1cabd1/?dl=1

原始格式如下，很明显，训练目标是输入content （也就是prompt）, 输出 summary （对应response）

{
    "content": "类型#裤*版型#宽松*风格#性感*图案#线条*裤型#阔腿裤", 
    "summary": "宽松的阔腿裤这两年真的吸粉不少，明星时尚达人的心头爱。毕竟好穿时尚，谁都能穿出腿长2米的效果宽松的裤腿，当然是遮肉小能手啊。上身随性自然不拘束，面料亲肤舒适贴身体验感棒棒哒。系带部分增加设计看点，还让单品的设计感更强。腿部线条若隐若现的，性感撩人。颜色敲温柔的，与裤子本身所呈现的风格有点反差萌。"
}

想将该自定义数据集放到我们的系统中使用，则需要进行如下两步操作

复制该数据集到 data目录下
修改 data/dataset_info.json 新加内容完成注册, 该注册同时完成了3件事

自定义数据集的名称为adgen_local，后续训练的时候就使用这个名称来找到该数据集
指定了数据集具体文件位置
定义了原数据集的输入输出和我们所需要的格式之间的映射关系

6. 基于LoRA的sft指令微调

在准备好数据集之后，我们就可以开始准备训练了，我们的目标就是让原来的LLaMA3模型能够学会我们定义的“你是谁”，同时学会我们希望的商品文案的一些生成。

这里我们先使用命令行版本来做训练，从命令行更容易学习相关的原理。

本脚本参数改编自 https://github.com/hiyouga/LLaMA-Factory/blob/main/examples/lora_single_gpu/llama3_lora_sft.yaml

CUDA_VISIBLE_DEVICES=0 llamafactory-cli train \
    --stage sft \
    --do_train \
    --model_name_or_path /models/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

关于参数的完整列表和解释可以通过如下命令来获取

llamafactory-cli train -h

部分关键的参数说明如下，model_name_or_path 和template 上文已解释

参数名称	参数说明
stage	当前训练的阶段，枚举值，有“sft”,”pt”,”rw”,”ppo”等，代表了训练的不同阶段，这里我们是有监督指令微调，所以是sft
do_train	是否是训练模式
dataset	使用的数据集列表，所有字段都需要按上文在data_info.json里注册，多个数据集用”,”分隔
dataset_dir	数据集所在目录，这里是 data，也就是项目自带的data目录
finetuning_type	微调训练的类型，枚举值，有”lora”,”full”,”freeze”等，这里使用lora
lora_target	如果finetuning_type是lora，那训练的参数目标的定义，这个不同模型不同，请到https://github.com/hiyouga/LLaMA-Factory/tree/main?tab=readme-ov-file#supported-models 获取不同模型的可支持module，比如llama3 默认是 q_proj,v_proj
output_dir	训练结果保存的位置
cutoff_len	训练数据集的长度截断
per_device_train_batch_size	每个设备上的batch size，最小是1，如果GPU 显存够大，可以适当增加
fp16	使用半精度混合精度训练
max_samples	每个数据集采样多少数据
val_size	随机从数据集中抽取多少比例的数据作为验证集

注意：精度相关的参数还有bf16 和pure_bf16，但是要注意有的老显卡，比如V100就无法支持bf16，会导致程序报错或者其他错误

训练过程中，系统会按照logging_steps的参数设置，定时输出训练日志，包含当前loss，训练进度等，训练完后就可以在设置的output_dir下看到如下内容，主要包含3部分

adapter开头的就是 LoRA保存的结果了，后续用于模型推理融合
training_loss 和trainer_log等记录了训练的过程指标
其他是训练当时各种参数的备份
7. 动态合并LoRA的推理

本脚本参数改编自 https://github.com/hiyouga/LLaMA-Factory/blob/main/examples/inference/llama3_lora_sft.yaml

当基于LoRA的训练进程结束后，我们如果想做一下动态验证，在网页端里与新模型对话，与步骤4的原始模型直接推理相比，唯一的区别是需要通过finetuning_type参数告诉系统，我们使用了LoRA训练，然后将LoRA的模型位置通过 adapter_name_or_path参数即可。

CUDA_VISIBLE_DEVICES=0 llamafactory-cli webchat \
    --model_name_or_path /models/Meta-Llama-3-8B-Instruct \
    --adapter_name_or_path ./saves/LLaMA3-8B/lora/sft  \
    --template llama3 \
    --finetuning_type lora

效果如下，可以看到，模型整个已经在学习了新的数据知识，学习了新的身份认知和商品文案生成的格式。

如果不方便使用webui来做交互，使用命令行来做交互，同样也是可以的。

本脚本改编自 https://github.com/hiyouga/LLaMA-Factory/blob/main/examples/inference/llama3_lora_sft.yaml

CUDA_VISIBLE_DEVICES=0 llamafactory-cli chat \
    --model_name_or_path /models/Meta-Llama-3-8B-Instruct \
    --adapter_name_or_path ./saves/LLaMA3-8B/lora/sft  \
    --template llama3 \
    --finetuning_type lora

8. 批量预测和训练效果评估

当然上文中的人工交互测试，会偏感性，那有没有办法批量地预测一批数据，然后使用自动化的bleu和 rouge等常用的文本生成指标来做评估。指标计算会使用如下3个库，请先做一下pip安装

pip install jieba
pip install rouge-chinese
pip install nltk

本脚本参数改编自 https://github.com/hiyouga/LLaMA-Factory/blob/main/examples/lora_single_gpu/llama3_lora_predict.yaml

CUDA_VISIBLE_DEVICES=0 llamafactory-cli train \
    --stage sft \
    --do_predict \
    --model_name_or_path /models/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	现在用于生成文本
max_samples	每个数据集采样多少用于预测对比

其中 generated_predictions.jsonl 文件输出了要预测的数据集的原始label和模型predict的结果

predict_results.json给出了原始label和模型predict的结果，用自动计算的指标数据

这里给相关的指标做一下进一步的解释

指标	含义
BLEU-4	BLEU（Bilingual Evaluation Understudy）是一种常用的用于评估机器翻译质量的指标。BLEU-4 表示四元语法 BLEU 分数，它衡量模型生成文本与参考文本之间的 n-gram 匹配程度，其中 n=4。值越高表示生成的文本与参考文本越相似，最大值为 100。
predict_rouge-1 和 predict_rouge-2	ROUGE（Recall-Oriented Understudy for Gisting Evaluation）是一种用于评估自动摘要和文本生成模型性能的指标。ROUGE-1 表示一元 ROUGE 分数，ROUGE-2 表示二元 ROUGE 分数，分别衡量模型生成文本与参考文本之间的单个词和双词序列的匹配程度。值越高表示生成的文本与参考文本越相似，最大值为 100。
predict_rouge-l	ROUGE-L 衡量模型生成文本与参考文本之间最长公共子序列（Longest Common Subsequence）的匹配程度。值越高表示生成的文本与参考文本越相似，最大值为 100。
predict_runtime	预测运行时间，表示模型生成一批样本所花费的总时间。单位通常为秒。
predict_samples_per_second	每秒生成的样本数量，表示模型每秒钟能够生成的样本数量。通常用于评估模型的推理速度。
predict_steps_per_second	每秒执行的步骤数量，表示模型每秒钟能够执行的步骤数量。对于生成模型，一般指的是每秒钟执行生成操作的次数。

9. LoRA模型合并导出

如果想把训练的LoRA和原始的大模型进行融合，输出一个完整的模型文件的话，可以使用如下命令。合并后的模型可以自由地像使用原始的模型一样应用到其他下游环节，当然也可以递归地继续用于训练。

本脚本参数改编自 https://github.com/hiyouga/LLaMA-Factory/blob/main/examples/merge_lora/llama3_lora_sft.yaml

CUDA_VISIBLE_DEVICES=0 llamafactory-cli export \
    --model_name_or_path /models/Meta-Llama-3-8B-Instruct \
    --adapter_name_or_path ./saves/LLaMA3-8B/lora/sft  \
    --template llama3 \
    --finetuning_type lora \
    --export_dir megred-model-path \
    --export_size 2 \
    --export_device cpu \
    --export_legacy_format False

10. 一站式webui board的使用

通过以下命令启动

注意：目前webui版本只支持单机单卡，如果是多卡请使用命令行版本

CUDA_VISIBLE_DEVICES=0 llamafactory-cli webui

如果要开启 gradio的share功能，或者修改端口号

CUDA_VISIBLE_DEVICES=0 GRADIO_SHARE=1 GRADIO_SERVER_PORT=7860 llamafactory-cli webui

11. API Server的启动与调用

训练好后，可能部分同学会想将模型的能力形成一个可访问的网络接口，通过API 来调用，接入到langchian或者其他下游业务中，项目也自带了这部分能力。

API 实现的标准是参考了OpenAI的相关接口协议，基于uvicorn服务框架进行开发，使用如下的方式启动

本脚本改编自 https://github.com/hiyouga/LLaMA-Factory/blob/main/examples/inference/llama3_lora_sft.yaml

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

项目也支持了基于vllm 的推理后端，但是这里由于一些限制，需要提前将LoRA 模型进行merge，使用merge后的完整版模型目录或者训练前的模型原始目录都可。

CUDA_VISIBLE_DEVICES=0 API_PORT=8000 llamafactory-cli api \
    --model_name_or_path megred-model-path \
    --template llama3 \
    --infer_backend vllm \
    --vllm_enforce_eager

服务启动后，即可按照openai 的API 进行远程访问，主要的区别就是替换其中的base_url，指向所部署的机器url和端口号即可。

import os
from openai import OpenAI
from transformers.utils.versions import require_version

require_version("openai>=1.5.0", "To fix: pip install openai>=1.5.0")

if __name__ == '__main__':
    # change to your custom portport = 8000
    client = OpenAI(
        api_key="0",
        base_url="http://localhost:{}/v1".format(os.environ.get("API_PORT", 8000)),
    )
    messages = []
    messages.append({"role": "user", "content": "hello, where is USA"})
    result = client.chat.completions.create(messages=messages, model="test")
    print(result.choices[0].message)

12. 进阶-大模型主流评测 benchmark

虽然大部分同学的主流需求是定制一个下游的垂直模型，但是在部分场景下，也可能有同学会使用本项目来做更高要求的模型训练，用于大模型刷榜单等，比如用于评测mmlu等任务。当然这类评测同样可以用于评估大模型二次微调之后，对于原来的通用知识的泛化能力是否有所下降。（因为一个好的微调，尽量是在具备垂直领域知识的同时，也保留了原始的通用能力）

本项目提供了mmlu，cmmlu, ceval三个常见数据集的自动评测脚本，按如下方式进行调用即可。

本脚本改编自 LLaMA-Factory/examples/lora_single_gpu/llama3_lora_eval.yaml at main · hiyouga/LLaMA-Factory

如果是chat版本的模型

CUDA_VISIBLE_DEVICES=0 llamafactory-cli eval \
--model_name_or_path /models/Meta-Llama-3-8B-Instruct \
--template llama3 \
--task mmlu \
--split validation \
--lang en \
--n_shot 5 \
--batch_size 1

输出如下, 具体任务的指标定义请参考mmlu，cmmlu, ceval等任务原始的相关资料, 和llama3的官方报告基本一致

        Average: 63.64                                                                                                                                     
           STEM: 50.83
Social Sciences: 76.31
     Humanities: 56.63
          Other: 73.31

如果是base版本的模型，template改为fewshot即可

CUDA_VISIBLE_DEVICES=0 llamafactory-cli eval \
--model_name_or_path /models/Meta-Llama-3-8B \
--template fewshot \
--task mmlu \
--split validation \
--lang en \
--n_shot 5 \
--batch_size 1

AI 大模型研发与应用

LLaMA-Factory 使用指南：从环境校验到自定义数据集微调