cschranz/gpu-jupyter

GPU-Jupyter

GPU-Jupyter：您的GPU加速JupyterLab，内置丰富的数据科学工具栈、TensorFlow和PyTorch，助力可复现的深度学习实验。

!https://github.com/iot-salzburg/gpu-jupyter/actions/workflows/default.yml/badge.svg

!https://raw.githubusercontent.com/iot-salzburg/gpu-jupyter/master/extra/jupyterlab-overview.png

镜像概述和主要用途

GPU-Jupyter 是一个基于 NVIDIA CUDA Docker 镜像和流行的 https://github.com/jupyter/docker-stacks 构建的 GPU 可用环境。该工具栈支持在 Jupyter 笔记本中进行 GPU 计算，同时通过容器和版本化标签确保实验的可复现性。通过对源代码进行版本控制、使用带标签的数据空间、为随机函数设置种子以及使用本文档提供的带标签环境，该解决方案使研究人员能够开展高度复杂且完全可复现、可共享的大数据实验。

有关如何使用 GPU-Jupyter 通过单个命令实现深度学习研究可复现性的示例，请访问 https://github.com/iot-salzburg/reproducible-research-with-gpu-jupyter%E3%80%82%E6%9C%AC%E4%BB%93%E5%BA%93%E7%9A%84%E9%95%9C%E5%83%8F%E5%8F%AF%E5%9C%A8 https://hub.docker.com/r/cschranz/gpu-jupyter 获取。

核心功能和特性

• GPU 加速计算：基于 NVIDIA CUDA 驱动，支持 TensorFlow、PyTorch 等深度学习框架的 GPU 加速。
• 丰富工具栈：集成 Python、R、Julia 等数据科学语言及相关库（如 SciPy、Pandas、Scikit-learn）。
• 可复现环境：通过容器化和版本化标签（如 v1.9_cuda-12.6_ubuntu-24.04）确保实验环境一致性。
• 多语言支持：提供全功能镜像（含 Python/R/Julia）及精简版（仅 Python）。
• 灵活配置：支持自定义密码/令牌、数据卷挂载、TensorBoard 集成、用户权限调整等。
• JupyterLab 界面：提供直观的集成开发环境，支持笔记本、终端、文件管理等功能。

使用场景和适用范围

• 深度学习研究：需要 GPU 加速的神经网络训练、模型调优实验。
• 可复现科研：需严格控制实验环境，确保结果可重复的学术研究。
• 数据科学工作流：涉及大规模数据处理、统计分析、可视化的多语言（Python/R/Julia）任务。
• 教学与演示：快速部署标准化的 GPU 数据科学环境，用于教学或技术演示。
• 自定义环境构建：通过修改 Dockerfile 生成满足特定需求的定制化 GPU 环境。

详细的使用方法和配置说明

目录

1. 快速开始
2. 构建自定义镜像
3. 容器监控与调试
4. 配置说明
5. 问题反馈与贡献

快速开始

前置条件

1. 硬件要求：拥有 NVIDIA GPU 的计算机。若无本地 GPU，可尝试 Saturn Cloud 提供的免费 GPU Jupyter 服务。
2. 软件安装：
   • Docker 版本 1.10.0+
   • Docker Compose 版本 1.28.0+
3. CUDA 配置：确保 Docker 容器可访问 GPU。按照 Medium 文章 中的步骤安装驱动。运行以下命令验证 GPU 是否可用：

   bash
   docker run --rm --gpus all nvidia/cuda:12.6.3-cudnn-runtime-ubuntu24.04 nvidia-smi
   

   若输出类似以下内容，则表示配置成功（需注意 CUDA 版本与本地驱动兼容性，建议 NVIDIA 驱动版本 ≥ 520）：

   Fri Feb 28 13:13:06 2025
   +-----------------------------------------------------------------------------------------+
   | NVIDIA-SMI 560.35.04              Driver Version: 561.17         CUDA Version: 12.6     |
   |-----------------------------------------+------------------------+----------------------+
   | GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
   | Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
   |                                         |                        |               MIG M. |
   |=========================================+========================+======================|
   |   0  NVIDIA GeForce RTX 3060 ...    On  |   00000000:01:00.0  On |                  N/A |
   | N/A   46C    P8             11W /   60W |     223MiB /   6144MiB |     15%      Default |
   |                                         |                        |                  N/A |
   +-----------------------------------------+------------------------+----------------------+
   

拉取并运行镜像

1. 进入工作目录并创建数据文件夹（默认挂载路径）：

   bash
   cd your-working-directory
   mkdir -p data  # 宿主机数据目录，将与容器共享
   

2. 启动 GPU-Jupyter 容器：

   bash
   docker run --gpus all -d -it -p 8848:8888 \
     -v $(pwd)/data:/home/jovyan/work \
     -e GRANT_SUDO=yes \
     -e JUPYTER_ENABLE_LAB=yes \
     --user root \
     cschranz/gpu-jupyter:v1.9_cuda-12.6_ubuntu-24.04
   

   • 参数说明：
     • --gpus all：启用所有 GPU
     • -p 8848:8888：端口映射（宿主机:容器）
     • -v $(pwd)/data:/home/jovyan/work：挂载数据卷（宿主机数据目录 → 容器工作目录）
     • -e GRANT_SUDO=yes：允许 root 用户执行 sudo
     • -e JUPYTER_ENABLE_LAB=yes：启动 JupyterLab（而非传统 Notebook）
     • --user root：以 root 用户运行容器

