描述

关联的Issue

测试

文档更新

类型标签

• 🐛 Bug修复
• ✨ 新特性
• ⚡ 性能优化
• ♻️ 重构
• 🧪 测试
• 📦 构建/CI
• 🔧 配置变更
• 📝 文档更新
• ⬆️ 依赖升级
• 🔒 安全修复
• 🧹 代码清理
• ❓ 其他，请描述：

PR #15295 全量代码检视报告

• PR: https://gitcode.com/cann/ops-transformer/pull/15295
• 检视分支: docs/mc2-a5-nonquant-scales-win
• 检视提交: b8c0ed98f（用户指定 5b5719750，该提交已被 amend 为 b8c0ed98f）
• 检视基线: origin/master
• 变更规模: 12 个文件，+307 / -65
• 检视方式: 按首次检视，重新对照 host tiling、helper 实现和文档公式

一、结论

核心逻辑与 host 侧口径一致，未发现会导致 A5 窗口少算的功能性错误。主要剩余问题集中在测试覆盖、保守预留策略和文档同步，均不阻塞合入，但建议处理。

二、问题与建议

1. [P2] Python helper 新增逻辑没有单元测试

• 文件: mc2/common/torch_extension/moe_distribute_buffer.py
• 变更: 新增 A5 设备判定、world_size/num_moe_expert/local*ep 上限、scales 最大占位、combine 480 对齐、rank offset。
• 风险: 这些分支直接影响 HCCL_BUFFSIZE，缺少测试时后续修改容易回归。
• 建议: 增加 mock get_device_name() 的单测，覆盖 A3/A5、fullmesh_v1/v2、有无 scales、rank offset 边界。

2. [P2] A5 所有场景都按 scales 最大值预留，量化场景会偏大

• 文件: mc2/common/torch_extension/moe_distribute_buffer.py:153-160
• 现象: max_scale_bytes = hidden * 4 对所有 A5 调用生效；host 侧只在 NON_QUANT + scales 时增加该占位。
• 影响: 不会导致越界，但 A5 量化场景会多申请 HCCL buffer。
• 建议: 若这是有意的保守策略，在文档/注释中明确；否则增加 quant_mode/scales 参数区分。

3. [P3] 英文文档未同步

• 文件: mc2/moe_distribute_dispatch_v2/docs/aclnnMoeDistributeDispatchV2_en.md、V3_en、V4_en，以及 combine V2/V3/V4 的 _en.md。
• 现象: 中文文档已补充 480 对齐、fullmesh_v2 变体和 scales 说明，英文文档仍是旧公式。
• 建议: 同步英文文档，或由英文文档维护流程跟进。

4. [P3][历史遗留] Dispatch V2 950 的 commAlg 参数约束仍写不支持

• 文件: mc2/moe_distribute_dispatch_v2/docs/aclnnMoeDistributeDispatchV2.md:500
• 现象: 同文档 950 HCCL 公式已包含 fullmesh_v1/fullmesh_v2，但参数约束仍写“commAlg 当前版本不支持”。
• 说明: 该描述早于本 PR 存在，代码侧 A5 fullmesh_v2 支持可追到 49af78d0a（2026-02-03，MR !1234），不是本 PR 引入。
• 建议: 单独提 PR 修正，避免本 PR 扩大范围。

5. [P3][文档清晰度] Combine 950 的 HCCL 公式使用了 commAlg，但参数约束写不支持

• 文件: mc2/moe_distribute_combine_v2/docs/aclnnMoeDistributeCombineV2.md、V3、V4 的 950 段。
• 现象: HCCL 公式按 dispatch 侧 commAlg 的 fullmesh_v1/v2 展开，但 combine 的 commAlg 参数约束写不支持。
• 说明: combine 本身可能不使用该属性，公式描述的是共享 buffer 的 dispatch 侧需求，但读者容易误解。
• 建议: 在公式处注明“此处的 commAlg 指 dispatch 侧配置”，或单独修正 combine 的参数约束。

三、核对通过项

• A5 非量化 scales：helper 使用 max_scale_bytes = hidden * 4，与 host CalcA5DispatchTokenBytes 的上界一致。
• dispatch token 对齐：fullmesh_v1 用 512、fullmesh_v2 用 480，与 host tokenDataAlign 一致。
• combine 对齐：A5 使用 480，A3 使用 512，与 host combineDataAlign 一致。
• rank offset：helper 增加 world_size * 1024，与 host EP_RANK_OFFSET_STEP=1024 一致。
• A5 上限：world_size≤1024、num_moe_expert≤2048、local*ep≤4096，与 host 常量一致。
• 文档 950 段已补齐 fullmesh_v1/v2 公式，并将 combine 项统一为 480Align512(2 * H)。
• _is_a5_device() 已消除重复判定；注释与常量命名已整理。

四、验证建议

1. 用 mock 设备名的 Python 单测对比 helper 返回值与 host tiling 的最小窗口要求。
2. 覆盖 fullmesh_v1/fullmesh_v2、NON_QUANT + scales、量化无 scales 三类场景。
3. 取 H=7168、较大 world_size 和 local_moe_expert_num 的边界组合，确认 rank offset 和 2MB 对齐没有少算。
4. 修改文档后执行 pre-commit run --files ...。