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

scripts/bound_analyzer.py

View on GitHub
#!/usr/bin/env python3
"""Bound 初筛工具 — 从 msOpProf PipeUtilization.csv 输出 Bound 候选。

用法:
  python3 scripts/bound_analyzer.py --csv PipeUtilization.csv --output bound_report.json

判定规则(最终结论仍需结合带宽、时间线和源码证据):
  MTE2/CUBE/VEC/FIXP/MTE3/SCALAR BOUND、LATENCY/SYNC 可疑、OCCUPANCY 可疑、无 bound

注意(A5/dav-3510 实测教训):
  - A5 上 vector kernel 的有效数据在 aiv_* 列,aic_* 列常为 NA;cube kernel 反之。
    本工具同时读两组列名并按各自均值/峰值取大者,不要再只看 aic_*。
  - 判定用 mean(核间平均),max 仅用于识别长尾;单核峰值不能代表全 kernel。
  - block 行数远小于 SoC 物理核数(A5 典型 28 AIC / 48~56 AIV)时优先查 occupancy,
    PipeUtilization 行数本身不能区分"核数不足"与"核间不均",需结合 OpBasicInfo 的 Block Dim。
"""

from __future__ import annotations

import argparse
import csv
import json
import sys
from pathlib import Path
from typing import Any


def parse_float(value: str) -> float:
    try:
        return float(value.strip().replace("%", ""))
    except (ValueError, AttributeError):
        return 0.0


def ratio_to_pct(value: float) -> float:
    """兼容 0~1 比例和 0~100 百分数两种版本字段。"""
    return value * 100 if 0 <= value <= 1.5 else value


def load_csv(csv_path: str) -> list[dict[str, str]]:
    rows: list[dict[str, str]] = []
    with open(csv_path, encoding="utf-8-sig", errors="replace") as f:
        reader = csv.DictReader(f)
        for row in reader:
            rows.append(row)
    return rows


# 每档 Bound 的候选列名(覆盖 aic_*/aiv_* 两组 A5 实测格式 + 旧版百分数格式)
CATEGORY_COLUMNS: dict[str, tuple[str, ...]] = {
    "MTE2": ("aic_mte2_ratio", "aiv_mte2_ratio", "Mte2Utilization(%)", "mte2_ratio", "MTE2(%)"),
    "MTE3": ("aic_mte3_ratio", "aiv_mte3_ratio", "Mte3Utilization(%)", "mte3_ratio", "MTE3(%)"),
    "CUBE": ("aic_cube_ratio", "aiv_cube_ratio", "CubeUtilization(%)", "cube_ratio", "CUBE(%)"),
    "VEC": ("aiv_vec_ratio", "aic_vec_ratio", "VectorUtilization(%)", "vec_ratio", "VECTOR(%)"),
    "FIXP": ("aic_fixpipe_ratio", "aiv_fixpipe_ratio", "FixpipeUtilization(%)", "fixp_ratio", "FIXP(%)"),
    "SCALAR": ("aic_scalar_ratio", "aiv_scalar_ratio", "ScalarUtilization(%)", "scalar_ratio", "SCALAR(%)"),
}

# A5 (dav-3510) 实测物理核数参考:occupancy 可疑判定的分母
A5_TYPICAL_CORES = 48


def category_stats(rows: list[dict[str, str]], columns: tuple[str, ...]) -> tuple[float, float]:
    """返回 (mean_pct, max_pct):对每个 block 行取候选列中的最大值,再跨行统计。"""
    per_row: list[float] = []
    for row in rows:
        best = 0.0
        for col in columns:
            best = max(best, ratio_to_pct(parse_float(str(row.get(col, "")))))
        per_row.append(best)
    if not per_row:
        return 0.0, 0.0
    return sum(per_row) / len(per_row), max(per_row)


