docs: update Ascend NPU documentation

Author: UsernameFull

.github/workflows/ci-npu-test.yml

@@ -198,7 +198,7 @@ jobs:
       - name: Install ROLL requirements
         run: |
           python3 -m pip install -r requirements_common.txt
-          python3 -m pip install deepspeed==0.16.4 tensorboard
+          python3 -m pip install tensorboard
 
       - name: Install SGLang NPU kernel from source
         shell: bash
@@ -289,7 +289,7 @@ jobs:
               except metadata.PackageNotFoundError:
                   return "not installed"
 
-          packages = ("vllm-ascend", "transformers", "deepspeed", "triton-ascend")
+          packages = ("vllm-ascend", "transformers", "triton-ascend")
           for package_name in packages:
               print(f"{package_name}={package_version(package_name)}")
 
@@ -302,7 +302,6 @@ jobs:
           export PYTHONPATH="${GITHUB_WORKSPACE}:${PYTHONPATH:-}"
           python3 -m pytest tests/third_party/sglang \
                             tests/third_party/vllm \
-                            tests/third_party/deepspeed \
                             tests/distributed \
                             tests/models \
                             tests/pipeline \
@@ -315,4 +314,3 @@ jobs:
                             -v --timeout=600 --durations=0 --durations-min=0 -x
         env:
           ROLL_NPU_CI: "1"
-          DS_UNITTEST_TIMEOUT: "600"

docker/Dockerfile.A2

@@ -1,4 +1,4 @@
-FROM quay.io/ascend/cann:8.5.1-910b-ubuntu22.04-py3.11
+FROM quay.io/ascend/cann:9.0.0-910b-ubuntu22.04-py3.11
 
 ARG SOC_VERSION="ascend910b1"
 
@@ -9,6 +9,7 @@ ENV PIP_CONSTRAINT=""
 
 ENV LD_LIBRARY_PATH=/usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64/common:/usr/local/Ascend/driver/lib64/driver:/usr/local/Ascend/add-ons:/usr/local/Ascend/ascend-toolkit/latest/fwkacllib/lib64:/usr/local/Ascend/ascend-toolkit/latest/acllib/lib64:/usr/local/Ascend/ascend-toolkit/latest/atc/lib64:${LD_LIBRARY_PATH}
 ENV ASCEND_HOME_PATH=/usr/local/Ascend/ascend-toolkit/latest
+ENV HCCL_NPU_SOCKET_PORT_RANGE=auto
 
 RUN apt-get update -y && \
     apt-get install -y --no-install-recommends \
@@ -26,8 +27,8 @@ RUN pip config set global.index-url https://mirrors.huaweicloud.com/repository/p
 
 WORKDIR /workspace
 
-RUN git clone --depth 1 -b v0.13.0 https://github.com/vllm-project/vllm.git && \
-    git clone --depth 1 -b releases/v0.13.0 https://github.com/vllm-project/vllm-ascend.git
+RUN git clone --depth 1 -b v0.18.0 https://github.com/vllm-project/vllm.git && \
+    git clone --depth 1 -b v0.18.0 https://github.com/vllm-project/vllm-ascend.git
 
 RUN cd vllm && \
     pip install -r requirements/build.txt && \
@@ -36,7 +37,7 @@ RUN cd vllm && \
     pip cache purge && \
     cd ..
 
-RUN pip install torch==2.8.0+cpu torchvision==0.23.0 torchaudio==2.8.0 \
+RUN pip install torch==2.9.0+cpu torchvision==0.24.0 torchaudio==2.9.0 \
     --index-url https://download.pytorch.org/whl/cpu
 
 RUN source /usr/local/Ascend/ascend-toolkit/set_env.sh && \
@@ -50,17 +51,18 @@ COPY . .
 
 RUN pip install -r requirements_common.txt
 
-RUN pip install "deepspeed==0.16.4" "transformers==4.57.6" "tensorboard==2.20.0"
+RUN pip install "transformers==4.57.6" "tensorboard==2.20.0"
 
 RUN pip install -e .
 
 RUN rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* && \
     pip uninstall -y triton && \
     pip uninstall -y triton-ascend && \
