Skip to content

doc : remove incompatible decord dependency and update ascend doc #471

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
UsernameFull wants to merge 1 commit into
base: main
Choose a base branch
from
Open

doc : remove incompatible decord dependency and update ascend doc #471

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docker/Dockerfile.A2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,9 @@ RUN source /usr/local/Ascend/ascend-toolkit/set_env.sh && \
WORKDIR /workspace/ROLL
COPY . .

RUN pip install -r requirements_common.txt
# remove decord from requirements_vision.txt because it is not compatible with Ascend
RUN sed '/requirements_vision\.txt/d' requirements_common.txt > /tmp/req.txt && sed '/^decord\b/d' requirements_vision.txt >> /tmp/req.txt && pip install -r /tmp/req.txt
ENV FORCE_QWENVL_VIDEO_READER=torchvision

@HuangJoJo HuangJoJo Jul 6, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

torchvision occurs seg fault or CPU mem leaks occasionally， Does Ascend support torchcodec reader？


RUN pip install "transformers==4.57.6" "tensorboard==2.20.0"

Expand Down
4 changes: 3 additions & 1 deletion docker/Dockerfile.A3
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,9 @@ RUN source /usr/local/Ascend/ascend-toolkit/set_env.sh && \
WORKDIR /workspace/ROLL
COPY . .

RUN pip install -r requirements_common.txt
# remove decord from requirements_vision.txt because it is not compatible with Ascend
RUN sed '/requirements_vision\.txt/d' requirements_common.txt > /tmp/req.txt && sed '/^decord\b/d' requirements_vision.txt >> /tmp/req.txt && pip install -r /tmp/req.txt
ENV FORCE_QWENVL_VIDEO_READER=torchvision

RUN pip install "transformers==4.57.6" "tensorboard==2.20.0"

Expand Down
19 changes: 15 additions & 4 deletions docs_roll/docs/User Guides/Hardware Support/ascend_docker_usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Last updated: 06/23/2026.

This guide explains how to get, build, and run ROLL images on **Huawei Ascend NPU**. Prefer the pre-built image when possible; use `Dockerfile.A2` or `Dockerfile.A3` when you need to customize dependencies. Atlas 950 currently follows the manual installation profile in [ROLL x Ascend](ascend_usage.md).
This guide explains how to get, build, and run ROLL images on **Huawei Ascend NPU**. Prefer the pre-built image when possible; use `Dockerfile.A2` or `Dockerfile.A3` when you need to customize dependencies. Ascend 950 currently follows the manual installation profile in [ROLL x Ascend](ascend_usage.md).

## Hardware & Software Requirements

Expand All @@ -15,7 +15,7 @@ This guide explains how to get, build, and run ROLL images on **Huawei Ascend NP
| Docker | >= 20.10 | >= 20.10 |
| Ascend NPU Driver | Installed on host | Installed on host |

This Docker guide covers the A2/A3 Dockerfiles. For Atlas 950, use the manual installation profile: torch 2.10, vLLM v0.20.2, vLLM-Ascend `main`, and `COMPILE_CUSTOM_KERNELS=1` when building vLLM-Ascend.
This Docker guide covers the A2/A3 Dockerfiles. For Ascend 950, use the manual installation profile: torch 2.10, vLLM v0.20.2, vLLM-Ascend `main`, and `COMPILE_CUSTOM_KERNELS=1` when building vLLM-Ascend.

## Key Components

Expand All @@ -29,9 +29,9 @@ Both Dockerfiles install the same versions of core dependencies:
| Transformers | 4.57.6 |
| triton-ascend | 3.2.1 |

Atlas 950 uses a newer manual installation stack:
Ascend 950 uses a newer manual installation stack:

