docs(perf): profile CUDA graph coverage and PLE costs on Spark

2026-09-18 01:22:13 +08:00
parent f1a8964072
commit d7e1e745c3
23 changed files with 8384 additions and 1 deletions
@@ -0,0 +1,38 @@
+# Nsight Systems 诊断脚本
+
+固定 nightly `0bfc7a15`、当前 PLE 适配，单 GPU、串行请求。
+方案见 [plan.md](plan.md)。这些脚本是实验工具，不是默认启动入口。
+
+- `prepare.py prepare --data ...`：使用正在运行的同一模型生成 8K/32K 固定检索数据并预检 token 数。
+- `instrument.py`：读取同目录 `vllm_ple_mmap.original.py` 和 `cudagraph_utils.original.py`，
+  精确匹配源码后生成临时 NVTX 版本；保持算子签名与计算不变。原始文件来自容器，不提交重复副本。
+- `client.py --label eager|graph`：在测试容器内运行，数据挂到 `/profiles/data`，密钥读挂载文件。
+  三轮正常计时和三次独立 trace；所有请求相同，temperature=0、seed=42、reasoning_effort=low。
+- `monitor.py`：在 Spark 宿主机运行，写资源采样到 stdout；以脚本目录中的文件发出停止信号。
+  必须在启动实验前启动监控，并配套退出后恢复原配置的 runner。保护是尽力而为，不能保证拦截瞬时 OOM。
+- `summarize_trace.py <trace.sqlite> ...`：导出 CUDA/NVTX 汇总，不读取进程命令行和环境。
+
+Nsight 使用主机安装目录只读挂载到 `/opt/nsight`。临时服务添加：
+
+```text
+--max-model-len 131072 --profiler-config '{"profiler":"cuda"}'
+```
+
+在原有 `vllm serve ...` 前包裹：
+
+```text
+/opt/nsight/bin/nsys profile --sample=none --trace=cuda,nvtx,osrt \
+  --capture-range=cudaProfilerApi --capture-range-end=repeat:3 --kill=none \
+  --trace-fork-before-exec=true --cuda-graph-trace=node --force-overwrite=true \
+  -o /profiles/<label>/trace vllm serve ...
+```
+
+临时将服务绑定到容器回环地址，客户端使用 `docker exec`；保留已有缓存、代理和 secret 挂载。
+PLE 和 CudaGraphManager 的标记文件分别只读覆盖原模块，不修改镜像或权重。
+测试时自动重启关闭；原 Compose 保留备份，退出时恢复并做健康及 smoke 检查。
+
+计时阶段没有启动 capture，但 Nsight launcher 和 NVTX 包装仍存在；本轮不是完全卸载 profiler 的独立测速。
+node 级采样可能增加开销，因此 trace 时长只用作诊断，不能代替无采样阶段排名。
+CPU API、NVTX 和 GPU 时间存在重叠；GPU busy 是 kernel/copy/memset 区间并集，
+分母为首次至末次 GPU 活动的时间跨度，不是 SM 利用率、带宽利用率或完整 HTTP 延迟。
+原始 `.nsys-rep` / SQLite 可能包含进程参数，只保留在 Spark 的受限目录，不提交 Git。