# 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。