-    pip install triton-ascend==3.2.0 && \
+    pip install triton-ascend==3.2.1 --extra-index-url https://mirrors.huaweicloud.com/ascend/repos/pypi && \
     pip cache purge
 
 RUN echo "source /usr/local/Ascend/ascend-toolkit/set_env.sh" >> /root/.bashrc && \
-    echo "source /usr/local/Ascend/nnal/atb/set_env.sh" >> /root/.bashrc
+    echo "source /usr/local/Ascend/nnal/atb/set_env.sh" >> /root/.bashrc && \
+    echo "export HCCL_NPU_SOCKET_PORT_RANGE=auto" >> /root/.bashrc
 
-CMD ["/bin/bash"]
+CMD ["/bin/bash"]

docker/Dockerfile.A3

@@ -1,4 +1,4 @@
-FROM quay.io/ascend/cann:8.5.1-a3-ubuntu22.04-py3.11
+FROM quay.io/ascend/cann:9.0.0-a3-ubuntu22.04-py3.11
 
 ARG SOC_VERSION="ascend910_9391"
 
@@ -9,6 +9,7 @@ ENV PIP_CONSTRAINT=""
 
 ENV LD_LIBRARY_PATH=/usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64/common:/usr/local/Ascend/driver/lib64/driver:/usr/local/Ascend/add-ons:/usr/local/Ascend/ascend-toolkit/latest/fwkacllib/lib64:/usr/local/Ascend/ascend-toolkit/latest/acllib/lib64:/usr/local/Ascend/ascend-toolkit/latest/atc/lib64:${LD_LIBRARY_PATH}
 ENV ASCEND_HOME_PATH=/usr/local/Ascend/ascend-toolkit/latest
+ENV HCCL_NPU_SOCKET_PORT_RANGE=auto
 
 RUN apt-get update -y && \
     apt-get install -y --no-install-recommends \
@@ -26,8 +27,8 @@ RUN pip config set global.index-url https://mirrors.huaweicloud.com/repository/p
 
 WORKDIR /workspace
 
-RUN git clone --depth 1 -b v0.13.0 https://github.com/vllm-project/vllm.git && \
-    git clone --depth 1 -b releases/v0.13.0 https://github.com/vllm-project/vllm-ascend.git
+RUN git clone --depth 1 -b v0.18.0 https://github.com/vllm-project/vllm.git && \
+    git clone --depth 1 -b v0.18.0 https://github.com/vllm-project/vllm-ascend.git
 
 RUN cd vllm && \
     pip install -r requirements/build.txt && \
@@ -36,7 +37,7 @@ RUN cd vllm && \
     pip cache purge && \
     cd ..
 
-RUN pip install torch==2.8.0+cpu torchvision==0.23.0 torchaudio==2.8.0 \
+RUN pip install torch==2.9.0+cpu torchvision==0.24.0 torchaudio==2.9.0 \
     --index-url https://download.pytorch.org/whl/cpu
 
 RUN source /usr/local/Ascend/ascend-toolkit/set_env.sh && \
@@ -50,17 +51,18 @@ COPY . .
 
 RUN pip install -r requirements_common.txt
 
-RUN pip install "deepspeed==0.16.4" "transformers==4.57.6" "tensorboard==2.20.0"
+RUN pip install "transformers==4.57.6" "tensorboard==2.20.0"
 
 RUN pip install -e .
 
 RUN rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* && \
     pip uninstall -y triton && \
     pip uninstall -y triton-ascend && \
-    pip install triton-ascend==3.2.0 && \
+    pip install triton-ascend==3.2.1 --extra-index-url https://mirrors.huaweicloud.com/ascend/repos/pypi && \
     pip cache purge
 
 RUN echo "source /usr/local/Ascend/ascend-toolkit/set_env.sh" >> /root/.bashrc && \
-    echo "source /usr/local/Ascend/nnal/atb/set_env.sh" >> /root/.bashrc
+    echo "source /usr/local/Ascend/nnal/atb/set_env.sh" >> /root/.bashrc && \
+    echo "export HCCL_NPU_SOCKET_PORT_RANGE=auto" >> /root/.bashrc
 
