name	shmem-ops-performance-optim
description	基于 SHMEM 的算子性能优化迭代，固定 5 轮机制优化，每轮输出 Δ% 对比。关键词：基于SHMEM性能优化、调优、optimization、机制优化、性能调优。

SHMEM 算子性能优化

Skill类型：分析推荐型（读性能数据 → 瓶颈分析 → 输出修改意见 → 委托子 skill 执行改动 → 验证 → 决策）。禁止自行修改算子代码或 design.md。

中文写作要求：performance_report.md MUST 使用中文撰写。仅 API 名称、代码片段、指标名等技术术语保留英文原文。

正确性通过、Phase 6 性能采集完成且编排器因 meta.performance_auto_optim: true 进入 Phase 6.5 后执行（false 时本 skill 不得被调用）。固定 5 轮：Round 1~5 均为机制优化轮（每轮一项代码/机制改动 + 可选参数扫描）。即使中途已达标也 MUST 完成全部 5 轮，以充分挖掘优化空间。

performance_report.md 由 shmem-ops-performance-eval 在每轮采集后写入/追加。优化过程中 NEVER 直接编辑该报告——填表由 eval skill 负责，optim skill 只读取。

优化优先级（MUST）

机制优化（流水、分核、同步粒度、engine、overlap）— 默认从 Round 1 起即优先尝试
参数调优（block_dim、chunk_size 等）— 在机制改动后的同一轮内扫描，或机制无法推进时的补充
大小分支 — 禁止作为默认优化手段；仅 unified 路径 profiling 后证明 ≥5% 收益才引入/保留 big_data/large 路径

统一实现原则

原则	说明
默认 single path	一套 kernel 逻辑 + UB 分块，覆盖平台 S/L 档
外层 tile	仅因 `GVA_BUFF_MAX_SIZE` / symm 容量触发的分块循环，可保留
证明后分拆	size 分支须附 Round 对比数据，未达标则合并删除
死代码	`if (0)`、`INT64_MAX` 禁用的 large 路径 MUST 在合并后删除

轮次模型

轮次	性质	内容
Round 1	机制优化轮（默认）	一项代码/机制改动（流水、分核、signal 等）+ 可选参数扫描
Round 2-5	机制优化轮	每轮一项新机制改动，改动后再扫参数找最优

参数 vs 机制的区分：

类别	定义	示例
参数调节	改配置值，不改代码结构	block_dim、chunk_size、TileShape、Swizzle offset/direction、transfer_size、UB buffer 大小
机制改动	改代码逻辑/算法	加 ping-pong double buffer、实现 sender/receiver 分核、barrier→signal/wait、增加流水级数、engine 切换（MTE→SDMA）、通信-计算 overlap

核心工作流

┌──────────────────────────────────────────────────────────────┐
│  OptimStep 1: 瓶颈定位（读 performance_report + design）      │
│  OptimStep 2: 基线锁定（确认全部基线指标）                    │
│  OptimStep 3: 输出修改意见                                    │
│    ├── 设计级改动 → 委托 shmem-ops-design 修订 design.md     │
│    │                 → 跳过 testcase-gen                      │
│    └── 代码级改动 → 委托 shmem-ops-code-gen 修改代码          │
│                      → 委托 shmem-ops-compile-debug 编译      │
│                        （compile-debug 不改代码，失败回 code-gen）│
│                      → 委托 shmem-ops-correctness-eval 正确性 │
│  OptimStep 4: 性能验证（调用 shmem-ops-performance-eval 采集并填入报告）│
│  OptimStep 5: 迭代决策（keep / revert）                       │
│               ↓ < 5 轮 → 回 OptimStep 1（无论是否达标）       │
│  OptimStep 6: 最终确认（检查报告完整性）                      │
└──────────────────────────────────────────────────────────────┘

必读资料