3. 获取登录令牌：

   bash
   docker exec -it [容器ID/名称] jupyter server list
   

   输出示例：

   [JupyterServerListApp] Currently running servers:
   [JupyterServerListApp] http://791003a731e1:8888/?token=5b96bb15be315ccb24643ea368a52cc0ba13657fbc29e409 :: /home/jovyan
   

   复制令牌，在浏览器访问 http://localhost:8848 并粘贴令牌登录。登录后可在 http://localhost:8848/login 设置密码（原默认密码 gpu-jupyter）。

可用镜像标签

Docker Hub 提供以下镜像变体（以 v1.9 为例）：

• v1.9_cuda-12.6_ubuntu-24.04：全功能版（含 Python/R/Julia 及完整工具栈）
• v1.9_cuda-12.6_ubuntu-24.04_python-only：仅含 Python 解释器（无 R/Julia）
• v1.9_cuda-12.6_ubuntu-24.04_slim：精简版（仅 Python，无额外工具包）

其他版本（如 v1.8_cuda-12.5_ubuntu-22.04、v1.7_cuda-12.3_ubuntu-22.04 等）及旧版本标签见 https://hub.docker.com/r/cschranz/gpu-jupyter/tags%E3%80%82

旧版本镜像（点击展开）

• v1.5_cuda-12.0_ubuntu-22.04 系列
• v1.4_cuda-11.6_ubuntu-20.04 系列
• v1.4_cuda-11.2_ubuntu-20.04 系列
• v1.4_cuda-10.1_ubuntu-18.04 系列

构建自定义镜像

如需自定义工具包或适配特定 GPU 架构，建议构建自定义镜像：

步骤

1. 克隆仓库并切换版本分支：

   bash
   git clone https://github.com/iot-salzburg/gpu-jupyter.git
   cd gpu-jupyter
   git checkout v1.9_cuda-12.6_ubuntu-24.04  # 选择或创建版本分支
   

2. 生成 Dockerfile（支持自定义参数，见 配置说明）：

   bash
   # 生成仅含 Python 的 Dockerfile（不含 Julia 和 R）
   ./generate-Dockerfile.sh --python-only
   

3. 构建镜像：

   bash
   docker build -t gpu-jupyter .build/  # 耗时较长，需耐心等待
   

4. 启动自定义容器：

   bash
   docker run --gpus all -d -it -p 8848:8888 \
     -v $(pwd)/data:/home/jovyan/work \
     -e GRANT_SUDO=yes \
     -e JUPYTER_ENABLE_LAB=yes \
     -e NB_UID="$(id -u)" \  # 同步宿主机用户 UID（避免权限问题）
     -e NB_GID="$(id -g)" \  # 同步宿主机用户 GID
     --user root \
     --restart always \  # 容器异常时自动重启
     --name gpu-jupyter_1 \  # 指定容器名称
     gpu-jupyter
   

使用 Docker Compose 启动

1. 创建 docker-compose.yml（参考仓库示例）：

   yaml
   version: '3.8'
   services:
     gpu-jupyter:
       build: .build/
       ports:
         - "8848:8888"
       volumes:
         - ./data:/home/jovyan/work
       environment:
         - GRANT_SUDO=yes
         - JUPYTER_ENABLE_LAB=yes
         - NB_UID=${UID}
         - NB_GID=${GID}
       user: root
       deploy:
         resources:
           reservations:
             devices:
               - driver: nvidia
                 count: all
                 capabilities: [gpu]
       restart: always
   

2. 启动服务：

   bash
   docker-compose up --build -d  # 构建并后台运行
   docker-compose ps  # 检查状态
   docker-compose logs -f  # 查看日志
   docker-compose down  # 停止服务
   

   注意：需 Docker Compose 版本 ≥ 1.28.0 以支持 GPU 资源配置。

容器监控与调试

• 查看运行中容器：

  bash
  docker ps  # 查看运行中容器（加 -a 查看所有容器）
  

• 查看容器资源占用：

  bash
  docker stats  # 实时监控 CPU/内存/网络/磁盘使用
  

• 查看容器日志：

  bash
  docker logs [容器ID/名称] -f  # -f 实时跟踪日志
  

• 进入容器终端：

  bash
  docker exec -it [容器ID/名称] bash  # 交互式终端
  

• 停止并删除容器：

  bash
  docker rm -f [容器ID/名称]
  

配置说明

Dockerfile 生成参数

generate-Dockerfile.sh 脚本用于生成自定义 Dockerfile，支持以下参数（互斥，每次仅选一个）：

环境变量

自定义工具包安装

避免直接修改 .build/Dockerfile（每次生成会覆盖），建议通过以下方式添加自定义包：

1. 修改 custom/usefulpackages.Dockerfile，添加 apt/pip 安装命令：

   dockerfile
   # 示例：安装额外 Python 包
   RUN pip install --no-cache-dir \
     "package1==x.y.z" \
     "package2"
   # 安装系统依赖
   RUN apt-get update && apt-get install -y --no-install-recommends \
     package3 \
     && rm -rf /var/lib/apt/lists/*
   

2. 重新生成并构建 Dockerfile：

   bash
   ./generate-Dockerfile.sh --python-only  # 重新生成
   docker build -t gpu-jupyter .build/     # 重新构建
   

授权配置

设置静态令牌

1. 生成 UUID 令牌：

   bash
   export JUPYTER_TOKEN=$(uuidgen)
   echo $JUPYTER_TOKEN  # 保存令牌备用
   

2. 启动容器时传入令牌：

   bash
   docker run --gpus all -d -it -p 8848:8888 \
     -e JUPYTER_TOKEN=${JUPYTER_TOKEN} \
     ...  # 其他参数
   

设置自定义密码

1. 通过登录页面：访问 http://localhost:8848/login，使用令牌登录后设置新