模型部署推理框架[2]:总体架构和Docker部署实战

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 bench CLI 的实现
  • config/------VllmConfig 全家桶

4. 两个容易误解的架构点

  1. "HTTP 服务"与"推理"不是同一线程/进程 :uvicorn 的事件循环只做协议与流转发;调度与 forward 全在 EngineCore 进程。因此客户端网络慢、detokenize 慢都不会拖住引擎,排队与调度只在引擎侧发生。
  2. 调度是"批中心 + 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 把模型名直接当参数:

    bash 复制代码
    docker 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 模型权重与放置

  1. 本地软链接(本项目默认做法,免下载) :
    • 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)。
  2. 自动下载 :VLLM_MODEL 写 HF 名(如 Qwen/Qwen3-8B),启动时经 HF_ENDPOINT=https://hf-mirror.com 下载,缓存在 hf-cache 卷。
  3. gated 模型 (Llama 系列):compose 里加 - HF_TOKEN=hf_xxx 环境变量。
  4. 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                       
相关推荐
爱笑的k117 天前
nano-vllm 源码剖析:千行 Python 手写离线推理引擎的调度、显存与并行时序
开发语言·python·vllm
code2cat11 天前
【随笔】推理准入控制:请求进来之前,先给KV缓存留出位置
缓存·大语言模型·vllm
code2cat16 天前
【随笔】连续批处理:长短请求怎样在迭代之间补位
java·人工智能·后端·大语言模型·vllm
一枕槐安48716 天前
Qwen 通义千问本地部署与推理服务封装
fastapi·qwen·vllm·流式推理·openai兼容api·awq量化
mumu15717 天前
快速上手大模型推理vllm
人工智能·python·大语言模型·agent·vllm
code2cat18 天前
【随笔】vLLM前缀缓存:相同的开头怎样少算一次
人工智能·python·缓存·vllm
JAI科研22 天前
把一个 Qwen3.8的聊天模型改造成 JEV 决策模型
人工智能·语言模型·自然语言处理·chatgpt·transformer·vllm·sglang
谢白羽23 天前
从传统运维到 AI Infra: K8s 上调度 100 张 GPU踩坑笔记
运维·人工智能·缓存·kubernetes·vllm·sglang·vllm-omni
Hrain-AI24 天前
企业本地推理引擎选型实战:Ollama、vLLM 与 MLX 怎么挑
vllm