LlamaFactory 到底是什么：零代码 CLI + Web UI 的微调工厂

2026-08-09

本文所有事实以 hiyouga/LlamaFactory 官方仓库 2026-08-09 的内容为准。我们没有安装、训练或部署过任何模型，文中数字均为仓库文档与源码里写着的值。

如果你要在一句话里说清 LlamaFactory 是什么，最省事的办法是照抄它 README 大标题下的那一行：“Easily fine-tune 100+ large language models with zero-code CLI and Web UI”。这句话里真正有信息量的不是”100+“，而是 “zero-code” 和 “CLI and Web UI” 这两个短语——它给自己的定位是”入口层”，不是”又一套训练框架”。

很多人第一次接触它是因为搜”怎么微调 Qwen”，然后被一堆 YAML 示例劝退了。这篇不讲怎么调参，只回答一个更前置的问题：这个项目在你的技术栈里坐在什么位置上，它替你收敛了什么，又明确没打算替你做什么。

先把身份坐标钉死

截至 2026-08-09，仓库 hiyouga/LlamaFactory 的 GitHub 数据是 star 73947、fork 9049、open issues 1109，许可标注 Apache-2.0，仓库创建于 2023-05-28。

这几个数字里最容易被过度解读的是 star。它只说明”被收藏过多少次”，不说明代码在你的场景里好不好用，别拿它推导稳定性、成熟度或适用性。创建时间 2023-05-28 也只是仓库开张的日期，我们不据此推断项目经历过什么。同样地，1109 个 open issues 这个数字本身也不构成任何质量判断，一个高活跃度的项目 issue 池大是常态。

其余几个身份标识，装之前先记住，能省掉不少找错地方的时间：

项目	值
PyPI 包名	`llamafactory`
Docker Hub 镜像	`hiyouga/llamafactory`
官方文档	`https://llamafactory.readthedocs.io/en/latest/`（README 明标 (WIP)）
官方博客	`https://blog.llamafactory.net/en/`
社群	微信群与 NPU 用户群（链接在 `hiyouga/llamafactory-community` 仓库）、Discord、Twitter `@llamafactory_ai`

README 顶部的徽章里还有一枚 Citation 徽章标着 citation-1000+，点过去是 Google Scholar 的引用页；README 正文也明写了 Amazon、NVIDIA、Aliyun 等在用，并各自给了对应的博客或产品页链接。这些是仓库自己贴的背书材料，看看就好。

这里有一条必须提醒的 README 原文声明：除了它自己列出的这些链接以外，其它所有网站都是未经授权的第三方网站，请谨慎使用。这条声明的实际用处是，当你搜到某个”LlamaFactory 在线版""官方镜像站”时，先回 README 的链接列表比对一遍。我们不点名任何具体站点，只是把这条原文转述给你。

一个绕不开的小坑：它到底叫什么名字

hiyouga/LlamaFactory 是这个仓库当前的真实路径，PyPI 包名是 llamafactory，命令行工具是 llamafactory-cli。但仓库内部的字符串并不统一：src/llamafactory/launcher.py 的欢迎语里写的项目主页仍然是带连字符的旧名 https://github.com/hiyouga/LLaMA-Factory，README 正文里也混用 LLaMA-Factory 和 LlamaFactory 两种写法。

这是仓库里能核实到的新旧写法并存，如实说到这儿就够了——改名的时间、原因、有没有重定向，我们都没有核实过，不做推断。对你的实际影响也就一条：搜资料、翻 issue 时两种拼法都试一遍，别因为拼法不同就以为搜到的是另一个项目。

“零代码”这三个字具体指什么

它指的是两条并行的入口，而不是”不用理解原理”。

一条是命令行：llamafactory-cli。你写一份 YAML 配置，用命令把它喂进去，训练、推理、导出各走各的子命令。这条路的特点是可版本化、可复现、能进 CI。

另一条是 Web UI。launcher.py 的 USAGE 里，这条子命令写的原文是 llamafactory-cli webui: launch LlamaBoard；README 的 Features 里，LlamaBoard 也出现在实验跟踪那一条。README 的安装折叠块里给了 uv 的用法示例，一行就是入口：

