profile-model

在 MAX 上对模型进行性能分析

此技能可解答有关任何可在 MAX 上运行的模型的三个问题，无论它是内置架构，还是通过 --custom-architectures 加载的自定义架构：

1. 我的 GPU 确实在工作吗？（利用率、内存、时钟频率）
2. 模型的大部分时间花在哪里？（哪些内核／阶段）
3. 这个内核为什么慢？（占用率、停顿、屋顶线分析）

它适用于通过 pip 或 pixi 安装的 MAX，可驱动公开的 max CLI 或 Python 脚本。

如何决定运行什么

每个问题都需要比前一个问题更深入、开销更大的采集。请从成本最低的检查开始，逐步深入，并根据每一步的结果决定是否值得继续——采集内容不要超出问题所需。

1. 先检查利用率。如果工作负载运行时 GPU 空闲或负载较低，瓶颈就在主机端（CPU、数据传输、小批量）——到此为止并报告这一情况。内核跟踪无法提供任何 GPU 繁忙时无法告诉你的信息。
2. 如果 GPU 繁忙，则采集内核细分数据。这是最常见的情况，通常也就是最终答案：它会显示哪些内核占用了大部分 GPU 时间。
3. 只有在某个内核占主导，且你需要了解其原因时，才对该内核进行单内核深度分析。除非细分数据已指向特定内核，否则请跳过此步骤——它会多次重放该内核，耗时较长。

你要解答的问题	工具	开销
GPU 是否繁忙？	max.profiler.gpu（纯 Python，支持 NVIDIA + AMD）	几秒钟，无需额外安装
时间花在哪里？	max ... --profile，或 nsys（NVIDIA）／rocprofv3（AMD）	几次性能分析运行
单个内核为什么慢？	Nsight Compute（ncu），仅限 NVIDIA	每个内核采集一次，耗时较长

请阅读当前步骤的参考文档，而不要一次性加载所有文档：

• 利用率检查 → references/utilization-api.md（以及随附的 scripts/gpu_snapshot.py）
• 内核细分，NVIDIA → references/nsys.md
• 内核细分，AMD → references/rocprofv3.md
• 单内核深度分析（NVIDIA） → references/ncu.md

使用 --custom-architectures 加载的模型

自定义架构的性能分析方式与内置架构相同。不同之处在于加载过程：自定义架构有额外的前置条件和故障模式——与已安装 MAX 版本的导入兼容性、PYTHONPATH 陷阱、架构名称冲突、没有聊天模板的基础模型，以及 max serve 对自定义嵌入模型的限制。这些问题会在任何性能分析开始之前阻止模型加载。如果你正在分析通过 --custom-architectures 传入的模型，请先阅读 references/custom-architectures.md。

阅读结果（内核组合告诉了你什么）

性能分析回答两个问题：GPU 是否已饱和（利用率检查），以及时间都花在哪里（内核细分）。将你看到的情况对应到诊断：

• Decode 由 gemv_split_k_* GEMV 主导，*_mha_* attention 和 rms_norm 排在其后——这是稠密 LLM 生成 token 时正常且健康的形态（decode 中 GEMV 受内存带宽限制）。无需进一步排查。
• 稀疏 MoE decode 由分组／块缩放矩阵乘法和路由内核主导——每个专家的分组矩阵乘法（*grouped*／block_scaled_* 矩阵乘法）是主导内核，而非稠密 GEMM；同时还会有 top-k 路由（topk_*、moe_create_indices）以及专家 gather/scatter。在多 GPU 场景下，还会出现 EP dispatch／combine 集合通信。这是 Mixture-of-Experts 模型健康的形态——路由和 gather 开销在预期之内，只有在其开销接近矩阵乘法本身时才值得排查。
• 低位权重（FP8／FP4／NVFP4）会增加量化准备内核——除矩阵乘法外，还会看到动态激活量化和缩放布局内核（*quantize*、*block_scales*），以及块缩放矩阵乘法变体，而不是普通的 gemv／gemm。低位模型花费时间进行量化／反量化准备是正常的；只有在其耗时远超所服务的矩阵乘法时才需要关注。内核前缀因 GPU 架构而异（Blackwell 上为 sm100_*，Hopper／MI 上则不同）——应按内核类别匹配，而非精确名称。
• 自定义架构未命中预期的融合内核（例如，attention 显示为通用的 elementwise／matmul，而非 *_mha_* 内核，或者归一化／RoPE 未融合）——这是接线方面的信号：即使 logits 检查通过，计算图的构建方式也可能与你想的不一样。系统初次接入时值得检查。
• decode tok/s 极低，且每一步都重复出现大量 prefill 形态的内核组合——这是典型的 O(n²) 重复 prefill（KV cache 缺失或损坏）。这是与正确性相关的 bug，不只是速度慢。
• 工作负载运行时 gpu_usage_percent 较低——受主机限制、启动／同步开销过高，或批次过小；瓶颈不在 GPU。
• 存在节流原因——GPU 受时钟限制；在解决散热／功耗问题之前，数据不具代表性。