| Component | Atlas 950 Version / Setting |
| Component | Ascend 950 Version / Setting |
| --------- | -------------------------- |
| PyTorch | 2.10 |
| vLLM | v0.20.2 |
Expand Down Expand Up @@ -113,6 +113,7 @@ docker build -f docker/Dockerfile.A3 --build-arg SOC_VERSION=ascend910_9391 -t r
```bash
docker run -dit \
--name roll_a2 \
--ulimit nofile=65536:65536 \
--device /dev/davinci0 \
--device /dev/davinci1 \
--device /dev/davinci2 \
Expand Down Expand Up @@ -141,6 +142,7 @@ docker run -dit \
```bash
docker run -dit \
--name roll_a3 \
--ulimit nofile=65536:65536 \
--device /dev/davinci0 \
--device /dev/davinci1 \
--device /dev/davinci2 \
Expand All @@ -149,6 +151,14 @@ docker run -dit \
--device /dev/davinci5 \
--device /dev/davinci6 \
--device /dev/davinci7 \
--device /dev/davinci8 \
--device /dev/davinci9 \
--device /dev/davinci10 \
--device /dev/davinci11 \
--device /dev/davinci12 \
--device /dev/davinci13 \
--device /dev/davinci14 \
--device /dev/davinci15 \
--device /dev/davinci_manager \
--device /dev/devmm_svm \
--device /dev/hisi_hdc \
Expand All @@ -171,6 +181,7 @@ For multi-NPU training, mount all available NPU devices. Adjust the number of `-
```bash
docker run -dit \
--name roll_ascend \
--ulimit nofile=65536:65536 \
--device /dev/davinci0 \
--device /dev/davinci1 \
--device /dev/davinci2 \
Expand Down
4 changes: 2 additions & 2 deletions docs_roll/docs/User Guides/Hardware Support/ascend_npu_env_config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,9 +175,9 @@ The following variable is used when building vLLM-Ascend from source. Set it bef

| Variable | Recommended Value | Description |
| -------- | ----------------- | ----------- |
| `COMPILE_CUSTOM_KERNELS` | `1` for Atlas A5 | Compile vLLM-Ascend custom kernels. Required by the Atlas A5 installation profile that uses vLLM-Ascend `main`. |
| `COMPILE_CUSTOM_KERNELS` | `1` for Ascend 950 | Compile vLLM-Ascend custom kernels. Required by the Ascend 950 installation profile that uses vLLM-Ascend `main`. |

Example (Atlas A5):
Example (Ascend 950):

```bash
git clone -b main --depth 1 https://github.com/vllm-project/vllm-ascend.git
Expand Down
14 changes: 7 additions & 7 deletions docs_roll/docs/User Guides/Hardware Support/ascend_usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,19 @@ ROLL's Ascend support is currently validated on training-series Ascend hardware:
| ------- | -------------- | ----- |
| Atlas 900 A2 PODc (Ascend 910B1) / Atlas A2 training series | √ | Use `docker/Dockerfile.A2` or the `roll:ascend-a2` image. |
| Atlas 900 A3 PODc (Ascend 910_9391) / Atlas A3 training series | √ | Use `docker/Dockerfile.A3` or the `roll:ascend-a3` image. |
| Atlas A5 training series | √ | Use the A5 installation profile: torch 2.10, vLLM v0.20.2, vLLM-Ascend `main`, and `COMPILE_CUSTOM_KERNELS=1` when building vLLM-Ascend. |
| Ascend 950 training series | √ | Use the Ascend 950 installation profile: torch 2.10, vLLM v0.20.2, vLLM-Ascend `main`, and `COMPILE_CUSTOM_KERNELS=1` when building vLLM-Ascend. |
| Atlas A2/A3 inference series and Atlas 200I/500 A2 inference products | x | Current ROLL NPU images and examples target training-series devices. |
| Other Ascend training or inference products | Not validated | Validate the driver, firmware, CANN, `torch_npu`, and vLLM-Ascend versions before use. |

> In this table, `√` means supported by the current ROLL Ascend Dockerfiles/examples or the manual A5 installation profile, and `x` means not supported in the current ROLL NPU setup.
> In this table, `√` means supported by the current ROLL Ascend Dockerfiles/examples or the manual Ascend 950 installation profile, and `x` means not supported in the current ROLL NPU setup.

Supported operating systems:

| Deployment scenario | Supported OS | Notes |
| ------------------- | ------------ | ----- |
| Physical host | Ubuntu 22.04 | Recommended and validated by the current ROLL Ascend guides. |
| ROLL Ascend container | Ubuntu 22.04 | The A2/A3 Dockerfiles are based on `quay.io/ascend/cann:9.0.0-*-ubuntu22.04-py3.11`. |
| Atlas A5 manual installation | Ubuntu 22.04 | Use the A5-specific torch/vLLM stack below. Keep the driver, firmware, CANN, and `torch_npu` versions aligned with the target A5 environment. |
| Ascend 950 manual installation | Ubuntu 22.04 | Use the Ascend 950-specific torch/vLLM stack below. Keep the driver, firmware, CANN, and `torch_npu` versions aligned with the target Ascend 950 environment. |
| VM/container deployments on other host OS versions | Follow Ascend/CANN compatibility guidance | Check the Ascend compatibility query assistant and the CANN Software Installation OS compatibility notes for the target hardware. |

## Installation
Expand All @@ -36,7 +36,7 @@ Supported operating systems:
| Python | 3.11 |
| CANN | 9.0.0 |

For Atlas A5, keep Python 3.11 and use the A5-specific torch/vLLM stack described in [A5 Installation Profile](#a5-installation-profile).
For Ascend 950 , keep Python 3.11 and use the Ascend 950-specific torch/vLLM stack described in [Ascend 950 Installation Profile](#Ascend 950-installation-profile).

### Create Conda Environment

Expand Down Expand Up @@ -89,9 +89,9 @@ pip install vllm==0.18.0
pip install vllm-ascend==0.18
```

