02 · 总体架构:从 HTTP 到 Token
- 本章拆解 vLLM V1 引擎的进程模型与数据通路。源码路径以 v0.34.0 为准(
/usr/local/lib/python3.12/dist-packages/vllm)。- 入口层结构 (引擎核心在
v1/*):entrypoints/按命令族组织------serve/(应用生命周期:FastAPI app、instrumentator、fault_tolerance)、openai/(OpenAI 协议层,内部再分chat_completion/、completion/、responses/、models/、parser/)、pooling/(嵌入/重排:embed/、scoring/)、generate/structured_decisions/(/v1/systemone)、launchers/(run-batch等)、speech_to_text/、anthropic/、cohere/、mcp/、rl/。
文章目录
-
[02 · 总体架构:从 HTTP 到 Token](#02 · 总体架构:从 HTTP 到 Token)
-
- [1. 顶层视图:API 服务与引擎核心解耦](#1. 顶层视图:API 服务与引擎核心解耦)
- [2. 一次 `/v1/chat/completions` 请求的消息流(鸟瞰)](#2. 一次
/v1/chat/completions请求的消息流(鸟瞰)) - [3. 目录地图](#3. 目录地图)
- [4. 两个容易误解的架构点](#4. 两个容易误解的架构点)
- [5. 状态观测入口(先混个脸熟)](#5. 状态观测入口(先混个脸熟))
- [6. Docker 部署实战](#6. Docker 部署实战)
-
- [6.1 nvidia-container-toolkit](#6.1 nvidia-container-toolkit)
- [6.2 官方镜像解剖(v0.34.0)](#6.2 官方镜像解剖(v0.34.0))
- [6.3 本项目 compose 逐行解读(docker/docker-compose.yml)](#6.3 本项目 compose 逐行解读(docker/docker-compose.yml))
- [6.4 模型权重与放置](#6.4 模型权重与放置)
- [6.5 双 3090 实战配置](#6.5 双 3090 实战配置)
- [6.6 验证清单](#6.6 验证清单)
-
学习仓库:kill-life/vllm-learn
1. 顶层视图:API 服务与引擎核心解耦

V1 架构的核心思想是进程解耦:HTTP 服务(快、不能被卡)与引擎核心(重、批量执行)分开,中间用 ZMQ 消息队列连接:
bash
┌─────────────────────────── API 进程 ────────────────────────────┐
│ FastAPI/uvicorn (entrypoints/openai/api_server.py) │
│ └── OpenAIServingChat / ...(协议层:校验、模板、工具解析) │
│ └── RequestProcessor → AsyncLLM (v1/engine/async_llm.py) │
│ · add_request():把请求转成 EngineCoreRequest │
│ · OutputProcessor:把引擎输出流整理成逐请求生成器 │
└───────────────┬──────────────────────────────────────────────────┘
│ ZMQ ipc socket(v1/engine/__init__.py 定义消息)
┌───────────────▼───────────────────────────┐
│ EngineCore 进程(v1/engine/core.py) │
│ · 请求队列 / 调度主循环 │
│ · Scheduler (v1/core/sched/scheduler.py)│
│ - vLLM 内部按 token 预算准入 │
│ - running 队列连续批处理 + preemption │
│ · KVCacheManager (v1/core/kv_cache_manager.py)│
│ - 块分配/前缀缓存命中/驱逐 │
└───────────────┬───────────────────────────┘
│ MultiprocExecutor / RayExecutor(每 TP rank 一 worker)
┌───────────────▼───────────────────────────┐
│ GPUWorker(v1/worker/gpu_worker.py) │
│ v1/worker/gpu_model_runner.py │
│ · 权重加载 / forward / 采样 │
│ · attention backend / CUDA Graph 回放 │
└────────────────────────────────────────────┘
要点:
- 进程边界 = 故障边界 :EngineCore 崩溃不影响 API 进程(可自动重启恢复);detokenize 在 API 进程侧的
OutputProcessor/Detokenizer完成,不占用引擎时间。 - 消息格式 :
v1/engine/__init__.py里的 msgspec 结构(EngineCoreRequest、EngineCoreOutputs),经 ZMQ IPC 传输;TP worker 间广播用 NCCL。 - AsyncLLM vs LLM :
vllm serve走AsyncLLM(asyncio);离线LLM类走同步封装的同一 EngineCore,两条入口,一个引擎。 - DP 场景 :
data_parallel_external_lb时由前置负载均衡分发;内置 DP 由dp_supervisor.py协调多组 EngineCore。
2. 一次 /v1/chat/completions 请求的消息流(鸟瞰)
bash
HTTP POST /v1/chat/completions
→ 协议层:apply chat template → 校验 sampling/tool 参数
→ AsyncLLM.add_request()
→ RequestProcessor 构造 EngineCoreRequest(token ids + 采样参数 + request_id)
→ zmq send → EngineCore
→ Scheduler.schedule()
· waiting 队列按 token 预算准入(prefill)
· 或 running 队列继续 decode(预算不足时 preemption)
· KVCacheManager:前缀缓存匹配 → 分配新块
→ GPUWorker forward → 采样 → 新 token
→ zmq send: EngineCoreOutputs
→ OutputProcessor:增量 detokenize → 按 request_id 找回生成器
→ HTTP SSE/JSON 返回
3. 目录地图
vllm/v1/(V1 引擎核心):
| 目录/文件 | 职责 |
|---|---|
engine/async_llm.py |
异步引擎入口(vllm serve 的心脏) |
engine/core.py |
EngineCore:调度循环 + 与 API 进程的桥 |
engine/output_processor.py / detokenizer.py |
输出整理与增量反解 |
core/sched/scheduler.py |
调度核心(准入/批处理/抢占) |
core/kv_cache_manager.py / block_pool.py |
KV 块管理、前缀缓存、驱逐 |
core/kv_cache_utils.py |
块哈希、KVCacheSpec(KV 布局描述) |
worker/gpu_model_runner.py |
权重加载、forward、CUDA Graph、采样 |
executor/multiproc_executor.py |
多进程执行器(TP 的默认后端) |
attention/ |
FlashAttention/FlashInfer/Triton 等后端注册 |
structured_output/ |
grammar 后端与 bitmask(教程 08) |
spec_decode/ |
ngram/EAGLE 推测解码 |
kv_offload/ / simple_kv_offload/ |
KV 卸载(CPU/远端) |
metrics/loggers.py |
Prometheus 指标定义 |
其他顶层:
engine/llm_engine.py与entrypoints/llm.py------离线LLM类entrypoints/openai/------OpenAI/Anthropic/Responses 协议层benchmarks/serve.py等------vllm benchCLI 的实现config/------VllmConfig 全家桶
4. 两个容易误解的架构点
- "HTTP 服务"与"推理"不是同一线程/进程 :uvicorn 的事件循环只做协议与流转发;调度与 forward 全在 EngineCore 进程。因此客户端网络慢、detokenize 慢都不会拖住引擎,排队与调度只在引擎侧发生。
- 调度是"批中心 + token 预算" :Scheduler 每步生成"下一个要执行的 batch"(prefill 或 decode),预算由
max_num_batched_tokens(每步 token 总预算)与max_num_seqs(批内序列数上限)共同约束。理解了Scheduler.schedule()这个函数,vLLM 的调度就懂了一大半。
5. 状态观测入口(先混个脸熟)
| 入口 | 用途 |
|---|---|
/server_info |
全部实际配置(vllm_config 各子配置的 dump) |
/metrics |
Prometheus 指标:vllm:kv_cache_usage_perc、TTFT/ITL 直方图、preemption 计数... |
/health / /readyz / /ping |
探活 |
日志 Engine 000: Avg prompt throughput: ... |
最直观的运行态窗口(每 10s 一条) |
docker compose logs -f |
chunked prefill / 抢占事件的观察位 |
6. Docker 部署实战
6.1 nvidia-container-toolkit
- 容器内没有 NVIDIA 驱动。
nvidia-container-runtime在容器启动时把宿主机的驱动用户态库 (libcuda.so、libnvidia-ml.so 等)注入容器,并挂载/dev/nvidia*设备文件。因此:- 容器内 CUDA 版本(运行时)≠ 宿主机驱动支持的 CUDA 版本,前者 ≤ 后者才可运行;
nvidia-smi在容器内可用(读的是宿主机驱动);- 驱动升级无需换镜像,换镜像无需升驱动(保持大版本兼容即可)。
自检命令:docker run --rm --gpus all --entrypoint nvidia-smi vllm/vllm-openai:v0.34.0(镜像默认入口是 vllm serve,必须用 --entrypoint 覆盖)。
6.2 官方镜像解剖(v0.34.0)
| 层 | 内容 |
|---|---|
| 基础层 | NVIDIA CUDA 镜像(CUDA 13.0.2 运行时/工具链) |
| Python 层 | Python 3.12.3 (PATH 里只有 python3,没有 python)、torch 2.14.0+cu130、triton 3.8 |
| 内核层 | FlashAttention / FlashInfer 等 attention 后端(按硬件自动选择);vllm download-kernels 可预装 FlashInfer 预编译内核,免启动时下载/编译 |
| 框架层 | vllm 0.34.0(pip 安装到 /usr/local/lib/python3.12/dist-packages/vllm)、transformers ≥5.16 等 |
| 工作区 | /vllm-workspace(默认 WORKDIR) |
要点:
-
默认入口 就是启动服务:
ENTRYPOINT ["vllm", "serve"],所以官方 README 的docker run把模型名直接当参数:bashdocker run --gpus all --shm-size 16g -p 8000:8000 \ -v ~/.cache/huggingface:/root/.cache/huggingface \ vllm/vllm-openai:v0.34.0 \ Qwen/Qwen3-8B --tensor-parallel-size 2 -
源码在 site-packages (
/usr/local/lib/python3.12/dist-packages/vllm),不在/vllm-workspace。 -
vLLM 的编译产物缓存(torch.compile / CUDA Graph 依赖)在
VLLM_CACHE_ROOT(默认~/.cache/vllm)。把它做成卷 ,否则每次重启容器重编译(本项目 compose 已配vllm-cache卷)。 -
CLI 布局 :
vllm顶层是命令组(serve/chat/bench/collect-env/download-kernels/preload/run-batch/snapshot/launch...),vllm serve --help=<Group>可按配置组分段查参数。
6.3 本项目 compose 逐行解读(docker/docker-compose.yml)
yaml
image: ${VLLM_IMAGE:-vllm/vllm-openai:v0.34.0} # .env 控制镜像,默认官方 CUDA 13 原镜像
entrypoint: ["bash", "/opt/vllm-explorer/entrypoint.sh"] # 覆盖默认入口:先拉起 explorer 再跑服务
command: >-
vllm serve ${VLLM_MODEL:-Qwen/Qwen3-1.7B}
--host 0.0.0.0 --port 8000
${VLLM_EXTRA_ARGS:-}
关键配置及理由:
| 配置 | 原因 |
|---|---|
gpus: all |
两张 3090 都给容器 |
ipc: host |
多卡 NCCL 需要大共享内存(等价 --shm-size),TP 的官方推荐 |
卷 ../workspace:/vllm-workspace/learn |
实验代码宿主机编辑、容器内立即可见 |
卷 ../docs:/vllm-workspace/learn-docs:ro |
explorer「教程阅读」的数据源 |
卷 hf-cache / vllm-cache |
权重与编译缓存持久化,重启免下载/免编译 |
端口 18082→8080 |
explorer;默认监听 0.0.0.0 ,局域网访问 http://<本机IP>:18082。 |
端口 8000 |
vLLM 的约定俗成端口;默认同样对局域网开放 |
healthcheck /health |
docker compose ps 能直接看到 healthy/unhealthy |
restart: unless-stopped |
意外退出自动拉起 |
.env 可调项见 .env.example 注释:VLLM_MODEL、VLLM_EXTRA_ARGS(默认已含 --served-model-name、工具调用开关 --enable-auto-tool-choice --tool-call-parser qwen3_xml、MTP 推测解码 --speculative-config '{"method":"mtp","num_speculative_tokens":2}',双卡再加 --tensor-parallel-size 2)、HF_ENDPOINT(默认 hf-mirror.com 加速)。
局域网访问与安全 :默认端口监听
0.0.0.0,局域网其他机器可直接调用http://<本机IP>:8000。此时注意两点:① explorer 能浏览容器文件且默认无鉴权,建议在
.env设EXPLORER_TOKEN(浏览器首访http://<本机IP>:18082/?token=密钥即可记住令牌);② vLLM API 默认无 api-key,需要鉴权就把
--api-key <密钥>追加到VLLM_EXTRA_ARGS。若只想本机访问,把 compose 端口映射改回127.0.0.1:8000:8000/127.0.0.1:18082:8080。
6.4 模型权重与放置
- 本地软链接(本项目默认做法,免下载) :
workspace/models/qwen3.5-4B -> $HOST_MODELS_DIR/qwen3.5-4B(真实权重 ~8.8GB);- workspace 整体挂载进容器后,软链接的目标目录必须以相同绝对路径只读挂进容器 (compose 已配
- ${HOST_MODELS_DIR}:${HOST_MODELS_DIR}:ro),否则容器内链接悬空; .env里设置HOST_MODELS_DIR为宿主机权重目录(未设置时挂载空目录/opt/vllm-models),VLLM_MODEL写容器内路径:/vllm-workspace/learn/models/qwen3.5-4B;- 新模型接入:
bash scripts/link-model.sh qwen3.5-9B /path/to/models/qwen3.5-9B。 - 模型对外名字 :vLLM 默认拿权重路径当 model id,不设别名时客户端必须传完整路径。
.env.example已用--served-model-name qwen3.5-4B起短名;客户端一律以GET /v1/models返回的id为准,擅自简写会 404(The model ... does not exist)。
- 自动下载 :
VLLM_MODEL写 HF 名(如Qwen/Qwen3-8B),启动时经HF_ENDPOINT=https://hf-mirror.com下载,缓存在hf-cache卷。 - gated 模型 (Llama 系列):compose 里加
- HF_TOKEN=hf_xxx环境变量。 - GGUF :
--load-format gguf(或模型路径直接指向 .gguf)。
6.5 双 3090 实战配置
硬件形态映射 :单卡机器不加
--tensor-parallel-size(默认即单卡形态);本机双卡 ≥8B 加 TP=2。离线实验脚本默认单卡,双卡跑离线实验:VLLM_TP=2 python 01_hello_vllm.py。
| 场景 | VLLM_MODEL |
VLLM_EXTRA_ARGS |
说明 |
|---|---|---|---|
| 冒烟(默认) | /vllm-workspace/learn/models/qwen3.5-4B(本地软链接) |
--gpu-memory-utilization 0.85 --max-model-len 32768 --enable-prefix-caching |
~8.8GB 权重单卡 |
| 单卡 8B | Qwen/Qwen3-8B |
--max-model-len 8192 --gpu-memory-utilization 0.92 |
权重 ~16GB,24GB 卡勉强 |
| 双卡 8B | Qwen/Qwen3-8B |
--tensor-parallel-size 2 --gpu-memory-utilization 0.88 --max-model-len 32768 |
每卡 ~8GB 权重 + KV |
| 双卡 7B 推理模型 | deepseek-ai/DeepSeek-R1-Distill-Qwen-7B |
--tensor-parallel-size 2 |
思考链模型 |
| 4bit 量化 14B | Qwen/Qwen3-14B-GPTQ-Int4 |
--tensor-parallel-size 2 |
量化详见教程 |
| MoE 小钢炮 | Qwen/Qwen3-30B-A3B-Instruct-2507(FP8/AWQ 版) |
--tensor-parallel-size 2 --enable-expert-parallel |
显存粗估:权重/卡 = 参数量 × 每参数字节数 ÷ TP (BF16≈2B/参数;GPTQ/AWQ INT4≈0.5B/参数),KV 池 = (总显存 × gpu-memory-utilization) − 权重 − 激活/编译预留。
6.6 验证清单
bash
docker compose ps # STATUS 应为 Up (healthy)
curl -s http://127.0.0.1:8000/health && echo OK
bash scripts/smoke-test.sh # 7 项端到端验证(含工具调用与 MTP)
docker compose exec vllm bash # 进入容器做底层验证(见下)
容器内的底层验证:
bash
python3 -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.device_count())"
# 预期: 2.14.0 13.0 2
python3 -c "import vllm; print(vllm.__version__, vllm.__file__)"
# 预期: 0.34.0 /usr/local/lib/python3.12/dist-packages/vllm/__init__.py
nvidia-smi
pip list | grep -Ei "vllm|torch|transformers|triton|xgrammar" # 核心栈版本
vllm --help