LlamaFactory（Llama-Factory）统一微调实战：从安装、LoRA 训练到 vLLM API 部署

2026-09-03 16:09:31作者：郜逊炳

本文基于 LlamaFactory（Llama-Factory）仓库的主文档 README_zh.md 及其配套源码、示例配置展开，完整覆盖“安装 → 数据准备 → 快速微调 → 推理 → 合并 → API 部署”的全流程，并结合 src/llamafactory 下的 CLI 分发器、训练入口与数据集注册文件，讲解每条命令背后的实现机制。读完本文，你可以独立完成百余种 LLM/VLM 的 LoRA/QLoRA 微调，理解 stage、finetuning_type、template 等核心参数的作用，并将训练产物部署为 OpenAI 风格 API。

一、项目定位与核心特性

LlamaFactory 的目标是“Unified Efficient Fine-Tuning of 100+ LLMs & VLMs”，用一个统一的代码库和一套 YAML 配置完成预训练、指令微调与偏好对齐。主文档列出的特性包括：

多种模型：LLaMA、LLaVA、Mistral、Mixtral-MoE、Qwen3、Qwen3-VL、DeepSeek、Gemma、GLM、Phi 等；
集成方法：（增量）预训练、（多模态）指令监督微调（SFT）、奖励模型训练（RM）、PPO、DPO、KTO、ORPO 等；
多种精度：16 比特全参数微调、冻结微调、LoRA 微调，以及基于 AQLM/AWQ/GPTQ/LLM.int8/HQQ/EETQ 的 2/3/4/5/6/8 比特 QLoRA；
先进算法：GaLore、BAdam、APOLLO、Adam-mini、Muon、OFT、DoRA、LongLoRA、LLaMA Pro、Mixture-of-Depths、LoRA+、LoftQ 和 PiSSA；
实用技巧：FlashAttention-2、Unsloth、Liger Kernel、KTransformers、RoPE scaling、NEFTune 和 rsLoRA；
广泛任务：多轮对话、工具调用、图像理解、视觉定位、视频识别和语音理解等；
实验监控：LlamaBoard、TensorBoard、Wandb、MLflow、SwanLab 等；
极速推理：基于 vLLM 或 SGLang 的 OpenAI 风格 API、浏览器界面和命令行接口。

对最新模型的支持节奏（主文档“Day-N 微调适配”表）：

适配时间	模型名称
Day 0	Qwen3 / Qwen2.5-VL / Gemma 3 / GLM-4.1V / InternLM 3 / MiniCPM-o-2.6
Day 1	Llama 3 / GLM-4 / Mistral Small / PaliGemma2 / Llama 4

若某些新特性不可用，主文档给出的排查建议是：重新拉取代码并再次安装 LlamaFactory。

从源码结构看，整个框架的入口非常精简：pyproject.toml 注册了两个命令行脚本 llamafactory-cli 与缩写 lmf，均指向 src/llamafactory/cli.py 的 main()。main() 内部检查 USE_V1 环境变量：启用时走 src/llamafactory/v1/launcher.py 的新一代 launcher，否则走经典版 src/llamafactory/launcher.py。版本号定义在 src/llamafactory/extras/env.py 的 VERSION 常量中（当前仓库为 0.9.6.dev0），可通过 llamafactory-cli env 打印完整环境信息（PyTorch、Transformers、PEFT、TRL、DeepSpeed、bitsandbytes、vLLM 等组件版本）。

二、支持的模型与对话模板

主文档给出了各模型家族、参数量与对应 template 的对照表（节选主流家族）：

