LLaMAFactory 微调实战

• LLaMA Factory Github

• LLaMA Factory Documentation

微调前准备

框架下载

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

数据准备

{
  "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 页面

• 模型名称：基座模型

• 模型路径：从第三方平台下载好的模型存放路径， 建议写绝对路径，一般要到模型检查点层级，如：/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 这两个低秩矩阵的权重

• 若微调效果不理想，可以：
• 使用更强的预训练模型
• 增加数据量
• 优化数据质量（数据清洗、数据增强等，可学习相关论文如何实现）
• 调整训练参数，如学习率、训练轮数、优化器、批次大小等等

合并导出

命令行

环境变量

微调

修改配置文件

### 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，默认使用全部

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

报错处理

[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)

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"

推理

原始模型推理配置

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

微调模型推理配置

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

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

LoRA 合并

合并

### 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 适配器时，不要使用量化模型或指定量化位数。可以使用本地或下载的未量化的预训练模型进行合并。

量化

• AQLM

• AWQ

• GPTQ

• QLoRA

• …

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

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

评估相关参数

导出

修改配置文件

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