企业官网建设流程全解析

CANN SHMEM 算子性能采集与对比：三阶段工作流与基线达标实践

【免费下载链接】shmemCANN SHMEM 是面向昇腾平台的多机多卡内存通信库，基于OpenSHMEM 标准协议，实现跨设备的高效内存访问与数据同步。项目地址: https://gitcode.com/cann/shmem

本文以.agents/skills/shmem-ops-performance-eval/references/perf-workflow.md为骨架，融合同 skill 的 timing-and-metrics-standard.md、baseline-compare-workflow.md、performance-eval-guide.md 等文档以及仓库源码，整理成一篇面向开发者的完整实操指南。

本篇技术指南讲解在 CANN SHMEM 仓库生态下，对基于 OpenSHMEM 标准实现的多机多卡内存通信算子（collective 通信算子、dispatch/combine 等路由型算子）进行性能采集与基线对比的完整方法论。你将掌握三阶段分时采集（HCCL baseline → SHMEM → 离线对比）的标准命令、日志标签与产物布局约定、kernel_bus_bandwidth_GBps达标口径、双指标（e2e_us/kernel_us）打点规范，以及 Docker 环境下的隔离执行规则，可直接复用于算子开发与性能报告生成。

1. 适用范围与前置约定

该性能采集工作流面向.agents/skills/shmem-ops-performance-evalskill 生成的custom-ops/交付树（以custom-ops/<op_name>/为算子根目录），而非 SHMEM upstream 自带目录。规范要点：

• perf 封装位置：custom-ops/scripts/（skill 生成交付物），以 perf-workflow.md 中的命令代码段为准，磁盘文件由对应阶段生成或同步；
• Skill 形态约束：命令以 Markdown 代码段形式维护，禁止在.agents/skills/下放置 skill 附属的.sh/.py脚本；
• SHMEM 原生部分：仅环境链（如install/set_env.sh、scripts/build.sh -examples等）来自 upstream；
• Hard Gate（硬隔离）：HCCL baseline 与 SHMEM perf绝对禁止在同一 shell 或同一次docker exec中混跑，必须分阶段、分 shell 执行，对比在离线阶段完成。

环境准备参考 custom-ops-entrypoints.md：先 source CANN 与 SHMEM 环境，再设置LD_LIBRARY_PATH指向${SHMEM_REPO}/build/lib，并在采集 baseline 时设置HCCL_WHITELIST_DISABLE=1。

2. 三阶段分时采集（核心工作流）

整个性能采集被拆成三个彼此隔离的阶段：阶段 A 仅跑 HCCL baseline→阶段 B 仅跑 SHMEM→阶段 C 离线对比。这样设计是为了规避 HCCL 与 SHMEM 在同一进程中混跑导致的资源抢占与初始化状态污染，确保两侧数据各自独立可信。

2.1 阶段 A — 仅采集 HCCL baseline

在独立 shell 中执行以下命令，日志写入data/perf/baseline_*.log：

OP=<op_name> DEVICE_LIST=0,1,2,3,4,5,6,7 BASE_COUNT=8388608 DTYPE=float16 WARMUP=10 MEASURE=40 ITERS=$((WARMUP + MEASURE)) # 50 total mkdir -p "${SHMEM_REPO}/custom-ops/${OP}/data/perf" LOG="${SHMEM_REPO}/custom-ops/${OP}/data/perf/baseline_${BASE_COUNT}_${DTYPE}.log" bash "${SHMEM_REPO}/custom-ops/${OP}/baseline/scripts/run_baseline.sh" \ "${DEVICE_LIST}" "${BASE_COUNT}" "${DTYPE}" "${ITERS}" \ 2>&1 | tee "${LOG}"

参数语义：

baseline 侧由baseline/scripts/run_baseline.sh驱动，输出以[BASELINE_PERF]前缀标记（详见下文 §4 日志标签约定）。

2.2 阶段 B — 仅采集 SHMEM

阶段 A 完成后间隔 ≥30 秒，新开一个 shell（不可复用阶段 A 的进程上下文），执行 SHMEM 采集，日志写入data/perf/shmem_*.log：

