OpenWAM Docker 部署指南:从镜像构建到离线 GPU 主机交付的完整流程

原创2026-10-16 21:57:501,352 阅读

OpenWAM Docker 部署指南:从镜像构建到离线 GPU 主机交付的完整流程

OpenWAM 是一个面向 World-Action Model(世界-动作模型)系统化预训练的开源研究框架,其 Docker 部署方案把策略推理服务(policy server)、训练与源码开发统一封装进单一 CUDA 镜像:宿主机无需安装 OpenWAM 的 Python 环境,装好 NVIDIA 驱动和 NVIDIA Container Toolkit 即可运行。本文带你走完 OpenWAM Docker 部署的完整流程:构建镜像、启动推理服务、容器内训练,以及把镜像打包交付到无法联网的离线 GPU 主机。

OpenWAM-Infra 架构与部署架构总览:模型组件、推理模式与推理加速选项

镜像里有什么:一个自包含的 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 检查。

延伸阅读

登录后查看全文
OpenWAM