LLaMA Factory 从入门到精通，一篇讲完

目录

一、LLaMA-Factory 简介

二、安装部署

三、数据微调

1、数据集的建立

2、数据集格式

3、模型参数

4、开始运行

5、导出模型

四、webui

评估预测与对话

导出

五、SFT 训练

命令行

六、LoRA 合并

合并

量化

七、推理

原始模型推理配置

微调模型推理配置

多模态模型

批量推理

八、评估

通用能力评估

NLG 评估

评估相关参数

一、LLaMA-Factory 简介

LLaMA Factory 是一个简单易用且高效的大型语言模型（Large Language Model）训练与微调平台。通过 LLaMA Factory，可以在无需编写任何代码的前提下，在本地完成上百种预训练模型的微调，框架特性包括：

• 模型种类：LLaMA、LLaVA、Mistral、Mixtral-MoE、Qwen、Yi、Gemma、Baichuan、ChatGLM、Phi 等等。
• 训练算法：（增量）预训练、（多模态）指令监督微调、奖励模型训练、PPO 训练、DPO 训练、KTO 训练、ORPO 训练等等。
• 运算精度：16 比特全参数微调、冻结微调、LoRA 微调和基于 AQLM/AWQ/GPTQ/LLM.int8/HQQ/EETQ 的 2/3/4/5/6/8 比特 QLoRA 微调。
• 优化算法：GaLore、BAdam、DoRA、LongLoRA、LLaMA Pro、Mixture-of-Depths、LoRA+、LoftQ 和 PiSSA。
• 加速算子：FlashAttention-2 和 Unsloth。
• 推理引擎：Transformers 和 vLLM。
• 实验监控：LlamaBoard、TensorBoard、Wandb、MLflow、SwanLab 等等。

二、安装部署

1、CUDA 安装

CUDA 是由 NVIDIA 创建的一个并行计算平台和编程模型，它让开发者可以使用 NVIDIA 的 GPU 进行高性能的并行计算。

首先，在 https://developer.nvidia.com/cuda-gpus 查看您的 GPU 是否支持CUDA

