LlamaFactory翻译站点

LlamaFactory（原名 LLaMA-Factory）是由北京航空航天大学郑耀威（hiyouga）团队发起的统一高效大模型微调框架，以 ACL 2024 论文为学术背书。框架通过”算法-模型-数据”解耦设计，用同一套流水线覆盖 PT→SFT→RM→PPO→DPO→KTO→ORPO 全生命周期，支持 100+ 主流模型（Llama、Qwen、DeepSeek、ChatGLM、Mistral、Gemma、Phi 等），提供 WebUI（LlamaBoard）+ CLI 双操作模式，集成 FlashAttention-2、Unsloth、DeepSpeed、FSDP 等加速方案，Apache-2.0 许可（以仓库 LICENSE 文件为准）。

 

项目概述

LlamaFactory 由北京航空航天大学郑耀威（hiyouga）团队于 2023 年发起，核心贡献者 hiyouga 占总提交 72%，相关学术论文《LlamaFactory: Unified Efficient Fine-Tuning of 100+ Language Models》发表于 ACL 2024 System Demonstrations 。

 

核心设计哲学：算法-模型-数据”解耦”

郑耀威将其比喻为”标准化的高速公路”——不同模型像在高速公路上行驶的不同车辆，数据像是装在车上的货物。只要模型推理能在这条高速公路上跑通，微调只需调节参数即可完成 。这种解耦设计让 LlamaFactory 能用同一套入口微调 100+ 模型，彻底解决”不同模型微调流程各异、切换成本高”的痛点。

 

双架构并行：

• v0（默认稳定版）：api/webui → chat/eval/train → data/model → hparams → extras，功能完整、文档齐全，是当前主力
• v1（实验版）：trainers → core → accelerator/plugins/config → utils，更模块化的分层设计，处于实验阶段

 

支持的模型系列（60+ 系列，100+ 变体）：

• 海外：Llama 3（1B-402B）、Mistral/Mixtral（7B-8x22B MoE）、Gemma 3（270M-27B）、Phi-3/4（3.8B-14B）、Falcon
• 国产：Qwen 2-3.6（0.5B-397B）、DeepSeek R1（1.5B-671B 蒸馏版）、ChatGLM/GLM-4/4.5（9B-355B）、Baichuan、Yi、InternLM
• 多模态：LLaVA、CogVLM、Qwen-VL 2-3（2B-235B）、InternVL 2.5-3.5（1B-241B）、MiniCPM（0.5B-9B）、PaliGemma

 

支持的训练范式 × 微调方法（8 × 6 = 48 种组合）：

 

高级算法支持：

FlashAttention-2、Unsloth（170% 加速 + 50% 显存节省）、DoRA、GaLore、BAdam、APOLLO、LoRA+、PiSSA、LongLoRA、LLaMA-Pro、Mixture-of-Depths、Agent Tuning、Liger Kernel、FP8 训练、RoPE scaling、NEFTune、rsLoRA

 

分布式训练引擎：

• NativeDDP：PyTorch 原生分布式数据并行
• DeepSpeed：ZeRO-1/2/3、ZeRO-Offload、Sparse Attention
• FSDP / FSDP2：PyTorch 原生全分片数据并行，FSDP2 基于 DTensor 实现逐参数分片
• Ray：多机多卡调度

 

量化支持：

PTQ（GPTQ、AWQ、AQLM、OFTQ、bitsandbytes、HQQ、EETQ）、QAT、2/3/4/5/6/8-bit QLoRA

 

推理与导出（训练框架附带的测试/部署能力）：

• 推理引擎：HuggingFace Transformers、vLLM（270% 加速）、SGLang
• 实验监控：LlamaBoard、TensorBoard、WandB、MLflow、SwanLab
• 导出格式：合并 LoRA 权重、GPTQ/AWQ 量化导出、HuggingFace 格式

 

许可策略：

项目以 Apache-2.0​ 许可开源（以 GitHub 仓库 LICENSE 文件为准），允许商用、修改、再分发、微调，无营收门槛、无月活限制。

💡 LlamaFactory 的独特定位：它是”训练&微调”子分类的综合型标杆——单个项目即可覆盖从数据预处理、预训练、SFT、RLHF/DPO/KTO/ORPO 对齐、奖励建模、LoRA 合并、量化导出到 vLLM/SGLang 推理测试的完整链路。虽然框架附带 OpenAI 风格 API、Gradio WebUI、vLLM 推理等能力，但其核心职责是”训练与微调”，推理/API/前端能力仅作为训练后的测试与验证工具，不应将其归入”推理引擎”、”API 封装”或”交互前端”子分类。

 

核心能力

