vllm 重新梳理cpu源码安装(版本0.21.0) (小白级文档)

声明: 纯兴趣爱好，如有疏漏敬请谅解。

源码版本: v0.21.0

学习相关源码路径: 

​​​​​​https://github.com/vllm-project/vllm/blob/v0.21.0/vllm/entrypoints/cli/main.py

之前写过一篇关于vllm源码编译安装的文章，但版本是0.19.0。现在正在学习的代码的版本是0.21.0，所以准备重新整理一下。0.19.0和0.21.0源码编译还是有一点小区别的。

源码安装

1. 准备dockerfile

摘抄自官方文件 https://github.com/vllm-project/vllm/blob/v0.21.0/docker/Dockerfile.cpu

建议不管学习还是以后做项目都以官方dockerfile为模版。

由于只用于vllm的源码编译，所以先只使用官方的部分dockerfile文件。

当然也可以直接使用官方的dockerfile，由于自己学习逐行摘抄便于理解。

文件内容如下:

FROM ubuntu:22.04 AS base-common

WORKDIR /workspace

ARG PYTHON_VERSION=3.12
ARG PIP_EXTRA_INDEX_URL="https://download.pytorch.org/whl/cpu"

# Install minimal dependencies and uv
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update -y \
    && apt-get install -y --no-install-recommends sudo ccache git curl wget ca-certificates \
    gcc-12 g++-12 libtcmalloc-minimal4 libnuma-dev ffmpeg libsm6 libxext6 libgl1 jq lsof make xz-utils \
    && update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-12 10 --slave /usr/bin/g++ g++ /usr/bin/g++-12 \
    && curl -LsSf https://astral.sh/uv/install.sh | sh

ENV CC=/usr/bin/gcc-12 CXX=/usr/bin/g++-12
ENV CCACHE_DIR=/root/.cache/ccache
ENV CMAKE_CXX_COMPILER_LAUNCHER=ccache
    
ENV PATH="/root/.local/bin:$PATH"
ENV VIRTUAL_ENV="/opt/venv"
ENV UV_PYTHON_INSTALL_DIR=/opt/uv/python
RUN uv venv --python ${PYTHON_VERSION} --seed ${VIRTUAL_ENV}
ENV PATH="$VIRTUAL_ENV/bin:$PATH"

可以理解为，用于vllm编译的基础镜像。

特别注意最后几行，把虚拟环境加入到PATH中，每次进入容器不需要手动激活环境(与我之前整理的有出入)

2. 构建镜像

使用dockerfile构建自己的镜像，执行如下命令:

docker build --target=base-common -t vllm-base-test:0.21.0 -f {你的docker文件} .

以我的为例:

docker build --target=base-common -t vllm-base-test:0.21.0 -f ./hella_vllm_0.21.0/Dockerfile .

3. 生成容器

命令如下:

docker run -it --name vllm-base-test vllm-base-test:0.21.0 /bin/bash

4. 编译

进入你的容器，在源码路径下执行如下命令

uv pip install -r requirements/build/cpu.txt --torch-backend cpu --index-strategy unsafe-best-match
uv pip install -r requirements/cpu.txt --torch-backend cpu --index-strategy unsafe-best-match

VLLM_TARGET_DEVICE=cpu uv pip install . --no-build-isolation

最后执行vllm -v 查看版本

0.21.0+cpu

docker知识点

1. docker build:

Docker镜像构建的核心指令，作用：读取Dockerfile脚本，按照脚本里的指令逐层执行，最终打包生成 Docker 镜像。

2. --target=base-common

指定多阶段构建的终止阶段名称

Dockerfile采用多阶段构建，开头通过FROM xxx AS base-common定义了阶段名base-common。

使用--target=base-common构建只会执行到 base-common 阶段就停止，不会执行后续 builder、runtime 的内容。

3. -t vllm-base-test

为构建完成的镜像设置名称与标签(tag)，是镜像的唯一标识。

简写-t，完整写法 --tag。

4. -f ./hella_vllm_0.21.0/Dockerfile

全称--file，手动指定 Dockerfile 脚本的文件路径。

默认规则：Docker 默认会在构建上下文根目录寻找名为 Dockerfile 的文件。

5. 末尾参数：.

docker build 必不可少的唯一位置参数，所有可选参数必须写在它前面。

Docker 会将该目录内的文件打包上传给后台构建引擎，Dockerfile 中的 COPY、ADD 指令，只能读取上下文目录内的文件。

6. WORKDIR

设置容器的全局工作目录。

后续所有 RUN / COPY / CMD / ENTRYPOINT 指令，默认都以 /workspace 为当前执行目录。

7. ARG

构建参数

仅在 docker build 镜像构建阶段生效，容器运行时彻底失效。

定义构建时的临时变量，用来外部传入配置、版本号、路径、开关，实现一套 Dockerfile 适配多种环境，不用反复修改文件。

8. ENV

用于定义容器运行时的环境变量，变量会永久写入镜像文件。

9. RUN

RUN 是 Dockerfile 核心执行指令，作用：在镜像构建阶段，运行 shell 命令，执行安装、编译、下载、配置等操作，命令执行后的文件变更，会生成一个独立的镜像分层，永久保存在镜像中。