LlamaFactory 统一高效微调 100+ 大模型实战指南：安装、LoRA SFT 快速上手、Docker 与 API 部署全流程

本文基于 LlamaFactory 仓库根目录的 README 编写，覆盖该项目的完整能力面：支持的大模型清单与模板体系、8 种训练方法 × 6 种微调方式的组合矩阵、依赖与显存估算、源码/Docker/NPU 三种安装路径、数据准备规范，以及"训练 → 推理 → 合并"三步 LoRA SFT 实战流程；并结合同仓库源码（cli.py、launcher.py、tuner.py）解释命令背后的调用链与分布式训练机制，读完即可独立完成一次从安装到 OpenAI 风格 API 部署的完整微调工程。

一、项目定位与功能总览

LlamaFactory 是一个"统一高效微调（Unified Efficient Fine-Tuning）"框架，目标是让用户零代码即可通过 CLI 或 Web UI 微调 100+ 个大语言模型与视觉语言模型。README 中列出的核心能力包括：

• 多种模型：LLaMA、LLaVA、Mistral、Mixtral-MoE、Qwen3、Qwen3-VL、DeepSeek、Gemma、GLM、Phi 等；
• 完整训练方法链：（连续）预训练、（多模态）监督微调（SFT）、奖励建模（RM）、PPO、DPO、KTO、ORPO 等；
• 可扩展的资源占用方案：16-bit 全参微调、冻结微调（freeze）、LoRA 以及基于 AQLM/AWQ/GPTQ/LLM.int8/HQQ/EETQ 的 2/3/4/5/6/8-bit 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；
• 快速推理：OpenAI 风格 API、Gradio UI 与 CLI，可搭配 vLLM 或 SGLang 后端。

README 还特别强调其对前沿模型的"Day-N 支持"节奏：Qwen3、Qwen2.5-VL、Gemma 3、GLM-4.1V、InternLM 3、MiniCPM-o-2.6 为 Day 0 支持，Llama 3、GLM-4、Mistral Small、PaliGemma2、Llama 4 为 Day 1 支持。

二、支持的大模型清单与模板选择

训练大模型前最关键的配置是 template 参数——它决定 prompt 如何渲染。README 给出的官方支持矩阵如下（名称与模板名可直接用于配置）：

模型系列	尺寸范围	模板（template）
BLOOM/BLOOMZ	560M/1.1B/1.7B/3B/7.1B/176B	-（base）
DeepSeek（LLM/Code/MoE）	7B/16B/67B/236B	deepseek
DeepSeek 3-3.2	236B/671B	deepseek3
DeepSeek R1（蒸馏版）	1.5B/7B/8B/14B/32B/70B/671B	deepseekr1
ERNIE-4.5	0.3B/21B/300B	ernie_nothink
Falcon/Falcon H1	0.5B/1.5B/3B/7B/11B/34B/40B/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.5V	9B/106B/355B	glm4_moe/glm4_5v
GPT-2	0.1B/0.4B/0.8B/1.5B	-（base）
GPT-OSS	20B/120B	gpt_oss
Granite 3-4	1B/2B/3B/7B/8B	granite3/granite4
Hunyuan/Hunyuan1.5	0.5B/1.8B/4B/7B/13B	hunyuan/hunyuan_small
InternLM 2-3	7B/8B/20B	intern2
InternVL 2.5-3.5	1B/2B/4B/8B/14B/30B/38B/78B/241B	intern_vl
Intern-S1-mini	8B	intern_s1
Kimi-VL	16B	kimi_vl
Ling 2.0	16B/100B	bailing_v2
LFM 2.5（VL）	1.2B/1.6B	lfm2/lfm2_vl
Llama / Llama 2 / Llama 3-3.3	7B-65B / 7B-70B / 1B-70B	- / llama2 / llama3
Llama 4	109B/402B	llama4
Llama 3.2 Vision	11B/90B	mllama
LLaVA-1.5 / LLaVA-NeXT / LLaVA-NeXT-Video	7B/13B 等	llava/llava_next/llava_next_video
MiMo	7B/309B	mimo/mimo_v2
MiniCPM 4/5、MiniCPM-o、MiniCPM-V 4.5/4.6	0.5B-9B	cpm4/empty/minicpm_o/minicpm_v/minicpm_v_4_6
MiniMax-M1/M2	229B/456B	minimax1/minimax2
Ministral 3 / Mistral / Mixtral	3B-8x22B	ministral3 / mistral
PaliGemma/PaliGemma2	3B/10B/28B	paligemma
Phi-3/3.5/4-mini/4	3.8B-14B	phi/phi_small/phi4_mini/phi4
Pixtral	12B	pixtral
Qwen2（Code/Math/MoE/QwQ）	0.5B-110B	qwen
Qwen3（MoE/Instruct/Thinking）	0.6B-235B	qwen3/qwen3_nothink
Qwen3.5 / Qwen3.6	0.8B-397B / 27B/35B	qwen3_5/qwen3_5_nothink / qwen3_6
Qwen2-Audio / Qwen2.5-Omni / Qwen3-Omni	7B / 3B/7B / 30B	qwen2_audio/qwen2_omni/qwen3_omni
Qwen2-VL/Qwen2.5-VL/QVQ / Qwen3-VL	2B-72B / 2B-235B	qwen2_vl / qwen3_vl
Seed（OSS/Coder）	8B/36B	seed_oss/seed_coder
StarCoder 2 / TeleChat / Yuan 2	3B-15B / 3B-115B / 2B-102B	- / telechat2 / yuan