• 100+ 模型统一微调入口：同一套 YAML/WebUI 配置微调 Llama、Qwen、DeepSeek、ChatGLM、Mistral、Gemma、Phi 等全系列模型，自动匹配对话模板、LoRA 目标层、RoPE 缩放
• 全生命周期训练：PT → SFT → RM → PPO → DPO → KTO → ORPO → SimPO 完整对齐链路
• 参数高效微调（PEFT）：LoRA、QLoRA（2/3/4/5/6/8-bit）、DoRA、LoRA+、PiSSA、rsLoRA、GaLore、BAdam、APOLLO、OFT/OFTQ
• 全参数微调：FP16/BF16 全参微调、Freeze 微调、纯 BF16 微调
• 零代码 WebUI（LlamaBoard）：浏览器可视化配置、启动训练、实时监控 loss 曲线、对话测试、导出模型
• CLI + YAML 配置：适合批量任务、服务器、CI/CD 自动化脚本
• 多模态训练：LLaVA、CogVLM、Qwen-VL、InternVL 等图文模型统一流程训练
• 分布式训练：NativeDDP / DeepSpeed / FSDP / FSDP2 / Ray，支持单机多卡与多机多卡
• 量化训练与导出：bitsandbytes 8-bit、GPTQ、AWQ、AQLM、HQQ、EETQ、OFTQ
• 加速算子集成：FlashAttention-2、Unsloth、Liger Kernel、RoPE scaling、NEFTune
• 50+ 内置数据集：alpaca_en/zh、identity、oaast_sft_en、dpo_en_demo、math_en 等，支持自定义数据集（dataset_info.json 配置）
• 实验监控全平台：LlamaBoard、TensorBoard、WandB、MLflow、SwanLab
• NPU 支持：华为昇腾芯片训练与推理（vLLM-Ascend）
• 一键导出部署：合并 LoRA 权重、量化导出、HuggingFace 格式、OpenAI 风格 API、vLLM/SGLang 高性能推理

 

优势亮点

• 零代码/低代码门槛：WebUI 让新手浏览器点选即可训练；CLI+YAML 让工程师批量自动化——兼顾新手与专业
• 消费级显卡可用：QLoRA 4-bit 下 7B 模型仅需 6GB VRAM，70B 模型仅需 48GB VRAM；FSDP+QLoRA 可在 2×24GB GPU 上微调 70B 模型
• 100+ 模型 Day-0 支持：新模型（如 Qwen3、Gemma 4、Llama 4）发布后 LlamaFactory 通常第一时间支持，国产模型（Qwen、DeepSeek、ChatGLM、GLM-4）适配极佳
• Apache-2.0 最干净许可：商用、修改、再分发均无门槛，与 MS-SWIFT、Axolotl 并列”最干净许可”阵营
• 训练速度业界领先：相比 ChatGLM P-Tuning，LoRA 微调训练速度提升 3.7 倍且 Rougel 分数更高；集成 Unsloth 后 LoRA 训练再获 170% 加速与 50% 显存节省
• RLHF 全流程闭环：从 SFT → RM → PPO/DPO/KTO/ORPO 全链路打通，是国内为数不多可完整跑通 RLHF 的开源框架
• 多模态统一流程：LLaVA、CogVLM、Qwen-VL、InternVL 等图文模型使用同一套训练流水线，多模态微调零额外学习成本
• 分布式训练完备：NativeDDP / DeepSpeed / FSDP / FSDP2 / Ray 五种引擎任意切换，FSDP+QLoRA 让 70B 模型微调门槛降至 2×24GB GPU
• ACL 2024 学术背书：论文《LlamaFactory: Unified Efficient Fine-Tuning of 100+ Language Models》提供学术严谨性保证
• 北航团队主导，社区活跃：GitHub 7.2万+ Stars，最新版本 v0.9.5（2026-05-30），总提交 3000+ commits
• 昇腾 NPU 原生支持：vLLM-Ascend 集成，国产算力适配佳

 

局限

• 超大规模预训练非强项：LlamaFactory 定位是”微调框架”而非”预训练引擎”，千亿参数从零预训练建议使用 Megatron-Core 或 NeMo
• RLHF PPO 训练资源消耗大：PPO 需要同时加载策略模型、参考模型、奖励模型、价值模型四个模型副本，70B PPO 全参微调需约 1200GB GPU 显存
• vLLM/SGLang 推理仅为附属功能：虽然框架集成 vLLM 推理（270% 加速），但其核心是训练而非推理服务，生产环境推理建议独立部署 vLLM/SGLang 集群
• WebUI 不适合超大规模集群：LlamaBoard 适合单机/小规模调试，大规模多机训练建议直接用 CLI+YAML+Ray/DeepSpeed
• 全参微调硬件门槛高：70B 模型 BF16 全参微调需 600GB 显存（约 8×A100 80GB），生产级全参微调仍需高昂硬件投入
• Windows 支持较弱：需手动安装 CUDA 版本 PyTorch，官方推荐 Linux 环境
• 某些前沿算法滞后：相比 TRL、veRL 等专职对齐库，最新的 RL 算法（如 DAPO、GRPO 变种）可能滞后 1-2 个月
• YAML 配置学习曲线：虽然 WebUI 零代码，但要充分发挥框架能力（自定义数据集、分布式训练、量化策略），仍需理解 YAML 配置的各项参数

 