模型名	参数量	Template
DeepSeek (LLM/Code/MoE)	7B/16B/67B/236B	deepseek
DeepSeek 3-3.2	236B/671B	deepseek3
DeepSeek R1 (Distill)	1.5B/7B/8B/14B/32B/70B/671B	deepseekr1
Falcon / Falcon H1	0.5B~180B	falcon / falcon_h1
Gemma / Gemma 2 / CodeGemma	2B/7B/9B/27B	gemma / gemma2
Gemma 3 / Gemma 3n	270M/1B/4B/6B/8B/12B/27B	gemma3 / gemma3n
GLM-4 / GLM-4-0414 / GLM-Z1	9B/32B	glm4 / glmz1
GLM-4.5 / GLM-4.5(6)V	9B/106B/355B	glm4_moe / glm4_5v
GPT-OSS	20B/120B	gpt_oss
InternLM 2-3	7B/8B/20B	intern2
InternVL 2.5-3.5	1B~241B	intern_vl
Llama 2	7B/13B/70B	llama2
Llama 3-3.3	1B/3B/8B/70B	llama3
Llama 4	109B/402B	llama4
Llama 3.2 Vision	11B/90B	mllama
LLaVA-1.5 / LLaVA-NeXT	7B/13B / 7B~110B	llava / llava_next
MiniCPM 4/5 / MiniCPM-o / MiniCPM-V	0.5B~9B	cpm4 / minicpm_o / minicpm_v
Mistral / Mixtral	7B/8x7B/8x22B	mistral
PaliGemma / PaliGemma2	3B/10B/28B	paligemma
Phi-3 / Phi-3.5 / Phi-4	4B/7B/14B/3.8B	phi / phi_small / phi4
Qwen2 (Code/Math/MoE/QwQ)	0.5B~110B	qwen
Qwen3 (MoE/Instruct/Thinking)	0.6B~235B	qwen3 / qwen3_nothink
Qwen2-VL / Qwen2.5-VL / QVQ	2B~72B	qwen2_vl
Qwen3-VL	2B~235B	qwen3_vl
Qwen2-Audio / Qwen2.5-Omni / Qwen3-Omni	7B / 3B~7B / 30B	qwen2_audio / qwen2_omni / qwen3_omni

完整清单以 src/llamafactory/extras/constants.py 为准；如果需要接入未覆盖的对话格式，可以在 src/llamafactory/data/template.py 中注册自定义模板。

模板使用有三条硬性规则（主文档 NOTE）：

所有“基座”（Base）模型的 template 可以是 default、alpaca、vicuna 等任意值；但“对话”（Instruct/Chat）模型必须使用对应的模板；
若模型有推理/非推理两个版本，用 _nothink 后缀区分模板，例如 qwen3 与 qwen3_nothink；
训练与推理必须采用完全一致的模板，否则生成行为会出错。

三、训练方法矩阵

主文档的方法 × 参数化方式支持矩阵（八种阶段均支持全参数、部分参数、LoRA、QLoRA）：

方法	全参数训练	部分参数训练	LoRA	QLoRA
预训练（pt）	✅	✅	✅	✅
指令监督微调（sft）	✅	✅	✅	✅
奖励模型训练（rm）	✅	✅	✅	✅
PPO 训练	✅	✅	✅	✅
DPO 训练	✅	✅	✅	✅
KTO 训练	✅	✅	✅	✅
ORPO 训练	✅	✅	✅	✅
SimPO 训练	✅	✅	✅	✅

源码印证：训练阶段的分派逻辑集中在 src/llamafactory/train/tuner.py 的 _training_function 中，按 finetuning_args.stage 依次调用 run_pt、run_sft、run_rm、run_ppo、run_dpo、run_kto 等工作流函数（每个阶段对应 src/llamafactory/train/ 下的独立子包，如 src/llamafactory/train/sft/workflow.py）。此外该文件还展示了可选后端：设置 use_hyper_parallel、use_megatron_bridge 或 use_mca 后，pt/sft/dpo 阶段会切换到 hyper-parallel / Megatron-bridge / mcore-adapter（Megatron-core）对应实现——这与更新日志中“支持 Megatron-core 作为训练后端”的条目一一对应。

四、数据准备

数据集分三类（主文档给出大量公开数据集，如 RefineWeb、RedPajama、FineWeb、SkyPile、Stanford Alpaca、BELLE、UltraChat、LMSYS Chat 1M、OpenO1-SFT、UltraFeedback、HH-RLHF、KTO mixed 等），可直接通过 Hugging Face / ModelScope / Modelers 社区加载，也可以使用本地文件。仓库自带一批演示数据，见 data/README_zh.md 与 data/dataset_info.json。

