使用 pip 的 vLLM Dockerfile (Ubuntu 24.04)

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

提示

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

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

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

WORKDIR /app

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

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

Dockerfile 说明

从宏观上看，我们在为运行 vLLM 应用程序构建 Docker 镜像时，主要优化了以下内容：

• PEP 668 兼容：使用单独的 venv 虚拟环境隔离应用与底层系统库依赖冲突。
• 构建环境隔离：通过设置工作目录（WORKDIR）建立独立的目录结构。
• 持久化构建缓存：利用 BuildKit 挂载机制复用 pip 下载缓存，提升重复构建速度。

基础运行环境

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

运行时基于 Ubuntu 24.04 基础镜像，系统内包含完整的 Shell 和底层系统依赖。

关键环境变量

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

• PIP_INDEX_URL：配置国内 PyPI 镜像源（如清华源），提升依赖包的下载速度。
• 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/pip \
    python3 -m venv $VIRTUAL_ENV && \
    pip install "vllm==0.16.0"

利用 BuildKit 的长期缓存机制（--mount=type=cache）挂载 pip 缓存目录，能显著加快镜像重建速度。该步骤首先初始化 Python 虚拟环境，随后通过 pip 安装 vLLM 核心框架。

缓存挂载参数说明：

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

项目安装

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

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