适用人群

• 大模型应用开发者：需要基于 Qwen、DeepSeek、ChatGLM 等开源模型做领域适配，LlamaFactory 是国产模型微调的首选
• 企业与行业定制化：金融、医疗、法律、教育等领域需要将通用模型微调为行业专家模型，WebUI 让业务人员也能参与
• 学术研究团队：ACL 2024 论文背书 + 100+ 模型统一入口，是多模态训练、对齐算法研究的理想平台
• 消费级硬件玩家：单张 RTX 4090（24GB）通过 QLoRA 4-bit 可微调 7B 模型，是个人开发者入门 LLM 微调的最佳选择
• 多模态模型微调：LLaVA、CogVLM、Qwen-VL、InternVL 统一流程训练，视觉语言模型定制零额外成本
• RLHF/DPO 对齐实验：需要完整跑通 SFT→RM→PPO/DPO 全流程的研究团队
• 国产算力用户：昇腾 NPU 原生支持，vLLM-Ascend 集成，国产硬件适配佳
• 自动化训练流水线：CLI+YAML 模式完美适配 CI/CD、Airflow、Ray 等自动化调度系统

 

安装与部署

 

1. 硬件需求参考

💡 消费级推荐：RTX 4090 24GB 通过 QLoRA 4-bit 可微调 7B 模型；2×RTX 4090 24GB 通过 FSDP+QLoRA 可微调 70B 模型

 

2. 源码安装

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

# 创建虚拟环境（推荐 Python 3.10）
conda create -n llamafactory python=3.10 -y
conda activate llamafactory

# 安装（包含 torch 与 metrics 依赖）
pip install -e ".[torch,metrics]" --no-build-isolation

# 可选：安装额外依赖
pip install deepspeed==0.16.4  # 分布式训练
pip install flash-attn==2.7.2  # FlashAttention-2 加速
pip install vllm==0.8.2         # vLLM 推理加速

# 验证 GPU 可用
python -c "import torch; print(torch.cuda.get_device_name(0))"

 

3. 通过 Docker 部署（推荐）

# 拉取官方镜像
docker pull hiyouga/llamafactory:latest

# 启动 WebUI（端口 7860）
docker run -d --name llamafactory --gpus all \
  -p 7860:7860 \
  -v /root/llamafactory/data:/app/LLaMA-Factory/data \
  -v /root/llamafactory/models:/root/.cache/huggingface \
  -v /root/llamafactory/output:/app/LLaMA-Factory/output \
  -v /root/llamafactory/saves:/app/LLaMA-Factory/saves \
  -e HF_TOKEN=hf_your_token_here \
  hiyouga/llamafactory:latest \
  llamafactory-cli webui

# 访问 http://localhost:7860 打开 LlamaBoard

 

4. WebUI 零代码微调（LlamaBoard）

# 启动 WebUI
llamafactory-cli webui

# 浏览器打开 http://localhost:7860
# 配置步骤：
# 1. 选择模型名称与路径（如 meta-llama/Meta-Llama-3-8B-Instruct）
# 2. 选择训练阶段（Supervised Fine-Tuning）
# 3. 选择微调方法（LoRA / QLoRA / Full）
# 4. 选择数据集（alpaca_en / alpaca_zh / 自定义）
# 5. 配置超参数（learning_rate=1e-4, lora_rank=8, epochs=3）
# 6. 点击 "Start" 开始训练，实时查看 loss 曲线

 

5. CLI + YAML 配置 LoRA SFT

# 例子：微调 Llama-3-8B-Instruct（LoRA SFT）
llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml

# YAML 配置示例（llama3_lora_sft.yaml）
# model
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct

# method
stage: sft
do_train: true
finetuning_type: lora
lora_target: all
lora_rank: 8
lora_alpha: 16
lora_dropout: 0.1

# dataset
dataset: alpaca_en
template: llama3
cutoff_len: 2048
max_samples: 1000
overwrite_cache: true
preprocessing_num_workers: 16

# output
output_dir: saves/llama3-8b/lora/sft
logging_steps: 10
save_steps: 500
plot_loss: true
overwrite_output_dir: true

# train
per_device_train_batch_size: 4
gradient_accumulation_steps: 4
learning_rate: 1.0e-4
num_train_epochs: 3.0
lr_scheduler_type: cosine
warmup_ratio: 0.1
bf16: true
ddp_timeout: 180000000

 