-CMD ["/bin/bash"]
+CMD ["/bin/bash"]

docs_roll/docs/User Guides/Hardware Support/ascend_docker_usage.md

@@ -2,15 +2,15 @@
 
 Last updated: 04/27/2026.
 
-This guide explains how to build and run ROLL on **Huawei Ascend NPU** using `Dockerfile.A2` and `Dockerfile.A3`.
+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.
 
 ## Hardware & Software Requirements
 
 | Item | Dockerfile.A2 | Dockerfile.A3 |
 | ---- | ------------- | ------------- |
 | Hardware | Atlas 900 A2 PODc (Ascend 910B1) | Atlas 900 A3 PODc (Ascend 910_9391) |
 | Host OS | Ubuntu 22.04 | Ubuntu 22.04 |
-| CANN | 8.5.1 | 8.5.1 |
+| CANN | 9.0.0 | 9.0.0 |
 | Python | 3.11 | 3.11 |
 | Docker | >= 20.10 | >= 20.10 |
 | Ascend NPU Driver | Installed on host | Installed on host |
@@ -21,21 +21,42 @@ Both Dockerfiles install the same versions of core dependencies:
 
 | Component | Version |
 | --------- | ------- |
-| PyTorch | 2.8.0+cpu |
-| vLLM | 0.13.0 |
-| vLLM-Ascend | 0.13.0 |
-| DeepSpeed | 0.16.4 |
+| PyTorch | 2.9.0+cpu |
+| vLLM | 0.18.0 |
+| vLLM-Ascend | 0.18 |
 | Transformers | 4.57.6 |
-| triton-ascend | 3.2.0 |
+| triton-ascend | 3.2.1 |
 
 The primary difference is the base image and SOC version:
 
 | Item | Dockerfile.A2 | Dockerfile.A3 |
 | ---- | ------------- | ------------- |
-| Base Image | `quay.io/ascend/cann:8.5.1-910b-ubuntu22.04-py3.11` | `quay.io/ascend/cann:8.5.1-a3-ubuntu22.04-py3.11` |
+| Base Image | `quay.io/ascend/cann:9.0.0-910b-ubuntu22.04-py3.11` | `quay.io/ascend/cann:9.0.0-a3-ubuntu22.04-py3.11` |
 | SOC_VERSION | `ascend910b1` | `ascend910_9391` |
 
-## Build the Docker Image
+## Get the Docker Image
+
+### Option A: Use the Pre-built Image (Recommended)
+
+Pull the image that matches your hardware, then tag it with the local name used by the commands below:
+
+**For Atlas 900 A2 PODc (Ascend 910B1):**
+
+```bash
+docker pull quay.io/ascend/roll:main-a2
+docker tag quay.io/ascend/roll:main-a2 roll:ascend-a2
+```
+
+**For Atlas 900 A3 PODc (Ascend 910_9391):**
+
+```bash
+docker pull quay.io/ascend/roll:main-a3
+docker tag quay.io/ascend/roll:main-a3 roll:ascend-a3
+```
+
+Check https://quay.io/repository/ascend/roll?tab=tags for available image tags. If you use a pre-built image, continue with [Run the Container](#run-the-container).
+
+### Option B: Build from Dockerfile
 
 ### 1. Clone the ROLL Repository
 
@@ -88,6 +109,7 @@ docker run -dit \
     --device /dev/davinci4 \
     --device /dev/davinci5 \
     --device /dev/davinci6 \
+    --device /dev/davinci7 \
     --device /dev/davinci_manager \
     --device /dev/devmm_svm \
     --device /dev/hisi_hdc \
@@ -115,6 +137,37 @@ docker run -dit \
     --device /dev/davinci4 \
     --device /dev/davinci5 \
     --device /dev/davinci6 \
