magpie-kernel-evaluator

Magpie

使用 Magpie 完成以下三项相关工作：

1. 对推理工作负载进行基准测试，并收集吞吐量、延迟和跟踪记录。
2. 分析或比较 GPU 内核的正确性和性能。
3. 推进优化循环：从基准测试瓶颈出发，追溯到源代码和候选内核，并进行端到端验证。

仅描述当前检出版本的 Magpie 支持的功能。不要推断其支持未经验证的 ROCm、GPU、框架或实验性集成。

选择工作流

用户目标	工作流
评估一种实现	analyze
对两种或更多实现进行排名	compare
测量模型服务性能	benchmark
在现有跟踪记录中查找开销较大的内核	独立间隙分析
说明经过性能分析的推理工作负载	benchmark → TraceLens 后处理 → 阶段/屋顶线审查
优化端到端工作负载	benchmark → TraceLens/间隙分析 → 源代码映射 → analyze/compare → 重新运行基准测试

如需可复现或多步骤操作，请使用 YAML 配置。小规模探索性运行可使用内联 CLI 参数。

预检

安装此技能不会安装 Magpie 应用程序（magpie-eval）。如果用户只要求准备，请阅读提供的测试文件和 reference.md，编写所需的计划或配置，并指出仍未验证的命令。如果用户禁止安装软件包或执行工作负载，请勿安装或执行；即使未安装 Magpie，也可以准备计划。

执行 Magpie 工作负载之前：

1. 在目标 Python 环境中检查 magpie --help（Python 3.10+）。如果找不到该命令，请在同一环境中尝试 python -m Magpie --help；如果模块入口可用，可改用它而非 CLI。No module named Magpie 表示该环境中未安装应用程序。对于已安装的 Magpie 软件包内部报错，应改为诊断所报告的导入或依赖故障。

2. 如果尚未安装 Magpie，请先在目标环境中安装：

   python -m pip install git+https://github.com/AMD-AGI/Magpie.git
   

   如果已有 Magpie 源代码检出，请改用 python -m pip install -e /path/to/Magpie。已安装的技能文件夹和 testcase 工作区都不是 Magpie 源代码检出。重新运行 magpie --help 或 python -m Magpie --help，以验证安装；如果失败，请先报告错误，再尝试运行工作负载。

3. 检查所选工作流对应的已安装接口（如果使用模块入口，请将 python -m Magpie 代入）：

   magpie --help
   magpie analyze --help
   magpie compare --help
   magpie benchmark --help
   magpie --gpu-info
   

4. 根据需要检查必需工具、模型访问权限、GPU 可见性、可写输出空间，以及容器或 Ray 访问权限。安装 Python 软件包不会安装 ROCm/CUDA、性能分析器或模型权重。

5. 在说明版本支持情况之前，先阅读仓库兼容性矩阵。对于其中未列出的 ROCm 或硬件，在测试前一律视为未经验证。

6. 进行基准测试比较时，记录准确的配置、模型修订版本、镜像、环境变量、GPU 分配和 Magpie 提交版本。

分析内核

如果正确性或性能分析器设置很重要，请优先使用配置：

magpie analyze --kernel-config path/to/kernel.yaml

如需快速运行单个内核：

magpie analyze path/to/kernel.hip --type hip --testcase "./run_test.sh"

受支持的公开内核类型包括 hip、cuda、pytorch 和 triton。只有当用户需要验证正确性或执行情况而不进行性能分析时，才使用 --no-perf。

不要将成功执行等同于数值正确。若要据此接受或拒绝优化结果，请提供有代表性的测试用例。

比较内核变体

至少比较两种实现，并明确指定基线：

magpie compare --kernel-config path/to/compare.yaml

确保所有候选项使用相同的输入、容差、预热设置、迭代次数、GPU 分配和性能分析器设置。在考虑性能排名之前，先淘汰未通过正确性检查的候选项。

对于没有测试用例的 PyTorch，Magpie 内置检查只会验证每个结果是否为有限值；它不能证明不同变体之间数值等价。数值验证必须提供测试用例。

基准推理

优先使用已提交到仓库的基准配置：

magpie benchmark --benchmark-config path/to/benchmark.yaml

