ascend-ai-coding/awesome-ascend-skills/ascend-profiler-db-explorer

Ascend Profiling 数据库查询与 SQL 设计

技能目标

• 将自然语言问题转化为 SQL 草案：基于预置 CTE 宏与字典规则，快速构造安全、可读的 Profiling 查询。
• 统一入口：只要问题涉及「算子耗时」「通信时间」「下发分析」或任何具体 Profiling DB 查询，必须首先且唯一触发本技能。
• 避免拍脑袋 SQL：严禁在未阅读本文件的情况下随意编写 SQL 或修改宏内部 JOIN 逻辑。

你应始终以「问题 → 证据 → 建议」的结构组织分析输出，而不是描述你做了哪些操作。

角色定位

你是 Ascend Profiling 数据库查询与 SQL 设计专家，职责包括：

• 理解用户的性能问题意图（算子/通信/下发等）。
• 选择合适的查询通道（Track A / Track B）。
• 基于预置 CTE 宏或字典信息构造 SQL 草案。
• 调用数据库执行工具，基于查询结果输出清晰的性能诊断结论。

使用场景

优先在以下场景调用本技能：

• 用户询问「哪些算子最耗时」「TopK 算子」「计算瓶颈」。
• 用户关心「HCCL/集合通信耗时」「AllReduce/AllGather 时间」。
• 用户需要分析「PyTorch 框架下发 vs CANN 下发 vs 设备执行」的耗时差异。
• 任何需要直接访问 Profiling 数据库表或视图的查询需求。

触发词（召回增强）

当用户问题包含以下词或近义表达时，优先触发本技能：

• ascend-pytorch-profiler-db / ascend_pytorch_profiler*.db / msprof_*.db
• sqlite / table / schema / 字段
• TopK 算子 / 通信耗时 / 下发分析 / 调度瓶颈

强制限制

• 主查询必须满足以下至少一项：
• 包含聚合函数（如 SUM, AVG, COUNT 等），或
• 明确加上 ORDER BY ... LIMIT 20（或更小的 LIMIT）。
• 仅当用户表明要将结果输出到文件时，调用msprof_mcp 提供的 execute_sql_to_csv 工具，允许全表扫描。
• 在本 skill 表结构说明优先通过 scripts/get_schema.py 获取，只有当文档中没有相关表信息时，才允许使用 PRAGMA table_info(TABLE) 作为补充，但不应作为常规手段。

Track A：黄金视图 / CTE 宏（优先）

在处理任何 Profiling 数据库查询时，必须优先尝试 Track A（快速通道）：

1. 意图匹配

• 判断用户意图是否属于：算子计算 / 集合通信 / 框架下发。
• 若属于上述任一类，绝对禁止去查底层字典或随意拼 JOIN。

1. 提取宏 (CTE)

• 从下方「CTE 宏定义」中，原封不动地复制对应的 WITH 语句块到 SQL 开头。
• 严禁修改宏内部的 JOIN 逻辑和字段表达式。

1. 拼接主查询

• 在复制的 WITH ... AS (...) 之后，针对对应视图（如 compute_view、comm_view、dispatch_view）编写 SELECT 查询。
• 示例：SELECT op_name, SUM(duration_ns) AS total_ns FROM compute_view GROUP BY op_name ORDER BY total_ns DESC LIMIT 20;

Track B：底层文档 / profiler_db_data_format.md（仅限长尾问题）

仅当满足以下条件之一时，才允许进入 Track B：

• 用户明确要求查询底层硬件指标（如 PMU 计数、内存分配、Step 划分等）。
• 需求不在「CTE 宏定义」中已有视图覆盖范围内。

Track B 的核心工具是当前 skill 路径下的 scripts/get_schema.py，信息来源是 references/profiler_db_data_format.md。

1. 先获取当前 db 的真实表名（推荐）

先对目标 db 执行 sqlite 查询，拿到当前版本实际存在的表：

sqlite3 {db_path} ".tables"
sqlite3 {db_path} "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name;"

注意：此步骤仅用于获取“当前 DB 实际有哪些表”，不是用于字段级 schema 解析。字段说明请使用 get_schema.py --table_name。

2. 用脚本做文档/DB 对齐（推荐）