OP=<op_name> DEVICE_LIST=0,1,2,3,4,5,6,7 BASE_COUNT=8388608 DTYPE=float16 WARMUP=10 MEASURE=40 ITERS=$((WARMUP + MEASURE)) # 50 total mkdir -p "${SHMEM_REPO}/custom-ops/${OP}/data/perf" LOG="${SHMEM_REPO}/custom-ops/${OP}/data/perf/shmem_${BASE_COUNT}_${DTYPE}.log" bash "${SHMEM_REPO}/custom-ops/${OP}/scripts/perf.sh" \ "${DEVICE_LIST}" "${BASE_COUNT}" "${DTYPE}" "${ITERS}" \ 2>&1 | tee "${LOG}"

SHMEM 侧由算子目录内scripts/perf.sh驱动（或 in-tree example 使用scripts/run.sh --perf），输出以[PERF]前缀标记。预热轮（WARMUP）不计入统计，统计轮（MEASURE）内多 PE 结果取平均，具体规范见 profiling-tools.md。

2.3 阶段 C — 离线对比

两阶段日志落盘后，使用custom-ops/scripts/lib/perf_compare.py离线解析并对比，禁止手工抄数：

OP=<op_name> BASE_COUNT=8388608 DTYPE=float16 SHMEM_LOG="${SHMEM_REPO}/custom-ops/${OP}/data/perf/shmem_${BASE_COUNT}_${DTYPE}.log" BASE_LOG="${SHMEM_REPO}/custom-ops/${OP}/data/perf/baseline_${BASE_COUNT}_${DTYPE}.log" python3 "${SHMEM_REPO}/custom-ops/scripts/lib/perf_compare.py" \ --shmem-log "${SHMEM_LOG}" --baseline-log "${BASE_LOG}"

对比通过 grep[PERF]与[BASELINE_PERF]两行 + 脚本解析完成。时延类算子可使用custom-ops/scripts/perf_compare_latency.py对比kernel_us/comm_only_us字段。

S 档采集说明：Round 0 与最终轮需要额外采集 S 档规模。做法是将BASE_COUNT替换为 S 档规模（分档标准见 testcase-scale-standard.md），其余流程与 L 档完全相同；中间优化轮次仅采 L 档。

3. 产物布局与隔离规则

3.1 目录结构约定

custom-ops/下性能相关产物布局如下，所有日志与脚本路径都必须遵守：

custom-ops/ ├── scripts/lib/perf_compare.py # 带宽离线对比脚本 ├── scripts/perf_compare_latency.py # 时延离线对比脚本（可选） └── <op_name>/ ├── baseline/scripts/run_baseline.sh # HCCL baseline 入口 ├── scripts/perf.sh # SHMEM perf 入口 └── data/perf/ # baseline_*.log / shmem_*.log

baseline 的实现约束（来自 baseline-compare-workflow.md）：

• baselineMUST以 C++ 可执行文件方式实现，禁止用 Python/torch 脚本充当 baseline；
• baseline 源码与 CMake 必须放在baseline/子目录，禁止混入算子src/或根CMakeLists.txt；
• 算子根CMakeLists.txt末尾通过add_subdirectory(baseline)集成，baseline 的CMakeLists.txt将CMAKE_RUNTIME_OUTPUT_DIRECTORY设为${CMAKE_BINARY_DIR}/../bin，与主程序同目录；
• 同一gen_data.py输出、同一 sendcounts/shape/dtype/PE 数，保证与 SHMEM 完全同 case。

3.2 HCCL 与 SHMEM 隔离（Hard Gate）

HCCL baseline 与 SHMEM perfNEVER同 shell / 同docker exec混跑，且每阶段使用独立的docker exec（见 docker-exec-contract.md）。典型执行方式是两次独立docker exec，容器内分别粘贴阶段 A/B 命令，再在第三处执行阶段 C 离线对比。

4. 日志标签与指标口径

4.1 日志标签约定

两边的性能日志以统一前缀输出，便于脚本 grep 与离线解析：

关键判定原则：

• kernel_bus_bandwidth_GBps是达标对比 MUST 使用的字段；
• e2e_bus_bandwidth_GBps仅作参考，NEVER作为 Round 间对比或达标主指标。

4.2 达标口径

