docs/ascend_tutorial/features/ascend_backend_features.md

# Ascend Backend Features Guide
==================================================================================

Last updated: 03/03/2026.

昇腾全面支持verl生态建设，本文将介绍NPU上对于verl的适配工作及后端特性支持供开发者进行参考

---

## 推理后端

当前verl支持vllm/sglang这两种主流推理后端，均可在昇腾NPU上运行。

### 1. vllm:

昇腾通过vllm-ascend插件来支持vllm推理后端，该插件是 vLLM 社区支持 Ascend 后端的推荐方法。它遵循[[RFC]](https://github.com/vllm-project/vllm/issues/11162)，提供了一个可插拔接口，将 Ascend NPU 与 vLLM 解耦。

##### 参数特性支持

| vllm参数| verl对应通用参数 | 简介|
| --- | --- | --- |
| `model_path` | `actor_rollout_ref.model.path` |模型权重文件的路径|
| `gpu_memory_utilization` | `actor_rollout_ref.rollout.gpu_memory_utilization` |用于控制每个阶段可使用的 GPU 内存量。它被指定为一个介于 0.0 和 1.0 之间的分数，其中：- 0.8 表示 GPU 总内存的 80%- 1.0 表示 GPU 总内存的 100%（不推荐，没有预留缓冲）|
| `enforce_eager`| `actor_rollout_ref.rollout.enforce_eager` |禁用图模式，verl默认为False|
| `enable_chunked_prefill`| `actor_rollout_ref.rollout.enable_chunked_prefill` | 分块预填充允许将大预填充分块成更小的块，并将它们与解码请求一起批处理。|
| `free_cache_engine`| `actor_rollout_ref.rollout.free_cache_engine`  |在部署生成阶段之后卸载 KVCache，默认值为 True。|
| `max_model_len` | `actor_rollout_ref.rollout.max_model_len` | 模型能够处理的最大序列长度。它限制了单个输入序列的最大长度 |
| `tp_size`|  `actor_rollout_ref.rollout.tensor_model_parallel_size * data_parallel_size`|TP并行度|
| `dp_size`| `actor_rollout_ref.rollout.data_parallel_size`|DP并行度|
| `ep_size`| `actor_rollout_ref.rollout.expert_parallel_size`|EP并行度|
| `node_rank`| `无，根据实际实例和卡数自动计算` |实例中的节点排序|
| `load_format`|  `actor_rollout_ref.rollout.load_format` |要加载的模型权重格式|
| `disable_log_stats`|  `actor_rollout_ref.rollout.disable_log_stats`|记录抢占请求的累积数量 |
| `nnodes `|  `无，根据实际实例和卡数自动计算` | 每个实例包含的节点数量` |
| `trust_remote_code`| `actor_rollout_ref.model.trust_remote_code`|是否允许在 Hub 上定义自定义模型，并将其写入自己的建模文件中|
| `max_num_seqs` | `actor_rollout_ref.rollout.max_num_seqs` |正在运行的请求的最大数量|
| `max_num_batched_tokens`| `actor_rollout_ref.rollout.max_num_batched_tokens` |在一次批处理（batch）中可以处理的最大总Token数|
| `skip_tokenizer_init`| `actor_rollout_ref.rollout.skip_tokenizer_init` |跳过初始化分词器并将 input_ids 传递到推理请求中|
| `enable_prefix_caching` | `actor_rollout_ref.rollout.enable_prefix_caching`|`用于启用自动前缀缓存` |
| `quantization`| `actor_rollout_ref.rollout.quantization，默认为None`|`量化方法`|
| `enforce_eager`|`actor_rollout_ref.rollout.enforce_eager`|标志用于强制使用PyTorch的eager执行模式，而非默认的图执行模式|

### 2. sglang:

对于sglang推理后端，昇腾通过直接向sglang社区进行持续建设与维护来支持相关功能。
此外在verl中使用sglang还涉及以下组件, 我们在[quick start](https://github.com/verl-project/verl/blob/main/docs/ascend_tutorial/ascend_sglang_quick_start.rst)中提供详细说明与一键安装脚本。

| 组件| 描述|
| --- | --- |
| [sgl_kernel_npu](https://github.com/sgl-project/sgl-kernel-npu/blob/main/python/sgl_kernel_npu/README.md) | Ascend NPU  SGL 优化推理内核集合，包括注意力机制、归一化、激活函数、LoRA 适配器等。 |
| [deepep](https://github.com/sgl-project/sgl-kernel-npu/blob/main/python/deep_ep/README.md) |  DeepEP的 Ascend 实现，为MoE模型提供高度优化的专家并行 (EP) 通信内核 |

##### 参数特性支持

verl中通过rollout config管理推理后端参数使能，包含通用参数和engine_kwargs自定义传参。
以下列举在verl中常见设置的sglang特性参数，更多参数介绍请参考 [sglang社区NPU特性支持](https://docs.sglang.io/platforms/ascend_npu_support_features.html)

| sglang参数| verl对应通用参数 | 简介|
| --- | --- | --- |
| model_path | actor_rollout_ref.model.path|模型权重文件的路径|
| mem_fraction_static| actor_rollout_ref.rollout.gpu_memory_utilization |用于静态分配（模型权重和键值缓存内存池）的内存比例|
| disable_cuda_graph| actor_rollout_ref.rollout.enforce_eager|禁用图模式，verl默认为False|
| enable_memory_saver| 无，verl中默认设置为True | 允许使用 release_memory_occupation 和 resume_memory_occupation 来节省内存
| base_gpu_id| 无，根据实际实例和卡数自动计算  |用于分配每个实例上计算卡资源时的的初始ID
| gpu_id_step| 无，默认设置为1| 使用的连续计算卡ID 之间的差值
| tp_size|  actor_rollout_ref.rollout.tensor_model_parallel_size * data_parallel_size|TP并行度|
| dp_size| actor_rollout_ref.rollout.data_parallel_size|DP并行度|
| ep_size| actor_rollout_ref.rollout.expert_parallel_size|EP并行度|
| node_rank| 无，根据实际实例和卡数自动计算 |实例中的节点排序|
| load_format|  actor_rollout_ref.rollout.load_format|要加载的模型权重格式|
| dist_init_addr|  无，自动计算|用于初始化分布式后端的主机地址|
| nnodes| 无，根据实际实例和卡数自动计算|每个实例包含的节点数量|
| trust_remote_code| actor_rollout_ref.model.trust_remote_code|是否允许在 Hub 上定义自定义模型，并将其写入自己的建模文件中|
| max_running_requests| actor_rollout_ref.rollout.max_num_seqs |正在运行的请求的最大数量|
| log_level| 无，默认设置为error |日志记录器的日志级别|
| skip_tokenizer_init| actor_rollout_ref.rollout.skip_tokenizer_init |跳过初始化分词器并将 input_ids 传递到推理请求中|
| skip_server_warmup| 无，默认设置为True |跳过预热|
| quantization| actor_rollout_ref.rollout.quantization，默认为None|量化方法|
| attention_backend|actor_rollout_ref.rollout.engine_kwargs.sglang.attention_backend|attention内核,NPU应该设置为ascend|

---

## 训练后端

### 1. FSDP

昇腾通过torch_npu提供FSDP相关支持能力，当前pytorch api支持度参照[版本说明](https://www.hiascend.com/document/detail/zh/Pytorch/730/apiref/PyTorchNativeapi/docs/zh/native_apis/pytorch_2-7-1/torch-distributed-fsdp.md)。

#### FSDP1
##### 参数特性支持
| verl参数 | 简介|
| --- | --- |
| `actor_rollout_ref.actor.fsdp_config.param_offload` |是否卸载模型权重到CPU，默认值为False|
| `actor_rollout_ref.actor.fsdp_config.optimizer_offload` |是否卸载优化器状态到CPU，默认值为False|
| `actor_rollout_ref.actor.fsdp_config.reshard_after_forward` |控制前向计算后的参数行为，平衡内存与通信。默认值为True：前向后重新分片参数，反向时重新全收集|
| `actor_rollout_ref.actor.fsdp_config.fsdp_size` | 每个FSDP分片组中的NPU数量；默认值-1表示自动。|
| `actor_rollout_ref.actor.fsdp_config.forward_prefetch`  |在前向计算完成前预取下一次前向传播的 all-gather，仅用于FSDP1，默认值为False|
| `actor_rollout_ref.actor.fsdp_config.use_orig_params` | FSDP是否会使用module的原始参数来初始化，仅用于FSDP1，默认值为False|
| `actor_rollout_ref.actor.ulysses_sequence_parallel_size`|Ulysses序列并行大小|
| `actor_rollout_ref.actor.entropy_from_logits_with_chunking`|通过分块计算熵以减少显存峰值，默认值为False|
| `actor_rollout_ref.actor.fsdp_config.entropy_checkpointing`|在训练时对熵计算启用重计算,降低显存峰值，默认值为False|
| `actor_rollout_ref.actor.fsdp_config.forward_only` |是否只进行前向计算，默认值为False|

#### FSDP2
##### 参数特性支持
| verl参数 | 简介|
| --- | --- |
| `actor_rollout_ref.actor.fsdp_config.param_offload` |是否卸载模型权重到CPU，默认值为False|
| `actor_rollout_ref.actor.fsdp_config.optimizer_offload` |是否卸载优化器状态到CPU，默认值为False|
| `actor_rollout_ref.actor.fsdp_config.reshard_after_forward` |控制前向计算后的参数行为，平衡内存与通信。默认值为True：前向后重新分片参数，反向时重新全收集|
| `actor_rollout_ref.actor.fsdp_config.fsdp_size` | 每个FSDP分片组中的NPU数量；默认值-1表示自动。|
| `actor_rollout_ref.actor.ulysses_sequence_parallel_size`|Ulysses序列并行大小|
| `actor_rollout_ref.actor.entropy_from_logits_with_chunking`|通过分块计算熵以减少显存峰值，默认值为False|
| `actor_rollout_ref.actor.fsdp_config.entropy_checkpointing`|在训练时对熵计算启用重计算,降低显存峰值，默认值为False|
| `actor_rollout_ref.actor.fsdp_config.forward_only` |是否只进行前向计算，默认值为False|



### 2. Megatron

Megatron 是 NVIDIA 推出的一个专注于模型并行的训练框架仓库。如果一个仓库（例如 Verl）的训练后端使用了 Megatron，同时又希望在 NPU 上运行该仓库，那么就需要额外安装 MindSpeed 来提供底层支持。下文将介绍 MindSpeed 是如何实现无感替换 Megatron 中的关键组件，从而使其能够适配 NPU 的。

MindSpeed 底层的替换原理采用了 Monkey Patch 技术

* MindSpeed Moneky Patch框架

在verl里面通过`from mindspeed.megatron_adaptor import repatch  `触发patch，调用栈如下：

~~~
from mindspeed.megatron_adaptor import repatch
├── 执行 megatron_adaptor.py 模块导入
├── 导入 features_manager 模块
├── 执行 mindspeed/features_manager/__init__.py  
├── @AutoExecuteFunction 装饰器触发
├── patch_features() 自动执行
└── 进行`apply_features_pre_patches`和`apply_features_patches`操作
~~~

`Patch`类是整个patch系统的核心，实现了函数/类的动态替换

~~~python
class Patch
~~~

`parse_path`方法实现了动态模块导入和创建

~~~python
def parse_path(module_path, function_name, create_dummy)
~~~

patch系统支持多层装饰器叠加

~~~
def apply_patch(self):  
    final_patch_func = self.orig_func  
    if self.patch_func is not None:  
        final_patch_func = self.patch_func  

    # 应用所有装饰器  
    for wrapper in self.wrappers:  
        final_patch_func = wrapper(final_patch_func)
~~~

* MindSpeedPatchesManager类

`MindSpeedPatchesManager`作为全局单例管理所有patch

~~~python
class MindSpeedPatchesManager:  
    patches_info: Dict[str, Patch] = {}
~~~

* Feature集成模式

各个Feature通过继承`MindSpeedFeature`基类集成patch系统

~~~python
class MindSpeedFeature:
    """Base class for mindspeed features."""

    def __init__(self, feature_name: str, optimization_level: int = 2):
        self.feature_name = feature_name.lower().strip().replace('-', '_')
        self.optimization_level = optimization_level
        self.default_patches = self.optimization_level == 0

    def is_need_apply(self, args):
        """Check the feature is need to apply."""
        return (self.optimization_level <= args.optimization_level and getattr(args, self.feature_name, None)) \
            or self.default_patches

    def register_args(self, parser: ArgumentParser):
        """Register cli arguments to enable the feature."""
        pass

    def pre_validate_args(self, args: Namespace):
        """Validate the arguments of mindspeed before megatron args validation
        and store some arguments of the mindspeed temporarily,
        incase that megatron validate faile.
        for example:
            ```python
            origin_context_parallel_size = args.context_parallel_size
            args.context_parallel_size = 1
            ```
        """
        pass

    def validate_args(self, args: Namespace):
        """Restore the arguments of the mindspeed.

        for example:
        ```python
        args.context_parallel_size = origin_context_parallel_size
        ```
        """
        pass

    def post_validate_args(self, args: Namespace):
        """validate mindspeed arguments after megatron arguments validation."""
        pass

    def pre_register_patches(self, patch_manager: MindSpeedPatchesManager, args: Namespace):
        """Register all patch functions before import megatron"""
        pass

    def register_patches(self, patch_manager: MindSpeedPatchesManager, args: Namespace):
        """Register all patch functions the feature is related."""
        pass

    def incompatible_check(self, global_args, check_args):
        """Register all incompatible functions the feature is related."""
        if getattr(global_args, self.feature_name, None) and getattr(global_args, check_args, None):
            raise AssertionError('{} and {} are incompatible.'.format(self.feature_name, check_args))

    def dependency_check(self, global_args, check_args):
        """Register all dependency functions the feature is related."""
        if getattr(global_args, self.feature_name, None) and not getattr(global_args, check_args, None):
            raise AssertionError('{} requires {}.'.format(self.feature_name, check_args))

    @staticmethod
    def add_parser_argument_choices_value(parser, argument_name, new_choice):
        """Add a new choice value to the existing choices of a parser argument."""
        for action in parser._actions:
            exist_arg = isinstance(action, argparse.Action) and argument_name in action.option_strings
            if exist_arg and action.choices is not None and new_choice not in action.choices:
                action.choices.append(new_choice)
~~~

##### 参数特性支持
| verl参数 | 简介|
| --- | --- |
| `actor_rollout_ref.actor.megatron.optimizer_offload` |是否卸载模型优化器到CPU，默认值为False|
| `actor_rollout_ref.actor.megatron.use_mbridge` |是否使用mbridge进行权重转换|
| `actor_rollout_ref.actor.megatron.param_offload` |是否卸载模型权重到CPU，默认值为False|
| `actor_rollout_ref.actor.megatron.tensor_model_parallel_size` | 张量并行大小；默认值为1。|
| `actor_rollout_ref.actor.megatron.pipeline_model_parallel_size`  |流水并行大小，默认值为1|
| `actor_rollout_ref.actor.megatron.expert_model_parallel_size` | 专家并行大小，默认值为1|
| `actor_rollout_ref.actor.megatron.expert_tensor_parallel_size`|TP拓展EP大小，默认值为null|
| `actor_rollout_ref.actor.context_parallel_size`|序列并行大小，默认值为False|
| `actor_rollout_ref.actor.megatron.override_transformer_config.deallocate_pipeline_outputs`|张量在发送到下一个pp stage后,输出数据被释放，降低显存峰值，默认值为False|
| `actor_rollout_ref.actor.megatron.override_transformer_config.persist_layer_norm` |是否使用持久化 LayerNorm，默认值为False|
| `actor_rollout_ref.actor.megatron.override_transformer_config.moe_grouped_gemm` |是否使用持Group GEMM，默认值为False|
| `actor_rollout_ref.actor.megatron.override_transformer_config.moe_router_dtype` |用于路由和专家输出加权平均的数据类型。使用 fp32 或 fp64 可以提高稳定性，尤其是在专家数量较多时，默认值为fp32|
| `actor_rollout_ref.actor.megatron.override_transformer_config.account_for_loss_in_pipeline_split` |如果设置为 True，在流水线并行的划分和放置策略中，loss 层会被视为一个标准的 Transformer 层来处理。默认为False。|
| `actor_rollout_ref.actor.megatron.override_transformer_config.account_for_embedding_in_pipeline_split` |如果设置为 True，在流水线并行的划分和放置策略中，输入embedding 层会被视为一个标准的 Transformer 层来处理。默认为False。|
| `actor_rollout_ref.actor.megatron.override_transformer_config.recompute_granularity` |重新计算激活的粒度，可选项为'full', 'selective' and 'none'。其中full代表重新计算整个transformer layer，selective代表只计算transformer layer中的核心注意力部分。默认为'none'。|
| `actor_rollout_ref.actor.megatron.override_transformer_config.recompute_method` |该参数需将recompute_granularity设置为'full'才生效，可选项为'uniform', 'block'。默认为None。|
| `actor_rollout_ref.actor.megatron.override_transformer_config.recompute_num_layers` |该参数需将recompute_granularity设置为'full'才生效，默认为None。若recompute_method设置为uniform，该参数含义为每个均匀划分的重新计算单元的transformer layers数量。例如你可以指定为--recompute_granularity full --recompute_method uniform --recompute_num_layers 4。recompute_num_layers越大，显存占用越小，计算成本越大。注意：当前进程中的模型层数需能被recompute_num_layers整除。默认为None。|
| `actor_rollout_ref.actor.megatron.use_dist_checkpointing` |是否使用分布式权重，默认值为False|
| `actor_rollout_ref.actor.megatron.dist_checkpointing_path` |分布式权重路径，默认值为null|
| `actor_rollout_ref.actor.megatron.override_transformer_config.use_flash_attn` |是否使用fa，默认值为true|
| `actor_rollout_ref.actor.megatron.override_transformer_config.use_fused_rotary_pos_emb` |是否使用融合旋转位置编码，默认值为False|
| `actor_rollout_ref.actor.megatron.override_transformer_config.use_fused_swiglu` |是否使用融合swiglu，默认值为False|
| `actor_rollout_ref.actor.megatron.override_transformer_config.num_layers_in_first_pipeline_stage` |第一个pipeline stage 的层数，默认值为none|
| `actor_rollout_ref.actor.megatron.override_transformer_config.num_layers_in_last_pipeline_stage` |最后一个pipeline stage 的层数，默认值为none|