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）。

必读资料

文件	用途
references/performance-eval-guide.md	采集流程概览、contract 字段、结果表格式、规模要求
references/baseline-selection.md	baseline 选择策略、HCCL/aclnn 清单、决策树；C++ 模板、CMake 集成
references/baseline-compare-workflow.md	baseline C++ 接入流程、日志标签约定、离线对比
references/perf-workflow.md	三阶段采集命令代码段（baseline + SHMEM + 离线对比）
references/perf-chat-output-spec.md	聊天自动输出规范
references/timing-and-metrics-standard.md	性能评估唯一标准：时间打点、双指标方案、指标计算公式、Device 打点、计算指标
references/profiling-tools.md	msprof、SHMEM cycle profiling、warmup 规范（前 N 轮不计入统计）、多 PE 取平均
references/device-profiling-guide.md	SHMEMI_PROF 完整操作指南（kernel 打点 → Host 导出 → 填报告 → 瓶颈分析）
templates/performance-report.md	性能报告模板（eval 写入数据的格式规范）
../shmem-ops-design/references/hardware-architecture.md	昇腾硬件参数速查（计算带宽利用率时 MUST 参考）
../shmem-ops-dev/references/shmem-repo-resolution.md	定位 `SHMEM_REPO`（读仓内和外链路径如 `custom-ops/<op>/` 前）

输入

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 C++ 代码 MUST 由 shmem-ops-code-gen 生成（由 dev 协调）；编译 MUST 通过 shmem-ops-compile-debug 完成；本 skill 负责运行、采集、对比
实现模板和 CMake 集成见 baseline-selection.md §1.3；日志标签格式 [BASELINE_PERF] 见 baseline-compare-workflow.md §2.2
源码与脚本 MUST 放在 custom-ops/<op>/baseline/ 下，算子根 CMakeLists.txt 通过 add_subdirectory(baseline) 编译
产物布局见 baseline-compare-workflow.md §2

Baseline 采集

MUST 使用与 SHMEM 相同的 case 和环境
采集命令见 perf-workflow.md §1 阶段 A
AllToAllV 类算子：CANN 无独立 aclnnAlltoAllV 头文件时，MUST 回退 HcclAlltoAllV 并记录原因（见 baseline-compare-workflow.md §5）
MUST 分三阶段执行（baseline → SHMEM → 离线对比），NEVER 同 shell 混跑（见 perf-workflow.md）

步骤 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检查

baseline 已选择或记录搜索过程
baseline C++ 程序已由 code-gen 生成、compile-debug 编译通过，且 [BASELINE_PERF] 已采集
性能数据已采集（Round 0: S 档 + L 档；中间轮次: L 档；最终轮: S 档 + L 档）
瓶颈已分析（基于 Device Frame Table；见 device-profiling-guide.md §6.2）
输出字段规范中全部 MUST 项已输出
docs/performance_report.md §3.5 对比表已填写
聊天已按 perf-chat-output-spec.md 自动输出（非用户追问才补）
optim 驱动时：每轮最优 step 后已输出 Round Δ% 表与累计总览

反模式（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