深度学习环境配置 - 学习笔记-上海佼艾

一、概述与环境总览

深度学习环境配置是进入人工智能领域的必经之路。一个稳定、高效、可复现的开发环境能大幅提升实验效率，避免因环境冲突导致的"环境调试两小时，训练五分钟"的尴尬局面。本文将系统梳理深度学习环境配置的完整技术栈，涵盖从底层 GPU 驱动到上层实验管理的全链路方案。

环境配置核心原则

版本兼容性优先： CUDA、cuDNN、PyTorch/TensorFlow 版本必须严格匹配，否则 GPU 无法正常工作
环境隔离： 不同项目使用独立的虚拟环境，防止依赖冲突
可复现性： 记录精确的版本号和配置信息，确保实验结果可复现
容器化部署： 使用 Docker 将环境打包，消除"在我机器上能跑"的问题
远程开发： 通过 SSH/容器远程连接 GPU 服务器，本地仅作为 IDE 前端

层级	推荐方案	备选方案
操作系统	Ubuntu 22.04 LTS	Rocky Linux 9 / Windows WSL2
GPU 驱动	NVIDIA Driver 535+	NVIDIA Driver 525 LTS
计算框架	CUDA 12.1 + cuDNN 8.9	CUDA 11.8 + cuDNN 8.6
容器运行时	Docker + nvidia-container-toolkit	Podman + nvidia hook
框架	PyTorch 2.x / TensorFlow 2.15	JAX / PaddlePaddle
包管理器	conda + uv	pipenv / poetry
IDE	VS Code + Remote-SSH	PyCharm Professional
实验跟踪	MLflow	W&B / TensorBoard

二、CUDA 环境配置

CUDA（Compute Unified Device Architecture）是 NVIDIA 推出的并行计算平台和编程模型，是深度学习 GPU 加速的基石。正确配置 CUDA 环境是深度学习开发的第一步，也是最容易出错的环节之一。

2.1 NVIDIA 驱动安装

驱动是 GPU 与操作系统通信的桥梁，必须优先安装。推荐使用官方 runfile 方式或系统包管理器安装。

# 1. 检查 GPU 型号和推荐驱动
lspci | grep -i nvidia
nvidia-smi          # 驱动安装后验证

# 2. 通过 Ubuntu 官方仓库安装（推荐）
sudo apt update
sudo apt install nvidia-driver-535
sudo reboot

# 3. 或通过 NVIDIA 官网 runfile 安装
wget https://us.download.nvidia.com/XFree86/Linux-x86_64/535.154.05/NVIDIA-Linux-x86_64-535.154.05.run
chmod +x NVIDIA-Linux-x86_64-535.154.05.run
sudo ./NVIDIA-Linux-x86_64-535.154.05.run

# 4. 安装后验证驱动版本
nvidia-smi
# 输出应显示驱动版本、CUDA 版本、GPU 型号和显存信息

2.2 CUDA Toolkit 安装

CUDA Toolkit 包含编译器（nvcc）、运行时库和开发工具。需要注意：nvidia-smi 显示的 CUDA 版本是驱动支持的最高版本，实际使用的 CUDA Toolkit 版本可以低于该值。

# 下载 CUDA 12.1 Toolkit（推荐，兼容性最广）
wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda_12.1.0_530.30.02_linux.run
sudo sh cuda_12.1.0_530.30.02_linux.run --toolkit --silent --override

# 配置环境变量（写入 ~/.bashrc 或 ~/.zshrc）
export PATH=/usr/local/cuda-12.1/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH

# 验证 CUDA Toolkit 安装
nvcc --version
# 输出示例：Cuda compilation tools, release 12.1, V12.1.105

2.3 cuDNN 安装

cuDNN（CUDA Deep Neural Network Library）是 NVIDIA 针对深度神经网络优化的 GPU 加速库，提供了卷积、池化、归一化等操作的极致优化实现。

# cuDNN 需在 NVIDIA 官网注册后下载：https://developer.nvidia.com/cudnn
# 下载 cuDNN for CUDA 12.x (v8.9+) 的 Linux x86_64 Tar 包

# 安装 cuDNN（tar 方式，推荐）
tar -xzvf cudnn-linux-x86_64-8.9.7.29_cuda12-archive.tar.gz
sudo cp cudnn-*-archive/include/cudnn*.h /usr/local/cuda-12.1/include/
sudo cp -P cudnn-*-archive/lib/libcudnn* /usr/local/cuda-12.1/lib64/
sudo chmod a+r /usr/local/cuda-12.1/include/cudnn*.h
sudo chmod a+r /usr/local/cuda-12.1/lib64/libcudnn*

# 验证 cuDNN 安装
cat /usr/local/cuda-12.1/include/cudnn_version.h | grep CUDNN_MAJOR
# 或使用 dpkg（deb 安装方式）
dpkg -l | grep cudnn