+    --device /dev/davinci7 \
+    --device /dev/davinci_manager \
+    --device /dev/devmm_svm \
+    --device /dev/hisi_hdc \
+    -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
+    -v /usr/local/Ascend/add-ons:/usr/local/Ascend/add-ons \
+    -v /usr/local/dcmi:/usr/local/dcmi \
+    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
+    -v /etc/ascend_install.info:/etc/ascend_install.info \
+    -v /home/$USER:/home/$USER \
+    --ipc=host \
+    --net=host \
+    roll:ascend-a3 \
+    /bin/bash
+```
+
+### Multi-NPU Startup (Recommended for Training)
+
+For multi-NPU training, mount all available NPU devices. Adjust the number of `--device /dev/davinciX` entries according to the NPU count on your node:
+
+```bash
+docker run -dit \
+    --name roll_ascend \
+    --device /dev/davinci0 \
+    --device /dev/davinci1 \
+    --device /dev/davinci2 \
+    --device /dev/davinci3 \
+    --device /dev/davinci4 \
+    --device /dev/davinci5 \
+    --device /dev/davinci6 \
+    --device /dev/davinci7 \
     --device /dev/davinci_manager \
     --device /dev/devmm_svm \
     --device /dev/hisi_hdc \
@@ -124,12 +177,20 @@ docker run -dit \
     -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
     -v /etc/ascend_install.info:/etc/ascend_install.info \
     -v /home/$USER:/home/$USER \
+    -v /path/to/models:/path/to/models \
+    -v /path/to/data:/path/to/data \
     --ipc=host \
     --net=host \
     roll:ascend-a3 \
     /bin/bash
 ```
 
+> **Note:**
+> - `--device /dev/davinciX`: Mounts NPU devices. Add or remove entries based on available NPU count.
+> - `--device /dev/davinci_manager`, `--device /dev/devmm_svm`, `--device /dev/hisi_hdc`: Required management devices for Ascend NPU.
+> - `-v /usr/local/Ascend/driver`: Mounts the host Ascend driver.
+> - `-v /path/to/models` and `-v /path/to/data`: Mount model weights and training data directories as needed.
+
 ### Enter the Container
 
 ```bash
@@ -152,7 +213,7 @@ npu-smi info
 env | grep -E "ASCEND|LD_LIBRARY_PATH|PATH"
 
 # Verify Python packages
-python -c "import torch; import torch_npu; print(torch_npu.npu.is_available())"
+python -c "import torch; import torch_npu; print(torch.npu.is_available())"
 python -c "import vllm; print(f'vllm: {vllm.__version__}')"
 python -c "import vllm_ascend; print(f'vllm_ascend available')"
 ```
@@ -161,20 +222,21 @@ python -c "import vllm_ascend; print(f'vllm_ascend available')"
 
 ### Important Configuration Notes
 
-Since Megatron-LM training is not yet supported on Ascend NPU, you need to use **DeepSpeed** as the training backend. Make sure your configuration files use the following settings:
+Since Megatron-LM is not supported on Ascend NPU, you need to use **FSDP2** as the training backend. Make sure your configuration files use the following settings:
 
-1. Set `strategy_args` to use DeepSpeed
-2. Set `device_mapping` to ensure training and inference are performed on different NPUs
+1. Set `strategy_args` to use FSDP2
 
 ### Example: RLVR Pipeline
 
 ```bash
 # After modifying model paths and adjusting device_mapping
 python examples/start_rlvr_pipeline.py \
     --config_path ascend_examples \