6. QLoRA 4-bit 微调（消费级硬件）

# 例子：QLoRA 4-bit 微调 Mistral-7B（单卡 RTX 4090 可运行）
cat > configs/qlora_mistral.yaml << 'EOF'
model:
  model_name_or_path: mistralai/Mistral-7B-Instruct-v0.3

method:
  stage: sft
  do_train: true
  finetuning_type: lora
  lora_target: all
  lora_rank: 16
  lora_alpha: 32
  lora_dropout: 0.05

dataset:
  dataset: alpaca_en
  template: mistral
  cutoff_len: 2048
  max_samples: 1000

quantization:
  quantization_method: bitsandbytes
  quantization_bit: 4

output:
  output_dir: saves/mistral-qlora
  logging_steps: 10
  save_steps: 500
  plot_loss: true

train:
  per_device_train_batch_size: 2
  gradient_accumulation_steps: 8
  learning_rate: 0.0001
  num_train_epochs: 3.0
  lr_scheduler_type: cosine
  warmup_ratio: 0.1
  fp16: true
EOF

llamafactory-cli train configs/qlora_mistral.yaml

 

7. DPO 偏好优化

# 第一步：基础模型 SFT
llamafactory-cli train \
  --model_name_or_path meta-llama/Meta-Llama-3-8B \
  --method lora \
  --stage sft \
  --dataset alpaca_en \
  --template llama3 \
  --output_dir ./sft-checkpoint

# 第二步：DPO 对齐
llamafactory-cli train \
  --model_name_or_path meta-llama/Meta-Llama-3-8B \
  --adapter_name_or_path ./sft-checkpoint \
  --method lora \
  --stage dpo \
  --dataset dpo_en_demo \
  --dpo_beta 0.1 \
  --pref_loss sigmoid \
  --template llama3 \
  --output_dir ./dpo-checkpoint

 

8. 多卡分布式训练（DeepSpeed ZeRO-3）

# 4 卡 DeepSpeed ZeRO-3 微调
FORCE_TORCHRUN=1 CUDA_VISIBLE_DEVICES=0,1,2,3 \
  llamafactory-cli train examples/train_lora/qwen3_lora_sft_ds3.yaml

# 或在 YAML 中启用 DeepSpeed
# deepspeed: examples/deepspeed/ds_z3_config.json

 

9. FSDP2 多机多卡训练

# 2 机 16 卡 FSDP2 训练
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_fsdp2.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_fsdp2.yaml

 

10. 训练后推理测试

# 交互式对话测试
llamafactory-cli chat \
  --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

# 使用 vLLM 加速推理
llamafactory-cli chat \
  --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 vllm

 

11. LoRA 合并与导出

# 合并 LoRA 权重到基座模型并导出
llamafactory-cli export \
  --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_dir ./output/llama3-merged \
  --export_size 4 \
  --export_legacy_format false

# 导出为 GPTQ 4-bit 量化模型
llamafactory-cli export \
  --model_name_or_path ./output/llama3-merged \
  --template llama3 \
  --export_dir ./output/llama3-gptq-4bit \
  --quantization_method gptq \
  --quantization_bit 4

 

12. 部署为 OpenAI 兼容 API

# 启动 OpenAI 风格 API 服务（使用 vLLM 后端）
API_PORT=8000 llamafactory-cli api \
  examples/inference/llama3.yaml \
  infer_backend=vllm

 

13. 自定义数据集

// data/my_dataset.json
[
  {
    "instruction": "You are a customer service agent for a tech company. Answer helpfully.",
    "input": "My laptop won't turn on after the update. What should I do?",
    "output": "I understand how frustrating that can be. Let's troubleshoot step by step:\n\n1."
  }
]

// data/dataset_info.json 中添加条目
{
  "my_dataset": {
    "file_name": "my_dataset.json",
    "columns": {
      "instruction": "instruction",
      "input": "input",
      "output": "output"
    }
  }
}

 

14. 部署前必检清单

• 确认仓库位于 github.com/hiyouga/LLaMA-Factory（官方仓库），许可以 LICENSE 文件为准（Apache-2.0）
• 商用部署：Apache-2.0 允许商用，无营收门槛、无月活限制
• 硬件选型参考上表：消费级建议 QLoRA 4-bit；70B 模型微调建议 FSDP+QLoRA 或 DeepSpeed ZeRO-3
• WebUI 适合调试与小规模训练；大规模分布式训练建议 CLI+YAML
• 国产模型（Qwen、DeepSeek、ChatGLM）Day-0 支持，是国产模型微调首选
• 昇腾 NPU 用户参考官方 NPU 安装文档
• 框架附带的 vLLM/SGLang 推理、OpenAI API、Gradio WebUI 仅作为训练后的测试与验证工具；生产环境推理服务建议独立部署 vLLM/SGLang 集群