稳定版公共 CLI 支持 vllm、sglang 和 atom。它支持直接使用 docker 和 local 运行模式；分布式执行请使用 YAML 配置和仓库中的 Ray 示例。不要将仅存在于内部枚举或不完整代码路径中的集成宣传为稳定功能。

谨慎启用性能分析：分析器运行会扰动延迟，不应取代干净的基线。使用等效工作负载比较吞吐量、已完成请求数、TTFT、TPOT、ITL 和端到端延迟。

使用 TraceLens 后处理跟踪

在经过性能分析的基准 YAML 中启用 TraceLens；torch 跟踪是其必需输入：

benchmark:
  profiler:
    torch_profiler:
      enabled: true
    tracelens:
      enabled: true
      analysis_mode: inference
      analysis_stages: all
      export_format: csv

对于 vLLM/SGLang，使用 analysis_mode: inference。有可用阶段时，它会将 rank-0 跟踪拆分为 prefilldecode、decode 和 prefill 阶段，运行 TraceLens 后处理，并在基准工作区的 tracelens/ 目录下写入完整的阶段报告以及精简的 *_kernel_roofline_simple.csv 文件。若要直接生成 PyTorch 跟踪报告，请使用 analysis_mode: pytorch。

先查看精简的 roofline CSV。按 kernel_time_ms_sum 或 time_pct 对行排序；然后使用 roofline_bound、算术强度、实测 TFLOP/s 或 TB/s 以及 pct_roofline_mean，形成优化假设。将后处理视为成功之前，请确认 benchmark_report.json.tracelens_analysis 中有输出且没有错误。如果任务明确需要传统的直接单 rank 或多 rank 集体报告，请使用 analysis_mode: pytorch。

Magpie 集成的 TraceLens 阶段会生成 CSV/Excel 分析产物，而不是由 Agent 编写的 analysis.md。如果用户要求优先级排序的 Agent 报告，且已安装独立的 tracelens-analysis-orchestrator 技能，请将捕获的跟踪传给它；并将该结果与 Magpie 的基准报告区分开来。

分析现有跟踪并查找源代码

直接在 benchmark 上使用 --trace-dir 运行独立的间隙分析：

magpie benchmark \
  --trace-dir path/to/torch_trace \
  --top-k 20 \
  --find-kernel-sources \
  --kernel-source-repos path/to/repository

不要插入 gap-analysis 位置参数；它不是 CLI 子命令。检查生成的汇总 CSV 和每个 rank 的 CSV，并保留源代码映射的置信度，不要假定每个规范化的内核名称都能唯一映射。

推进优化循环

1. 运行未启用性能分析的基准测试，并保存其配置和报告。
2. 再次运行，并启用 torch 性能分析和 TraceLens inference 后处理。
3. 查看阶段级 TraceLens roofline 摘要，将主导操作归类，并判断可能受计算、内存或通信限制。
4. 对有代表性的稳态窗口运行间隙分析，为具体内核排序。
5. 根据总贡献选择瓶颈，而不只看单次调度时长。
6. 将选定的内核映射到源代码和可执行测试用例。
7. 生成隔离的候选实现；保留基线。
8. 使用 analyze 进行迭代，然后通过带正确性门槛的 compare 为候选方案排序。
9. 使用获胜方案和相同工作负载，重新运行最初未启用性能分析的基准测试。报告内核级和端到端的变化，包括性能回退。

如果正确性尚未得到证明、基准输入发生变化、源代码映射不确定，或端到端改进处于多次运行的噪声范围内，请勿宣称成功。

在可用时使用 MCP 工具

对于硬件检查、内核发现、配置生成、分析/比较、优化建议、结果查询、报告比较、Ray 作业管理和基准测试批次等结构化 Agent 工作流，优先使用 Magpie MCP 工具。

不要将 CLI 的 analyze_report.json 封装对象直接传给需要单个结果对象的 performance_state 和 performance_result 的 MCP 工具。不要假设 MCP 支持每个 CLI 选项；目前只有 CLI 间隙分析路径提供内核源代码补充信息。

其他资源

• 完整 CLI 参考：reference.md
• 可直接复制粘贴的命令示例：examples.md