• 带宽：SHMEM kernel_bus_bandwidth_GBps / HCCL kernel_bus_bandwidth_GBps；
• 时延：HCCL / SHMEM（使用comm_only或kernel_us）；
• 有 baseline 时默认达标线为current ≥ baseline 的 80%；无 baseline 时（metric_only）通信算子带宽利用率NEVER 低于 20%；
• 完整达标线与判定规则见 timing-and-metrics-standard.md。

4.3[PERF]行字段语义

SHMEM 算子--perf输出单行格式为：

[PERF] pe=<id> e2e_us=<val> kernel_us=<val> algo_bandwidth_GBps=<val> e2e_bus_bandwidth_GBps=<val> kernel_bus_bandwidth_GBps=<val> bandwidth_utilization_pct=<val> payload_bytes=<val> bus_factor=<val> peak_bandwidth_GBps=<val>

HCCL baseline 输出格式与之类似，前缀为[BASELINE_PERF]，并追加api=字段指明调用的 HCCL API。

5. 公平对比：双指标与执行模型对齐

timing-and-metrics-standard.md规定每个 SHMEM 算子MUST报告两个时延指标，这是保证与 HCCL 公平对比的基础：

5.1 两种数据放置模型

由于远端 PE 只能访问对称内存（aclshmem_malloc分配），而用户input在普通 Device GM（aclrtMalloc），数据放置方式取决于通信引擎对地址类型的支持：

约束要点：

• MTE/SDMA/UDMA 下SHOULD选用做法 A，直接在 kernel 内搬运，避免无意义的 kernel 外循环；代码中 MUST 在注释中说明引擎选择（如// MTE put_nbi src=local GM, no Host-side memcpy needed）；
• RDMA 下MUST选用做法 B——双方数据都必须位于对称内存；
• 做法 A 下e2e_us ≈ kernel_us是正常现象而非问题；做法 B 下e2e_us MUST > kernel_us，差值即 kernel 外的搬运时间；
• 禁止为制造e2e_us > kernel_us的假象而在做法 A 路径上增加无意义的 kernel 外搬运；
• 设计 DSLschedule中MUST标注使用的引擎和对应放置方式（A 或 B）。

5.2 公平对比原则

HCCL API 调用时间包含其内部全部 staging 开销，因此 SHMEM 的 e2e 计时必须覆盖从用户 input(GM) 到结果 output(GM) 的全部搬运，两侧计时边界对齐：

5.3 perf 循环结构示例（做法 B）

以 all-to-all（transport, fp16）为例，phase 分解为：staging（aclrtMemcpyAsync）→ barrier（aclshmem_barrier_all）→ kernel（LaunchAlltoallHalf）→ sync。推荐的双循环打点结构：

// e2e timing — 每轮包含 staging + barrier + kernel aclrtRecordEvent(e2eStart, stream); for (int i = 0; i < iters; ++i) { aclrtMemcpyAsync(stagingSym, totalBytes, inputDev, totalBytes, ACL_MEMCPY_DEVICE_TO_DEVICE, stream); aclshmem_barrier_all(); LaunchAlltoallHalf(blockDim, stream, ...); } aclrtRecordEvent(e2eEnd, stream); // kernel-only timing — staging 已在 e2e 阶段完成 aclshmem_barrier_all(); aclrtRecordEvent(kernelStart, stream); for (int i = 0; i < iters; ++i) { LaunchAlltoallHalf(blockDim, stream, ...); } aclrtRecordEvent(kernelEnd, stream);

e2e 循环中每轮重新 staging + barrier 是为了模拟真实调用模式；staging 与 kernel 的 overlap 属于后续优化范畴。

6. 指标计算：从逻辑载荷到带宽利用率

6.1 logical_payload_bytes

统一按单 PE 语义数据量计算，输出中 MUST 标注口径：

6.2 algo_bandwidth 与 bus_bandwidth

algo_bandwidth_GBps = logical_payload_bytes / latency_s / 1e9 kernel_bus_bandwidth_GBps = algo_bandwidth_GBps(kernel) × bus_factor bandwidth_utilization_percent = kernel_bus_bandwidth_GBps / peak_bandwidth_GBps × 100

