本文档记录了在Docker容器中挂载并使用NVIDIA Nsight Systems (nsys) 性能分析工具的完整流程。

一、背景

1.1 什么是nsys？

NVIDIA Nsight Systems (nsys) 是一个系统级性能分析工具，用于：

- 分析GPU程序的性能瓶颈

- 追踪CUDA kernel执行时间

- 分析CPU-GPU并行度

- 可视化程序执行时间线

1.2 为什么需要在Docker中使用nsys？

- 开发环境通常在Docker容器中

- 需要分析容器内运行的程序性能

- 便于性能调优和问题定位

 二、完整挂载流程

Step 1: 查找开发机上nsys的安装路径

**命令**：

```bash

which nsys

```



**示例输出**：

```

/usr/local/cuda-12.8/bin/nsys

```



**说明**：

- 首先确认开发机上nsys的实际安装路径

- 不同机器可能安装在不同位置

- 常见路径：`/usr/local/cuda-*/bin/nsys` 或 `/opt/nvidia/nsight-systems/*/bin/nsys`

Step 2: 启动Docker容器并挂载nsys

**完整命令**：

**关键参数说明**：

docker run -itd \

  --shm-size=64g \

  --name nsys_test \

  --gpus all \

  --runtime=nvidia \

  --privileged \

  -v /home/users/nsys_test/project/horizon_j6_open_explorer_v3.7.0-py310_20251215:/open_explorer \

  -v /home/data:/data/horizon_j6/data \

  -v /usr/local/cuda-12.8:/usr/local/cuda-host:ro \

  hub.hobot.cc/aitools/ai_toolchain_ubuntu_22_j6_gpu:v3.7.0

| 参数 | 说明 |

|------|------|

| `--privileged` | **必需**，nsys需要系统级权限访问性能计数器 |

| `--gpus all` | 使用所有GPU |

| `--runtime=nvidia` | 使用NVIDIA runtime |

| `-v /usr/local/cuda-12.8:/usr/local/cuda-host:ro` | 挂载开发机的CUDA工具链到容器，`:ro`表示只读 |

| `--shm-size=64g` | 设置共享内存大小，大模型训练需要 |

 Step 3: 进入容器并验证

**进入容器**：

```bash

docker exec -it nsys_test bash

```

**验证nsys可用**：

```bash

/usr/local/cuda-host/bin/nsys --version

```

**预期输出**：

```

NVIDIA Nsight Systems version 2024.6.2.xxx

```

Step 4: 配置环境变量（可选但推荐）

**方法1：临时添加（当前会话有效）**

export PATH="/usr/local/cuda-host/bin:$PATH"

nsys --version

**方法2：永久添加到bashrc**

echo 'export PATH="/usr/local/cuda-host/bin:$PATH"' >> ~/.bashrc

source ~/.bashrc

**方法3：创建别名**

echo 'alias nsys="/usr/local/cuda-host/bin/nsys"' >> ~/.bashrc

source ~/.bashrc

三、常见问题与解决方案

问题1: `bash: groups: command not found`

**原因**：在`docker run`时使用`-e PATH=...`覆盖了容器默认的PATH，导致找不到基本系统命令。

**错误示例**：

docker run -itd \

  --env PATH="/opt/nvidia/nsight-systems/2024.5.1/bin/:${PATH}" \

  ...

**解决方案**：

- 不要在`docker run`时设置PATH环境变量

- 进入容器后再手动设置PATH

问题2: `bash: nsys: command not found`

**原因**：挂载路径不正确，或nsys不在预期的bin目录下。

**排查步骤**：

# 在开发机上查找nsys实际路径

which nsys

ls -la /usr/local/cuda-*/bin/nsys