模板选择的官方注意事项（原文照录要点）：

1. 对 base 模型（表格中标 - 的），template 可选 default、alpaca、vicuna 等；但对 instruct/chat 模型必须使用其对应模板，否则微调效果会严重退化；
2. 同时存在推理（thinking）与非推理版本的模型，用 _nothink 后缀区分，例如 qwen3 与 qwen3_nothink；
3. 训练和推理必须使用同一个模板；
4. 部分新模型需要安装 transformers 主分支版本，并设置 DISABLE_VERSION_CHECK=1 跳过版本检查。

从源码看，模板的完整清单定义在 src/llamafactory/data/template.py 的 TEMPLATES 字典中（例如可检索到 name="qwen3_nothink" 的条目），模型族的常量枚举位于 src/llamafactory/extras/constants.py；README 也明确提示：如需支持新模型，可先向 template.py 添加自定义 chat template，再按需补充 src/llamafactory/model/patcher.py 与 src/llamafactory/data/mm_plugin.py 的适配。

三、支持的训练方法与微调方式矩阵

LlamaFactory 把"训练阶段（stage）"与"微调方式（finetuning_type）"两个维度正交组合，官方支持矩阵如下（均为支持状态）：

训练方法（stage）	全参	Freeze	LoRA	QLoRA	OFT	QOFT
预训练（Pre-Training, pt）	✓	✓	✓	✓	✓	✓
监督微调（SFT, sft）	✓	✓	✓	✓	✓	✓
奖励建模（Reward Modeling, rm）	✓	✓	✓	✓	✓	✓
PPO 训练（ppo）	✓	✓	✓	✓	✓	✓
DPO 训练（dpo）	✓	✓	✓	✓	✓	✓
KTO 训练（kto）	✓	✓	✓	✓	✓	✓
ORPO 训练（orpo）	✓	✓	✓	✓	✓	✓
SimPO 训练（simpo）	✓	✓	✓	✓	✓	✓

这一矩阵与源码的路由逻辑完全对应：src/llamafactory/train/tuner.py 中的 _training_function 依据 finetuning_args.stage 依次分发到 run_pt / run_sft / run_rm / run_ppo / run_dpo / run_kto，并在命中 use_hyper_parallel、use_megatron_bridge、use_mca 等开关时切换到大模型并行后端（HyperParallel FSDP2、Megatron Bridge、mcore_adapter）。因此新增一个训练阶段，本质上就是在 train/ 下新增一个 run_xxx workflow 并在该函数中注册分支。

四、内置数据集与数据准备

README 提供了三类官方数据集清单（具体 hub 地址以仓库 data/dataset_info.json 为准）：