uv run llamafactory-cli webui

Web UI 这条路真正解决的是”参数太多、不知道哪些必填”的问题：它把配置项摆在界面上让你选，选完落成同一套参数。所以”零代码”的准确含义是不用写训练脚本，而不是不用理解 template、数据格式和显存约束。这三样东西不管走哪条入口都躲不掉。

八条 Features 分别在解决哪一层

README 的 Features 一共八条。直接读容易读成一串名词，按”它在替你收敛什么”重新归一下就清楚多了：

收敛”用什么模型”：Various models 一条，列了 LLaMA、LLaVA、Mistral、Mixtral-MoE、Qwen3、Qwen3-VL、DeepSeek、Gemma、GLM、Phi 等。README 另有一张 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。这张表是对过去的记录，不是对未来新模型的承诺，读的时候别读成 SLA。

收敛”用什么训练方法”：Integrated methods 一条覆盖（持续）预训练、（多模态）监督微调、奖励建模、PPO、DPO、KTO、ORPO 等。也就是说，从预训练续训到偏好对齐，你不用为每一步换一个仓库。

收敛”用多大资源”：Scalable resources 一条列了 16-bit 全参微调、freeze-tuning、LoRA，以及通过 AQLM、AWQ、GPTQ、LLM.int8、HQQ、EETQ 实现的 2/3/4/5/6/8-bit QLoRA。也就是说，从全参到 2-bit 量化这一整条资源梯度，README 把它们放在同一套入口下枚举，不需要你为不同精度换工具。

收敛”用什么算法和技巧”：Advanced algorithms 一条给了 GaLore、BAdam、APOLLO、Adam-mini、Muon、OFT、DoRA、LongLoRA、LLaMA Pro、Mixture-of-Depths、LoRA+、LoftQ、PiSSA；Practical tricks 一条给了 FlashAttention-2、Unsloth、Liger Kernel、KTransformers、RoPE scaling、NEFTune、rsLoRA。这两条的性质是”接进来了”，不是”默认开着”，具体开关在各自的参数里。

收敛”能做什么任务”：Wide tasks 一条包含多轮对话、工具调用、图像理解、视觉定位、视频识别、音频理解等。

收敛”训练过程怎么看”：Experiment monitors 一条给了 LlamaBoard、TensorBoard、Wandb、MLflow、SwanLab 等。

收敛”训完怎么用起来”：Faster inference 一条提供 OpenAI 风格 API、Gradio UI 和 CLI，可以接 vLLM worker 或 SGLang worker。这一条常被忽略，但它决定了你训完之后能不能不换栈就把服务拉起来。

显存和依赖：这篇只点两个最影响判断的格子

README 有一张 Hardware Requirement 表，也有一张 Requirement 依赖表。这两张表各自都够写一整篇，这里只取跟”我该不该上手”直接相关的两格。

第一格是显存表里同一列的量级差：7B 列上，Full（bf16 或 fp16，32）标 120GB，Freeze/LoRA/GaLore/APOLLO/BAdam/OFT（16）标 16GB，相差 7.5 倍。这个倍数决定了绝大多数人的默认起点是 LoRA 系而不是全参。

必须带上的限定是：这张表在表头上方被 README 自己标了 * estimated（估算）。它不是实测占用，我们也没有跑过任何一次训练。所以这里只说”表里写的量级差是 7.5 倍”，不推导”你那张卡够不够”。这张表还有一处内部对不上的格子，我们另有一篇专门讲。

第二格是依赖表里的 python 行：Minimum 3.11、Recommend >=3.11。这一行的意思是下限就是 3.11，如果你手上是更老的环境，先解决 Python 版本再谈其它。README 用 > [!IMPORTANT] 强调了一句 Installation is mandatory.，安装这一步没有”直接跑源码试试”的捷径。

从源码装的四行照抄如下：

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

可选依赖是 metrics 和 deepspeed，README 也给了一次装两个的写法；特定功能的额外依赖放在 examples/requirements/ 下。

不想碰本地环境就走官方镜像：

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

