跳到主要内容
LLaMA Factory 大模型训练与微调完整教程 | 极客日志
Python AI 算法
LLaMA Factory 大模型训练与微调完整教程 LLaMA Factory 的使用指南，涵盖安装部署、数据准备、SFT 训练、LoRA 合并、推理及评估全流程。内容包括 CUDA 环境配置、Python 虚拟环境搭建、数据集格式规范（Alpaca/ShareGPT）、命令行与 WebUI 操作、模型量化与导出方法，以及基于 vLLM 的批量推理和通用能力评估。适合希望快速上手大模型微调的开发者参考。
咸鱼开飞机 发布于 2026/4/6 更新于 2026/5/20 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 等。
安装部署
CUDA 安装
CUDA 是由 NVIDIA 创建的一个并行计算平台和编程模型，它让开发者可以使用 NVIDIA 的 GPU 进行高性能的并行计算。
保证当前 Linux 版本支持 CUDA。在命令行中输入 uname -m && cat /etc/*release，应当看到类似的输出：
x86_64 DISTRIB_ID=Ubuntu DISTRIB_RELEASE=22.04
检查是否安装了 gcc。在命令行中输入 gcc --version，应当看到类似的输出：
gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0
下载所需的 CUDA 版本（推荐 12.2 或更高）。注意需要根据上述输出选择正确版本。
如果您之前安装过 CUDA，需要先卸载。如果命令无法运行，可以直接删除目录并清理缓存：
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 检查是否出现对应的版本号，若出现则安装完成。
LLaMA-Factory 安装
基础环境：Ubuntu 22.04, CUDA 12.x, Python 3.10+, PyTorch 2.x。
在安装 LLaMA-Factory 之前，请确保您安装了下列依赖。运行以下指令以安装 LLaMA-Factory 及其依赖：
conda create -n llama_factory python=3.10 -y
clone
cd
".[torch,metrics]"
如果出现环境冲突，请尝试使用 pip install --no-deps -e . 解决不依赖去安装；或者自己创建一个开发环境，指定 python 等相关版本。
LLaMA-Factory 校验 完成安装后，可以通过使用 llamafactory-cli version 来快速校验安装是否成功。
CUDA_VISIBLE_DEVICES=0 GRADIO_SHARE=1 GRADIO_SERVER_PORT=7860 llamafactory-cli webui
下载离线模型 训练时需要填写模型路径，可从 HuggingFace 或本地下载预训练模型。
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 发行版本。
名称 描述 torch 开源深度学习框架 PyTorch，广泛用于机器学习和人工智能研究中。 torch-npu PyTorch 的昇腾设备兼容包。 metrics 用于评估和监控机器学习模型性能。 deepspeed 提供了分布式训练所需的零冗余优化器。 bitsandbytes 用于大型语言模型量化。 hqq 用于大型语言模型量化。 eetq 用于大型语言模型量化。 gptq 用于加载 GPTQ 量化模型。 awq 用于加载 AWQ 量化模型。 aqlm 用于加载 AQLM 量化模型。 vllm 提供了高速并发的模型推理服务。 galore 提供了高效全参微调算法。 badam 提供了高效全参微调算法。 qwen 提供了加载 Qwen v1 模型所需的包。 modelscope 魔搭社区，提供了预训练模型和数据集的下载途径。 swanlab 开源训练跟踪工具 SwanLab，用于记录与可视化训练过程 dev 用于 LLaMA Factory 开发维护。
数据微调 dataset_info.json 包含了所有经过处理的本地数据集以及在线数据集。如果您希望使用自定义数据集，请务必在 dataset_info.json 文件中添加对数据集及其内容的定义。
目前我们支持 Alpaca 格式和 ShareGPT 格式的数据集。
指令监督微调数据集 指令监督微调 (Instruct Tuning) 通过让模型学习详细的指令以及对应的回答来优化模型在特定指令下的表现。
instruction 列对应的内容为人类指令。input 列对应的内容为人类输入。output 列对应的内容为模型回答。 在进行指令监督微调时，instruction 列对应的内容会与 input 列对应的内容拼接后作为最终的人类输入，即人类输入为 instruction\ninput。而 output 列对应的内容为模型回答。
如果指定，system 列对应的内容将被作为系统提示词。
history 列是由多个字符串二元组构成的列表，分别代表历史消息中每轮对话的指令和回答。
[
{
"instruction" : "人类指令（必填）" ,
"input" : "人类输入（选填）" ,
"output" : "模型回答（必填）" ,
"system" : "系统提示词（选填）" ,
"history" : [
[ "第一轮指令（选填）" , "第一轮回答（选填）" ] ,
[ "第二轮指令（选填）" , "第二轮回答（选填）" ]
]
}
]
下面提供一个 alpaca 格式多轮对话的例子，对于单轮对话只需省略 history 列即可。
[
{
"instruction" : "今天的天气怎么样？" ,
"input" : "" ,
"output" : "今天的天气不错，是晴天。" ,
"history" : [
[ "今天会下雨吗？" , "今天不会下雨，是个好天气。" ] ,
[ "今天适合出去玩吗？" , "非常适合，空气质量很好。" ]
]
}
]
在 dataset_info.json 中的数据集描述应为：
"数据集名称" : {
"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_tag" : "人类反馈 [true/false]（必填）"
}
]
多模态数据集 目前我们支持多模态图像数据集、视频数据集以及音频数据集的输入。
图像数据集 ：需要额外添加一个 images 列，包含输入图像的路径。注意图片的数量必须与文本中所有 <image> 标记的数量严格一致。视频数据集 ：需要额外添加一个 videos 列，包含输入视频的路径。注意视频的数量必须与文本中所有 <video> 标记的数量严格一致。音频数据集 ：需要额外添加一个 audio 列，包含输入音频的路径。注意音频的数量必须与文本中所有 <audio> 标记的数量严格一致。
WebUI LLaMA-Factory 支持通过 WebUI 零代码微调大语言模型。在完成安装后，您可以通过以下指令进入 WebUI：
模型名称及路径
训练阶段
微调方法
训练数据集
学习率、训练轮数等训练参数
微调参数等其他参数
输出目录及配置路径
评估预测与对话 模型训练完毕后，您可以通过在评估与预测界面通过指定模型及适配器的路径在指定数据集上进行评估。
您也可以通过在对话界面指定模型、适配器及推理引擎后输入对话内容与模型进行对话观察效果。
导出 如果您对模型效果满意并需要导出模型，您可以在导出界面通过指定模型、适配器、分块大小、导出量化等级及校准数据集、导出设备、导出目录等参数后点击 导出 按钮导出模型。
SFT 训练
命令行 您可以使用以下命令使用 examples/train_lora/llama3_lora_sft.yaml 中的参数进行微调：
llamafactory-cli train examples/train_lora/llama3_lora_sft.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 提供了微调时的配置示例。该配置指定了模型参数、微调方法参数、数据集参数以及评估参数等。您需要根据自身需求自行配置。
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 相对应。
名称 描述 model_name_or_path 模型名称或路径 stage 训练阶段，可选：rm(reward modeling), pt(pretrain), sft(Supervised Fine-Tuning), PPO, DPO, KTO, ORPO do_train true 用于训练，false 用于评估 finetuning_type 微调方式。可选：freeze, lora, full lora_target 采取 LoRA 方法的目标模块，默认值为 all。 dataset 使用的数据集，使用","分隔多个数据集 template 数据集模板，请保证数据集模板与模型相对应。 output_dir 输出路径 logging_steps 日志输出步数间隔 save_steps 模型断点保存间隔 overwrite_output_dir 是否允许覆盖输出目录 per_device_train_batch_size 每个设备上训练的批次大小 gradient_accumulation_steps 梯度积累步数 max_grad_norm 梯度裁剪阈值 learning_rate 学习率 lr_scheduler_type 学习率曲线，可选 linear, cosine, polynomial, constant 等。 num_train_epochs 训练周期数 bf16 是否使用 bf16 格式 warmup_ratio 学习率预热比例 warmup_steps 学习率预热步数 push_to_hub 是否推送模型到 Huggingface
LoRA 合并
合并 当我们基于预训练模型训练好 LoRA 适配器后，我们不希望在每次推理的时候分别加载预训练模型和 LoRA 适配器，因此我们需要将预训练模型和 LoRA 适配器合并导出成一个模型，并根据需要选择是否量化。
您可以通过 llamafactory-cli export merge_config.yaml 指令来合并模型。其中 merge_config.yaml 需要您根据不同情况进行配置。
examples/merge_lora/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
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) 是一种在训练后对预训练模型进行量化的方法。我们通过量化技术将高精度表示的预训练模型转换为低精度的模型，从而在避免过多损失模型性能的情况下减少显存占用并加速推理。
model_name_or_path: 预训练模型的名称或路径template: 模型模板export_dir: 导出路径export_quantization_bit: 量化位数export_quantization_dataset: 量化校准数据集export_size: 最大导出模型文件大小export_device: 导出设备export_legacy_format: 是否使用旧格式导出
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
template: llama3
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。
推理 您可以使用 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 即可。
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
template: llama3
infer_backend: huggingface
微调模型推理配置 对于微调模型推理，除原始模型和模板外，还需要指定适配器路径 adapter_name_or_path 和微调类型 finetuning_type。
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
多模态模型 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
批量推理 您可以通过以下指令启动 vllm 推理引擎并使用数据集进行批量推理：
python scripts/vllm_infer.py --model_name_or_path path_to_merged_model --dataset alpaca_en_demo
您可以使用 API_PORT=8000 CUDA_VISIBLE_DEVICES=0 llamafactory-cli api examples/inference/llama3_lora_sft.yaml 启动 api 服务并运行以下示例程序进行调用：
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 具体如下：
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b/lora/sft
finetuning_type: lora
task: mmlu_test
template: fewshot
lang: en
n_shot: 5
save_dir: saves/llama3-8b/lora/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 具体如下：
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b/lora/sft
stage: sft
do_predict: true
finetuning_type: lora
eval_dataset: identity,alpaca_en_demo
template: llama3
cutoff_len: 2048
max_samples: 50
overwrite_cache: true
preprocessing_num_workers: 16
output_dir: saves/llama3-8b/lora/predict
overwrite_output_dir: true
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 推理框架以取得更快的推理速度。
评估相关参数 参数名称 类型 介绍 task str 评估任务的名称，可选项有 mmlu_test, ceval_validation, cmmlu_test task_dir str 包含评估数据集的文件夹路径，默认值为 evaluation。 batch_size int 每个 GPU 使用的批量大小，默认值为 4。 seed int 用于数据加载器的随机种子，默认值为 42。 lang str 评估使用的语言，可选值为 en、zh。默认值为 en。 n_shot int few-shot 的示例数量，默认值为 5。 save_dir str 保存评估结果的路径，默认值为 None。如果该路径已经存在则会抛出错误。 download_mode str 评估数据集的下载模式，默认值为 DownloadMode.REUSE_DATASET_IF_EXISTS。如果数据集已经存在则重复使用，否则则下载。
相关免费在线工具 加密/解密文本 使用加密算法（如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
