msAgent

当用户需要部署 msmodeling optix 服务化自动寻优工具时使用。负责安装与验证。

当首次使用 msmodeling optix 的用户需要根据硬件、模型、负载和优化目标推荐 MindIE/vLLM 寻优参数、搜索范围、benchmark 侧字段或 config.toml 片段时使用。

指导并自动化完成昇腾 NPU 上 MindSpeed-LLM 训练的 Profiling 数据采集。支持配置并运行带 Profiling 的模型训练，包括 CPU 采集、内存采集、不同采集级别（level0/level1/level2）和自定义 step 范围。生成的 Profiling 数据可用 MindStudio Insight 进行性能分析。当用户需要在模型训练中采集 Profiling 数据、进行训练性能分析、或执行 性能数据采集/Profiling采集 时触发。触发关键词：profiling、性能分析、性能数据采集、Profiling采集、训练框架profiling、MindSpeed-LLM profiling。

指导并自动化完成昇腾 NPU 上 MindSpeed-MM 模型训练的 Profiling 数据采集。通过识别训练脚本，自动找到配置文件并启用内置 Profiler，支持静态采集（指定起止 step）和动态采集（运行时动态开关），支持 Megatron 引擎（tools.json）和独立 FSDP2 引擎（YAML）两种配置方式。生成的 Profiling 数据可用 MindStudio Insight 进行性能分析。当用户需要在多模态模型训练中采集 Profiling 数据、进行训练性能分析、或执行 性能数据采集/Profiling采集 时触发。触发关键词：profiling、性能分析、性能数据采集、Profiling采集、多模态训练profiling、MindSpeed-MM profiling。

Skill for analyzing communication performance bottlenecks and detecting slow/fast rank issues in Ascend NPU systems. Use this skill whenever you need to analyze communication efficiency, data transfer bottlenecks, or identify slow/fast rank problems using profiling data.

用于分析Ascend NPU系统中计算性能瓶颈的技能，专注于算子效率和计算优化

分析MindStudio Insight采集的profiling数据识别快慢卡，以及分析系统trace文件识别Host侧进程性能问题。当用户需要分析NPU卡间性能差异或Host侧进程瓶颈时调用。

华为昇腾NPU性能分析技能集，**当用户提供Profiling文件或目录路径时必须使用**，用于分析Profiling数据识别计算、通信、下发等性能瓶颈，支持step_trace_time.csv、op_statistic.csv、kernel_details.csv等多种数据格式，提供完整的性能分析流程和优化建议。

使用 torch_npu.profiler 在非 MindSpeed-LLM 与非 MindSpeed-MM 的训练/推理脚本中采集 Ascend NPU Profiling 数据。覆盖 level0/level1/level2 采集级别、训练循环/单次推理/指定代码段三种方式，支持 .py 和 .sh 脚本路径。当用户需要性能采集、性能分析、查看算子耗时、定位训练瓶颈时使用。触发关键词：profiling、性能采集、性能分析、算子耗时、瓶颈定位、torch_npu.profiler。

大模型训练MFU (Model FLOPs Utilization) 计算工具。在用户需要计算MFU、评估训练效率、分析模型性能、或提到FLOPs、吞吐量、硬件利用率时自动应用。支持Dense和MoE模型，提供详细的性能分析报告。

Generate msmodelslim evaluation YAML configuration (service_oriented + aisbench + vllm-ascend). Use when user asks for evaluation config generation.

End-to-end automated model quantization and accuracy tuning workflow. Use when user asks for automated model quantization and accuracy tuning, e.g. "自动量化", "量化调优", "一键量化", "精度调优", etc.

多卡分布式训练中的 loss/gnorm 精度溢出检测与根因追溯。基于 MSProbe dump 数据，先跨 rank 定位首次出现 NaN 的源卡，再在源卡上追溯具体的溢出根因算子。 当用户需要：(1) 多卡分布式训练场景下的 NaN/Inf 溢出检测 (2) 找出首先出现 NaN 的源卡 (3) 追溯根因计算算子 (4) loss/gnorm NaN 问题定位 时使用此 skill。

