用途:为 Isaac Lab 3.0+ 独立模式及其他不含 Kit/Carbonite 的 Python 应用做函数级 NVTX 性能剖析,这类场景下 CARB_PROFILING_PYTHON 无效。
主要能力:借助捆绑的 scripts/sitecustomize.py 安装带 NVTX 区间的 sys.setprofile() 钩子。用 PYTHONPATH 加载该辅助脚本,避免写入环境已有的 sitecustomize.py;禁用时只需取消 PYTHONPATH 或 NVTX_PROFILE_PYTHON 即可。
安装与启用:# uv pip install nvtx;将技能 scripts 目录加入 PYTHONPATH,例如: NVTX_SKILL_DIR="${NVTX_SKILL_DIR:-$PWD/.agents/skills/nvtx-python}" test -f "$NVTX_SKILL_DIR/scripts/sitecustomize.py" export PYTHONPATH="$NVTX_SKILL_DIR/scripts:${PYTHONPATH:-}" 环境变量:NVTX_PROFILE_PYTHON 设为 1 启用;NVTX_PROFILE_INCLUDE 指定追踪的模块前缀(逗号分隔,空为全部);NVTX_PROFILE_EXCLUDE 指定排除的模块前缀(默认 importlib)。
与 Nsight Systems 配合:示例命令 PYTHONPATH="$NVTX_SKILL_DIR/scripts:${PYTHONPATH:-}" NVTX_PROFILE_PYTHON=1 nsys profile -t nvtx,cuda,osrt uv run python <脚本> 建议用 NVTX_PROFILE_INCLUDE 限定范围以降低开销。
限制:每次函数调用/返回都会触发回调,追踪全部模块开销显著;Isaac Lab / Kit 宿主会覆盖 sys.setprofile,需在导入后调用 sitecustomize.install() 重新挂载(该函数幂等并重读环境变量)。即使重装,sys.setprofile 仍为每线程,threading.setprofile 只能捕获 Python threading 创建的线程,Kit / PhysX / Hydra / Fabric / TBB 原生线程不可见,env.step() 大多运行于这些线程。原生侧覆盖请改用 CARB_PROFILING_PYTHON=1,或对关注函数用 @nvtx.annotate 装饰。nsys 也支持 --python-functions-trace 选项。