Skip to content

Ascend/msagent / skills/operator/ops-performance-tuning

ops-performance-tuning

Verified

Compile, profile, diagnose, optimize, and compare Ascend NPU operators across CANN versions and A2/A3/A5 for Ascend C, CATLASS, Triton-Ascend, TileLang-Ascend, PyPTO, and SHMEM/MC2. Use when an operator already has a runnable implementation and the user asks for msOpProf collection, bottleneck analysis, source-level tuning, or a reproducible before/after performance report. Do not use as the primary workflow for operator creation, migration, or unresolved correctness failures.

FileKindSize
SKILL.mdskill md15.4 KB
evals/evals.jsonconfig3.6 KB
references/case-routing.mdmarkdown30.0 KB
references/cases/ascendc/pr_ascendc_allgathermm_scalar_align.mdmarkdown1.7 KB
references/cases/ascendc/pr_ascendc_cann_samples_perf_story.mdmarkdown3.9 KB
references/cases/ascendc/pr_ascendc_cgdr_vf_inverse.mdmarkdown1.6 KB
references/cases/ascendc/pr_ascendc_conv3ddx_tque_tbuf.mdmarkdown1.6 KB
references/cases/ascendc/pr_ascendc_layernorm_areg.mdmarkdown1.6 KB
references/cases/ascendc/pr_ascendc_logit_a5_microapi.mdmarkdown1.9 KB
references/cases/ascendc/pr_ascendc_matmul_case_18x.mdmarkdown1.5 KB
references/cases/ascendc/pr_ascendc_matmul_full_load_wiki.mdmarkdown1.6 KB
references/cases/ascendc/pr_ascendc_matmul_vcv_wiki.mdmarkdown1.8 KB
references/cases/ascendc/pr_ascendc_mc2_fusion.mdmarkdown1.4 KB
references/cases/ascendc/pr_ascendc_mhc_24x.mdmarkdown1.2 KB
references/cases/ascendc/pr_ascendc_msopprof_add_block_imbalance.mdmarkdown1.7 KB
references/cases/ascendc/pr_ascendc_quantize_a2_micro_opt.mdmarkdown2.0 KB
references/cases/ascendc/pr_ascendc_rotate_quant_blaze.mdmarkdown2.8 KB
references/cases/ascendc/pr_ascendc_tiling_l2_official.mdmarkdown1.6 KB
references/cases/catlass/pr_catlass_baseline.mdmarkdown1.3 KB
references/cases/catlass/pr_catlass_fixpipe_dualdst.mdmarkdown1.6 KB
references/cases/catlass/pr_catlass_grouped_matmul_tiling.mdmarkdown1.5 KB
references/cases/catlass/pr_catlass_mstuner_3p8x.mdmarkdown1.9 KB
references/cases/catlass/pr_catlass_swizzle_balance.mdmarkdown1.6 KB
references/cases/pypto/pr_pypto_gqa_decode_vector_merge.mdmarkdown2.4 KB
references/cases/pypto/pr_pypto_l2_hit_layout_s13.mdmarkdown1.9 KB
references/cases/pypto/pr_pypto_per_matmul_tile_shapes.mdmarkdown2.4 KB
references/cases/pypto/pr_pypto_small_shape_matmul.mdmarkdown2.3 KB
references/cases/pypto/pr_pypto_weight_none_cacheable.mdmarkdown2.6 KB
references/cases/shmem/pr_shmem_alltoallv_mr152.mdmarkdown2.4 KB
references/cases/shmem/pr_shmem_reduce_scatter_serial.mdmarkdown2.6 KB
references/cases/tilelang/pr_tilelang_benchmark_vs_ascendc.mdmarkdown1.7 KB
references/cases/tilelang/pr_tilelang_compiler_prs.mdmarkdown2.3 KB
references/cases/tilelang/pr_tilelang_fa_pr698.mdmarkdown1.5 KB
references/cases/tilelang/pr_tilelang_gqa_bwd_pr1494.mdmarkdown1.3 KB
references/cases/tilelang/pr_tilelang_persistent_mqa_decode.mdmarkdown2.2 KB
references/cases/tilelang/pr_tilelang_sfa_pr665.mdmarkdown914 B
references/cases/triton/pr_triton_atomic_simd_24x.mdmarkdown1.8 KB
references/cases/triton/pr_triton_autotune_background.mdmarkdown1.0 KB
references/cases/triton/pr_triton_constexpr_recompile.mdmarkdown1.1 KB
references/cases/triton/pr_triton_lgamma_simt.mdmarkdown1.6 KB
references/compile/compile-ascendc.mdmarkdown9.0 KB
references/compile/compile-catlass.mdmarkdown2.4 KB
references/compile/compile-pypto.mdmarkdown2.0 KB
references/compile/compile-shmem.mdmarkdown2.6 KB
references/compile/compile-tilelang.mdmarkdown2.7 KB
references/compile/compile-triton.mdmarkdown4.4 KB
references/diagnose/diagnose-l2-cache.mdmarkdown2.2 KB
references/diagnose/diagnose-occupancy.mdmarkdown4.0 KB
references/diagnose/diagnose-pipeline.mdmarkdown4.1 KB
references/diagnose/diagnose-roofline.mdmarkdown3.1 KB
references/optimize/optimize-api-usage.mdmarkdown1.7 KB
references/optimize/optimize-ascendc-regbase-vf.mdmarkdown5.9 KB
references/optimize/optimize-ascendc-tiling.mdmarkdown935 B
references/optimize/optimize-catlass.mdmarkdown3.0 KB
references/optimize/optimize-data-copy.mdmarkdown870 B
references/optimize/optimize-index.mdmarkdown3.6 KB
references/optimize/optimize-memory-hierarchy.mdmarkdown599 B
references/optimize/optimize-pipeline.mdmarkdown1.0 KB
references/optimize/optimize-pypto.mdmarkdown1.5 KB
references/optimize/optimize-shmem.mdmarkdown5.1 KB
references/optimize/optimize-tilelang.mdmarkdown1.7 KB
references/optimize/optimize-triton.mdmarkdown3.8 KB
references/profile/benchmark-harness.mdmarkdown2.2 KB
references/profile/profile-msopprof.mdmarkdown7.4 KB
references/troubleshooting.mdmarkdown5.8 KB
scripts/bound_analyzer.pyscript9.0 KB
scripts/delta_report.pyscript4.8 KB
scripts/env_check.shscript5.0 KB
scripts/result_saver.pyscript5.0 KB