数据集注册机制（源码级）：LlamaFactory 并不硬编码数据集路径，而是通过 data/dataset_info.json 做注册表。从该文件可以看到三种典型的注册写法：

本地文件："identity": { "file_name": "identity.json" }、"alpaca_en_demo": { "file_name": "alpaca_en_demo.json" }；
ShareGPT 多轮/多模态格式："mllm_demo" 指定 "formatting": "sharegpt" 并用 columns、tags 映射消息、图片/音频/视频字段；
远端数据集："hf_hub_url"（Hugging Face）、"ms_hub_url"（魔搭）、"om_hub_url"（魔乐）三个 URL 字段。

使用自定义数据集时，必须更新 data/dataset_info.json；字段含义详见 data/README_zh.md。

部分数据集需要访问确认，主文档推荐先执行：

pip install --upgrade huggingface_hub
huggingface-cli login

五、软硬件依赖

主文档给出的软件依赖最低/推荐版本：

必需项	至少	推荐
python	3.11	>=3.11
torch	2.0.0	2.6.0
torchvision	0.15.0	0.21.0
transformers	4.49.0	4.50.0
datasets	2.16.0	3.2.0
accelerate	0.34.0	1.2.1
peft	0.14.0	0.15.1
trl	0.8.6	0.9.6

可选项	至少	推荐
CUDA	11.6	12.2
deepspeed	0.10.0	0.16.4
bitsandbytes	0.39.0	0.43.1
vllm	0.4.3	0.8.2
flash-attn	2.5.6	2.7.2

以当前仓库为准的补充：pyproject.toml 中 pip install -e . 实际锁定的依赖比上表更严格，例如 torch>=2.4.0、transformers>=4.55.0,<=5.8.0（且排除个别版本）、accelerate>=1.3.0、peft>=0.18.0、trl>=0.18.0，GUI 依赖 gradio>=4.38.0，推理服务依赖 uvicorn/fastapi/sse-starlette。上表可理解为“功能可用的下限”，而 pyproject 才是当前版本安装时真实生效的约束。

显存占用估算（主文档，估算值，xB 表示 x 个 B 的模型）：

方法	精度	7B	14B	30B	70B	`x`B
Full (`bf16` or `fp16`)	32	120GB	240GB	600GB	1200GB	`18x`GB
Full (`pure_bf16`)	16	60GB	120GB	300GB	600GB	`8x`GB
Freeze/LoRA/GaLore/APOLLO/BAdam	16	16GB	32GB	64GB	160GB	`2x`GB
QLoRA	8	10GB	20GB	40GB	80GB	`x`GB
QLoRA	4	6GB	12GB	24GB	48GB	`x/2`GB
QLoRA	2	4GB	8GB	16GB	24GB	`x/4`GB

六、安装 LlamaFactory

6.1 从源码安装

git clone --depth 1 https://github.com/hiyouga/LlamaFactory.git
cd LlamaFactory
pip install -e .
pip install -r requirements/metrics.txt

可选依赖按 requirements/ 目录中的 .txt 文件按需安装，如：

pip install -e . && pip install -r requirements/metrics.txt -r requirements/deepspeed.txt

其他可选依赖（vllm、sglang、bitsandbytes、liger-kernel、swanlab、ktransformers、muon 等）在 requirements/ 下均有对应文件。

6.2 从官方镜像安装

docker run -it --rm --gpus=all --ipc=host hiyouga/llamafactory:latest

该镜像基于 Ubuntu 22.04（x86_64）、CUDA 12.4、Python 3.11、PyTorch 2.6.0 和 Flash-Attn 2.7.4 构建。镜像构建配方见 docker/docker-cuda/Dockerfile，可另选 docker/docker-npu/Dockerfile（昇腾）与 docker/docker-rocm/Dockerfile（AMD）。

6.3 使用 uv 构建虚拟环境

uv run llamafactory-cli webui

6.4 Windows 用户指南