### A5 Installation Profile
### Ascend 950 Installation Profile

For Atlas A5, use torch 2.10, vLLM v0.20.2, and vLLM-Ascend from the `main` branch. Set `COMPILE_CUSTOM_KERNELS=1` before installing vLLM-Ascend so its custom kernels are built:
For Ascend 950, use torch 2.10, vLLM v0.20.2, and vLLM-Ascend from the `main` branch. Set `COMPILE_CUSTOM_KERNELS=1` before installing vLLM-Ascend so its custom kernels are built:

```
# Install torch 2.10
Expand Down Expand Up @@ -172,7 +172,7 @@ python examples/start_agentic_pipeline.py \
| --------------- | ------------------------------------------------------------ | ---------------- | ----------------- | ----------------- |
| Agentic | examples/qwen2.5-0.5B-agentic/run_agentic_pipeline_sokoban.sh | FSDP2 | vLLM | Atlas 900 A2/A3 PODc |
| Agentic-Rollout | examples/qwen2.5-0.5B-agentic/run_agentic_rollout_sokoban.sh | FSDP2 | vLLM | Atlas 900 A2/A3 PODc |
| RLVR | examples/ascend_examples/run_rlvr_pipeline.sh | FSDP2 | vLLM | Atlas 900 A2/A3/A5 training series |
| RLVR | examples/ascend_examples/run_rlvr_pipeline.sh | FSDP2 | vLLM | Atlas 900 A2/A3/Ascend 950 training series |

## Disclaimer

Expand Down
17 changes: 14 additions & 3 deletions ...plugin-content-docs/current/User Guides/Hardware Support/ascend_docker_usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
| Docker | >= 20.10 | >= 20.10 |
| 昇腾 NPU 驱动 | 已安装在宿主机上 | 已安装在宿主机上 |

本 Docker 指南覆盖 A2/A3 Dockerfile。Atlas 950 请使用手动安装配置：torch 2.10、vLLM v0.20.2、vLLM-Ascend `main`，并在构建 vLLM-Ascend 时设置 `COMPILE_CUSTOM_KERNELS=1`。
本 Docker 指南覆盖 A2/A3 Dockerfile。Ascend 950 请使用手动安装配置：torch 2.10、vLLM v0.20.2、vLLM-Ascend `main`，并在构建 vLLM-Ascend 时设置 `COMPILE_CUSTOM_KERNELS=1`。

## 主要组件

Expand All @@ -29,9 +29,9 @@
| Transformers | 4.57.6 |
| triton-ascend | 3.2.1 |

Atlas 950 使用更新的手动安装版本组合：
Ascend 950 使用更新的手动安装版本组合：

| 组件 | Atlas 950 版本 / 设置 |
| 组件 | Ascend 950 版本 / 设置 |
| ---- | -------------------- |
| PyTorch | 2.10 |
| vLLM | v0.20.2 |
Expand Down Expand Up @@ -113,6 +113,7 @@ docker build -f docker/Dockerfile.A3 --build-arg SOC_VERSION=ascend910_9391 -t r
```bash
docker run -dit \
--name roll_a2 \
--ulimit nofile=65536:65536 \
--device /dev/davinci0 \
--device /dev/davinci1 \
--device /dev/davinci2 \
Expand Down Expand Up @@ -141,6 +142,7 @@ docker run -dit \
```bash
docker run -dit \
--name roll_a3 \
--ulimit nofile=65536:65536 \
--device /dev/davinci0 \
--device /dev/davinci1 \
--device /dev/davinci2 \
Expand All @@ -149,6 +151,14 @@ docker run -dit \
--device /dev/davinci5 \
--device /dev/davinci6 \
--device /dev/davinci7 \
--device /dev/davinci8 \
--device /dev/davinci9 \
--device /dev/davinci10 \
--device /dev/davinci11 \
--device /dev/davinci12 \
--device /dev/davinci13 \
--device /dev/davinci14 \
--device /dev/davinci15 \
--device /dev/davinci_manager \
--device /dev/devmm_svm \
--device /dev/hisi_hdc \
Expand All @@ -171,6 +181,7 @@ docker run -dit \
```bash
docker run -dit \
--name roll_ascend \
--ulimit nofile=65536:65536 \
--device /dev/davinci0 \
--device /dev/davinci1 \
--device /dev/davinci2 \
Expand Down
4 changes: 2 additions & 2 deletions ...ugin-content-docs/current/User Guides/Hardware Support/ascend_npu_env_config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,9 +175,9 @@ export VLLM_ASCEND_ENABLE_PREFETCH_MLP=1

