CAM算子替换专家技能

技能概述

本技能专注于将基于DeepEP的Mixture of Experts (MoE) 代码迁移至昇腾（Ascend）NPU环境。它能自动识别DeepEP dispatch & combine算子，**严格基于代码的实际运行参数（而非默认值）**校验CAM算子约束。

核心原则：

• 思维链先行：在执行任何代码修改前，必须先输出分析过程和自检结果。严禁直接生成代码。
• 原地修改：默认直接在用户指定的原文件上修改，严禁创建新文件（除非用户显式要求）。
• 动态值优先：判断约束时，必须追踪参数的实际运行时值，严禁直接使用代码中的硬编码默认值。
• 强制交互：在算子模式选择（如A3普通 vs Shmem）和功能支持度处理上，必须询问用户，严禁AI自作主张。

工作流程

1. 代码扫描与依赖分析

1.1 目标检测

• DeepEP识别：扫描代码中是否存在import deep_ep及dispatch/combine相关调用。
• MOE/EP模式识别：确认代码是否涉及Mixture of Experts或Expert Parallelism逻辑。
• 无匹配处理：若未检测到相关代码，直接告知用户并终止流程。

1.2 依赖与上下文分析

• 导入分析：提取所有import语句，识别本地模块依赖。
• 通信域扫描：检查是否存在dist.init_process_group、backend='nccl'、torch.cuda.set_device等特征代码。
• 外部依赖检查：识别是否调用了外部初始化函数（如utils.init_dist），需同步分析这些函数的实现。

🛑 阶段 1 阻断检查（必须显式输出） 在生成任何回复前，请先输出以下内容：

[阶段 1 自检]
- DeepEP 代码识别：[是/否]
- 本地依赖文件列表：[列出文件]
- 状态：[通过/失败]

若“DeepEP 代码识别”为否，直接终止。若为是，继续下一阶段。

2. 环境与策略决策

注意：此阶段必须与用户交互，不得跳过。

2.1 环境选择

向用户展示以下选项，确定目标运行环境：

• 选项1：基于当前环境自动检测（尝试执行npu-smi info，根据设备型号判断是A2环境或A3环境）。
• 选项2：指定目标环境（用户手动指定A2环境或A3环境，用于交叉编译或代码预研场景）。

2.2 参数值解析与约束校验

重要原则：代码中的默认值（Default Value）≠ 实际运行值（Runtime Value）

在执行替换前，必须对约束条件涉及的参数进行实际值溯源：

1. 参数溯源：

   • 检查参数是否通过argparse、config.yaml或命令行传入。
   • 严禁使用 parser.add_argument(..., default=XXX) 中的 XXX 作为判断依据。
   • 必须假设代码中的默认值可能不是实际运行值。

2. 交互确认机制：

   • 对于关键约束参数（如 hidden_size, top_k, expert_num 等），如果无法从代码逻辑中100%确定其运行时赋值，必须向用户发起询问：

     “检测到参数 [参数名] 在代码中的默认值为 [默认值]，但这可能不是实际运行值。请确认实际运行时的数值是多少？以便准确判断是否满足CAM算子约束。”

3. 约束校验逻辑：

   • 情况A（值确定且满足）：用户确认实际值，且满足CAM算子约束 -> 进入算子模式选择。
   • 情况B（值确定但不满足）：用户确认实际值，不满足约束 -> 停止替换，告知用户不支持。
   • 情况C（值不确定）：用户未提供 -> 暂停替换，标记该处需人工确认。

2.3 算子模式选择

在确认参数值满足约束后，根据目标环境确定具体算子模式：

• A2环境：仅使用 CAM A2 算子。
• A3环境：
  • 检查代码是否同时满足 普通A3算子、 Shmem算子 和fused deep moe算子的约束条件。
  • 注意fused deep moe算子替换有严格的约束范式，请仔细阅读说明文档，检查是否满足范式，需要基于dispatch & combine函数去查找调用链，查看最终调用方是否满足约束范式
  • 阻断规则：如果有多个都满足，AI必须立即停止自动流程，并向用户展示选择题，等待用户回复，以三个条件都满足的场景为例，可以展示如下选项

    检测到当前代码同时满足多组算子的约束条件，请做出选择：()

    • 选项1（普通A3）：参数配置简单，无需额外共享内存初始化。
    • 选项2（Shmem A3）：性能更优，但需满足特定约束及初始化。
    • 选项2（fused deep moe算子）：性能最优，将通信计算过程融合为一个大算子。 请回复选项继续。

  • 如果仅满足其一：自动选择该模式并告知用户。

2.4 功能支持度分析与策略确认

在执行替换前，必须对比DeepEP原功能与CAM算子支持范围，并输出分析报告。

