LlamaFactory 示例实战指南：LoRA、QLoRA、全参微调、模型导出与推理部署

LlamaFactory 在 examples 目录下维护了一套覆盖主流微调范式的完整示例集合，从 LoRA、QLoRA 到全参微调、偏好对齐训练，再到 LoRA 合并、GPTQ 量化导出与多后端推理部署。本文以 examples/README.md 为骨架，逐条解读其中的命令与配置，并结合仓库内真实 YAML 配置文件与源码入口，帮助你在单卡、多卡、多机及 NPU 环境下直接复制可用的训练与部署方案。

一、基本用法与参数覆盖机制

所有示例命令都要求在 LlamaFactory 项目根目录下执行。CLI 入口是 llamafactory-cli，其实现位于 src/llamafactory/cli.py，根据环境变量 USE_V1 决定分发到新版还是常规 launcher，因此同一套命令在新旧两套训练引擎间保持兼容。

指定计算设备的方式是环境变量：GPU 使用 CUDA_VISIBLE_DEVICES，NPU（昇腾）使用 ASCEND_RT_VISIBLE_DEVICES；不设置时默认使用全部可见设备。

基础用法——传入一个 YAML 配置文件即可启动训练：

llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml

进阶用法——命令行参数可以覆盖 YAML 中的同名配置，例如调整学习率与日志步数：

CUDA_VISIBLE_DEVICES=0,1 llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml \
    learning_rate=1e-5 \
    logging_steps=1

也可以直接执行封装好的 shell 脚本：

bash examples/train_lora/qwen3_lora_sft.sh

配置文件结构解析

以 examples/train_lora/qwen3_lora_sft.yaml 为例，仓库中的示例配置统一分为 model / method / dataset / output / train / eval 六个区块，理解这一结构后所有示例配置都可举一反三：

### model
model_name_or_path: Qwen/Qwen3-4B-Instruct-2507
trust_remote_code: true

### method
stage: sft                # 训练阶段
do_train: true
finetuning_type: lora     # lora / full / freeze
lora_rank: 8
lora_target: all          # 对全部线性层注入 LoRA

### dataset
dataset: identity,alpaca_en_demo   # 在 data/dataset_info.json 中注册的数据集
template: qwen3_nothink            # 对话模板
cutoff_len: 2048                   # 最大截断长度
max_samples: 1000                  # 演示用，限制样本数
preprocessing_num_workers: 16

### output
output_dir: saves/qwen3-4b/lora/sft
logging_steps: 10
save_steps: 500
plot_loss: true
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

### eval
# eval_dataset: alpaca_en_demo
# val_size: 0.1
# eval_strategy: steps
# eval_steps: 500

几个值得注意的细节：

• dataset 字段引用的数据集名必须先在 data/dataset_info.json 中注册，仓库内置了 identity.json、alpaca_en_demo.json、dpo_en_demo.json、kto_en_demo.json 等演示数据；
• report_to 支持 wandb、tensorboard、swanlab、mlflow 等多种实验追踪后端；
• eval 区块默认注释，取消注释即可在训练中进行周期性评估。

二、LoRA 微调全场景

继续预训练（Continual Pre-Training）

llamafactory-cli train examples/train_lora/qwen3_lora_pretrain.yaml

监督微调（SFT）

llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml

多模态监督微调

使用 Qwen3-VL 的视觉语言模型做 LoRA SFT：

llamafactory-cli train examples/train_lora/qwen3vl_lora_sft.yaml

偏好对齐训练：DPO / ORPO / SimPO

同一份配置文件即可切换三种偏好优化损失，见 examples/train_lora/qwen3_lora_dpo.yaml 中的关键参数：

llamafactory-cli train examples/train_lora/qwen3_lora_dpo.yaml

stage: dpo
pref_beta: 0.1                  # DPO 的 KL 惩罚系数
pref_loss: sigmoid              # choices: [sigmoid (dpo), orpo, simpo]
dataset: dpo_en_demo            # 偏好对数据
learning_rate: 5.0e-6           # 偏好训练常用更小学习率

多模态场景同理：

llamafactory-cli train examples/train_lora/qwen3vl_lora_dpo.yaml

奖励建模与 KTO

llamafactory-cli train examples/train_lora/qwen3_lora_reward.yaml   # 奖励模型
llamafactory-cli train examples/train_lora/qwen3_lora_kto.yaml     # KTO 训练

大数据集预处理（tokenized_path）