| 变量 | 推荐值 | 说明 |
| ---- | ------ | ---- |
| `COMPILE_CUSTOM_KERNELS` | Atlas A5 设置为 `1` | 编译 vLLM-Ascend 自定义 kernel。使用 vLLM-Ascend `main` 的 Atlas A5 安装配置需要设置该变量。 |
| `COMPILE_CUSTOM_KERNELS` | Ascend 950 设置为 `1` | 编译 vLLM-Ascend 自定义 kernel。使用 vLLM-Ascend `main` 的 Ascend 950 安装配置需要设置该变量。 |

示例（Atlas A5）：
示例（Ascend 950）：

```bash
git clone -b main --depth 1 https://github.com/vllm-project/vllm-ascend.git
Expand Down
18 changes: 9 additions & 9 deletions ...saurus-plugin-content-docs/current/User Guides/Hardware Support/ascend_usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,19 @@ ROLL 昇腾适配当前覆盖以下训练系列硬件：
| ---- | -------- | ---- |
| Atlas 900 A2 PODc（Ascend 910B1）/ Atlas A2 训练系列产品 | √ | 使用 `docker/Dockerfile.A2` 或 `roll:ascend-a2` 镜像。 |
| Atlas 900 A3 PODc（Ascend 910_9391）/ Atlas A3 训练系列产品 | √ | 使用 `docker/Dockerfile.A3` 或 `roll:ascend-a3` 镜像。 |
| Atlas A5 训练系列产品 | √ | 使用 A5 安装配置：torch 2.10、vLLM v0.20.2、vLLM-Ascend `main`，并在构建 vLLM-Ascend 时设置 `COMPILE_CUSTOM_KERNELS=1`。 |
| Ascend 950 训练系列产品 | √ | 使用 Ascend 950 安装配置：torch 2.10、vLLM v0.20.2、vLLM-Ascend `main`，并在构建 vLLM-Ascend 时设置 `COMPILE_CUSTOM_KERNELS=1`。 |
| Atlas A2/A3 推理系列产品、Atlas 200I/500 A2 推理产品 | x | 当前 ROLL NPU 镜像和示例面向训练系列设备。 |
| 其他昇腾训练或推理产品 | 未验证 | 使用前请确认驱动、固件、CANN、`torch_npu` 与 vLLM-Ascend 版本配套。 |

> 本节表格中 `√` 代表当前 ROLL 昇腾 Dockerfile、示例或 A5 手动安装配置已支持，`x` 代表当前 ROLL NPU 配套不支持。
> 本节表格中 `√` 代表当前 ROLL 昇腾 Dockerfile、示例或 Ascend 950 手动安装配置已支持，`x` 代表当前 ROLL NPU 配套不支持。

支持的操作系统：

| 部署场景 | 支持的操作系统 | 说明 |
| -------- | -------------- | ---- |
| 物理机宿主机 | Ubuntu 22.04 | 当前 ROLL 昇腾文档推荐并验证的宿主机操作系统。 |
| ROLL 昇腾容器 | Ubuntu 22.04 | A2/A3 Dockerfile 基于 `quay.io/ascend/cann:9.0.0-*-ubuntu22.04-py3.11`。 |
| Atlas A5 手动安装 | Ubuntu 22.04 | 使用下文 A5 专用 torch/vLLM 版本组合。驱动、固件、CANN 和 `torch_npu` 版本需要与目标 A5 环境匹配。 |
| Ascend 950 手动安装 | Ubuntu 22.04 | 使用下文 Ascend 950 专用 torch/vLLM 版本组合。驱动、固件、CANN 和 `torch_npu` 版本需要与目标 Ascend 950 环境匹配。 |
| 其他宿主机 OS 上的虚拟机或容器部署 | 以昇腾/CANN 兼容性说明为准 | 请结合目标硬件查询昇腾兼容性查询助手，以及 CANN 软件安装文档中的操作系统兼容性说明。 |

## 安装
Expand All @@ -36,7 +36,7 @@ ROLL 昇腾适配当前覆盖以下训练系列硬件：
| Python | 3.11 |
| CANN | 9.0.0 |

Atlas A5 请保持 Python 3.11，并使用下文 [A5 安装配置](#a5-安装配置) 中的专用 torch/vLLM 版本组合。
Ascend 950 请保持 Python 3.11，并使用下文 [Ascend 950 安装配置](#Ascend 950-安装配置) 中的专用 torch/vLLM 版本组合。

### 创建 conda 环境

Expand Down Expand Up @@ -90,9 +90,9 @@ pip install vllm==0.18.0
pip install vllm-ascend==0.18
```

