VLLM源码安装运行示例

vLLM 是一个高性能的大语言模型推理和服务库，专注于提供快速、易用、低成本的LLM服务。它采用PagedAttention 技术高效管理注意力的键值内存，支持连续批处理，并提供了多种优化手段。

使用vLLM 可以通过快速安装可运行版本，也可以使用源码开发模式。本文记录了从源码安装运行 vLLM 的示例，以及一些踩坑教程。

1 环境配置

可以成功安装运行的搭配：

环境	版本	备注
CUDA	11.8	vllm官方要求CUDA=12.4或者CUDA=11.8
Python	3.10.8
vLLM	0.6.4.post1	也可以用其他稳定版本
PyTorch	2.5.1+cu124

如果CUDA版本不匹配，可以通过以下方式卸载重装：

# 查看当前CUDA版本
nvcc --version

# 卸载旧版本 CUDA（可选但推荐）
sudo apt-get --purge remove "*cublas*" "cuda*" "nsight*" 
sudo apt-get autoremove

# 安装新版本 CUDA（Ubuntu 22.04， CUDA 11.8）
wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda-repo-ubuntu2204-11-8-local_11.8.0-520.61.05-1_amd64.deb
sudo dpkg -i cuda-repo-ubuntu2204-11-8-local_11.8.0-520.61.05-1_amd64.deb
sudo cp /var/cuda-repo-ubuntu2204-11-8-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get install -y cuda

# 设置环境变量
echo 'export PATH=/usr/local/cuda-11.8/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

2 安装

# 1. 克隆所需版本仓库
git clone --branch v0.6.4.post1 https://github.com/vllm-project/vllm.git
cd vllm

# 1. 创建并激活虚拟环境（可选）
python3 -m venv vllmenv
source vllmenv/bin/activate

# 3. 安装依赖（不确定是否必需）
sudo apt update
sudo apt install -y ninja-build cmake git g++ python3-dev
pip install numpy wheel setuptools

# 4. 编译
export VLLM_USE_PRECOMPILED=1
pip install -e .

3 运行

可以用一个最小模型（如 facebook/opt-125m）测试：

python3 -m vllm.entrypoints.openai.api_server --model facebook/opt-125m

运行成功后会启动一个本地 HTTP 接口，默认监听 http://localhost:8000/v1/chat/completions。可以测试一下：

curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
        "model": "facebook/opt-125m",
        "prompt": "Hello, my name is",
        "max_tokens": 20
      }'

在 /examples 中也有很多示例，可以直接运行最简单的 offline_inference.py 测试：

from vllm import LLM, SamplingParams

# Sample prompts.
prompts = [
    "Hello, my name is",
    "The president of the United States is",
    "The capital of France is",
    "The future of AI is",
]
# Create a sampling params object.
sampling_params = SamplingParams(temperature=0.8, top_p=0.95)

# Create an LLM.
llm = LLM(model="facebook/opt-125m")
# Generate texts from the prompts. The output is a list of RequestOutput objects
# that contain the prompt, generated text, and other information.
outputs = llm.generate(prompts, sampling_params)
# Print the outputs.
for output in outputs:
    prompt = output.prompt
    generated_text = output.outputs[0].text
    print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")

4 踩坑记录

1. build wheels 失败

直接从github clone 了最新的仓库，执行 pip install -e . 安装依赖时报错记录如下：

note: This error originates from a subprocess, and is likely not a problem with pip.
ERROR: Failed building editable for vllm
Failed to build vllm
ERROR: Could not build wheels for vllm, which is required to install pyproject.toml-based projects

尝试的方法有：

• 为系统安装编译依赖： sudo apt install -y ninja-build cmake git g++ python3-dev
• 直接使用正常编译方式： pip install .
• 添加 CUDA 等的环境变量

在网上找了一些方法都没有用，遂放弃，使用了 0.6.4.post1 版本的vLLM。

2. Hugging Face 下载超时

在运行的时候出现以下报错，由于服务器连接不上 https://huggingface.co。

requests.exceptions.ConnectTimeout: (MaxRetryError("HTTPSConnectionPool(host='huggingface.co', port=443): Max retries exceeded with url: /facebook/opt-125m/resolve/main/config.json (Caused by ConnectTimeoutError(<urllib3.connection.HTTPSConnection object at 0x7f02bb397910>, 'Connection to huggingface.co timed out. (connect timeout=10)'))"), '(Request ID: 6f4012b5-b44e-4189-8ccf-76fee1848336)')

可以在本地下载好模型，传到服务器上：

from transformers import AutoTokenizer, AutoModelForCausalLM

AutoTokenizer.from_pretrained("facebook/opt-125m", cache_dir="./opt-125m")
AutoModelForCausalLM.from_pretrained("facebook/opt-125m", cache_dir="./opt-125m")

注意这种方式用 huggingface_hub 下载了 snapshot 格式模型，并没有自动 unpack 到真正可以用的格式。真正的模型文件一般在该目录下：opt-125m/models--facebook--opt-125m/snapshots/<commit-id>/。里面有 config.json 、tokenizer.json 等文件。