分析 PyTorch memory snapshot pickle 文件（_dump_snapshot 导出的内存快照），提供内存峰值、碎片、泄漏、OOM 检测与交互式 HTML 报告。仅当用户明确提及 memory snapshot、内存快照、_dump_snapshot、pickle 内存文件 或需要对 snapshot pickle 做内存分析时才触发，不处理一般的 NPU 性能分析、SQLite 查询或通用内存问题。

专门用于 Ascend 集群 Profiling 性能数据的“快慢卡”诊断专家技能。当用户提供【集群性能数据目录/路径】并要求分析【快慢卡】、【慢节点】、【负载不均衡】或【集群瓶颈】时，必须触发此技能。该技能会自动接收集群路径，调度相关工具输出快慢卡的宏观定性与微观根因（如 Host 下发瓶颈、算子计算劣化）。

Analyze Ascend NPU collective communication profiling data with a DB-first workflow. Use when the user provides `cluster_analysis_output/cluster_analysis.db`, rank-level `analysis.db`, rank-level `ascend_pytorch_profiler_{rank_id}.db`, together with `profiler_info.json`, and asks about HCCL or hcom communication cost, collective communication TOP ops, wait time, slow rank/straggler, Notify Wait, bandwidth, retry, relay, SDMA/RDMA/HCCS links, communication matrix, or Ascend communication fault patterns.

MindStudio Profiler Analyze（msprof-analyze）是面向 AI 训练与推理场景的性能分析工具，基于采集得到的 profiling 数据进行统计、比对和诊断，帮助定位计算、通信、调度及集群场景下的性能瓶颈。

当用户提供 MindStudio profiler 采集的性能数据（框架 profiler、msprof 命令行）时，对数据完整性、采集状态及关键配置进行校验，确保后续分析工具能正常运行。

面向 Ascend PyTorch Profiler / msprof DB（如 ascend_pytorch_profiler*.db、msprof_*.db）的 SQL 分析技能。将自然语言问题（算子耗时、通信、下发、调度、schema/table 查询）转为安全可执行 SQL，并按需从官方文档提取表结构详情。

计算算子（如 matmul/GEMM）的 MFU（Machine FLOP Utilization），并给出清晰的公式和推导过程。

执行模型测评。通过 scripts/run_evaluation.py 依据 Evaluation YAML 对量化模型进行评测。

Use when 量化调优闭环中需要生成或修改一轮调优所需的 Practice YAML，包括敏感层分析、策略决策、写出 YAML 文件和校验。

训练与推理数据不一致的端到端根因分析。当模块映射/值比较不足以定位问题时使用，可追踪首个可信的分歧边界，过滤融合或结构性误报，遵循生产者-消费者链，并生成包含具体假设和证据的根因报告。

Use when diagnosing NPU + PyTorch or LLM Serving Host CPU affinity, NUMA locality, cgroup/cpuset constraints, CPU range conflicts, PyTorch/runtime threading, DataLoader, tokenizer, scheduler, vLLM-Ascend, SGLang, TTFT, TPOT, tokens/s, QPS, or multi-rank/multi-worker CPU binding issues.

为 msModelSlim 适配器执行功能性验证。适用于基础适配器开发完成后，自动执行四步验证（测试模型、全回退量化、权重一致性与可加载/保存、实际量化规则校验）并输出通过/失败结论。

为 msModelSlim 适配流程注入反量化能力。先识别模型权重是否可反量化，再实现反量化脚本并接入 model_adapter。当前仅覆盖 FP8 的 per-block 与 per-channel 两类；若格式不确定或无公开反量化规则，要求用户提供反量化脚本或浮点权重。

执行模型量化。通过 msmodelslim quant 依据 Practice YAML 对模型进行量化。

在需要根据自然语言规格为未支持硬件新增或更新 DeviceProfile 设备画像条目时使用

Install and verify the msmodeling development environment. Use when the user explicitly asks to install msmodeling dependencies, set up this repository, create `myenv` with `uv`, install this repository's `requirements.txt`, set project `PYTHONPATH`, or configure `HF_ENDPOINT`; if the user only says to install an environment, ask whether they mean msmodeling dependencies before proceeding.

Interactively gather parameters for `python -m cli.inference.throughput_optimizer`, generate a deployment simulation command, explain assumptions, ask for execution confirmation, then run the simulation and summarize the best parallel strategy. Use when the user wants to evaluate a model on one or more hardware profiles, compare hardware targets, compare aggregation versus disaggregation versus PD ratio optimization, choose TP/EP/MOE-DP search ranges, or obtain recommended concurrency, throughput, TTFT, and TPOT results from throughput modeling.

