Docker 容器化部署 verl 手冊
無論你是剛接觸大模型工具的初學者，還是需要高效管理訓練任務的高級工程師，本教程都將帶你一步步完成 verlai/verl 鏡像的 Docker 部署——從工具認知、環(huán)境搭建到多場景部署實踐，每個步驟均配備完整命令與詳細說明，確保照著做就能成。
一、關于 verl：它是什么？能做什么？
基于 verl 官方文檔（https://verl.readthedocs.io），verl 是一款聚焦大模型“訓練+推理”全流程的工具集，核心定位是降低大模型強化學習（RL）訓練與高效推理的門檻，尤其適配企業(yè)級大模型落地場景。其本質是通過封裝主流深度學習框架（如 PyTorch、Megatron-LM）和推理引擎（如 vLLM），讓開發(fā)者無需手動解決復雜的環(huán)境依賴、分布式配置問題，專注于模型優(yōu)化與業(yè)務邏輯。
1.1 verl 的核心功能
verl 的能力覆蓋“訓練”和“推理”兩大核心場景，且支持靈活擴展：
-
大模型訓練：主打強化學習與分布式能力
- 支持多訓練后端：適配
FSDP（PyTorch 原生分布式框架，適合快速驗證原型）、Megatron-LM（NVIDIA 高性能分布式框架，支持萬卡級大模型訓練，適合大規(guī)模落地）。 - 強化學習（RL）優(yōu)化：內置 RL 訓練流程封裝，可直接用于大模型 RLHF（基于人類反饋的強化學習）、RLHF 變種任務，無需從零搭建訓練 pipeline。
- 依賴自動兼容：自動適配 PyTorch、CUDA、FlashAttention 等核心依賴版本，避免“版本沖突導致訓練崩潰”。
- 支持多訓練后端：適配
-
大模型推理：高效生成 rollout 結果
- 支持多推理引擎：集成
vLLM（業(yè)界領先的高吞吐推理框架，支持動態(tài)批處理）、TGI（Hugging Face Text Generation Inference，適合標準 Hugging Face 模型），未來將支持SGLang。 - 聚焦“rollout 生成”：專為強化學習場景設計——快速生成模型輸出樣本（如 RLHF 中的“模型回答候選”），推理速度比原生 Hugging Face
pipeline提升 5-10 倍。
- 支持多推理引擎：集成
-
高擴展性與定制化
- 支持自定義訓練配置：可通過 YAML 配置文件修改訓練參數(shù)（如學習率、 batch size、分布式策略）。
- 源碼級可定制：若使用掛載目錄部署，可直接修改
verl源碼（如適配新的 RL 算法、自定義數(shù)據(jù)集），無需重新構建鏡像。
1.2 verl 的適用場景
| 用戶類型 | 適用場景 |
|---|---|
| 算法工程師 | 快速驗證大模型 RL 算法、搭建 RLHF 訓練流程、測試不同推理引擎的 rollout 效率。 |
| 企業(yè)運維/DevOps | 為團隊快速部署統(tǒng)一的大模型訓練/推理環(huán)境，避免“一人一環(huán)境”的運維混亂。 |
| 初學者 | 零門檻體驗大模型分布式訓練與高效推理，無需手動配置 CUDA、PyTorch 等復雜環(huán)境。 |
| 大型團隊 | 基于 Megatron-LM 后端搭建大規(guī)模分布式訓練集群，支撐百億/千億參數(shù)模型訓練。 |
二、為什么用 Docker 部署 verl？
verl 依賴的組件（如 CUDA 12.1+、PyTorch 2.4.0+、Megatron-LM、vLLM）版本關聯(lián)性極強，傳統(tǒng)“本地手動安裝”常面臨 “CUDA 版本不兼容”“FlashAttention 編譯失敗”“Megatron-LM 路徑配置錯誤” 等問題。而 Docker 部署能完美解決這些痛點，核心優(yōu)勢如下：
- 環(huán)境“開箱即用”：
verlai/verl鏡像已預裝所有核心依賴（CUDA、PyTorch、vLLM、Megatron-LM），無需手動編譯或配置環(huán)境變量，新手也能 5 分鐘啟動訓練。 - GPU 環(huán)境免配置：鏡像內置 GPU 驅動適配邏輯，只需在啟動時指定
--gpus all，即可自動啟用 GPU 加速，避免“本地 GPU 驅動與 CUDA 版本不匹配”。 - 快速版本切換：若需測試不同
verl版本（如兼容 Megatron-LM v0.4.0 的舊版本），只需拉取對應標簽的鏡像，無需卸載重裝依賴。 - 服務隔離安全：
verl容器與主機、其他服務（如 MySQL、Redis）完全隔離，即使訓練任務崩潰，也不會影響其他應用。 - 企業(yè)級可管理：支持通過
docker-compose統(tǒng)一管理訓練任務、日志、數(shù)據(jù)掛載，便于團隊協(xié)作與運維。
三、準備工作：搭建 Docker 與 GPU 環(huán)境
verl 依賴 GPU 加速（CPU 模式僅支持極小模型測試，不推薦），因此需先完成 Docker 安裝 和 NVIDIA GPU 環(huán)境配置。
3.1 一鍵安裝 Docker & Docker Compose（Linux 系統(tǒng)）
若你的服務器未安裝 Docker，直接執(zhí)行以下一鍵腳本（支持 Ubuntu、CentOS、Debian 等主流 Linux 發(fā)行版），腳本會自動安裝 Docker、Docker Compose，并配置 軒轅鏡像加速源（解決“鏡像拉取慢”問題）：
# 一鍵安裝 Docker、Docker Compose 并配置軒轅加速
bash <(wget -qO- https://xuanyuan.cloud/docker.sh)
驗證 Docker 安裝成功
執(zhí)行以下命令，若輸出版本信息，則說明 Docker 安裝正常：
# 驗證 Docker 版本
docker --version
# 驗證 Docker Compose 版本
docker compose version
3.2 安裝 NVIDIA Container Toolkit（關鍵：啟用 GPU 支持）
verl 依賴 GPU 運行，需安裝 NVIDIA Container Toolkit 讓 Docker 容器識別主機 GPU。步驟如下（以 Ubuntu 為例，其他系統(tǒng)可參考 NVIDIA 官方文檔）：
-
添加 NVIDIA 官方源：
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 -
安裝 NVIDIA Container Toolkit：
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit -
重啟 Docker 服務使配置生效：
sudo systemctl restart docker -
驗證 GPU 支持：
運行 NVIDIA 測試鏡像，若輸出 GPU 信息（如型號、CUDA 版本），則 GPU 配置正常：docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi
四、查看 verl 鏡像：國內鏡像倉庫地址
本次部署使用 軒轅鏡像倉庫 的 verlai/verl 鏡像（地址：https://xuanyuan.cloud/r/verlai/verl），該倉庫提供：
- 加速拉取：國內網(wǎng)絡拉取速度比 Docker Hub 快 5-10 倍。
五、下載 verl 鏡像：4 種拉取方式
根據(jù)你的權限與使用場景，選擇以下任意一種方式拉取 verlai/verl 鏡像，推薦初學者優(yōu)先選擇 “專屬域名拉取”（步驟最簡單）。
5.1 方式 1：專屬域名拉取
直接拉取最新穩(wěn)定版鏡像，命令如下：
# 從軒轅鏡像專屬域名拉取 verlai/verl 對應版本。注意，這里的版本需要按照你的配置選擇，這里只是示例。
docker pull xxx.xuanyuan.run/verlai/verl:app-verl0.6-transformers4.56.1-sglang0.5.2-mcore0.13.0-te2.2
5.2 方式 2：拉取后改名（簡化后續(xù)命令）
若覺得 xuanyuan.cloud/r/verlai/verl 鏡像名過長，可拉取后重命名為 verlai/verl（與 Docker Hub 官方命名一致），后續(xù)啟動命令更簡潔：
# 拉取鏡像 → 重命名 → 刪除原標簽（避免占用空間）
docker pull xxx.xuanyuan.run/verlai/verl:app-verl0.6-transformers4.56.1-sglang0.5.2-mcore0.13.0-te2.2 \
&& docker tag xxx.xuanyuan.run/verlai/verl:app-verl0.6-transformers4.56.1-sglang0.5.2-mcore0.13.0-te2.2 verlai/verl:app-verl0.6-transformers4.56.1-sglang0.5.2-mcore0.13.0-te2.2 \
&& docker rmi xxx.xuanyuan.run/verlai/verl:app-verl0.6-transformers4.56.1-sglang0.5.2-mcore0.13.0-te2.2
5.3 方式 3：登錄驗證拉取（適合需要權限的鏡像）
- 登錄軒轅鏡像（按提示輸入軒轅鏡像用戶名和密碼）：
docker login docker.xuanyuan.run - 拉取鏡像：
docker pull docker.xuanyuan.run/verlai/verl:app-verl0.6-transformers4.56.1-sglang0.5.2-mcore0.13.0-te2.2
5.4 方式 4：Docker Hub 官方拉取（備用）
若你的網(wǎng)絡可直連 Docker Hub，也可直接拉取官方鏡像（速度可能較慢，建議優(yōu)先用軒轅鏡像）：
docker pull verlai/verl:app-verl0.6-transformers4.56.1-sglang0.5.2-mcore0.13.0-te2.2
5.5 驗證鏡像拉取成功
執(zhí)行以下命令，若輸出 verlai/verl 鏡像信息（如 REPOSITORY、TAG、SIZE），則拉取成功：
docker images | grep verlai/verl
示例輸出（成功狀態(tài)）：
REPOSITORY TAG IMAGE ID CREATED SIZE
verlai/verl latest a1b2c3d4e5f6 1 week ago 15.2GB
六、部署 verl：3 種場景方案
根據(jù)你的使用需求（測試、實際項目、企業(yè)級管理），選擇以下部署方案。每種方案均包含 完整命令、參數(shù)說明、驗證步驟，確保不同水平的用戶都能操作。
6.1 方案 1：快速部署（測試用，適合初學者）
適合快速驗證 verl 功能（如查看版本、測試基礎命令），無需持久化數(shù)據(jù)，命令極簡：
# 啟動 verl 容器（命名為 verl-test，啟用所有 GPU，后臺運行）
docker run -d \
--name verl-test \
--gpus all \ # 啟用主機所有 GPU（關鍵：verl 依賴 GPU 運行）
--shm-size="16g" \ # 共享內存設置為 16GB（避免多進程訓練內存不足）
verlai/verl:app-verl0.6-transformers4.56.1-sglang0.5.2-mcore0.13.0-te2.2
核心參數(shù)說明：
| 參數(shù) | 作用 |
|---|---|
-d |
后臺運行容器，避免終端退出后容器停止。 |
--name verl-test |
為容器指定名稱，便于后續(xù)管理（如停止、重啟）。 |
--gpus all |
讓容器使用主機所有 GPU（若需指定單個 GPU，可改為 --gpus "device=0"）。 |
--shm-size="16g" |
增大容器共享內存（大模型訓練需高頻數(shù)據(jù)交換，默認 64MB 會導致內存溢出）。 |
驗證部署成功：
-
查看容器是否正常運行：
docker ps | grep verl-test若
STATUS列顯示Up（如Up 5 minutes），則容器啟動正常。 -
進入容器測試
verl功能：# 進入 verl-test 容器的命令行 docker exec -it verl-test /bin/bash進入容器后，執(zhí)行以下命令驗證
verl是否可用：# 查看 verl 版本（驗證安裝） pip list | grep verl # 查看 PyTorch 與 CUDA 兼容性（驗證 GPU 可用） python -c "import torch; print('PyTorch 版本:', torch.__version__); print('CUDA 是否可用:', torch.cuda.is_available())"預期輸出（成功狀態(tài)）：
# verl 版本輸出 verl 0.0.6 # PyTorch 與 CUDA 輸出 PyTorch 版本: 2.4.0+cu124 CUDA 是否可用: True -
退出容器：
exit -
停止/刪除測試容器（若需）：
# 停止容器 docker stop verl-test # 刪除容器（測試完成后可刪除，釋放資源） docker rm verl-test
6.2 方案 2：掛載目錄部署（實際項目用，推薦）
適合實際訓練/推理任務——通過掛載宿主機目錄，實現(xiàn) 配置持久化、數(shù)據(jù)共享、日志留存（避免容器刪除后數(shù)據(jù)丟失）。核心思路：將宿主機的“配置目錄”“數(shù)據(jù)目錄”“日志目錄”“模型目錄”掛載到容器內，方便本地修改配置、管理數(shù)據(jù)。
第一步：創(chuàng)建宿主機掛載目錄
在宿主機創(chuàng)建 4 個核心目錄（路徑可自定義，此處以 /data/verl 為例），用于存儲配置、數(shù)據(jù)、日志、模型：
# 一次性創(chuàng)建 4 個目錄（-p 確保父目錄不存在時自動創(chuàng)建）
mkdir -p /data/verl/{config,data,logs,models}
目錄用途說明：
| 宿主機目錄 | 容器內掛載路徑 | 用途 |
|---|---|---|
/data/verl/config |
/root/verl/config |
存放 verl 訓練/推理配置文件（如 YAML 配置）。 |
/data/verl/data |
/root/verl/data |
存放數(shù)據(jù)集（如 RLHF 訓練數(shù)據(jù)、推理輸入數(shù)據(jù)）。 |
/data/verl/logs |
/root/verl/logs |
存放訓練日志、推理日志（容器內日志會實時同步到宿主機，便于查看）。 |
/data/verl/models |
/root/verl/models |
存放預訓練模型（如 LLaMA-7B、ChatGLM-6B），避免每次啟動容器重新下載。 |
第二步：準備測試配置與數(shù)據(jù)（可選）
為驗證掛載功能，可在宿主機目錄中添加測試文件（如訓練配置 YAML、簡單數(shù)據(jù)集）：
-
創(chuàng)建測試訓練配置文件
/data/verl/config/test_train.yml：# 測試用 RL 訓練基礎配置（簡化版） train: backend: "fsdp" # 使用 FSDP 分布式后端（適合快速驗證） model: name: "llama-7b" # 模型名稱（需確保 /data/verl/models 中有該模型） path: "/root/verl/models/llama-7b" # 容器內模型路徑（對應宿主機 /data/verl/models/llama-7b） data: path: "/root/verl/data/train_data.json" # 容器內數(shù)據(jù)集路徑（對應宿主機 /data/verl/data/train_data.json） log: path: "/root/verl/logs/train.log" # 容器內日志路徑（對應宿主機 /data/verl/logs/train.log） -
創(chuàng)建測試數(shù)據(jù)集
/data/verl/data/train_data.json（簡單 JSON 格式）：[ {"input": "What is AI?", "target": "AI is the simulation of human intelligence processes by machines."}, {"input": "What is verl?", "target": "verl is a tool for large model training and inference."} ]
第三步：啟動容器并掛載目錄
執(zhí)行以下命令，啟動容器并掛載 4 個目錄，同時配置時區(qū)（避免日志時區(qū)混亂）：
docker run -d \
--name verl-prod \ # 容器名（prod 表示生產用）
--gpus all \
--shm-size="32g" \ # 共享內存設為 32GB（比測試版更大，適配實際訓練）
-e TZ=Asia/Shanghai \ # 設置時區(qū)為上海（避免日志時區(qū)與本地不一致）
# 目錄掛載：宿主機目錄:容器內目錄
-v /data/verl/config:/root/verl/config \
-v /data/verl/data:/root/verl/data \
-v /data/verl/logs:/root/verl/logs \
-v /data/verl/models:/root/verl/models \
verlai/verl:app-verl0.6-transformers4.56.1-sglang0.5.2-mcore0.13.0-te2.2
驗證掛載功能：
-
進入容器，查看掛載目錄是否同步宿主機文件：
docker exec -it verl-prod /bin/bash # 查看容器內配置文件（應與宿主機 /data/verl/config/test_train.yml 內容一致） cat /root/verl/config/test_train.yml # 查看容器內數(shù)據(jù)集（應與宿主機 /data/verl/data/train_data.json 內容一致） cat /root/verl/data/train_data.json -
在容器內創(chuàng)建日志文件，驗證宿主機是否同步：
# 容器內創(chuàng)建測試日志 echo "Test log from container" > /root/verl/logs/test.log # 退出容器 exit # 宿主機查看日志文件（應能看到容器內創(chuàng)建的內容） cat /data/verl/logs/test.log若宿主機能看到
Test log from container，則掛載功能正常。
更新配置后重啟容器：
若修改了宿主機 /data/verl/config 中的配置文件，需重啟容器使配置生效：
docker restart verl-prod
6.3 方案 3：docker-compose 部署（企業(yè)級，適合團隊協(xié)作）
適合多容器管理、長期運行的企業(yè)級場景——通過 docker-compose.yml 文件統(tǒng)一配置容器參數(shù)（如鏡像、掛載、GPU、重啟策略），支持一鍵啟動/停止/查看狀態(tài)，便于團隊共享配置。
第一步：創(chuàng)建 docker-compose.yml 文件
在宿主機創(chuàng)建目錄（如 /data/verl-compose），并在該目錄下創(chuàng)建 docker-compose.yml 文件：
# 創(chuàng)建目錄并進入
mkdir -p /data/verl-compose && cd /data/verl-compose
# 創(chuàng)建 docker-compose.yml 文件（用 vim 編輯，新手也可直接復制內容）
vim docker-compose.yml
將以下內容粘貼到 docker-compose.yml 中（按 i 進入編輯模式，粘貼后按 Esc，輸入 :wq 保存退出）：
version: '3.8' # 兼容 Docker Compose V2 的語法版本
services:
verl-service: # 服務名（可自定義）
image: xxx.xuanyuan.run/verlai/verl:app-verl0.6-transformers4.56.1-sglang0.5.2-mcore0.13.0-te2.2 # 使用的鏡像
container_name: verl-service # 容器名
restart: always # 容器退出后自動重啟（保障服務可用性，企業(yè)級必備）
deploy:
resources:
reservations:
devices:
- driver: nvidia # 啟用 NVIDIA GPU
count: all # 使用所有 GPU（也可指定數(shù)量，如 count: 2）
capabilities: [gpu] # 聲明 GPU 能力
shm_size: "32g" # 共享內存大小
environment:
- TZ=Asia/Shanghai # 時區(qū)配置
volumes: # 目錄掛載（與方案 2 一致）
- /data/verl/config:/root/verl/config
- /data/verl/data:/root/verl/data
- /data/verl/logs:/root/verl/logs
- /data/verl/models:/root/verl/models
# 可選：若需暴露端口（如推理服務端口），添加 ports 配置
# ports:
# - "8000:8000" # 宿主機 8000 端口映射到容器 8000 端口（用于推理服務）
第二步：啟動服務
在 docker-compose.yml 所在目錄（/data/verl-compose）執(zhí)行以下命令，一鍵啟動 verl 服務：
# 后臺啟動服務（-d 表示 detached 模式）
docker compose up -d
常用 docker-compose 命令（企業(yè)級運維必備）
| 命令 | 作用 |
|---|---|
docker compose up -d |
后臺啟動服務（首次啟動或重啟）。 |
docker compose ps |
查看服務狀態(tài)（如容器是否運行、端口映射）。 |
docker compose logs |
查看服務日志（默認輸出所有日志，按 Ctrl+C 退出）。 |
docker compose logs -f |
實時查看日志（動態(tài)刷新，適合排查問題）。 |
docker compose restart |
重啟服務（修改配置后執(zhí)行）。 |
docker compose stop |
停止服務（容器保留，可重新啟動）。 |
docker compose down |
停止并刪除服務（容器、網(wǎng)絡會被刪除，掛載數(shù)據(jù)不會丟失）。 |
驗證服務啟動成功：
# 查看服務狀態(tài)
docker compose ps
# 查看實時日志（確認無報錯）
docker compose logs -f
若 State 列顯示 Up，且日志無 CUDA error、No GPU found 等報錯，則服務啟動正常。
七、常見問題與解決方案
即使按照教程操作，也可能遇到一些細節(jié)問題。以下是 verl Docker 部署中高頻問題的排查步驟，初學者可按流程逐一驗證。
7.1 問題 1：容器啟動失敗，日志顯示“CUDA error: no CUDA-capable device is detected”
原因：Docker 容器未識別到 GPU，可能是 NVIDIA Container Toolkit 未安裝或未重啟 Docker。
解決方案：
- 驗證主機 GPU 是否正常：
nvidia-smi # 若輸出 GPU 信息，說明主機 GPU 正常；否則需先解決主機 GPU 驅動問題 - 重新安裝并重啟
NVIDIA Container Toolkit（參考步驟 3.2）：sudo apt-get reinstall nvidia-container-toolkit sudo systemctl restart docker - 重新啟動容器，確保添加
--gpus all參數(shù)。
7.2 問題 2：訓練時內存溢出，日志顯示“Bus error (core dumped)”
原因：容器共享內存不足（大模型訓練需高頻數(shù)據(jù)交換，默認共享內存僅 64MB）。
解決方案：
- 啟動容器時增大
--shm-size參數(shù)，如改為--shm-size="64g"（根據(jù)主機內存調整，建議不超過主機內存的 50%）。 - 示例命令（修改共享內存）：
docker run -d \ --name verl-prod \ --gpus all \ --shm-size="64g" \ # 增大共享內存到 64GB -v /data/verl/config:/root/verl/config \ verlai/verl:app-verl0.6-transformers4.56.1-sglang0.5.2-mcore0.13.0-te2.2
7.3 問題 3：宿主機修改配置文件后，容器內不生效
原因：
- 未重啟容器（配置修改后需重啟容器加載新配置）；
- 掛載路徑錯誤（宿主機目錄與容器內目錄映射不匹配）。
解決方案： - 驗證掛載路徑是否正確（參考步驟 6.2 中的目錄映射）：
確認# 查看容器掛載信息 docker inspect verl-prod | grep Mounts -A 50Source（宿主機目錄）與Destination（容器內目錄）對應正確。 - 重啟容器：
docker restart verl-prod
7.4 問題 4：鏡像拉取慢或超時
原因：未使用軒轅鏡像加速，或網(wǎng)絡不穩(wěn)定。
解決方案：
- 優(yōu)先使用軒轅鏡像拉取（參考步驟 5.1）：
docker pull xxx.xuanyuan.run/verlai/verl:app-verl0.6-transformers4.56.1-sglang0.5.2-mcore0.13.0-te2.2 - 若已安裝 Docker，可手動配置軒轅鏡像加速（腳本已自動配置，若失效可重新執(zhí)行步驟 3.1 的一鍵腳本）。
7.5 問題 5：如何查看 verl 訓練日志？
解決方案：
- 若使用掛載目錄部署（方案 2/3），直接查看宿主機
/data/verl/logs目錄下的日志文件：# 查看訓練日志（按實際日志文件名修改） cat /data/verl/logs/train.log # 實時查看日志 tail -f /data/verl/logs/train.log - 若未掛載目錄，通過 Docker 日志命令查看：
docker logs -f verl-prod
八、結尾：不同用戶的下一步建議
本教程覆蓋了 verlai/verl Docker 部署的全流程，從工具認知到企業(yè)級落地。根據(jù)你的角色，可參考以下建議進一步實踐：
- 初學者：先從「方案 1 快速部署」熟悉
verl基礎命令，再嘗試「方案 2 掛載目錄」，修改/data/verl/config中的配置文件，體驗“配置-重啟-訓練”的完整流程。 - 算法工程師：基于「方案 3 docker-compose」部署，在
/data/verl/models中放入預訓練模型（如 LLaMA-7B），修改配置文件使用Megatron-LM后端，測試大規(guī)模分布式訓練。 - 運維工程師：在
docker-compose.yml中添加監(jiān)控配置（如集成 Prometheus、Grafana），監(jiān)控容器 GPU 使用率、內存占用，確保訓練任務穩(wěn)定運行。
若需深入學習 verl 的訓練/推理功能，可參考官方文檔：https://verl.readthedocs.io。遇到教程未覆蓋的問題，可通過 docker logs 容器名 查看詳細日志，或在 verl 官方社區(qū)提問。
浙公網(wǎng)安備 33010602011771號