使用 uv 的 SGLang Dockerfile (CUDA 12.9.1, Ubuntu 22.04)

下面是一个平台推荐的 Dockerfile 示例，用于构建包含 SGLang 推理框架的 Docker 镜像。基于 Ubuntu 22.04 构建，使用 uv 作为包管理器安装 SGLang 0.5.9。本文提供两种构建方案：

• 分层构建（推荐）：基于预先构建好的自定义 CUDA 镜像叠加安装，构建速度快。
• 一体化构建：从零开始在单个 Dockerfile 中依次安装 CUDA 12.9.1、cuDNN 9.x 和 SGLang，适合在开发机内使用 docker build 构建。

分层构建

基于预先构建好的自定义系统级 CUDA 镜像叠加安装 SGLang。请先参照 CUDA 12.9.1 + cuDNN 9 Dockerfile (Ubuntu 22.04) 构建 CUDA 基础镜像，并将其推送至租户私有镜像仓库以供后续复用。

FROM ghcr.io/astral-sh/uv:latest AS builder

FROM YOUR_CUSTOM_CUDA_IMAGE

COPY --from=builder /uv /uvx /bin/

ENV UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
ENV UV_COMPILE_BYTECODE=1

WORKDIR /app

RUN --mount=type=cache,target=/root/.cache/uv \
    uv pip install --system --no-cache \
        "sglang==0.5.9" --prerelease=allow

注意

请将 YOUR_CUSTOM_CUDA_IMAGE 替换为您实际推送的 CUDA 基础镜像地址。分层复用 CUDA 基础镜像可大幅节约后续应用镜像的构建时间。

一体化构建

以下 Dockerfile 一次性安装系统级 CUDA 12.9.1、cuDNN 9.x 和 SGLang，无需预先准备 CUDA 基础镜像。

注意

此方案更适用于在开发机内部使用 docker build 命令构建镜像。如果在镜像中心使用该 Dockerfile 构建镜像，构建时间有可能超过 1 小时限制，导致构建失败。

FROM ghcr.io/astral-sh/uv:latest AS builder

FROM cr.infini-ai.com/infini-ai/ubuntu:22.04-20240429

COPY --from=builder /uv /uvx /bin/

ENV PATH=/usr/local/cuda/bin:/usr/local/cuda-12.9/bin${PATH:+:${PATH}} \
    LD_LIBRARY_PATH=/usr/local/cuda/lib64:/usr/local/cuda-12.9/lib64:/usr/lib/x86_64-linux-gnu${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} \
    CUDA_HOME=/usr/local/cuda \
    CPATH=/usr/include${CPATH:+:${CPATH}} \
    LIBRARY_PATH=/usr/lib/x86_64-linux-gnu${LIBRARY_PATH:+:${LIBRARY_PATH}}

ENV UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
ENV UV_COMPILE_BYTECODE=1

RUN apt-get update && \
    DEBIAN_FRONTEND=noninteractive apt-get install -y wget build-essential \
    && rm -rf /var/lib/apt/lists/* \
    && wget https://developer.download.nvidia.com/compute/cuda/12.9.1/local_installers/cuda_12.9.1_575.57.08_linux.run \
    && sh cuda_12.9.1_575.57.08_linux.run --toolkit --silent --override \
    && echo '/usr/local/cuda/lib64' >> /etc/ld.so.conf \
    && echo '/usr/local/cuda-12.9/lib64' >> /etc/ld.so.conf \
    && ldconfig \
    && rm cuda_12.9.1_575.57.08_linux.run

RUN wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb \
    && dpkg -i cuda-keyring_1.1-1_all.deb \
    && apt-get update \
    && apt-get install -y cudnn-cuda-12 \
    && echo '/usr/lib/x86_64-linux-gnu' >> /etc/ld.so.conf \
    && ldconfig \
    && rm cuda-keyring_1.1-1_all.deb \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

RUN --mount=type=cache,target=/root/.cache/uv \
    uv pip install --system --no-cache \
        "sglang==0.5.9" --prerelease=allow

注意

如果出现以下情况，我们推荐您自己构建镜像：

• 环境不匹配：平台提供的镜像不满足您特定的软件版本（如框架、库）组合。
• 访问受限：您访问外部 Docker Hub 等公共仓库不方便或受限。

本文包含的 Dockerfile 可用于在镜像中心基于 Dockerfile 构建镜像，或直接在开发机中构建镜像（使用 docker build / docker buildx build 命令）。

关于什么是系统级 CUDA 环境，可参考以下教程：

📖 手动安装特定版本的系统级 CUDA/cuDNN

📖 NVIDIA CUDA Toolkit 与 PyTorch 安装中的 CUDA 的区别

📖 获取系统级 CUDA/cuDNN 环境

Dockerfile 说明

从宏观上看，我们在为运行 SGLang 应用构建及优化 Docker 镜像时，主要进行了以下设计：

• 多阶段构建：将包管理器工具（uv、uvx）的提取与应用运行环境分离，避免在运行时层面安装多余的底层工具依赖。
• 分层镜像策略：推荐先行构建并复用 CUDA 基础镜像，再叠加安装应用框架，极大缩短后续的重复构建时间。
• 持久化构建缓存：利用 BuildKit 挂载机制复用 uv 的缓存结构，使重复构建更轻巧。
• 清除多余残留：安装后在单层 RUN 步骤内部迅速清理安装包缓存，减小镜像体积。

获取构建工具（多阶段）

FROM ghcr.io/astral-sh/uv:latest AS builder

此阶段基于官方 uv 镜像，仅用于提取 uv 和 uvx 可执行文件。这是一种轻量级的获取二进制文件的方式，避免在运行环境中通过 pip install uv 引入不必要的依赖。

配置运行时环境

FROM YOUR_CUSTOM_CUDA_IMAGE

COPY --from=builder /uv /uvx /bin/

运行时阶段将第一阶段提取的 uv 和 uvx 二进制文件复制到 /bin/，确保其在 $PATH 内可被直接调用。在分层构建方案中，基础镜像已经包含了完整的 CUDA 与 cuDNN 环境；在一体化构建方案中，则使用 Ubuntu 22.04 基础镜像并在后续步骤中安装 CUDA 和 cuDNN。

关键环境变量

ENV UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
ENV UV_COMPILE_BYTECODE=1

• UV_INDEX_URL：配置国内 PyPI 镜像源（如清华源），提升依赖包的下载速度。
• UV_COMPILE_BYTECODE=1：指示 uv 将 Python 文件编译为字节码，以加快应用程序启动速度。

安装 SGLang

WORKDIR /app

RUN --mount=type=cache,target=/root/.cache/uv \
    uv pip install --system --no-cache \
        "sglang==0.5.9" --prerelease=allow

WORKDIR 设定容器内的主要活动路径。利用 BuildKit 的缓存挂载机制（--mount=type=cache）复用 uv 缓存目录，使用 --system 标志将 SGLang 及其依赖直接安装到系统级 Python 环境中。--prerelease=allow 允许解析并安装尚处于预发布阶段的依赖版本。如需安装其他版本的 SGLang，直接修改版本号（如 "sglang==0.5.8"）即可。

一体化构建中的 CUDA 与 cuDNN 安装

如果选择一体化构建方案，CUDA 与 cuDNN 的安装步骤与 CUDA 12.9.1 + cuDNN 9 Dockerfile (Ubuntu 22.04) 完全一致，具体说明请参考该文档。