对于大规模数据集，先单独执行一次训练配置完成 tokenization 落盘，之后再通过配置中的 tokenized_path 直接加载预处理结果，可显著节省启动时间。参见 examples/train_lora/qwen3_preprocess.yaml：

llamafactory-cli train examples/train_lora/qwen3_preprocess.yaml

### dataset
dataset: identity,alpaca_en_demo
template: qwen3_nothink
cutoff_len: 2048
tokenized_path: saves/qwen3-4b/dataset/sft   # 预处理数据落盘路径

多机 LoRA SFT

使用 FORCE_TORCHRUN=1 启用 torchrun 启动方式，并在两台机器上分别执行（各自设置不同的 NODE_RANK）：

FORCE_TORCHRUN=1 NNODES=2 NODE_RANK=0 MASTER_ADDR=192.168.0.1 MASTER_PORT=29500 llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml
FORCE_TORCHRUN=1 NNODES=2 NODE_RANK=1 MASTER_ADDR=192.168.0.1 MASTER_PORT=29500 llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml

其中 MASTER_ADDR/MASTER_PORT 是节点 0 的地址与端口，各节点需保证网络互通。

DeepSpeed ZeRO-3 权重分片

LoRA 训练同样可以启用 DeepSpeed ZeRO-3 进行权重分片，配置见 examples/train_lora/qwen3_lora_sft_ds3.yaml，与基础 LoRA 配置的差异仅在 method 区块中多出一行：

FORCE_TORCHRUN=1 llamafactory-cli train examples/train_lora/qwen3_lora_sft_ds3.yaml

deepspeed: examples/deepspeed/ds_z3_config.json  # choices: [ds_z0_config.json, ds_z2_config.json, ds_z3_config.json]

仓库在 examples/deepspeed/ 下提供了 ds_z0、ds_z2、ds_z3 及多种 offload 变体的现成配置，可直接替换引用。

基于 Ray 的多 GPU 训练

通过 USE_RAY=1 环境变量启用 Ray 启动器，见 examples/train_lora/qwen3_lora_sft_ray.yaml：

USE_RAY=1 llamafactory-cli train examples/train_lora/qwen3_lora_sft_ray.yaml

### ray
ray_num_workers: 4  # Number of GPUs to use.
# ray_init_kwargs:
#   runtime_env:
#     env_vars:
#       <YOUR-ENV-VAR-HERE>: "<YOUR-ENV-VAR-HERE>"
#     pip:
#       - emoji

Ray 方案还支持 dataset_dir: REMOTE:llamafactory/demo_data 这种远端数据源写法，适合多机共享同一数据集的场景。

三、QLoRA 量化微调

在 4-bit/8-bit 量化基座上训练 LoRA，可将显存需求压缩到消费级 GPU 可承受的范围。推荐方式是 Bitsandbytes/HQQ/EETQ 在线量化，示例为 examples/train_qlora/qwen3_lora_sft_otfq.yaml：

llamafactory-cli train examples/train_qlora/qwen3_lora_sft_otfq.yaml

其核心是 model 区块的两个量化参数：

quantization_bit: 4  # choices: [8 (bnb/hqq/eetq), 4 (bnb/hqq), 3 (hqq), 2 (hqq)]
quantization_method: bnb  # choices: [bnb, hqq, eetq]

其余字段（lora_rank、lora_target、数据集、训练超参）与非量化 LoRA 配置一致。此外还有针对特定量化格式的变体：

# 昇腾 NPU 上的 4-bit Bitsandbytes 量化 SFT
llamafactory-cli train examples/train_qlora/qwen3_lora_sft_bnb_npu.yaml

# 4/8-bit GPTQ 量化模型上的 SFT
llamafactory-cli train examples/train_qlora/llama3_lora_sft_gptq.yaml

# 4-bit AWQ 量化模型上的 SFT
llamafactory-cli train examples/train_qlora/llama3_lora_sft_awq.yaml

# 2-bit AQLM 量化模型上的 SFT
llamafactory-cli train examples/train_qlora/llama3_lora_sft_aqlm.yaml

GPTQ/AWQ/AQLM 要求基座模型本身已经是该格式导出好的量化权重（如 Qwen/Qwen3-4B-GPTQ-4bit 等），与 bnb/hqq/eetq 的运行时在线量化不同；各格式的额外依赖分别在 requirements/gptq.txt、requirements/aqlm.txt 等文件中声明，安装时需要单独拉取。

四、全参微调

单节点全参 SFT