• 预训练数据集：Wiki Demo（仓库内置，见 data/wiki_demo.txt）、RefinedWeb、RedPajama V2、Wikipedia（中/英）、Pile、SkyPile、FineWeb / FineWeb-Edu、CCI3/CCI4 系列、The Stack、StarCoder 等；
• SFT 数据集：Identity（仓库内置，见 data/identity.json）、Stanford Alpaca（中/英）、Alpaca GPT4、Glaive Function Calling V2（工具调用）、LIMA、BELLE 系列、UltraChat、OpenOrca/SlimOrca、MathInstruct、Firefly、ShareGPT 系列、Magpie 系列、OpenO1-SFT、Open-R1-Math、LLaVA mixed（多模态）等；
• 偏好数据集：DPO mixed、UltraFeedback、COIG-P、RLHF-V、VLFeedback、Orca DPO Pairs、HH-RLHF、KTO mixed 等。

对于需要授权确认的 Hub 数据集，官方建议先登录：

pip install "huggingface_hub<1.0.0"
huggingface-cli login

自定义数据集的使用规范（详见 data/README.md）：

1. 在 data/dataset_info.json 中登记 dataset description，训练时在 yaml 里指定 dataset: dataset_name；dataset_info.json 默认位于 dataset_dir（默认 ./data）；
2. 支持 alpaca 与 sharegpt 两种格式，允许的文件类型为 json、jsonl、csv、parquet、arrow；
3. 描述项可配置 hf_hub_url / ms_hub_url / script_url / cloud_file_name（s3/gcs）/ file_name 五种来源（前者优先级更高）、formatting、ranking（偏好数据标记）、columns（prompt/query/response/history/messages/system/tools/images/videos/audios/chosen/rejected/kto_tag 列名映射）以及 sharegpt 格式专用的 tags（role_tag/content_tag/user_tag/assistant_tag 等）；
4. alpaca 格式下 instruction 与 input 拼接为用户 prompt，output 为模型响应，system 为系统提示，history 为多轮历史（其中历史响应同样参与学习）；预训练数据仅使用 text 列；
5. 对带推理能力的模型（如 Qwen3），若数据不含 CoT，框架会自动补空 CoT：enable_thinking 为 True（慢思考）时空 CoT 加到响应侧并计入 loss；为 False（快思考）时加到用户提示侧且不计 loss——训练与推理的 enable_thinking 必须保持一致；
6. 除 Hub 数据集外，也支持合成数据工具链（Easy Dataset、DataFlow、GraphGen）来构造微调数据。

仓库内置的演示数据可直接试跑：data/alpaca_en_demo.json、data/alpaca_zh_demo.json、data/identity.json、data/c4_demo.jsonl（预训练）、data/dpo_zh_demo.json、data/kto_en_demo.json 以及多模态示例 data/mllm_demo.json 等。

五、运行环境：软件依赖与显存估算

5.1 软件依赖

README 给出的官方最低/推荐版本如下：

必装依赖	最低版本	推荐版本
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 中声明的依赖约束更严格：requires-python >= 3.11，核心依赖为 torch>=2.4.0、transformers>=4.55.0,<=5.8.0（排除 4.57.0/5.6.0）、datasets>=2.16.0,<=4.0.0、accelerate>=1.3.0,<=1.11.0、peft>=0.18.0,<=0.18.1、trl>=0.18.0,<=0.24.0，并内置 gradio、fastapi/uvicorn（Web UI 与 API 服务）、modelscope、hf-transfer 等。实际安装时以 pip install -e . 解析到的版本为准。可选功能依赖独立存放于 requirements/ 目录，如 requirements/deepspeed.txt、requirements/metrics.txt、requirements/npu.txt、requirements/vllm.txt、requirements/liger-kernel.txt、requirements/galore.txt 等，按需 pip install -r 安装。

5.2 显存估算（官方估算值）

