LlamaFactory：零代码大模型微调 WebUI｜Docker 与源码部署全指南

仓库：https://github.com/hiyouga/LLaMA-Factory 官方文档：https://llamafactory.readthedocs.io/ Docker 镜像：https://hub.docker.com/r/hiyouga/llamafactory/tags 运行形态：Python 库 + WebUI / CLI，支持 GPU 训练

1. 项目简介

LlamaFactory（LLaMA Factory）是零代码大模型微调 WebUI，主打"开箱即用的大模型微调工具箱"。官方特性是对前沿模型 Day-N 支持（Qwen3、Llama 4、InternVL3、GLM-4.1V、GPT-OSS、Kimi-VL 等），并被 Amazon、NVIDIA、阿里云等用于生产。

1.1 核心信息一览

1.2 适用场景

• 想零代码给开源大模型做 SFT / RLHF / 量化微调；
• 需要 WebUI 可视化配置微调任务；
• 想在多卡 / NPU 上微调前沿模型。

1.3 能力边界（官方口径）

• 安装是强制前置步骤；
• 训练需 GPU（NVIDIA / 部分 NPU）；
• Windows 需手动装 GPU 版 PyTorch 与 bitsandbytes。

2. 功能特性

• Day-N 模型支持：快速跟进 Qwen3、Llama 4、InternVL3、GPT-OSS 等；
• 零代码 WebUI：可视化配置微调；
• 多种微调方法：含 LoRA、QLoRA、OFT/OFTv2、Megatron-core 后端等；
• 量化训练：QLoRA（Windows 需 bitsandbytes）；
• 多后端：CUDA 与 Ascend NPU 文档；
• 生态入口：Colab / DSW / HF Spaces / ModelScope Studios。

3. 官方界面预览

上图为官方 README logo（README 官方素材）。

4. 官方跳转链接汇总

• 仓库主页：https://github.com/hiyouga/LLaMA-Factory
• 文档：https://llamafactory.readthedocs.io/
• NPU 文档：https://llamafactory.readthedocs.io/en/latest/multibackend/npu/index.html
• 博客：https://blog.llamafactory.net/en/
• Docker 镜像：https://hub.docker.com/r/hiyouga/llamafactory/tags
• HF Spaces：https://huggingface.co/spaces/hiyouga/LLaMA-Board

5. 前置要求与服务器配置

• NVIDIA GPU（或支持的 Ascend NPU）；
• 源码安装需 Python 环境与 PyTorch；
• Windows：先装 GPU 版 PyTorch（pip install torch --index-url https://download.pytorch.org/whl/cu126）；
• QLoRA 需 bitsandbytes。

6. 方式一：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。

7. 方式二：源码安装

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

可选 deepspeed：

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

uv 一键起 WebUI：

uv run llamafactory-cli webui

Windows GPU PyTorch：

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())"

8. 配置项说明

9. 常用运维命令

# 源码
pip install -e .
llamafactory-cli webui

# uv
uv run llamafactory-cli webui

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

10. 常见故障排查

• Windows pickling 报错：设 dataloader_num_workers: 0；
• QLoRA 报错：装对应 CUDA 版本的 bitsandbytes；
• torch.cuda.is_available() 为 False：重装 CUDA 版 PyTorch；
• 新模型不认识：升级到最新 main。

11. 风险与合规说明

• 许可证以仓库 LICENSE 为准；
• 训练数据与微调模型遵守各自许可；
• GPU 成本由使用者承担；
• 本文为社区部署笔记，命令以官方 README 最新版本为准。