Magpie 是一个面向 LLM 推理基准测试与 GPU 内核优化的工具，本技能将其能力接入智能体工作流。它把三类相互关联的工作串联起来：对推理负载做基准测试并采集吞吐量、延迟和 trace；分析或比较 GPU 内核的正确性与性能；以及从基准测试发现的瓶颈出发，驱动“定位源码—生成候选内核—端到端验证”的优化闭环。
用途与工作流选择
根据用户目标选择工作流：评估单个实现用 analyze；对两个及以上实现排名用 compare；测量模型服务性能用 benchmark；在已有 trace 中查找高开销内核用独立的 gap analysis；解释已剖析的推理负载走 benchmark → TraceLens 后处理 → stage/roofline 审查；优化端到端负载走 benchmark → TraceLens/gap 分析 → 源码映射 → analyze/compare → 重新基准测试。可复现或多步骤工作建议使用 YAML 配置，小型探索性运行可用内联 CLI 参数。
预检与安装
安装本技能不会安装 Magpie 应用（magpie-eval）。若用户仅要求准备方案，应读取提供的 fixtures 和 reference.md，写出所需计划或配置，并标明尚未验证的命令；用户禁止时不要安装包或执行负载。执行前需在目标 Python 环境（Python 3.10+）检查 magpie --help；若命令缺失，可尝试 python -m Magpie --help，可用的模块入口可替代 CLI。提示 No module named Magpie 表示该环境未安装应用；若已安装包内部报错，应诊断具体的导入或依赖失败。未安装时可在目标环境安装：python -m pip install git+https://github.com/AMD-AGI/Magpie.git；若已有源码检出，改用 python -m pip install -e /path/to/Magpie。安装后重新运行 magpie --help 或 python -m Magpie --help 验证。还需检查所需工具、模型访问、GPU 可见性、可写输出空间以及容器或 Ray 访问；安装 Python 包不会安装 ROCm/CUDA、profiler 或模型权重。做版本声明前应阅读仓库兼容性矩阵，未列出的 ROCm 或硬件在测试前视为未验证。基准比较需记录确切的配置、模型版本、镜像、环境变量、GPU 分配和 Magpie commit。
分析内核
正确性或 profiler 设置重要时优先用配置：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 分配和 profiler 设置需保持一致；先剔除正确性失败的候选，再考虑性能排名。对于没有测试用例的 PyTorch，Magpie 内置检查只验证结果有限，不证明变体间数值等价，数值验证需提供测试用例。
推理基准测试
优先使用已检入的基准配置：magpie benchmark --benchmark-config path/to/benchmark.yaml。稳定的公开 CLI 支持 vllm、sglang、atom，支持直接 docker 和本地运行模式；分布式执行使用 YAML 配置和仓库的 Ray 示例。不要将仅存在于内部枚举或部分代码路径的集成宣传为稳定。启用剖析需谨慎：profiler 运行会扰动延迟，不应替代干净的基线。比较吞吐量、完成请求数、TTFT、TPOT、ITL 和端到端延迟时应使用等价负载。
用 TraceLens 后处理 trace
在剖析基准 YAML 中启用 TraceLens，torch trace 是其必需输入：
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 trace 拆分为 prefilldecode、decode 和 prefill 阶段，运行 TraceLens 后处理，并在基准工作区的 tracelens/ 目录下写出完整阶段报告和紧凑的 *_kernel_roofline_simple.csv 文件。直接 PyTorch trace 报告使用 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 有输出且无错误后，才视为后处理成功。Magpie 集成的 TraceLens 阶段产出 CSV/Excel 分析产物，而非智能体撰写的 analysis.md；若用户需要优先级化的智能体报告，可在安装后把捕获的 trace 交给独立的 tracelens-analysis-orchestrator 技能，并与 Magpie 基准报告区分开。
分析已有 trace 并定位源码
在 benchmark 上直接用 --trace-dir 运行独立 gap 分析：
magpie benchmark
--trace-dir path/to/torch_trace
--top-k 20
--find-kernel-sources
--kernel-source-repos path/to/repository
不要插入 gap-analysis 位置参数，它不是 CLI 子命令。检查生成的聚合和每 rank CSV，保留源码映射的置信度，不要假设每个归一化内核名都唯一映射。
驱动优化闭环
先运行未剖析的基线基准并保存其配置和报告；再启用 torch 剖析和 TraceLens 推理后处理重复运行；审查阶段级 TraceLens roofline 摘要，对主导操作分类并判断可能的计算、内存或通信限制；在代表性稳态窗口上运行 gap 分析以对具体内核排名；按总贡献而非仅单次调度时长选择瓶颈；将选定内核映射到源码和可执行测试用例；生成隔离的候选实现并保留基线；用 analyze 迭代，再用带正确性门禁的 compare 对候选排名；用获胜候选和相同负载重新运行原始未剖析基准，报告内核级和端到端变化，包括回退。若正确性未证明、基准输入改变、源码映射不确定或端到端改进在运行间噪声范围内，应停止而不宣称成功。
MCP 工具
有 Magpie MCP 工具时优先用于结构化智能体工作流，如硬件检查、内核发现、配置生成、analyze/compare、优化建议、结果查询、报告比较、Ray 作业管理和基准批次。不要把 CLI 的 analyze_report.json 包装直接传给期望单个结果对象 performance_state 和 performance_result 的 MCP 工具；不要假设每个 CLI 选项在 MCP 中都存在，内核源码增强目前由 CLI gap 分析路径暴露。
其他资源
完整 CLI 参考见 reference.md，可复制命令示例见 examples.md。