方法	位宽	7B	14B	30B	70B	通用公式（x = 参数量 B）
全参（bf16/fp16）	32	120GB	240GB	600GB	1200GB	18x GB
全参（pure_bf16）	16	60GB	120GB	300GB	600GB	8x GB
Freeze/LoRA/GaLore/APOLLO/BAdam/OFT	16	16GB	32GB	64GB	160GB	2x GB
QLoRA / QOFT	8	10GB	20GB	40GB	80GB	x GB
QLoRA / QOFT	4	6GB	12GB	24GB	48GB	x/2 GB
QLoRA / QOFT	2	4GB	8GB	16GB	24GB	x/4 GB

按此表规划：单张 24GB 卡可跑 7B 全参（bf16 全参训练不现实，但 16-bit LoRA 与 4-bit QLoRA 均可行），70B 模型则必须走 QLoRA + 多卡或 DeepSpeed/FSDP 分片路线（见 examples/train_qlora 与 examples/deepspeed 目录中的配置）。

六、安装方式

6.1 源码安装（官方强制要求先安装）

git clone --depth 1 https://gitcode.com/GitHub_Trending/ll/LlamaFactory
cd LlamaFactory
pip install -e .
pip install -r requirements/metrics.txt

可选依赖组合安装：pip install -e . && pip install -r requirements/metrics.txt -r requirements/deepspeed.txt。

6.2 Docker 镜像安装

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 中 BASE_IMAGE=hiyouga/pytorch:th2.6.0-cu124-flashattn2.7.4-cxx11abi0-devel 的定义一致；Dockerfile 在安装后默认暴露 7860（LLaMA Board 的 Gradio 端口）与 8000（API 服务端口）两个端口，并设置 VLLM_WORKER_MULTIPROC_METHOD=spawn。

6.3 使用 uv 管理虚拟环境

uv run llamafactory-cli webui

6.4 Windows 用户要点

1. 需手动安装 GPU 版 PyTorch（pip install torch torchvision torchaudio --index-url .../whl/cu126），并用 python -c "import torch; print(torch.cuda.is_available())" 验证输出 True；遇到 Can't pickle local object 错误时设置 dataloader_num_workers: 0；
2. 启用 QLoRA 需安装 bitsandbytes（pip install bitsandbytes；uv 环境建议 uv pip install bitsandbytes --no-deps 且须在装好 CUDA 版 PyTorch 之后）。注意官方 wheel 按 CUDA Toolkit 版本分构建，RTX 50 系列（sm_120）需要 CUDA 12.8–12.9 构建；旧环境可安装第三方预编译 win_amd64 wheel；
3. FlashAttention-2 在 Windows 上需借助 flash-attention-windows-wheel 仓库中的脚本自行编译安装。

6.5 Ascend NPU 用户要点

1. 使用 Python 3.12，执行 pip install -r requirements/npu.txt 并安装 Ascend CANN Toolkit 和 Kernels；
2. 官方提供预构建镜像，如 docker pull hiyouga/llamafactory:latest-910b-ubuntu、latest-a3-ubuntu、latest-910b-openeuler、latest-a3-openeuler（quay.io 亦有同名镜像）；
3. NPU 上跑 QLoRA 需三步：源码编译 bitsandbytes（cmake -DCOMPUTE_BACKEND=npu -S . && make && pip install .，要求 cmake>=3.22.1、g++>=12.x）→ 安装 transformers 主分支 → 配置中设置 double_quantization: false（参考示例 examples/train_qlora/qwen3_lora_sft_bnb_npu.yaml）。

七、Quickstart：三步完成 Qwen3-4B 的 LoRA 微调、推理与合并

README 的 Quickstart 以 Qwen3-4B-Instruct 为例，给出训练、推理、合并三条命令：

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

更高级的用法（含分布式训练、QLoRA、DeepSpeed、MoE 等）可参考 examples/README.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
do_train: true
finetuning_type: lora
lora_rank: 8
lora_target: all

### dataset
dataset: identity,alpaca_en_demo
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

参数解读：

