From 58441729199e003ecfd43bf160856e36aa571aeb Mon Sep 17 00:00:00 2001 From: liuyanwei Date: Mon, 2 Jun 2025 11:06:00 +0800 Subject: [PATCH] supplement moe doc --- .../docs/source_zh_cn/appendix/conf_files.md | 6 + .../source_zh_cn/function/other_features.md | 125 ++++++++++++++++++ 2 files changed, 131 insertions(+) diff --git a/docs/mindformers/docs/source_zh_cn/appendix/conf_files.md b/docs/mindformers/docs/source_zh_cn/appendix/conf_files.md index 96dcd64e21..4c7f234111 100644 --- a/docs/mindformers/docs/source_zh_cn/appendix/conf_files.md +++ b/docs/mindformers/docs/source_zh_cn/appendix/conf_files.md @@ -91,6 +91,12 @@ Context配置主要用于指定[mindspore.set_context](https://www.mindspore.cn/ | moe_config.comp_comm_parallel | 设置是否开启ffn的计算通信并行。默认值：False。 | bool | | moe_config.comp_comm_parallel_degree | 设置ffn计算通信的分割数。数字越大，重叠越多，但会消耗更多内存。此参数仅在comp_com_parallel启用时有效。 | int | | moe_config.moe_shared_expert_overlap | 设置是否开启共享专家和路由专家的计算通信并行。默认值：False。 | bool | +| moe_config.use_gating_sigmoid | 设置MoE中gating的结果使用sigmoid函数进行激活。默认值：False。 | bool | +| moe_config.use_gmm | 设置MoE专家计算是否使用GroupedMatmul。默认值：False。 | bool | +| moe_config.use_fused_ops_permute | 设置是否MoE使用permute，unpermute融合算子进行性能加速，仅在use_gmm=True时生效。 | bool | +| moe_config.enable_deredundency | 设置是否开启去冗余通信，要求专家并行数是每个节点中npu卡数量的整数倍，默认值：False，当use_gmm为True时生效。 | bool | +| moe_config.npu_nums_per_device | 设置每个节点中npu卡的数量，默认值8，当enable_deredundency=True时生效。 | int | +| moe_config.enable_gmm_safe_tokens | 保证每个专家至少分配1个tokens，避免极度负载不均衡情况下，GroupedMatmul计算失败。当use_gmm=True时，建议开启。 | bool | ### 模型训练配置 diff --git a/docs/mindformers/docs/source_zh_cn/function/other_features.md b/docs/mindformers/docs/source_zh_cn/function/other_features.md index 63dac73faf..250c1930f3 100644 --- a/docs/mindformers/docs/source_zh_cn/function/other_features.md +++ b/docs/mindformers/docs/source_zh_cn/function/other_features.md @@ -139,3 +139,128 @@ runner_wrapper: |---------------|-------------------|----------------------------| | use_clip_grad | 控制在训练过程中是否开启梯度裁剪。 | (bool, 可选) - 默认值： `False` 。 | | max_grad_norm | 控制梯度裁剪的最大 norm 值。 | (float, 可选) - 默认值： `1.0` 。 | + +## GroupedMatmul + +### 概述 + +针对MoE单卡多专家计算，存在细碎的专家计算操作与通信，通过Grouped GeMM算子对多专家计算进行合并，提升MoE单卡多专家训练性能。通过调用gmm 融合算子，对多个专家计算进行融合达到加速效果。 + +### 配置与使用 + +#### YAML 参数配置 + +用户在需要MoE开启GroupedMatmul的场景下，只需在配置文件中的 `moe_config` 项下配置 `use_gmm` 项，设置为`True`即可： + +```yaml +# moe_config config +moe_config: + ... + use_gmm: True + ... +``` + +### 常见问题FAQ + +使用gmm融合算子，在负载不均衡的情况下可能会卡上的专家未分配任何token，导致程序报错。报错如下： + +```log +VallueError: For primitive[Reshape]， the accumulate of x_shape must be equal to out_shape, but got x_shape: [const vector]{}, and output_shape: [const vector]{0, hiddensize} +``` + +此时，可以配置enable_gmm_safe_tokens: True, 保证每个专家至少分配1个tokens，避免程序报错。 + +```yaml +# moe_config config +moe_config: + ... + enable_gmm_safe_tokens: True + ... +``` + +## MoE Droprate打印 + +### 概述 + +在使用MoE（Mixture of Experts）容量方案进行模型训练时，为了提高效率和性能，系统可能会对某些token执行drop操作。 +通过启用droprate打印功能，用户可以在训练过程中实时监控这些drop操作的发生率，从而更好地理解模型的行为，并据此调整训练策略。 +此功能允许用户在训练过程中查看每一层的droprate情况。droprate是指在特定层中被drop掉的token的比例。 +通过观察droprate的变化趋势，可以帮助用户评估当前的训练参数设置是否合理，以及模型是否有效地利用了专家资源 + +### 配置与使用 + +#### YAML 参数配置 + +用户要启用droprate打印功能，需在配置文件中的 `moe_config` 项下配置 `callback_moe_droprate` 项，设置为`True`， +在callback部分添加`MoEDropRateCallback`配置项，并设置模型相关参数`expert_num`、`capacity_factor`、`num_layers`、`mtp_depth`。示例： + +```yaml +# moe_config config +moe_config: + ... + callback_moe_droprate: True + ... +# callback config +callback: + ... + - type: MoEDropRateCallback + expert_num: 4 + capacity_factor: 1.5 + num_layers: 8 + mtp_depth: 1 + ... +``` + +#### 主要配置参数介绍 + +| 参数 | 描述 | 取值说明 | +|---------------|-------------------|----------------------------| +| callback_moe_droprate | 是否在callback中打印moe droprate。 | (bool, 可选) - 默认值： `False` 。 | +| expert_num | 专家数量。 | (int, 必选) 。- 默认值： `None`。 | +| capacity_factor | 容量因子。 | (float, 必选) 。- 默认值： `None`。 | +| num_layers | 模型层数。 | (int, 必选) 。- 默认值： `None`。 | +| mtp_depth | mtp层层数。 | (int, 必选) 。- 默认值： `None`。 | + +## rotary_position_embedding融合算子 + +### 概述 + +网络中使用RoPE（Rotary Position Embedding）作为位置编码时，可以启用该融合算子提升整网性能。 +该功能提供RoPE的融合算子实现，提升整网性能。算子的接口可参考： +https://www.mindspore.cn/docs/zh-CN/r2.6.0/api_python/ops/mindspore.ops.rotary_position_embedding.html + +### 配置与使用 + +#### YAML 参数配置 + +用户需要使用rotary_position_embedding融合算子，需在配置文件中的 `model_config` 项下配置 `use_fused_rope` 项，设置为`True`，示例： + +```yaml +# model_config config +model_config: + ... + use_fused_rope: True + ... +``` + +## swiglu融合算子 + +### 概述 + +网络中使用SwigLU作为激活函数时可以启用该融合算子提升整网性能。 +该功能提供swiglu的融合算子实现，提升整网性能。算子的功能可参考： +https://www.mindspore.cn/docs/zh-CN/r2.6.0/api_python/ops/mindspore.ops.swiglu.html + +### 配置与使用 + +#### YAML 参数配置 + +用户需要使用swiglu融合算子，需在配置文件中的 `model_config` 项下配置 `use_fused_swiglu` 项，设置为`True`，示例： + +```yaml +# model_config config +model_config: + ... + use_fused_swiglu: True + ... +``` -- Gitee