微调前准备

框架下载

git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory

环境安装

conda create -n llama-factory python=3.10 -y

conda activate llama-factory

pip install -e ".[torch,metrics,bitsandbytes,hqq,swanlab]" --index-url https://pypi.tuna.tsinghua.edu.cn/simple

安装时的可选参数：

名称

描述

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 开发维护。

数据准备

数据格式根据 LLaMAFactory 官方要求格式来准备，有专门将文档处理成指定格式的项目：Easy Dataset；具体使用方法推荐参考官方文档。最终导出 json 或 jsonl 文件。

数据文件准备好之后，将数据文件放到 LLaMA-Factory/data 路径下，并配置路径下的 LLaMA-Factory/data/dataset_info.json 文件，将新增的数据集添加进去：

{
  "identity": {
    "file_name": "identity.json"
  },
  "alpaca_en_demo": {
    "file_name": "alpaca_en_demo.json"
  },
  "alpaca_zh_demo": {
    "file_name": "alpaca_zh_demo.json"
  },
  
  
  "how_searchers_are_made": {
    "file_name": "how_searchers_are_made.json"
  },

……
}

WebUI 微调

Web 页面

启动命令

llamafactory-cli webui

# 指定设备启动
CUDA_VISIBLE_DEVICES=0,2 llamafactory-cli webui

Web 页面

notion imagenotion image

  • 模型名称：基座模型
  • 模型路径：从第三方平台下载好的模型存放路径， 建议写绝对路径，一般要到模型检查点层级，如：/anjhon/Models/hub/models--Qwen--Qwen3-14B/snapshots/8268fe3026cb304910457689366670e803a6fd56
  • 微调方法：常用的有 LoRA、qLoRA等

训练

参数详解：

  • 学习率（Learning Rate）：决定了模型每次更新时权重改变的幅度。过大可能会错过最优解；过小会学得很慢或陷入局部最优解
  • 训练轮数（Epochs）：太少模型会欠拟合（没学好），太大会过拟合（学过头了）
  • 最大梯度范数（Max Gradient Norm）：当梯度的值超过这个范围时会被截断，防止梯度爆炸现象
  • 最大样本数（Max Samples）：每轮训练中最多使用的样本数
  • 计算类型（Computation Type）：在训练时使用的数据类型，常见的有 float32 和 float16。在性能和精度之间找平衡
  • 截断长度（Truncation Length）：处理长文本时如果太长超过这个阈值的部分会被截断掉，避免内存溢出
  • 批处理大小（Batch Size）：由于内存限制，每轮训练我们要将训练集数据分批次送进去，这个批次大小就是 Batch Size
  • 梯度累积（Gradient Accumulation）：默认情况下模型会在每个 batch 处理完后进行一次更新一个参数，但你可以通过设置这个梯度累计，让他直到处理完多个小批次的数据后才进行一次更新
  • 验证集比例（Validation Set Proportion）：数据集分为训练集和验证集两个部分，训练集用来学习训练，验证集用来验证学习效果如何
  • 学习率调节器（Learning Rate Scheduler）：在训练的过程中帮你自动调整优化学习率

设置好参数和模型之后就可以开始训练了。

评估

  • 观察损失曲线的变化；观察最终损失
  • 在交互页面上通过预测/对话等方式测试微调好的效果
  • 检查点：保存的是模型在训练过程中的一个中间状态，包含了模型权重、训练过程中使用的配置（如学习率、批次大小）等信息，对LoRA来说，检查点包含了训练得到的 B 和 A 这两个低秩矩阵的权重
  • 若微调效果不理想，可以：
    • 使用更强的预训练模型
    • 增加数据量
    • 优化数据质量（数据清洗、数据增强等，可学习相关论文如何实现）
    • 调整训练参数，如学习率、训练轮数、优化器、批次大小等等

合并导出

在页面上配置导出路径，导出即可

命令行

环境变量

名称

类型

介绍

API_HOST

API

API 服务器监听的主机地址

API_PORT

API

API 服务器监听的端口号

API_KEY

API

访问 API 的密码。

API_MODEL_NAME

API