• stage: sft + finetuning_type: lora 决定了走 SFT + LoRA 路线；lora_rank: 8 为秩，lora_target: all 表示把 LoRA 注入所有可训练线性层（也可指定模块名单）；
• dataset 支持逗号分隔的多个数据集名，须已在 data/dataset_info.json 中注册；template: qwen3_nothink 表明按 Qwen3 快思考（非推理）模板渲染，chat 与 export 阶段的 yaml 必须与训练使用同一模板；
• cutoff_len: 2048 限制单样本最大 token 长度，max_samples: 1000 用于演示快速试跑；
• per_device_train_batch_size: 1 × gradient_accumulation_steps: 8 得到有效 batch 8，配合 learning_rate: 1.0e-4、cosine 调度与 10% warmup，是 LoRA 微调 4B 级模型的常见起点；
• report_to 可选 none/wandb/tensorboard/swanlab/mlflow，实验监控方式见第十二节；
• 文件尾部的 eval 段是可选的验证集配置，默认注释掉。

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 可选 huggingface、vllm、sglang、ktransformers 四种推理引擎，分别对应 src/llamafactory/chat/hf_engine.py、vllm_engine.py、sglang_engine.py 等实现；切换 vllm 后端即可获得并发、更高吞吐的推理（对应 README Changelog 中集成 vLLM 的记录）。

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
export_device: cpu  # choices: [cpu, auto]
export_legacy_format: false

export_model 的实现位于 src/llamafactory/train/tuner.py：它强制要求 export_dir，并显式禁止"边量化边合并"（adapter_name_or_path 与 export_quantization_bit 同时非空会抛 ValueError）；export_size 控制单分片大小（GB），export_device: cpu 适合低显存环境；export_legacy_format: false 表示输出 safetensors。合并完成后还会自动在导出目录写入一份 Ollama Modelfile，便于直接用 Ollama 加载。

7.4 命令背后的调用链

从源码结构看，上述三条命令的执行路径是：

1. 入口：pyproject.toml 中 [project.scripts] 把 llamafactory-cli 与 lmf 两个可执行命令都映射到 llamafactory.cli:main；
2. src/llamafactory/cli.py 的 main() 检查环境变量 USE_V1：未开启时走 v0 默认架构的 launcher.launch()，开启则走 src/llamafactory/v1 中的实验性新架构（trainers → core → accelerator/plugins/config 的分层设计）；
3. src/llamafactory/launcher.py 按子命令分发：train → run_exp()、chat → run_chat()、api → run_api()、export → export_model()、webui → run_web_ui()、webchat → run_web_demo()、env/version/help 为辅助命令；
4. run_exp()（tuner.py）先 read_args() 解析 YAML/JSON 与命令行覆盖参数，再由 get_train_args() 产出 ModelArguments / DataArguments / FinetuningArguments / TrainingArguments（扩展 HuggingFace TrainingArguments）四个类型化数据类，随后按 stage 路由到对应 workflow；
5. 多卡场景下（本机可见设备数 > 1 且未启用 Ray/KTransformers），launcher 会自动改用 torchrun 拉起分布式进程，支持 NNODES、NODE_RANK、NPROC_PER_NODE、MASTER_ADDR、MASTER_PORT 环境变量，并支持 RDZV_ID + MAX_RESTARTS 的弹性容错启动；OPTIM_TORCH=1 时还会注入 PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True 与 TORCH_NCCL_AVOID_RECORD_STREAMS=1 以优化显存碎片与 NCCL 行为。

这意味着单机多卡无需任何额外命令——直接 llamafactory-cli train xxx.yaml 即可，多机则补齐 NNODES/NODE_RANK/MASTER_ADDR 环境变量。Ray 集群训练则通过 use_ray 参数启用（_ray_training_function 会校验设备数、创建 placement group 并启动远端 Worker）。

八、Web UI：LLaMA Board（Gradio）

零代码用户可启动一体化 Web 界面完成训练、评估与推理：

llamafactory-cli webui

对应入口为 src/llamafactory/webui/interface.py 的 run_web_ui()，组件按 src/llamafactory/webui/components 目录拆分（top/train/data/eval/export/infer/chatbot 等）。Docker 镜像默认映射 7860 端口即为此服务。

九、自建 Docker 镜像

9.1 使用 Docker Compose（推荐）

CUDA 用户：

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

