alibaba · shun001 · Jul 16, 2026
diff --git a/.github/workflows/ci-npu-mindspeed.yml b/.github/workflows/ci-npu-mindspeed.yml
@@ -0,0 +1,195 @@
+name: MegatronAdaptor NPU Tests
+
+on:
+  workflow_dispatch:
+    inputs:
+      megatron_adaptor_repo:
+        description: "MegatronAdaptor git repository"
+        default: "https://gitcode.com/Ascend/MegatronAdaptor.git"
+      megatron_adaptor_ref:
+        description: "MegatronAdaptor branch, tag, or ref to install"
+        default: "core_r0.17.0"
+      transformer_engine_npu_repo:
+        description: "TransformerEngineNPU git repository"
+        default: "https://gitcode.com/Ascend/TransformerEngineNPU.git"
+      transformer_engine_npu_ref:
+        description: "TransformerEngineNPU branch, tag, or ref to install"
+        default: "main"
+      megatron_core_repo:
+        description: "Megatron-Core git repository"
+        default: "https://github.com/NVIDIA/Megatron-LM.git"
+      megatron_core_ref:
+        description: "Megatron-Core branch, tag, or ref to install"
+        default: "core_r0.17.0"
+  push:
+    branches: [main, npu_ci_all]
+    paths: &npu_paths
+      - ".github/workflows/ci-npu-mindspeed.yml"
+      - "mcore_adapter/**"
+      - "roll/**"
+      - "tests/third_party/megatron/**"
+      - "requirements_common.txt"
+      - "requirements_vision.txt"
+      - "setup.py"
+      - "pyproject.toml"
+  pull_request:
+    branches: [main, npu_ci_all]
+    paths: *npu_paths
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  megatron-adaptor-npu-test:
+    name: MegatronAdaptor 0.17 Core NPU Tests
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: linux-aarch64-a3-8
+    timeout-minutes: 90
+    container:
+      image: quay.io/ascend/vllm-ascend:v0.18.0-a3
+    env:
+      PIP_CACHE_DIR: ${{ github.workspace }}/.pip-cache
+      PIP_INDEX_URL: https://repo.huaweicloud.com/repository/pypi/simple
+      PIP_TRUSTED_HOST: repo.huaweicloud.com
+      HF_ENDPOINT: https://hf-mirror.com
+      PYTORCH_NPU_ALLOC_CONF: "expandable_segments:True"
+      TASK_QUEUE_ENABLE: "2"
+      MEGATRON_ADAPTOR_REPO: ${{ github.event.inputs.megatron_adaptor_repo || 'https://gitcode.com/Ascend/MegatronAdaptor.git' }}
+      MEGATRON_ADAPTOR_REF: ${{ github.event.inputs.megatron_adaptor_ref || 'core_r0.17.0' }}
+      TRANSFORMER_ENGINE_NPU_REPO: ${{ github.event.inputs.transformer_engine_npu_repo || 'https://gitcode.com/Ascend/TransformerEngineNPU.git' }}
+      TRANSFORMER_ENGINE_NPU_REF: ${{ github.event.inputs.transformer_engine_npu_ref || 'main' }}
+      MEGATRON_CORE_REPO: ${{ github.event.inputs.megatron_core_repo || 'https://github.com/NVIDIA/Megatron-LM.git' }}
+      MEGATRON_CORE_REF: ${{ github.event.inputs.megatron_core_ref || 'core_r0.17.0' }}
+      MEGATRON_ADAPTOR_CACHE_KEY: "core-r0.17.0-te-npu-main"
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Cache NPU pip packages
+        uses: actions/cache@v4
+        with:
+          path: .pip-cache
+          key: ${{ runner.os }}-npu-megatron-adaptor-${{ env.MEGATRON_ADAPTOR_CACHE_KEY }}-${{ hashFiles('requirements_common.txt', 'requirements_vision.txt', 'mcore_adapter/pyproject.toml', 'mcore_adapter/requirements.txt', 'setup.py', 'pyproject.toml', '.github/workflows/ci-npu-mindspeed.yml') }}
+          restore-keys: |
+            ${{ runner.os }}-npu-megatron-adaptor-${{ env.MEGATRON_ADAPTOR_CACHE_KEY }}-
+            ${{ runner.os }}-npu-megatron-adaptor-
+            ${{ runner.os }}-npu-pip-
+
+      - name: Configure Ascend runtime
+        shell: bash
+        run: |
+          for env_file in \
+            /usr/local/Ascend/ascend-toolkit/set_env.sh \
+            /usr/local/Ascend/nnal/atb/set_env.sh; do
+            [ -f "${env_file}" ] && source "${env_file}"
+          done
+
+          ASCEND_HOME_PATH="${ASCEND_HOME_PATH:-/usr/local/Ascend/ascend-toolkit/latest}"
+          ASCEND_TOOLKIT_HOME="${ASCEND_TOOLKIT_HOME:-${ASCEND_HOME_PATH}}"
+          ASCEND_OPP_PATH="${ASCEND_OPP_PATH:-${ASCEND_HOME_PATH}/opp}"
+          ASCEND_AICPU_PATH="${ASCEND_AICPU_PATH:-${ASCEND_HOME_PATH}}"
+          LD_LIBRARY_PATH="${ASCEND_HOME_PATH}/lib64:${ASCEND_HOME_PATH}/runtime/lib64:${ASCEND_HOME_PATH}/runtime/lib64/stub:${ASCEND_HOME_PATH}/tools/hccl/lib64:${ASCEND_HOME_PATH}/hccl/lib64:${LD_LIBRARY_PATH:-}"
+
+          for path in \
+            "${ASCEND_OPP_PATH}/built-in/op_impl/ai_core/tbe" \
+            "${ASCEND_HOME_PATH}/python/site-packages"; do
+            [ -d "${path}" ] && PYTHONPATH="${path}:${PYTHONPATH:-}"
+          done
+
+          {
+            echo "ASCEND_HOME_PATH=${ASCEND_HOME_PATH}"
+            echo "ASCEND_TOOLKIT_HOME=${ASCEND_TOOLKIT_HOME}"
+            echo "ASCEND_OPP_PATH=${ASCEND_OPP_PATH}"
+            echo "ASCEND_AICPU_PATH=${ASCEND_AICPU_PATH}"
+            echo "LD_LIBRARY_PATH=${LD_LIBRARY_PATH}"
+            echo "PYTHONPATH=${PYTHONPATH:-}"
+          } >> "${GITHUB_ENV}"
+          {
+            echo "${ASCEND_HOME_PATH}/bin"
+            echo "${ASCEND_HOME_PATH}/compiler/ccec_compiler/bin"
+          } >> "${GITHUB_PATH}"
+
+      - name: Check NPU environment
+        run: |
+          python3 - <<'PY'
+          import importlib.util
+
+          import torch
+          import torch_npu
+
+          if importlib.util.find_spec("tbe") is None:
+              raise RuntimeError("CANN tbe Python module is not visible in PYTHONPATH")
+          if not torch.npu.is_available():
+              raise RuntimeError("torch.npu.is_available() is False")
+          print(f"npu_device_count={torch.npu.device_count()}")
+          PY
+
+      - name: Install Megatron-Core 0.17
+        shell: bash
+        run: |
+          python3 -m pip install --upgrade pip wheel
+          # Megatron-Core 0.17 metadata requires Python 3.12, while the
+          # Ascend-supported stack and runner image use Python 3.10.
+          python3 -m pip install "setuptools<80" pybind11 "packaging>=24.2"
+          export MEGATRON_CORE_SRC="/tmp/Megatron-LM"
+          rm -rf "${MEGATRON_CORE_SRC}"
+          git clone --depth 1 --branch "${MEGATRON_CORE_REF}" \
+            "${MEGATRON_CORE_REPO}" "${MEGATRON_CORE_SRC}"
+          python3 -m pip install --ignore-requires-python --no-build-isolation --no-deps \
+            -e "${MEGATRON_CORE_SRC}"
+
+      - name: Install ROLL requirements
+        shell: bash
+        run: |
+          # Megatron-Core requires setuptools<80; this also keeps
+          # pkg_resources available for torchair.
+          python3 -m pip install --retries 10 --timeout 120 -r requirements_common.txt
+          python3 -m pip install --retries 10 --timeout 120 deepspeed==0.16.4 tensorboard
+          python3 -m pip install "setuptools<80"
+          python3 -c "import pkg_resources"
+
+      - name: Install Ascend Megatron dependencies
+        shell: bash
+        run: |
+          export MEGATRON_ADAPTOR_SRC="/tmp/MegatronAdaptor"
+          export TRANSFORMER_ENGINE_NPU_SRC="/tmp/TransformerEngineNPU"
+          rm -rf "${MEGATRON_ADAPTOR_SRC}" "${TRANSFORMER_ENGINE_NPU_SRC}"
+          git clone --depth 1 --branch "${TRANSFORMER_ENGINE_NPU_REF}" \
+            "${TRANSFORMER_ENGINE_NPU_REPO}" "${TRANSFORMER_ENGINE_NPU_SRC}"
+          git clone --depth 1 --branch "${MEGATRON_ADAPTOR_REF}" \
+            "${MEGATRON_ADAPTOR_REPO}" "${MEGATRON_ADAPTOR_SRC}"
+          python3 -m pip install --no-build-isolation -e "${TRANSFORMER_ENGINE_NPU_SRC}"
+          python3 -m pip install --no-build-isolation -e "${MEGATRON_ADAPTOR_SRC}"
+
+      - name: Install ROLL
+        run: |
+          python3 -m pip install -e .
+
+      - name: Prepare Megatron test model
+        shell: bash
+        run: |
+          local_model="/data/cpfs_0/common/models/Qwen2.5-0.5B-Instruct"
+          if [ -d "${local_model}" ]; then
+            echo "ROLL_MEGATRON_TEST_MODEL=${local_model}" >> "${GITHUB_ENV}"
+            exit 0
+          fi
+
+          python3 - <<'PY'
+          import os
+          from huggingface_hub import snapshot_download
+
+          model_path = snapshot_download("Qwen/Qwen2.5-0.5B-Instruct")
+          with open(os.environ["GITHUB_ENV"], "a", encoding="utf-8") as env_file:
+              env_file.write(f"ROLL_MEGATRON_TEST_MODEL={model_path}\n")
+          PY
+
+      - name: Run MegatronAdaptor offload tests
+        shell: bash
+        run: |
+          torchrun --standalone --nnodes=1 --nproc-per-node=2 \
+            -m pytest -q --tb=short tests/third_party/megatron/test_offload_states.py
diff --git a/docs_roll/docs/User Guides/Hardware Support/ascend_docker_usage.md b/docs_roll/docs/User Guides/Hardware Support/ascend_docker_usage.md
@@ -1,6 +1,6 @@
 # Running ROLL on Ascend NPU with Docker
 