README 原文写明这个镜像基于 Ubuntu 22.04 (x86_64)、CUDA 12.4、Python 3.11、PyTorch 2.6.0、Flash-attn 2.7.4。预构建镜像列表在 Docker Hub 的 tags 页。要自建的话，README 给的是 cd docker/docker-cuda/ 然后 docker compose up -d，仓库 docker/ 目录下按后端分了子目录。

想先看一眼再决定：三条云端入口

README 自己列了三条不用装环境的试用路径，这对”到底是不是我要的东西”这个阶段很实用：

Colab（免费）：README 给了直达 notebook 链接
PAI-DSW（免费试用）：https://gallery.pai-ml.com/#/preview/deepLearning/nlp/llama_factory
AMD GPU Cloud（免费额度）：AMD Developers Notebooks 仓库里的对应 notebook

另外还有两份第三方托管的文档：AMD ROCm 的 llama_factory_llama3 notebook，以及 Ascend NPU 的多后端文档页。

Windows 用户尤其要记的两行

README 明确设定了一个场景：Hugging Face 下载有问题时，切下载源。两个环境变量分别对应两个 Hub，注意 Windows 的写法和 Linux/macOS 不一样：

切到 ModelScope Hub：

# Linux / macOS
export USE_MODELSCOPE_HUB=1

:: Windows
set USE_MODELSCOPE_HUB=1

然后把 model_name_or_path 填成 ModelScope 的 model ID，README 给的例子是 LLM-Research/Meta-Llama-3-8B-Instruct。

切到 Modelers Hub 是同一套写法，变量换成 USE_OPENMIND_HUB=1，model ID 示例是 TeleAI/TeleChat-7B-pt。

如果你用的是 Ascend NPU，README 的折叠块里另有一条具体提示：在配置里设 double_quantization: false，并给了参考示例 examples/train_qlora/qwen3_lora_sft_bnb_npu.yaml。

它明确没打算替你做的事

看清楚边界，比看清楚功能更省时间。

它不替你造数据。 README 反过来推荐了三个外部工具来做微调数据：Easy Dataset（ConardLi/easy-dataset）、DataFlow（OpenDCAI/DataFlow）、GraphGen（open-sciencelab/GraphGen），并各自配了博客文章。换句话说，数据这一段在这套体系里是被显式外包出去的。

它的文档还在写。 llamafactory.readthedocs.io 这个官方文档页在 README 里被标了 (WIP)。实践中这意味着，当文档和仓库里的示例 YAML、--help 输出打架时，以后两者为准。

许可这块我们只指路。 仓库 License 一节标的是 Apache-2.0，Citation 一节给了 BibTeX 引用格式。各模型权重另有各自的条款，具体商用边界请以官方 LICENSE 原文和各模型许可原文为准。

那么，什么情况下该用它

按”你现在卡在哪一步”来判断比按功能表判断准：

你已经确定要做微调，但不想为每种方法（SFT / DPO / 奖励建模）各维护一套脚本，那它收敛的正是这件事；
你手上有多种模型要横着试，尤其涉及多模态，那它的模型表和 template 体系值得投入；
你还没有数据，那先去看它推荐的那三个数据工具，微调框架不是你现在的瓶颈；
你只是想让某个通用模型少说几句废话，那大概率提示词工程和检索就够了，微调是更贵的一档手段。

至于 llamafactory-cli 的子命令怎么分工、template 为什么必须训练推理两侧对齐、dataset_info.json 的字段怎么填、显存表那个对不上的格子在哪里，我们各有专门篇目讲，这篇只负责把地基交代清楚。

本文依据 LlamaFactory 官方仓库（github.com/hiyouga/LlamaFactory）的 README、data/README.md、examples/ 下的配置与 src/llamafactory/hparams/ 的参数定义整理，核对日 2026-08-09。本文内容为仓库源码与文档口径，我们没有安装、训练或部署过任何模型，文中显存数字均为官方标注的估算值（README 原文标 * estimated）而非实测占用。参数与默认值随版本变动，请以 llamafactory-cli train -h 的实际输出为准。许可条款请以官方 LICENSE 原文为准，本文不构成法律意见。