📚 课程目录第2章环境准备

环境准备：安装与配置CI/CD工具、版本控制与容器化环境

在将AI模型集成到CI/CD流水线之前，必须先搭建一套可靠、可复现的基础环境。AI模型训练与推理具有数据依赖重、环境敏感、计算资源需求波动大等特点，如果底层工具链配置不当，后续的模型验证、镜像构建、部署上线都会频繁出现“在我机器上能跑”的尴尬问题。本节围绕三个核心支柱展开：CI/CD工具（以Jenkins与GitLab CI为例）、版本控制（Git与Git LFS）、容器化环境（Docker与Docker Compose），并给出可落地的安装与验证步骤。

核心原理：三支柱如何支撑AI模型流水线

AI模型集成流水线与传统软件流水线的最大差异在于：模型文件体积大（动辄数百MB甚至数GB）、训练环境依赖复杂（CUDA、cuDNN、Python包版本）、以及需要频繁进行实验追踪。因此，环境准备必须解决三个关键问题：

可重复性：同一份代码和配置，在任何时间、任何机器上都能构建出行为一致的模型产物。
可追溯性：每次模型训练或更新都能关联到具体的代码版本、数据集版本和超参数配置。
可移植性：模型从开发环境到测试环境再到生产环境，不因底层库差异而失效。

下图展示了三支柱之间的协作关系：Git仓库管理代码与模型元数据，CI/CD工具监听仓库事件并触发流水线，Docker容器为流水线的每个阶段（训练、测试、打包）提供隔离且一致的环境。

方法流程：从零搭建可用的AI流水线环境

环境准备遵循“先本地验证，再服务端部署”的原则。以下流程以Ubuntu 22.04 LTS为例，适用于大多数云服务器或自建机房。

第一步：安装Docker与Docker Compose

Docker是容器化的基石。AI模型训练通常需要GPU，因此还需安装NVIDIA Container Toolkit。执行以下命令：

# 安装Docker引擎
curl -fsSL https://get.docker.com | bash
sudo systemctl enable --now docker

# 安装NVIDIA Container Toolkit（用于GPU容器）
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-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

# 验证GPU容器可用
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

验证输出应显示GPU型号与驱动版本。若失败，检查驱动是否安装、nvidia-container-cli是否正常。

第二步：安装Git与Git LFS

AI项目中模型权重文件通常超过100MB，必须使用Git LFS避免仓库膨胀。安装与初始化：

sudo apt-get install -y git git-lfs
git lfs install

# 在项目仓库中跟踪模型文件
git lfs track "*.h5" "*.pt" "*.pth" "*.onnx"
git add .gitattributes
git commit -m "chore: add LFS track rules"

注意：.gitattributes文件必须提交到仓库，否则其他协作者无法正确拉取LFS文件。

第三步：安装Jenkins（或配置GitLab CI Runner）

两种工具选其一即可。若团队已使用GitLab，推荐GitLab CI；若需要更灵活的插件生态，选Jenkins。以Jenkins为例：

# 使用Docker运行Jenkins（数据持久化到宿主机）
docker run -d \
  --name jenkins \
  --restart=always \
  -p 8080:8080 -p 50000:50000 \
  -v jenkins_home:/var/jenkins_home \
  -v /var/run/docker.sock:/var/run/docker.sock \
  jenkins/jenkins:lts

# 获取初始管理员密码
docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

若使用GitLab CI，则需在GitLab服务器上注册Runner：

# 在GitLab项目 → Settings → CI/CD → Runners 中获取token
docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gitlab/gitlab-runner:latest register \
  --url https://gitlab.com \
  --token YOUR_RUNNER_TOKEN \
  --executor docker \
  --docker-image python:3.10-slim \
  --docker-volumes /var/run/docker.sock:/var/run/docker.sock

第四步：验证环境连通性

创建一个最小测试流水线，确认CI/CD工具能调用Docker并执行容器内命令。Jenkins中新建Pipeline任务，测试脚本如下：

pipeline {
    agent {
        docker { image 'python:3.10-slim' }
    }
    stages {
        stage('Check') {
            steps {
                sh 'python --version'
                sh 'pip list | grep torch || echo "torch not installed"'
            }
        }
    }
}

若控制台输出Python 3.10版本且无报错，说明Jenkins→Docker→容器执行链路已打通。

案例场景：一个典型的AI模型训练流水线配置

假设团队正在开发一个图像分类模型，使用PyTorch框架。项目结构如下：

ml-project/
├── .gitignore
├── .gitattributes          # LFS规则
├── .gitlab-ci.yml          # GitLab CI配置（或Jenkinsfile）
├── Dockerfile              # 训练环境镜像
├── docker-compose.yml      # 本地开发编排
├── requirements.txt        # Python依赖
├── src/
│   ├── train.py            # 训练脚本
│   └── evaluate.py         # 评估脚本
└── data/
    └── images/             # 数据集（不入库，用DVC或外部存储）

关键配置文件示例：

# .gitlab-ci.yml（片段）
stages:
  - train
  - test
  - package

train_model:
  stage: train
  image: pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime
  script:
    - pip install -r requirements.txt
    - python src/train.py --epochs 10 --batch-size 32
  artifacts:
    paths:
      - models/model.pt
    expire_in: 1 week

test_model:
  stage: test
  image: pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime
  script:
    - python src/evaluate.py --model models/model.pt
  needs: ["train_model"]

Dockerfile示例（用于固化训练环境）：

FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime
WORKDIR /workspace
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
ENV PYTHONUNBUFFERED=1

该配置实现了：代码推送→自动训练→自动评估→产物归档。每次训练产出的model.pt与Git提交SHA关联，便于回溯。

误区与复盘：环境准备中的常见陷阱

误区	后果	正确做法
将模型权重直接提交到Git仓库（未用LFS）	仓库体积膨胀至数GB，clone极慢，甚至超出平台限制	使用Git LFS跟踪大文件，或采用DVC管理数据与模型
CI Runner未挂载Docker Socket	流水线内无法执行docker build/push命令	在Runner配置中增加`/var/run/docker.sock`卷挂载
训练环境与生产环境CUDA版本不一致	模型在测试时正常，上线后推理报错	统一使用Docker镜像锁定CUDA/cuDNN版本，禁止在宿主机直接跑训练
忽略`.gitattributes`的提交	新成员clone后LFS文件无法正确拉取	将`.gitattributes`纳入版本控制，并在README中说明
Jenkins容器内未安装Git LFS	流水线拉取代码时LFS文件为指针而非实际内容	在Jenkins镜像中预装git-lfs，或使用包含LFS的Agent镜像

最佳实践提示：在项目根目录添加.gitignore，排除__pycache__、.pytest_cache、*.pyc、models/*.pt（若用LFS则例外）等无关文件。同时建议在CI流水线的第一个Stage执行git lfs pull，确保LFS文件在训练前已完整下载。

安全提醒：切勿将Docker Socket直接暴露给不受信任的流水线任务。若使用Jenkins，建议配置Docker Agent而非直接挂载Socket；若必须挂载，请确保只有受信任的Pipeline任务能访问该Runner。

环境准备完成后，建议执行一次“空跑”验证：提交一个仅打印环境信息的commit，观察CI/CD工具能否正确触发流水线、容器能否正常启动、日志能否完整回传。这一步能提前暴露80%的配置问题，为后续AI模型集成打下稳定基础。