文件	阅读时机	用途
references/optimization-patterns.md	OptimStep 1 定位瓶颈后选择对应优化	通信、流水线、同步、内存、分核优化手段
references/compute-optimization.md	当瓶颈在 compute 部分时	通算融合中 Matmul/Compute 调优
../shmem-ops-performance-eval/references/device-profiling-guide.md	OptimStep 4 性能验证采集 frame 数据	SHMEMI_PROF 打点操作方法
../shmem-ops-performance-eval/references/perf-chat-output-spec.md	OptimStep 4 完成后、OptimStep 6 交付前	每轮聊天自动输出：Round Δ% 表、累计总览、最终对比
../shmem-ops-performance-eval/templates/performance-report.md	OptimStep 1 读取报告、OptimStep 6 最终确认	性能报告模板（由 eval skill 维护）
../shmem-ops-design/references/hardware-architecture.md	OptimStep 1 和每轮参数调优时	昇腾硬件参数速查（核数、带宽）——调参时 NEVER 超出硬件上限
../shmem-ops-compile-debug/references/custom-ops-entrypoints.md	OptimStep 3 委托 compile-debug 编译时	custom-ops 编译入口命令
../shmem-ops-dev/references/shmem-repo-resolution.md	读仓内文件前	定位 `SHMEM_REPO`
../shmem-ops-dev/references/docker-exec-contract.md	用户指定 Docker 时	全部 build/run/perf 必须 docker exec，禁止宿主机裸跑
../shmem-ops-code-gen/SKILL.md	OptimStep 3 委托 code-gen 时	code-gen 入口与输入契约

前置条件

算子已通过正确性验证（shmem-ops-correctness-eval）
design.md 中 meta.performance_required: true 且 meta.performance_auto_optim: true
Phase 6 性能采集已完成且 未达标（由 shmem-ops-dev 编排器门控后调用本 skill）
design.md 中有明确性能目标

达标规则

达标线用于评估结论，NEVER 作为提前停止条件——进入 Phase 6.5 后 MUST 完成全部 5 轮。

情况	达标线（通信算子）
有 baseline（HCCL/已有实现）	kernel_bus_bandwidth_GBps 达标线：默认 ≥ baseline 的 80%
无 baseline，通信算子	kernel_bus_bandwidth_GBps 对应带宽利用率 ≥ 20%
无 baseline，通算融合	达到 design 指标目标

e2e_latency 仅作参考；Round 间性能变化对比 MUST 用 kernel_bus_bandwidth_GBps，NEVER 用 e2e 带宽。

OptimStep 1：瓶颈定位

Round 0（首次）：Round 0 基线数据已由 Phase 6 eval 生成。若 performance_report.md 不存在（异常中断恢复），则调用 eval 补齐 §1-§3。

Round 1+：已有前序轮次的性能报告。

读取 performance_report.md，重点看上一轮最优 step 的 Device Frame Table 和 §5 轮次总览
对比当前瓶颈与前序轮次的变化，确认本轮优化方向

算法级排查（SHMEM/baseline < 50% 时 MUST 执行）

当性能差距极大（与 baseline 相比不到 50%，或无 baseline 但 bus_bandwidth 利用率极低）时，优先检查算法选择本身是否匹配硬件拓扑，再进入细粒度排查。

步骤：

确认硬件拓扑：查阅 hardware-architecture.md §2.4-2.5 确认当前 SoC 的互联拓扑（如 910B3 = 8 卡 full-mesh，每卡 7 条 HCCS 直连）
分析 baseline 算法：HCCL 在 full-mesh 拓扑下使用 mesh 算法，所有 peer 链路并发通信；ring 算法仅在 ring 拓扑下使用
对比当前算法：当前实现是否利用了拓扑的并发能力？例如 full-mesh 下 peer 串行 get 只用了 N-1 条链路中的 1 条
判断优化方向：
- 算法不匹配拓扑 → 机制优化轮应优先做算法级重构（如串行 fetch → 并发 peer 通信 + 通信/计算 overlap）
- 算法已匹配拓扑 → 进入下方 5 类细粒度排查

输出：在瓶颈列表最前面标注算法级判断。

5 类细粒度排查

按以下 5 类系统排查：