2.4 版本兼容矩阵

版本兼容是环境配置中最关键的环节，不匹配的版本组合会导致 GPU 无法识别或训练崩溃。以下是最常用的兼容组合：

CUDA 版本	cuDNN 版本	PyTorch 版本	TensorFlow 版本	驱动最低版本
11.8	8.6.0	2.0.0 - 2.1.x	2.12 - 2.13	450.80.02
12.1	8.9.4	2.1.0 - 2.2.x	2.14 - 2.15	530.30.02
12.4	9.0.0	2.3.0 - 2.4.x	2.16+	550.54.14

2.5 PyTorch / TensorFlow GPU 版安装

安装深度学习框架时，务必从官网获取对应 CUDA 版本的安装命令，避免使用默认的 CPU-only 版本。

# PyTorch GPU 版安装（CUDA 12.1）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# PyTorch GPU 版安装（CUDA 11.8）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# TensorFlow GPU 版安装
pip install tensorflow[and-cuda]==2.15.0

# 或使用 conda 安装（会自动处理 CUDA 依赖）
conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia
conda install tensorflow-gpu=2.15.0

2.6 环境验证

完成安装后，务必运行以下验证脚本确认 GPU 正常工作。

# PyTorch GPU 验证
python3 -c "
import torch
print('PyTorch version:', torch.__version__)
print('CUDA available:', torch.cuda.is_available())
print('CUDA version:', torch.version.cuda)
print('cuDNN version:', torch.backends.cudnn.version())
print('GPU count:', torch.cuda.device_count())
print('GPU name:', torch.cuda.get_device_name(0))
# 执行一个简单的 GPU 张量运算
x = torch.randn(1000, 1000).cuda()
y = torch.mm(x, x)
print('GPU tensor test passed!')
"

# TensorFlow GPU 验证
python3 -c "
import tensorflow as tf
print('TF version:', tf.__version__)
print('GPU list:', tf.config.list_physical_devices('GPU'))
# 执行 GPU 矩阵运算
with tf.device('/GPU:0'):
    a = tf.random.normal([1000, 1000])
    b = tf.random.normal([1000, 1000])
    c = tf.matmul(a, b)
print('TF GPU test passed!')
"

常见问题排查

torch.cuda.is_available() 返回 False： 检查驱动版本、CUDA Toolkit 版本是否与 PyTorch 匹配，尝试重新安装对应 CUDA 版本的 PyTorch
nvidia-smi 显示但 PyTorch 找不到： 可能是权限问题，检查是否在 Docker 容器中运行且未设置 --gpus 参数
CUDA 版本不匹配： 使用 nvidia-smi 查看驱动支持的 CUDA 版本，确保安装的 Toolkit 版本不高于该值

三、Docker 容器化

Docker 容器化是深度学习环境管理的"终极方案"。它将整个环境（包括 CUDA、cuDNN、Python 包等）打包为镜像，实现"一次构建，随处运行"，彻底解决环境冲突和可复现性问题。

3.1 NVIDIA Container Toolkit 安装

要让 Docker 容器访问宿主机的 GPU，必须安装 NVIDIA Container Toolkit（原 nvidia-docker2）。

# 1. 安装 Docker Engine（Ubuntu）
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER   # 将当前用户加入 docker 组，避免每次 sudo
newgrp docker                   # 刷新用户组

# 2. 安装 NVIDIA Container Toolkit
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt update
sudo apt install nvidia-container-toolkit

# 3. 配置 container runtime
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# 4. 验证 GPU 直通
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

3.2 Docker Run GPU 参数详解

docker run --gpus 参数控制 GPU 访问权限，支持细粒度 GPU 选择。

# 使用所有 GPU
docker run --gpus all ...

# 使用指定 GPU（GPU 索引从 0 开始）
docker run --gpus '"device=0,1"' ...
docker run --gpus '"device=GPU-3a7c3f8f-..."' ...  # 使用 UUID

# 指定 GPU 数量和计算能力
docker run --gpus 'count=2,capabilities=compute,utility' ...

# 其他重要运行时参数
docker run \
  --gpus all \
  --shm-size=32g \          # 共享内存（PyTorch DataLoader 需要大 shm）
  --ipc=host \              # 使用主机 IPC 命名空间
  --network=host \          # 使用主机网络（方便 Jupyter 等）
  -v /data:/data \          # 挂载数据卷
  -v /home/user/code:/workspace \  # 挂载代码
  -p 8888:8888 \            # 端口映射
  -it pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime bash

3.3 使用官方镜像

NVIDIA、PyTorch 和 TensorFlow 官方均提供了预配置镜像，开箱即用。

# PyTorch 官方镜像（推荐）
docker pull pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime
docker pull pytorch/pytorch:2.1.0-cuda12.1-cudnn8-devel  # 包含编译工具

