verl容器化部署：K8s+Docker生产级配置模板分享

verl容器化部署：K8s+Docker生产级配置模板分享

verl 是一个灵活、高效且可用于生产环境的强化学习（RL）训练框架，专为大型语言模型（LLMs）的后训练设计。它由字节跳动火山引擎团队开源，是 HybridFlow 论文的开源实现。

verl 具有以下特点，使其灵活且易于使用：

易于扩展的多样化 RL 算法：Hybrid 编程模型结合了单控制器和多控制器范式的优点，能够灵活表示并高效执行复杂的后训练数据流。用户只需几行代码即可构建 RL 数据流。

与现有 LLM 基础设施无缝集成的模块化 API：通过解耦计算和数据依赖，verl 能够与现有的 LLM 框架（如 PyTorch FSDP、Megatron-LM 和 vLLM）无缝集成。此外，用户可以轻松扩展到其他 LLM 训练和推理框架。

灵活的设备映射和并行化：支持将模型灵活地映射到不同的 GPU 组上，以实现高效的资源利用，并在不同规模的集群上具有良好的扩展性。

与流行的 HuggingFace 模型轻松集成：verl 能够方便地与 HuggingFace 模型进行集成。

verl 也具有以下优势，使其运行速度快：

最先进的吞吐量：通过无缝集成现有的 SOTA LLM 训练和推理框架，verl 实现了高生成和训练吞吐量。

基于 3D-HybridEngine 的高效 Actor 模型重分片：消除了内存冗余，并显著减少了在训练和生成阶段之间切换时的通信开销。

1. 为什么需要容器化部署 verl？

在本地开发机上跑通 verl 只是第一步。当你真正想把强化学习训练任务放到服务器集群上，尤其是需要多卡、多机并行训练时，就会遇到一系列头疼的问题：环境依赖冲突、不同机器配置不一致、资源调度混乱、任务难以管理和监控。

这时候，容器化部署就成了最佳选择。它能把你的代码、运行环境、依赖库全部打包成一个标准化的“集装箱”，确保在任何地方运行的结果都是一样的。而 Kubernetes（K8s）就是这个集装箱的“超级调度中心”，它能帮你自动管理成百上千个容器，实现资源的弹性伸缩、故障自愈和高效利用。

简单来说，用 Docker + K8s 部署 verl，能让你：

• 环境一致：开发、测试、生产环境完全一致，告别“在我机器上好好的”这类问题。
• 资源高效：自动调度任务到有空闲 GPU 的节点，最大化硬件利用率。
• 弹性伸缩：训练任务需要更多资源时，K8s 可以自动扩容；任务结束，自动回收资源。
• 便于管理：统一的命令行或界面管理所有训练任务，日志、监控一目了然。

接下来，我将分享一套可以直接用于生产环境的配置模板，手把手带你完成从构建镜像到在 K8s 上运行 verl 训练任务的完整流程。

2. 构建 verl 的 Docker 镜像

镜像是容器化部署的基石。一个好的镜像应该尽可能轻量，同时包含所有必要的依赖。下面是一个针对 verl 的 Dockerfile 模板，它基于 PyTorch 官方镜像，并进行了优化。

# 使用带有 CUDA 的 PyTorch 官方镜像作为基础，减少底层依赖问题
FROM pytorch/pytorch:2.1.0-cuda11.8-cudnn8-runtime

# 设置环境变量，防止 Python 输出缓冲，使得日志能实时输出
ENV PYTHONUNBUFFERED=1
# 设置 pip 镜像源，加速国内下载（可选）
ENV PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