指定 API 服务要加载和使用的模型名称

API_VERBOSE

API

控制 API 日志的详细程度

FASTAPI_ROOT_PATH

API

设置 FastAPI 应用的根路径

MAX_CONCURRENT

API

API 的最大并发请求数。

DISABLE_VERSION_CHECK

General

是否禁用启动时的版本检查。

FORCE_CHECK_IMPORTS

General

强制检查可选的导入

ALLOW_EXTRA_ARGS

General

允许在命令行中传递额外参数

LLAMAFACTORY_VERBOSITY

General

设置 LLaMA-Factory 的日志级别(“DEBUG”,”INFO”,”WARN”)

USE_MODELSCOPE_HUB

General

优先使用 ModelScope 下载模型/数据集或使用缓存路径中的模型/数据集

USE_OPENMIND_HUB

General

优先使用 Openmind 下载模型/数据集或使用缓存路径中的模型/数据集

USE_RAY

General

是否使用 Ray 进行分布式执行或任务管理。

RECORD_VRAM

General

是否记录 VRAM 使用情况。

OPTIM_TORCH

General

是否表示启用特定的 PyTorch 优化。

NPU_JIT_COMPILE

General

是否为 NPU启用 JIT 编译。

CUDA_VISIBLE_DEVICES

General

GPU 选择。

ASCEND_RT_VISIBLE_DEVICES

General

NPU 选择。

FORCE_TORCHRUN

Torchrun

是否强制使用 torchrun 启动脚本

MASTER_ADDR

Torchrun

Torchrun部署中主节点 (master node) 的网络地址

MASTER_PORT

Torchrun

Torchrun部署中主节点用于通信的端口号

NNODES

Torchrun

参与分布式部署的总节点数量

NODE_RANK

Torchrun

当前节点在所有节点中的 rank，通常从 0 到 NNODES-1。

NPROC_PER_NODE

Torchrun

每个节点上的 GPU 数

WANDB_DISABLED

Log

是否禁用 wandb

WANDB_PROJECT

Log

设置 wandb 中的项目名称。

WANDB_API_KEY

Log

访问 wandb 的 api key

GRADIO_SHARE

Web UI

是否创建一个可共享的 webui 链接

GRADIO_SERVER_NAME

Web UI

设置 Gradio 服务器 IP 地址（例如 0.0.0.0）

GRADIO_SERVER_PORT

Web UI

设置 Gradio 服务器的端口

GRADIO_ROOT_PATH

Web UI

设置 Gradio 应用的根路径

GRADIO_IPV6

Web UI

启用 Gradio 服务器的 IPv6 支持

ENABLE_SHORT_CONSOLE

Setting

支持使用 lmf 表示 llamafactory-cli

微调

修改配置文件

命令行微调相较于 webui 更自由、定制化程度更高

根据官方项目中提供的模板：LLaMA-Factory/examples/train_qlora/llama3_lora_sft_otfq.yaml 进行复制调整，最终调整如下：

### model
model_name_or_path: /anjhon/LLaMA-Factory/models/hub/models--Qwen--Qwen3-14B/snapshots/8268fe3026cb304910457689366670e803a6fd56
quantization_bit: 4  # choices: [8 (bnb/hqq/eetq), 4 (bnb/hqq), 3 (hqq), 2 (hqq)]
quantization_method: bnb  # choices: [bnb, hqq, eetq]
trust_remote_code: true

### method
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 8
lora_target: all

### dataset
dataset: how_searchers_are_made
template: qwen3
cutoff_len: 2048
max_samples: 1000
overwrite_cache: true
preprocessing_num_workers: 16
dataloader_num_workers: 4

### output
output_dir: saves/qwen3-14b/lora/sft
logging_steps: 10
save_steps: 500
plot_loss: true
overwrite_output_dir: true
save_only_model: false
report_to: none  # choices: [none, wandb, tensorboard, swanlab, mlflow]

### train
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

### eval
# val_size: 0.1
# per_device_eval_batch_size: 1
# eval_strategy: steps
# eval_steps: 500

训练启动

启动命令