1. 生成支持度报告：

   • 分析代码中使用了哪些DeepEP特性, 当前cam对deep ep特性支持度如下 | DeepEP特性 | CAM支持情况 | 详细说明 | | :--- | :--- | :--- | | 低延迟模式 | 不支持 | CAM 不支持低延迟模式。若检测到 low_latency_mode=True 或相关逻辑，必须标记为不兼容。警告用户将使用非低时延模式替换 | | 精细化调优 | 不支持 | CAM 屏蔽了底层性能参数配置。若代码中显式传入了 Config 对象或 num_sms, buffer_size 等调优参数，需自动忽略这些参数并警告用户，改用 CAM 默认配置。| | 异步控制流 | 不支持 | CAM 不支持 Event 对象作为返回值。若检测到 event = dispatch(...) 或 event.wait()，移除所有 Event 相关的变量定义和等待逻辑。警告用户：通信与计算的重叠控制将被移除，算子将按默认同步/异步策略执行。|
   • 列出 支持替换的部分 和 不支持替换的部分。

2. 用户确认策略：

   • 如果存在 不支持替换的部分，必须向用户展示以下选项，等待用户回复： 检测到CAM算子对当前代码的支持情况如下：
     • 支持替换的部分：[列出具体功能/代码行]
     • 不支持替换的部分：[列出具体功能/代码行] 请选择处理策略：
     • 选项A：停止替换，不做任何修改。
     • 选项B：替换支持的部分，保留不支持的功能代码不变（混合模式）。
     • 选项C：替换支持的部分，删除不支持的功能代码。

🛑 阶段 2 阻断检查（必须显式输出） 在进入代码生成前，请输出：

[阶段 2 自检]
- 目标环境确认：[A2/A3]
- 关键参数实际值确认：[列出参数及值，严禁使用默认值]
- A3模式决策：[A2算子替换不涉及/普通A3/Shmem]
- 功能支持度报告已展示：[是/否]
- 用户策略确认：[保留/删除/混合]
- 状态：[通过/失败 - 若失败请停止,针对不满足项重新执行阶段2]

3. 执行替换与转换

3.1 通信域转换（NCCL -> HCCL）

执行范围：目标文件及所有识别到的本地依赖文件。

3.2 算子接口替换

根据用户确认的CAM算子模式（A2/A3/Shmem）和策略（保留/删除），执行以下操作：

• 导入替换：将import deep_ep替换为cam对应库,注意cam库依赖torch_npu,必须先import torch_npu然后import umdk_cam_op_lib。
• 接口映射：将deep ep dispatch & combine等相关算子映射为对应的CAM接口调用。
• 参数调整：根据CAM算子文档调整参数顺序和命名。
• 代码处理：
  • 若用户选择 保留：保留原DeepEP代码块，添加注释 # CAM Migration: DeepEP code retained due to unsupported feature。
  • 若用户选择 删除：删除不支持的功能代码。
• 冗余清理：删除原DeepEP特有但CAM不需要的参数构造代码。 资源释放 通信域释放和shmem的释放(aclshmem_free和aclshmem_finialize)必须在算子执行结束，即torch.npu.synchronize()等同步操作之后

🛑 阶段 3 自检 在结束前，请简要确认：

• 所有 nccl 已替换为 hccl
• 所有 cuda 已替换为 npu
• 接口入参形状和类型和接口文档要保持一致
• 如果使用shmem，需要保证shmem资源释放(aclshmem_free和aclshmem_finialize)要在算子执行结束之后，即torch.npu.synchronize()等同步操作之后
• 状态：[通过/失败 - 若失败请停止,针对不满足项重新执行阶段3]

4. 验证与收尾

• 语法检查：确保修改后的Python代码语法正确。
• 用户报告：
  • 列出修改的文件清单。
  • 关键提示：列出所有依赖用户运行时配置的参数。
  • 提示必须设置的环境变量。

参考文档库

在执行替换时，必须严格查阅以下文档：

1. 通信转换：references/nccl_to_hccl_converter.md
2. A2算子：references/cam_dispatch_and_combine_a2.md
3. A3算子：references/cam_dispatch_and_combine_a3.md
4. Shmem算子：references/cam_dispatch_and_combine_shmem.md
5. fused deep moe算子：references/cam_fused_deep_moe.md

检查清单

在输出最终结果前，自我核对：

• 是否已确认目标环境（A2/A3）？
• 是否已严格区分默认值与实际运行值？（严禁使用argparse default值做约束判断）
• A3场景下，若普通和Shmem模式均满足约束，是否已强制抛出选择题并暂停？（严禁自动选择）
• 是否已输出功能支持度报告，并询问用户处理策略？（严禁擅自删除代码）
• 是否已将所有nccl替换为hccl？
• 是否已将所有cuda相关调用替换为npu？
• 是否在原文件上进行了修改？