1、保证当前 Linux 版本支持CUDA. 在命令行中输入 uname -m && cat /etc/*release，应当看到类似的输出

#命令 uname -m && cat /etc/*release #输出结果： x86_64 DISTRIB_ID=Ubuntu DISTRIB_RELEASE=22.04

2、检查是否安装了 gcc . 在命令行中输入 gcc --version ，应当看到类似的输出

# 输入命令 gcc --version #查看结果 gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0

3、在以下网址下载所需的 CUDA，这里推荐12.2版本。 https://developer.nvidia.com/cuda-gpus 注意需要根据上述输出选择正确版本

如果您之前安装过 CUDA(例如为12.1版本)，需要先使用 sudo /usr/local/cuda-12.1/bin/cuda-uninstaller 卸载。如果该命令无法运行，可以直接：

# 卸载 CUDA sudo /usr/local/cuda-12.1/bin/cuda-uninstaller #如果无法运行需要执行以下命令 sudo rm -r /usr/local/cuda-12.1/ sudo apt clean && sudo apt autoclean # 卸载完成后运行以下命令并根据提示继续安装： wget https://developer.download.nvidia.com/compute/cuda/12.2.0/local_installers/cuda_12.2.0_535.54.03_linux.run sudo sh cuda_12.2.0_535.54.03_linux.run 

注意:在确定 CUDA 自带驱动版本与 GPU 是否兼容之前,建议取消 Driver 的安装

完成后输入 nvcc -V 检查是否出现对应的版本号，若出现则安装完成

2、LLaMA-Factory 安装

基础环境：ubuntu22.04 -cuda 12.4.0-python 3.11- pytorch 2.6.0 -1.26.0-llm

在安装 LLaMA-Factory 之前，请确保您安装了下列依赖:

运行以下指令以安装 LLaMA-Factory 及其依赖:

 # 创建python 环境 conda create -n llama_factory python=3.10 -y # 创建成功后切换到新的环境 conda activate llama_factory # 安装cuda pytorch等核心工具 conda install pytorch==2.2.2 torchvision==0.17.2 torchaudio==2.2.2 pytorch-cuda=11.8 -c pytorch -c nvidia pip3 install torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 pip install llmtuner # 安装llama_factory git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git cd LLaMA-Factory #安装环境依赖（官网） pip install -e ".[torch,metrics]" 

如果出现环境冲突，请尝试使用 pip install --no-deps -e . 解决   不依赖去安装；

或者 自己创建一个开发环境，指定python等相关版本,命令如上；

LLaMA-Factory 校验

完成安装后，可以通过使用 llamafactory-cli version 来快速校验安装是否成功

如果您能成功看到类似下面的界面，就说明安装成功了。

启动LLaMA-Factory  web的页面:

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

下载离线模型，一会进行训练时候填写到模型路径即可

#从魔搭社区下载 git clone https://www.modelscope.cn/Qwen/Qwen2.5-0.5B-Instruct.git

以下可以参考阅读：到此安装成功

LLaMA-Factory 高级选项

Windows

QLoRA

如果您想在 Windows 上启用量化 LoRA（QLoRA），请根据您的 CUDA 版本选择适当的 bitsandbytes 发行版本。

pip install https://github.com/jllllll/bitsandbytes-windows-webui/releases/download/wheels/bitsandbytes-0.41.2.post2-py3-none-win_amd64.whl 

FlashAttention-2

如果您要在 Windows 平台上启用 FlashAttention-2，请根据您的 CUDA 版本选择适当的 flash-attention 发行版本。

Extra Dependency

如果您有更多需求，请安装对应依赖

三、数据微调

dataset_info.json 包含了所有经过预处理的 本地数据集 以及 在线数据集。如果您希望使用自定义数据集，请 务必 在 dataset_info.json 文件中添加对数据集及其内容的定义。

目前我们支持 Alpaca 格式和 ShareGPT 格式的数据集。

指令监督微调数据集

指令监督微调(Instruct Tuning)通过让模型学习详细的指令以及对应的回答来优化模型在特定指令下的表现。

 instruction 列对应的内容为人类指令， input 列对应的内容为人类输入， output 列对应的内容为模型回答。下面是一个例子：在进行指令监督微调时， instruction 列对应的内容会与 input 列对应的内容拼接后作为最终的人类输入，即人类输入为 instruction\ninput。而 output 列对应的内容为模型回答。 在上面的例子中，人类的最终输入是：

"alpaca_zh_demo.json" { "instruction": "计算这些物品的总费用。 ", "input": "输入：汽车 - $3000，衣服 - $100，书 - $20。", "output": "汽车、衣服和书的总费用为 $3000 + $100 + $20 = $3120。" },

在进行指令监督微调时， instruction 列对应的内容会与 input 列对应的内容拼接后作为最终的人类输入，即人类输入为 instruction\ninput。而 output 列对应的内容为模型回答。在上面的例子中： 人类的最终输入是：

计算这些物品的总费用。 输入：汽车 - $3000，衣服 - $100，书 - $20。

模型的回答是：

汽车、衣服和书的总费用为 $3000 + $100 + $20 = $3120。

如果指定， system 列对应的内容将被作为系统提示词。

history 列是由多个字符串二元组构成的列表，分别代表历史消息中每轮对话的指令和回答。注意在指令监督微调时，历史消息中的回答内容也会被用于模型学习。

指令监督微调数据集 格式要求 如下：

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

下面提供一个 alpaca 格式 多轮 对话的例子，对于单轮对话只需省略 history 列即可。

[ { "instruction": "今天的天气怎么样？", "input": "", "output": "今天的天气不错，是晴天。", "history": [ [ "今天会下雨吗？", "今天不会下雨，是个好天气。" ], [ "今天适合出去玩吗？", "非常适合，空气质量很好。" ] ] } ]

"数据集名称": { "file_name": "data.json", "columns": { "prompt": "instruction", "query": "input", "response": "output", "system": "system", "history": "history" } }

预训练数据集

样例数据集： 预训练样例数据集

大语言模型通过学习未被标记的文本进行预训练，从而学习语言的表征。通常，预训练数据集从互联网上获得，因为互联网上提供了大量的不同领域的文本信息，有助于提升模型的泛化能力。 预训练数据集文本描述格式如下：

[ {"text": "document"}, {"text": "document"} ]

在预训练时，只有 text 列中的 内容 （即document）会用于模型学习。

对于上述格式的数据， dataset_info.json 中的 数据集描述 应为：

"数据集名称": { "file_name": "data.json", "columns": { "prompt": "text" } }

偏好数据集

偏好数据集用于奖励模型训练、DPO 训练和 ORPO 训练。对于系统指令和人类输入，偏好数据集给出了一个更优的回答和一个更差的回答。

一些研究 表明通过让模型学习“什么更好”可以使得模型更加迎合人类的需求。 甚至可以使得参数相对较少的模型的表现优于参数更多的模型。

偏好数据集需要在 chosen 列中提供更优的回答，并在 rejected 列中提供更差的回答，在一轮问答中其格式如下：

[ { "instruction": "人类指令（必填）", "input": "人类输入（选填）", "chosen": "优质回答（必填）", "rejected": "劣质回答（必填）" } ]

KTO 数据集

KTO数据集与偏好数据集类似，但不同于给出一个更优的回答和一个更差的回答，KTO数据集对每一轮问答只给出一个 true/false 的 label。 除了 instruction 以及 input 组成的人类最终输入和模型回答 output ，KTO 数据集还需要额外添加一个 kto_tag 列（true/false）来表示人类的反馈。

在一轮问答中其格式如下：

[ { "instruction": "人类指令（必填）", "input": "人类输入（选填）", "output": "模型回答（必填）", "kto_tag": "人类反馈 [true/false]（必填）" } ]

对于上述格式的数据， dataset_info.json 中的 数据集描述 应为：

"数据集名称": { "file_name": "data.json", "columns": { "prompt": "instruction", "query": "input", "response": "output", "kto_tag": "kto_tag" } }

多模态数据集

目前我们支持 多模态图像数据集、 视频数据集 以及 音频数据集 的输入。

图像数据集

多模态图像数据集需要额外添加一个 images 列，包含输入图像的路径。 注意图片的数量必须与文本中所有 <image> 标记的数量严格一致。

[ { "instruction": "人类指令（必填）", "input": "人类输入（选填）", "output": "模型回答（必填）", "images": [ "图像路径（必填）" ] } ]

视频数据集

多模态视频数据集需要额外添加一个 videos 列，包含输入视频的路径。 注意视频的数量必须与文本中所有 <video> 标记的数量严格一致。

[ { "instruction": "人类指令（必填）", "input": "人类输入（选填）", "output": "模型回答（必填）", "videos": [ "视频路径（必填）" ] } ]

对于上述格式的数据， dataset_info.json 中的 数据集描述 应为：

"数据集名称": { "file_name": "data.json", "columns": { "prompt": "instruction", "query": "input", "response": "output", "videos": "videos" } }

音频数据集

多模态音频数据集需要额外添加一个 audio 列，包含输入图像的路径。 注意音频的数量必须与文本中所有 <audio> 标记的数量严格一致。

[ { "instruction": "人类指令（必填）", "input": "人类输入（选填）", "output": "模型回答（必填）", "audios": [ "音频路径（必填）" ] } ]

对于上述格式的数据， dataset_info.json 中的 数据集描述 应为：

"数据集名称": { "file_name": "data.json", "columns": { "prompt": "instruction", "query": "input", "response": "output", "audios": "audios" } }

ShareGPT

针对不同任务，数据集格式要求如下：

• 指令监督微调
• 偏好训练
• OpenAI格式

我就不一一展示：

下面进入操作：

1、数据集的建立

所有的数据集都在lama-factory/data目录下

然后在llama-factory/data/dataset_info.json下加入此文件名；如下图

2、数据集格式

一般格式为如下标准格式格式:  

数据集参数说明：
instruction：该数据的说明
input：输入提的问题
output：他应该回答的内容

3、模型参数

其中一些参数。可以选择默认：

4、开始运行

其实设置完之后默认是在服务器上进行一个命令的执行，如下：

点击开始运行即可：

5、导出模型

四、webui

LLaMA-Factory 支持通过 WebUI 零代码微调大语言模型。 在完成 安装 后，您可以通过以下指令进入 WebUI:

llamafactory-cli webui

在开始训练模型之前，您需要指定的参数有：

1. 模型名称及路径
2. 训练阶段
3. 微调方法
4. 训练数据集
5. 学习率、训练轮数等训练参数
6. 微调参数等其他参数
7. 输出目录及配置路径

随后，您可以点击 开始 按钮开始训练模型。

评估预测与对话

模型训练完毕后，您可以通过在评估与预测界面通过指定 模型 及 适配器 的路径在指定数据集上进行评估。

您也可以通过在对话界面指定 模型、 适配器 及 推理引擎 后输入对话内容与模型进行对话观察效果。

导出

如果您对模型效果满意并需要导出模型，您可以在导出界面通过指定 模型、 适配器、 分块大小、 导出量化等级及校准数据集、 导出设备、 导出目录 等参数后点击 导出 按钮导出模型。

五、SFT 训练

命令行

您可以使用以下命令使用 examples/train_lora/llama3_lora_sft.yaml 中的参数进行微调：

llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml

也可以通过追加参数更新 yaml 文件中的参数:

llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml \ learning_rate=1e-5 \ logging_steps=1

examples/train_lora/llama3_lora_sft.yaml 提供了微调时的配置示例。该配置指定了模型参数、微调方法参数、数据集参数以及评估参数等。您需要根据自身需求自行配置。

### examples/train_lora/llama3_lora_sft.yaml model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct stage: sft do_train: true finetuning_type: lora lora_target: all dataset: identity,alpaca_en_demo template: llama3 cutoff_len: 1024 max_samples: 1000 overwrite_cache: true preprocessing_num_workers: 16 output_dir: saves/llama3-8b/lora/sft logging_steps: 10 save_steps: 500 plot_loss: true overwrite_output_dir: true per_device_train_batch_size: 1 gradient_accumulation_steps: 8 learning_rate: 1.0e-4 num_train_epochs: 3.0 lr_scheduler_type: cosine warmup_ratio: 0.1 bf16: true ddp_timeout: 180000000 val_size: 0.1 per_device_eval_batch_size: 1 eval_strategy: steps eval_steps: 500

备注

模型 model_name_or_path 、数据集 dataset 需要存在且与 template 相对应。

六、LoRA 合并

合并

当我们基于预训练模型训练好 LoRA 适配器后，我们不希望在每次推理的时候分别加载预训练模型和 LoRA 适配器，因此我们需要将预训练模型和 LoRA 适配器合并导出成一个模型，并根据需要选择是否量化。根据是否量化以及量化算法的不同，导出的配置文件也有所区别。

您可以通过 llamafactory-cli export merge_config.yaml 指令来合并模型。其中 merge_config.yaml 需要您根据不同情况进行配置。

examples/merge_lora/llama3_lora_sft.yaml 提供了合并时的配置示例。

### examples/merge_lora/llama3_lora_sft.yaml ### model model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct adapter_name_or_path: saves/llama3-8b/lora/sft template: llama3 finetuning_type: lora ### export export_dir: models/llama3_lora_sft export_size: 2 export_device: cpu export_legacy_format: false

备注

• 模型 model_name_or_path 需要存在且与 template 相对应。 adapter_name_or_path 需要与微调中的适配器输出路径 output_dir 相对应。
• 合并 LoRA 适配器时，不要使用量化模型或指定量化位数。您可以使用本地或下载的未量化的预训练模型进行合并。

量化

在完成模型合并并获得完整模型后，为了优化部署效果，人们通常会基于显存占用、使用成本和推理速度等因素，选择通过量化技术对模型进行压缩，从而实现更高效的部署。

量化（Quantization）通过数据精度压缩有效地减少了显存使用并加速推理。LLaMA-Factory 支持多种量化方法，包括:

• AQLM
• AWQ
• GPTQ
• QLoRA
• …

GPTQ 等后训练量化方法(Post Training Quantization)是一种在训练后对预训练模型进行量化的方法。我们通过量化技术将高精度表示的预训练模型转换为低精度的模型，从而在避免过多损失模型性能的情况下减少显存占用并加速推理，我们希望低精度数据类型在有限的表示范围内尽可能地接近高精度数据类型的表示，因此我们需要指定量化位数 export_quantization_bit 以及校准数据集 export_quantization_dataset。

备注

在进行模型合并时，请指定：

• model_name_or_path: 预训练模型的名称或路径
• template: 模型模板
• export_dir: 导出路径
• export_quantization_bit: 量化位数
• export_quantization_dataset: 量化校准数据集
• export_size: 最大导出模型文件大小
• export_device: 导出设备
• export_legacy_format: 是否使用旧格式导出

下面提供一个配置文件示例：

### examples/merge_lora/llama3_gptq.yaml ### model model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct template: llama3 ### export export_dir: models/llama3_gptq export_quantization_bit: 4 export_quantization_dataset: data/c4_demo.json export_size: 2 export_device: cpu export_legacy_format: false

QLoRA 是一种在 4-bit 量化模型基础上使用 LoRA 方法进行训练的技术。它在极大地保持了模型性能的同时大幅减少了显存占用和推理时间。

警告

不要使用量化模型或设置量化位数 quantization_bit

下面提供一个配置文件示例：

### examples/merge_lora/llama3_q_lora.yaml ### model model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct adapter_name_or_path: saves/llama3-8b/lora/sft template: llama3 finetuning_type: lora ### export export_dir: models/llama3_lora_sft export_size: 2 export_device: cpu export_legacy_format: false

七、推理

LLaMA-Factory 支持多种推理方式。

您可以使用 llamafactory-cli chat inference_config.yaml 或 llamafactory-cli webchat inference_config.yaml 进行推理与模型对话。对话时配置文件只需指定原始模型 model_name_or_path 和 template ，并根据是否是微调模型指定 adapter_name_or_path 和 finetuning_type。

如果您希望向模型输入大量数据集并保存推理结果，您可以启动 vllm 推理引擎对大量数据集进行快速的批量推理。您也可以通过 部署 api 服务的形式通过 api 调用来进行批量推理。

默认情况下，模型推理将使用 Huggingface 引擎。 您也可以指定 infer_backend: vllm 以使用 vllm 推理引擎以获得更快的推理速度。

备注

使用任何方式推理时，模型 model_name_or_path 需要存在且与 template 相对应。

原始模型推理配置

对于原始模型推理， inference_config.yaml 中 只需指定原始模型 model_name_or_path 和 template 即可。

### examples/inference/llama3.yaml model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct template: llama3 infer_backend: huggingface #choices： [huggingface, vllm]

微调模型推理配置

对于微调模型推理，除原始模型和模板外，还需要指定适配器路径 adapter_name_or_path 和微调类型 finetuning_type。

### examples/inference/llama3_lora_sft.yaml model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct adapter_name_or_path: saves/llama3-8b/lora/sft template: llama3 finetuning_type: lora infer_backend: huggingface #choices： [huggingface, vllm]

多模态模型

对于多模态模型，您可以运行以下指令进行推理。

llamafactory-cli webchat examples/inference/llava1_5.yaml

examples/inference/llava1_5.yaml 的配置示例如下：

model_name_or_path: llava-hf/llava-1.5-7b-hf template: vicuna infer_backend: huggingface #choices： [huggingface, vllm]

批量推理

您可以通过以下指令启动 vllm 推理引擎并使用数据集进行批量推理：

python scripts/vllm_infer.py --model_name_or_path path_to_merged_model --dataset alpaca_en_demo

下面是一个启动并调用 api 服务的示例：

您可以使用 API_PORT=8000 CUDA_VISIBLE_DEVICES=0 llamafactory-cli api examples/inference/llama3_lora_sft.yaml 启动 api 服务并运行以下示例程序进行调用：

# api_call_example.py from openai import OpenAI client = OpenAI(api_key="0",base_url="http://0.0.0.0:8000/v1") messages = [{"role": "user", "content": "Who are you?"}] result = client.chat.completions.create(messages=messages, model="meta-llama/Meta-Llama-3-8B-Instruct") print(result.choices[0].message)

八、评估

通用能力评估

在完成模型训练后，您可以通过 llamafactory-cli eval examples/train_lora/llama3_lora_eval.yaml 来评估模型效果。

配置示例文件 examples/train_lora/llama3_lora_eval.yaml 具体如下：

### examples/train_lora/llama3_lora_eval.yaml ### model model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct adapter_name_or_path: saves/llama3-8b/lora/sft # 可选项 ### method finetuning_type: lora ### dataset task: mmlu_test # mmlu_test, ceval_validation, cmmlu_test template: fewshot lang: en n_shot: 5 ### output save_dir: saves/llama3-8b/lora/eval ### eval batch_size: 4

NLG 评估

此外，您还可以通过 llamafactory-cli train examples/extras/nlg_eval/llama3_lora_predict.yaml 来获得模型的 BLEU 和 ROUGE 分数以评价模型生成质量。

配置示例文件 examples/extras/nlg_eval/llama3_lora_predict.yaml 具体如下：

### examples/extras/nlg_eval/llama3_lora_predict.yaml ### model model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct adapter_name_or_path: saves/llama3-8b/lora/sft ### method stage: sft do_predict: true finetuning_type: lora ### dataset eval_dataset: identity,alpaca_en_demo template: llama3 cutoff_len: 2048 max_samples: 50 overwrite_cache: true preprocessing_num_workers: 16 ### output output_dir: saves/llama3-8b/lora/predict overwrite_output_dir: true ### eval per_device_eval_batch_size: 1 predict_with_generate: true ddp_timeout: 180000000

同样，您也通过在指令 python scripts/vllm_infer.py --model_name_or_path path_to_merged_model --dataset alpaca_en_demo 中指定模型、数据集以使用 vllm 推理框架以取得更快的推理速度。

评估相关参数