| name | shmem-ops-performance-eval |
| description | 基于 SHMEM 的算子性能采集、baseline 对比、瓶颈分析和性能报告生成。关键词：基于SHMEM性能评估、性能采集、performance、baseline、bandwidth、性能报告。 |
SHMEM 算子性能采集
Skill类型：评测型（采集性能数据，对比 baseline，将结构化数据写入 performance_report.md）
中文写作要求：性能报告 MUST 使用中文撰写。仅 API 名称、代码片段、指标名（如 e2e_latency_us）等技术术语保留英文原文。
正确性验证通过后执行。仅当 design.md meta.performance_required: true（Phase 0 #4 用户已确认）时由编排器调用 Phase 6；NEVER 在用户未要求性能工作时擅自采集。
性能优化（Phase 6.5）仅当 meta.performance_auto_optim: true 且 Phase 6 未达标时由编排器自动调用 shmem-ops-performance-optim；performance_auto_optim: false 时 eval 只采集与报告，禁止擅自改 kernel。
采集性能数据、接入 baseline、分析瓶颈，将结构化数据写入 performance_report.md（模板：templates/performance-report.md）。
必读资料
输入
- design.md 的 perf contract（metric、baseline、target_cases、最小规模）
- 已通过正确性验证的算子二进制
- 算子已包含性能打点代码（由
shmem-ops-code-gen 按 timing-and-metrics-standard.md 生成）
- 调用上下文（由
shmem-ops-performance-optim OptimStep 5 传入）：
| 参数 | 含义 | 示例 |
|---|
target_section | 写入目标区域 | round_0（基线采集）、round_1_step_3（Round 1 step 3） |
round_label | 轮次标签 | Round 0 基线、Round 1 机制优化：并发 peer put、Round 2 机制优化：double buffer |
is_optimal_step | 是否为该轮最优 step | true（需输出 Device Frame Table）、false（仅填 step 表行） |
独立调用 eval 时（非 optim 驱动），默认 target_section = round_0，仅写入 §2 + §3 + §6.2 baseline 列。
工作流
步骤 1 选择 baseline + 确认 baseline C++ 代码已由 code-gen 生成、compile-debug 编译通过 + 采集 baseline 性能（[BASELINE_PERF]）
步骤 2 采集 SHMEM 性能（[PERF]）+ 离线对比
步骤 3 瓶颈分析 + 写入 performance_report.md + 聊天自动输出
所有命令代码段见 perf-workflow.md；聊天输出格式见 perf-chat-output-spec.md。
路径说明：custom-ops/<op>/ 类路径均相对于 SHMEM_REPO（定位规则见 shmem-repo-resolution.md）。参考实现：${SHMEM_REPO}/custom-ops/alltoallv/baseline/ + perf-workflow.md。
步骤 1：Baseline 选择与实现
MUST 按以下顺序逐步查找，声称"无 baseline"前每步都要排查（详见 references/baseline-selection.md）：
- HCCL 集合通信算子：AllGather、AllReduce、ReduceScatter、AllToAll、Broadcast、Reduce、Scatter、Gather（完整清单见 baseline-selection.md §1.1）
- aclnn 扩展算子：aclnnAlltoAllV 等（完整清单见 baseline-selection.md §1.2）
- 指标测试（无直接 baseline）：仅测量利用率指标（见 baseline-selection.md §2）
peak_bandwidth 决策表见 timing-and-metrics-standard.md §4.4。
Baseline 实现要求
Baseline 采集
步骤 2：SHMEM 性能采集
前置：确认打点代码
SHMEM 算子的 --perf 打点代码（timing loop + SHMEMI_PROF + [PERF] 输出）MUST 由 shmem-ops-code-gen 生成（由 dev 协调）。执行采集前 MUST 确认：
main.cpp 包含 --perf flag 和 [PERF] 输出逻辑- kernel 包含
SHMEMI_PROF_START/END 宏对（至少 5 个 frame_id）
scripts/perf.sh 存在
若未包含，由 dev 编排器调用 shmem-ops-code-gen 添加后重新编译再采集。
采集命令
MUST 按 perf-workflow.md §1 阶段 B 执行 SHMEM 采集，并按 perf-workflow.md §1 阶段 C 进行离线对比。采集规范（warmup、repeats、多 PE 取平均）见 profiling-tools.md。
时间打点与指标
算子打点代码由 shmem-ops-code-gen 按 timing-and-metrics-standard.md 生成。本 skill 负责验证输出：确认 [PERF] 行包含全部 MUST 字段且格式正确。
与 baseline 对比时 latency 参考 e2e_us，带宽达标与 Round 间对比 MUST 用 kernel_bus_bandwidth_GBps。指标计算公式见 timing-and-metrics-standard.md §4。
MUST 记录字段
| 字段 | 内容 |
|---|
| case | shape、dtype、PE count、engine、scope |
| command | 完整测试命令和环境 |
| metric | e2e_latency_us、kernel_latency_us、algo_bandwidth_GBps、e2e_bus_bandwidth_GBps、kernel_bus_bandwidth_GBps、bandwidth_utilization_percent |
| device frame | phase、cycles、avg_us、percent_of_e2e（采集方法见 device-profiling-guide.md） |
| compute | effective_flops、compute_utilization_percent（标注 N/A） |
注意：algo_bandwidth NEVER 乘 2，统一按 input size 计算（NCCL algBw 惯例）。
规模要求
性能 case 要求（规模分档见 shmem-ops-testcase-gen/references/testcase-scale-standard.md）：
- 性能采集 MUST 覆盖 8PE S 档 + 8PE L 档 两种规模，NEVER 只采 L 档
- L 档：集合通信 ≥256MB 数据量（全 PE 总量）
- S 档：按 testcase-scale-standard.md 定义
- NEVER 只用 smoke 小 shape
有 baseline 时，计算 delta（当前实现 vs baseline）和利用率；无 baseline 时，计算 metric_only 达标判断。
步骤 3：瓶颈分析与报告写入
瓶颈分析
基于 profiler frame table 判断（分析方法论见 device-profiling-guide.md §6.2）：
- 哪个 phase 占比最高 → 对应优化方向
max_core_us / avg_us 比值 → 是否存在长尾 block/PE- signal_wait / barrier 占比 → 同步效率是否合理
- 通信 frame 的 algo_bw / peak_bw → 带宽利用率是否达标
- 是否存在不合理的 wait/sync 占比
写入报告
根据 target_section 和 is_optimal_step 决定写入 docs/performance_report.md 的位置：
| target_section | is_optimal_step | 写入位置 | 具体内容 |
|---|
round_0 | — | §2 + §3.1~§3.5 + §6.2 baseline 列 | Baseline 详细信息、L 档性能结果/通信/计算/Device Frame/性能对比表；S 档 baseline 直接写入 §6.2 baseline 列，final 列暂空 |
round_N_step_M | false | §4 Round N Step 表 | 在已有 Step 表中追加一行（以 L 档数据为准） |
round_N_step_M | true | §4 Round N | Step 表行（以 L 档为准）+ 性能验证对比表 + Device Frame Table |
round_N_step_M | true（最终轮） | §4 + §5 + §6 + §7 | 上述 + §5 轮次总览行 + §6.1 L 档对比 + §6.2 S 档 final 列（MUST 重新采集 S 档）+ §7 结论 |
| — | 仅 S 档 | §6.2 | S 档在 Round 0 直接写入 §6.2 baseline 列；最终轮后 MUST 重新采集 S 档数据（非复用 Round 0 数据），填入 final 列与 Δ%。NEVER 写入 §4 优化记录 |
节号强制约束：写入时 MUST 使用模板定义的固定节号（§1~§7）和节名。以下行为 NEVER 允许：
- 在 §1~§7 之外新增自定义章节（如"采集命令"、"指标公式"、"正确性回归"）
- 辅助信息归入已有章节：采集命令 → §2 Baseline 详细信息；指标公式 → §3.2/§3.3 表头备注
- §4 每个 Round MUST 包含完整子结构：Step 表 → 性能验证对比表 → Device Frame Table → 本轮最优配置 → 决策
聊天自动输出（Hard Gate）
脚本跑完后 MUST 在同轮对话自动输出带宽表 + 时延表，NEVER 只报时延或等用户追问。输出格式和模板见 perf-chat-output-spec.md。
输出字段规范
eval 输出以下结构化数据，写入 performance_report.md。缺失任一项视为不完整。
MUST 输出
| 输出项 | 字段 | 说明 |
|---|
| Baseline 信息 | type, source_api, search_process, measurement | 逐步排查记录、baseline 测试数据 |
| 性能结果表 | case_id, shape, dtype, n_pes, e2e_us, kernel_us, algo_bandwidth_GBps, kernel_bus_bandwidth_GBps, utilization% | 每个采集 case 的完整指标 |
| 通信指标 | logical_payload_bytes, bus_factor, peak_bandwidth_GBps, bandwidth_utilization_percent | 通信算子 MUST |
| 计算指标 | op_count_flops, compute_latency_us, effective_flops, peak_flops, compute_utilization_percent | 标注 "N/A" |
| Device Frame Table | frame_id, phase, avg_us, max_core_us, count, percent_of_e2e, bottleneck_note | MUST 存在；采集方法见 device-profiling-guide.md |
| 瓶颈判断 | 主要耗时来源、带宽利用率是否达标、计算利用率是否达标 | 基于 frame table 分析（方法论见 device-profiling-guide.md §6.2） |
| Delta vs Baseline | kernel_bus_bandwidth_GBps 对比、达标判断 | 有 baseline 时 MUST |
| 聊天自动输出 | 带宽表+时延表、（optim 驱动时）轮次 Δ% 表 | MUST，见 perf-chat-output-spec.md |
调用方差异
| 调用方 | target_section | 聊天 MUST 额外输出 |
|---|
| Phase 6 独立 eval | round_0 | §2 perf-chat-output-spec：S+L 表 + 对比表 |
| optim OptimStep 5（每 step） | round_N_step_M | 无（仅写报告 Step 行） |
| optim OptimStep 5（round 最优） | round_N_step_M + is_optimal_step=true | §3 perf-chat-output-spec：本轮最优表 + 更新累计总览 |
| optim 全部完成 | 最终轮最优 | §4 perf-chat-output-spec：最终对比表 |
输出格式
性能结果以表格形式在聊天界面展示，关键指标 MUST 摘要输出，NEVER 仅输出路径。
有 baseline 时，聊天回复 MUST 包含带宽表与时延表（kernel_bus_bandwidth_GBps、比值、目标、达标），格式见 perf-chat-output-spec.md §2。NEVER 只粘贴单行 [PERF] 或只报 e2e 时延。
示例（结构示意，数值须来自实际采集）：
| 指标 | SHMEM | HCCL baseline | SHMEM/baseline |
|---|
| bus_GBps (M_fp16_8pe) | 30.86 | 10.61 | 290.7% PASS |
MUST检查
反模式（NEVER DO THESE）
- ❌ 有可用 baseline 却不接入
- ❌ 只采集时间不分析瓶颈
- ❌ 用 smoke 小 shape 作为性能结论
- ❌ 没有硬件却编造性能数据
- ❌ 通信算子不测量带宽利用率
- ❌ 只输出 algo_bandwidth 不输出 bus_bandwidth 和 utilization
- ❌ 报告中缺少 Device Frame Table
- ❌ baseline 字段写
"none" 但不记录搜索过程
- ❌ 输出指标不完整
- ❌ 写入 performance_report.md 时新增模板未定义的章节（如"采集命令"、"指标公式"、"正确性回归"），所有信息必须归入 §1~§7 对应子节
- ❌ custom-ops 性能采集在文档/回复中首选裸
cd custom-ops/<op> && ...（用 perf-workflow.md）
- ❌ 性能测试完成后不在聊天中自动输出结果，等用户引导
- ❌ Phase 6.5 只在第 5 轮结束才报性能变化
- ❌ 只报 SHMEM
[PERF] 不报 baseline [BASELINE_PERF] 及对比表
- ❌ 无离线对比流程却声称已完成 baseline 对比
- ❌ 同一 shell 内混跑 HCCL baseline 与 SHMEM perf（须分阶段 + 离线 compare）
- ❌ AllToAllV 未排查
HcclAlltoAllV 就直接写 metric_only
- ❌ baseline 与 SHMEM 使用不同 gen_data / sendcounts