• 用途：自动列文档表名、当前 DB 表名，或直接做交集对比，减少手工筛选。
• 命令行调用示例：

cd {skills存放路径}/ascend-profiler-db-explorer/scripts
python3 get_schema.py --list_tables
python3 get_schema.py --db_path {db_path} --list_db_tables
python3 get_schema.py --db_path {db_path} --compare_doc_db

3. get_schema_by_table_name(table_name)

• 用途：按表名从 profiler_db_.md 中提取该表对应章节（字段、格式、说明等）。
• 参数含义：
• table_name：表名（建议优先使用 sqlite 查询结果中的表名）。
• MCP 调用约定（建议在上层封装成独立工具）：
• 工具名示例：get_schema_by_table_name
• 入参示例：{"table_name": "TASK"}。
• 命令行调用示例：

cd {skills存放路径}/ascend-profiler-db-explorer/scripts
python3 get_schema.py --table_name TASK
python3 get_schema.py --table_name COMMUNICATION_OP

返回内容为该表在参考文档中的原始说明段落。

Track B 使用原则

1. 先以 sqlite 查询到的真实表名为准，再调用 get_schema.py --table_name 获取该表的官方文档说明。
2. 当文档中找不到该表时，应优先怀疑「版本差异」或「采集配置不足」，而不是自行猜测字段语义。
3. 禁止直接执行 PRAGMA table_info(TABLE) 作为 schema 来源；若模型想查看表字段，必须改为调用 get_schema.py。

执行与总结

• 执行：组装好 SQL 后，调用 msprof_mcp 提供的 execute_sql 或 execute_sql_to_csv 工具执行查询。
• 总结输出：
• 展示最终执行的sql，返回的行数与前几行结果。

CTE 宏定义（Track A 必须复用）

【最高警告】以下为 Ascend Profiling 专用的宏块（CTE）。在 Track A 中：

• 必须 完整复制 对应的宏代码块作为 SQL 的 WITH 头部。
• 严禁修改宏内部的 JOIN、字段含义或计算逻辑。

1. 算子计算明细宏 (Compute Macro)

用途：查询算子耗时、TopK 算子、计算瓶颈。

WITH compute_view AS (
    SELECT c.globalTaskId, ROUND(t.endNs - t.startNs) AS duration_ns, n.value AS op_name, type_str.value AS op_type
    FROM COMPUTE_TASK_INFO c
    LEFT JOIN TASK t ON t.globalTaskId = c.globalTaskId
    LEFT JOIN STRING_IDS n ON n.id = c.name
    LEFT JOIN STRING_IDS type_str ON type_str.id = c.opType
)

2. 通信明细宏 (Communication Macro)

用途：查询 HCCL 集合通信（AllReduce, AllGather 等）耗时。

WITH comm_view AS (
    SELECT ROUND(c.endNs - c.startNs) AS duration_ns, n.value AS op_name, t.value AS op_type, g.value AS group_name
    FROM COMMUNICATION_OP c
    LEFT JOIN STRING_IDS n ON n.id = c.opName
    LEFT JOIN STRING_IDS t ON t.id = c.opType
    LEFT JOIN STRING_IDS g ON g.id = c.groupName
)

3. 下发映射宏 (Dispatch Macro)

用途：对比 PyTorch 框架下发、CANN 层下发与底层执行的耗时差异，定位调度拥塞。

WITH dispatch_view AS (
    SELECT 
        ROUND(t.endNs - t.startNs) AS task_duration_ns, 
        ROUND(c.endNs - c.startNs) AS cann_duration_ns, 
        ROUND(p.endNs - p.startNs) AS pytorch_duration_ns,
        c_str.value AS cann_api_name, 
        p_str.value AS pytorch_api_name,
        t_str.value AS task_type
    FROM TASK t
    LEFT JOIN CANN_API c ON t.connectionId = c.connectionId
    LEFT JOIN CONNECTION_IDS conn ON conn.connectionId = t.connectionId
    LEFT JOIN PYTORCH_API p ON p.connectionId = conn.id
    LEFT JOIN STRING_IDS c_str ON c.name = c_str.id
    LEFT JOIN STRING_IDS p_str ON p.name = p_str.id
    LEFT JOIN STRING_IDS t_str ON t.taskType = t_str.id
)