全参训练对显存需求最高，官方示例默认搭配 DeepSpeed ZeRO-3，见 examples/train_full/qwen3_full_sft.yaml。与 LoRA 版本相比，关键差异是 finetuning_type: full、去掉了 LoRA 参数，并引入 DeepSpeed 配置；学习率也从 1e-4 降到 1e-5（全参微调的常规量级）：

FORCE_TORCHRUN=1 llamafactory-cli train examples/train_full/qwen3_full_sft.yaml

### method
stage: sft
do_train: true
finetuning_type: full
deepspeed: examples/deepspeed/ds_z3_config.json

### train
gradient_accumulation_steps: 2   # 比 LoRA 示例更小的累积步数
learning_rate: 1.0e-5

多机全参 SFT

FORCE_TORCHRUN=1 NNODES=2 NODE_RANK=0 MASTER_ADDR=192.168.0.1 MASTER_PORT=29500 llamafactory-cli train examples/train_full/qwen3_full_sft.yaml
FORCE_TORCHRUN=1 NNODES=2 NODE_RANK=1 MASTER_ADDR=192.168.0.1 MASTER_PORT=29500 llamafactory-cli train examples/train_full/qwen3_full_sft.yaml

弹性容错多机训练

在至少 MIN_NNODES 台、至多 MAX_NNODES 台机器上执行同一条命令，配合 MAX_RESTARTS 失败重试次数，即可启动弹性作业；RDZV_ID 是所有参与节点共享的唯一作业 ID。参数语义与 torchrun 弹性启动文档一致：

FORCE_TORCHRUN=1 MIN_NNODES=1 MAX_NNODES=3 MAX_RESTARTS=3 RDZV_ID=llamafactory MASTER_ADDR=192.168.0.1 MASTER_PORT=29500 llamafactory-cli train examples/train_full/qwen3_full_sft.yaml

多模态全参 SFT

FORCE_TORCHRUN=1 llamafactory-cli train examples/train_full/qwen3vl_full_sft.yaml

五、LoRA 合并与模型量化导出

合并 LoRA 适配器

注意：合并 LoRA 时不要使用量化模型，也不要设置 quantization_bit。

llamafactory-cli export examples/merge_lora/qwen3_lora_sft.yaml

导出配置 examples/merge_lora/qwen3_lora_sft.yaml 的核心字段：

model_name_or_path: Qwen/Qwen3-4B-Instruct-2507
adapter_name_or_path: saves/qwen3-4b/lora/sft   # 训练产出的 LoRA 适配器
template: qwen3_nothink

### export
export_dir: saves/qwen3_sft_merged
export_size: 5             # 按该大小分片保存
export_device: cpu         # choices: [cpu, auto]，CPU 合并可节省显存
export_legacy_format: false

使用 AutoGPTQ 量化导出

将全精度模型导出为 GPTQ 4-bit 量化权重，见 examples/merge_lora/qwen3_gptq.yaml：

llamafactory-cli export examples/merge_lora/qwen3_gptq.yaml

### export
export_dir: saves/qwen3_gptq
export_quantization_bit: 4
export_quantization_dataset: data/c4_demo.jsonl   # 量化校准数据
export_size: 5
export_device: cpu
export_legacy_format: false

export_quantization_dataset 指定的校准集用于统计权重量化的数值分布，仓库内置的 data/c4_demo.jsonl 可直接使用。

导出 Ollama modelfile

对已导出的全精度 checkpoint 运行 export，可生成 Ollama 所需的 modelfile，便于将自训模型注册到本地 Ollama 服务：

llamafactory-cli export examples/merge_lora/qwen3_full_sft.yaml

其配置 examples/merge_lora/qwen3_full_sft.yaml 中 model_name_or_path 指向训练产出的全参 checkpoint 目录（saves/qwen3-4b/full/sft），其余 export 字段与上述一致。

六、推理与部署微调后的模型

使用 vLLM 多 GPU 批量评测

先用 vLLM 批量生成预测，再用评测脚本计算 BLEU/ROUGE：

python scripts/vllm_infer.py --model_name_or_path Qwen/Qwen3-4B-Instruct-2507 --template qwen3_nothink --dataset alpaca_en_demo
python scripts/eval_bleu_rouge.py generated_predictions.jsonl

对应脚本为 scripts/vllm_infer.py 与 scripts/eval_bleu_rouge.py。

CLI / Web UI 聊天框