排查类别	指标/现象	典型瓶颈信号
通信带宽	algo_bandwidth 远低于理论带宽	chunk 太小、engine 选择不当、无 overlap
同步开销	kernel_us 中大量时间在 barrier/wait	全局 barrier 过多、signal 粒度太粗
核利用率	部分核空闲或 tail 核负载翻倍	分核比例不当、负载不均衡
内存效率	多余 GM scratch 读写、未对齐搬运	UB 未充分利用、buffer 未对齐
流水深度	通信和计算串行、无 double buffer	缺少 ping-pong、phase 间无 overlap

输出：按优先级排列的瓶颈列表，每项标注排查类别和预期收益。

OptimStep 2：基线锁定

确认基线数据（来自 shmem-ops-performance-eval 生成的 performance_report.md §3）：

指标	适用	值
e2e_latency_us	全部	[从 §3.1 获取]
kernel_latency_us	全部	[从 §3.1 获取]
algo_bandwidth_GBps	全部	[从 §3.1 获取]
kernel_bus_bandwidth_GBps	全部	[从 §3.1 获取]
bandwidth_utilization_percent	通信算子	[从 §3.2 获取]
compute_utilization_percent	通算融合算子	[从 §3.3 获取]；纯通信标 N/A

OptimStep 3：输出修改意见与委托执行

本 skill 禁止自行修改算子代码或 design.md。 所有改动必须委托对应子 skill 执行。

3a. 输出修改意见

根据 OptimStep 1 瓶颈分析，将本轮优化方向分类并输出结构化意见：

分类	改动范围	委托目标
设计级	分核策略、调度 phase 重构、算法变更（ring→mesh）、topology 适配	`shmem-ops-design` 修订 design.md
代码级	engine 切换、double buffer、signal/wait 替换、block_dim/chunk_size 调整	`shmem-ops-code-gen` 修改代码

每条意见 MUST 包含：改什么、为什么（关联 OptimStep 1 的瓶颈）、预期收益（Δ% kernel_bus_bandwidth_GBps）。

机制改动参考（从 optimization-patterns.md 或 compute-optimization.md 选择）：

机制改动	说明	分类	参考
Ping-pong double buffer	增加双缓冲流水，掩盖搬运气泡	代码级	optimization-patterns.md §2.1
Copy-to-symmetric overlap	sender/receiver 分核 + 逐 chunk signal	代码级	optimization-patterns.md §1.1
Engine 切换	MTE→SDMA 或 MTE→RDMA	代码级	optimization-patterns.md §1.2
Barrier→signal/wait	全局 barrier 替换为点对点同步	代码级	optimization-patterns.md §3.1
通信-计算 overlap	chunk k 通信与 chunk k-1 计算重叠	代码级	optimization-patterns.md §2.2
分核策略调整	core partition 比例、send/recv 核数分配	设计级	optimization-patterns.md §5
算法级重构	串行 fetch→并发 peer 通信、ring→mesh	设计级	OptimStep 1 算法级排查

参数扫描（block_dim、chunk_size、transfer_size 等）属于代码级改动，同样委托 code-gen 执行。每次参数变更记录为一个 step（step N.1、N.2...）。

3b. 委托执行链

修改意见输出后，按以下顺序委托子 skill 执行。本轮所有 step 共享同一委托链——每个 step 变更参数后重新走 code-gen → compile → correctness 循环。

设计级改动（如有）→ 委托 shmem-ops-design 修订 design.md。修订完成后 跳过 testcase-gen（测试用例不变），进入步骤 2
代码级改动 → 委托 shmem-ops-code-gen 修改代码
编译 → 委托 shmem-ops-compile-debug 执行构建与诊断（compile-debug 只诊断不改代码，编译失败回 code-gen 修复后重试）。编译命令见 custom-ops-entrypoints.md §1
正确性复测 → 委托 shmem-ops-correctness-eval。正确性失败的 step NEVER 采纳为性能结论

3c. Step 记录规范

每个 step MUST 记录：

