第4章安装与 OpenAI 兼容服务 — vLLM 高性能推理实战

环境要求

组件	最低	推荐
Python	3.9	3.10 / 3.11
CUDA	11.8	12.1+
GPU	Compute Cap 7.0+(V100 起)	A100 / H100 / L40S
PyTorch	2.4+	2.5+
OS	Linux(glibc 2.31+)	Ubuntu 22.04

Mac 用户
vLLM 目前对 Apple Silicon(MPS)支持有限,CPU 后端 0.6+ 才实验性上线。本地开发建议用 Ollama,生产再上 Linux + GPU。

安装

# 方式一:uv(推荐,最快)
uv pip install vllm

# 方式二:pip
pip install vllm

# 方式三:源码编译(自定义 CUDA 架构)
git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -e .

装完验证:

python -c "import vllm; print(vllm.__version__)"
# 0.6.x

启动 OpenAI 兼容服务

最小命令:

vllm serve meta-llama/Llama-3-8B-Instruct

默认监听 0.0.0.0:8000,模型从 HuggingFace Hub 下载(私有模型记得先 huggingface-cli login)。

完整常用参数:

vllm serve meta-llama/Llama-3-8B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --served-model-name llama3-8b \                    # API 里用的名字
  --dtype bfloat16 \                                 # A100 / H100 默认
  --max-model-len 8192 \                            # 按业务裁
  --gpu-memory-utilization 0.9 \                    # 吃 90% 显存
  --tensor-parallel-size 1 \                        # 多卡改这里
  --enable-chunked-prefill \
  --enable-prefix-caching \                          # 共享 system prompt
  --api-key "sk-your-secret"                       # 加简单鉴权

启动参数详解

--model (位置参数)

HuggingFace 路径、本地目录、或 ModelScope 路径。例:/data/models/Qwen2-7B。

--served-model-name

API 里模型的标识名。默认用 --model 的路径,太长时改短。多个 --served-model-name 可以一条命令注册多个别名。

--dtype

auto(推荐)/bfloat16/float16/float32。A100+ 选 bf16 稳,V100 只能 fp16。

--max-model-len

支持的最大上下文长度。越大 KV 池吃越多,按业务最长 prompt 定。Llama-3 默认 8k,Qwen2-128k 就要看显存够不够。

--gpu-memory-utilization

默认 0.9,即吃 90% 显存给模型 + KV。和其他进程共享卡时调低(0.75)免得挤爆。

--max-num-seqs

并发序列上限,默认 256。聊天场景够用,批量压测可以调高到 1024。

--quantization

加载量化版模型时填 awq / gptq / fp8 / bitsandbytes。详见第 5 章。

--enable-prefix-caching

开启前缀缓存,多请求共享同 prompt 时 KV 可复用,prefill 变快。多轮对话必开。

OpenAI SDK 直接调用

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="sk-your-secret",
)

# chat completion
resp = client.chat.completions.create(
    model="llama3-8b",
    messages=[
        {"role": "system", "content": "你是一个简洁的助手"},
        {"role": "user", "content": "一句话解释 PagedAttention"},
    ],
    temperature=0.7,
    max_tokens=256,
)
print(resp.choices[0].message.content)

# 流式
stream = client.chat.completions.create(
    model="llama3-8b",
    messages=[{"role": "user", "content": "写首诗"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

curl 直接测

curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer sk-your-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3-8b",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

多模型一次性启动

同一 vLLM 服务默认只跑一个 model_path,但可以挂多个 alias:

vllm serve Qwen/Qwen2-7B-Instruct \
  --served-model-name qwen2 qwen2-7b backup-model

三个名字指向同一模型,方便前端按不同别名做路由(比如把旧系统的 "gpt-3.5" 直接映射过来)。

想真正同时跑多个不同模型,需要起多个进程或用 docker-compose 分端口。

Docker 部署

docker run --runtime nvidia --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:v0.6.3 \
  --model meta-llama/Llama-3-8B-Instruct \
  --dtype bfloat16

为什么要 --ipc=host
PyTorch dataloader 和 NCCL 都用 shared memory 通信。默认 Docker 给 /dev/shm 只有 64MB,很容易炸。--ipc=host 或 --shm-size 32g 都行,多卡张量并行尤其必开。

离线批量推理(不用 HTTP)

如果场景是"处理 10 万条问题一次性给结果",起 HTTP 服务是绕路。直接用 LLM 类:

from vllm import LLM, SamplingParams

llm = LLM(
    model="meta-llama/Llama-3-8B-Instruct",
    dtype="bfloat16",
    gpu_memory_utilization=0.9,
    max_model_len=4096,
)

prompts = [
    "将 'Hello World' 翻译成中文:",
    "写一个冒泡排序:",
    "东京在哪个国家?",
] * 3000   # 9000 条

params = SamplingParams(temperature=0.7, max_tokens=256)

outputs = llm.generate(prompts, params)
for out in outputs[:3]:
    print(out.prompt[:50], "→", out.outputs[0].text[:80])

vLLM 内部照样用连续批处理,吞吐和 HTTP 模式一样。单机 9000 条 token<200 的 prompt,A100 上大概 40 秒跑完。

HuggingFace 镜像加速

国内下模型慢,换 HF 镜像:

export HF_ENDPOINT=https://hf-mirror.com
export HF_HOME=/mnt/data/hf-cache       # 大盘装模型
vllm serve Qwen/Qwen2-7B-Instruct

或直接用魔搭社区模型:

export VLLM_USE_MODELSCOPE=True
vllm serve qwen/Qwen2-7B-Instruct

内置 endpoint 一览

路径	作用
`/v1/chat/completions`	OpenAI chat API 兼容
`/v1/completions`	OpenAI completion API 兼容
`/v1/embeddings`	需要 embedding 模型(BGE 等)
`/v1/models`	列出注册的 model 名
`/health`	k8s liveness 探针
`/metrics`	Prometheus 指标
`/tokenize` / `/detokenize`	工具接口,算 token 数很方便

常见启动报错

报错	原因	修复
CUDA OOM	--gpu-memory-utilization 太高或 --max-model-len 太大	降到 0.85 / 裁短 max-model-len
Cannot find attribute	模型 config 不识别	升级 vLLM 或装 transformers main 分支
Model architecture not supported	模型太新	查支持列表,必要时用 HF auto_map
NCCL error on multi-GPU	--ipc=host 没加	Docker 加上,或 --shm-size 32g
HF 403 / timeout	没登录或墙	huggingface-cli login / 换镜像

本章小结

    Linux + CUDA 12 + PyTorch 2.5 是甜点环境,pip install vllm 一行搞定
vllm serve 起 OpenAI 兼容服务,业务代码零改动切 openai SDK
关键参数:model / served-model-name / max-model-len / gpu-memory-utilization / tensor-parallel-size / enable-prefix-caching
离线批量用 LLM 类直接跑,比起 HTTP 省去网络开销
多卡要加 --ipc=host,中国区用 HF 镜像或 MODELSCOPE

  