references/compile/compile-triton.md

View on GitHub
# Triton-Ascend 算子工程:编译、运行、验证、单测方法

> 本文档目的:整理 triton-ascend 框架的算子工程方法(简介与仓库地址、依赖版本、编译命令、运行/验证方法、单测方式)。多框架总览与环境速查见 [算子类型路由](../case-routing.md)。

## 2. triton-ascend

### 2.1 简介与仓库

Triton 语言的 Ascend NPU 后端。仓库:<https://github.com/triton-lang/triton-ascend>(README 含完整安装文档);GitCode 镜像:<https://gitcode.com/Ascend/triton-ascend>。

### 2.2 环境与版本对齐

Python、CANN、PyTorch、torch_npu 与 Triton-Ascend 必须采用目标 release 兼容表中的同一组版本;不得固化某个历史 README 快照的推荐版本。

```bash
git rev-parse HEAD
rg -n "CANN|torch_npu|Python|compatib|version" README* docs/ 2>/dev/null
python3 -c 'import torch, torch_npu, triton; print(torch.__version__, torch_npu.__version__, triton.__version__)'
```

### 2.3 安装(编译)

```bash
# 方式一:兼容表指定的 wheel
python3 -m pip install triton-ascend==<compatible-version> --extra-index-url=https://mirrors.huaweicloud.com/ascend/repos/pypi
# 方式二:源码
python3 -m pip install ninja cmake wheel pybind11
git clone https://github.com/triton-lang/triton-ascend.git && cd triton-ascend
python3 -m pip install -e .
# LLVM、clang/lld 和容器基础镜像按该分支安装文档准备。
```