字段	说明	格式约束
Step ID	`轮次.序号`	MUST 为 `1.1`、`2.3` 等格式，NEVER 使用其他格式
变更描述	具体改了什么	MUST 包含具体参数值（如 `block_dim: 16→32`），NEVER 使用笼统描述
Correctness	正确性结果	只允许 PASS / FAIL，NEVER 使用模糊值
e2e_us	端到端延迟	MUST 为数值
kernel_us	纯 kernel 延迟	MUST 为数值
kernel_bus_bandwidth_GBps	总线带宽（kernel 口径）	MUST 为数值；Round 对比主指标
algo_bandwidth_GBps	算法带宽 (GBps)	MUST 为数值
e2e_bus_bandwidth_GBps	e2e 总线带宽 (GBps)	参考；NEVER 作 round 对比主指标
compute_utilization%	计算利用率	通算融合算子 MUST 填写，纯通信算子标记 N/A
备注	观察到的现象	如"核利用率从 60%→90%"

Step 表列名与 timing-and-metrics-standard.md 标准字段对齐。table headers in §4 of performance_report.md MUST use these exact names.

OptimStep 4：性能验证

调用 shmem-ops-performance-eval 重新采集性能数据，由 eval skill 将结果写入 performance_report.md 对应 Round 的 §4 子节。

L 档固定 case：优化轮次 MUST 使用 Round 0 锁定的平台区 base_count/dtype/PE，NEVER 每轮换 payload（否则不可比）。

聊天自动输出（Hard Gate）

每轮最优 step 确定后（is_optimal_step=true），eval 与 optim MUST 在聊天自动输出（无需用户追问）：

本轮 Step 摘要表（多 step 时）
Round N 最优 vs Round0 / vs 上轮最优（含 kernel_bus_bandwidth_GBps Δ%）
累计轮次总览表（0~N 行，每轮结束后更新）

模板见 perf-chat-output-spec.md §3。NEVER 只在 Round 5 结束才输出变化。

调用上下文（optim → eval）

optim 调用 eval 时 MUST 附带以下上下文，使 eval 知道写入报告的位置：

参数	含义	值
`target_section`	写入目标区域	`round_0`（基线采集）、`round_N_step_M`（如 `round_1_step_3`）
`round_label`	轮次标签	`Round 0 基线`、`Round 1 机制优化：并发 peer put`、`Round 2 机制优化：double buffer`
`is_optimal_step`	是否为该轮最优 step	`true`（需输出 Device Frame）、`false`（仅填 step 表行）

eval skill 根据上下文写入的位置：

target_section	is_optimal_step	写入内容
`round_0`	—	§2 Baseline 详细信息 + §3.1~§3.5 L 档基线数据 + S 档数据（供 §6.2）
`round_N_step_M`	`false`	在 §4 Round N 的 Step 表中追加一行（仅 L 档）
`round_N_step_M`	`true`	Step 表行 + 性能验证对比表 + Device Frame Table（均仅 L 档）
`round_N_step_M`	`true`（且为最终轮次）	上述内容 + §5 轮次总览行 + §6.1 L 档对比 + §6.2 S 档对比 + §7 结论

规则

使用与基线相同的 case、参数和环境
S 档仅在 Round 0 采集一次，§4 优化轮（Round 1~5）NEVER 记录 S 档数据，仅记录 L 档
eval skill MUST 将以下内容写入 performance_report.md §4 对应 Round：
1. 性能验证对比表（Baseline vs Round N 最优 | Δ%）—— 简表格式
2. Device Frame Table（最优 step 的 frame 数据）—— 若该轮包含多个 step（参数扫描），只输出最优 step 的 Device Frame
纯通信算子：不需要输出 compute_utilization_pct
通算融合算子 MUST 同时输出 compute_utilization_pct
MUST 输出与基线的 Δ% 对比

optim skill 从 OptimStep 5 得到的结构化数据格式：

性能验证对比表（由 eval 填入 §4 各 Round 末尾）：

指标	Baseline	Round N 最优	Δ%
kernel_bus_bandwidth_GBps
e2e_latency_us
kernel_latency_us
algo_bandwidth_GBps
e2e_bus_bandwidth_GBps
compute_utilization_pct

compute_utilization_pct 行仅通算融合算子填写；纯通信标 "N/A"

Device Frame Table（由 eval 填入 §4 各 Round "Device Frame（最优 step）" 子节）：

Frame	Phase	Avg us	Max core us	Count	% E2E	Bottleneck

若该轮仅一个 step，取该 step 的 frame 数据；若多个 step，取最优 step 的 frame 数据。

OptimStep 5：迭代决策

决策	条件
keep	本轮最优 step 性能提升且正确性通过 → 采纳该 step 配置作为新基线
revert	本轮所有 step 性能退步或正确性失败 → 恢复上一轮最优配置

决策后：若轮次 < 5 → 回 OptimStep 1 开始下一轮（无论是否已达标）。

停止条件

已完成 5 轮（唯一正常停止条件——即使已达标也 MUST 跑满 5 轮）
用户明确要求继续优化 → 可超过 5 轮，每额外轮次仍遵循完整的 OptimStep 1-6 流程，并在 performance_report.md 中标注"用户要求的额外优化轮次"；模板 §4/§5 按 Round 2 格式续写，无上限
进一步优化需修改 SHMEM 核心库但无 gap analysis 授权（异常停止，需在报告中说明）

OptimStep 6：最终确认与格式走读

所有轮次完成后（无论达标与否），按以下步骤最终确认：

格式走读：逐节对照模板检查 performance_report.md：

检查项	内容
节号与模板一致	§1~§7 完整，无自定义新增章节（如"采集命令"、"指标公式"、"正确性回归"）
节名与模板一致	使用模板定义的标准节名（"算子信息"、"Baseline 详细信息"等），不自行重命名
表结构一致	列名、列数、列顺序与模板完全相同
§3.2 / §3.3 适用性标注	通信算子 §3.3 标注 "N/A"，通算融合 §3.2 不得标 N/A
Device Frame Table	§3.4 和 §4 每个 Round 最优 step 均存在，无空表
§4 每个 Round 结构完整	Step 表 + 性能验证对比表 + Device Frame + 本轮最优配置 + 决策
§5 轮次总览	行数与实际轮次数一致，含 Round 0
compute_util% 列	纯通信算子标 "N/A"，通算融合算子必须填写

完整性确认：report MUST 包含以下全部内容 → 对应模板位置：
算子信息（名称、shape、dtype、PE 数、目标指标）→ §1
Baseline 详细信息 → §2
基线数据（Round 0 的完整指标 + 通信指标表 + 计算指标表 + Device Frame Table + 性能对比表）→ §3
每轮每步的完整记录（Step 表 + 性能验证对比表 + Device Frame Table）→ §4 各 Round
轮次总览表 → §5
最终对比表（baseline vs final，含 Δ%）→ §6
结论（达标/未达标 + 瓶颈总结 + 优化路径）→ §7
交付：确认通过后输出 docs/performance_report.md 路径。

performance_report.md 由 shmem-ops-performance-eval 在每轮执行时维护，位于算子目录 docs/performance_report.md。

输出

两级记录表

每轮记录（Round 级）：

Round	性质	机制改动	最优 Step	最优 kernel_bus_bandwidth_GBps	vs R0	vs baseline	决策
0	baseline	—	—	...	...	...	—
1	机制优化	并发 peer 通信	1.3	...	...	...	keep
2	机制优化	加 ping-pong double buffer	2.2	...	...	...	keep

compute_util% 列仅通算融合算子填写；纯通信标 N/A

每步记录（Step 级，嵌套在 Round 内）：

| Step | 变更 | Correctness | kernel_bus_bandwidth_GBps | e2e_us | kernel_us | 备注 | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 1.1 | block_dim: 16→32 | PASS | ... | ... | ... | ... | N/A | 核利用率提升 | | 1.2 | block_dim: 32→48 | PASS | ... | ... | ... | ... | N/A | 无明显提升 | | 1.3 | chunk_size: 64KB→190KB | PASS | ... | ... | ... | ... | N/A | 带宽提升 20% |

performance_report.md

最终交付 MUST 在算子目录下生成 docs/performance_report.md，由 shmem-ops-performance-eval 按模板格式维护。

反模式（NEVER DO THESE）

