# Deepep To Cam Converter

> 识别代码中可替换为CAM算子的DeepEP算子，基于实际运行参数校验约束，自动完成通信域转换（NCCL->HCCL）、设备适配（CUDA->NPU）及算子替换。

- Skill: `xiaoluolyg/deepep-to-cam-converter` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add xiaoluolyg/deepep-to-cam-converter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xiaoluolyg/deepep-to-cam-converter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: xiaoluolyg (https://skillmd.com/u/xiaoluolyg)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xiaoluolyg/deepep-to-cam-converter

---


# 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 阻断检查（必须显式输出）**
> 在生成任何回复前，请先输出以下内容：
> ```text
> [阶段 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 阻断检查（必须显式输出）**
> 在进入代码生成前，请输出：
> ```text
> [阶段 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 自检**
> 在结束前，请简要确认：
> - [ ] 所有 `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`？
- [ ] 是否在原文件上进行了修改？