安装 GPU 版 PyTorch：需先卸载 CPU 版再按 PyTorch 官方指引安装对应 CUDA 构建，例如：
```
pip uninstall torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126
python -c "import torch; print(torch.cuda.is_available())"
```
输出 True 即成功。若遇到 Can't pickle local object 报错，请将 dataloader_num_workers 设为 0。
安装 bitsandbytes：优先 pip install bitsandbytes（官方按 CUDA 版本分别构建 wheel，RTX 50 系列对应 CUDA 12.8–12.9 的构建）；若使用 uv 管理环境，建议在装好 GPU 版 PyTorch 后执行 uv pip install bitsandbytes --no-deps；需要兼容较老环境时可用社区第三方预编译 wheel。
安装 FlashAttention-2：需使用社区的 flash-attention-windows-wheel 脚本自行编译安装。

6.5 昇腾 NPU 用户指南

使用 Python 3.12，并执行 pip install -r requirements/npu.txt 安装额外依赖；
需要安装 Ascend CANN Toolkit 与 Kernels（参考框架文档中的安装教程）；
也可直接拉取预置镜像，例如 hiyouga/llamafactory:latest-910b-ubuntu、hiyouga/llamafactory:latest-a3-ubuntu 及对应 openEuler 版本；
若要在 NPU 上做 bitsandbytes QLoRA：从 bitsandbytes 的 multi-backend 分支源码编译（cmake -DCOMPUTE_BACKEND=npu -S .），安装 transformers 的 main 分支，并在训练参数中设置 double_quantization: false，可参考示例 examples/train_qlora/qwen3_lora_sft_bnb_npu.yaml。

七、快速开始：LoRA 微调 → 推理 → 合并三行命令

主文档给出的最小闭环——对 Qwen3-4B-Instruct 做 LoRA 微调、加载适配器对话、合并导出：

llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml
llamafactory-cli chat examples/inference/qwen3_lora_sft.yaml
llamafactory-cli export examples/merge_lora/qwen3_lora_sft.yaml

高级用法（多 GPU、冻结、QLoRA、偏好对齐等）参考 examples/README_zh.md。

7.1 训练配置解读

examples/train_lora/qwen3_lora_sft.yaml 全文（可直接复制修改）：

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

### method
stage: sft                    # 训练阶段：pt/sft/rm/ppo/dpo/kto
do_train: true
finetuning_type: lora          # 参数化方式：full/lora/freeze
lora_rank: 8
lora_target: all               # all 表示注入所有线性层

### dataset
dataset: identity,alpaca_en_demo   # 逗号分隔多个数据集（在 dataset_info.json 中注册）
template: qwen3_nothink            # 对话模型必须匹配模板
cutoff_len: 2048                   # 最大序列长度
max_samples: 1000                  # 每个数据集最多取多少条
preprocessing_num_workers: 16
dataloader_num_workers: 4

### output
output_dir: saves/qwen3-4b/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
resume_from_checkpoint: null

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

命令如何走到这份 YAML（源码级）：llamafactory-cli train <yaml> 由 src/llamafactory/launcher.py 的 launch() 分发。它有一个关键设计——多卡自动分布式：当 train 子命令检测到 FORCE_TORCHRUN=1，或本机可用设备数大于 1（且未使用 Ray/KTransformers）时，会自动拼装 torchrun --nnodes ... --nproc_per_node ... --master_addr ... --master_port ... 并以子进程方式重启自身，从而无需用户手写 torchrun；NNODES、NODE_RANK、NPROC_PER_NODE、MASTER_ADDR、MASTER_PORT、RDZV_ID 等环境变量可控制多机与弹性启动。单卡场景则直接调用 src/llamafactory/train/tuner.py 的 run_exp()，由 read_args() 同时读取 YAML 与命令行追加参数（因此可 llamafactory-cli train xxx.yaml learning_rate=5e-5 覆盖配置）。llamafactory-cli help 会打印全部子命令：api、chat、export、train、webchat、webui、env、version。