### A5 安装配置
### Ascend 950 安装配置

Atlas A5 上使用 torch 2.10、vLLM v0.20.2，并从 `main` 分支安装 vLLM-Ascend。安装 vLLM-Ascend 前需要设置 `COMPILE_CUSTOM_KERNELS=1`，以便编译自定义 kernel：
Ascend 950上使用 torch 2.10、vLLM v0.20.2，并从 `main` 分支安装 vLLM-Ascend。安装 vLLM-Ascend 前需要设置 `COMPILE_CUSTOM_KERNELS=1`，以便编译自定义 kernel：

```
# 安装 torch 2.10
Expand Down Expand Up @@ -171,9 +171,9 @@ python examples/start_agentic_pipeline.py \

| 功能 | 示例 | 训练后端 | 推理后端 | 硬件 |
| ---- | ---- | -------- | -------- | ---- |
| Agentic | examples/qwen2.5-0.5B-agentic/run_agentic_pipeline_sokoban.sh | FSDP2 | vLLM | Atlas 900 A2/A3 PODc |
| Agentic-Rollout | examples/qwen2.5-0.5B-agentic/run_agentic_rollout_sokoban.sh | FSDP2 | vLLM | Atlas 900 A2/A3 PODc |
| RLVR | examples/ascend_examples/run_rlvr_pipeline.sh | FSDP2 | vLLM | Atlas 900 A2/A3/A5 训练系列 |
| Agentic | examples/qwen2.5-0.5B-agentic/run_agentic_pipeline_sokoban.sh | FSDP2 | vLLM | Atlas 900 A2/A3/Ascend 950 训练系列 |
| Agentic-Rollout | examples/qwen2.5-0.5B-agentic/run_agentic_rollout_sokoban.sh | FSDP2 | vLLM | Atlas 900 A2/A3/Ascend 950 训练系列 |
| RLVR | examples/ascend_examples/run_rlvr_pipeline.sh | FSDP2 | vLLM | Atlas 900 A2/A3/Ascend 950 训练系列 |

## 声明

Expand Down
Loading