Analyze Ascend NPU schedule, operator dispatch, operator launch, and Host Bound profiling issues in Ascend profiling data. Use when need to diagnose device Free time, framework/operator dispatch latency, launch latency, PYTORCH_API/CANN_API launch gaps, aclrtSynchronizeStream stalls, task queue behavior, CPU scheduling interference, GC/lock pauses, CPU affinity, or schedule-side optimization actions.

Analyze Ascend NPU computation-side profiling data for single-card runs or a selected rank from multi-card runs. Use this skill when the user asks to diagnose computation bottlenecks, AI Core / AI Vector / AICPU hotspots, dynamic shape overhead, block dim issues, redundant TransData/Transpose/Cast, cross-stream waits, frequency/runtime-state issues, or fusion opportunities.

为 msModelSlim 创建基础 Transformers 模型适配器（Model Adapter）。 包含创建适配器、实现必需接口与注册安装流程。 适用：Decoder-only LLM、理解类 VLM（仅 LLM/text 部分）。 不适用：多模态生成模型（图像/视频/语音生成）、Encoder-only、非 Transformers 架构。

执行msProbe数据比对并分析比对结果，定位确定性计算问题首个输入一致输出不一致的API。

为 msModelSlim 适配器实现逐层量化（按层加载/懒加载）能力。仅在用户明确要求逐层量化或基础适配因 CPU 内存不足无法全量加载权重时使用。该特性为高阶可选项，不是基础适配必需项。

在实现适配器前对候选模型做分析。确定模型实现来源（transformers 或模型目录）、结构特征、内存约束下的逐层量化建议（可选）及 MoE 融合权重风险。适用于用户询问模型适配可行性或做适配前分析时使用。

提供 msModelSlim 的通用快速量化指引，包含安装、最简 YAML 配置与基础执行校验。适用于用户询问 msmodelslim 安装、快速量化、配置 yaml、linear_quant 或 minmax 基础参数时。

基于 msprof op 工具的端到端 Ascend NPU 算子性能调优技能。当用户提供算子源码目录，并要求使用 msprof op 完成从性能采集、瓶颈分析、代码优化到优化效果验证的完整闭环时，必须使用此 skill。典型触发词包括"端到端调优"、"代码优化"、"msprof op 调优"、"完整调优"、"性能优化闭环"、"端到端"、"调优全流程"。此 skill 自动执行：编译运行 → msprof op 上板/仿真性能采集 → 瓶颈诊断 → 代码优化 → 重新采集 → 优化前后性能对比。注意：此 skill 专门使用 msprof op 工具进行性能采集和分析，覆盖 msot-msopprof-operator-profiler（纯分析），并额外包含编译运行和性能采集的自动化流程。

当用户希望使用 msOpProf（`msprof op` / `msprof op simulator`）对昇腾 AI 算子做上板或仿真性能调优、解释 `aic-metrics`/`trace.json`/`visualize_data.bin`、选择 device vs simulator 路径、排查 `--soc-version`/`--export`/`signal 6`/`Bad address`/热点图或流水图相关问题，或要求生成固定分析报告模板（算子基本信息 / 关键数据 TOP5 / 核心瓶颈 TOP5 / 优化建议 TOP5）时，使用本技能。它负责先判定模式、输入形态与芯片/能力边界，再给出正确命令、结果解读、固定报告输出与高频踩坑规避；不要把经验案例当成通用规则。

当用户希望你像第一次接触项目的人一样，真实按仓库的 README、安装文档或 quick start 跑一遍，并判断“新人能不能走通”“文档是否可用”“哪里会卡住”“安装/启动说明是否对新手友好”时，使用这个 skill。它适用于 repo onboarding audit、documentation UX review、quickstart validation、README walkthrough、按文档验证安装与运行并输出问题报告的场景；即使用户只是说“按 README 试一下”“帮我检查这个仓库文档能不能跑通”“看看 quick start 为什么带不动新人”，也应触发。不要用于纯翻译、润色、摘要、风格对比、治理项检查，或只想直接修环境/修单个报错而不做完整文档体验审查的请求。