OpenWAM Docker 部署指南:从镜像构建到离线 GPU 主机交付的完整流程
OpenWAM Docker 部署指南:从镜像构建到离线 GPU 主机交付的完整流程
OpenWAM 是一个面向 World-Action Model(世界-动作模型)系统化预训练的开源研究框架,其 Docker 部署方案把策略推理服务(policy server)、训练与源码开发统一封装进单一 CUDA 镜像:宿主机无需安装 OpenWAM 的 Python 环境,装好 NVIDIA 驱动和 NVIDIA Container Toolkit 即可运行。本文带你走完 OpenWAM Docker 部署的完整流程:构建镜像、启动推理服务、容器内训练,以及把镜像打包交付到无法联网的离线 GPU 主机。
镜像里有什么:一个自包含的 CUDA 12.8 环境
OpenWAM 的 Docker 镜像由 docker/Dockerfile 构建,核心内容:
- 基础环境:
nvidia/cuda:12.8.1-devel-ubuntu24.04(按 digest 固定,保证可复现),系统包全部来自固定的 Ubuntu 快照源; - Python 环境:Python 3.12 + venv,依赖版本被 docker/requirements-cu128.txt 锁定,PyTorch 2.7.1 + CUDA 12.8;
- 运行入口:docker/entrypoint.sh 支持
serve(策略服务)、train(分布式训练)两类命令,并自动校验缓存目录可写; - 离线默认:Compose 配置默认
HF_HUB_OFFLINE=1、TRANSFORMERS_OFFLINE=1、WANDB_MODE=offline,即镜像加载后不会尝试联网拉取模型。
根目录的 compose.yaml 定义了四个服务:serve(单卡推理)、train(训练,通过 OPENWAM_TRAIN_GPUS 选择 GPU)、dev(CPU 开发 shell)和 gpu-check(GPU 冒烟检查)。
一键构建与三层检查
在能联网、且有代码检出(checkout)的主机上操作:
git clone https://gitcode.com/gh_mirrors/op/OpenWAM
cd OpenWAM
test -f .env || cp docker/.env.example .env
mkdir -p .cache/docker outputs
所有 Docker 目标集中在 docker/docker.mk,可用 make docker-help 查看:
| 命令 | 作用 |
|---|---|
make docker-build |
构建 openwam:cu128 镜像(需要网络,首次会下载大量依赖) |
make docker-check |
校验 Compose 配置、容器内 pip check、CPU 测试与 Ruff 检查 |
make docker-integration-check |
测试镜像选择、dev 挂载与离线交付链路 |
make docker-gpu-check |
在 GPU 主机上验证 BF16、编译前后向、DeepSpeed FusedAdam 与多卡 NCCL |
在 GPU 主机上建议先跑 GPU 检查再加载权重:
docker compose run --rm -T gpu-check
该检查在断网环境下执行(对应 docker/gpu_smoke.py),必须整条命令以退出码 0 结束才算通过。
配置 .env:一次改好,处处生效
.env 模板见 docker/.env.example,关键项如下(用 id -u / id -g 查看主机用户 ID,并保证对应用户能写入缓存目录):
| 变量 | 说明 |
|---|---|
OPENWAM_IMAGE |
镜像标签,首次构建用 openwam:cu128 |
OPENWAM_UID / OPENWAM_GID |
容器内运行的用户/组 ID |
OPENWAM_GPU_ID |
推理占用的单张 GPU 索引 |
OPENWAM_TRAIN_GPUS |
训练可见 GPU,如 1,3 |
OPENWAM_CHECKPOINT_DIR |
宿主机上的完整 checkpoint 目录(推理以只读方式挂载) |
OPENWAM_ASSETS_DIR |
训练用资产目录,默认 ./assets |
OPENWAM_CACHE_DIR / OPENWAM_OUTPUT_DIR |
缓存与输出目录 |
一个完整 checkpoint 目录应包含 config.yaml、checkpoint_step_*.safetensors、tokenizer 与归一化资产。
启动策略服务并验证一次推理
在能联网的主机下载示例 RoboTwin 策略(约 25 GB),然后在 GPU 主机上:
docker compose up -d serve
docker compose ps serve
docker compose logs --tail=50 serve
等 health 变为 healthy(首次加载需数分钟)后做两项验证:
docker compose exec -T serve python /opt/openwam/docker/healthcheck.py
docker compose exec -T serve python scripts/inference_test/inference_single_test.py \
--test --state-dim 20
健康检查(docker/healthcheck.py)只发 ping,退出码 0 即通过;预测测试应输出 Smoke test passed. 并返回 20 个动作值。首次预测较慢属正常(编译预热),随机测试观测只验证执行链路,不验证策略质量。服务默认监听 ws://127.0.0.1:8848,可用 docker compose down 停止。
💡 远程访问默认回环端点时,可在客户端主机上建 SSH 隧道:
ssh -N -L 8848:127.0.0.1:8848 gpu-host,再连接ws://127.0.0.1:8848。
容器内训练:复用同一镜像
训练使用同一个镜像的 train 服务。先在联网主机用 dev 服务下载数据集与骨干权重,再在 GPU 主机启动训练(以 LIBERO 调试模式为例):
docker compose run --rm train train \
dataloader=libero training.debug=true training.num_epochs=null training.batch_size=1 \
dataloader.dataset_dir=/opt/openwam/assets/benchmark_data/libero \
model.video_backbone.model_path=/opt/openwam/assets/video_backbone_ckpt/Wan2.2-TI2V-5B
注意两点:
- 这里传的是容器内路径(
/opt/openwam/assets/...),而.env里写的是宿主机路径; - 官方推荐完整训练使用 8 张 80 GB 显存的 GPU;已有测试显示 2×H100 会在首次 Adam 更新时 OOM,4 张可通过——batch size 为 1 时优化器状态同样吃显存。
断点恢复用 training.resume_ckpt_path 指向输出目录(须含 config.yaml 与完整的 accel_state_step_* 子目录),与 training.finetune_ckpt_path 互斥。
交付离线 GPU 主机:打包、传输、校验、加载
离线交付是 OpenWAM Docker 方案的特色:目标机器不需要项目 Python 环境、不需要代码检出,只要提前装好 Docker、Compose、NVIDIA 驱动、NVIDIA Container Toolkit 和 Python 3.8+。
第 1 步:在联网主机导出离线包
make docker-export PYTHON=python3
该目标调用 docker/offline.py 的 export 子命令,把镜像 + 标准 Compose 文件 + 环境变量模板打包到 dist/openwam-offline/。注意:权重、数据与输出都不包含在镜像包内,需单独传输 checkpoint。
第 2 步:传输到离线 GPU 主机(先创建远端目录)
rsync -a --partial dist/openwam-offline/ gpu-host:/path/to/openwam-offline/
rsync -a --partial assets/openwam_ckpt/openwam_alpha/OpenWAM-Alpha-Sim-RoboTwin-Full/ \
gpu-host:/path/to/checkpoints/OpenWAM-Alpha-Sim-RoboTwin-Full/
第 3 步:离线主机上校验并加载
cd /path/to/openwam-offline
python3 docker/offline.py load . && cp docker/.env.example .env
mkdir -p .cache/docker outputs
load 成功后输出 Loaded <image>;只想先校验完整性可用 python3 docker/offline.py verify .(不加载镜像)。随后按本文"配置 .env"一节设置 UID/GID、GPU 索引与绝对路径的 checkpoint/资产路径,即可按"启动策略服务"一节执行。
几个容易踩坑的点:
- 每个新离线包要交付到全新目录,且包内不能存在
.env或*.override.yaml文件(校验器会拒绝); - 保持包内镜像标签不变;复用旧
.env时要从docker/.env.example更新OPENWAM_IMAGE; - 相对路径从包所在新目录解析,想沿用既有存储请改用绝对路径;
- 自定义 overlay(如
compose.inference.yaml)不随包导出,需单独传输并加入COMPOSE_FILE。
常见问题速查
| 症状 | 处理方向 |
|---|---|
| 连不上 Docker daemon | 检查 docker context show 与 docker info;仅 sudo 可用时解决该用户的 daemon 访问权限 |
| 挂载源缺失 / 权限被拒 | 按 .env 创建对应宿主目录,并让 UID/GID 与目录属主一致 |
| 服务 unhealthy | docker compose logs --tail=100 serve;检查本地权重与端口。健康 ping 不测模型执行,也不会自动重启容器 |
| GPU 不可用 / 编译失败 | 检查驱动与 NVIDIA Container Toolkit 后重跑 gpu-check;仅 nvidia-smi 正常不代表 CUDA/编译器兼容 |
| 训练 OOM | 复核 GPU 数量、模型规模与分布式/offload 设置;debug 模式并不省优化器状态开销 |
若驱动版本与镜像 CUDA 不匹配,Toolkit 通常可处理前向兼容;否则在 .env 中试 OPENWAM_CUDA_COMPAT=1,重建容器后重跑 GPU 检查。
延伸阅读
- 官方 Docker 使用文档(含网络/推理参数、worktree 开发与镜像维护):assets/openwam_usage_docs/docker.md
- Docker 验证记录:assets/openwam_usage_docs/docker-validation.md
- 训练与部署指南:assets/openwam_usage_docs/train-and-deploy.md
- Compose 叠加层(host 网络 / dev 源码挂载 / worktree):docker/compose.host.yaml、docker/compose.dev.yaml、docker/compose.worktree.yaml
- 依赖锁定与约束:docker/requirements-cu128.txt、docker/constraints-cu128.txt
