企业官网建设流程全解析

PyASC 算子上板性能调优：asc.metrics_prof_stop 接口详解与 msProf 采集范围控制

【免费下载链接】pyasc本项目为Python用户提供算子编程接口，支持在昇腾AI处理器上加速计算，接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc

本文聚焦 PyASC 的asc.language.basic.metrics_prof_stop()接口，说明它与asc.metrics_prof_start()配对指定 msProf 性能数据采集范围的使用方式，并结合当前仓库源码解析该接口从 Python 调用、AscIR 算子定义到 Ascend C 代码生成的完整实现链路。读完本文，你不仅知道如何正确插入这对接口来圈定需要调优的 kernel 侧代码段，还能从源码层面确认它们在 PyASC 编译管线中的落点与验证方式。

1. 接口定义与对应的 Ascend C 原型

metrics_prof_stop()是 PyASC 提供的算子侧（kernel 侧）性能数据采集控制接口，用于设置"性能数据采集信号停止"，必须与asc.metrics_prof_start()配合使用。在 API 参考页 asc.language.basic.metrics_prof_stop 中，接口的定义如下：

asc.language.basic.metrics_prof_stop() → None

其对应的 Ascend C 函数原型为：

__aicore__ inline void MetricsProfStop()

两个关键约束：

• 参数：无。
• 返回值：无。

接口文档中的标准调用示例为：

asc.metrics_prof_stop()

2. 典型使用场景：用 msProf 圈定算子内的调优代码段

metrics_prof_start()（见 asc.language.basic.metrics_prof_start）与metrics_prof_stop()是一对"开关"。当使用 msProf 工具进行算子上板调优时，可以在 kernel 侧代码段的前后分别调用这两个接口，以指定需要调优的代码段范围。典型的 kernel 侧写法如下（结构示意，具体数据搬运与计算代码以实际算子为准）：

import asc from asc.language.core import GlobalTensor, LocalTensor # kernel 入口函数（由 PyASC JIT 编译后上板执行） def my_kernel(...) -> None: # ... 加载数据、准备 tile ... asc.metrics_prof_start() # 数据采集开始信号 # —— 需要调优的核心代码段（如循环内的向量计算、Cube 计算）—— # ... asc.metrics_prof_stop() # 数据采集停止信号 # ... 收尾、回写结果 ...

使用要点：

1. 必须成对使用：metrics_prof_start()与metrics_prof_stop()分别插在待测代码段的前、后，形成闭合的采集区间；
2. 面向上板调优：该接口用于真实 NPU 上运行时配合 msProf 工具采集指定区间的性能指标，属于性能调优（profiling）类接口，而非功能计算接口；
3. 无状态、无参数：接口本身不携带任何配置，采集范围完全由成对调用位置决定。

3. PyASC 源码实现：从 Python 调用到 AscIR 算子

从源码结构看，metrics_prof_stop()在 PyASC 中是一条"零参数、纯副作用"的 trace 型接口，其实现位于 dump_tensor.py：

@overload def metrics_prof_stop() -> None: ... @require_jit @set_common_docstring(api_name="metrics_prof_stop") def metrics_prof_stop() -> None: builder = global_builder.get_ir_builder() builder.create_asc_MetricsProfStopOp()

可以从源码中读出三个实现细节：

• @require_jit装饰器：接口只能在 PyASC 的 JIT trace 上下文中被调用，即 kernel 函数体被 PyASC 编译器追踪时执行。Python 层面调用后并不直接产生任何硬件动作，而是由global_builder.get_ir_builder()在当前 builder 位置创建一条 IR 算子；
• create_asc_MetricsProfStopOp()：生成的 IR 算子名为ascendc.metrics_prof_stop，与 start 接口对应的是ascendc.metrics_prof_start；
• @set_common_docstring：API 参考文档（即本文开头的asc.language.basic.metrics_prof_stop.md）通过统一的 docstring 机制与该实现关联，保证文档与代码的签名一致。

3.1 AscIR 算子定义

metrics_prof_stop对应的 AscIR 方言算子在 TableGen 中定义于 OpDumpTensor.td：

def AscendC_MetricsProfStartOp : APIOp<"metrics_prof_start","MetricsProfStart", [AscFunc]> { let description = "Start performance metrics collection for a code region; pair with MetricsProfStop."; } def AscendC_MetricsProfStopOp : APIOp<"metrics_prof_stop","MetricsProfStop", [AscFunc]> { let description = "Stop performance metrics collection started by MetricsProfStart."; }

两个要点：

• 该算子属于APIOp类（Ascend C API 算子），携带AscFunctrait，算子第二参数即目标函数名MetricsProfStop，说明它最终会被映射为对 Ascend CMetricsProfStop()的内联调用；
• 从 description 字段可见，"start/stop 成对使用"是算子定义层面的既定语义，与 API 文档的说明一致。

3.2 代码生成验证：lit 测试确认输出

仓库中的 lit 测试 dump_tensor.mlir 验证了ascendc.metrics_prof_stop被翻译为 Ascend C 代码时的确切输出：

// CHECK-LABEL:void emit_metrics_prof_stop() { // CHECK-NEXT: AscendC::MetricsProfStop(); // CHECK-NEXT: return; // CHECK-NEXT: } func.func @emit_metrics_prof_stop() { ascendc.metrics_prof_stop return }

可以看到，ascendc.metrics_prof_stop算子在最终生成的 C++ 代码中就是裸调用AscendC::MetricsProfStop();——这与 API 文档给出的__aicore__ inline void MetricsProfStop()原型一一对应。start 接口在同一测试文件中有完全对称的用例（AscendC::MetricsProfStart();）。

4. 运行验证方式与相关设施

PyASC 用两类测试覆盖这对接口：

1. Python 端单测：test_common_api.py 中的test_metrics_prof_stop用例，在mock_launcher_run环境下定义一个仅调用asc.metrics_prof_stop()的 kernel 函数，并以kernel_metrics_prof_stop[1]()的形式触发执行链路（下标1为 PyASC 的 block 数调用参数），验证接口在 trace 与上板启动流程中可用；start 接口有对应的test_metrics_prof_start用例；
2. 代码生成 lit 测试：如第 3.2 节所示，用 FileCheck 校验 Ascend C 源码输出，保证从 IR 到代码的翻译稳定。

此外，仓库在python/asc/lib/profiling/下提供了 msProf 相关的 profiling 支持模块（如 msprof.py），可在上板性能分析场景中与本文介绍的 kernel 侧采集区间配合使用；具体参数以该模块当前实现与运行时环境为准。

5. 小结与注意事项

• asc.metrics_prof_stop()无参数、无返回值，语义是"性能数据采集信号停止"，必须与asc.metrics_prof_start()成对使用，用于在使用 msProf 进行算子上板调优时圈定待测代码段；
• 在 PyASC 中，该调用在 JIT trace 期生成ascendc.metrics_prof_stop算子（dump_tensor.py），该算子由 OpDumpTensor.td 定义，最终在生成的 Ascend C 代码中输出为AscendC::MetricsProfStop();；
• 该接口仅在 kernel 侧、PyASC JIT 编译上下文中有效（@require_jit），不适用于 host 侧普通 Python 代码；
• 如需进一步阅读，可对照 API 文档 asc.language.basic.metrics_prof_stop 与 asc.language.basic.metrics_prof_start，以及测试用例 test_common_api.py 和 lit 测试 dump_tensor.mlir。

【免费下载链接】pyasc本项目为Python用户提供算子编程接口，支持在昇腾AI处理器上加速计算，接口与Ascend C一一对应并遵守Python原生语法。项目地址: https://gitcode.com/cann/pyasc