-    --config_name qwen3_8b_rlvr_deepspeed
+    --config_name qwen3_30b_rlvr_fsdp2
 ```
 
+> **Note:** The `qwen3_30b_rlvr_fsdp2` configuration is specifically designed for Ascend NPU with FSDP2 as the training backend. Adjust `device_mapping` in the configuration file according to your NPU topology.
+
 ## Troubleshooting
 
 ### NPU Not Visible Inside Container

docs_roll/docs/User Guides/Hardware Support/ascend_npu_env_config.md

@@ -79,6 +79,7 @@ These variables control the behavior of HCCL (Huawei Collective Communication Li
 | `HCCL_DETERMINISTIC` | `false` | Disable deterministic computation. Enabling it significantly reduces communication performance |
 | `HCCL_OP_EXPANSION_MODE` | `"AIV"` | Communication algorithm dispatch location. `AIV` uses Vector Core, outperforms `AI_CPU`/`HOST`/`HOST_TS` |
 | `HCCL_BUFFSIZE` | e.g. `"2147483648"` | HCCL communication buffer size in bytes. Increase for large data volume scenarios |
+| `HCCL_NPU_SOCKET_PORT_RANGE` | `auto` | Allow HCCL to allocate non-default device-side NIC ports when multiple worker processes run on the same NPU |
 | `HCCL_IF_IP` | Node's IP address | Specify the IP address used by HCCL for inter-node communication. Required for multi-node training |
 | `HCCL_SOCKET_IFNAME` | e.g. `"enp194s0f0"` | Network interface name for HCCL socket communication. Must be consistent across all nodes |
 | `HCCL_IF_BASE_PORT` | e.g. `23456` | Base port for HCCL inter-node communication. Ensure ports are not blocked by firewall |
@@ -90,6 +91,7 @@ Example (single-node):
 export HCCL_CONNECT_TIMEOUT=3600
 export HCCL_DETERMINISTIC=false
 export HCCL_OP_EXPANSION_MODE="AIV"
+export HCCL_NPU_SOCKET_PORT_RANGE="auto"
 ```
 
 Example (multi-node):
@@ -99,6 +101,7 @@ export HCCL_CONNECT_TIMEOUT=3600
 export HCCL_EXEC_TIMEOUT=3600
 export HCCL_DETERMINISTIC=false
 export HCCL_OP_EXPANSION_MODE="AIV"
+export HCCL_NPU_SOCKET_PORT_RANGE="auto"
 export HCCL_IF_IP=$(hostname -I | awk '{print $1}')
 export HCCL_SOCKET_IFNAME="enp194s0f0"
 export HCCL_IF_BASE_PORT=23456
@@ -151,8 +154,7 @@ export CPU_AFFINITY_CONF=1,npu0:0-1,npu1:2-3,npu2:4-5,npu3:6-7
 | `VLLM_USE_V1` | `1` | Enable vLLM V1 architecture. Required for vLLM-Ascend |
 | `VLLM_ATTENTION_BACKEND` | `XFORMERS` | vLLM attention computation backend |
 | `VLLM_ASCEND_ENABLE_FLASHCOMM` | `1` | Enable Ascend FlashComm high-speed communication optimization |
-| `VLLM_ASCEND_ENABLE_DENSE_OPTIMIZE` | `1` | Enable dense computation optimization for large model inference |
-| `VLLM_ASCEND_ENABLE_PREFETCH_MLP` | `1` | Enable MLP layer weight prefetching |
+| `VLLM_ASCEND_ENABLE_PREFETCH_MLP` | `1` | Enable MLP layer weight prefetching. This replaces the older dense optimize toggle in current vLLM-Ascend releases. |
 | `VLLM_ASCEND_ENABLE_TOPK_OPTIMIZE` | `1` | Enable TopK operator fusion optimization for generation decoding |
 | `VLLM_ASCEND_MODEL_EXECUTE_TIME_OBSERVE` | `1` | Print prefill/decode phase timing details (for debugging) |
 | `VLLM_ASCEND_TRACE_RECOMPILES` | `1` | Trace operator recompilation for debugging performance issues |
@@ -164,7 +166,6 @@ Example:
 export VLLM_USE_V1=1
 export VLLM_ATTENTION_BACKEND=XFORMERS
 export VLLM_ASCEND_ENABLE_FLASHCOMM=1
-export VLLM_ASCEND_ENABLE_DENSE_OPTIMIZE=1
 export VLLM_ASCEND_ENABLE_PREFETCH_MLP=1
 ```
 
@@ -243,7 +244,6 @@ export OMP_NUM_THREADS=1
 # vLLM-Ascend inference
 export VLLM_USE_V1=1
 export VLLM_ASCEND_ENABLE_FLASHCOMM=1
-export VLLM_ASCEND_ENABLE_DENSE_OPTIMIZE=1
 export VLLM_ASCEND_ENABLE_PREFETCH_MLP=1
 
 # Operator compilation cache