Nsight Graphics CLI 技能
官方 NVIDIA Nsight Graphics 活动的命令行编排。
能力
- 探测已安装的 Nsight 二进制文件和兼容模式
- 在 Nsight 下分离启动应用程序
- 将 Nsight 附加到正在运行的 PID
- 触发图形捕获或 OpenGL 帧调试器捕获
- 触发 GPU Trace 捕获、自动导出和汇总
- 通过
ngfx-replay分析已有的.ngfx-capture文件 - 为
.ngfx-gputrace输入提供清晰的兼容性诊断 - 触发生成 C++ 捕获
命令
doctor
cli-anything-nsight-graphics --json doctor info
cli-anything-nsight-graphics --json doctor versions
cli-anything-nsight-graphics --nsight-path "C:\Path\To\Nsight Graphics 2024.2\host\windows-desktop-nomad-x64" --json doctor info
launch
cli-anything-nsight-graphics launch detached --activity "Graphics Capture" --exe "C:\Path\To\App.exe"
cli-anything-nsight-graphics launch attach --activity "Graphics Capture" --pid 12345
帧捕获
cli-anything-nsight-graphics --output-dir D:\captures frame capture ^
--exe "C:\Path\To\App.exe" ^
--wait-frames 10
GPU Trace
cli-anything-nsight-graphics --output-dir D:\traces gpu-trace capture ^
--exe "C:\Path\To\App.exe" ^
--start-after-ms 1000 ^
--limit-to-frames 1 ^
--auto-export ^
--summarize
cli-anything-nsight-graphics gpu-trace summarize ^
--input-dir D:\traces
回放分析
cli-anything-nsight-graphics --json replay analyze ^
--capture-file D:\captures\frame.ngfx-capture ^
--output-dir D:\analysis
生成 C++ 捕获
cli-anything-nsight-graphics --output-dir D:\cpp cpp capture ^
--exe "C:\Path\To\App.exe" ^
--wait-seconds 5
Agent 说明
- 优先使用
doctor info以发现可用的兼容模式。 - 当存在多个 Nsight Graphics 版本时，使用
doctor versions列出已检测到的安装。 - 使用
--nsight-path强制指定特定的安装目录或ngfx.exe。 - 对于程序化工作流，使用
--json。 - 对于一步式性能排查，优先使用
gpu-trace capture --auto-export --summarize。汇总信息包括导出的表格清单、指标清单、帧预算分类、工作负载分类、吞吐量排名、瓶颈提示以及空事件/规约表的警告。 - 当输入为已有的
.ngfx-capture文件时，使用replay analyze。未指定分析开关时，它会导出元数据、日志、捕获的日志错误和回放性能报告，然后添加结构化的analysis.highlights/analysis.warnings。 ngfx-replay文档说明其输入应为图形捕获文件。.ngfx-gputrace输入可用于清晰的诊断，但在 Nsight Graphics 2026.1.0 上可能报告Invalid file header；对于导出的 GPU Trace 表格分析，请使用gpu-trace summarize。replay analyze使用官方的ngfx-replay元数据/日志/截图/性能报告输出；它不是类似 RenderDoc 的着色器、管线、纹理或资源检查器。- 帧/GPU/C++ 捕获命令需要通过
--exe指定启动目标，或通过预先配置的根级别--project指定。 - 如果全局的
cli-anything-nsight-graphics命令指向旧的工作树，请从nsight-graphics/agent-harness重新安装，使用python -m pip install -e .。