ls -la /opt/nvidia/nsight-systems/*/bin/

**解决方案**：

- 使用`which nsys`找到的实际路径进行挂载

- 确保挂载的是包含nsys的父目录，而不仅仅是nsys文件

问题3: `Error: Nsight Systems 2024.6.2 hasn't been installed with CUDA Toolkit 12.8`

**原因**：容器内自带的nsys版本与CUDA版本不匹配。

**错误示例**：

root@8adf7542ad9f:/open_explorer# nsys

Error: Nsight Systems 2024.6.2 hasn't been installed with CUDA Toolkit 12.8

**解决方案**：

- 挂载开发机上的完整CUDA工具链，而不是使用容器内自带的nsys

- 使用 `-v /usr/local/cuda-12.8:/usr/local/cuda-host:ro` 挂载开发机的CUDA

---

### 问题4: 权限不足

**原因**：nsys需要访问性能计数器，需要特权模式。

**错误示例**：

```

Error: Cannot access performance counters

```

**解决方案**：

- 在`docker run`时添加`--privileged`参数

- 或使用`--cap-add=SYS_ADMIN --cap-add=SYS_PTRACE`

 四、nsys使用示例

 4.1 基本使用

# 分析Python脚本

nsys profile -o my_report python train.py


# 分析指定脚本并设置追踪选项

nsys profile -o cuda_report --trace=cuda,nvtx python your_script.py

 4.2 常用参数

| 参数 | 说明 |

|------|------|

| `-o <name>` | 输出报告名称 |

| `--trace=cuda,nvtx` | 追踪CUDA和NVTX标记 |

| `--cuda-flavor=cuda` | 指定CUDA flavor |

| `--duration=<seconds>` | 采样持续时间 |

| `--sample=cpu` | 采样CPU活动 |

4.3 查看报告

**方法1：在开发机上查看**

# 报告会生成在当前目录

nsys-ui my_report.nsys-rep

**方法2：导出为SQLite格式**

nsys export -t sqlite -o report.sqlite my_report.nsys-rep

五、替代方案：在开发机上分析容器内程序

如果容器内挂载nsys仍有问题，可以在开发机上直接分析容器内运行的程序：

# 在开发机上执行

nsys profile -o my_profile \

  docker exec xuliang_lantu_test \

  python /open_explorer/your_script.py

# 查看结果

nsys-ui my_profile.nsys-rep

**优点**：

- 避免容器内版本兼容问题

- 无需在容器内配置环境

- 更简单直接

六、完整示例脚本

6.1 启动脚本 (start_container.sh)

```bash

```

#!/bin/bash

CONTAINER_NAME="nsys_test"

IMAGE="hub.hobot.cc/aitools/ai_toolchain_ubuntu_22_j6_gpu:v3.7.0"

# 查找开发机上nsys路径

NSYS_PATH=$(which nsys 2>/dev/null)

CUDA_PATH=$(dirname $(dirname $NSYS_PATH))



echo "Found nsys at: $NSYS_PATH"

echo "CUDA path: $CUDA_PATH"



# 检查容器是否已存在

if docker ps -a --format '{{.Names}}' | grep -q "^${CONTAINER_NAME}$"; then

    echo "Container $CONTAINER_NAME already exists, removing..."

    docker rm -f $CONTAINER_NAME

fi



# 启动容器

docker run -itd \

  --shm-size=64g \

  --name $CONTAINER_NAME \

  --gpus all \

  --runtime=nvidia \

  --privileged \

  -v /home/users/nsys_test/project/horizon_j6_open_explorer_v3.7.0-py310_20251215:/open_explorer \

  -v /home/data:/data/horizon_j6/data \

  -v ${CUDA_PATH}:/usr/local/cuda-host:ro \

  $IMAGE



echo "Container started. To enter:"

echo "  docker exec -it $CONTAINER_NAME bash"

echo ""

echo "Inside container, run:"

echo "  export PATH=\"/usr/local/cuda-host/bin:\$PATH\""

echo "  nsys --version"

6.2 进入容器脚本 ( enter_container.sh)

#!/bin/bash



CONTAINER_NAME="xuliang_lantu_test"



docker exec -it \

  -e PATH="/usr/local/cuda-host/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" \

  $CONTAINER_NAME bash

七、总结

成功挂载nsys的关键点

1. **找到正确路径**：使用`which nsys`找到开发机上nsys的实际安装路径

2. **挂载完整CUDA目录**：挂载整个CUDA目录而非单个文件

3. **添加特权模式**：使用`--privileged`参数

4. **不覆盖PATH**：不要在docker run时设置PATH，进入容器后手动设置

快速检查清单

- [ ] 开发机上nsys路径已确认 (`which nsys`)

- [ ] docker run命令包含`--privileged`

- [ ] 挂载了正确的CUDA目录

- [ ] 容器内验证nsys可用 (`/usr/local/cuda-host/bin/nsys --version`)

- [ ] 配置了环境变量或别名