注意：algo_bandwidth不乘 2，统一按 input size 计算（遵循 NCCLalgBw惯例）。

6.3 bus_factor 参照表

bus_factor唯一参照源为 timing-and-metrics-standard.md §4.3，各 skill 中的取值 MUST 以该表为准：

6.4 peak_bandwidth 决策表

peak_bandwidth_GBpsMUST 记录来源（SoC、链路类型、PE 数、拓扑），按决策表取值：

utilization 超过 100% 时应在报告中注释可能原因（bus_factor 高估、链路实际带宽超出标称值）。

6.5 计算示例（all-to-all, fp16, 8 PE, shard_elems = 8388608）

logical_payload_bytes = 8 × 8388608 × 2 = 134,217,728 (128 MiB per PE) bus_factor = (8 - 1) / 8 = 0.875 # 假设测量值 e2e_us = 1200.0 kernel_us = 1050.0 algo_GBps (e2e) = 134217728 / (1200.0 × 1e-6) / 1e9 = 111.85 algo_GBps (kernel) = 134217728 / (1050.0 × 1e-6) / 1e9 = 127.83 bus_GBps (e2e) = 111.85 × 0.875 = 97.87 bus_GBps (kernel) = 127.83 × 0.875 = 111.85 # HCCL baseline: hccl_us = 1100.0 algo_GBps (hccl) = 134217728 / (1100.0 × 1e-6) / 1e9 = 122.02 bus_GBps (hccl) = 122.02 × 0.875 = 106.77 # 达标判断 (kernel_bus_bandwidth_GBps vs hccl baseline) ratio: 111.85 / 106.77 = 104.8% >= 80% -> PASS

7. Baseline 选择策略

性能采集需要明确的 baseline 作为对比基准（详见 baseline-selection.md），按优先级选择：

7.1 优先级 1：HCCL / aclnn 算子库

声称"无 baseline"前 MUST 逐一排查 HCCL 集合通信算子清单：

aclnn 扩展算子：AllToAllV 对应aclnnAlltoAllV；当 CANN 无独立aclnnAlltoAllV头文件时 MUST 回退HcclAlltoAllV（hccl/hccl.h），参考custom-ops/alltoallv/baseline/实现。

7.2 优先级 2：指标测试（metric_only）

既无 HCCL 对应算子也无 aclnn 扩展算子时，使用 metric_only，但 MUST 先记录已逐一排查 HCCL 清单、aclnn 扩展、已有 SHMEM example、用户参考实现的过程。测试策略包括时延测试、带宽测试与带宽利用率测量（能计算时 MUST 输出 utilization，且 NEVER 低于 20%）。

7.3 选择决策树

Step 1: 查找 HCCL 集合通信算子清单 ├─ 有完全对应 → 使用 HCCL 算子作为 baseline └─ 无 → Step 2 Step 2: 查找 aclnn 扩展算子 ├─ 有对应算子 → 使用 aclnn 算子作为 baseline └─ 无 → Step 3 Step 3: 使用指标测试（metric_only） └─ 带宽利用率 ≥ 20%

HCCL baseline 采集示例（AllToAll 打点模式）：

for (int i = 0; i < warmup; i++) { LaunchHcclBaseline(sendBuf, recvBuf, count, comm, stream); } aclrtSynchronizeStream(stream); aclrtRecordEvent(startEvent, stream); for (int i = 0; i < iters; i++) { LaunchHcclBaseline(sendBuf, recvBuf, count, comm, stream); } aclrtRecordEvent(endEvent, stream); aclrtSynchronizeStream(stream); float elapsed_ms; aclrtEventElapsedTime(&elapsed_ms, startEvent, endEvent); float avg_us = elapsed_ms * 1000.0f / iters; printf("[BASELINE_PERF] pe=%d e2e_us=%.2f kernel_us=%.2f ...", ...);

8. 性能 Case 规模要求与报告输出

8.1 规模分档

性能采集 MUST 覆盖8PE S 档 + 8PE L 档两种规模，NEVER 只采 L 档（分档标准见 testcase-scale-standard.md）：

性能前置条件：编译成功、correctness contract 通过、中等规模 case 通过（NEVER 只依赖 smoke 小 shape）。correctness 未通过时性能数据无效。

