| name | deepep-to-cam-converter |
| description | 识别代码中可替换为CAM算子的DeepEP算子，基于实际运行参数校验约束，自动完成通信域转换（NCCL->HCCL）、设备适配（CUDA->NPU）及算子替换。 |
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）
在执行替换前，必须对约束条件涉及的参数进行实际值溯源：
-
参数溯源：
- 检查参数是否通过
argparse、config.yaml或命令行传入。
- 严禁使用
parser.add_argument(..., default=XXX) 中的 XXX 作为判断依据。
- 必须假设代码中的默认值可能不是实际运行值。
-
交互确认机制：
- 对于关键约束参数（如 hidden_size, top_k, expert_num 等），如果无法从代码逻辑中100%确定其运行时赋值，必须向用户发起询问：
“检测到参数 [参数名] 在代码中的默认值为 [默认值]，但这可能不是实际运行值。请确认实际运行时的数值是多少？以便准确判断是否满足CAM算子约束。”
-
约束校验逻辑：
- 情况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算子支持范围，并输出分析报告。
-
生成支持度报告：
- 分析代码中使用了哪些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 相关的变量定义和等待逻辑。警告用户：通信与计算的重叠控制将被移除，算子将按默认同步/异步策略执行。|
- 列出 支持替换的部分 和 不支持替换的部分。
-
用户确认策略：
- 如果存在 不支持替换的部分，必须向用户展示以下选项，等待用户回复：
检测到CAM算子对当前代码的支持情况如下：
- 支持替换的部分：[列出具体功能/代码行]
- 不支持替换的部分：[列出具体功能/代码行]
请选择处理策略：
- 选项A：停止替换，不做任何修改。
- 选项B：替换支持的部分，保留不支持的功能代码不变（混合模式）。
- 选项C：替换支持的部分，删除不支持的功能代码。
🛑 阶段 2 阻断检查（必须显式输出）
在进入代码生成前，请输出：
[阶段 2 自检]
- 目标环境确认：[A2/A3]
- 关键参数实际值确认：[列出参数及值，严禁使用默认值]
- A3模式决策：[A2算子替换不涉及/普通A3/Shmem]
- 功能支持度报告已展示：[是/否]
- 用户策略确认：[保留/删除/混合]
- 状态：[通过/失败 - 若失败请停止,针对不满足项重新执行阶段2]
3. 执行替换与转换
3.1 通信域转换（NCCL -> HCCL）
执行范围：目标文件及所有识别到的本地依赖文件。
| 原代码特征 (CUDA/NCCL) | 替换后代码 (NPU/HCCL) | 备注 |
|---|
backend='nccl' | backend='hccl' | 核心通信后端 |
torch.cuda.set_device(x) | torch.npu.set_device(x) | 设备绑定 |
torch.set_default_device('cuda') | torch.set_default_device('npu') | 默认设备 |
torch.device('cuda:0') | torch.device('npu:0') | 设备对象 |
tensor.cuda() | tensor.npu() | Tensor迁移 |
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 自检
在结束前，请简要确认：
4. 验证与收尾
- 语法检查：确保修改后的Python代码语法正确。
- 用户报告：
- 列出修改的文件清单。
- 关键提示：列出所有依赖用户运行时配置的参数。
- 提示必须设置的环境变量。
参考文档库
在执行替换时，必须严格查阅以下文档：
- 通信转换：
references/nccl_to_hccl_converter.md
- A2算子：
references/cam_dispatch_and_combine_a2.md
- A3算子：
references/cam_dispatch_and_combine_a3.md
- Shmem算子：
references/cam_dispatch_and_combine_shmem.md
- fused deep moe算子：
references/cam_fused_deep_moe.md
检查清单
在输出最终结果前，自我核对：
