From 19e9fe3ced33c5bc442ad32d36a3442dcac870ef Mon Sep 17 00:00:00 2001
From: xvxuopop <xvxuopop@gmail.com>
Date: Fri, 24 Jul 2026 15:22:01 +0800
Subject: [PATCH] [docker] improve NPU image build and distribution (#10664)

---
 .github/workflows/docker.yml         |  36 -----
 .github/workflows/docker_npu.yml     | 115 +++++++++++++
 README.md                            |  36 ++++-
 README_zh.md                         |  36 ++++-
 docker/docker-npu/OVERVIEW.md        | 232 +++++++++++++++++++++++++++
 docker/docker-npu/OVERVIEW.zh.md     | 232 +++++++++++++++++++++++++++
 docker/docker-npu/docker-compose.yml | 110 ++++++++-----
 7 files changed, 701 insertions(+), 96 deletions(-)
 create mode 100644 .github/workflows/docker_npu.yml
 create mode 100644 docker/docker-npu/OVERVIEW.md
 create mode 100644 docker/docker-npu/OVERVIEW.zh.md

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index 30a2e7779..84bfddbf5 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -29,8 +29,6 @@ jobs:
       matrix:
         include:
           - device: "cuda"
-          - device: "npu-a2"
-          - device: "npu-a3"
 
     runs-on: ubuntu-latest
 
@@ -71,14 +69,6 @@ jobs:
           username: ${{ vars.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      - name: Login to Quay
-        if: ${{ github.event_name != 'pull_request' && startsWith(matrix.device, 'npu') }}
-        uses: docker/login-action@v3
-        with:
-          registry: quay.io
-          username: ${{ vars.QUAY_ASCEND_USERNAME }}
-          password: ${{ secrets.QUAY_ASCEND_TOKEN }}
-
       - name: Build and push Docker image (CUDA)
         if: ${{ matrix.device == 'cuda' }}
         uses: docker/build-push-action@v6
@@ -88,29 +78,3 @@ jobs:
           push: ${{ github.event_name != 'pull_request' }}
           tags: |
             docker.io/hiyouga/llamafactory:${{ steps.version.outputs.tag }}
-
-      - name: Build and push Docker image (NPU-A2)
-        if: ${{ matrix.device == 'npu-a2' }}
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          platforms: linux/amd64,linux/arm64
-          file: ./docker/docker-npu/Dockerfile
-          push: ${{ github.event_name != 'pull_request' }}
-          tags: |
-            docker.io/hiyouga/llamafactory:${{ steps.version.outputs.tag }}-npu-a2
-            quay.io/ascend/llamafactory:${{ steps.version.outputs.tag }}-npu-a2
-
-      - name: Build and push Docker image (NPU-A3)
-        if: ${{ matrix.device == 'npu-a3' }}
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          platforms: linux/amd64,linux/arm64
-          file: ./docker/docker-npu/Dockerfile
-          build-args: |
-            BASE_IMAGE=quay.io/ascend/cann:9.0.0-a3-ubuntu22.04-py3.11
-          push: ${{ github.event_name != 'pull_request' }}
-          tags: |
-            docker.io/hiyouga/llamafactory:${{ steps.version.outputs.tag }}-npu-a3
-            quay.io/ascend/llamafactory:${{ steps.version.outputs.tag }}-npu-a3
diff --git a/.github/workflows/docker_npu.yml b/.github/workflows/docker_npu.yml
new file mode 100644
index 000000000..209128a32
--- /dev/null
+++ b/.github/workflows/docker_npu.yml
@@ -0,0 +1,115 @@
+name: docker-npu
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "17 2 * * *"
+      timezone: "Asia/Shanghai"
+  release:
+    types:
+      - published
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - device: "npu-a2"
+            os: "ubuntu"
+            base_image: "quay.io/ascend/cann:9.0.0-910b-ubuntu22.04-py3.11"
+          - device: "npu-a3"
+            os: "ubuntu"
+            base_image: "quay.io/ascend/cann:9.0.0-a3-ubuntu22.04-py3.11"
+          - device: "npu-a2"
+            os: "openeuler"
+            base_image: "quay.io/ascend/cann:9.0.0-910b-openeuler24.03-py3.11"
+          - device: "npu-a3"
+            os: "openeuler"
+            base_image: "quay.io/ascend/cann:9.0.0-a3-openeuler24.03-py3.11"
+
+    runs-on: ubuntu-latest
+
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}-${{ matrix.device }}-${{ matrix.os }}
+      cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+    environment:
+      name: docker
+      url: https://hub.docker.com/r/hiyouga/llamafactory
+
+    steps:
+      - name: Free up disk space
+        uses: jlumbroso/free-disk-space@v1.3.1
+        with:
+          tool-cache: true
+          docker-images: false
+
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Get llamafactory version
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" = "release" ]; then
+            echo "tag=$(grep -oP 'VERSION = "\K[^"]+' src/llamafactory/extras/env.py)" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=latest" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Get NPU image tag
+        id: npu_tag
+        env:
+          BASE_IMAGE: ${{ matrix.base_image }}
+          DEVICE: ${{ matrix.device }}
+          MATRIX_OS: ${{ matrix.os }}
+          LLAMAFACTORY_VERSION: ${{ steps.version.outputs.tag }}
+        run: |
+          base_image_tag="${BASE_IMAGE##*:}"
+          cann_version="${base_image_tag%%-*}"
+          torch_npu_version="$(sed -nE 's/^torch[-_]npu==([0-9]+(\.[0-9]+)*).*/\1/p' requirements/npu.txt)"
+          accelerator="${DEVICE#npu-}"
+          accelerator="${accelerator^^}"
+          operating_system="$(grep -oE '(ubuntu|openeuler)' <<< "${base_image_tag}" | head -n 1)"
+          python_version="$(grep -oE 'py[0-9]+\.[0-9]+' <<< "${base_image_tag}" | head -n 1)"
+
+          if [[ -z "${cann_version}" || -z "${torch_npu_version}" || -z "${operating_system}" || -z "${python_version}" ]]; then
+            echo "Failed to derive the NPU image tag from ${BASE_IMAGE} and requirements/npu.txt" >&2
+            exit 1
+          fi
+
+          if [[ "${operating_system}" != "${MATRIX_OS}" ]]; then
+            echo "Operating system ${operating_system} derived from ${BASE_IMAGE} does not match matrix OS ${MATRIX_OS}" >&2
+            exit 1
+          fi
+
+          echo "tag=${LLAMAFACTORY_VERSION}-cann${cann_version}-torch_npu${torch_npu_version}-${accelerator}-${operating_system}-${python_version}" >> "$GITHUB_OUTPUT"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Login to Quay
+        uses: docker/login-action@v3
+        with:
+          registry: quay.io
+          username: ${{ vars.QUAY_ASCEND_USERNAME }}
+          password: ${{ secrets.QUAY_ASCEND_TOKEN }}
+
+      - name: Build and push Docker image (${{ matrix.device }}-${{ matrix.os }})
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          file: ./docker/docker-npu/Dockerfile
+          build-args: |
+            BASE_IMAGE=${{ matrix.base_image }}
+          push: true
+          tags: |
+            docker.io/hiyouga/llamafactory:${{ steps.npu_tag.outputs.tag }}
+            quay.io/ascend/llamafactory:${{ steps.npu_tag.outputs.tag }}
diff --git a/README.md b/README.md
index c5d2b40c2..9ed3aaea3 100644
--- a/README.md
+++ b/README.md
@@ -604,19 +604,23 @@ To enable FlashAttention-2 on the Windows platform, please use the script from [
 
 <details><summary>For Ascend NPU users</summary>
 
-To install LLaMA Factory on Ascend NPU devices, please upgrade Python to version 3.10 or higher: `pip install -r requirements/npu.txt`. Additionally, you need to install the **Ascend CANN Toolkit and Kernels**. Please follow the [installation tutorial](https://llamafactory.readthedocs.io/en/latest/advanced/npu_installation.html).
+To install LLaMA Factory on Ascend NPU devices, please upgrade Python to version 3.10 or higher: `pip install -r requirements/npu.txt`. Additionally, you need to install the **Ascend CANN Toolkit and Kernels**. Please follow the [installation tutorial](https://llamafactory.readthedocs.io/en/latest/multibackend/npu/npu_installation.html).
 
 
 You can also download the pre-built Docker images:
 
 ```bash
 # Docker Hub
-docker pull hiyouga/llamafactory:latest-npu-a2
-docker pull hiyouga/llamafactory:latest-npu-a3
+docker pull hiyouga/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A2-ubuntu-py3.11
+docker pull hiyouga/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A3-ubuntu-py3.11
+docker pull hiyouga/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A2-openeuler-py3.11
+docker pull hiyouga/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A3-openeuler-py3.11
 
 # quay.io
-docker pull quay.io/ascend/llamafactory:latest-npu-a2
-docker pull quay.io/ascend/llamafactory:latest-npu-a3
+docker pull quay.io/ascend/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A2-ubuntu-py3.11
+docker pull quay.io/ascend/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A3-ubuntu-py3.11
+docker pull quay.io/ascend/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A2-openeuler-py3.11
+docker pull quay.io/ascend/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A3-openeuler-py3.11
 ```
 
 #### Install BitsAndBytes
@@ -697,12 +701,28 @@ docker compose up -d
 docker compose exec llamafactory bash
 ```
 
-For Ascend NPU users:
+For Ascend NPU users (A2 with Ubuntu by default):
 
 ```bash
 cd docker/docker-npu/
-docker compose up -d
-docker compose exec llamafactory bash
+docker compose up -d llamafactory-a2-ubuntu
+docker compose exec llamafactory-a2-ubuntu bash
+```
+
+Other NPU variants can be started with their corresponding profiles and services:
+
+```bash
+# A3 with Ubuntu
+docker compose --profile a3 up -d llamafactory-a3-ubuntu
+docker compose exec llamafactory-a3-ubuntu bash
+
+# A2 with openEuler
+docker compose --profile openeuler up -d llamafactory-a2-openeuler
+docker compose exec llamafactory-a2-openeuler bash
+
+# A3 with openEuler
+docker compose --profile a3-openeuler up -d llamafactory-a3-openeuler
+docker compose exec llamafactory-a3-openeuler bash
 ```
 
 For AMD ROCm users:
diff --git a/README_zh.md b/README_zh.md
index 79dd90e9d..a2b13760a 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -605,18 +605,22 @@ pip install https://github.com/jllllll/bitsandbytes-windows-webui/releases/downl
 
 <details><summary>昇腾 NPU 用户指南</summary>
 
-在昇腾 NPU 设备上安装 LLaMA Factory 时，请升级 Python 到 3.10 及以上，并需要指定额外依赖项，使用 `pip install -r requirements/npu.txt` 命令安装。此外，还需要安装 **Ascend CANN Toolkit 与 Kernels**，安装方法请参考[安装教程](https://llamafactory.readthedocs.io/zh-cn/latest/advanced/npu_installation.html)。
+在昇腾 NPU 设备上安装 LLaMA Factory 时，请升级 Python 到 3.10 及以上，并需要指定额外依赖项，使用 `pip install -r requirements/npu.txt` 命令安装。此外，还需要安装 **Ascend CANN Toolkit 与 Kernels**，安装方法请参考[安装教程](https://llamafactory.readthedocs.io/zh-cn/latest/multibackend/npu/npu_installation.html)。
 
 您可以直接下载预安装的最新docker镜像：
 
 ```bash
 # Docker Hub
-docker pull hiyouga/llamafactory:latest-npu-a2
-docker pull hiyouga/llamafactory:latest-npu-a3
+docker pull hiyouga/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A2-ubuntu-py3.11
+docker pull hiyouga/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A3-ubuntu-py3.11
+docker pull hiyouga/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A2-openeuler-py3.11
+docker pull hiyouga/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A3-openeuler-py3.11
 
 # quay.io
-docker pull quay.io/ascend/llamafactory:latest-npu-a2
-docker pull quay.io/ascend/llamafactory:latest-npu-a3
+docker pull quay.io/ascend/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A2-ubuntu-py3.11
+docker pull quay.io/ascend/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A3-ubuntu-py3.11
+docker pull quay.io/ascend/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A2-openeuler-py3.11
+docker pull quay.io/ascend/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A3-openeuler-py3.11
 ```
 
 #### 安装 BitsAndBytes
@@ -697,12 +701,28 @@ docker compose up -d
 docker compose exec llamafactory bash
 ```
 
-昇腾 NPU 用户：
+昇腾 NPU 用户（默认使用 A2 和 Ubuntu）：
 
 ```bash
 cd docker/docker-npu/
-docker compose up -d
-docker compose exec llamafactory bash
+docker compose up -d llamafactory-a2-ubuntu
+docker compose exec llamafactory-a2-ubuntu bash
+```
+
+其他 NPU 组合可以通过对应的 profile 和服务启动：
+
+```bash
+# A3 + Ubuntu
+docker compose --profile a3 up -d llamafactory-a3-ubuntu
+docker compose exec llamafactory-a3-ubuntu bash
+
+# A2 + openEuler
+docker compose --profile openeuler up -d llamafactory-a2-openeuler
+docker compose exec llamafactory-a2-openeuler bash
+
+# A3 + openEuler
+docker compose --profile a3-openeuler up -d llamafactory-a3-openeuler
+docker compose exec llamafactory-a3-openeuler bash
 ```
 
 AMD ROCm 用户：
diff --git a/docker/docker-npu/OVERVIEW.md b/docker/docker-npu/OVERVIEW.md
new file mode 100644
index 000000000..b8ab121d5
--- /dev/null
+++ b/docker/docker-npu/OVERVIEW.md
@@ -0,0 +1,232 @@
+# LLaMA Factory for Ascend NPU
+
+LLaMA Factory Ascend NPU images provide a ready-to-use environment for fine-tuning, evaluating, and serving large language and multimodal models on Huawei Ascend Atlas NPUs. The images are based on Ascend CANN container images and include LLaMA Factory, Python, PyTorch, torch-npu, Triton Ascend, DeepSpeed, and the metric dependencies used by LLaMA Factory.
+
+For installation and troubleshooting details, see the [English NPU installation guide](https://llamafactory.readthedocs.io/en/latest/multibackend/npu/npu_installation.html).
+
+## Quick Reference
+
+- Image registries:
+  - `docker.io/hiyouga/llamafactory`
+  - `quay.io/ascend/llamafactory`
+- Dockerfile: `docker/docker-npu/Dockerfile`
+- Docker Compose file: `docker/docker-npu/docker-compose.yml`
+- Default base image: `quay.io/ascend/cann:9.0.0-910b-ubuntu22.04-py3.11`
+- Supported accelerators: Ascend A2 and A3
+- Supported container operating systems: Ubuntu 22.04 and openEuler 24.03
+- Target CPU architectures: `linux/amd64` and `linux/arm64`
+- Exposed ports:
+  - `7860`: LLaMA Board Web UI
+  - `8000`: API service
+- Ascend environment script: `/usr/local/Ascend/ascend-toolkit/set_env.sh`
+
+The current image variants are:
+
+| Accelerator | Container OS | CANN base image |
+| --- | --- | --- |
+| A2 | Ubuntu 22.04 | `quay.io/ascend/cann:9.0.0-910b-ubuntu22.04-py3.11` |
+| A3 | Ubuntu 22.04 | `quay.io/ascend/cann:9.0.0-a3-ubuntu22.04-py3.11` |
+| A2 | openEuler 24.03 | `quay.io/ascend/cann:9.0.0-910b-openeuler24.03-py3.11` |
+| A3 | openEuler 24.03 | `quay.io/ascend/cann:9.0.0-a3-openeuler24.03-py3.11` |
+
+## Image Contents and Intended Use
+
+The image is intended for Ascend NPU training, fine-tuning, evaluation, Web UI, and API workflows supported by LLaMA Factory. It installs the following core components:
+
+| Component | Version or source |
+| --- | --- |
+| CANN | Inherited from the selected CANN 9.0.0 base image |
+| Python | Python 3.11, inherited from the base image |
+| PyTorch | `2.7.1` |
+| torch-npu | `2.7.1.post4` |
+| torchvision | `0.22.1` |
+| torchaudio | `2.7.1` |
+| Triton Ascend | `3.2.1` |
+| DeepSpeed | `>=0.10.0,<=0.18.4` |
+| LLaMA Factory | Installed from the repository build context |
+
+The image does not include model weights or datasets. Mount or download them separately and comply with their respective licenses and acceptable-use requirements.
+
+## Image Tags and Dockerfile Archive
+
+Images use the following tag format:
+
+```text
+<llamafactory-version>-cann<cann-version>-torch_npu<torch-npu-version>-<accelerator>-<os>-<python-version>
+```
+
+| Field | Example | Description |
+| --- | --- | --- |
+| `llamafactory-version` | `latest` or `0.9.6` | Non-release builds use `latest`; release builds use the LLaMA Factory version |
+| `cann-version` | `9.0.0` | Parsed from the CANN base image tag |
+| `torch-npu-version` | `2.7.1` | Parsed from `requirements/npu.txt`; a suffix such as `.post4` is not included in the image tag |
+| `accelerator` | `A2` or `A3` | Ascend hardware generation selected for the image |
+| `os` | `ubuntu` or `openeuler` | Container operating system family |
+| `python-version` | `py3.11` | Parsed from the CANN base image tag |
+
+Examples:
+
+```text
+latest-cann9.0.0-torch_npu2.7.1-A2-ubuntu-py3.11
+latest-cann9.0.0-torch_npu2.7.1-A3-openeuler-py3.11
+0.9.6-cann9.0.0-torch_npu2.7.1-A3-ubuntu-py3.11
+```
+
+The CPU architecture is not part of the tag. Published images are configured as multi-platform images, and Docker selects the `linux/amd64` or `linux/arm64` manifest for the host automatically.
+
+The Dockerfile and its distribution overview are archived together at:
+
+```text
+docker/docker-npu/
+├── Dockerfile
+├── OVERVIEW.md
+├── OVERVIEW.zh.md
+└── docker-compose.yml
+```
+
+## Quick Start
+
+### Prerequisites
+
+Before starting a container:
+
+1. Install an Ascend driver and firmware compatible with the CANN version in the image.
+2. Verify that `npu-smi info` works on the host.
+3. Install Docker with permission to access the required Ascend device nodes and driver files.
+
+Driver, firmware, CANN, torch-npu, and the target Ascend hardware must be mutually compatible.
+
+### Pull and Run
+
+The following example starts the latest A2 Ubuntu image with one NPU. Change the image tag and `/dev/davinci0` as needed.
+
+```bash
+export IMAGE=quay.io/ascend/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A2-ubuntu-py3.11
+
+docker pull "$IMAGE"
+
+docker run --rm -it \
+  --name llamafactory-npu \
+  --ipc=host \
+  --device=/dev/davinci0 \
+  --device=/dev/davinci_manager \
+  --device=/dev/devmm_svm \
+  --device=/dev/hisi_hdc \
+  -v /usr/local/dcmi:/usr/local/dcmi \
+  -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
+  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
+  -v /etc/ascend_install.info:/etc/ascend_install.info \
+  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
+  -p 7860:7860 \
+  -p 8000:8000 \
+  "$IMAGE" \
+  bash
+```
+
+The host path for `npu-smi` may be `/usr/local/sbin/npu-smi` on some driver installations. Adjust the mount source when necessary. Add more `--device=/dev/davinci<N>` options to expose additional NPUs.
+
+Verify the runtime inside the container:
+
+```bash
+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
+```
+
+Start LLaMA Board when needed:
+
+```bash
+llamafactory-cli webui
+```
+
+### Build Locally
+
+Run the build from the repository root. The following example builds the A3 openEuler variant:
+
+```bash
+docker build \
+  -f ./docker/docker-npu/Dockerfile \
+  --build-arg BASE_IMAGE=quay.io/ascend/cann:9.0.0-a3-openeuler24.03-py3.11 \
+  --build-arg PIP_INDEX=https://pypi.org/simple \
+  -t llamafactory:npu-a3-openeuler \
+  .
+```
+
+Available build arguments:
+
+| Argument | Default | Purpose |
+| --- | --- | --- |
+| `BASE_IMAGE` | A2 Ubuntu CANN 9.0.0 image | Selects the accelerator and container OS variant |
+| `PIP_INDEX` | `https://pypi.org/simple` | Selects the Python package index |
+| `PYTORCH_INDEX` | `https://download.pytorch.org/whl/cpu` | Selects the PyTorch wheel index used with torch-npu |
+| `HTTP_PROXY` | Empty | Provides an optional HTTP/HTTPS proxy during the build |
+
+Docker Compose can build and start each supported variant:
+
+```bash
+cd docker/docker-npu
+
+# A2 with Ubuntu
+docker compose up -d llamafactory-a2-ubuntu
+
+# A3 with Ubuntu
+docker compose --profile a3 up -d llamafactory-a3-ubuntu
+
+# A2 with openEuler
+docker compose --profile openeuler up -d llamafactory-a2-openeuler
+
+# A3 with openEuler
+docker compose --profile a3-openeuler up -d llamafactory-a3-openeuler
+```
+
+### Extend or Develop from the Image
+
+For interactive development, mount a local checkout and reinstall it in editable mode inside the container:
+
+```bash
+git clone https://github.com/hiyouga/LLaMA-Factory.git
+cd LLaMA-Factory
+
+# Add the same Ascend --device and driver mount options shown above.
+docker run --rm -it \
+  --ipc=host \
+  -v "$PWD:/workspace/LLaMA-Factory" \
+  -w /workspace/LLaMA-Factory \
+  "$IMAGE" \
+  bash
+
+pip install -e . --no-build-isolation
+```
+
+For a reproducible derived image, create a separate Dockerfile:
+
+```dockerfile
+FROM quay.io/ascend/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A2-ubuntu-py3.11
+
+COPY requirements-extension.txt /tmp/requirements-extension.txt
+RUN pip install --no-cache-dir -r /tmp/requirements-extension.txt
+
+COPY . /workspace/application
+WORKDIR /workspace/application
+```
+
+Pass Ascend devices and driver mounts when running the derived image; device access should not be embedded in the image itself.
+
+## Hardware Support and Compatibility Notes
+
+- A2 images use the `910b` CANN base image; A3 images use the `a3` CANN base image.
+- The image build targets both x86-64 (`linux/amd64`) and AArch64 (`linux/arm64`) hosts. This CPU architecture is independent of whether the accelerator is A2 or A3.
+- Ubuntu 22.04 and openEuler 24.03 refer to the operating system inside the container.
+- The current dependency baseline aligns PyTorch `2.7.1` with torch-npu `2.7.1.post4`. Upgrading either package independently may break compatibility.
+- Use a fixed release tag for reproducible production deployments. The `latest` tag can change after scheduled builds.
+- Legacy short tags such as `latest-npu-a2` do not encode the CANN, torch-npu, operating system, or Python versions. Prefer the full tag format documented above.
+- Validate the exact driver, firmware, CANN, and SoC combination before production deployment.
+
+## License and Disclaimer
+
+LLaMA Factory is distributed under the [Apache License 2.0](../../LICENSE).
+
+Ascend CANN, torch-npu, Triton Ascend, DeepSpeed, base operating-system packages, model weights, datasets, and other third-party components are governed by their respective licenses and terms. The LLaMA Factory license does not replace or override those terms.
+
+The image is provided on an "AS IS" basis, without warranties or conditions of any kind. Users are responsible for validating hardware and software compatibility, securing the container and its runtime configuration, complying with applicable licenses and laws, and reviewing model and dataset terms before training, evaluation, or deployment.
diff --git a/docker/docker-npu/OVERVIEW.zh.md b/docker/docker-npu/OVERVIEW.zh.md
new file mode 100644
index 000000000..d9bcee005
--- /dev/null
+++ b/docker/docker-npu/OVERVIEW.zh.md
@@ -0,0 +1,232 @@
+# 面向昇腾 NPU 的 LLaMA Factory 镜像
+
+LLaMA Factory 昇腾 NPU 镜像面向华为昇腾 Atlas NPU，提供可直接用于大语言模型和多模态模型微调、评测与服务部署的运行环境。镜像基于昇腾 CANN 容器镜像构建，预装 LLaMA Factory、Python、PyTorch、torch-npu、Triton Ascend、DeepSpeed 和 LLaMA Factory 评测依赖。
+
+安装方法和问题排查请参考 [LLaMA Factory NPU 安装及配置文档](https://llamafactory.readthedocs.io/zh-cn/latest/multibackend/npu/npu_installation.html)。
+
+## 快速参考
+
+- 镜像仓库：
+  - `docker.io/hiyouga/llamafactory`
+  - `quay.io/ascend/llamafactory`
+- Dockerfile：`docker/docker-npu/Dockerfile`
+- Docker Compose 文件：`docker/docker-npu/docker-compose.yml`
+- 默认基础镜像：`quay.io/ascend/cann:9.0.0-910b-ubuntu22.04-py3.11`
+- 支持的加速器：昇腾 A2、A3
+- 支持的容器操作系统：Ubuntu 22.04、openEuler 24.03
+- 目标 CPU 架构：`linux/amd64`、`linux/arm64`
+- 对外端口：
+  - `7860`：LLaMA Board Web UI
+  - `8000`：API 服务
+- 昇腾环境脚本：`/usr/local/Ascend/ascend-toolkit/set_env.sh`
+
+当前提供以下镜像组合：
+
+| 加速器 | 容器操作系统 | CANN 基础镜像 |
+| --- | --- | --- |
+| A2 | Ubuntu 22.04 | `quay.io/ascend/cann:9.0.0-910b-ubuntu22.04-py3.11` |
+| A3 | Ubuntu 22.04 | `quay.io/ascend/cann:9.0.0-a3-ubuntu22.04-py3.11` |
+| A2 | openEuler 24.03 | `quay.io/ascend/cann:9.0.0-910b-openeuler24.03-py3.11` |
+| A3 | openEuler 24.03 | `quay.io/ascend/cann:9.0.0-a3-openeuler24.03-py3.11` |
+
+## 镜像介绍
+
+该镜像用于运行 LLaMA Factory 支持的昇腾 NPU 训练、微调、评测、Web UI 和 API 服务，主要包含以下组件：
+
+| 组件 | 版本或来源 |
+| --- | --- |
+| CANN | 继承自所选 CANN 9.0.0 基础镜像 |
+| Python | Python 3.11，继承自基础镜像 |
+| PyTorch | `2.7.1` |
+| torch-npu | `2.7.1.post4` |
+| torchvision | `0.22.1` |
+| torchaudio | `2.7.1` |
+| Triton Ascend | `3.2.1` |
+| DeepSpeed | `>=0.10.0,<=0.18.4` |
+| LLaMA Factory | 从构建上下文中的仓库源码安装 |
+
+镜像不包含模型权重和数据集。请通过目录挂载或运行时下载的方式单独提供，并遵守对应的许可证和使用要求。
+
+## 镜像 Tag 说明与 Dockerfile 归档路径
+
+镜像使用以下 tag 格式：
+
+```text
+<llamafactory版本>-cann<CANN版本>-torch_npu<torch-npu版本>-<加速器>-<操作系统>-<Python版本>
+```
+
+| 字段 | 示例 | 说明 |
+| --- | --- | --- |
+| `llamafactory版本` | `latest` 或 `0.9.6` | 非 release 构建使用 `latest`，release 构建使用 LLaMA Factory 版本号 |
+| `CANN版本` | `9.0.0` | 从 CANN 基础镜像 tag 中提取 |
+| `torch-npu版本` | `2.7.1` | 从 `requirements/npu.txt` 中提取，镜像 tag 不包含 `.post4` 等后缀 |
+| `加速器` | `A2` 或 `A3` | 当前镜像所适配的昇腾硬件代际 |
+| `操作系统` | `ubuntu` 或 `openeuler` | 容器内操作系统类型 |
+| `Python版本` | `py3.11` | 从 CANN 基础镜像 tag 中提取 |
+
+示例：
+
+```text
+latest-cann9.0.0-torch_npu2.7.1-A2-ubuntu-py3.11
+latest-cann9.0.0-torch_npu2.7.1-A3-openeuler-py3.11
+0.9.6-cann9.0.0-torch_npu2.7.1-A3-ubuntu-py3.11
+```
+
+CPU 架构不写入 tag。发布镜像配置为多架构镜像，Docker 拉取时会根据宿主机自动选择 `linux/amd64` 或 `linux/arm64` 版本。
+
+Dockerfile 和用于镜像分发的概述文件在同一目录归档：
+
+```text
+docker/docker-npu/
+├── Dockerfile
+├── OVERVIEW.md
+├── OVERVIEW.zh.md
+└── docker-compose.yml
+```
+
+## 快速开始
+
+### 前置条件
+
+启动容器前需要：
+
+1. 在宿主机安装与镜像内 CANN 版本兼容的昇腾驱动和固件。
+2. 确认宿主机执行 `npu-smi info` 可以正常识别 NPU。
+3. 安装 Docker，并确保当前用户有权访问所需的昇腾设备节点和驱动文件。
+
+驱动、固件、CANN、torch-npu 与目标昇腾硬件需要保持兼容。
+
+### 拉取并运行镜像
+
+以下示例使用一张 NPU 启动最新的 A2 Ubuntu 镜像。请根据实际环境修改镜像 tag 和 `/dev/davinci0`。
+
+```bash
+export IMAGE=quay.io/ascend/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A2-ubuntu-py3.11
+
+docker pull "$IMAGE"
+
+docker run --rm -it \
+  --name llamafactory-npu \
+  --ipc=host \
+  --device=/dev/davinci0 \
+  --device=/dev/davinci_manager \
+  --device=/dev/devmm_svm \
+  --device=/dev/hisi_hdc \
+  -v /usr/local/dcmi:/usr/local/dcmi \
+  -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
+  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
+  -v /etc/ascend_install.info:/etc/ascend_install.info \
+  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
+  -p 7860:7860 \
+  -p 8000:8000 \
+  "$IMAGE" \
+  bash
+```
+
+部分驱动环境中的 `npu-smi` 位于 `/usr/local/sbin/npu-smi`，此时需要调整挂载源路径。使用多张 NPU 时，继续追加 `--device=/dev/davinci<N>` 参数。
+
+进入容器后验证运行环境：
+
+```bash
+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
+```
+
+需要使用 LLaMA Board 时执行：
+
+```bash
+llamafactory-cli webui
+```
+
+### 本地构建
+
+在仓库根目录执行构建。以下示例构建 A3 openEuler 镜像：
+
+```bash
+docker build \
+  -f ./docker/docker-npu/Dockerfile \
+  --build-arg BASE_IMAGE=quay.io/ascend/cann:9.0.0-a3-openeuler24.03-py3.11 \
+  --build-arg PIP_INDEX=https://pypi.org/simple \
+  -t llamafactory:npu-a3-openeuler \
+  .
+```
+
+可用构建参数：
+
+| 参数 | 默认值 | 用途 |
+| --- | --- | --- |
+| `BASE_IMAGE` | A2 Ubuntu CANN 9.0.0 镜像 | 选择加速器和容器操作系统组合 |
+| `PIP_INDEX` | `https://pypi.org/simple` | 指定 Python 软件包索引 |
+| `PYTORCH_INDEX` | `https://download.pytorch.org/whl/cpu` | 指定配合 torch-npu 使用的 PyTorch wheel 索引 |
+| `HTTP_PROXY` | 空 | 构建期间可选的 HTTP/HTTPS 代理 |
+
+也可以通过 Docker Compose 构建并启动各个组合：
+
+```bash
+cd docker/docker-npu
+
+# A2 + Ubuntu
+docker compose up -d llamafactory-a2-ubuntu
+
+# A3 + Ubuntu
+docker compose --profile a3 up -d llamafactory-a3-ubuntu
+
+# A2 + openEuler
+docker compose --profile openeuler up -d llamafactory-a2-openeuler
+
+# A3 + openEuler
+docker compose --profile a3-openeuler up -d llamafactory-a3-openeuler
+```
+
+### 二次开发
+
+交互式开发时，可以将本地源码挂载到容器中，并在容器内以 editable 模式重新安装：
+
+```bash
+git clone https://github.com/hiyouga/LLaMA-Factory.git
+cd LLaMA-Factory
+
+# 同时添加前述昇腾 --device 和驱动目录挂载参数。
+docker run --rm -it \
+  --ipc=host \
+  -v "$PWD:/workspace/LLaMA-Factory" \
+  -w /workspace/LLaMA-Factory \
+  "$IMAGE" \
+  bash
+
+pip install -e . --no-build-isolation
+```
+
+需要可复现的派生镜像时，可以新建独立 Dockerfile：
+
+```dockerfile
+FROM quay.io/ascend/llamafactory:latest-cann9.0.0-torch_npu2.7.1-A2-ubuntu-py3.11
+
+COPY requirements-extension.txt /tmp/requirements-extension.txt
+RUN pip install --no-cache-dir -r /tmp/requirements-extension.txt
+
+COPY . /workspace/application
+WORKDIR /workspace/application
+```
+
+运行派生镜像时仍需传入昇腾设备和驱动挂载参数，不应将设备访问配置固化到镜像中。
+
+## 硬件支持与兼容性说明
+
+- A2 镜像使用标记为 `910b` 的 CANN 基础镜像，A3 镜像使用标记为 `a3` 的 CANN 基础镜像。
+- 镜像构建目标同时包含 x86-64（`linux/amd64`）和 AArch64（`linux/arm64`）宿主机。CPU 架构与加速器属于 A2 还是 A3 无关。
+- Ubuntu 22.04 和 openEuler 24.03 指容器内部的操作系统。
+- 当前依赖基线将 PyTorch `2.7.1` 与 torch-npu `2.7.1.post4` 配套使用。单独升级其中一个软件包可能破坏兼容性。
+- 生产环境建议使用固定 release tag，以确保部署可复现；定时构建可能更新 `latest` tag。
+- `latest-npu-a2` 等旧式短 tag 没有体现 CANN、torch-npu、操作系统和 Python 版本，建议迁移到本文所述的完整 tag。
+- 正式部署前，请验证具体驱动、固件、CANN 和 SoC 组合的兼容性。
+
+## 许可证与免责声明
+
+LLaMA Factory 基于 [Apache License 2.0](../../LICENSE) 发布。
+
+昇腾 CANN、torch-npu、Triton Ascend、DeepSpeed、基础操作系统软件包、模型权重、数据集和其他第三方组件分别受其自身许可证与条款约束。LLaMA Factory 的许可证不会替代或覆盖这些条款。
+
+本镜像按“原样”提供，不附带任何明示或暗示的保证。用户需要自行验证软硬件兼容性、保障容器及运行配置的安全、遵守适用的许可证和法律，并在训练、评测或部署前审查模型与数据集的使用条款。
diff --git a/docker/docker-npu/docker-compose.yml b/docker/docker-npu/docker-compose.yml
index 75ee904a4..c5782b157 100644
--- a/docker/docker-npu/docker-compose.yml
+++ b/docker/docker-npu/docker-compose.yml
@@ -1,58 +1,80 @@
+x-build-args: &build-args
+  PIP_INDEX: https://pypi.org/simple
+
+x-build: &build
+  dockerfile: ./docker/docker-npu/Dockerfile
+  context: ../..
+
+x-npu-common: &npu-common
+  volumes:
+    - /usr/local/dcmi:/usr/local/dcmi
+    - /usr/local/bin/npu-smi:/usr/local/bin/npu-smi
+    - /usr/local/Ascend/driver:/usr/local/Ascend/driver
+    - /etc/ascend_install.info:/etc/ascend_install.info
+  ipc: host
+  tty: true
+  # shm_size: "16gb"  # ipc: host is set
+  stdin_open: true
+  command: bash
+  devices:
+    - /dev/davinci0
+    - /dev/davinci_manager
+    - /dev/devmm_svm
+    - /dev/hisi_hdc
+  restart: unless-stopped
+
 services:
-  llamafactory-a2:
+  llamafactory-a2-ubuntu:
+    <<: *npu-common
     build:
-      dockerfile: ./docker/docker-npu/Dockerfile
-      context: ../..
+      <<: *build
       args:
-        PIP_INDEX: https://pypi.org/simple
-    container_name: llamafactory-a2
-    image: llamafactory:npu-a2
-    volumes:
-      - /usr/local/dcmi:/usr/local/dcmi
-      - /usr/local/bin/npu-smi:/usr/local/bin/npu-smi
-      - /usr/local/Ascend/driver:/usr/local/Ascend/driver
-      - /etc/ascend_install.info:/etc/ascend_install.info
+        <<: *build-args
+        BASE_IMAGE: quay.io/ascend/cann:9.0.0-910b-ubuntu22.04-py3.11
+    container_name: llamafactory-a2-ubuntu
+    image: llamafactory:npu-a2-ubuntu
     ports:
       - "7860:7860"
       - "8000:8000"
-    ipc: host
-    tty: true
-    # shm_size: "16gb"  # ipc: host is set
-    stdin_open: true
-    command: bash
-    devices:
-      - /dev/davinci0
-      - /dev/davinci_manager
-      - /dev/devmm_svm
-      - /dev/hisi_hdc
-    restart: unless-stopped
 
-  llamafactory-a3:
+  llamafactory-a3-ubuntu:
+    <<: *npu-common
     profiles: ["a3"]
     build:
-      dockerfile: ./docker/docker-npu/Dockerfile
-      context: ../..
+      <<: *build
       args:
+        <<: *build-args
         BASE_IMAGE: quay.io/ascend/cann:9.0.0-a3-ubuntu22.04-py3.11
-        PIP_INDEX: https://pypi.org/simple
-    container_name: llamafactory-a3
-    image: llamafactory:npu-a3
-    volumes:
-      - /usr/local/dcmi:/usr/local/dcmi
-      - /usr/local/bin/npu-smi:/usr/local/bin/npu-smi
-      - /usr/local/Ascend/driver:/usr/local/Ascend/driver
-      - /etc/ascend_install.info:/etc/ascend_install.info
+    container_name: llamafactory-a3-ubuntu
+    image: llamafactory:npu-a3-ubuntu
     ports:
       - "7861:7860"
       - "8001:8000"
-    ipc: host
-    tty: true
-    # shm_size: "16gb"  # ipc: host is set
-    stdin_open: true
-    command: bash
-    devices:
-      - /dev/davinci0
-      - /dev/davinci_manager
-      - /dev/devmm_svm
-      - /dev/hisi_hdc
-    restart: unless-stopped
+
+  llamafactory-a2-openeuler:
+    <<: *npu-common
+    profiles: ["openeuler"]
+    build:
+      <<: *build
+      args:
+        <<: *build-args
+        BASE_IMAGE: quay.io/ascend/cann:9.0.0-910b-openeuler24.03-py3.11
+    container_name: llamafactory-a2-openeuler
+    image: llamafactory:npu-a2-openeuler
+    ports:
+      - "7862:7860"
+      - "8002:8000"
+
+  llamafactory-a3-openeuler:
+    <<: *npu-common
+    profiles: ["a3-openeuler"]
+    build:
+      <<: *build
+      args:
+        <<: *build-args
+        BASE_IMAGE: quay.io/ascend/cann:9.0.0-a3-openeuler24.03-py3.11
+    container_name: llamafactory-a3-openeuler
+    image: llamafactory:npu-a3-openeuler
+    ports:
+      - "7863:7860"
+      - "8003:8000"