8.2 聊天与报告输出

采集完成后 MUST 在聊天界面自动输出（不等待用户追问，见 perf-chat-output-spec.md）：

块 A — S 档 + L 档性能表：

| 规模 | case_id | e2e_us | kernel_us | kernel_bus_bandwidth_GBps | utilization% | |------|---------|--------|-----------|---------------------------|--------------| | S 档 | ... | ... | ... | ... GB/s | ...% | | L 档 | ... | ... | ... | ... GB/s | ...% |

块 B — SHMEM vs Baseline 对比表（达标判定）：

| 指标 | SHMEM | HCCL baseline | SHMEM/baseline | 达标 | |------|-------|---------------|----------------|------| | kernel_bus_bandwidth_GBps | ... | ... | ...% | PASS/FAIL | | e2e_us | ... | ... | ... | — | | kernel_us | ... | ... | ... | — |

达标线：有 baseline 时默认 ≥ baseline 80%；无 baseline 时通信算子带宽利用率 ≥ 20%。同时 MUST 将对比表写入docs/performance_report.md§3.5（含kernel_bus_bandwidth_GBps对比），§7 说明达标/未达标原因；NEVER 只输出 SHMEM 单边[PERF]数据。

8.3 Device 侧片段打点

性能采集 MUST 同时覆盖端到端指标和关键 Device 片段指标，优化判断 NEVER 只依赖总耗时。kernel 中按 phase 插入SHMEMI_PROF_START(frame_id)/SHMEMI_PROF_END(frame_id)（宏定义位于 shmemi_prof.h），Host 侧在 stream 同步后调用aclshmemx_get_prof(nullptr, true)导出各 PE、block、frame 的 cycles、count 与平均耗时。frame map 至少覆盖copy_in/copy_out、remote_put_get、signal_or_barrier_wait、local_compute、finalize等主要耗时来源。参考仓库中的 profiling 模式，如 tp_allreduce_perf_host.h 中[PERF]行的 host_total 与 frame 级输出方式。

采集 MUST 记录命令、workdir、环境变量、case、重复次数和日志路径，保证可复现；默认性能路径 NEVER 永久打开 printf、DumpTensor 或重型 debug 日志。

9. 反模式清单

以下行为被明确禁止，实践中应逐条规避：

• ❌ 同一 shell / 同一次docker exec内先 SHMEM 再 HCCL（必须分阶段 + 离线 compare）；
• ❌ 同一流程内嵌启动 baseline + shmem；
• ❌ baseline 用 Python dist 代替 C++ HCCL 程序；
• ❌ 对比表只写文件路径、聊天无表格；
• ❌ 在宿主机无 NPU 环境伪造 perf 数据；
• ❌ 用 smoke 小 shape 作为性能结论；
• ❌ 只报 SHMEM[PERF]不报 baseline[BASELINE_PERF]及对比表；
• ❌ 只输出 algo_bandwidth 不输出 bus_bandwidth 与 utilization；
• ❌ 用 e2e 带宽作 Round 间对比（固定开销导致虚假"提升"）；
• ❌ baseline 与 SHMEM 使用不同 gen_data / sendcounts；
• ❌ 性能测试完成后不在聊天中自动输出结果，等用户追问。

10. 相关文档索引

• timing-and-metrics-standard.md：时间打点、双指标方案、指标计算与 bus_factor 唯一参照源
• baseline-compare-workflow.md：baseline 接入流程、日志标签、离线对比
• baseline-selection.md：HCCL/aclnn baseline 清单与决策树
• performance-eval-guide.md：采集流程概览、contract 字段、结果表格式
• perf-chat-output-spec.md：聊天自动输出规范
• device-profiling-guide.md：SHMEMI_PROF完整操作指南
• testcase-scale-standard.md：S/L 档规模定义
• custom-ops-entrypoints.md：环境链与编译/运行入口
• 仓库内 profiling 参考实现：shmemi_prof.h、tp_allreduce_perf_host.h

【免费下载链接】shmemCANN SHMEM 是面向昇腾平台的多机多卡内存通信库，基于OpenSHMEM 标准协议，实现跨设备的高效内存访问与数据同步。项目地址: https://gitcode.com/cann/shmem