正文

显卡驱动装好后用Docker一键启动Jupyter让普通电脑也能快速跑AI代码不再为环境报错发愁

/0 浏览量
0721

装完显卡驱动，很多人会停在一个尴尬的地方：nvidia-smi 能跑出来，但一写 Python 就报 CUDA not available，一装 PyTorch 又跟系统 Python 版本打架，虚拟环境越建越乱。其实你手里已经握着一块“免安装钥匙”了，只是还没把它插进 Docker 的锁孔里。

下面这套流程，我带过不少零基础的同学用过。不绕弯子，直接从“驱动已就绪”开始，把 Jupyter + CUDA + 主流 AI 框架一次性塞进容器里。跑坏了不影响原系统，关掉容器就像没来过一样干净。

先摸一下底：驱动到底醒没醒

打开终端，敲一行：

nvidia-smi

如果能看到类似这样的输出，说明驱动层没问题，显卡已经能听懂指令了：

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 535.104.05   Driver Version: 535.104.05   CUDA Version: 12.2     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf    Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|===============================+======================+======================|
|   0  NVIDIA GeForce RTX 3060   Off  | 00000000:01:00.0  On |                  N/A |
|  0%   38C    P8     5W / 170W |    128MiB / 12288MiB |      0%      Default |
+-----------------------------------------------------------------------------+

注意看右上角的 CUDA Version: 12.2。这不是说你的电脑装了 CUDA 12.2，而是驱动支持的最高 CUDA 版本。容器里用的 CUDA Toolkit 版本不能超过这个数字，否则跑不起来。后面选镜像时会用到这个数。

给 Docker 请个“翻译官”

Docker 本身是个轻量虚拟机，它默认不认识你的 NVIDIA 显卡。要让容器里的程序直接调用 GPU，需要装一个中间件：NVIDIA Container Toolkit。你可以把它理解为“翻译官”：容器说英文，显卡说 CUDA 方言，翻译官负责实时互通。

Linux（Ubuntu / Debian）

# 添加官方 GPG 密钥
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

# 添加软件源
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# 安装并重启 Docker
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

装完后验证：

docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

如果输出和宿主机一样，说明翻译官上岗成功。

Windows / macOS

如果你用的是 Docker Desktop，GPU 支持现在已经内置得比较完善。Windows 需要确保开启 WSL2 后端（设置 → Docker Engine → "wslEngine": {"enabled": true}），并在 BIOS 里打开虚拟化。macOS 目前对 NVIDIA GPU 支持有限，Intel/M系列 Mac 跑 AI 训练建议走 CPU 镜像或远程服务器；如果有 AMD 显卡，可以换成 rocm 系列镜像，命令结构基本一致。

一条命令，把 Jupyter + CUDA + PyTorch 全家桶拉起来

别急着拼 Dockerfile，先用现成的官方镜像跑通流程。NVIDIA NGC 维护了一个带 Jupyter、PyTorch、TensorFlow、CUDA 的现成镜像，开箱即用：

docker run --gpus all -it \
  -p 8888:8888 \
  -v $(pwd):/workspace \
  -e JUPYTER_ENABLE_LAB=yes \
  nvcr.io/nvidia/pytorch:24.07-py3 \
  jupyter lab --ip=0.0.0.0 --allow-root --no-browser --NotebookApp.token='niuba123'

💡 Windows 用户把 -v $(pwd):/workspace 换成 -v %cd%:/workspace（CMD）或 -v ${PWD}:/workspace（PowerShell）。

回车之后，终端会打印一串地址，大概长这样：

http://127.0.0.1:8888/lab?token=niuba123

复制粘贴到浏览器，Jupyter Lab 就打开了。

这条命令到底干了什么？拆开看很直观

片段 作用 普通人能懂的比喻
--gpus all 把宿主机的所有 GPU 透传给容器 给容器开了一扇直达显卡的后门
-p 8888:8888 端口映射 把容器里的门牌号 8888 挂到你电脑的 8888 上
-v $(pwd):/workspace 挂载本地文件夹 容器里的 U 盘，插的就是你当前目录
-e JUPYTER_ENABLE_LAB=yes 强制启动新版界面 告诉镜像：今天用 Lab，不用旧版 Notebook
nvcr.io/nvidia/pytorch:24.07-py3 基础镜像 预装了 Python 3.10 + PyTorch 2.4 + CUDA 12.4 的“精装房”
jupyter lab --ip=0.0.0.0 --allow-root ... 启动命令 容器入口指令，绑定所有网卡、允许 root、设密码

进房间后第一件事：验明正身

在 Jupyter 里新建一个 Python 3 笔记本，跑这几行：

import torch
import tensorflow as tf

print("PyTorch 版本:", torch.__version__)
print("CUDA 是否可用:", torch.cuda.is_available())
print("显卡名称:", torch.cuda.get_device_name(0) if torch.cuda.is_available() else "无")

print("\nTensorFlow 版本:", tf.__version__)
print("TF 检测到 GPU:", len(tf.config.list_physical_devices('GPU')))

如果输出类似：

PyTorch 版本: 2.4.0+cu124
CUDA 是否可用: True
显卡名称: NVIDIA GeForce RTX 3060