def determine_bound(rows: list[dict[str, str]]) -> dict[str, Any]:
    """从 PipeUtilization.csv 生成 Bound 候选。"""
    means: dict[str, float] = {}
    maxs: dict[str, float] = {}
    for cat, cols in CATEGORY_COLUMNS.items():
        means[cat], maxs[cat] = category_stats(rows, cols)

    max_cat = max(means, key=means.get)  # type: ignore[arg-type]
    max_mean = means[max_cat]
    max_peak = maxs[max_cat]

    bound = "无 bound"
    reason = ""
    notes: list[str] = []

    if max_mean > 80:
        bound = f"{max_cat} BOUND"
        reason = f"{max_cat} busy 核间均值 {max_mean:.1f}%(峰值 {max_peak:.1f}%),大于 80%"
    elif max_mean > 70:
        bound = f"{max_cat} BOUND"
        reason = f"{max_cat} busy 核间均值 {max_mean:.1f}%(峰值 {max_peak:.1f}%),占比最大且大于 70%"
    elif max_mean < 50:
        # 全部 pipe 低占用:不是"无 bound",是 latency/同步可疑(全 pipe 等依赖)
        bound = "LATENCY/SYNC 可疑"
        reason = (
            f"所有 pipe busy 均值均低于 50%(最高 {max_cat}={max_mean:.1f}%):"
            "排除 compute 与带宽饱和后,典型为流水未重叠、频繁同步或小包/轮询等待,"
            "按 diagnose-pipeline.md 判读规则核实用 SetFlag/WaitFlag、PipeBarrier 与跨核同步"
        )

    # 长尾提示:峰值显著高于均值说明核间不均
    if max_mean >= 50 and max_peak > max_mean * 1.25:
        notes.append(
            f"{max_cat} 峰值 {max_peak:.1f}% 显著高于均值 {max_mean:.1f}%(>{1.25}x),"
            "存在核间长尾嫌疑,按 diagnose-occupancy.md 核对各 block 行"
        )

    # occupancy 可疑:block 行数少
    if 0 < len(rows) < 16:
        notes.append(
            f"PipeUtilization 仅 {len(rows)} 个 block 行;若 OpBasicInfo 的 Block Dim "
            f"同样远小于 SoC 物理核数(A5 约 {A5_TYPICAL_CORES} AIV / 28 AIC),"
            "优先按 occupancy(核数不足/切核过少)排查,本工具的 pipe 占比仅统计已活跃核"
        )

    # 优化方向推荐
    recommendation_map = {
        "MTE2": ("数据搬运优化", [
            "references/optimize/optimize-data-copy.md",
            "references/optimize/optimize-memory-hierarchy.md",
        ]),
        "MTE3": ("数据搬出优化", [
            "references/optimize/optimize-data-copy.md",
        ]),
        "CUBE": ("Cube 利用率优化", [
            "references/optimize/optimize-ascendc-tiling.md",
            "references/optimize/optimize-catlass.md",
        ]),
        "VEC": ("Vector 利用率优化", [
            "references/optimize/optimize-api-usage.md",
            "references/optimize/optimize-pipeline.md",
            "references/optimize/optimize-memory-hierarchy.md",
        ]),
        "FIXP": ("Fixpipe 优化", [
            "references/optimize/optimize-pipeline.md",
        ]),
        "SCALAR": ("标量削减", [
            "references/optimize/optimize-api-usage.md",
        ]),
    }
    if bound == "LATENCY/SYNC 可疑":
        rec = ("流水/同步优化(latency bound)", [
            "references/diagnose/diagnose-pipeline.md",
            "references/optimize/optimize-pipeline.md",
            "references/optimize/optimize-data-copy.md",
        ])
    else:
        rec = recommendation_map.get(max_cat, ("进一步分析", [
            "references/profile/profile-msopprof.md",
        ]))

    return {
        "bound": bound,
        "reason": reason,
        "categories_mean": {k: round(v, 1) for k, v in means.items()},
        "categories_max": {k: round(v, 1) for k, v in maxs.items()},
        "notes": notes,
        "recommendation": {"direction": rec[0], "docs": rec[1]},
        "source_file": None,
        "row_count": len(rows),
    }


def main() -> int:
    parser = argparse.ArgumentParser(description="Bound 自动初筛(mean/max 双口径,含 occupancy 提示)")
    parser.add_argument("--csv", default=None, help="msprof PipeUtilization.csv 路径")
    parser.add_argument("--msprof-dir", default=None, help="msprof 输出目录,自动搜索 **/PipeUtilization.csv")
    parser.add_argument("--output", required=True, help="bound_report.json 输出路径")
    args = parser.parse_args()

    csv_path = args.csv
    if not csv_path and args.msprof_dir:
        # 自动搜索 msprof 目录下的 PipeUtilization.csv
        msprof_root = Path(args.msprof_dir)
        if not msprof_root.is_dir():
            print(f"ERROR: msprof 目录不存在: {args.msprof_dir}", file=sys.stderr)
            return 1
        candidates = list(msprof_root.rglob("PipeUtilization.csv"))
        if not candidates:
            print(f"ERROR: 在 {args.msprof_dir} 下未找到 PipeUtilization.csv", file=sys.stderr)
            print("提示: 确保 msprof op 采集时使用了 --aic-metrics=PipeUtilization", file=sys.stderr)
            return 1
        # 优先选 roofline 目录下的
        roofline = [c for c in candidates if "roofline" in str(c).lower()]
        chosen = roofline[0] if roofline else candidates[0]
        csv_path = str(chosen)
        print(f"自动选择: {csv_path}")
    if not csv_path:
        print("ERROR: 必须提供 --csv 或 --msprof-dir", file=sys.stderr)
        return 1
    if not Path(csv_path).is_file():
        print(f"ERROR: CSV 文件不存在: {csv_path}", file=sys.stderr)
        return 1

    rows = load_csv(csv_path)
    result = determine_bound(rows)
    result["source_file"] = str(Path(csv_path).resolve())

    output = Path(args.output)
    output.parent.mkdir(parents=True, exist_ok=True)
    output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n",
                      encoding="utf-8")

    print(f"Bound 判定: {result['bound']}")
    print(f"原因: {result['reason']}")
    for note in result.get("notes", []):
        print(f"提示: {note}")
    if "recommendation" in result:
        print(f"优化方向: {result['recommendation']['direction']}")
        print(f"参考文档: {', '.join(result['recommendation']['docs'])}")
    print(f"结果已保存: {output}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
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: 118kUpdated 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