7.2 推理配置

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 对应 src/llamafactory/chat/ 下的多个引擎：hf_engine.py（Hugging Face）、vllm_engine.py、sglang_engine.py，由 chat_model.py 统一封装，llamafactory-cli chat 与 webchat 共用。

7.3 合并导出配置

examples/merge_lora/qwen3_lora_sft.yaml：

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

### model
model_name_or_path: Qwen/Qwen3-4B-Instruct-2507
adapter_name_or_path: saves/qwen3-4b/lora/sft
template: qwen3_nothink
trust_remote_code: true

### export
export_dir: saves/qwen3_sft_merged
export_size: 5            # 分片大小（GB）
export_device: cpu        # choices: [cpu, auto]
export_legacy_format: false

源码印证：export 子命令调用 src/llamafactory/train/tuner.py 的 export_model()。其流程为：加载 tokenizer → 按模板修复 tokenizer（get_template_and_fix_tokenizer）→ 加载模型并拒绝“量化模型合并 LoRA”的非法组合 → 按 export_size 分片 save_pretrained（export_legacy_format: false 时输出 safetensors）→ 保存 tokenizer/processor → 额外生成 Ollama 的 Modelfile（template.get_ollama_modelfile(tokenizer)），因此合并产物可以直接被 Ollama 使用。训练日志中 report_to 的四个取值（wandb/tensorboard/swanlab/mlflow）也与 src/llamafactory/train/callbacks.py 中的 ReporterCallback 相对应。

八、LLaMA Board 可视化微调

llamafactory-cli webui

启动后在浏览器中即可完成“选择模型 → 选择数据集 → 选择超参 → 开始训练 → 浏览器内对话/导出”的全流程。实现位于 src/llamafactory/webui/：interface.py 构建 Gradio 页面，components/train.py 提供训练面板，runner.py 负责把界面状态翻译成训练参数并调用 run_exp，manager.py 管理训练状态与导出目录。

九、构建 Docker 镜像

Docker Compose 方式（推荐）：

CUDA 用户：

cd docker/docker-cuda/
docker compose up -d
docker compose exec llamafactory bash

昇腾 NPU 用户（按芯片与系统选择 profile）：

cd docker/docker-npu/
# A3 + Ubuntu
docker compose --profile a3-ubuntu up -d
docker compose --profile a3-ubuntu exec llamafactory-a3-ubuntu bash
# 另有 a2-ubuntu / a2-openeuler / a3-openeuler 组合

AMD ROCm 用户：

cd docker/docker-rocm/
docker compose up -d
docker compose exec llamafactory bash

不使用 Compose 时，CUDA 场景可直接：

docker build -f ./docker/docker-cuda/Dockerfile \
    --build-arg PIP_INDEX=https://pypi.org/simple \
    --build-arg EXTRAS=metrics \
    -t llamafactory:latest .

docker run -dit --ipc=host --gpus=all \
    -p 7860:7860 -p 8000:8000 \
    --name llamafactory llamafactory:latest
docker exec -it llamafactory bash

NPU 镜像构建时需用 --device /dev/davinci0 等参数透传设备节点并挂载 Ascend 驱动目录；ROCm 需透传 /dev/kfd 与 /dev/dri。完整命令见 docker/docker-npu/ 与 docker/docker-rocm/ 下的 Dockerfile 和 compose 文件。

数据卷：取消 docker/docker-cuda/Dockerfile 中 VOLUME [ "/root/.cache/huggingface", "/app/shared_data", "/app/output" ] 的注释，并在 docker run 时加 -v ./hf_cache:/root/.cache/huggingface 即可挂载。三个卷的用途：hf_cache（宿主机 HF 缓存）、shared_data（数据集目录）、output（导出模型可回读宿主机的输出目录）。

十、利用 vLLM 部署 OpenAI API

API_PORT=8000 llamafactory-cli api examples/inference/qwen3.yaml infer_backend=vllm vllm_enforce_eager=true

该命令加载 examples/inference/qwen3.yaml 配置，通过 infer_backend=vllm 启用 vLLM 后端做高并发推理，并额外透传 vllm_enforce_eager=true（禁用 CUDA Graph，便于排错）。服务提供与 OpenAI Chat 接口一致的 /v1/chat/completions 端点，因此可直接接入任意 OpenAI SDK 客户端。仓库提供了两个端到端调用示例：

图像理解：scripts/api_example/test_image.py
工具调用：scripts/api_example/test_toolcall.py

服务实现位于 src/llamafactory/api/app.py（FastAPI + SSE 流式响应），请求/响应协议在 src/llamafactory/api/protocol.py 中按 OpenAI 格式定义，会话拼装逻辑见 src/llamafactory/api/chat.py。

十一、从魔搭社区 / 魔乐社区下载

在 Hugging Face 下载受阻时，可切换模型/数据集来源：

export USE_MODELSCOPE_HUB=1   # Windows 使用 set USE_MODELSCOPE_HUB=1

或

export USE_OPENMIND_HUB=1    # Windows 使用 set USE_OPENMIND_HUB=1

然后把 model_name_or_path 设为对应社区的模型 ID 即可。从 data/dataset_info.json 的注册结构也能看到这一点：每个数据集可同时声明 hf_hub_url、ms_hub_url、om_hub_url，运行时按环境变量选择数据源，配置无需改动。

十二、实验跟踪：W&B 与 SwanLab

使用 Weights & Biases 时，在 YAML 中加入：

report_to: wandb
run_name: test_run   # 可选

启动训练前设置环境变量 WANDB_API_KEY 完成登录。

使用 SwanLab 时，在 YAML 中加入：

use_swanlab: true
swanlab_run_name: test_run   # 可选

登录方式三选一：YAML 中写 swanlab_api_key=<your_api_key>；设置环境变量 SWANLAB_API_KEY；或启动前执行 swanlab login。源码中对应的开关是 finetuning_args.use_swanlab，训练时会注入 SwanLab 回调（见 src/llamafactory/train/trainer_utils.py 的 get_swanlab_callback），相关依赖位于 requirements/swanlab.txt。

十三、更新日志要点、协议与引用

近几条更新日志（完整列表见 README_zh.md）：

[25/10/26] 支持 Megatron-core 作为训练后端并适配 mcore_adapter；
[25/08/22] 支持 OFT 与 OFTv2 模型微调，示例见 examples/extras/oft/；
[25/08/20] 支持 Intern-S1-mini 微调；
[25/08/06] 支持 GPT-OSS 微调；
[25/04/21] 支持 Muon 优化器，示例见 examples/extras/muon/。

协议：仓库代码依照 Apache-2.0 开源；使用模型权重时须遵循各模型自身协议（DeepSeek、Llama、Qwen、Gemma 等均有独立许可）。

论文引用（ACL 2024 System Demonstrations）：

@inproceedings{zheng2024llamafactory,
  title={LlamaFactory: Unified Efficient Fine-Tuning of 100+ Language Models},
  author={Yaowei Zheng and Richong Zhang and Junhao Zhang and Yanhan Ye and Zheyan Luo and Zhangchi Feng and Yongqiang Ma},
  booktitle={Proceedings of the 62nd Annual Meeting of the Association for Computational Linguistics (Volume 3: System Demonstrations)},
  address={Bangkok, Thailand},
  publisher={Association for Computational Linguistics},
  year={2024}
}

附：一次完整微调的自检清单

依赖安装后先 llamafactory-cli env 确认 PyTorch/CUDA 与 transformers 版本满足 pyproject.toml 约束；
自定义数据先写入 data/dataset_info.json，并核对 formatting（alpaca/sharegpt）与 columns 映射；
stage + finetuning_type 决定训练路径（pt/sft/rm/ppo/dpo/kto × full/lora/freeze），template 必须与模型版本（是否 thinking）严格匹配；
多卡训练无需手动 torchrun——launcher 会自动分发起 src/llamafactory/launcher.py；
训练产物用 chat 验证效果，再用 export 合并为完整模型（自动附带 Ollama Modelfile），最后以 api infer_backend=vllm 暴露为 OpenAI 兼容服务。