使用 uv 的 vLLM Dockerfile (Ubuntu 24.04)

下面是一个平台推荐的 Dockerfile 示例，用于为使用 uv 作为包管理器的 vLLM 应用构建 Docker 镜像。基于 Ubuntu 24.04。

提示

在平台预置镜像不满足要求，或无法访问 Docker Hub 时，推荐您使用下方 Dockerfile 自行构建镜像。

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

FROM cr.infini-ai.com/infini-ai/ubuntu:24.04

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

ENV UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
ENV UV_COMPILE_BYTECODE=1
ENV VIRTUAL_ENV=/opt/vllm-env
ENV PATH="$VIRTUAL_ENV/bin:$PATH"

WORKDIR /app

RUN --mount=type=cache,target=/root/.cache/uv \
    uv venv $VIRTUAL_ENV && \
    uv pip install "vllm==0.16.0"

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

Dockerfile 说明

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

• 多阶段构建：将包管理器工具的提取与真正应用程序运行环境分离，避免在运行时层面安装多余的底层网络工具。
• PEP 668 兼容：使用独立的虚拟环境隔离应用程序，避免破坏底层系统依赖。
• 构建环境隔离：通过设置工作目录（WORKDIR）建立独立的目录结构。
• 持久化构建缓存：利用 BuildKit 挂载机制复用高速包管理器 uv 的缓存结构，使得重复安装和重建更轻巧。

第一阶段：获取构建工具

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

此阶段基于官方 uv 镜像，主要目的是提取并提供 uv 可执行文件。这是一种轻量级的获取二进制文件的方式，避免在运行环境安装不必要的包管理工具依赖。

第二阶段：配置运行时环境

FROM cr.infini-ai.com/infini-ai/ubuntu:24.04

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

运行时阶段基于 Ubuntu 基础镜像。系统包含完整的 Shell 和底层依赖，首先将第一阶段的 uv 与其扩展工具 uvx 的二进制文件复制到当前镜像的默认执行库 /bin/ 中，以确保在任何环境下都能立即被调用。

关键环境变量

ENV UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
ENV UV_COMPILE_BYTECODE=1
ENV VIRTUAL_ENV=/opt/vllm-env
ENV PATH="$VIRTUAL_ENV/bin:$PATH"

• UV_INDEX_URL：配置国内 PyPI 镜像源（如清华源），提升依赖包的下载速度。
• UV_COMPILE_BYTECODE=1：指示 uv 将 Python 文件编译为字节码，以加快应用程序启动速度。
• UV_LINK_MODE=copy：确保 uv 复制文件而不是创建符号链接。在进行跨文件系统构建或需要完整镜像复制时特别有用。
• VIRTUAL_ENV 与 PATH：定义虚拟环境的隔离路径，并将其添加到系统的执行路径优先位置。此举主要是为了遵循 PEP 668 规范，避免修改操作系统基础环境进而引发冲突。一种风险较高（不推荐）的替代方案是在安装时指定 --break-system-packages 标志，或直接设置环境变量 ENV PIP_BREAK_SYSTEM_PACKAGES=1。

设置工作目录

WORKDIR /app

WORKDIR 设定了容器内的主要活动路径。后续的所有命令（如 RUN、CMD、ENTRYPOINT 或 COPY）默认都会在该目录下相对执行，这有助于代码结构隔离，并维持虚拟环境之外的文件系统整洁。

依赖安装

RUN --mount=type=cache,target=/root/.cache/uv \
    uv venv $VIRTUAL_ENV && \
    uv pip install "vllm==0.16.0"

利用 BuildKit 的长期缓存机制（--mount=type=cache）挂载 uv 缓存目录，能显著加快镜像重建速度。该步骤首先初始化 Python 虚拟环境，随后高速安装 vLLM 核心框架。uv 即使遇到中止操作也能优雅地维护缓存一致性。

缓存挂载参数说明

• type=cache：指定这是一个跨构建持久化的缓存挂载。
• target=/root/.cache/uv：uv 缓存目录的挂载点，用于存储已下载的包和编译后的 wheel 文件。

有关 uv 缓存挂载的详细信息，请参阅官方 uv 文档。

项目安装

如果在 vLLM 基础上需要封装您自己的扩展逻辑参数或上层 API 服务，可以在所有系统和框架依赖准备妥当后，将应用代码合并至镜像内：

# COPY ./src /app/src
# WORKDIR /app
# RUN uv pip install -r requirements.txt