-Last updated: 06/23/2026.
+Last updated: 07/16/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. Ascend 950 currently follows the manual installation profile in [ROLL x Ascend](ascend_usage.md).
 
@@ -244,9 +244,9 @@ python -c "import vllm_ascend; print(f'vllm_ascend available')"
 
 ### Important Configuration Notes
 
-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:
+The bundled RLVR example uses **FSDP2** and runs with the base Ascend image dependencies. Compatible Megatron configurations on A2/A3 require the optional packages from [Install Megatron on Ascend](ascend_usage.md#install-megatron-on-ascend); the A2/A3 Dockerfiles do not install them by default.
 
-1. Set `strategy_args` to use FSDP2
+For the bundled FSDP2 RLVR example, set `strategy_args` to use FSDP2.
 
 ### Example: RLVR Pipeline
 

diff --git a/docs_roll/docs/User Guides/Hardware Support/ascend_npu_env_config.md b/docs_roll/docs/User Guides/Hardware Support/ascend_npu_env_config.md
@@ -153,7 +153,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_FLASHCOMM` | `0` | Enable Ascend FlashComm high-speed communication optimization |
 | `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) |
@@ -165,7 +165,7 @@ Example:
 ```bash
 export VLLM_USE_V1=1
 export VLLM_ATTENTION_BACKEND=XFORMERS
-export VLLM_ASCEND_ENABLE_FLASHCOMM=1
+export VLLM_ASCEND_ENABLE_FLASHCOMM=0
 export VLLM_ASCEND_ENABLE_PREFETCH_MLP=1
 ```
 