# TensorFlow 官方镜像
docker pull tensorflow/tensorflow:2.15.0-gpu
docker pull tensorflow/tensorflow:2.15.0-gpu-jupyter  # 包含 Jupyter

# NVIDIA 官方镜像（基础镜像）
docker pull nvidia/cuda:12.1.0-base-ubuntu22.04
docker pull nvidia/cuda:12.1.0-devel-ubuntu22.04  # 包含 nvcc
docker pull nvidia/cuda:12.1.0-runtime-ubuntu22.04

# 运行 PyTorch 官方镜像
docker run --gpus all --ipc=host -it \
  -v $(pwd):/workspace \
  pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime bash

3.4 自定义 Dockerfile

基于官方镜像构建自定义环境，安装项目特定的依赖。

# Dockerfile - 深度学习训练环境
FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime

LABEL maintainer="dev@example.com"
LABEL description="Deep Learning Training Environment"

# 设置工作目录
WORKDIR /workspace

# 安装系统依赖
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    git \
    curl \
    wget \
    vim \
    htop \
    tmux \
    libgl1-mesa-glx \
    libglib2.0-0 \
    && rm -rf /var/lib/apt/lists/*

# 安装 Python 依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 配置 Jupyter
RUN pip install jupyterlab ipywidgets nb_conda_kernels
EXPOSE 8888

# 配置 MLflow
RUN pip install mlflow
EXPOSE 5000

# 默认命令
CMD ["bash"]

3.5 多阶段构建

多阶段构建可以显著缩小最终镜像体积，将构建时依赖与运行时依赖分离。

# 多阶段构建 Dockerfile
# Stage 1: 编译阶段
FROM nvidia/cuda:12.1.0-devel-ubuntu22.04 AS builder

WORKDIR /build
COPY requirements.txt .
RUN pip install --user --no-cache-dir -r requirements.txt

# Stage 2: 运行阶段
FROM nvidia/cuda:12.1.0-runtime-ubuntu22.04

WORKDIR /workspace

# 复制 Python 及已安装的包
COPY --from=builder /root/.local /root/.local
COPY --from=builder /usr/local/bin/python3 /usr/local/bin/python3

# 确保 scripts 在 PATH 中
ENV PATH=/root/.local/bin:$PATH

COPY . .

CMD ["python3", "train.py"]

# 构建命令：docker build -t my-dl-env:latest .
# 最终镜像大小可减少 40-60%

3.6 Docker Compose 深度学习环境

使用 docker-compose 可以一键启动完整的深度学习开发栈，包括训练环境、Jupyter、MLflow 等。

# docker-compose.yml - 深度学习开发环境
version: '3.8'

services:
  dev:
    build:
      context: .
      dockerfile: Dockerfile
    image: dl-env:latest
    container_name: dl-dev
    runtime: nvidia
    shm_size: '32g'
    ipc: host
    network_mode: host
    volumes:
      - ./code:/workspace/code
      - ./data:/workspace/data
      - ./configs:/workspace/configs
      - ./logs:/workspace/logs
      - ~/.ssh:/home/dev/.ssh:ro
    environment:
      - CUDA_VISIBLE_DEVICES=0,1
      - TZ=Asia/Shanghai
      - PYTHONUNBUFFERED=1
    command: tail -f /dev/null
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

  jupyter:
    image: dl-env:latest
    container_name: dl-jupyter
    runtime: nvidia
    shm_size: '16g'
    ipc: host
    ports:
      - "8888:8888"
    volumes:
      - ./code:/workspace/code
      - ./data:/workspace/data
    environment:
      - CUDA_VISIBLE_DEVICES=0
    command: >
      jupyter lab --ip=0.0.0.0 --port=8888
      --no-browser --allow-root --NotebookApp.token='custom_token'

  mlflow:
    image: dl-env:latest
    container_name: dl-mlflow
    ports:
      - "5000:5000"
    volumes:
      - ./mlruns:/workspace/mlruns
    command: mlflow server --host 0.0.0.0 --port 5000 --backend-store-uri sqlite:///workspace/mlruns/mlflow.db

# 启动全部服务：docker compose up -d
# 仅启动开发容器：docker compose up -d dev

Docker 最佳实践

使用 --shm-size=32g 或 --ipc=host 避免 PyTorch DataLoader 的共享内存不足错误
将数据集和代码挂载到容器内，而非复制到镜像中，避免镜像体积过大
使用 .dockerignore 排除 .git、__pycache__、.env 等不需要的文件
为生产环境使用固定版本标签，避免使用 :latest

四、包管理与虚拟环境

包管理是日常开发中最频繁的操作。一个项目可能依赖 PyTorch 2.1，另一个项目可能依赖 TensorFlow 2.15，如果没有环境隔离，依赖冲突将寸步难行。

4.1 Conda 环境隔离

Conda 是目前深度学习领域最流行的包管理器和环境管理工具，尤其擅长处理非 Python 依赖（如 CUDA 库）。

# 安装 Miniconda（推荐，比 Anaconda 更轻量）
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda3
eval "$($HOME/miniconda3/bin/conda shell.bash hook)"
conda init

# 创建独立的深度学习环境
conda create -n dl_pytorch python=3.10 -y
conda create -n dl_tf python=3.10 -y

# 激活环境
conda activate dl_pytorch

# 安装 PyTorch（conda 会自动处理 CUDA 依赖）
conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia -y

# 安装其他常用包
conda install numpy pandas matplotlib scikit-learn tqdm -y
pip install transformers datasets accelerate wandb tensorboard

4.2 Pip 依赖管理

requirements.txt 是 Python 项目最通用的依赖声明方式，配合 pip 的 freeze 功能可以精确锁定版本。

# requirements.txt - 深度学习项目依赖
torch==2.1.0
torchvision==0.16.0
torchaudio==2.1.0
--index-url https://download.pytorch.org/whl/cu121
numpy==1.24.3
pandas==2.0.3
scikit-learn==1.3.0
matplotlib==3.7.2
tqdm==4.66.1
transformers==4.35.0
datasets==2.14.5
accelerate==0.24.1
wandb==0.15.12
tensorboard==2.15.0
mlflow==2.8.0
jupyterlab==4.0.8
ipywidgets==8.1.1
opencv-python==4.8.1.78
Pillow==10.1.0

# 安装依赖
pip install -r requirements.txt

# 冻结当前环境的所有依赖（用于记录精确版本）
pip freeze > requirements_frozen.txt

# 从冻结文件重建环境
pip install -r requirements_frozen.txt

4.3 Environment.yml

Conda 的 environment.yml 比 requirements.txt 更强大，可以同时管理 conda 包和 pip 包，并且支持跨平台。

# environment.yml
name: dl_project
channels:
  - pytorch
  - nvidia
  - conda-forge
  - defaults
dependencies:
  - python=3.10
  - pytorch=2.1.0
  - torchvision=0.16.0
  - torchaudio=2.1.0
  - pytorch-cuda=12.1
  - numpy=1.24.3
  - pandas=2.0.3
  - scikit-learn=1.3.0
  - matplotlib=3.7.2
  - tqdm=4.66.1
  - jupyterlab=4.0.8
  - ipywidgets=8.1.1
  - pip
  - pip:
    - transformers==4.35.0
    - datasets==2.14.5
    - accelerate==0.24.1
    - wandb==0.15.12
    - mlflow==2.8.0
    - opencv-python==4.8.1.78

# 从 environment.yml 创建环境
conda env create -f environment.yml

# 更新环境
conda env update -f environment.yml

# 导出当前环境
conda env export > environment_full.yml

4.4 uv 快速安装

uv 是 Rust 实现的极速 Python 包管理器，安装速度比 pip 快 10-100 倍，是深度学习环境搭建的利器。

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 使用 uv 创建虚拟环境并安装依赖
uv venv dl_env --python 3.10
source dl_env/bin/activate

# uv 安装 PyTorch（自动处理 CUDA）
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# uv 安装 requirements.txt（速度比 pip 快 10x+）
uv pip install -r requirements.txt

# uv 编译依赖（类似 pip-compile）
uv pip compile requirements.txt -o requirements_frozen.txt

# uv 同步环境（确保环境精确匹配）
uv pip sync requirements_frozen.txt

4.5 虚拟环境最佳实践

注意事项

不要将虚拟环境目录（.venv/、env/）提交到 Git 仓库
始终使用 requirements.txt 或 environment.yml 记录依赖，而非依赖本地环境
Python 版本尽可能统一（推荐 3.10），避免跨版本迁移问题
CUDA 相关包尽量用 conda 安装（自动处理底层库依赖），纯 Python 包用 pip/uv

五、Jupyter 配置

Jupyter Lab 是深度学习实验最常用的交互式开发环境，支持代码、文本、可视化混排，非常适合数据探索和原型验证。

5.1 安装与基础配置

# 安装 Jupyter Lab（推荐替代经典 Notebook）
pip install jupyterlab jupyterlab-lsp ipywidgets

# 生成配置文件
jupyter lab --generate-config

# 配置文件位置：~/.jupyter/jupyter_lab_config.py

# 设置密码（推荐替代 token）
jupyter lab password
# 输入并确认密码，密码哈希值将写入 ~/.jupyter/jupyter_server_config.json

5.2 远程 Jupyter + SSH 隧道

在远程 GPU 服务器上启动 Jupyter，通过 SSH 隧道在本地浏览器安全访问，是最常见的远程开发模式。

# 远程服务器上启动 Jupyter Lab
jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root

# 本地机器建立 SSH 隧道
ssh -N -L 8888:localhost:8888 user@remote-server.com -p 22

# 自动重连的 SSH 隧道（使用 autossh）
autossh -M 0 -o "ServerAliveInterval 60" -o "ServerAliveCountMax 3" \
  -N -L 8888:localhost:8888 user@remote-server.com

# SSH 配置文件方式（~/.ssh/config）
Host gpu-server
    HostName remote-server.com
    User user
    Port 22
    IdentityFile ~/.ssh/id_rsa
    LocalForward 8888 localhost:8888
    ServerAliveInterval 60

# 然后只需：ssh gpu-server

5.3 Jupyter 扩展安装

Jupyter Lab 的扩展生态极大增强了其功能。

# 安装 LSP（代码补全、跳转）
pip install jupyterlab-lsp
pip install 'python-lsp-server[all]'

# 安装变量查看器
pip install lckr-jupyterlab-variableinspector

# 安装 Git 集成
pip install jupyterlab-git

# 安装代码格式化
pip install jupyterlab-code-formatter black isort

# 安装 Table of Contents（自动生成目录）
pip install jupyterlab-toc
# Jupyter Lab 3.x 内置了 TOC，无需额外安装

# 安装绘图增强
pip install ipympl  # matplotlib 交互式绘图
pip install plotly notebook  # Plotly 交互式图表

5.4 nb_conda 内核与多环境内核

在 Jupyter 中切换不同的 conda 环境，需要在每个环境中安装 ipykernel。

# 方案一：为每个 conda 环境注册 Jupyter 内核
conda activate dl_pytorch
pip install ipykernel
python -m ipykernel install --user --name dl_pytorch --display-name "PyTorch 2.1 (CUDA 12.1)"

conda activate dl_tf
pip install ipykernel
python -m ipykernel install --user --name dl_tf --display-name "TensorFlow 2.15 (GPU)"

# 方案二：安装 nb_conda_kernels（自动检测所有 conda 环境）
conda activate base
pip install nb_conda_kernels
# 然后启动 Jupyter Lab，新建笔记本时即可看到所有 conda 环境

# 查看已注册的内核列表
jupyter kernelspec list

# 删除内核
jupyter kernelspec remove dl_pytorch

5.5 Jupyter 配置最佳实践

# ~/.jupyter/jupyter_lab_config.py 关键配置项

# 允许远程访问
c.ServerApp.ip = '0.0.0.0'

# 端口
c.ServerApp.port = 8888

# 不自动打开浏览器
c.ServerApp.open_browser = False

# 允许 root 用户运行
c.ServerApp.allow_root = True

# 密码认证（替代 token，更便于团队使用）
c.ServerApp.password = 'argon2:...'  # 通过 jupyter lab password 生成

# 设置工作目录
c.ServerApp.root_dir = '/workspace'

# 禁用默认的 token 认证（使用密码后）
c.ServerApp.token = ''

# 启用 LSP
c.LanguageServerManager.language_servers = {
    "python": {
        "argv": ["pylsp"],
        "languages": ["python"],
    }
}

安全提醒

生产环境中务必设置密码认证，禁用 token
优先使用 SSH 隧道而非直接暴露 Jupyter 端口到公网
如果必须暴露到公网，配置 HTTPS 和防火墙规则
不要在公开的 Jupyter notebook 中硬编码密码或 API 密钥

六、VS Code 远程开发

VS Code 的远程开发扩展（Remote Development）将本地 IDE 的便利性与远程 GPU 服务器的算力完美结合，是目前最主流的深度学习开发方式。

6.1 Remote-SSH 配置

通过 Remote-SSH 连接到远程 GPU 服务器，在本地 VS Code 中编写代码，所有计算在远程服务器上执行。

# 在 VS Code 中安装 Remote - SSH 扩展
# 扩展 ID：ms-vscode-remote.remote-ssh

# 配置 SSH 密钥认证（免密码登录）
ssh-keygen -t ed25519 -C "dev@example.com" -f ~/.ssh/id_ed25519
ssh-copy-id -i ~/.ssh/id_ed25519.pub user@remote-server.com

# ~/.ssh/config 完整配置示例
Host dl-gpu
    HostName 192.168.1.100
    User devuser
    Port 22
    IdentityFile ~/.ssh/dl_gpu_key
    ForwardAgent yes
    ServerAliveInterval 60
    ServerAliveCountMax 5
    LocalForward 8888 localhost:8888   # Jupyter 端口转发
    LocalForward 6006 localhost:6006   # TensorBoard 端口转发
    LocalForward 5000 localhost:5000   # MLflow 端口转发
    RemoteForward 8080 localhost:8080

# 连接后在 VS Code 中打开远程工作区
# Ctrl+Shift+P -> Remote-SSH: Connect to Host -> dl-gpu

6.2 Remote-Container 配置

Dev Containers（原 Remote-Container）允许在 Docker 容器中开发，容器内预装所有依赖，实现真正的"开箱即用"。

# .devcontainer/devcontainer.json
{
    "name": "Deep Learning Dev Container",
    "build": {
        "dockerfile": "../Dockerfile",
        "context": ".."
    },
    "runArgs": [
        "--gpus", "all",
        "--shm-size=32g",
        "--ipc=host",
        "--network=host"
    ],
    "mounts": [
        "source=${localWorkspaceFolder}/data,target=/workspace/data,type=bind",
        "source=${localWorkspaceFolder}/logs,target=/workspace/logs,type=bind",
        "source=${env:HOME}${env:USERPROFILE}/.ssh,target=/home/dev/.ssh,type=bind,readonly"
    ],
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-python.python",
                "ms-python.vscode-pylance",
                "ms-toolsai.jupyter",
                "ms-toolsai.tensorboard",
                "eamodio.gitlens",
                "github.copilot",
                "github.copilot-chat"
            ],
            "settings": {
                "python.defaultInterpreterPath": "/opt/conda/bin/python",
                "python.terminal.activateEnvironment": true,
                "jupyter.kernels.filter": "python",
                "files.watcherExclude": {
                    "**/.git/objects/**": true,
                    "**/data/**": true,
                    "**/logs/**": true
                }
            }
        }
    },
    "postCreateCommand": "pip install -r requirements.txt",
    "remoteUser": "dev"
}

6.3 端口转发与文件同步

VS Code 内置的端口转发功能可以将远程服务映射到本地端口，同时还支持自动文件同步。

# VS Code 端口转发（自动映射到 localhost）
# 在 VS Code 中打开 Remote Explorer -> Forwarded Ports
# 或手动添加转发规则到 .vscode/settings.json

{
    "remote.portsAttributes": {
        "8888": {
            "label": "Jupyter Lab",
            "onAutoForward": "openBrowser",
            "protocol": "http"
        },
        "6006": {
            "label": "TensorBoard",
            "onAutoForward": "openBrowserOnce"
        },
        "5000": {
            "label": "MLflow",
            "onAutoForward": "openBrowserOnce"
        }
    }
}

# 远程文件同步（使用 rsync 手动同步，某些场景比 VS Code 自动同步更可靠）
rsync -avz --progress --exclude '.git' --exclude 'data' --exclude '.venv' \
  ./ user@remote-server.com:/workspace/project/

# 实时文件同步（使用 unison 或 lsyncd）
# 推荐用于大文件或大量文件的场景

6.4 VS Code 深度学习开发配置最佳实践

七、实验环境管理

随着实验数量增加，手动跟踪每次实验的超参数、指标和模型权重变得不切实际。实验管理工具可以自动记录实验信息，支持对比分析和结果复现。

7.1 MLflow 实验跟踪

MLflow 是一个开源平台，涵盖实验跟踪（Tracking）、模型注册（Registry）、部署（Serving）全流程。

# 安装 MLflow
pip install mlflow

# 启动 MLflow Tracking Server（本地）
mlflow server --host 0.0.0.0 --port 5000 \
  --backend-store-uri sqlite:///mlruns/mlflow.db \
  --default-artifact-root ./mlruns/artifacts

# 在训练脚本中集成 MLflow
import mlflow
import mlflow.pytorch

mlflow.set_tracking_uri("http://localhost:5000")
mlflow.set_experiment("resnet-cifar10")

with mlflow.start_run(run_name="resnet50_lr0.001"):
    # 记录超参数
    mlflow.log_params({
        "model": "resnet50",
        "learning_rate": 0.001,
        "batch_size": 256,
        "optimizer": "adam",
        "epochs": 100
    })

    # 训练循环...
    for epoch in range(100):
        train_loss = train_epoch()
        val_acc = validate()

        # 记录指标
        mlflow.log_metrics({
            "train_loss": train_loss,
            "val_accuracy": val_acc
        }, step=epoch)

    # 记录模型
    mlflow.pytorch.log_model(model, "model")

    # 记录额外文件
    mlflow.log_artifact("configs/experiment.yaml")
    mlflow.log_artifact("logs/training.log")

    # 自动记录（自动跟踪 PyTorch/TF 指标）
    # mlflow.pytorch.autolog()

7.2 自托管 W&B Server

Weights & Biases (W&B) 是另一个流行的实验跟踪平台，支持自托管部署以保护数据隐私。

# 使用 Docker 自托管 W&B Server
docker pull wandb/local

docker run -d --name wandb-server \
  -p 8080:8080 \
  -v wandb_data:/vol \
  -e LOCAL_RESTORE=true \
  wandb/local

# 在训练脚本中使用 W&B
import wandb

wandb.init(
    project="cifar10-classification",
    name="resnet50_lr0.001",
    config={
        "model": "resnet50",
        "learning_rate": 0.001,
        "batch_size": 256,
        "epochs": 100,
        "dataset": "cifar10"
    }
)

# 训练循环
for epoch in range(100):
    loss = train_epoch()
    acc = validate()

    wandb.log({
        "train/loss": loss,
        "val/accuracy": acc,
        "epoch": epoch
    })

# 记录模型
wandb.save("model.pt")

wandb.finish()

7.3 实验记录数据库方案

对于需要精细化管理的团队，可以使用 MongoDB 存储实验元数据，灵活性更高。

# 使用 Docker 启动 MongoDB
docker run -d --name experiment-db \
  -p 27017:27017 \
  -v mongo_data:/data/db \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=secure_password \
  mongo:7.0

# Python 实验记录工具
from pymongo import MongoClient
from datetime import datetime
import json

class ExperimentLogger:
    def __init__(self, uri="mongodb://admin:secure_password@localhost:27017"):
        self.client = MongoClient(uri)
        self.db = self.client.experiments

    def log_experiment(self, project, config, metrics, artifacts=None):
        record = {
            "project": project,
            "status": "running",
            "config": config,
            "metrics_history": [metrics],
            "best_metrics": metrics,
            "artifacts": artifacts or [],
            "start_time": datetime.utcnow(),
            "last_updated": datetime.utcnow(),
            "host": socket.gethostname(),
            "gpu_info": self._get_gpu_info()
        }
        return self.db.runs.insert_one(record).inserted_id

    def update_metrics(self, run_id, metrics):
        self.db.runs.update_one(
            {"_id": run_id},
            {
                "$push": {"metrics_history": metrics},
                "$set": {"last_updated": datetime.utcnow()}
            }
        )

    def _get_gpu_info(self):
        import subprocess
        try:
            result = subprocess.run(
                ["nvidia-smi", "--query-gpu=name,memory.total,index",
                 "--format=csv,noheader"],
                capture_output=True, text=True
            )
            return [line.strip() for line in result.stdout.strip().split("\n")]
        except Exception:
            return ["GPU info not available"]

7.4 多 GPU 配置

多 GPU 训练是提升训练速度的常用手段，需要额外配置分布式训练环境。

# PyTorch DDP（Distributed Data Parallel）配置

# 方式一：单机多卡（torchrun）
# 训练脚本 train_ddp.py：
import torch
import torch.distributed as dist
import torch.multiprocessing as mp
from torch.nn.parallel import DistributedDataParallel as DDP

def setup(rank, world_size):
    dist.init_process_group(
        backend='nccl',
        init_method='env://',
        world_size=world_size,
        rank=rank
    )

def cleanup():
    dist.destroy_process_group()

def train(rank, world_size):
    setup(rank, world_size)
    torch.cuda.set_device(rank)

    model = MyModel().to(rank)
    ddp_model = DDP(model, device_ids=[rank])

    # 分布式数据加载器
    train_dataset = MyDataset()
    train_sampler = torch.utils.data.distributed.DistributedSampler(
        train_dataset,
        num_replicas=world_size,
        rank=rank
    )
    train_loader = DataLoader(
        train_dataset,
        batch_size=64,
        sampler=train_sampler,
        num_workers=4,
        pin_memory=True
    )

    optimizer = torch.optim.Adam(ddp_model.parameters(), lr=0.001)
    loss_fn = torch.nn.CrossEntropyLoss()

    for epoch in range(100):
        train_sampler.set_epoch(epoch)
        for batch in train_loader:
            x, y = batch
            x, y = x.to(rank), y.to(rank)

            optimizer.zero_grad()
            pred = ddp_model(x)
            loss = loss_fn(pred, y)
            loss.backward()
            optimizer.step()

    cleanup()

if __name__ == "__main__":
    world_size = torch.cuda.device_count()
    mp.spawn(train, args=(world_size,), nprocs=world_size)

# 运行：torchrun --nproc_per_node=4 train_ddp.py

# CUDA_VISIBLE_DEVICES 控制可见 GPU
export CUDA_VISIBLE_DEVICES=0,1,2,3   # 使用 GPU 0-3
export CUDA_VISIBLE_DEVICES=2,3       # 仅使用 GPU 2 和 3
python train.py                       # 程序只能看到被允许的 GPU

实验管理最佳实践

每次实验都记录： 即使是一个简单的测试，也建议记录到实验管理系统
固定随机种子： 在实验开始时固定 torch、numpy、random 的种子，确保可复现性
记录环境信息： 包括 CUDA 版本、PyTorch 版本、GPU 型号、Python 版本
保存完整配置： 将实验配置文件（YAML/JSON）保存为实验 artifact
定期清理： 失败的实验（如训练崩溃）标记为 failed 以便筛选

八、核心要点总结

深度学习环境配置清单

类别	关键操作	验证命令
NVIDIA 驱动	安装 nvidia-driver-535	`nvidia-smi`
CUDA Toolkit	安装 CUDA 12.1	`nvcc --version`
cuDNN	复制库文件到 CUDA 目录	`cat /usr/local/cuda/include/cudnn_version.h`
PyTorch GPU	`pip install torch --index-url https://download.pytorch.org/whl/cu121`	`torch.cuda.is_available()`
TensorFlow GPU	`pip install tensorflow[and-cuda]`	`tf.config.list_physical_devices('GPU')`
Docker GPU	安装 nvidia-container-toolkit	`docker run --gpus all nvidia/cuda:12.1-base nvidia-smi`
Conda 环境	`conda create -n myenv python=3.10`	`conda info --envs`
Jupyter Lab	`jupyter lab --ip=0.0.0.0 --port=8888`	浏览器访问 + 运行 GPU 代码
VS Code Remote	安装 Remote-SSH 扩展，配置 SSH 密钥	在远程终端运行 `nvidia-smi`
MLflow	`mlflow server --host 0.0.0.0`	浏览器访问 http://localhost:5000
DDP 多 GPU	`torchrun --nproc_per_node=4 train.py`	观察多个 GPU 利用率 > 0%

最佳实践总结

版本兼容是第一位： 安装前务必查阅 CUDA、cuDNN、框架三者的版本兼容矩阵，避免不兼容导致的诡异错误
优先使用 Docker： Docker 容器化是最可靠的环境隔离方案，配合 docker-compose 可一键启动完整开发栈
环境即代码： 将环境配置声明为代码（Dockerfile、requirements.txt、environment.yml），纳入版本管理
SSH 隧道保安全： 远程访问 Jupyter 等服务时，优先使用 SSH 隧道而非直接暴露端口
实验自动化跟踪： 从第一个实验开始就使用 MLflow/W&B 记录，养成良好的实验管理习惯
随机种子固定： 在训练脚本开头固定 torch.manual_seed(42)，确保实验可复现
多 GPU 数据并行： 使用 PyTorch DDP 替代 DataParallel，后者在多卡场景下有性能瓶颈
定期清理环境： 定期使用 conda clean --all / docker system prune 释放磁盘空间

一键环境检查脚本

#!/bin/bash
# check_env.sh - 深度学习环境完整性检查

echo "===== 系统信息 ====="
uname -a
echo ""

echo "===== NVIDIA 驱动 ====="
nvidia-smi --query-gpu=name,driver_version,memory.total --format=csv,noheader 2>/dev/null || echo "NVIDIA driver not found"
echo ""

echo "===== CUDA Toolkit ====="
nvcc --version 2>/dev/null || echo "CUDA Toolkit not found"
echo ""

echo "===== cuDNN ====="
cat /usr/local/cuda/include/cudnn_version.h 2>/dev/null | grep CUDNN_MAJOR -A2 || echo "cuDNN not found"
echo ""

echo "===== PyTorch ====="
python3 -c "
import torch
print(f'PyTorch: {torch.__version__}')
print(f'CUDA available: {torch.cuda.is_available()}')
print(f'CUDA version: {torch.version.cuda}')
print(f'cuDNN version: {torch.backends.cudnn.version()}')
print(f'GPU count: {torch.cuda.device_count()}')
print(f'GPU name: {torch.cuda.get_device_name(0)}')
" 2>/dev/null || echo "PyTorch not installed"
echo ""

echo "===== TensorFlow ====="
python3 -c "
import tensorflow as tf
print(f'TensorFlow: {tf.__version__}')
gpus = tf.config.list_physical_devices('GPU')
print(f'GPU devices: {gpus}')
" 2>/dev/null || echo "TensorFlow not installed"
echo ""

echo "===== Docker ====="
docker --version 2>/dev/null || echo "Docker not installed"
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi 2>/dev/null | head -2 || echo "Docker GPU not working"
echo ""

echo "===== 检查完成 ====="

九、进一步思考

深度学习环境配置看似繁琐，但本质上是"一次配置，长期受益"的过程。随着 MLOps 理念的普及，环境配置正从"手工打造"走向"基础设施即代码（IaC）"。推荐进一步探索以下方向：

进阶方向

Kubernetes + Kubeflow： 在 K8s 集群上编排分布式训练任务，实现自动扩缩容和故障恢复
GitOps 工作流： 使用 ArgoCD 或 Flux 实现环境配置的声明式管理和自动同步
CI/CD for ML： 使用 GitHub Actions 或 GitLab CI 自动构建 Docker 镜像、运行测试、部署模型
Feature Store： 引入 Feast / Tecton 等特征存储平台，统一管理训练和推理时的特征
模型服务化： 使用 Triton Inference Server / TorchServe / BentoML 部署生产级模型服务

目录