Ascend NPU 用户（按硬件选择 profile）：

cd docker/docker-npu/

# A2 with Ubuntu
docker compose --profile a2-ubuntu up -d
docker compose --profile a2-ubuntu exec llamafactory-a2-ubuntu bash

# A3 with Ubuntu
docker compose --profile a3-ubuntu up -d
docker compose --profile a3-ubuntu exec llamafactory-a3-ubuntu bash

# A2 with openEuler
docker compose --profile a2-openeuler up -d
docker compose --profile a2-openeuler exec llamafactory-a2-openeuler bash

# A3 with openEuler
docker compose --profile a3-openeuler up -d
docker compose --profile a3-openeuler exec llamafactory-a3-openeuler bash

AMD ROCm 用户：

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

9.2 不使用 Compose 手动构建

CUDA：

docker build -f ./docker/docker-cuda/Dockerfile \
    --build-arg PIP_INDEX=https://pypi.org/simple \
    -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

Ascend NPU（需挂载 davinci 设备与驱动目录）：

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

docker run -dit --ipc=host \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -p 7860:7860 \
    -p 8000:8000 \
    --device /dev/davinci0 \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    --name llamafactory \
    llamafactory:latest

docker exec -it llamafactory bash

AMD ROCm（挂载 kfd/dri 设备）：

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

docker run -dit --ipc=host \
    -p 7860:7860 \
    -p 8000:8000 \
    --device /dev/kfd \
    --device /dev/dri \
    --name llamafactory \
    llamafactory:latest

docker exec -it llamafactory bash

9.3 使用 Docker 数据卷

取消 Dockerfile 中 VOLUME [ "/root/.cache/huggingface", "/app/shared_data", "/app/output" ] 的注释即可启用数据卷；构建/运行时用 -v ./hf_cache:/root/.cache/huggingface 挂载宿主机目录。三个官方卷的用途：hf_cache（复用宿主机 HF 缓存）、shared_data（存放数据集）、output（把导出目录指向该位置，宿主机可直接访问合并结果）。

十、部署：OpenAI 风格 API + vLLM

一条命令即可把微调后的模型暴露为 OpenAI 兼容的 /v1/chat/completions 服务：

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

其中 examples/inference/qwen3.yaml 的内容为：

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

命令行追加的 infer_backend=vllm vllm_enforce_eager=true 覆盖了 yaml 中的后端配置（LlamaFactory 的参数系统支持"yaml 打底 + 命令行覆盖"）。API 服务基于 FastAPI/uvicorn 实现（见 src/llamafactory/api/app.py），仓库提供两个客户端示例：scripts/api_example/test_image.py（图像理解）与 scripts/api_example/test_toolcall.py（函数调用）。部署后即可把该模型无缝插入任意 OpenAI 生态应用。

十一、模型与数据集下载源切换

国内网络环境下可切换到国内模型仓库，只需设置环境变量：

# ModelScope
export USE_MODELSCOPE_HUB=1 # Windows: set USE_MODELSCOPE_HUB=1

# Modelers Hub
export USE_OPENMIND_HUB=1 # Windows: set USE_OPENMIND_HUB=1

随后直接把对应 Hub 的模型 ID 填入 model_name_or_path（例如 LLM-Research/Meta-Llama-3-8B-Instruct、TeleAI/TeleChat-7B-pt）即可训练。pyproject.toml 的依赖里默认包含 modelscope 与 hf-transfer，即两条下载通道均已内置。

十二、实验监控：W&B 与 SwanLab

Weights & Biases：在 yaml 中添加

report_to: wandb
run_name: test_run # optional

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

SwanLab：在 yaml 中添加

use_swanlab: true
swanlab_run_name: test_run # optional

登录方式三选一：1）yaml 中写 swanlab_api_key=<your_api_key>；2）环境变量 SWANLAB_API_KEY；3）执行 swanlab login。从源码看，tuner.py 检测到 finetuning_args.use_swanlab 为真时会追加 get_swanlab_callback() 回调，与 HuggingFace 的 report_to 机制并行工作；训练配置示例见 examples/train_lora 中各 yaml 的 report_to 字段。