@@ -260,7 +260,7 @@ export OMP_NUM_THREADS=1
 
 # vLLM-Ascend inference
 export VLLM_USE_V1=1
-export VLLM_ASCEND_ENABLE_FLASHCOMM=1
+export VLLM_ASCEND_ENABLE_FLASHCOMM=0
 export VLLM_ASCEND_ENABLE_PREFETCH_MLP=1
 
 # Operator compilation cache

diff --git a/docs_roll/docs/User Guides/Hardware Support/ascend_npu_examples.md b/docs_roll/docs/User Guides/Hardware Support/ascend_npu_examples.md
@@ -1,6 +1,6 @@
 # Ascend NPU End-to-End Configuration Examples
 
-Last updated: 04/27/2026.
+Last updated: 07/16/2026.
 
 This document provides end-to-end configuration examples for running ROLL on Huawei Ascend NPU, including environment setup, resource allocation, and launch commands for both single-node and multi-node scenarios.
 
@@ -12,19 +12,21 @@ Before running these examples, ensure you have:
 2. Verified the environment inside the container (see [Verify the Environment](ascend_docker_usage.md#verify-the-environment)).
 3. Downloaded the model weights to a directory accessible from inside the container.
 
-The repository currently includes a runnable Ascend RLVR example in `examples/ascend_examples`, including `qwen3_30b_rlvr_fsdp2.yaml` and `run_rlvr_pipeline.sh`.
+The repository includes runnable examples in `examples/ascend_examples`: an FSDP2 RLVR example (`qwen3_30b_rlvr_fsdp2.yaml` and `run_rlvr_pipeline.sh`) and a Megatron DPO example (`qwen3_4B_dpo_megatron.yaml` and `run_dpo_pipeline.sh`).
 
 ## Key Differences from GPU
 
-When adapting GPU configurations for NPU, the following changes are **required**:
+When adapting GPU configurations for NPU, select either the FSDP2 path used by the examples below or a compatible Megatron configuration with its optional NPU dependencies:
 
 | Item | GPU | NPU |
 | ---- | --- | --- |
-| Training backend | Megatron or FSDP2 | FSDP2 only (Megatron not supported on NPU) |
+| Training backend | Megatron or FSDP2 | FSDP2 in the examples below; Megatron for compatible A2/A3 configurations after optional dependencies are installed |
 | Attention implementation | `flash_attn` or `fa2` | `fa2` via `transformers` (not `flash_attn` package) |
 | Communication backend | NCCL | HCCL |
 | Device visibility | `CUDA_VISIBLE_DEVICES` | `ASCEND_RT_VISIBLE_DEVICES` |
 
+For the Megatron path, first complete [Install Megatron on Ascend](ascend_usage.md#install-megatron-on-ascend). The following Agentic examples intentionally remain on FSDP2.
+
 ## Example 1: Single-Node Agentic Pipeline (Qwen2.5-0.5B)
 
 This example runs the FrozenLake agentic pipeline on a single 8-NPU node using FSDP2.
@@ -82,7 +84,7 @@ export OMP_NUM_THREADS=1
 # vLLM-Ascend inference
 export VLLM_USE_V1=1
 export VLLM_ASCEND_ENABLE_NZ=0
-export VLLM_ASCEND_ENABLE_FLASHCOMM=1
+export VLLM_ASCEND_ENABLE_FLASHCOMM=0
 export VLLM_ASCEND_ENABLE_PREFETCH_MLP=1
 
 # Operator compilation cache
@@ -175,7 +177,7 @@ actor_train:
       param_dtype: bf16
       reduce_dtype: bf16
       reshard_after_forward: true
-      offload_policy: false    # NPU: Must use FSDP2, NOT megatron_train
+      offload_policy: false    # NPU FSDP2 example
   device_mapping: list(range(0,4))    # NPU: Training on NPUs 0-3
   infer_batch_size: 2
 
@@ -550,7 +552,7 @@ export OMP_NUM_THREADS=1
 # === vLLM-Ascend inference ===
 export VLLM_USE_V1=1
 export VLLM_ASCEND_ENABLE_NZ=0
-export VLLM_ASCEND_ENABLE_FLASHCOMM=1
+export VLLM_ASCEND_ENABLE_FLASHCOMM=0
 export VLLM_ASCEND_ENABLE_PREFETCH_MLP=1
 
 # === Operator compilation cache ===

diff --git a/docs_roll/docs/User Guides/Hardware Support/ascend_npu_faq.md b/docs_roll/docs/User Guides/Hardware Support/ascend_npu_faq.md
@@ -1,6 +1,6 @@
 # Ascend NPU FAQ
 
-Last updated: 04/27/2026.
+Last updated: 07/16/2026.
 
 This document compiles common issues encountered when running ROLL on Huawei Ascend NPU and their solutions.
 
@@ -93,11 +93,23 @@ pip install triton-ascend==3.2.1 --extra-index-url https://mirrors.huaweicloud.c
 
 ## Training Configuration
 
-### Megatron Strategy Not Supported
+### Megatron Strategy Initialization Error
 
-**Symptom:** Errors when using `strategy: megatron` in configuration on NPU.
+**Symptom:** Import or initialization errors occur when using `megatron_train` or `megatron_infer` on NPU.
 
-**Solution:** Megatron-LM is not supported on Ascend NPU. Use FSDP2 as the training backend:
+**Solution:** Megatron is available for validated A2/A3 configurations, but its optional dependencies are not part of the base Ascend installation. Complete [Install Megatron on Ascend](ascend_usage.md#install-megatron-on-ascend), then verify the three packages in an environment where the Ascend toolkit has been initialized:
+
+```bash
+python - <<'PY'
+import megatron_adaptor
+import megatron.core
+import transformer_engine.pytorch
+
+print("MegatronAdaptor NPU dependencies are available.")
+PY
+```
+
+If you do not need the Megatron path, select FSDP2 instead and keep the matching FSDP2 strategy configuration:
 
 ```yaml
 strategy_args: