源码、Docker、uv：三条安装路径分别适合谁

2026-08-09

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

LlamaFactory 的 README 在安装这一节用 > [!IMPORTANT] 加了一句 Installation is mandatory.——装是必须的，没有”先把源码拉下来直接跑一下试试”这条捷径。而它给出的安装方式不止一种：从源码装、从 Docker 镜像装、用 uv 建隔离环境，另外还单列了三条根本不用装的云端入口。这几条不是”任选其一都一样”，它们照顾的是完全不同的处境。

这篇不讲怎么训练，只回答一件事：你现在这台机器、这个项目阶段，应该走哪一条。

先看那条会把人拦在门外的下限

README 的 Requirement 表分 Mandatory 和 Optional 两张。整张表各行的取值我们另有一篇专门讲，这里只挑跟”能不能装”直接相关的两行。

第一行是 Mandatory 表里的 python：Minimum 3.11、Recommend >=3.11。这一行的特别之处在于，最低和推荐是同一个数——也就是说 3.11 不是”建议升到”的目标，而是下限。如果你手上是更老的解释器，先解决 Python 版本，再谈后面三条路走哪条，否则三条都走不通。

第二行在 Optional 表里：CUDA，Minimum 11.6、Recommend 12.2。它被放在 Optional 里，说明它不是每种用法的硬前提；但它同时也是下面 Docker 那条路的判断依据之一，等会儿会用到。

其余像 torch、transformers、datasets、accelerate、peft、trl 的版本区间，装的时候由 pip 去解，你要盯的是 Python 这一行。

路径一：从源码装

README 给的四行，原样照抄：

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

这里插一句跟安装直接相关的小坑：仓库内部新旧写法并存。当前真实路径是 hiyouga/LlamaFactory（clone URL 就是上面那一行），PyPI 包名是 llamafactory，命令行是 llamafactory-cli；但 src/llamafactory/launcher.py 的欢迎语里，项目主页写的仍是带连字符的旧名 https://github.com/hiyouga/LLaMA-Factory，README 正文里也混用两种写法。这是仓库里能核实到的差异，如实说到这儿就够了——改名时间、原因、有没有重定向，我们都没核实过，不推断。对你的实际影响只有一条：搜教程、翻 issue 时两种拼法都试一遍。

四行里最关键的是第三行的 pip install -e .。-e 是可编辑安装，意味着你后面改仓库里的代码，装好的包会跟着变。这一点决定了这条路适合谁：

你要改源码、要打补丁、要读着 src/llamafactory/ 下的实现调试；
你要照着 examples/ 下那些 YAML 改配置——它们就在你 clone 下来的这个目录里，本地有一份完整仓库比翻网页方便得多；
你要装可选依赖。README 列的可选依赖是 metrics 和 deepspeed，一次装两个的写法是：

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

README 还说明，特定功能的额外依赖放在 examples/requirements/ 下。这条信息的用处在排查阶段：某个功能报缺包，先去这个目录看看是不是有对应的 requirements 文件，而不是凭报错名一个个 pip install。

这条路的代价也很明确：你得自己面对本地的 CUDA、驱动、Python 版本和已有环境的冲突。如果你的机器上已经躺着好几个深度学习项目，这一步的时间开销不由这个项目决定。

路径二：从官方 Docker 镜像装

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

这一行请原样用，不要顺手删选项——README 给的就是这个组合，我们没有跑过它，也不替它论证某个选项能不能省。

这条路的最大信息量在于，README 原文写明了这个镜像里预置了什么：Ubuntu 22.04 (x86_64)、CUDA 12.4、Python 3.11、PyTorch 2.6.0、Flash-attn 2.7.4。把它跟上一节那两行对照着看，这条路的适用判断就很直白了：

Python 3.11 那条下限，镜像里已经满足，你本地是什么版本不影响；
CUDA 12.4 已经在镜像里，高于 Optional 表标的 Recommend 12.2；
但它标的是 x86_64。你的机器架构不在这一条上，这条路就不成立。

