LlamaFactory 昇腾 NPU 容器实战：Ascend 镜像选型、Tag 规则与一键启动全流程

本文基于 LlamaFactory 仓库中的 NPU 镜像总览文档（OVERVIEW.md）编写，系统讲解面向华为昇腾 Atlas NPU 的 LlamaFactory 官方镜像：镜像内预装组件清单、latest 与 release 两种 Tag 命名规则、docker run 拉起单卡容器的完整挂载参数、本地 docker build 的四个构建参数，以及通过 Docker Compose profile 一键启动四种硬件/系统组合的方法。读完后你可以直接在 Ascend 910B（A2）或 A3 设备上拉取、构建并验证一个可用的 LlamaFactory 训练环境，并能自行判断驱动、CANN 与 TorchNPU 的版本搭配是否正确。

一、镜像定位与快速参考

LlamaFactory 的 Ascend NPU 镜像面向华为昇腾 Atlas NPU，提供开箱即用的 LlamaFactory 环境。镜像基于昇腾 CANN 容器镜像构建，预装 Python、PyTorch、TorchNPU、DeepSpeed、LlamaFactory 等核心组件。安装细节与故障排查可参考官方文档站中的 NPU 安装指南（见 OVERVIEW.md 中的外部文档链接）。

快速参考信息如下：

• 镜像仓库：
  • docker.io/hiyouga/llamafactory
  • quay.io/ascend/llamafactory
• Dockerfile：docker/docker-npu/Dockerfile
• Docker Compose 文件：docker/docker-npu/docker-compose.yml

当前可用的 latest NPU 镜像 Tag：

硬件系列	操作系统	Tag
A2	Ubuntu 22.04	latest-910b-ubuntu
A3	Ubuntu 22.04	latest-a3-ubuntu
A2	openEuler 24.03	latest-910b-openeuler
A3	openEuler 24.03	latest-a3-openeuler

选型逻辑很直接：先看你的设备属于 A2（对应 910B 芯片）还是 A3 系列，再看你偏好的容器内操作系统是 Ubuntu 22.04 还是 openEuler 24.03，两个维度交叉即得到唯一 Tag。

二、镜像内置组件与版本约束

镜像预装的核心组件及其版本：

组件	版本
CANN	9.1.0
Python	3.12
PyTorch	2.10.0
TorchNPU	2.10.0.post2
torchvision / torchaudio	0.25.0 / 2.10.0
Transformers	构建时的最新兼容版本
Triton Ascend	3.2.1
DeepSpeed	构建时的最新兼容版本
LlamaFactory	从构建上下文中的仓库源码安装

这些版本号并非仅停留在文档里，仓库中的依赖清单可以逐条印证：

• requirements/npu.txt 固定了 torch==2.10.0、torch-npu==2.10.0.post2、torchvision==0.25.0、torchaudio==2.10.0，与上表完全一致；
• requirements/triton_ascend.txt 指定 triton-ascend==3.2.1；
• requirements/deepspeed.txt 约束 deepspeed>=0.10.0,<=0.18.4，即文档中“最新兼容版本”的具体版本区间；
• Transformers 未固定版本，因此文档注明为“构建时的最新兼容版本”。

OVERVIEW.md 同时明确：镜像不包含模型权重和数据集，需要通过目录挂载或运行时下载单独提供，并遵守对应许可证与使用条款。

从 Dockerfile 看镜像的实际构建流程

阅读 Dockerfile 可以理解上述组件清单是如何落地的，关键步骤依次是：

1. 以 BASE_IMAGE 参数（默认 quay.io/ascend/cann:9.1.0-910b-ubuntu22.04-py3.12）作为 CANN 基础镜像，因此 CANN 9.1.0 与 Python 3.12 实际上来自基础镜像 Tag 本身；
2. 先 pip uninstall -y torch torchvision torchaudio 清掉基础镜像自带的 CPU 版 PyTorch，再按 --index-url "${PYTORCH_INDEX}" 安装 npu.txt，保证 torch 与 torch-npu 成对安装；
3. 依次安装 triton_ascend.txt、deepspeed.txt；
4. 以 pip install -e . --no-build-isolation 从仓库源码安装 LlamaFactory 本体，并追加 requirements/metrics.txt 中的评测指标依赖；
5. 暴露 7860 端口（GRADIO_SERVER_PORT，LlamaBoard Web UI）与 8000 端口（API_PORT，OpenAI 风格 API 服务），这解释了后面 Compose 配置中的端口映射。

此外 Dockerfile 还设置了 VLLM_WORKER_MULTIPROC_METHOD=spawn、FLASH_ATTENTION_FORCE_BUILD=TRUE 等环境变量，前者是 PyTorch 2.x 下多进程启动方式的常见实践，后者强制源码编译 FlashAttention。

三、镜像 Tag 命名规则

NPU 镜像的 latest 与 release Tag 采用不同格式，且文档特别强调：以下规则不适用于 CUDA 镜像。

