Docker for SGLang Development: Images, Containers, and Reproducible GPU Workflows

文档教程人工智能大模型RLHF【免费下载链接】Awesome-ML-SYS-TutorialMy learning notes for ML SYS.项目地址https://gitcode.com/gh_mirrors/aw/Awesome-ML-SYS-Tutorial点击查看免费下载Docker 是 ML 系统开发中最基础也最容易被忽略的一环它把 Python、CUDA、cuDNN 等环境连同代码一起打包成镜像让深度学习代码真正具备可复现性也让集群上的多用户协作不再互相污染环境。本文以当前仓库中 Docker 使用指南 为骨架结合仓库内 SGLang、verl 的实际开发记录完整讲解镜像下载、容器运行、容器管理、镜像构建与上传以及 VSCode 远程容器开发这整套工作流读完即可在共享 GPU 集群上独立搭建可复现的 SGLang 开发环境。1. 为什么用 Docker镜像Image与容器ContainerDocker 是一种将**环境打包成镜像image的软件工具。用户把这些镜像运行在容器container**中从而获得完全一致的环境无需手工配置。使用官方 PyTorch 镜像后你不再需要担心运行深度学习代码时 Python、CUDA、cuDNN 之间的版本兼容问题。镜像相当于压缩包必须解压成容器才能运行宿主机host machine指的就是你所在的服务器。在共享集群场景下Docker 的价值更具体详见 中文版文档可复现且隔离的环境可以在容器内自由安装依赖、修改系统配置而不影响宿主机即使没有 sudo 权限也能在容器内完成所有必要的环境配置避免在我机器上能跑的问题。共享磁盘空间集群磁盘往往吃紧例如 8×H100 集群可能只有 3T 磁盘。通过统一账号登录、每个开发者一个容器并把外部的 HuggingFace cache 统一映射进容器避免每个用户重复缓存同一份模型权重显著节省磁盘。2. 安装 DockerSGLang 的开发环境是 Linux 系统安装时请注意以下三点通常无需手动安装服务器管理员会预先装好 Docker你也不需要 sudo 权限来安装软件。nerdctl 兜底如果服务器上找不到 Docker可以改用nerdctl——它完全兼容 Docker 命令只需把指令替换成nerdctl xxx即可。管理员手动安装可参考 Docker 官方安装文档Install | Docker Docs或咨询 GPT。3. 下载 Docker 镜像绝大多数 Docker 镜像发布在 Docker Hub 上。开发 SGLang 时推荐使用官方镜像lmsysorg/sglang# 下载镜像 # docker pull image-name docker pull lmsysorg/sglang:latest镜像的 tag 选择在仓库的实际开发中有明确分工用户usersdocker pull lmsysorg/sglang:latest开发者developersdocker pull lmsysorg/sglang:dev部分开发问题可能需要特定镜像届时联系 issue 负责人确认即可。此外仓库中记录了为 verl–SGLang CI 专门构建的镜像例如ocss884/verl-sglang:ngc-th2.6.0-cu126-sglang0.4.5.post3见 readme.md。这类镜像名里带 SGLang 版本号通常不是最新的 SGLang主要用于 CI 测试实际开发 verl–SGLang 时仍使用 SGLang 官方镜像再在容器内安装 verl 和最新版 SGLang。4. 在容器内运行镜像docker run运行容器的指令格式是docker run [OPTIONS] IMAGE [COMMAND]OPTIONS运行容器时的附加参数IMAGE镜像名必须放在OPTIONS之后、COMMAND之前COMMAND容器启动时执行的命令4.1 常用 OPTIONS必读参数含义说明-it交互式终端有该参数才能在容器内使用交互式终端。不加-it时docker run ubuntu bash会因无法接收输入而立即退出--name container-name容器名便于标识容器用途或归属。请遵循服务器命名规范否则可能被管理员当作孤儿容器删除--shm-size shared-memory-size共享内存大小深度学习框架需要大内存默认 64MB 会导致崩溃建议至少设为 16GB--gpus all允许访问 GPU除非有特殊的 GPU 分配需求否则设置为all-v host-path:container-path目录挂载把宿主机host-path的全部内容挂载到容器container-path宿主机与容器共享目录下所有文件修改双向可见。可多次使用常用于映射代码工作区、数据集、模型文件和配置文件关于-v挂载原文档给出了两个高频实战场景把 Hugging Face cache 从宿主机映射进容器让容器复用已下载的模型而无需重复下载-v ~/.cache/huggingface:/root/.cache/huggingface在 Linux 上pwd会输出当前目录路径可用-v $(pwd):container-path直接挂载执行docker run的目录实现在宿主机上开发、在容器里运行代码-v $(pwd):/workspace把常用参数组合起来一条完整的命令形如docker run -it --name container-name --shm-size 16g --gpus all -v host-path:container-path IMAGE4.2 可选 OPTIONS参数含义说明-p host-port:container-port端口映射把容器内container-port映射到宿主机host-port使外部可通过宿主机端口访问容器内服务可多次使用--network host网络共享容器直接使用宿主机网络共享 IP、端口和网络资源。服务器在国内时加--network host可共享网络代理使用该参数时-p会被忽略-e env-nameenv-value环境变量设置容器内环境变量的值可多次使用--ipchost进程间通信命名空间共享允许容器内进程与宿主机进程通信可用于替代--shm-size-d后台运行容器在后台运行退出终端时容器不停止--rm退出即删容器退出后自动删除4.3 IMAGE用户docker pull lmsysorg/sglang:latest开发者docker pull lmsysorg/sglang:dev部分开发问题需要不同镜像时请与 issue 负责人沟通。4.4 COMMAND指定容器启动时执行的命令在启动容器的同时可以指定容器立即执行的命令。两个典型场景场景一在容器内启动 bash 终端像虚拟机一样输入命令、管理文件docker run -it [other OPTIONS] image-name bash场景二在容器内启动 SGLang server服务运行在容器 30000 端口并映射到宿主机 30000 端口供外部访问同时用环境变量HF_TOKEN指定模型 tokendocker run -p 30000:30000 --env HF_TOKENhf_xxx [other OPTIONS] image-name python3 -m sglang.launch_server [other parameters]4.5 仓库内的真实 docker run 用例仓库中多个文档给出了生产级的 docker run 示例可对照本文参数逐项理解Qwen2.5VL GRPO 训练环境见 veRL-VLM.md使用--shm-size 32g、挂载/root/.cache、通过--env注入HF_TOKEN与WANDB_API_KEY并配合--ipchostdocker run -it --name h100_verl_{your_name} --gpus all \ --shm-size 32g \ -v /.cache:/root/.cache \ --env HF_TOKEN$HF_TOKEN \ --env WANDB_API_KEY$WANDB_API_KEY \ --ipchost \ lmsysorg/sglang:latest \ /bin/bashTP2 复现环境见 debug-tp-2.md进一步组合了--networkhost、--privileged并挂载 HuggingFace cachedocker run \ -it \ --shm-size 32g \ --gpus all \ -v {YOUR_HUGGINGFACE_CACHE_DIR}:/root/.cache \ --ipchost \ --networkhost \ --privileged \ --name sglang-FSDP-TP-2 \ lmsysorg/sglang:dev \ /bin/zshAMD GPUROCm开发环境见 dev.md展示--rm、--device直通、--cap-add SYS_PTRACE、-w $PWD等工作在特殊硬件上的参数用法docker run --rm -it \ --device /dev/dri \ --device /dev/kfd \ -p 8265:8265 \ --group-add video \ --cap-add SYS_PTRACE \ --security-opt seccompunconfined \ --privileged \ -v $HOME/.ssh:/root/.ssh \ -v $HOME:$HOME \ --shm-size 128G \ --name verl_vllm_upstream \ -w $PWD \ lmsysorg/sglang:v0.4.5-rocm630 \ /bin/bash5. 容器管理5.1 容器生命周期run / start / restart / exec 的区别理解四个核心命令的差异是容器管理的基础对比详见 readme.md命令容器不存在时容器存在时docker run创建并启动新容器买台新电脑并开机报错Error: Conflict. The container name is already in use不能创建同名容器docker start报错Error: No such container启动已停止的容器保持原配置不变把已关机的电脑重新开机docker restart报错Error: No such container先停止再启动重启电脑用于容器崩溃时docker exec报错Error: No such container仅当容器正在运行时可执行命令已停止时报错Error: Container is not running配套的使用场景示例源自 readme.md# 1. 首次创建并运行容器 docker run -it --name my_container ubuntu bash # 2. 容器停止后重新启动 docker start my_container # 3. 容器运行中需要重启 docker restart my_container # 4. 容器运行中需要打开新的终端 docker exec -it my_container bash # 5. 如果容器已存在想创建新容器 docker run -it --name my_container_new ubuntu bash5.2 查看容器docker ps查看正在运行的容器docker ps -a查看所有容器含已停止的docker ps -a -s查看所有容器及其大小5.3 停止容器退出会话并停止容器输入exit或按Ctrl D退出会话但保持容器后台运行按Ctrl P后再按Ctrl Q部分 IDE 中因快捷键冲突可能失效或在docker run时加-d参数退出终端后容器仍在运行或直接关闭终端停止正在运行的容器docker stop container-name注意容器会在COMMAND执行完毕后自动停止。5.4 重启与再次进入容器docker restart container-name容器必须处于运行状态才能 attach。进入正在运行的容器docker exec -it container-name bashexec在运行中的容器内执行命令也可以借此修改环境变量。仓库的 latest_sglang.md 还演示了退出后再次回到会话的惯用法先用docker start -i重启并进入已命名的容器docker start -i h100_verl_{your_name}5.5 删除容器删除前必须先停止容器docker stop container-name docker rm container-name或在docker run时加--rm容器退出后自动删除。5.6 特别说明使用--rm时容器停止后会被自动删除此时start和restart都会失败exec只能用于运行中的容器不能用于已停止的容器run是创建新容器其余命令都是操作已存在的容器。6. 构建镜像Dockerfile 详解为 CI 测试机器发布稳定的 Docker 镜像是日常开发必不可少的一环。构建镜像的意义在于安装特定版本的 CUDA、PyTorch 驱动加入自己写的脚本和代码配置环境变量等。Docker 构建镜像的过程基于Dockerfile忠实地执行这些操作。6.1 Dockerfile 常见指令指令作用关键点FROM base-image:tag指定基础镜像告诉 Docker 基于哪个现有镜像开始构建WORKDIR /path/to/workdir设置工作目录后续指令都在该目录下执行目录不存在时会自动创建RUN command在镜像内部执行命令每条RUN都会在当前镜像基础上新增一层为减少层数与体积、加快构建通常把多个apt-get install或pip install用连成一条RUNCOPY host-path container-path复制文件进镜像把宿主机文件或目录复制到镜像内指定路径CMD [command, param1, param2]指定容器启动时的默认命令也支持 shell formCMD command param1 param2一个 Dockerfile 只能有一条CMD多条时只有最后一条生效docker run指定了命令时CMD会被覆盖ENV keyvalue设置容器运行时的环境变量镜像构建时不生效ARG keyvalue设置镜像构建时的临时变量容器运行时不生效6.2 示例 Dockerfile# 导入 Nvidia 官方镜像 # 该镜像已装好 CUDA 12.1.1 与 cuDNN 8.9.0无需再处理版本兼容问题 FROM nvidia/cuda:12.1.1-cudnn8-devel-ubuntu22.04 # 设置工作目录为 /sgl-workspace WORKDIR /sgl-workspace # 设置环境变量如 huggingface token 用于下载模型 ENV HF_TOKENhf_xxxyyyzzz # 安装开发工具 RUN apt-get update apt-get install -y \ vim \ tmux \ wget \ git \ rm -rf /var/lib/apt/lists/* \ apt-get clean # 将当前目录下的 app.py 文件复制到容器内的工作目录 COPY app.py /sgl-workspace/app.py # 默认执行命令启动 Python 脚本 CMD [python3, app.py]6.3 构建命令docker build -t image-name:tag -f docker-file path-t image-name:tag镜像的名字和标签-f docker-fileDockerfile 的路径path构建上下文路径即 Docker 构建时可以访问的文件和目录的根路径决定 Dockerfile 中COPY、ADD等文件引用的查找范围通常设为.表示当前目录也可以是其他本地目录或 Git 仓库 URL。6.4 仓库实战为 verl 构建带指定 SGLang 版本的镜像how_to_bump_version.md 完整记录了一次为 verl 升级 SGLang 版本0.4.9 → 0.4.10.post2并构建镜像的流程可看作第 6、7 节的端到端实例① 编写 Dockerfile基于 verl 基础镜像通过ENV与多条RUN安装指定版本的 SGLang 及其依赖节选# Start from the verl base image FROM verlai/verl:base-verl0.5-cu126-cudnn9.8-torch2.7.1-fa2.7.4 ENV MAX_JOBS8 ENV HF_HUB_ENABLE_HF_TRANSFER1 # Install FlashInfer and the pinned SGLang version RUN pip install --resume-retries 999 --no-cache-dir --no-build-isolation flashinfer-python0.2.9rc1 RUN pip install --resume-retries 999 --no-cache-dir --no-build-isolation sglang[all]0.4.10.post2② 构建镜像注意不能在 Docker 容器内 buildDocker 相关操作应在裸机上完成先登录自己的 Docker 账号docker login -u [your_username] docker build -t popsodazhp/verl:app-verl0.5-sglang0.4.10.post2-mcore0.12.2-te2.2 \ -f docker/verl0.5-cu126-torch2.7-fa2.7.4/Dockerfile.app.sglang0.4.10.post2.mcore0.12 .③ 推送并验证push 上去后修改 CI 配置文件中的镜像名观察 CI 是否通过通过后与 verl 团队协商由官方构建镜像。7. 上传镜像tag、login、push镜像构建好后可以把本地镜像 push 到远程镜像仓库如 Docker Hub。7.1 给镜像打标签对于 Docker Hub镜像名通常是dockerhub-username/repo-name:tag。如果docker build时已经用了这个格式这一步可以跳过否则或要推送到不同仓库/用户名下需要重新打标签docker tag source-image:tag target-image:tag7.2 登录镜像仓库在 Docker Hub 注册账号后使用docker login在本地登录docker login7.3 推送镜像确保image-name:tag是上一步打好的、符合仓库规范的完整名称然后推送docker push image-name:tag8. 在 VSCode 中使用 DockerDevcontainer开发容器Devcontainer让你在 VSCode 的全部功能补全、调试、Git 等都作用于容器内部是最接近容器内开发体验的方式。前置条件确保在 VSCode 中安装 Dev Containers 扩展。步骤在你希望于容器内打开的文件夹中创建.devcontainer子目录在.devcontainer下创建devcontainer.json例如{ name: simon, build: { dockerfile: ../docker/cuda_new.Dockerfile }, runArgs: [ --gpus, device7 ] }dockerfile字段指向你要使用的 Dockerfile 路径按实际路径修改这里指向上一级docker/cuda_new.DockerfilerunArgs等价于docker run的 OPTIONS示例中把容器限定使用编号为 7 的 GPU即--gpus device7。按Ctrl Shift P输入并执行Dev Containers: Open Folder in Container...选择创建了.devcontainer子目录的文件夹。之后你就能在容器内使用 VSCode 的全部功能进行开发。更详细的 Devcontainer 用法可参阅 VSCode 官方 Dev Containers 文档。总结本文从镜像与容器的概念出发完整覆盖了 SGLang 开发中的 Docker 工作流安装与 nerdctl 兜底、拉取lmsysorg/sglang官方镜像、用docker run组合-it/--shm-size/--gpus/-v/--env等参数搭建 GPU 开发环境、通过ps/start/restart/exec/rm管理容器生命周期、用Dockerfile构建带固定版本依赖的镜像并tag/login/push发布以及在 VSCode 中通过devcontainer.json进入容器开发。仓库内 veRL-VLM.md、debug-tp-2.md、dev.md 和 how_to_bump_version.md 中的真实命令均可作为本文所述参数与流程的直接验证样本建议在动手前通读对照。赞分享文档教程人工智能大模型RLHF【免费下载链接】Awesome-ML-SYS-TutorialMy learning notes for ML SYS.项目地址https://gitcode.com/gh_mirrors/aw/Awesome-ML-SYS-Tutorial点击查看免费下载相关推荐一键拿到网盘直链八大网盘直链解析油猴脚本全攻略安装4类常见故障一键拿到网盘直链八大网盘直链解析油猴脚本全攻略安装4类常见故障 工作交接时前同事把项目资料丢进网盘只留了一条分享链接。浏览器里下载速度慢得能看清数前端OCRmyPDF让扫描PDF秒变可搜索文本的终极指南OCRmyPDF让扫描PDF秒变可搜索文本的终极指南 一份 200 页的扫描合同没有文本层CtrlF 搜不到条款只能逐页人眼翻找。用免费的 OCRmyPOCRCLIgh_mirrors/sh1/sh的错误处理模式Result类型与错误链的应用gh_mirrors/sh1/sh的错误处理模式Result类型与错误链的应用 在Shell解析器和解释器开发中错误处理直接影响系统稳定性和用户体验。gh_API网关后端云原生LLM 网关人工智能MCP 服务上一篇Resources Saver从网页资源收集困境到一键式解决方案的完整指南下一篇Fort FirewallWindows系统智能网络安全防护方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考