verl 项目 Docker 镜像全指南层级体系、多架构构建与 uv 运行镜像实战【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verlverlHybridFlow是一个灵活高效的 RL 后训练Post-Training框架其 docker/README.md 是理解如何为 verl 搭建 GPU 训练与推理环境的权威入口。本文以该文档为骨架结合仓库内实际的 Dockerfile、manage_envs.py与示例脚本源码系统讲解 verl 的镜像发布层级、Stable 镜像与 uv 通用镜像的构建与使用、GB200aarch64多架构构建方案以及从容器内启动 verl 训练任务的完整流程帮助你快速获得一套可复制、可运行的 verl 容器化环境。镜像层级体系Base Image 与 Application Imageverl 的镜像发布采用“基础镜像 应用镜像”的两级层次结构这一设计从 v0.6.0 起正式启用目的是兼顾稳定性与生产力Base Image基础镜像由上游推理引擎社区维护的官方镜像verl 不重复造轮子直接以其为底座。vLLM 系列自 v0.7.0 起由于vllm/vllm-openai:v0.12.0这类最小化镜像缺少部分必要系统库verl 改用nvidia/cuda:13.0.2-devel-ubuntu24.04CUDA devel 镜像作为 vLLM 系基础镜像见 Dockerfile.stable.vllm 中的FROM nvidia/cuda:${CUDA_VERSION}-devel-ubuntu24.04。SGLang 系列直接使用官方发布的lmsysorg/sglang镜像如 v0.5.12见 Dockerfile.stable.sglang。Application Image应用镜像在基础镜像之上verl 再叠加推理与训练所需的扩展软件栈。以 vLLM Stable 镜像为例其额外安装的软件包包括flash_attnFlashAttention 2.8.3强制源码编译Megatron-LMcore_v0.18.0与Megatron-Bridger0.5.0 配套ApexNVIDIA 混合精度训练库源码编译启用--cpp_ext/--cuda_extTransformerEnginev2.16.1DeepEPDeepSeek 的 Expert Parallel 通信库依赖 GDRCopy 与 NVSHMEM此外应用镜像还内置了 verl 训练所需的配套组件TRL0.27.0、liger_kernel、nvtx、TransferQueue0.1.8、qwen-vl-utils、torchcodec多模态支持、Nsight Systems 2025.6.1性能剖析以及针对 verl 权重同步流程打补丁的 vLLM#44483、#45589两个未合并 PR 的 diff 通过git apply --3way合入。为支持ncclCommSuspend/ncclCommResume详见 Dockerfile.stable.vllm镜像还会将 NCCL 强制覆盖到2.29.7,3.0。Stable 镜像官方推荐的预构建镜像verl 在 Docker Hub 的verlai/verl组织下发布了所有预构建镜像命名遵循引擎版本.latest的约定。当前仓库对应的最新 Stable 镜像为verlai/verl:sgl0512.latest基于 SGLang v0.5.12verlai/verl:vllm024.latest基于 vLLM v0.24.0Stable 镜像基础镜像推理引擎torchCUDADockerfile.stable.vllmnvidia/cuda:13.0.2-devel-ubuntu24.04vLLM 0.24.02.11.013.0.2Dockerfile.stable.sglanglmsysorg/sglang:v0.5.12SGLang 0.5.122.11.013.0.2Dockerfile.stable.trtllmNGCtensorrt-llm/release:1.3.0rc15TensorRT-LLM随基础镜像随基础镜像其中 TRT-LLM 镜像直接以 NVIDIA NGC 的 TensorRT-LLM release 镜像为底座其中已预装 TensorRT-LLM构建时会清除基础镜像继承的TORCH_CUDA_ARCH_LIST避免 FlashInfer 在运行时误判 GPU 架构、安装 Megatron 依赖与 Ray 2.54.1并将 verl 以pip install verl[mcore] git...v0.7.1的方式装入见 Dockerfile.stable.trtllm。注意Dockerfile.stable.vllm顶部注释表明其面向双架构x86_640.24.0, aarch640.20.2但 aarch64 的预构建镜像尚未发布需要用户自行在 aarch64 机器上本地构建。本地构建一条命令产出 Stable 镜像从源码构建 Stable 镜像只需一条命令构建上下文为仓库根目录docker build -f docker/Dockerfile.stable.vllm -t verl:vllm-local .对于国内用户可通过APT_MIRROR构建参数传入 apt 镜像源加速软件包下载docker build -f docker/Dockerfile.stable.vllm \ --build-arg APT_MIRRORhttps://mirrors.tuna.tsinghua.edu.cn \ -t verl:vllm-local .该参数在 Dockerfile.stable.vllm 中以ARG APT_MIRROR声明构建时若非空会通过sed将 Ubuntu 源替换为镜像地址。类似地uv 镜像还额外支持UBUNTU_MIRROR、PIP_DEFAULT_INDEX、GITHUB_ARTIFACTORY等镜像/索引覆盖参数见 Dockerfile.uv.cu130。GB200 / aarch64 构建预构建镜像目前不包含 GB200aarch64版本用户需要在 aarch64 机器上本地构建。由于基础镜像是多架构 manifest同一份 Dockerfile 在对应架构的主机上即可产出对应架构的镜像docker build -f docker/Dockerfile.stable.vllm -t verl:vllm-arm64 . docker build -f docker/Dockerfile.uv.cu130 -t verl:uv-cu130-arm64 . # uv 镜像构建前先用uname -m确认架构在aarch64主机上直接执行上述docker build即可无需任何额外操作。若在x86_64主机上则需要二选一方案一远程 arm64 机器原生构建推荐。将远程 arm64 主机作为 buildx 节点挂载从 x86_64 驱动构建全程无模拟执行。注意userarm-host只是占位符必须替换为真实可解析的 arm64 主机地址节点要求 Docker 18.9 且支持免密 SSHbuildx 通过ssh ... docker system dial-stdio非交互式工作SSH 用户需在docker组内。先验证连通性再创建 builderssh userarm-host docker version # 必须无需密码即可成功 docker buildx create --name verl-arm --driver docker-container \ --platform linux/arm64 ssh://userarm-host --use docker buildx build --platform linux/arm64 -f docker/Dockerfile.uv.cu130 \ -t verl:uv-cu130-arm64 --load .需要留意的是buildx create上的--platform只是声明该节点宣称支持的平台并不会让 x86_64 节点“原生”构建 arm64。方案二完全没有 arm64 机器时使用 QEMU 模拟。该方案可行但很慢——apt 安装、GDRCopy 源码构建以及prefetch阶段 megatron-core / mbridge 的源码构建都会在模拟环境下执行docker run --privileged --rm tonistiigi/binfmt --install arm64 docker buildx create --name verl-qemu --driver docker-container --use docker buildx build --platform linux/arm64 -f docker/Dockerfile.uv.cu130 \ -t verl:uv-cu130-arm64 --load .在出口代理egress proxy之后构建一个常见误区--build-arg http_proxy...只对RUN步骤生效而FROM中的基础镜像由 BuildKit 守护进程即buildx_buildkit_*容器自行解析——此时构建参数尚未生效因此代理参数无法解决failed to resolve source metadata for docker.io/nvidia/cuda:...之类的拉取失败。正确做法是把代理配置在builder上构建参数继续留给RUN步骤docker buildx rm verl-qemu 2/dev/null || true docker buildx create --name verl-qemu --driver docker-container --use \ --driver-opt env.http_proxyhttp://proxy.example.com:8118 \ --driver-opt env.https_proxyhttp://proxy.example.com:8118 \ --driver-opt env.no_proxylocalhost,127.0.0.1 docker buildx build --platform linux/arm64 -f docker/Dockerfile.uv.cu130 \ --build-arg http_proxyhttp://proxy.example.com:8118 \ --build-arg https_proxyhttp://proxy.example.com:8118 \ -t verl:uv-cu130-arm64 --load .如果 Docker Hub 始终不可达还可以完全绕开它把基础镜像指向内部镜像仓库arm64 构建要求该镜像仓库必须携带 arm64 manifestdocker buildx build --platform linux/arm64 -f docker/Dockerfile.uv.cu130 \ --build-arg CUDA_BASE_IMAGEmirror/nvidia/cuda \ -t verl:uv-cu130-arm64 --load .CUDA_BASE_IMAGE与CUDA_VERSION默认13.0.2在 Dockerfile.uv.cu130 中组合为FROM ${CUDA_BASE_IMAGE}:${CUDA_VERSION}-devel-ubuntu24.04 AS base。多架构单 Tag 发布x86_64 与 aarch64 可以共享同一个镜像 Tag发布为多架构 manifest listdocker pull verlai/verl:uv.cu130时会按拉取方架构自动解析下游镜像中的FROM verlai/verl:uv.cu130也会按构建平台解析——这正是nvidia/cuda官方镜像自身的工作方式也让一份 Dockerfile 一份作业规格同时覆盖两种架构。如果单个 builder 能同时触达两个平台例如同一 builder 中同时挂载了原生 x86_64 节点和原生 arm64 节点一条命令即可完成docker buildx build --platform linux/amd64,linux/arm64 \ -f docker/Dockerfile.uv.cu130 -t verlai/verl:uv.cu130 --push .更常见的情形是两次构建发生在不同机器、不同时间此时先推送带架构后缀的 Tag之后再进行合并——合并只是元数据操作瞬间完成且可重复执行# 分别在各自主机上原生构建 docker buildx build -f docker/Dockerfile.uv.cu130 -t verlai/verl:uv.cu130-amd64 --push . docker buildx build -f docker/Dockerfile.uv.cu130 -t verlai/verl:uv.cu130-arm64 --push . # 然后在任意位置合并 docker buildx imagetools create -t verlai/verl:uv.cu130 \ verlai/verl:uv.cu130-amd64 verlai/verl:uv.cu130-arm64 docker buildx imagetools inspect verlai/verl:uv.cu130 # 验证两个平台三个关键注意事项多平台构建必须--push--load无法把 index 放入本地 docker 镜像存储如需本地使用请一次只加载一个架构。若 registry 或运行时对 buildx 默认写入 index 的unknown/unknown附加证明条目报错请追加--provenancefalse。按 Tag 而非 digest 固定digest 只指向某一个具体 manifestFROM ...sha256:...会把镜像锁定到单一架构从而破坏多架构行为。uv 通用镜像Dockerfile.uv.cu130docker/Dockerfile.uv.cu130是 verl 容器化方案的另一条主线围绕 verl 项目的单一通用uv.lock构建一个镜像同时覆盖 CUDA 13.0 / torch 2.11 下的 vllm、sglang、fsdp、megatron 等全部后端以及无 GPU 的cpu切片且 x86_64 与 aarch64 共用一份 Dockerfilepyproject.toml的[tool.uv].environments同时声明两种架构因此提交的uv.lock携带两种架构的 wheel。设计要点烘焙 uv 缓存而非固定 .venv该镜像最核心的设计是构建时把全部后端的 uv 包缓存烘焙进镜像prefetch阶段但不烘焙固定的.venv。容器启动后没有安装步骤第一个uv run --extra ...会从烘焙好的缓存中把所选 extras 物化到/workspace/verl/.venv快速、离线该 venv 已在PATH上可直接运行DOCKER_BUILDKIT1 docker build -f docker/Dockerfile.uv.cu130 -t verl:uv-cu130 .进入容器并运行示例脚本docker run --rm -it --gpus all verl:uv-cu130 bash # 容器内工作目录 /workspace/verl其 .venv 已在 PATH 上 bash examples/grpo_trainer/run_qwen3_8b_fsdp.sh # ... 或显式拼出命令 uv run --frozen --all-packages --extra sglang --extra megatron \ python3 -m verl.trainer.main_ppo ...后端组合在运行时选择后端组合在运行时决定而非构建时且必须是无冲突的受[tool.uv].conflicts约束。典型组合规则为推理引擎vllm或sglang二选一 训练后端fsdp默认或megatroncpu为无 GPU 切片单独使用。uv 会直接拒绝不可能的组合而非解析出一个错误结果。各命令中的关键 flag 含义与 docs/start/install.rst 中描述一致--frozen按提交的uv.lock原样使用绝不重新解析--all-packages安装 uv workspace 中的所有包--extra engine --extra trainer本次运行的后端组合。实际示例脚本 run_qwen3_8b_fsdp.sh 展示了这一模式的落地当VERL_USE_UV未禁用、设备为 GPU 且推理后端为 vllm/sglang 时驱动进程与所有 Ray worker通过ray_kwargs.ray_init.runtime_env.py_executable统一使用uv run --frozen --all-packages --extra ${INFER_BACKEND} --extra fsdp python3启动保证作业内所有进程解析到同一环境其余后端 / NPU 场景自动回退到系统 python。多阶段构建与命名目标该 Dockerfile 采用多阶段结构详见 Dockerfile.uv.cu130可通过--target选择构建目标base系统依赖层是 sglang 与 vllm 上游 Dockerfile basic 阶段的超集包含完整 RDMA/InfiniBand、OpenMPI、NUMA、开发库、GDRCopy、IBGDA 符号链接与 localeUbuntu 24.04deps仅复制依赖元数据pyproject.toml、uv.lock、manage_envs.py、setup.py、verl/version/version使昂贵的prefetch缓存层只在依赖真正变化时才失效prefetch执行python3 manage_envs.py prefetch cu130 dev -- --frozen把 vllmfsdp、vllmmegatron、sglangfsdp、sglangmegatron、cpu 等无冲突运行时组合同步进临时环境纯粹用于填满UV_CACHE_DIR/root/.cache/uv该层刻意不使用--mounttypecache从而把预热的缓存作为镜像层提交进镜像运行时uv run/uv sync可离线解析final运行时镜像继承完整的烘焙缓存并复制 verl 源码同时将运行时默认编译器切换为 gcc-13解决 sglang 运行时 JIT 编译自定义 kernel 需要std::bit_cast、要求 GCC 11 的问题该层位于prefetch下游不会使昂贵的缓存层失效lock--targetlock用于重新生成uv.lockdocker build -f docker/Dockerfile.uv.cu130 --targetlock -t verl:uv-cu130-lock . docker create --name verl-tmp verl:uv-cu130-lock docker cp verl-tmp:/workspace/verl/uv.lock ./uv.lock docker rm verl-tmpprefetch的目标范围cu130 dev把镜像限定在 torch-2.11 世界。值得注意的是README 中提及的 companion 文件docker/Dockerfile.uv.cu129cu12.9 / torch-2.9.1 的 veomni、nemoautomodel 后端在当前仓库树中已不存在Dockerfile 注释说明其已被移除、可从 git 历史恢复trtllm后端因 CUDA-13 RC sdist 会引爆 uv 解析器而保持延迟deferred状态。构建参数速查参数默认值作用CUDA_VERSION13.0.2替代的 CUDA dev 基础镜像版本CUDA_BASE_IMAGEnvidia/cuda基础镜像仓库指向内部镜像UBUNTU_MIRROR空apt 镜像sglang 风格覆盖PIP_DEFAULT_INDEX空pip 全局 index URLGITHUB_ARTIFACTORYgithub.comGitHub 镜像地址NCCL_VERSION2.28.9-1与uv.lock中 torch 传递钉住的nvidia-nccl-cu13版本匹配从 Docker 镜像安装并运行 verl拉取目标镜像并完成推理/训练框架安装后可按以下步骤启动创建并进入容器docker create --runtimenvidia --gpus all --nethost --shm-size10g --cap-addSYS_ADMIN -v .:/workspace/verl --name verl image:tag sleep infinity docker start verl docker exec -it verl bash关键参数说明--runtimenvidia --gpus all暴露全部 GPU--nethost使用宿主机网络Ray 多节点与 NCCL 通信需要--shm-size10g扩大共享内存数据加载与分布式通信依赖--cap-addSYS_ADMIN授予系统管理权限-v .:/workspace/verl将 verl 源码挂载进容器实现宿主机编辑、容器内运行。安装 verl 本体使用官方镜像时依赖已齐备仅需安装 verl 本身# 安装 nightly 版本推荐 git clone https://github.com/verl-project/verl cd verl pip3 install --no-deps -e .可选在不同推理框架间切换# 安装 nightly 版本推荐 git clone https://github.com/verl-project/verl cd verl pip3 install -e .[vllm] pip3 install -e .[sglang]镜像发布历史时间vLLM StableSGLang Stable关键变更2026/07/21vllm 0.24.0torch 2.11.0, CUDA 13.0.2, Ubuntu 24.04sglang 0.5.12当前最新 Stable 版本2026/03/10vllm 0.17.0sglang 0.5.9—2026/01/17torch 2.9.1, cudnn 9.16, deepep 1.2.1—vLLM 系依赖更新2025/12/23vllm 0.12.0sglang 0.5.6从该版本起 vLLM 改用 CUDA devel 基础镜像2025/11/18vllm 0.11.1sglang 0.5.5—结合源码观察vLLM Stable 镜像的内部版本号标注为verlai/verl:vllm024.dev2见 Dockerfile.stable.vllmSGLang 为verlai/verl:sgl0512.dev4见 Dockerfile.stable.sglang即 Stable 镜像在内部迭代过程中仍以dev后缀进行渐进式发布。此外uv 镜像还内置了 Nsight Systems 2025.6.1并与 Stable 镜像保持同一版本便于跨镜像对比性能剖析结果。小结与选型建议追求开箱即用直接拉取verlai/verl:sgl0512.latest或verlai/verl:vllm024.latest等预构建镜像按“创建容器 → 安装 verl → 运行示例”三步走需要复现或离线部署使用Dockerfile.uv.cu130构建 uv 镜像其烘焙缓存支持离线物化任意后端组合且同一镜像覆盖 x86_64 与 aarch64GB200aarch64场景目前需在 arm64 硬件上本地构建可借助远程原生 buildx 节点或 QEMU 模拟从 x86_64 驱动Ascend NPU / AMD ROCm / TensorRT-LLM不在 uv 工作流范围内请使用 docker/ascend/ 下的 Ascend 专用 Dockerfile、docker/rocm/Dockerfile.rocm 或 Dockerfile.stable.trtllm。更多关于 uv 启动流程、烘焙缓存机制与重新锁定的细节可参阅 docs/start/install.rst 中的 Install with uv 章节以及 manage_envs.py 中prefetch/lock/sync等子命令的实现。【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考