十三、版本演进与高级后端（Changelog 精选）

README 的 Changelog 记录了该框架的能力演进，对定位功能可用性很有参考价值（按时间倒序节选）：

• 支持 Megatron-core 训练后端（mcore_adapter，即 train/mca/ 工作流）；
• 支持 OFT / OFTv2（示例见 examples/oft）；
• 支持 Intern-S1-mini、GPT-OSS 模型微调；
• 支持 Muon 优化器（examples/muon）、APOLLO 优化器、Adam-mini 优化器；
• 集成 SGLang 推理后端（infer_backend: sglang）；
• 支持 Gemma 3、Llama 4、Qwen2.5 Omni、GLM-4.1V、InternVL3 等模型；
• 导出 checkpoint 时自动生成 Ollama Modelfile；
• 支持 Qwen2-Audio / MiniCPM-o 的音频理解任务、SwanLab 实验追踪；
• 更早的重要能力：无污染的 neat_packing 打包训练（neat_packing: true）、PiSSA 初始化、SimPO/KTO/ORPO 偏好学习、KTO、FSDP+QLoRA（2×24GB 微调 70B）、LoRA+、GaLore、DoRA（use_dora: true）、BAdam、LongLoRA 长序列、FlashAttention-2（flash_attn: fa2）、RoPE scaling、DPO、数据集流式加载（streaming: true）、QLoRA 量化训练、Agent 工具调用微调（dataset: glaive_toolcall_en）、NEFTune（neftune_noise_alpha: 5）等。

官方提示：若某项最新功能不可用，请拉取最新代码并重新安装 LlamaFactory。

十四、许可证与引用

• 仓库代码采用 Apache-2.0 许可证（见 LICENSE）；各模型权重须遵循其各自的模型许可协议（README 的 License 一节列出了 BLOOM、DeepSeek、Falcon、Gemma、GLM-4、Llama 系列、MiniCPM、Mistral、Phi、Qwen、StarCoder 2 等模型对应的许可条款，使用前务必逐条确认）；
• 引用本项目请使用 README 给出的 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},
  url={http://arxiv.org/abs/2403.13372}
}

十五、附录：仓库结构速览（对照源码定位问题）

按"以文档为主、源码为辅"的原则，最后给出定位关键文件的路径索引，便于读者在复现过程中自行深入：

关注点	路径
依赖与入口命令声明	pyproject.toml
CLI 分发（v0/v1 切换）	src/llamafactory/cli.py、src/llamafactory/launcher.py
参数解析（四大数据类）	src/llamafactory/hparams/parser.py
训练阶段路由（pt/sft/rm/ppo/dpo/kto + 并行后端）	src/llamafactory/train/tuner.py
SFT workflow / 指标	src/llamafactory/train/sft/workflow.py、metric.py
Megatron-core 后端	src/llamafactory/train/mca、HyperParallel：src/llamafactory/train/hyper_parallel
模型加载/补丁/量化/LoRA	src/llamafactory/model/loader.py、patcher.py、model_utils/quantization.py
模板体系（100+ 模板）	src/llamafactory/data/template.py
多模态数据插件	src/llamafactory/data/mm_plugin.py
推理引擎（HF/vLLM/SGLang/KTransformers）	src/llamafactory/chat/
OpenAI 风格 API	src/llamafactory/api/
Web UI（LLaMA Board）	src/llamafactory/webui/
全部训练示例 yaml	examples/（train_lora / train_full / train_qlora / deepspeed / ktransformers / megatron 等）
数据集登记与格式说明	data/dataset_info.json、data/README.md
Docker（CUDA/NPU/ROCm）	docker/docker-cuda、docker/docker-npu、docker/docker-rocm
回归测试	tests/（v0）、tests_v1/（v1）

掌握以上"README 骨架 + 源码佐证"两条线索后，建议按第七节三步命令先跑通一个 Qwen3-4B 的 LoRA 全流程，再逐步尝试 examples/ 中的 QLoRA、DeepSpeed、vLLM 部署与多模态示例，即可完成对 LlamaFactory 的完整上手。