[doc] feat: update Qwen3.5 NPU guide (verl-project#6667)

### What does this PR do?

update qwen3.5 ascend doc for 35b and 122b size

### Checklist Before Starting

- [ ] Search for similar PRs. Paste at least one query link here: ...
- [x] Format the PR title as `[{modules}] {type}: {description}` (This
will be checked by the CI)
- `{modules}` include `fsdp`, `megatron`, `veomni`, `sglang`, `vllm`,
`rollout`, `trainer`, `ci`, `training_utils`, `recipe`, `hardware`,
`deployment`, `ray`, `worker`, `single_controller`, `misc`, `perf`,
`model`, `algo`, `env`, `tool`, `ckpt`, `doc`, `data`, `cfg`, `reward`,
`fully_async`, `one_step_off`
- If this PR involves multiple modules, separate them with `,` like
`[megatron, fsdp, doc]`
  - `{type}` is in `feat`, `fix`, `refactor`, `chore`, `test`
- If this PR breaks any API (CLI arguments, config, function signature,
etc.), add `[BREAKING]` to the beginning of the title.
  - Example: `[BREAKING][fsdp, megatron] feat: dynamic batching`

### Test

> For changes that can not be tested by CI (e.g., algorithm
implementation, new model support), validate by experiment(s) and show
results like training curve plots, evaluation results, etc.

### API and Usage Example

> Demonstrate how the API changes if any, and provide usage example(s)
if possible.

```python
# Add code snippet or script demonstrating how to use this
```

### Design & Code Changes

> Demonstrate the high-level design if this PR is complex, and list the
specific changes.

### Checklist Before Submitting

> [!IMPORTANT]
> Please check all the following items before requesting a review,
otherwise the reviewer might deprioritize this PR for review.

- [x] Read the [Contribute
Guide](https://github.com/verl-project/verl/blob/main/CONTRIBUTING.md).
- [x] Apply [pre-commit
checks](https://github.com/verl-project/verl/blob/main/CONTRIBUTING.md#code-linting-and-formatting):
`pre-commit install && pre-commit run --all-files --show-diff-on-failure
--color=always`
- [ ] Add / Update [the
documentation](https://github.com/verl-project/verl/tree/main/docs).
- [ ] Add unit or end-to-end test(s) to [the CI
workflow](https://github.com/verl-project/verl/tree/main/.github/workflows)
to cover all the code. If not feasible, explain why: ...
- [ ] Once your PR is ready for CI, send a message in [the `ci-request`
channel](https://verl-project.slack.com/archives/C091TCESWB1) in [the
`verl` Slack
workspace](https://join.slack.com/t/verl-project/shared_invite/zt-3855yhg8g-CTkqXu~hKojPCmo7k_yXTQ).
(If not accessible, please try [the Feishu group
(飞书群)](https://applink.larkoffice.com/client/chat/chatter/add_by_link?link_token=772jd4f1-cd91-441e-a820-498c6614126a).)
- [ ] If your PR is related to the `recipe` submodule, please also
update the reference to the submodule commit via `git submodule update
--remote` or `cd recipe && git pull origin main`.

Author: zjchenn

docs/ascend_tutorial/index.rst

@@ -29,7 +29,7 @@ Last updated: 06/05/2026.
    model_support/examples/ascend_vllm_best_practices
    model_support/examples/dapo_multi_model_optimization_practice
    model_support/examples/gspo_optimization_practice
-   model_support/examples/qwen3_5_122b_npu
+   model_support/examples/qwen3_5_megatron_npu
 
 .. toctree::
    :maxdepth: 1

docs/ascend_tutorial/model_support/examples/qwen3_5_122b_npu.md

@@ -0,0 +1,135 @@
+# Qwen3.5 Megatron NPU 使用指南
+
+Last updated: 06/08/2026.
+
+本文用于指导在 Ascend NPU 上使用 verl + Megatron + vLLM 跑通 Qwen3.5-35B-A3B 和 Qwen3.5-122B-A10B GRPO 示例。
+
+## 版本要求
+
+| software | version |
+| --- | --- |
+| Docker image | `quay.io/ascend/verl:verl-9.0.0-a3-ubuntu22.04-py3.11-latest` |
+| verl | commit `cdd9014f` |
+| Python | 3.11 |
+| CANN | 9.0.0 |
+| Megatron-LM | 0.16.1 |
+| MindSpeed | 0.16.0 |
+| Megatron-Bridge | `de93536e` |
+
+建议直接使用上表中的镜像：
+
+```bash
+docker pull quay.io/ascend/verl:verl-9.0.0-a3-ubuntu22.04-py3.11-latest
+```
+
+启动容器后，将 verl 固定到指定 commit：
+
+```bash
+git checkout cdd9014f
+```
+
+脚本注释中列出的额外依赖如下；镜像已包含的依赖不需要重复安装：
+
+```bash
+pip install viztracer flash-linear-attention nvidia-modelopt nvidia-ml-py nvidia-resiliency-ext megatron-energon
+```
+
+## 模型和脚本
+
+| model | HF model | script |
+| --- | --- | --- |
+| Qwen3.5-35B-A3B | `Qwen/Qwen3.5-35B-A3B` | `examples/grpo_trainer/run_qwen3_5_35b_megatron.sh` |
+| Qwen3.5-122B-A10B | `Qwen/Qwen3.5-122B-A10B` | `examples/grpo_trainer/run_qwen3_5_122b_a10b_megatron.sh` |
+
+## 硬件和并行配置
+
+示例脚本默认使用如下 NPU 配置，可以通过同名环境变量覆盖：
+
+| model | nnodes | devices per node | TP | PP | CP | EP | ETP | GEN_TP |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Qwen3.5-35B-A3B | 1 | 16 | 2 | 2 | 1 | 8 | 1 | 8 |
+| Qwen3.5-122B-A10B | 4 | 16 | 2 | 4 | 1 | 16 | 1 | 16 |
+
+## 数据和模型准备
+
+脚本默认使用 Geo3K 数据集，并会下载到 `$HOME/data/geo3k`：
+
+```bash
+hf download tyzhu/geo3k --repo-type dataset --local-dir $HOME/data/geo3k
+```
+
+模型权重可以使用 Hugging Face 模型名，也可以提前下载到本地路径：
+
+```bash
+hf download Qwen/Qwen3.5-35B-A3B --local-dir /path/to/Qwen3.5-35B-A3B
+hf download Qwen/Qwen3.5-122B-A10B --local-dir /path/to/Qwen3.5-122B-A10B
+```
+
+## 启动训练
+
+训练前需要先启动 Ray 集群。通用多节点说明可参考 [Multinode Training](../../../start/multinode.rst)，Ascend 多节点脚本示例可参考 [Ascend SGLang Best Practices](ascend_sglang_best_practices.rst)。
+
+最小启动方式如下，单机任务只需要执行 head 节点命令；多机任务需要在其他节点执行 worker 节点命令。`MASTER_ADDR` 在所有节点上保持一致，`CURRENT_IP` 设置为当前节点 IP。
+
+```bash
+MASTER_ADDR=<head-node-ip>
+CURRENT_IP=<current-node-ip>
+NPUS_PER_NODE=16
+
+# head node
+ray start --head --port 6766 --dashboard-host=$MASTER_ADDR --node-ip-address=$CURRENT_IP --dashboard-port=8260 --resources='{"NPU": '$NPUS_PER_NODE'}'
+
+# worker nodes, only needed for multi-node jobs
+ray start --address="$MASTER_ADDR:6766" --node-ip-address=$CURRENT_IP --resources='{"NPU": '$NPUS_PER_NODE'}'
+
+ray status
+```
+
+通过 `ray status` 确认 NPU 资源数量符合预期后，在主节点执行训练脚本。Qwen3.5-35B-A3B 默认需要 16 个 NPU 资源，Qwen3.5-122B-A10B 默认需要 64 个 NPU 资源。
+
+### Qwen3.5-35B-A3B
+
+```bash
+export DEVICE=npu
+export HF_MODEL_PATH=/path/to/Qwen3.5-35B-A3B
+
+bash examples/grpo_trainer/run_qwen3_5_35b_megatron.sh
+```
+
+如果需要覆盖数据路径：
+
+```bash
+DEVICE=npu \
+HF_MODEL_PATH=/path/to/Qwen3.5-35B-A3B \
+train_path=/path/to/train.parquet \
+test_path=/path/to/test.parquet \
+bash examples/grpo_trainer/run_qwen3_5_35b_megatron.sh
+```
+
+### Qwen3.5-122B-A10B
+
+```bash
+export DEVICE=npu
+export HF_MODEL_PATH=/path/to/Qwen3.5-122B-A10B
+
+bash examples/grpo_trainer/run_qwen3_5_122b_a10b_megatron.sh
+```
+
+如果需要覆盖数据、保存路径或并行配置：
+
+```bash
+DEVICE=npu \
+HF_MODEL_PATH=/path/to/Qwen3.5-122B-A10B \
+train_files=/path/to/train.parquet \
+test_files=/path/to/test.parquet \
+save_path=/path/to/checkpoints \
+n_devices_per_node=16 \
+nnodes=4 \
+bash examples/grpo_trainer/run_qwen3_5_122b_a10b_megatron.sh
+```
+
+## 注意事项
+
+- 脚本会通过 `torch_npu` 自动识别 NPU 环境；如需手动指定，设置 `DEVICE=npu`。
+- Qwen3.5 的 Gated Delta Net 当前不使用 packed sequence，因此脚本中保持 `use_remove_padding=False` 和 `use_dynamic_bsz=False`。
+- NPU 分支会设置 `vanilla_mbridge=False`、`use_flash_attn=True`、`moe_token_dispatcher_type=alltoall` 等 Ascend 适配参数。

docs/ascend_tutorial/model_support/examples/qwen3_5_megatron_npu.md

@@ -46,7 +46,7 @@ Last updated: 05/14/2026.
 | 38 | Qwen3.5-27B | GRPO | [27B](https://huggingface.co/Qwen/Qwen3.5-27B) | FSDP(MindSpeed-MM) | vllm | [`link`](https://github.com/verl-project/verl-ascend-recipe/tree/main/grpo_mindspeed_mm/run_qwen3_5-27b_npu.sh) | - | Atlas 200T A2 Box16, Atlas 800T A3 |
 | 39 | Qwen3.5-35B-A3B | GRPO | [35B](https://huggingface.co/Qwen/Qwen3.5-35B-A3B) | FSDP2 | vllm | [`link`](https://github.com/verl-project/verl/blob/main/examples/grpo_trainer/run_qwen3_5_35b_fsdp.sh) | - | Atlas 200T A2 Box16, Atlas 800T A3 |
 | 40 | Qwen3.5-35B-A3B | GRPO | [35B](https://huggingface.co/Qwen/Qwen3.5-35B-A3B) | FSDP2(MindSpeed-MM) | vllm | [`link`](https://github.com/verl-project/verl-ascend-recipe/tree/main/grpo_mindspeed_mm/run_qwen3_5-35b_npu.sh) | - | Atlas 200T A2 Box16, Atlas 800T A3 |
-| 41 | Qwen3.5-122B-A10B | GRPO | [122B](https://huggingface.co/Qwen/Qwen3.5-122B-A10B) | Megatron | vllm | [`link`](https://github.com/verl-project/verl/blob/main/examples/grpo_trainer/run_qwen3_5_122b_a10b_megatron.sh) | [`link`](examples/qwen3_5_122b_npu.md) | Atlas 800T A3 |
+| 41 | Qwen3.5-122B-A10B | GRPO | [122B](https://huggingface.co/Qwen/Qwen3.5-122B-A10B) | Megatron | vllm | [`link`](https://github.com/verl-project/verl/blob/main/examples/grpo_trainer/run_qwen3_5_122b_a10b_megatron.sh) | [`link`](examples/qwen3_5_megatron_npu.md) | Atlas 800T A3 |
 | 42 | Qwen3-Next-80B-A3B-Instruct | GRPO | [80B](https://huggingface.co/Qwen/Qwen3-Next-80B-A3B-Instruct) | FSDP2 | vllm | [`link`](https://github.com/verl-project/verl/blob/main/examples/grpo_trainer/run_qwen3_next_80b_a3b_fsdp.sh) | - | Atlas 900 A2 PODc, Atlas 200T A2 Box16, Atlas 800T A3 |
 | 43 | DeepSeek-V3 | GRPO | [671B](https://huggingface.co/deepseek-ai/DeepSeek-V3) | Megatron | vllm | [`link`](https://github.com/verl-project/verl-ascend-recipe/tree/main/r1_ascend/run_deepseekv3_671b_grpo_megatron_npu.sh) | - | Atlas 200T A2 Box16, Atlas 800T A3 |
 | 44 | Qwen3-1.7B | GRPO | [1.7B](https://huggingface.co/Qwen/Qwen3-1.7B) | VeOmni | vllm | [`link`](https://github.com/verl-project/verl-ascend-recipe/blob/main/verl_ascend_practice/run_qwen3_1_7b_npu.sh) | - | Atlas 800T A3 |