mirror of https://github.com/hiyouga/LLaMA-Factory.git synced 2026-08-17 13:35:44 +08:00

Files

xvxuopop 0bbe481e6e [docker] upgrade NPU images to CANN 9.1 and PyTorch 2.10 (#10729 )

2026-08-10 11:20:41 +08:00

6.9 KiB

Raw Blame History

面向昇腾 NPU 的 LlamaFactory 镜像

LlamaFactory 昇腾 NPU 镜像面向华为昇腾 Atlas NPU，提供可直接使用的 LlamaFactory 环境。镜像基于昇腾 CANN 容器镜像构建，预装 Python、PyTorch、TorchNPU、DeepSpeed、LlamaFactory 等组件。

安装方法和问题排查请参考 LlamaFactory NPU 安装及配置文档。

快速参考

镜像仓库：
- 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`

镜像介绍

镜像内预装以下主要组件：

组件	版本
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	从构建上下文中的仓库源码安装

镜像不包含模型权重和数据集。请通过目录挂载或运行时下载的方式单独提供，并遵守对应的许可证和使用要求。

镜像 Tag 说明

NPU 镜像的 latest 和 release tag 使用不同格式；以下规则不适用于 CUDA 镜像。

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

latest-<芯片信息>-<操作系统>

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

Release 构建使用完整 tag：

<LlamaFactory版本>-cann<CANN版本>-torch_npu<TorchNPU版本>-<芯片信息>-<操作系统>-<Python版本>

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

例如：

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

快速开始

前置条件

启动容器前需要：

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

驱动、固件、CANN、TorchNPU 与目标昇腾硬件需要保持兼容。

拉取并运行镜像

以下示例使用一张 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

部分驱动环境中的 npu-smi 位于 /usr/local/sbin/npu-smi，此时需要调整挂载源路径。使用多张 NPU 时，继续追加 --device=/dev/davinci<N> 参数。

进入容器后验证运行环境：

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

本地构建镜像

在仓库根目录执行构建。以下示例构建 A2 Ubuntu 镜像：

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 \
  .

可用构建参数：

参数	默认值	用途
`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 代理

通过 Docker Compose 启动

前面的 docker build 命令直接调用 Dockerfile，只构建镜像，不启动容器。Docker Compose 不使用另一套构建逻辑：它读取 docker-compose.yml 中的预设配置，复用同一个 Dockerfile，并通过 profile 选择硬件系列和操作系统组合。下面的 up -d 会在后台启动容器；若本地镜像不存在，Docker 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 构建镜像而不启动容器，请使用 docker compose --profile <profile> build。

硬件支持与兼容性说明

A2 镜像使用标记为 910b 的 CANN 基础镜像，A3 镜像使用标记为 a3 的 CANN 基础镜像。
镜像构建目标同时包含 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 发布。

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

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

6.9 KiB Raw Blame History Unescape Escape