llamafactory-cli chat examples/inference/qwen3_lora_sft.yaml      # 终端聊天
llamafactory-cli webchat examples/inference/qwen3_lora_sft.yaml   # Gradio Web UI

启动 OpenAI 风格 API

llamafactory-cli api examples/inference/qwen3_lora_sft.yaml

三种部署方式共用同一份推理配置 examples/inference/qwen3_lora_sft.yaml：

model_name_or_path: Qwen/Qwen3-4B-Instruct-2507
adapter_name_or_path: saves/qwen3-4b/lora/sft
template: qwen3_nothink
infer_backend: huggingface  # choices: [huggingface, vllm, sglang, ktransformers]
trust_remote_code: true

其中 infer_backend 可切换为 vllm 或 sglang 以获得更高吞吐，仓库内 src/llamafactory/chat/vllm_engine.py、src/llamafactory/chat/sglang_engine.py 分别是对应推理引擎的实现；vLLM/SGLang 的额外依赖在 requirements/vllm.txt 与 requirements/sglang.txt 中声明。

七、进阶训练方法（Extras）

examples/extras/ 目录汇集了若干论文级训练技巧的落地配置，每个方法都有独立的 requirements 文件，安装对应依赖后即可直接训练：

# 显存高效的低秩梯度优化器
llamafactory-cli train examples/extras/galore/llama3_full_sft.yaml      # GaLore

llamafactory-cli train examples/extras/apollo/llama3_full_sft.yaml      # APOLLO

llamafactory-cli train examples/extras/badam/llama3_full_sft.yaml      # BAdam（批量自适应参数微调）

llamafactory-cli train examples/extras/adam_mini/qwen2_full_sft.yaml    # Adam-mini

llamafactory-cli train examples/extras/muon/qwen2_full_sft.yaml        # Muon 优化器

llamafactory-cli train examples/extras/loraplus/llama3_lora_sft.yaml   # LoRA+（差异化学习率）

llamafactory-cli train examples/extras/pissa/llama3_lora_sft.yaml      # PiSSA（SVD 初始化 LoRA）

llamafactory-cli train examples/extras/mod/llama3_full_sft.yaml        # Mixture-of-Depths

# LLaMA-Pro：先扩展层数，再冻结微调
bash examples/extras/llama_pro/expand.sh
llamafactory-cli train examples/extras/llama_pro/llama3_freeze_sft.yaml

# FSDP + QLoRA（需先运行初始化脚本）
bash examples/extras/fsdp_qlora/train.sh

llamafactory-cli train examples/extras/oft/llama3_oft_sft.yaml         # OFT（正交微调）

llamafactory-cli train examples/extras/qoft/llama3_oft_sft_bnb_npu.yaml  # QOFT（量化正交微调，NPU）

这些方法对应的可选依赖声明在 requirements/ 目录下，如 requirements/galore.txt、requirements/apollo.txt、requirements/badam.txt、requirements/adam-mini.txt 等；其中 Muon 优化器的实现位于 src/llamafactory/third_party/muon/，LLaMA-Pro 的层扩展脚本为 scripts/llama_pro.py。

八、延伸阅读

仓库内还有若干未在本文命令清单中展开的示例目录，可按需查看：

• examples/accelerate/：FSDP / FSDP2 单文件加速配置（含 Qwen3.5 MoE 变体）；
• examples/ascend/：昇腾 NPU 上的 Qwen3 系列 FSDP/FSDP2 训练示例；
• examples/megatron/ 与 examples/megatron_bridge/：Megatron 大规模并行训练配置；
• examples/ktransformers/：CPU+GPU 混合推理框架下的 MoE 量化训练；
• examples/v1/：新版（v1）训练引擎的批处理策略、冻结训练与 FSDP2 配置；
• examples/merge_lora/qwen3_gptq.yaml 等 merge 目录下的多模型导出示例。

总结

examples/README.md 提供了 LlamaFactory 从数据预处理、LoRA/QLoRA/全参训练、偏好对齐，到适配器合并、GPTQ 量化导出与多后端推理部署的完整命令清单。仓库中每个命令都对应一份可直接运行的 YAML 配置，且统一遵循「命令行参数覆盖 YAML 字段」的机制——修改 examples/train_lora/qwen3_lora_sft.yaml 中的数据集、模板与训练超参，即可适配你自己的微调任务。建议从 LoRA SFT 示例起步，跑通后再按需切换到 QLoRA 降低显存、全参 + DeepSpeed 提升上限，或进入 Extras 探索论文级训练技巧。