CUDA_VISIBLE_DEVICES=0,2 llamafactory-cli train examples/train_qlora/qwen3_14_lora_sft_otfq.yaml
  • CUDA_VISIBLE_DEVICES：指定用来训练的 GPU，默认使用全部

在启动命令后还可追加参数更新 yaml 文件中的参数：

CUDA_VISIBLE_DEVICES=0,2 llamafactory-cli train examples/train_qlora/qwen3_14_lora_sft_otfq.yaml learning_rate=1e-5 logging_steps=1

更多可选参数如下（基本都是 .yaml 文件中有的参数）：

名称

描述

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

报错处理

报错一：

OSError: Not enough disk space. Needed: Unknown size (download: Unknown size, generated: Unknown size, post-processed: Unknown size)

[rank0]: Traceback (most recent call last):
[rank0]:   File "/nfsdata/DataSynthesis_/llafat/LLaMA-Factory/src/llamafactory/launcher.py", line 23, in <module>
[rank0]:     launch()
[rank0]:   File "/nfsdata/DataSynthesis_/llafat/LLaMA-Factory/src/llamafactory/launcher.py", line 19, in launch
[rank0]:     run_exp()
[rank0]:   File "/nfsdata/DataSynthesis_/llafat/LLaMA-Factory/src/llamafactory/train/tuner.py", line 110, in run_exp
[rank0]:     _training_function(config={"args": args, "callbacks": callbacks})
[rank0]:   File "/nfsdata/DataSynthesis_/llafat/LLaMA-Factory/src/llamafactory/train/tuner.py", line 72, in _training_function
[rank0]:     run_sft(model_args, data_args, training_args, finetuning_args, generating_args, callbacks)
[rank0]:   File "/nfsdata/DataSynthesis_/llafat/LLaMA-Factory/src/llamafactory/train/sft/workflow.py", line 51, in run_sft
[rank0]:     dataset_module = get_dataset(template, model_args, data_args, training_args, stage="sft", **tokenizer_module)
[rank0]:   File "/nfsdata/DataSynthesis_/llafat/LLaMA-Factory/src/llamafactory/data/loader.py", line 304, in get_dataset
[rank0]:     dataset = _get_merged_dataset(data_args.dataset, model_args, data_args, training_args, stage)
[rank0]:   File "/nfsdata/DataSynthesis_/llafat/LLaMA-Factory/src/llamafactory/data/loader.py", line 182, in _get_merged_dataset
[rank0]:     datasets[dataset_name] = _load_single_dataset(dataset_attr, model_args, data_args, training_args)
[rank0]:   File "/nfsdata/DataSynthesis_/llafat/LLaMA-Factory/src/llamafactory/data/loader.py", line 131, in _load_single_dataset
[rank0]:     dataset = load_dataset(
[rank0]:   File "/root/miniconda3/envs/llafat/lib/python3.10/site-packages/datasets/load.py", line 2084, in load_dataset
[rank0]:     builder_instance.download_and_prepare(
[rank0]:   File "/root/miniconda3/envs/llafat/lib/python3.10/site-packages/datasets/builder.py", line 876, in download_and_prepare
[rank0]:     raise OSError(
[rank0]: OSError: Not enough disk space. Needed: Unknown size (download: Unknown size, generated: Unknown size, post-processed: Unknown size)
[rank1]: Traceback (most recent call last):
[rank1]:   File "/nfsdata/DataSynthesis_/llafat/LLaMA-Factory/src/llamafactory/launcher.py", line 23, in <module>
[rank1]:     launch()
[rank1]:   File "/nfsdata/DataSynthesis_/llafat/LLaMA-Factory/src/llamafactory/launcher.py", line 19, in launch
[rank1]:     run_exp()
[rank1]:   File "/nfsdata/DataSynthesis_/llafat/LLaMA-Factory/src/llamafactory/train/tuner.py", line 110, in run_exp
[rank1]:     _training_function(config={"args": args, "callbacks": callbacks})
[rank1]:   File "/nfsdata/DataSynthesis_/llafat/LLaMA-Factory/src/llamafactory/train/tuner.py", line 72, in _training_function
[rank1]:     run_sft(model_args, data_args, training_args, finetuning_args, generating_args, callbacks)
[rank1]:   File "/nfsdata/DataSynthesis_/llafat/LLaMA-Factory/src/llamafactory/train/sft/workflow.py", line 51, in run_sft
[rank1]:     dataset_module = get_dataset(template, model_args, data_args, training_args, stage="sft", **tokenizer_module)
[rank1]:   File "/nfsdata/DataSynthesis_/llafat/LLaMA-Factory/src/llamafactory/data/loader.py", line 304, in get_dataset
[rank1]:     dataset = _get_merged_dataset(data_args.dataset, model_args, data_args, training_args, stage)
[rank1]:   File "/nfsdata/DataSynthesis_/llafat/LLaMA-Factory/src/llamafactory/data/loader.py", line 182, in _get_merged_dataset
[rank1]:     datasets[dataset_name] = _load_single_dataset(dataset_attr, model_args, data_args, training_args)
[rank1]:   File "/nfsdata/DataSynthesis_/llafat/LLaMA-Factory/src/llamafactory/data/loader.py", line 131, in _load_single_dataset
[rank1]:     dataset = load_dataset(
[rank1]:   File "/root/miniconda3/envs/llafat/lib/python3.10/site-packages/datasets/load.py", line 2084, in load_dataset
[rank1]:     builder_instance.download_and_prepare(
[rank1]:   File "/root/miniconda3/envs/llafat/lib/python3.10/site-packages/datasets/builder.py", line 876, in download_and_prepare
[rank1]:     raise OSError(
[rank1]: OSError: Not enough disk space. Needed: Unknown size (download: Unknown size, generated: Unknown size, post-processed: Unknown size)

解决一：

日志中可以看出是在加载数据集的时候提示磁盘空间不足，但是明明使用的是已经下载好的模型和数据，而且检查当前路径下的可用空间是足够的；

在 github 仓库的 issue 中找到解决方法，在启动命令后面重新指定 cache_dir 即可（将 cache 路径指向 LLaMAFactory 路径下的 cache）：

CUDA_VISIBLE_DEVICES=0,2 llamafactory-cli train examples/train_qlora/qwen3_14_lora_sft_otfq.yaml cache_dir="/nfsdata/DataSynthesis_/llafat/LLaMA-Factory/cache"

推理

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

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

原始模型推理配置

对于原始模型推理， 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]

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。

### 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

合并相关参数

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

评估

通用能力评估

修改配置文件

### 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

执行评估

llamafactory-cli eval examples/train_lora/llama3_lora_eval.yaml

NLG 评估

修改配置文件

### 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

执行评估

llamafactory-cli train examples/extras/nlg_eval/llama3_lora_predict.yaml

评估相关参数

参数名称

类型

介绍

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_modes

str

评估数据集的下载模式，默认值为 DownloadMode.REUSE_DATASET_IF_EXISTS。如果数据集已经存在则重复使用，否则则下载。

导出

修改配置文件

根据合并配置样例文件：LLaMA-Factory/examples/merge_lora/llama3_lora_sft.yaml 进行修改：

### Note: DO NOT use quantized model or quantization_bit when merging lora adapters

### model
model_name_or_path: /anjhon/LLaMA-Factory/models/hub/models--Qwen--Qwen3-14B/snapshots/8268fe3026cb304910457689366670e803a6fd56
adapter_name_or_path: saves/qwen3-14b/lora/sft
template: qwen3
trust_remote_code: true

### export
export_dir: output/qwen3-14b_sft
export_size: 5
export_device: cpu  # choices: [cpu, auto]
export_legacy_format: false
  • model_name_or_path：基座模型路径
  • adapter_name_or_path：微调后的保存路径（与训练配置文件中保持一致）
  • template: 模型模板
  • export_dir: 合并后的导出路径
  • export_quantization_bit: 量化位数
  • export_quantization_dataset: 量化校准数据集
  • export_size: 最大导出模型文件大小
  • export_device: 导出设备
  • export_legacy_format: 是否使用旧格式导出

执行合并

llamafactory-cli export examples/merge_lora/qwen3_14_lora_sft.yaml