TensorFlow 版本: 2.15.0
TF 检测到 GPU: 1

恭喜，环境已经彻底打通。接下来随便克隆 GitHub 上的 AI 项目、跑 Stable Diffusion、微调 LLM，都不用再操心 pip install 的依赖地狱。

文件往哪儿存？别等容器没了才后悔

Docker 容器本质上是“用完可丢弃”的。镜像里的 /opt/conda、/usr/local/lib/python3.10 这些路径，容器一删就没了。真正要留住的只有两样东西：

  1. 你的代码和笔记 → 靠 -v $(pwd):/workspace 映射到本地
  2. 下载的大模型权重 → 建议单独建一个文件夹挂载，比如 -v D:/AI_models:/workspace/models

以后每次启动，直接改一下命令里的路径就行：

docker run --gpus all -it \
  -p 8889:8888 \
  -v D:/My_AI_Projects:/workspace \
  -v D:/HuggingFace_Cache:/root/.cache/huggingface \
  -e JUPYTER_ENABLE_LAB=yes \
  nvcr.io/nvidia/pytorch:24.07-py3 \
  jupyter lab --ip=0.0.0.0 --allow-root --no-browser --NotebookApp.token='niuba123'

注意端口从 8888 改成了 8889，避免和上一次冲突。Hugging Face 的缓存也挂出来了，下次下载同一个模型就不用重新扣带宽。

常见报错，按症状对号入座

1. 启动后浏览器打不开，终端报 Address already in use

端口被占用了。要么关掉其他占着 8888 的程序，要么换端口：

-p 8890:8888

2. 终端直接退出，提示 Could not find platform independent libraries

通常是因为挂载路径写法不对，或者容器内工作目录权限乱了。最稳的修法：

docker run --gpus all -it \
  -p 8888:8888 \
  -v "$(realpath .)":/workspace \
  ...

Linux/macOS 用 realpath 拿绝对路径，避免相对路径在容器里飘。

3. 代码里 torch.cuda.is_available() 返回 False，但 nvidia-smi 正常

大概率是 Container Toolkit 没装好，或者镜像里的 CUDA 版本超过了驱动支持的上限。回到第一步确认 nvidia-smi 的 CUDA 版本，然后换一个更老的镜像标签，比如：

nvcr.io/nvidia/pytorch:23.10-py3

或者手动在容器里装对应版本的 PyTorch。

4. Windows Docker Desktop 启动极慢，GPU 调用失败

检查两点：

  • Docker Desktop 设置 → General → 勾选 Use the WSL 2 based engine
  • 终端运行 wsl --shutdown，然后重启 Docker Desktop
  • 确保 BIOS 里 Virtualization Technology 已开启

5. 内存爆满，Jupyter 直接 OOM

AI 项目容易吃显存和内存。可以在启动命令里加限制：

--memory=12g --shm-size=4g

--shm-size 特别重要，PyTorch 多进程数据加载器默认依赖共享内存，太小会卡死。

想自己定制？三行 Dockerfile 就能造“私人精装房”

现成镜像虽然快，但有时候你想预装 transformers、accelerate、bitsandbytes，或者换成国内镜像源。写一个 Dockerfile，一行 docker build 就完事：

FROM nvcr.io/nvidia/pytorch:24.07-py3

# 换成清华源，pip 下载飞快
RUN pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple \
    transformers accelerate datasets scikit-learn matplotlib

# 创建非 root 用户（可选，更安全）
USER root
RUN useradd -m -s /bin/bash aiuser
USER aiuser
WORKDIR /workspace

构建：

docker build -t my-ai-jupyter .

启动时把镜像名换掉即可：

docker run --gpus all -it -p 8888:8888 -v $(pwd):/workspace \
  my-ai-jupyter jupyter lab --ip=0.0.0.0 --allow-root --no-browser --NotebookApp.token='niuba123'

以后不管换电脑、重装系统、还是被同学借走硬盘，只要把这个 Dockerfile 拷过去，三分钟就能复刻一模一样的环境。

几个让体验更顺的小习惯

  • 别在容器里 apt-get install 一堆杂项。容器适合“一次性、可重建”。真需要系统级依赖，写进 Dockerfile 重新 build。
  • 密码别用默认空 token。NGC 镜像默认可能没设密码，局域网内谁都能连。启动时一定加 --NotebookApp.token='你的强密码'，或者用 --NotebookApp.password='...' 加密存储。
  • 想后台跑长任务，用 docker run -d 代替 -it，配合 docker logs <容器ID> 看进度。
  • 清理僵尸容器：定期跑 docker container prune，别让它悄悄吃掉硬盘空间。

把显卡驱动装好，其实只完成了 20%。剩下的 80% 是环境管理，而 Docker 把这件事从“修电脑”变成了“开盲盒”：每次打开都是干净的、可复现的、带 GPU 加速的 Jupyter。你只需要写代码、调参数、看结果，再也不用半夜三点对着 Segmentation fault (core dumped) 怀疑人生。

如果哪天想换框架、升版本、或者干脆换个城市换台机器，把那条 docker run 命令和 Dockerfile 存进云盘，三分钟就能在新电脑上复活整个 AI 工作台。这才是普通电脑跑 AI 的正确姿势。

-- 展开阅读全文 --