持久有效的算法

工具和 MAX 打包方式经常变化；值得保留的是这一套方法。无论运行哪种采集，都请遵循以下步骤：

1. 先检测环境，再选择工具。运行 nvidia-smi 或 rocm-smi 了解 GPU 厂商 — 按内核分类和深入分析的工具因厂商而异。确认分析器已安装（which nsys / which rocprofv3 / which ncu）；如果缺少，请告知用户确切的安装命令（参见参考资料），不要等到执行一半才失败。
2. 启动任何长时间运行的任务前先确认。对 max serve 进行性能分析会预热编译缓存（冷编译可能需要几分钟）、启动服务并运行基准测试。在执行这些操作前，向用户展示模型、标志和计划执行的命令，并等待确认。对于小型模型，一次性运行 max generate --profile 的开销很小，可以跳过确认。
3. 先预热缓存，再进行性能分析。模型首次运行时会产生一次性编译和权重加载开销，掩盖实际的内核耗时。先运行一次不带性能分析的预热，然后再运行带性能分析的任务，这样采集到的才是稳定状态下的推理数据，而不是编译过程。
4. 缩短采集窗口。并发数为 1 时，10 秒的窗口足以了解内核组成。长时间采集会生成体积庞大的跟踪文件，打开速度慢，提供的信息却不会更多。
5. 尽早发现错误。启动服务后，先在几秒内检查进程是否存活、日志中是否出现早期错误（找不到模型、OOM、标志无效），然后再开始轮询 /health。如果服务已经退出，不要继续等待完整超时。
6. 验证产物，然后汇报。确认输出文件存在且大小并非微不足道，再宣称任务成功。汇报产物路径、打开方式和关键数据（排名靠前的内核或 GPU 峰值利用率）。
7. 只清理自己启动的任务。终止自己启动的服务或基准测试进程组。在共享机器上避免使用范围过广的 pkill -f max — 这可能会停止其他人的任务。

Nightly 与 stable 版本

性能分析功能会先进入 nightly，再进入 stable，因此此技能面向 nightly 版 max-serve。使用 pixi 安装：

pixi init quickstart -c https://conda.modular.com/max-nightly/ -c conda-forge
cd quickstart && pixi add max-serve
pixi run max --version          # expect a *.dev build

利用率 API（GPUDiagContext、BackgroundRecorder）随 conda 的 max 包一起发布，因此请通过 pixi 或 conda 安装，而不是使用普通的 pip install max wheel，因为它可能不包含 max.profiler.gpu。如果下方某条命令返回 404，或导入失败，请确认你使用的是较新的 nightly 版本。

安装说明

• MAX 本身：通过 pixi 安装了 nightly 版 max-serve 包的项目（参见上文的 Nightly 与 stable 版本）。下方所有 max CLI 命令都假定你可以在该项目中运行 pixi run max ...。max-serve 包包含使用 MAX 提供模型服务所需的额外依赖项；主 max 包不包含这些依赖项。
• nsys 和 ncu 随 CUDA Toolkit 一起提供。如果 which nsys 失败，但 CUDA 已安装，请运行 export PATH=/usr/local/cuda/bin:$PATH。否则，请从 NVIDIA 安装 Nsight Systems / Nsight Compute，或运行 sudo apt-get install nsight-systems。
• rocprofv3 随 ROCm 一起提供（/opt/rocm/bin）。如有需要，请将其添加到 PATH。
• 利用率 API 除 max 外无需其他工具 — 它通过 max.profiler.gpu 直接与 NVML / ROCm SMI 通信。

快速路径

最省事的命令，每条命令的详细说明见对应的参考文件：

• “我的 GPU 正在使用吗？” → 搭配简短的基准测试运行 scripts/gpu_snapshot.py。纯 Python，适用于 NVIDIA 和 AMD。
• “快速给我一份内核分类结果。” → pixi run max generate --model <m> --prompt "hello" --num-warmups 1 --profile。输出按排名排列的 GPU 内核 Top-N 表格 并写入 .nsys-rep（NVIDIA）。没有 GPU 时则回退到 CPU 摘要。
• “分析我的服务基准测试。” → 使用 MODULAR_ENABLE_PROFILING=detailed 配合 nsys launch / rocprofv3 的服务端点流程。