非 release 构建（短 Tag，定时更新）

非 release 构建复用以下短 Tag，每次定时构建会更新对应 Tag 指向的镜像：

latest-<chip>-<os>

字段	可选值	说明
chip	910b 或 a3	镜像适配的昇腾芯片型号
os	ubuntu 或 openeuler	容器操作系统类型

Release 构建（完整 Tag）

Release 构建使用包含全部关键版本信息的完整 Tag：

<LlamaFactory-version>-cann<CANN-version>-torch_npu<TorchNPU-version>-<chip>-<os>-<Python-version>

字段	示例	说明
LlamaFactory-version	0.9.5	LlamaFactory release 版本号
CANN-version	9.1.0	从 CANN 基础镜像 Tag 中提取
TorchNPU-version	2.10.0.post2	镜像使用的 TorchNPU 完整版本，含 .postN 等后缀
chip	910b 或 a3	镜像适配的昇腾芯片型号
os	ubuntu22.04 或 openeuler24.03	容器操作系统类型和版本
Python-version	py3.12	从 CANN 基础镜像 Tag 中提取

示例：

0.9.5-cann9.1.0-torch_npu2.10.0.post2-a3-ubuntu22.04-py3.12

完整 Tag 的价值在于可复现性：生产环境应优先锁定 release Tag，这样 CANN、TorchNPU、Python 版本全部被钉死，避免短 Tag 在定时构建后悄然变化。需要说明的是，当前仓库源码中的开发版本号为 0.9.6.dev0（见 src/llamafactory/extras/env.py），release Tag 示例中的 0.9.5 仅为文档示例。

四、快速开始

4.1 前置条件

启动容器前，宿主机需要满足：

1. 安装与镜像内 CANN 版本兼容的昇腾驱动和固件；
2. 确认宿主机执行 npu-smi info 能正常识别 NPU；
3. 安装 Docker，且当前用户有权限访问所需的昇腾设备节点和驱动文件。

驱动、固件、CANN、TorchNPU 与目标昇腾硬件必须保持相互兼容——这是 NPU 容器化部署中最常见的问题来源，版本链中任何一环不匹配都会表现为设备不可见或算子报错。

4.2 拉取并运行镜像

以下示例使用一张 NPU 启动最新的 A2 Ubuntu 镜像，请按实际环境修改 DOCKER_IMAGE 与 --device 参数：

CONTAINER_NAME=llamafactory-npu
DOCKER_IMAGE=hiyouga/llamafactory:latest-910b-ubuntu

docker run --rm -it \
  --net=host \
  --device=/dev/davinci0 \
  --device=/dev/davinci_manager \
  --device=/dev/devmm_svm \
  --device=/dev/hisi_hdc \
  -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
  -v /usr/local/dcmi:/usr/local/dcmi \
  -v /etc/ascend_install.info:/etc/ascend_install.info \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
  -v /data:/data \
  --name "$CONTAINER_NAME" \
  "$DOCKER_IMAGE" \
  /bin/bash

各参数含义与注意点：

• --net=host：NPU 训练常需要主机网络内的多机通信，直接复用宿主机网络栈；
• --device=/dev/davinci0：暴露第一张 NPU 设备节点，多卡时继续追加 --device=/dev/davinci1、--device=/dev/davinci2 等；
• --device=/dev/davinci_manager、/dev/devmm_svm、/dev/hisi_hdc：CANN 运行时依赖的管理、共享内存与调试通信设备节点；
• 四个 -v 挂载：npu-smi 工具、DCMI 目录、安装信息文件和驱动目录。注意部分驱动安装中 npu-smi 位于 /usr/local/sbin/npu-smi，此时需要相应调整挂载源路径；
• -v /data:/data：挂载数据目录，用于存放模型权重与数据集（镜像本身不含二者）。

进入容器后，用以下命令验证运行环境：

source /usr/local/Ascend/ascend-toolkit/set_env.sh
npu-smi info
python -c "import torch, torch_npu; print(torch.__version__, torch_npu.__version__, torch.npu.is_available())"
llamafactory-cli help

验证链路的含义分别是：加载 CANN toolkit 环境变量、确认设备被识别、确认 PyTorch 的 torch.npu 后端可用（torch.npu.is_available() 返回 True）、确认 LlamaFactory CLI 已安装。llamafactory-cli 这个命令名来自 pyproject.toml 中的入口点注册（llamafactory-cli 与别名 lmf 都指向 src/llamafactory/cli.py 的 main），CLI 分发逻辑在 src/llamafactory/launcher.py：train 在多卡时会经 get_device_count() 探测到多张 NPU 并自动走 torchrun 分布式启动，api、chat、webui 等子命令则分别对应 OpenAI 风格 API、命令行对话与 LlamaBoard。

4.3 本地构建镜像

在仓库根目录执行构建。以下示例构建 A2 Ubuntu 变体（注意构建上下文是仓库根目录 .，而非 Dockerfile 所在目录）：

docker build \
  -f ./docker/docker-npu/Dockerfile \
  --build-arg BASE_IMAGE=quay.io/ascend/cann:9.1.0-910b-ubuntu22.04-py3.12 \
  --build-arg PIP_INDEX=https://pypi.org/simple \
  -t llamafactory:npu-910b-ubuntu \
  .

可用的构建参数（与 Dockerfile 中的 ARG 声明一一对应）：

参数	默认值	用途
BASE_IMAGE	quay.io/ascend/cann:9.1.0-910b-ubuntu22.04-py3.12	按设备型号与容器操作系统选择对应的基础镜像
PIP_INDEX	https://pypi.org/simple	指定 Python 包索引
PYTORCH_INDEX	https://download.pytorch.org/whl/cpu	指定配合 TorchNPU 使用的 PyTorch wheel 索引
HTTP_PROXY	空	构建期间可选的 HTTP/HTTPS 代理

其中 PYTORCH_INDEX 的默认值指向 PyTorch 官方 CPU wheel 索引：NPU 场景下 PyTorch 本体是 CPU 包，NPU 加速由 TorchNPU 接管，这与 CUDA 镜像需要 GPU 版 wheel 的构建方式不同。

4.4 通过 Docker Compose 启动

docker build 只构建镜像、不启动容器。Docker Compose 复用的是同一个 Dockerfile：它读取 docker-compose.yml 中的预设配置，通过 profile 选择硬件系列与操作系统的组合。每条 up -d 命令都会后台启动对应容器；若本地不存在镜像，Compose 会先执行构建：

cd docker/docker-npu

# A2 + Ubuntu
docker compose --profile a2-ubuntu up -d

# A3 + Ubuntu
docker compose --profile a3-ubuntu up -d

# A2 + openEuler
docker compose --profile a2-openeuler up -d

# A3 + openEuler
docker compose --profile a3-openeuler up -d

只想构建镜像而不启动容器时，使用 docker compose --profile <profile> build。

从 docker-compose.yml 的源码可以看到，四个服务（llamafactory-a2-ubuntu、llamafactory-a3-ubuntu、llamafactory-a2-openeuler、llamafactory-a3-openeuler）通过 YAML 锚点共享一份 x-npu-common 公共配置，包含：

• 与 4.2 节相同的一组设备节点（/dev/davinci0 等四个）与驱动相关挂载；
• ipc: host：共享宿主机 IPC 命名空间，替代显式 shm_size（配置中注释说明 ipc: host 已覆盖共享内存需求）；
• stdin_open: true 与 tty: true、command: bash：容器起来后可以直接 docker attach 进入交互 shell；
• restart: unless-stopped：异常退出后自动拉起。

四个 profile 唯一差异在 BASE_IMAGE（如 A3 Ubuntu 用 quay.io/ascend/cann:9.1.0-a3-ubuntu22.04-py3.12）和宿主机端口映射：Web UI 依次占用 7860/7861/7862/7863，API 依次占用 8000/8001/8002/8003，因此四种容器可以在同一宿主机上并存运行而不冲突。

五、硬件支持与兼容性说明

• A2 镜像使用 910b 标记的 CANN 基础镜像，A3 镜像使用 a3 标记的基础镜像；
• 镜像构建目标同时覆盖 x86-64（linux/amd64）与 AArch64（linux/arm64）宿主机；CPU 架构与硬件系列是 A2 还是 A3 相互独立；
• Ubuntu 22.04 与 openEuler 24.03 指的是容器内部操作系统，不是宿主机系统要求；
• 旧式 NPU Tag 已由 latest-<910b|a3>-<ubuntu|openeuler> 格式取代，遇到旧脚本请对照更新；
• 正式部署前，务必验证具体驱动、固件、CANN 与 SoC 组合的兼容性。

六、许可证与免责声明

LlamaFactory 基于 Apache License 2.0 发布（见 LICENSE）。

昇腾 CANN、TorchNPU、Triton Ascend、DeepSpeed、基础操作系统软件包、模型权重、数据集及其他第三方组件分别受其自身许可证与条款约束，LlamaFactory 的许可证不会替代或覆盖这些条款。

本镜像按“原样”（AS IS）提供，不附带任何明示或暗示的保证。用户需自行负责：验证软硬件兼容性、保障容器及其运行配置的安全、遵守适用的许可证与法律，并在训练、评测或部署前审查模型与数据集的使用条款。

七、延伸阅读

• 镜像构建实现：docker/docker-npu/Dockerfile
• Compose 预设：docker/docker-npu/docker-compose.yml
• 版本依赖清单：requirements/npu.txt、requirements/triton_ascend.txt、requirements/deepspeed.txt
• CLI 入口与多卡启动逻辑：src/llamafactory/cli.py、src/llamafactory/launcher.py
• 多机/单机训练配置示例（可配合镜像内训练使用）：examples/ascend 下的 FSDP 全量与 LoRA 训练配置