# 安装系统依赖，包括 git、一些编译工具和 verd 可能需要的库
RUN apt-get update && apt-get install -y \
    git \
    build-essential \
    curl \
    && rm -rf /var/lib/apt/lists/*

# 设置工作目录
WORKDIR /workspace

# 复制项目依赖文件（requirements.txt）到镜像中
# 假设你的项目根目录有 requirements.txt
COPY requirements.txt .

# 安装 Python 依赖
# 先升级 pip，然后安装依赖。使用 `--no-cache-dir` 减少镜像层大小。
RUN pip install --upgrade pip && \
    pip install --no-cache-dir -r requirements.txt

# 安装 verl 框架本身
# 这里假设从官方仓库安装，你也可以复制本地代码用 `pip install -e .` 安装
RUN pip install --no-cache-dir verl

# 验证安装
RUN python -c "import verl; print(f'verl version: {verl.__version__}')"

# 复制你的训练代码和配置文件到镜像中
COPY . .

# 设置默认的启动命令（可以在 K8s YAML 中被覆盖）
CMD ["python", "your_training_script.py"]

关键点解释：

1. 基础镜像选择：pytorch/pytorch:2.1.0-cuda11.8-cudnn8-runtime 已经包含了 PyTorch、CUDA 和 cuDNN，这是运行 verl 和大多数 LLM 的基础，比从 Ubuntu 开始安装省事得多。
2. 依赖安装：将依赖安装步骤放在复制代码之前。这样，当你只修改代码时，Docker 可以利用缓存，跳过耗时的依赖安装步骤，加速镜像构建。
3. 工作目录：设置一个清晰的工作目录（如 /workspace），方便管理。
4. 启动命令：CMD 指定了容器启动后默认执行的命令。在 K8s 中，我们通常会在 YAML 文件里覆盖这个命令，以运行不同的训练任务。

构建镜像命令： 在包含 Dockerfile 和 requirements.txt 的目录下执行：

docker build -t your-registry/verl-training:1.0.0 .

请将 your-registry 替换为你的容器镜像仓库地址（如 harbor.example.com/ai-team）。

3. Kubernetes 部署配置模板

有了镜像，接下来就需要告诉 K8s 如何运行它。下面是一个 Deployment 和 Service 结合的配置模板，适用于需要稳定运行、可能包含多个副本的训练任务（如持续学习的服务）。对于一次性的训练任务，使用 Job 或 CronJob 更合适，模板会在后面给出。

3.1 Deployment 配置（用于常驻服务）

# verl-training-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: verl-training-deployment
  namespace: ai-training # 建议使用独立的命名空间
  labels:
    app: verl-training
spec:
  replicas: 1 # 根据需求调整副本数，verl 内部会处理多进程/多机并行
  selector:
    matchLabels:
      app: verl-training
  template:
    metadata:
      labels:
        app: verl-training
    spec:
      # 节点选择器：确保 Pod 被调度到有 GPU 的节点上
      nodeSelector:
        accelerator: nvidia-gpu # 这个标签需要你在 K8s GPU 节点上提前打上
      containers:
      - name: verl-trainer
        image: your-registry/verl-training:1.0.0 # 替换为你的镜像
        imagePullPolicy: IfNotPresent
        # 资源请求与限制，对 GPU 训练至关重要
        resources:
          requests:
            memory: "32Gi"
            cpu: "8"
            nvidia.com/gpu: 2 # 请求 2 块 GPU
          limits:
            memory: "48Gi"
            cpu: "12"
            nvidia.com/gpu: 2 # 限制最多使用 2 块 GPU，必须与 requests 一致
        # 挂载存储卷，用于保存训练数据、模型检查点和日志
        volumeMounts:
        - name: training-data
          mountPath: /workspace/data
          subPath: data # 挂载到卷的 data 子目录
        - name: training-data
          mountPath: /workspace/checkpoints
          subPath: checkpoints
        - name: training-data
          mountPath: /workspace/logs
          subPath: logs
        # 环境变量配置，可以传递训练超参数
        env:
        - name: WANDB_API_KEY
          valueFrom:
            secretKeyRef:
              name: wandb-secret # 假设密钥保存在名为 wandb-secret 的 Secret 中
              key: api-key
        - name: TRAIN_BATCH_SIZE
          value: "4"
        # 启动命令，覆盖 Dockerfile 中的 CMD
        command: ["python"]
        args: ["/workspace/train.py", "--config", "/workspace/config.yaml"]
        # 存活探针和就绪探针，确保服务健康
        livenessProbe:
          exec:
            command:
            - python
            - -c
            - "import torch; print('CUDA available:', torch.cuda.is_available())"
          initialDelaySeconds: 60
          periodSeconds: 30
      volumes:
      - name: training-data
        persistentVolumeClaim:
          claimName: verl-training-pvc # 需要提前创建 PVC
---
# 配套的 Service，如果需要从集群外部访问训练中的某些服务（如TensorBoard）
apiVersion: v1
kind: Service
metadata:
  name: verl-training-service
  namespace: ai-training
spec:
  selector:
    app: verl-training
  ports:
  - port: 6006 # TensorBoard 默认端口
    targetPort: 6006
    name: tensorboard
  type: ClusterIP # 根据需求可改为 NodePort 或 LoadBalancer

3.2 Job 配置（用于一次性训练任务）

对于跑完就结束的训练任务，使用 Job 资源更合适，K8s 会在任务完成后停止 Pod。

# verl-training-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: verl-ppo-finetune-job
  namespace: ai-training
spec:
  backoffLimit: 1 # 任务失败重试次数
  ttlSecondsAfterFinished: 86400 # 任务完成后 24 小时自动删除 Pod，清理资源
  template:
    spec:
      nodeSelector:
        accelerator: nvidia-gpu
      restartPolicy: Never # Job 的 Pod 重启策略应为 Never 或 OnFailure
      containers:
      - name: trainer
        image: your-registry/verl-training:1.0.0
        imagePullPolicy: IfNotPresent
        resources:
          requests:
            memory: "64Gi"
            cpu: "16"
            nvidia.com/gpu: 4
          limits:
            memory: "80Gi"
            cpu: "20"
            nvidia.com/gpu: 4
        volumeMounts:
        - name: training-storage
          mountPath: /workspace
        env:
        - name: NODE_RANK
          valueFrom:
            fieldRef:
              fieldPath: metadata.annotations['batch.kubernetes.io/job-completion-index'] # 用于多实例 Job
        - name: MASTER_ADDR
          value: "verl-ppo-finetune-job-0.verl-training-svc.ai-training.svc.cluster.local" # 主节点地址，需要配合 Headless Service
        command: ["torchrun"]
        args:
        - "--nnodes=2" # 节点数
        - "--nproc_per_node=2" # 每个节点的进程数（GPU数）
        - "--rdzv_backend=c10d"
        - "--rdzv_endpoint=$(MASTER_ADDR):29500"
        - "--max_restarts=0"
        - "/workspace/train.py"
        - "--config"
        - "/workspace/config.yaml"
      volumes:
      - name: training-storage
        persistentVolumeClaim:
          claimName: verl-training-pvc

配置核心要点：

1. 资源请求与限制（resources）：这是 GPU 训练的关键。必须明确请求 nvidia.com/gpu，K8s 的调度器才会把 Pod 分配到有 GPU 的节点。limits 防止单个任务耗尽节点资源。
2. 存储卷（volumes & volumeMounts）：训练数据、模型和日志必须持久化，不能放在容器内部（容器重启就没了）。这里通过 PersistentVolumeClaim (PVC) 挂载网络存储（如 NFS、Ceph）。
3. 探针（livenessProbe）：用于检查容器是否健康。示例中是一个简单的 Python 脚本检查 CUDA 是否可用。对于训练任务，可以设计更复杂的检查，如检查模型文件是否存在、能否写入日志等。
4. 环境变量（env）：将配置参数（如批次大小、学习率）通过环境变量传入，比硬编码在代码中更灵活，也符合十二要素应用原则。
5. 多机并行训练：在 Job 示例中，我们使用了 torchrun 和 MASTER_ADDR 等环境变量来配置分布式训练。这需要配合 K8s 的 Headless Service 来为每个 Pod 提供稳定的网络标识。这是生产级多机训练的标准做法。

4. 生产环境部署实战步骤

假设你已经有一个安装了 NVIDIA GPU 驱动、nvidia-container-toolkit 和配置了 GPU 插件的 K8s 集群。

4.1 步骤一：准备存储

首先，创建 PVC 来提供持久化存储。

# pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: verl-training-pvc
  namespace: ai-training
spec:
  accessModes:
    - ReadWriteMany # 多节点读写，适合分布式训练
  resources:
    requests:
      storage: 1Ti # 根据你的数据集和模型大小调整
  storageClassName: csi-rbd-sc # 替换为你的集群存储类名称

应用配置：

kubectl create namespace ai-training
kubectl apply -f pvc.yaml

4.2 步骤二：推送镜像并部署

1. 将构建好的 Docker 镜像推送到你的镜像仓库：

   docker push your-registry/verl-training:1.0.0
   

2. 修改 verl-training-deployment.yaml 或 verl-training-job.yaml 中的镜像地址为你推送的地址。
3. 部署应用：

   # 部署 Deployment（常驻服务）
   kubectl apply -f verl-training-deployment.yaml
   
   # 或者部署 Job（一次性任务）
   kubectl apply -f verl-training-job.yaml
   

4.3 步骤三：监控与日志

部署后，你需要知道训练任务跑得怎么样。

• 查看 Pod 状态：

  kubectl get pods -n ai-training -w # -w 参数持续观察状态变化
  

• 查看日志：

  # 查看指定 Pod 的日志
  kubectl logs -f verl-training-deployment-xxxxx -n ai-training
  
  # 对于 Job，查看其 Pod 的日志
  kubectl logs -f verl-ppo-finetune-job-xxxxx -n ai-training
  

• 监控资源使用：

  kubectl top pod -n ai-training
  kubectl describe pod verl-training-deployment-xxxxx -n ai-training # 查看详细事件和状态
  

4.4 步骤四：问题排查清单

如果 Pod 没有正常运行，可以按以下顺序排查：

1. Pod 状态是 Pending：通常是资源不足（GPU 不够）或调度问题。kubectl describe pod 查看事件。
2. Pod 状态是 CrashLoopBackOff：容器启动后立即崩溃。检查日志 kubectl logs --previous（查看上一次崩溃的日志）。
3. GPU 无法使用：检查节点是否有 GPU (kubectl describe node <node-name>)，检查 nvidia.com/gpu 资源是否可分配。确保节点安装了 nvidia-device-plugin。
4. 无法挂载存储：检查 PVC 状态是否为 Bound (kubectl get pvc)。检查 Pod 描述中是否有挂载错误。
5. 镜像拉取失败：检查镜像地址是否正确，是否有拉取权限。可以尝试手动 docker pull 测试。

5. 总结

将 verl 这类复杂的强化学习框架通过 Docker 和 Kubernetes 进行容器化部署，是将实验代码转化为稳定生产服务的关键一步。本文提供的配置模板覆盖了从镜像构建、资源声明、存储挂载到分布式训练配置的核心环节。

核心收获：

1. 标准化镜像：通过精心设计的 Dockerfile，固化运行环境，保证一致性。
2. 声明式配置：使用 K8s YAML 文件，清晰定义了应用所需的一切资源（CPU、GPU、内存、存储），使得部署可重复、可版本化管理。
3. 资源与弹性：K8s 确保了珍贵的 GPU 资源被高效、公平地调度，并能根据需求进行伸缩。
4. 生产就绪：通过持久化存储、健康检查、日志收集等配置，让训练任务具备了生产系统的可靠性和可观测性。

你可以直接使用这些模板作为起点，根据自己团队的基础设施（如具体的镜像仓库、存储类型、网络策略）进行调整。接下来，你可以进一步探索如何集成监控告警（如 Prometheus+Grafana）、日志聚合系统（如 ELK）和流水线（如 Kubeflow Pipelines），构建起一个完整的 MLOps 平台，让 AI 模型的训练、部署和管理变得更加高效和自动化。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。