官方镜像里到底装了什么：Ubuntu 22.04 + CUDA 12.4 + PyTorch 2.6.0
本文所有事实以
hiyouga/LlamaFactory官方仓库 2026-08-09 的内容为准。我们没有拉取过这个镜像、没有安装或训练过任何模型，文中所有版本号都是仓库文档里写着的值。
README 里关于官方 Docker 镜像只有一句话：这个镜像基于 Ubuntu 22.04 (x86_64)、CUDA 12.4、Python 3.11、PyTorch 2.6.0、Flash-attn 2.7.4。这句话的信息密度其实相当高——它把操作系统、CUDA、Python、PyTorch、flash-attn 这几层的版本一次性交代清楚了，前提是你愿意把它和 README 那张 Requirement 依赖表放在一起读。
绝大多数人对这句话的处理方式是直接跳过，然后照抄下面那条命令：
docker run -it --rm --gpus=all --ipc=host hiyouga/llamafactory:latest
命令能跑起来当然好，但一旦出现”我本地某个包版本对不上""这个功能在镜像里能不能用”这类问题，你还是得回来看这五个版本号。这篇就只干一件事：把这句原文拆开，逐项说清它意味着什么、不意味着什么。
五个版本号，逐项对着依赖表读
README 的 Requirement 表分 Mandatory 和 Optional 两块。把镜像那句话里出现的组件挑出来，跟表里对应的行摆在一起，是这样：
| 组件 | 镜像里标的（README 原文） | Requirement 表 Minimum | Requirement 表 Recommend |
|---|---|---|---|
| python | 3.11 | 3.11 | >=3.11 |
| torch | 2.6.0 | 2.0.0 | 2.6.0 |
| CUDA | 12.4 | 11.6 | 12.2 |
| flash-attn | 2.7.4 | 2.5.6 | 2.7.2 |
这张表我只取了这四行，因为只有这四行同时出现在”镜像那句话”和”依赖表”里。完整的依赖表还有 torchvision、transformers、datasets、accelerate、peft、trl 以及 deepspeed、bitsandbytes、vllm 这些行，镜像那句话没提它们，我也就不替它猜镜像里装的是哪个版本。
读这四行的时候有两处值得停一下：
python 和 torch 是对齐的。 镜像标 Python 3.11，正好是依赖表里 python 行的 Minimum；镜像标 PyTorch 2.6.0，正好是 torch 行的 Recommend。也就是说，这两格镜像与依赖表是能对上的：镜像里标的 torch 版本，就是 README 自己在 Recommend 列写下的那个值。
CUDA 和 flash-attn 比推荐值高一档。 CUDA 那行的 Recommend 是 12.2，镜像里标的是 12.4；flash-attn 那行的 Recommend 是 2.7.2，镜像里标的是 2.7.4。这是两处能从文档里直接读出来的差异，只陈述到这儿——为什么不一致、哪个值”更对”、是不是哪边没同步，我们没有核实，不做推断，也不拿这个去评价什么。你要做的只有一件事：如果你的某个依赖对 CUDA 或 flash-attn 版本有硬要求，别照着依赖表的 Recommend 去推断镜像里是什么，直接以镜像内的实际版本为准。
顺便说一句，CUDA 和 flash-attn 这两行在 README 里属于 Optional 那一块，不是 Mandatory。镜像把它们装进去了，是镜像这条路自己的选择，不代表你走源码安装那条路时也会自动得到它们。
(x86_64) 这三个字不能当没看见
README 原文在 Ubuntu 22.04 后面明确跟了 (x86_64)。这是一个架构限定，写在了官方那句话里。
它有没有 ARM 的对应镜像、latest 这个 tag 之外还有哪些 tag、各 tag 分别是什么架构——这些 README 那句话都没说。README 只给了一个去处：预构建镜像列表在 Docker Hub 的 tags 页（https://hub.docker.com/r/hiyouga/llamafactory/tags）。所以判断路径很直接：你的机器不是 x86_64，或者你需要非 latest 的 tag，就去 tags 页看，不要拿这句 README 去推断。 我们没有拉过任何一个 tag，也不替它列清单。
镜像替你解决了什么，没替你解决什么
镜像这条路真正收敛的是”软件栈版本”这一层：操作系统、CUDA、Python、PyTorch、flash-attn 这几样被一次性钉死，你不用在本地环境里跟它们逐个谈判。README 用 > [!IMPORTANT] 强调过一句 Installation is mandatory.，安装这一步躲不掉，镜像的意义是让这一步不污染你本地那套 Python 环境。
它明确没有解决的是硬件这一层。README 另有一张 Hardware Requirement 表，表头上方 README 自己标了 * estimated（估算）——那不是实测占用，我们也没有跑过任何一次训练。举个跟本文最相关的例子：7B 这一列上，Full（bf16 或 fp16，32 位）标的是 120GB，Freeze/LoRA/GaLore/APOLLO/BAdam/OFT（16 位）标的是 16GB。我引这两格只是为了说明一件事：镜像拉下来、容器起来了，跟你的卡跑不跑得动，是两个完全独立的问题。 至于”你的显卡够不够”，这张表是估算值，我不据此给任何结论，你得自己按官方文档和实际情况判断。那张表内部还有一处能核实到的格子对不上，我们另有一篇专门讲，这里不展开。
同样地，镜像也不替你解决模型和数据集从哪儿下载的问题——那是环境变量那一层的事，下面单说。
自建镜像与换后端
不想用 latest，想自己构建，README 给的是这两步：
cd docker/docker-cuda/
docker compose up -d
README 也说了，仓库的 docker/ 目录下按后端分了子目录，docker-cuda 只是其中之一。所以如果你不是 CUDA 这条线，路径要换成对应后端的那个子目录——具体有哪几个、各自叫什么，以你拉下来的仓库当前目录为准，别照抄本文或任何一篇教程里的路径。
Ascend NPU 这条线 README 另给了一个很具体的提示：在配置里设 double_quantization: false，并给了参考示例 examples/train_qlora/qwen3_lora_sft_bnb_npu.yaml。这条提示是写在 NPU 的折叠块里的，跟”用不用 Docker”无关，但如果你是走 NPU 后端的容器，两件事会同时撞上来，所以顺手记一下。
docker run 那条命令里的 -it、--rm、--gpus=all、--ipc=host 都是 Docker 自己的选项，语义以 Docker 官方文档为准，跟 LlamaFactory 无关，我不在这儿转述。
Windows 与 Linux/macOS：环境变量这一层要分清
如果 Hugging Face 下载有问题，README 给的办法是切下载源。这里的写法在两个平台上不一样，别混用。
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。
用 Docker 的时候，这里多了一层需要你自己想清楚的东西：你是在宿主机上设这个变量，还是在容器里设。README 给的是变量名和值，没有给”在容器里怎么设”的写法——具体用什么机制把变量带进容器，属于 Docker 自己的用法，官方这段没写，我也不替它补。你只要记住宿主机的 shell 环境和容器内的环境是两回事，别在宿主机 set 完就以为容器里也有。
不走容器、想要一个隔离的本地环境，README 的折叠块里还给了 uv 的用法，一行进 Web UI：
uv run llamafactory-cli webui
顺带说两处”仓库内部口径不一致”
既然聊到照抄命令，有两处摆在明面上的差异值得知道，免得你搜资料时绕路。
一是项目名。 仓库当前的真实路径是 hiyouga/LlamaFactory，README 给的 clone 地址也是这个；但 src/llamafactory/launcher.py 的欢迎语里写的项目主页仍然是带连字符的旧名 https://github.com/hiyouga/LLaMA-Factory，README 正文里两种写法也混着用。这是仓库里能核实到的新旧写法并存，说到这儿为止——改名时间、原因、有没有重定向，我们都没核实，不推断。对你的实际影响只有一条：搜 issue 的时候两种拼法都试一遍。
二是 trust_remote_code。 这个参数在源码里的默认值是 False，而 examples/ 下的示例 YAML 普遍写的是 true。同一件事在”源码默认”和”官方示例”两层给出的取值不同，这也是可核实的差异，同样只陈述、不推断原因。它对你的意义是：照抄示例 YAML 跑起来，和用默认值跑起来，在这一项上不是同一个配置，你自己得知道当前跑的是哪一种。这个参数具体牵动什么，我们另有一篇专门讲。
那么，该不该走镜像这条路
按你现在卡在哪儿判断，比按功能对比判断快：
- 你只是想先把环境跑通、不想让 CUDA / PyTorch / flash-attn 这几样在本地互相打架，镜像正是为这一层准备的，README 那句版本声明就是它给你的承诺范围；
- 你的机器不是 x86_64，或者你对某个依赖版本有硬要求，先去 Docker Hub 的 tags 页确认，再决定拉哪个 tag；
- 你走的是 NPU 或其它非 CUDA 后端，进
docker/找对应子目录，别停在docker-cuda； - 你要的是”能不能训得动”的答案，那镜像帮不上忙——那是显存和硬件那一层的事，README 的估算表只能当参考，不能当结论；
- 你完全不想碰容器，README 里还有源码安装和 uv 两条路，另外 README 还列了三条云端试用入口（Colab、PAI-DSW、AMD GPU Cloud），我们另有篇目交代。
镜像那句版本声明看着不起眼，但它是文档里为数不多能一句话说清”给你锁了哪几层”的地方。花两分钟把它和 Requirement 表对一遍，比出问题之后翻 issue 划算得多。
本文依据 LlamaFactory 官方仓库（github.com/hiyouga/LlamaFactory）的 README、data/README.md、examples/ 下的配置与 src/llamafactory/hparams/ 的参数定义整理，核对日 2026-08-09。本文内容为仓库源码与文档口径，我们没有安装、训练或部署过任何模型，文中显存数字均为官方标注的估算值（README 原文标 * estimated）而非实测占用。参数与默认值随版本变动，请以 llamafactory-cli train -h 的实际输出为准。安全相关做法请结合自身环境评估，本文不构成安全方案建议。