❌ performance_auto_optim: false 时擅自进入本 skill 或改 kernel
❌ 将 Host RMA → Device kernel 当作性能优化（这是功能完善）
❌ 无瓶颈分析就随机改参数
❌ 未经用户明确要求超过 5 轮（用户主动要求继续不受此限制）
❌ 未完成 5 轮就声称优化完成（达标不是停止理由）
❌ 正确性未复测就采纳性能结果
❌ 未证明 ≥5% 收益就引入或恢复 big_data/large 与 unified 路径并行维护
❌ 将 UB 内部分块误判为「大小两套实现」从而拒绝合并代码
❌ Round 1 仅扫 block_dim 而无机制改动（除非机制已全部穷尽且文档说明）
❌ 不输出 performance_report.md 就声称优化完成
❌ step 记录中省略具体参数值或度量结果
❌ 将用户 input 直接构造在对称内存（symmetric memory / GVA）上以跳过输入到对称堆的拷贝来提升性能。真实使用场景中，用户 input 来自 Device GM buffer，MUST 经过 输入到对称堆的拷贝 → symmetric memory → kernel 的完整流程。跳过输入到对称堆的拷贝的"优化"只是在测试中作弊，不反映实际部署性能
❌ 将输入到对称堆的拷贝移到性能循环外（如循环前做一次预拷贝），导致 e2e_latency_us 不包含输入到对称堆的拷贝时间。e2e 性能循环 MUST 每轮都执行 input(GM) → 输入到对称堆的拷贝 → symmetric memory → barrier → kernel 完整流程
❌ performance_report.md 使用模板 §1~§7 之外的节号（如 §8、§9、§10）或自定义节名（如"采集命令"、"指标公式"、"正确性回归"）
❌ 自行修改算子代码（.cpp/.h/CMakeLists.txt）——必须委托 shmem-ops-code-gen
❌ 自行修改 design.md ——必须委托 shmem-ops-design
❌ Phase 6.5 只在最后一轮才在聊天报性能变化
❌ Round 间用 e2e 带宽对比（应使用 kernel_bus_bandwidth_GBps）
❌ 优化轮次更换 payload 规模导致不可比
❌ §4 优化记录只输出一个扁平表格而不按 Round 分子节（每个 Round 必须包含 Step 表 + 性能验证 + Device Frame + 最优配置 + 决策）

最佳实践

✅ 先定位瓶颈再选优化手段
✅ 每个 step 记录具体参数值和 6 指标结果
✅ 正确性通过后再看性能数据
✅ 退步时 revert 而非继续叠加
✅ 机制优化轮（Round 1~5） MUST 包含代码级改动
✅ 固定完成 5 轮优化，达标后继续挖掘优化空间
✅ 最终输出 performance_report.md（由 eval skill 按模板维护）
✅ 最终对比表包含 Δ%

shmem-ops-performance-optim

Más de este repositorio

Más de este repositorio

SHMEM 算子性能优化

优化优先级（MUST）

统一实现原则

轮次模型

核心工作流

必读资料

前置条件

达标规则

OptimStep 1：瓶颈定位

算法级排查（SHMEM/baseline < 50% 时 MUST 执行）

5 类细粒度排查

OptimStep 2：基线锁定

OptimStep 3：输出修改意见与委托执行

3a. 输出修改意见

3b. 委托执行链

3c. Step 记录规范

OptimStep 4：性能验证

聊天自动输出（Hard Gate）

调用上下文（optim → eval）

规则

OptimStep 5：迭代决策

停止条件

OptimStep 6：最终确认与格式走读

输出

两级记录表

performance_report.md

反模式（NEVER DO THESE）

最佳实践

MUST检查

SHMEM 算子性能优化

优化优先级（MUST）

统一实现原则

轮次模型

核心工作流

必读资料

前置条件

达标规则

OptimStep 1：瓶颈定位

算法级排查（SHMEM/baseline < 50% 时 MUST 执行）

5 类细粒度排查

OptimStep 2：基线锁定

OptimStep 3：输出修改意见与委托执行

3a. 输出修改意见

3b. 委托执行链

3c. Step 记录规范

OptimStep 4：性能验证

聊天自动输出（Hard Gate）

调用上下文（optim → eval）

规则

OptimStep 5：迭代决策

停止条件

OptimStep 6：最终确认与格式走读

输出

两级记录表

performance_report.md

反模式（NEVER DO THESE）

最佳实践

MUST检查