预构建镜像不止 latest 一个，README 把完整列表指向了 Docker Hub 的 tags 页（https://hub.docker.com/r/hiyouga/llamafactory/tags）。要自己构建的话，README 给的是：

cd docker/docker-cuda/
docker compose up -d

注意目录名里的 docker-cuda——仓库的 docker/ 目录是按后端分了子目录的。这意味着你如果不是 CUDA 后端，别照抄 docker-cuda 这个路径，先去 docker/ 下看看有哪些子目录。

所以这条路适合：手上是 x86_64 + NVIDIA 的机器，不想动本地环境，或者本地环境已经乱到不想收拾；也适合要在多台机器上拿到同一份环境的场景。不适合：你打算改源码——镜像是给你跑的，不是给你改的（要改就回路径一，或者自建镜像）。

路径三：用 uv 建隔离环境

README 里这一段的折叠块标题是 “Setting up a virtual environment with uv”，里面给的是一条命令：

uv run llamafactory-cli webui

需要说清楚的是：README 这个折叠块里给的就是这一行，没有更多步骤。我们不替它补前置命令，你手上 uv 该怎么装、项目目录该怎么初始化，请以 uv 自己的官方文档为准。

这一行的落点是 webui 这个子命令。README 大标题下的一句话定位原文是 “Easily fine-tune 100+ large language models with zero-code CLI and Web UI”，命令行与 Web UI 是并列的两种入口，而 uv 这个折叠块给的正是后者对应的子命令。所以这条路照顾的处境很具体：你想在一个不污染全局环境的地方，先把这个入口打开看看，而不是先去啃 YAML。至于打开之后界面里长什么样、有哪些控件、点起来什么手感，我们没有跑过，不描述。

那么，三条路怎么选

按处境倒推，比按功能表选快：

本地就是 x86_64 + NVIDIA，只想尽快有个能跑的环境 → Docker 镜像。它把 Python 3.11、CUDA 12.4、PyTorch 2.6.0 这几件事一次性摁死了。
你要读代码、改代码、跟着 examples/ 下的 YAML 走 → 源码 + pip install -e .。这条路给你的是一份可编辑的完整仓库。
你只想先看一眼，又不想弄脏本地 Python 环境 → uv 那一行。
机器架构或后端不在 CUDA/x86_64 这条线上 → 先去 docker/ 目录看有没有对应后端的子目录，别默认 docker-cuda。
你连”是不是要用它”都还没定 → 下面那三条云端入口，一行都不用装。

还有第四种选择：先别装

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 的多后端文档页（llamafactory.readthedocs.io/en/latest/multibackend/npu/index.html）。

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

装完立刻会遇到的一件事：下载源，Windows 要单写

这一步严格说不属于安装，但它是三条路走完之后共同的下一个坎：模型拉不下来。README 给了两个环境变量，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（Windows 同样是 set 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 的 Hardware Requirement 表里，7B 那一列 Full（bf16 或 fp16，32）写的是 120GB，Freeze/LoRA/GaLore/APOLLO/BAdam/OFT（16）写的是 16GB，QLoRA / QOFT（4）写的是 6GB。这三格决定于你选哪种训练方法，跟你是 pip install -e . 装的还是 docker 拉的没有关系。

而且这张表在表头上方被 README 自己标了 * estimated（估算），它不是实测占用，我们也没有跑过任何一次训练。所以这里只做一件事：把表里写着的数字念给你听，说明它跟安装路径无关。至于”你那张卡够不够”，一张标了估算的表不足以下这个结论，我们不给。这张表内部还有一处对不上的格子，我们另有一篇专门讲。

同样地，官方文档站 llamafactory.readthedocs.io 在 README 里被标了 (WIP)。装的过程里如果文档和仓库里的 examples/ 示例、--help 输出打架，以后两者为准。

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