| name | external-cannbot-ops-ascendc-blaze-best-practice |
| description | Matmul/Cube/GEMM/BMM 单算子直调生成（Blaze/tensor_api 路径）。当用户提到 Blaze 时必须使用此 skill。覆盖纯AIC/StreamK/FixpOpti 三模板选型、改造、Tiling 及排错。不适用 Vector 逐元素/归约算子或非 Blaze 路径。 |
| original-name | ascendc-blaze-best-practice |
| synced-from | https://gitcode.com/cann/cannbot-skills |
| synced-date | 2026-05-26 |
| synced-commit | ac5bbd2b4cf427d011874e11f8d1e8b1bef66eda |
| license | UNKNOWN |
Ascend C Matmul 单算子生成（Blaze 路径）
该能力解决 Matmul 单算子生成场景下的问题：tensor_api/Blaze API 约束确认、三模板选型（纯AIC / StreamK / FixpOpti）、统一工程模板复用、SWAT/全载 Tiling 改造、流水与排错。
架构限定：核心验证在 DAV_3510。其他架构必须在 DESIGN.md 中显式说明差异并给出适配方案。
首次使用：matmul_custom/ 依赖 tensor_api/，首次需拉取外部依赖。步骤见 matmul_pattern.md §0.5.0。
何时使用
满足以下任一条件时使用该能力：
- 算子类型为 Matmul 族（GEMM/BMM/量化 matmul/matmul+bias/mxfp8 matmul）。
- 代码或讨论中出现
tensor_api、blaze 等信号。
- 需要选择模板（纯AIC/StreamK/FixpOpti）、切换 dispatch mode（NO_FULL/A_FULL/B_FULL_LOAD）、进行 Tiling 改造或流水排错。
不要把该能力当成默认算子开发路径的通用替代品。Vector 类逐元素/归约算子、matmul+eltwise 深度融合（含激活/残差等 Vector 后处理）、matmul+softmax 等不在本 skill 模板直接覆盖范围内；这些场景使用本 skill 的 FixpOpti 模板做 Cube 段，epilogue 部分需自行扩展。
三模板速览
| 模板 | 典型场景 | 交付状态 |
|---|
| 纯AIC | 通用场景（默认） | 已交付 |
| StreamK | MN 欠并行 + 长 K（≥4096） | 设计文档 |
| FixpOpti | AIC/AIV 流水重叠、可定制 epilogue | 已交付 |
三模板共享同一基底 references/matmul_custom/（common/、tiling/、scheduler/、utils/）。
FixpOpti 专用文件（matmul_fixpopti.cpp、matmul_kernel_fused.h、epilogue/）也在该目录中。
详细对比（执行模式、调度器、同步机制、Workspace、ASCII 数据流图、决策树）见 matmul_pattern.md §10，此处不重复。
按角色/阶段查阅
阅读顺序：先速览 tensor_api_user_guide.md 了解 API → matmul_pattern.md §10 选模板 → 纯AIC 路径继续 §0 选 mode → §0.5 复制+改造 → 共享基础 §1–§9 + 专属深度文档。
| 阶段/角色 | 主文档 | 辅助 / 深度 |
|---|
| 方案决策（Architect） | matmul_pattern.md §10 三模板选择 + §0 模式总览 | tensor_api_user_guide.md（API 速查） |
| 设计（Architect） | 选定模板后进入深度文档：
- 纯AIC：matmul_basic.md / matmul_full_load.md
- StreamK：matmul_streamk.md
- FixpOpti：matmul_fixpopti.md | matmul_pattern.md §1–§9 共享基础 |
| 实现（Developer） | 统一从 references/matmul_custom/ 基底出发：
纯AIC → matmul_custom.cpp（[MODIFY] N/C/A）
FixpOpti → matmul_fixpopti.cpp（[MODIFY] N/C/A/E），按 matmul_fixpopti.md §3 改造 | matmul_fixpopti.md（改造食谱） |
| 审查（Reviewer） | matmul_pattern.md §8 排障速查 | 对应模板深度文档的「常见陷阱」表 |
| 修复调试 | matmul_pattern.md §8（编译期 / 精度 / 跑通自检） | matmul_fixpopti.md §6 陷阱表 |
约束
- 架构验证范围：DAV_3510。其他架构因
tensor_api 依赖和 L1/L0 容量差异，可能不兼容。
- 全载交付状态：
A_FULL_LOAD_MODE 已落地（matmul_block_mmad_a_full_load.h + MatmulTilingAFullLoad，3 行 diff 切换）。B_FULL_LOAD_MODE 仅有设计草案（见 matmul_full_load.md §3.2 / §4.2 / §4.3），仓库中无 B_FULL_LOAD_MODE 常量、MatmulMultiBlockPolicy<B_FULL_LOAD_MODE> 特化、MatmulSwatScheduler<B_FULL_LOAD_MODE> selector、MatmulTilingBFullLoad 类、matmul_block_mmad_b_full_load.h 头文件——使用前必须按对称设计自行镜像补齐，不能套用 matmul_pattern.md §0.5.3 的切换 diff（B 全载段已替换为告警 NOTE）。
- 模板复制起手：纯AIC 从
references/matmul_custom/matmul_custom.cpp 入手，FixpOpti 从 references/matmul_custom/matmul_fixpopti.cpp 入手；两条路径共享 references/matmul_custom/ 下的 common/、tiling/、scheduler/、utils/。均按 [MODIFY] 标记改造。FixpOpti 额外需要：(1) 替换启动器 matmul_custom.cpp→matmul_fixpopti.cpp，(2) BlockMmad 的 CopyL0C2GM 改为 CopyL0C2UB+SPLIT_M Trait（见 matmul_fixpopti.md §3.5），(3) 新增 matmul_kernel_fused.h 和 epilogue 文件。比纯AIC 多一档 [MODIFY] E 用于自定义 Epilogue。
- API 签名不猜测：
AscendC::Te:: 系列接口有大量重载和模板特化。查阅 references/tensor_api_user_guide.md 或官方文档。
- 伪代码不等于可编译实现：设计文档中的代码片段为说明概念而简化。写代码时回到对应模板工程——细节已处理好。
- mode 和模板选择说明依据：在 DESIGN.md 中写清楚为何选这个 mode/模板。
与 CANNBot 集成
| CANNBot 阶段 | 调用方 | 加载方式 |
|---|
| Step 2 设计 | Architect Subagent | 当用户需求路径判定为「tensor_api / CUTLASS 风格 API」时显式加载本 skill |
| Step 3 开发 | Developer Subagent | 按设计选定模板，复用模板工程 |
| Step 4 审查 | Reviewer Subagent | 用 matmul_pattern.md §8 排障速查交叉验证 |
