📚 课程目录第4章环境与依赖管理

4. 环境与依赖管理

4.1 为什么训练环境需要“可复现”

在AI训练链路中，环境漂移是导致实验结果无法复现、模型性能波动、甚至线上事故的首要原因。一个典型的训练任务依赖三层环境：系统层（CUDA驱动、cuDNN、NCCL）、运行时层（Python解释器、PyTorch/TensorFlow版本、依赖库）、数据与配置层（数据集版本、超参数、随机种子）。任何一层的细微差异，例如cuDNN从8.4升级到8.6，都可能导致浮点运算顺序变化，进而使损失曲线出现不可忽略的偏差。

容器化技术的核心价值在于将这三层环境与宿主机隔离，并打包成不可变镜像。镜像一旦构建，其内部的文件系统、库版本、环境变量即被固化。配合镜像的内容寻址存储（通过SHA256摘要标识镜像层），可以精确记录每次训练实际使用的环境指纹，从而为“可复现”提供底层保障。

核心原理：容器不是虚拟机。它共享宿主机内核，仅通过命名空间（Namespace）隔离进程视图，通过控制组（CGroup）限制资源使用。因此，容器内的CUDA驱动版本必须与宿主机内核模块兼容，而CUDA运行时库（libcudart）则可以打包在镜像内。理解这一分层关系，是设计训练镜像的基础。

4.2 构建训练镜像的方法流程

构建可复现的训练镜像，核心是分层设计与依赖锁定。推荐采用以下流程：

基础镜像选择：优先使用官方镜像（如 nvidia/cuda:11.8.0-cudnn8-devel-ubuntu20.04），避免使用 latest 标签，必须指定完整版本号。
依赖锁定：使用 pip freeze 或 poetry.lock 生成精确到补丁版本的依赖清单。对于conda环境，使用 conda env export 导出 environment.yml。
多阶段构建：将编译阶段与运行阶段分离，减小镜像体积，同时避免将编译工具链带入生产环境。
非root用户：创建专用用户运行训练任务，避免容器内以root权限操作，降低安全风险。

# 多阶段构建示例：Dockerfile
# 阶段1：编译依赖
FROM nvidia/cuda:11.8.0-cudnn8-devel-ubuntu20.04 AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --user -r requirements.txt

# 阶段2：运行环境
FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu20.04
RUN useradd -m -u 1000 trainer
WORKDIR /workspace
COPY --from=builder /root/.local /home/trainer/.local
COPY train.py config.yaml ./
ENV PATH="/home/trainer/.local/bin:${PATH}" \
    PYTHONUNBUFFERED=1 \
    CUDA_VISIBLE_DEVICES=0
USER trainer
ENTRYPOINT ["python", "train.py"]

4.3 Kubernetes编排训练任务

当训练任务需要多节点分布式执行或需要动态申请GPU资源时，Kubernetes成为标准方案。通过自定义资源（CRD）如 PyTorchJob 或 TFJob，可以声明式地描述训练任务拓扑。

资源类型	用途	关键参数
Pod	单容器运行单元	resources.limits.nvidia.com/gpu: 1
Service	分布式训练节点间通信	headless service, port 23456
PersistentVolumeClaim	数据集与checkpoint持久化	storageClassName: nfs-client
ConfigMap	注入超参数与配置文件	data: config.yaml

一个典型的PyTorch分布式训练任务，需要为每个worker创建独立的Pod，并通过环境变量注入MASTER_ADDR、MASTER_PORT、RANK和WORLD_SIZE。Kubernetes的调度器会根据节点GPU资源标签，将Pod调度到合适的GPU节点上。

# PyTorchJob 示例（使用kubeflow）
apiVersion: kubeflow.org/v1
kind: PyTorchJob
metadata:
  name: resnet50-distributed
spec:
  pytorchReplicaSpecs:
    Master:
      replicas: 1
      template:
        spec:
          containers:
          - name: pytorch
            image: registry.example.com/train:resnet50-v1.2
            args: ["--epochs=50", "--batch-size=256"]
            resources:
              limits:
                nvidia.com/gpu: 1
    Worker:
      replicas: 3
      template:
        spec:
          containers:
          - name: pytorch
            image: registry.example.com/train:resnet50-v1.2
            args: ["--epochs=50", "--batch-size=256"]
            resources:
              limits:
                nvidia.com/gpu: 1

4.4 案例：从“能跑”到“可复现”的改造

某团队训练一个BERT微调模型，最初直接在GPU服务器上创建conda环境。当需要从单卡扩展到4卡分布式训练时，发现不同节点上的cuDNN版本不一致，导致NCCL通信初始化失败。改造过程如下：

第一步：将训练代码、依赖清单、启动脚本打包为Docker镜像，基础镜像固定为 nvidia/cuda:11.8.0-cudnn8-devel-ubuntu20.04。
第二步：在Kubernetes集群中创建PyTorchJob，指定Master和Worker副本数，并通过ConfigMap挂载不同的超参数配置。
第三步：将训练数据放在NFS持久卷上，所有Pod以只读方式挂载，确保数据一致性。
第四步：训练完成后，将镜像的SHA256摘要记录到实验元数据库（如MLflow），作为该次实验的环境指纹。

改造后，团队可以在任意时间点重新拉取相同摘要的镜像，在相同数据版本上重跑实验，损失曲线与原始实验的误差小于1e-6。

最佳实践：在CI/CD流水线中，将镜像构建与训练触发解耦。镜像构建成功后，将镜像标签（如 train:resnet50-20240515-3f2a）写入Git提交信息或工单系统。训练任务通过引用该标签，确保流水线可追溯。

4.5 常见误区与复盘

误区一：使用 latest 标签。 这会导致镜像内容随时间变化，无法复现历史实验。正确做法是始终使用不可变标签（日期+短哈希）。

误区二：忽略宿主机驱动兼容性。 容器内的CUDA运行时版本不能高于宿主机驱动支持的版本。例如，宿主机驱动为535.104.05（支持CUDA 12.2），容器内使用CUDA 11.8可以运行，但反之则报错。建议在CI中增加驱动版本检查步骤。

误区三：将训练数据打包进镜像。 镜像体积会急剧膨胀，且每次数据更新都需要重新构建镜像。应将数据挂载为Volume，并在镜像中只保留数据读取逻辑。

复盘一次线上事故：某团队升级了PyTorch版本从1.12到2.0，但未更新Dockerfile中的基础镜像，导致容器内实际运行的仍是旧版本。原因是CI脚本中使用了 pip install torch 而非从锁定文件安装。修复措施：在Dockerfile中显式指定 torch==2.0.1，并在CI流水线中加入依赖一致性校验（pip check）。