使用 uv 的 vLLM Dockerfile (Ubuntu 22.04)

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

提示

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

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 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 "vllm==0.16.0"

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

Dockerfile 说明

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

• 多阶段构建：将包管理器工具的提取与真正应用程序运行环境分离，避免在运行时层面安装多余的底层网络工具。
• 精简基础依赖：使用已经配置好 Python 的 Ubuntu 基础镜像，减少系统层安装步骤。
• 构建环境隔离：通过设置工作目录（WORKDIR）建立独立的内部目录结构。
• 持久化构建缓存：利用 BuildKit 挂载机制复用高速包管理器 uv 的缓存结构，使得重复安装和重建更轻巧。

第一阶段：获取构建工具

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

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

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

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

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

运行时阶段基于 Ubuntu 基础镜像。由于该镜像默认已经自带了 Python 环境，同时也无需再去规避 PEP 668 规范，所以我们可以精简很多相关配置。首先它将第一阶段的 uv 和 uvx 二进制文件复制到当前镜像的默认执行库 /bin/ 中，以确保在任何环境下都能立即被调用。

[NOTE] 为了遵循 PEP 394 以及现代 Linux 发行版（如 Ubuntu 20.04 以上）的社区最佳实践，基础容器内默认只提供明确的版本化命令 python3 和 pip3（未创建全局 python 软链接），请在执行环境和调用脚本时统一使用 python3 作为调用命令。

关键环境变量

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 文件编译为字节码，以加快应用程序启动速度。

设置工作目录

WORKDIR /app

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

依赖安装

RUN --mount=type=cache,target=/root/.cache/uv \
    uv pip install --system "vllm==0.16.0"

利用 BuildKit 的长期缓存机制（--mount=type=cache）挂载 uv 缓存目录，能显著加快镜像重建速度。这里利用 --system 标志直接将包并入系统级 Python 环境中。uv 即使遇到中止操作也能优雅地维护缓存一致性。

缓存挂载参数说明

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

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

项目安装

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

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