### 2.4 运行/验证方法

与上游 Triton 一致——`@triton.jit` 写 kernel,配合 torch/torch_npu 张量直接调用;首次调用时 JIT 编译(Triton IR → Ascend 后端 → CCE 二进制)。典型下游用法见 sgl-kernel-npu、vllm-ascend。

### 2.5 单测方式

(PR 模板原文)`/test` 跑 lit 测试、`/unittest` 跑 C++ 单测、`/python/test` 跑端到端测试;仓库根目录有 `test/`(lit)、`unittest/`(C++ gtest)目录。

### 2.6 性能分析入口

docs/en/debug_guide/profiling.md(<https://github.com/triton-lang/triton-ascend/blob/main/docs/en/debug_guide/profiling.md>):board profiling 分析 tiling(如 block dim 超过 48 个 vector core 导致 host 调度开销)、仿真流水图定位 MTE2/VECTOR 流水中断、代码热点(scalar 指令占比过高 → 优化标量计算/向量化)。

### 2.7 环境修复与 SoC 配套(实测:Ascend950PR / CANN 9.1)

`import torch_npu` 成功不代表可用——**真正的可用性门禁是"最小 triton kernel 上板跑通"**(见 §2.4,vector add 级别)。环境修复按以下顺序排查:

1. **`Unsupported soc version: Ascend950PR 9579`**:torch_npu 版本太旧不认识 950PR。实测 torch_npu 2.6.0.post5 报错,2.11.0/2.12.0 可用;公开 issue 中 950PR 可用组合为 torch 2.10 + torch_npu 2.10 + triton-ascend 3.2.1(同代组合均可先试)。torch 用 `+cpu` wheel(`--index-url https://download.pytorch.org/whl/cpu`)可同时满足 torch-npu 的 `torch==X+cpu` 依赖钉。
2. **triton-ascend wheel 与 CANN 头文件不兼容**:pypi 的 triton-ascend 3.2.0 的 `npu_utils.cpp` 引用已被 CANN 9.1 改名的枚举(`RT_LIMIT_TYPE_SIMT_WARP_STACK_SIZE`→`RT_LIMIT_TYPE_SIMT_STACK_SIZE`),运行时 JIT 编译 npu_utils 失败;更新版本(3.2.1+)或按报错改名打补丁。
3. **kernel 启动 207000("This feature is not supported",plog 中 `Custom hand fail! name=<kernel>`)**:import 和 JIT 编译都成功但 launch 被运行时拒绝。实测区分两类:① 后端整体不支持该 SoC(简单 add kernel 也挂)→ 换配套组合;② 仅复杂 kernel 挂(开发中 fork 的 codegen 不完整)→ 换正式 release 后端。**不要在这种状态下调性能**。
4. **新 API 缺失**(如 `tl.insert_slice`):kernel 用了比本机 triton-ascend 更新的语言 API,属于工具链版本不足,只能升级/源码构建后端——按任务边界这属于开发工作,不是性能调优,标记 `BLOCKED` 并记录所需 API。
5. **triton-ascend 的元数据依赖**:`torch-npu` 在 pypi 上钉 `torch==X+cpu`;triton-ascend 对 scipy/pytest/psutil/pandas 等有版本钉,用 venv 隔离安装避免污染系统环境;`import triton` 需要 `pybind11`、`yaml`(pyyaml)等隐式依赖,缺失时逐个补装。
6. 版本配套查询入口:`pip index versions torch-npu` / `pip index versions triton-ascend`(pypi 只发布到 3.2.0,更新版本在 GitCode release 或源码构建)。
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall