【vllm】（总体）vLLM v0.20.0 超深度系统级架构分析

张忠琳

1174人浏览 · 2026-04-19 14:05:59

张忠琳 · 2026-04-19 14:05:59 发布

vLLM 系统级架构分析

项目: vLLM — High-throughput and memory-efficient inference engine for LLMs
代码规模: 1935 Python文件(~687K行) + 233 C++/CUDA文件(~87K行) ≈ 77万行
代码目录: github.com/vllm
分析日期: 2026-05-17

一、项目整体架构

1.1 整体设计思路

vLLM 的核心设计目标是高吞吐、低延迟、显存高效的大语言模型推理服务引擎。其整体架构围绕三大核心技术挑战展开：

KV Cache 显存管理：PagedAttention（分页注意力）将 KV Cache 按块（block）管理，block_size默认16个token，解决传统连续分配导致的显存碎片化问题。支持前缀缓存(prefix caching)，相同前缀的请求可复用已有KV blocks。
请求调度优化：Continuous Batching（连续批处理）在迭代级别动态调度请求，取代静态批处理。Scheduler不再区分prefill/decode阶段，而是统一在token级别调度——每个迭代中既有新请求的prefill token，也有正在运行的decode token。
分布式推理：原生支持5维并行布局(ExternalDP×DP×PP×PCP×TP)、专家并行负载均衡(EPLB)、弹性专家并行(Elastic EP)及分离式推理(Disaggregated Serving via KV Transfer)。

核心架构模式：分层管道架构（Layered Pipeline Architecture）+ 插件式注册机制（Plugin Registry Pattern）

1.2 整体架构6层模型

┌─────────────────────────────────────────────────────────┐
│  第1层：用户/客户端层                                      │
│  HTTP/OpenAI API / CLI / Python SDK / gRPC / WebSocket   │
└──────────────────────┬──────────────────────────────────┘
                       │ HTTP请求 / API调用
┌──────────────────────▼──────────────────────────────────┐
│  第2层：服务入口层 (Entrypoints)                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │ InputProcessor(分词+多模态) → Detokenizer → OutputProcessor │
│  │ ToolParserManager(工具调用) / ReasoningParser(CoT)│   │
│  └──────────────────────────────────────────────────┘   │
└──────────────────────┬──────────────────────────────────┘
                       │ EngineCoreRequest (msgspec序列化)
┌──────────────────────▼──────────────────────────────────┐
│  第3层：V1引擎层 (Engine)                                │
│  ┌──────────────────────────────────────────────────┐   │
│  │ Frontend进程:  AsyncLLM → EngineCoreClient(IPC)  │   │
│  │ Core子进程:    EngineCore → Scheduler → Executor │   │
│  │                KVCacheManager → BlockPool         │   │
│  └──────────────────────────────────────────────────┘   │
└──────────────────────┬──────────────────────────────────┘
                       │ SchedulerOutput (调度决策)
┌──────────────────────▼──────────────────────────────────┐
│  第4层：执行器+Worker层                                  │
│  ┌──────────────────────────────────────────────────┐   │
│  │ Executor(UniProc/Multiproc/Ray/ExternalLauncher) │   │
│  │ Worker(GPU/CPU/XPU) → ModelRunner(GPU/CPU)       │   │
│  │ GPUModelRunner._prepare_inputs() → forward()     │   │
│  └──────────────────────────────────────────────────┘   │
└──────────────────────┬──────────────────────────────────┘
                       │ model.forward()
┌──────────────────────▼──────────────────────────────────┐
│  第5层：模型执行层 (Model Executor)                       │
│  ┌──────────────────────────────────────────────────┐   │
│  │ Models: 296种(LLaMA/Mixtral/DeepSeek/Qwen/...)   │   │
│  │ Layers: Attention/FusedMoE/Quantization/RoPE/Lin │   │
│  │ Weight Loader: AutoWeightsLoader/WeightsMapper   │   │
│  └──────────────────────────────────────────────────┘   │
└──────────────────────┬──────────────────────────────────┘
                       │ CUDA ops / torch.ops.vllm.*
┌──────────────────────▼──────────────────────────────────┐
│  第6层：内核+分布式层                                     │
│  ┌──────────────────┐  ┌───────────────────────────┐   │
│  │ C++/CUDA Kernels │  │ Distributed               │   │
│  │ PagedAttention   │  │ parallel_state(5维并行)    │   │
│  │ QuantKernels     │  │ kv_transfer(11种Connector)│   │
│  │ MoE/Sampler/...  │  │ device_communicators(NCCL)│   │
│  └──────────────────┘  └───────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

         ←──── 横切关注点 ────→
┌─────────────────────────────────────────────────────────┐
│  VllmConfig(22子配置) | Platforms(6平台) | Compilation   │
│  Tokenizers | ToolParsers(40种) | LoRA | MultiModal     │
│  IR(ir.ops注册) | Tracing | Profiler | Plugins          │
└─────────────────────────────────────────────────────────┘

1.3 架构模式详解

模式	应用位置	说明
分层管道架构	全局6层（入口→引擎→执行器→模型→内核→分布式）	请求自顶向下流经各层，每层有明确职责边界和数据格式
插件式注册	Models(296种)/Quantization(25+)/Attention Backend(8+)/KV Connector(11种)	通过Registry/工厂函数动态注册，运行时按配置选择实现
进程分离架构	EngineCore(子进程) ↔ Frontend(主进程)	调度核心与API服务进程隔离，通过ZMQ+共享内存IPC通信
策略模式	Scheduler(FCFS/Priority)/Executor(UniProc/Ray/MP)/Attention Backend	接口统一，多种实现可替换
观察者模式	KV Events(ZeroMQ PUB/SUB)/Engine Events	发布-订阅解耦模块间通知
模板方法	Model.forward()/Worker生命周期/ModelRunner._prepare_inputs()	基类定义骨架，子类覆写关键步骤
工厂模式	ModelRegistry/QuantizationConfig/KVConnectorFactory	统一创建接口，隐藏实现细节
代理模式	EngineCoreClient(代理EngineCore)	本地接口，远程执行

1.4 整体运行流程（端到端序列图）

二、子模块/功能模块划分

2.1 模块全景图

2.2 模块1：V1引擎层 (vllm/v1)

核心作用：vLLM的推理引擎核心，管理从请求接收到输出生成的完整生命周期。采用Frontend-Core进程分离架构：Frontend进程运行API服务和detokenizer，Core子进程运行Scheduler和模型执行循环，通过ZMQ+共享内存IPC通信。

架构模式：进程分离 + 调度-执行解耦

关键类/方法清单：

类	文件	核心方法	作用
`AsyncLLM`	v1/engine/async_llm.py	`generate()`	异步推理入口，返回`AsyncGenerator[RequestOutput]`
		`abort()`	中止请求
		`sleep()/wake_up()`	引擎睡眠/唤醒（节省显存）
`EngineCore`	v1/engine/core.py	`step()`	核心循环：schedule→execute→update
		`run()`	子进程主循环入口
`EngineCoreClient`	v1/engine/core_client.py	`send_request()`	发送请求到Core
		`get_output()`	获取推理输出
`Scheduler`	v1/core/sched/scheduler.py	`schedule()`	统一token级调度（无prefill/decode区分）
		`update_from_output()`	根据模型输出更新请求状态
		`_preempt_request()`	抢占低优先级请求释放KV blocks
		`_select_waiting_queue_for_scheduling()`	选择下一个调度队列
`KVCacheManager`	v1/core/kv_cache_manager.py	`get_computed_blocks()`	前缀缓存匹配
		`allocate_slots()`	为请求分配KV blocks
		`free()`	释放请求的KV blocks
		`evict_blocks()`	驱逐blocks（LRU策略）
`BlockPool`	v1/core/block_pool.py	`get_block_ids()`	物理块分配/回收
`Worker`	v1/worker/gpu_worker.py	`init_device()`	GPU初始化+分布式环境设置
		`execute_model()`	执行模型推理
		`load_model()`	加载模型权重
`GPUModelRunner`	v1/worker/gpu_model_runner.py	`_prepare_inputs()`	构建推理输入(input_ids/positions/block_tables)
		`forward()`	模型前向传播
		`_build_attention_metadata()`	构建注意力元数据

调度策略详解：

数据流入：EngineCoreRequest(token_ids, sampling_params, lora_request, multi_modal_data, arrival_time)
数据流出：EngineCoreOutput(request_id, sampled_token_ids, finish_reason, logprobs, kv_connector_output)

2.3 模块2：模型执行层-模型注册 (vllm/model_executor/models)

核心作用：承载296+种大语言模型的推理实现，提供统一的模型注册/加载/执行框架。将HuggingFace的架构名映射到vLLM的优化实现。

架构模式：注册表模式 + 工厂模式 + 适配器模式

关键类/方法：

类	作用
`ModelRegistry`	架构名→(module, class)映射，支持延迟导入(lazy import)避免启动时加载全部模型
`LlamaForCausalLM`	LLaMA系列实现，forward()含Embedding→N×DecoderLayer→Logits
`MixtralForCausalLM`	MoE模型，MLP替换为Router+Experts
`DeepSeekV3ForCausalLM`	MLA注意力+细粒度MoE+共享专家
`_ModelInfo`	模型元信息，含arch/支持特性(LoRA/PP/Eagle/MM)
`AutoWeightsLoader`	自动权重加载，处理HF→vLLM权重名映射
`WeightsMapper`	权重重命名/拆分/合并的声明式映射

模型分类：

Dense模型：LLaMA, Qwen2, GPT-2, Gemma, Phi, Mistral…
MoE模型：Mixtral, DeepSeek-V2/V3, QwenMoE, Arctic, Jamba…
Hybrid模型：Jamba(Mamba+Attention), Zamba…
多模态模型：LLaVA, Qwen2VL, InternVL, Phi3V, DeepSeekVL…

2.4 模块3：模型执行层-算子层 (vllm/model_executor/layers)

核心作用：提供模型层所需的全部算子实现，是模型层与内核层的桥梁。包含量化、MoE、注意力、位置编码等核心算子。

量化框架注册机制：

2.5 模块4：分布式层 (vllm/distributed)

核心作用：多GPU/多节点分布式推理的通信与协调。支持5维并行布局和11种KV传输连接器。

KV Connector双端接口设计：

2.6 模块5：服务入口层 (vllm/entrypoints)

核心作用：提供多种服务入口，将外部请求转化为引擎可处理的内部格式。核心是OpenAI兼容API。

Chat Completion请求处理完整流程：

2.7 模块6：配置与编译层 (vllm/config + vllm/compilation + vllm/ir)

核心作用：全局配置枢纽（22个子配置类聚合在VllmConfig中）与编译优化管线。

优化级别差异：

级别	编译器	CUDAGraph	融合Pass	适用场景
O0	Eager	无	无	调试/开发
O1	Eager	Full	选择性	生产默认
O2	torch.compile	Partition	全部14步	高性能
O3	Standalone	Full+预编译	全部+离线优化	最高性能

2.8 模块7：LoRA适配器 (vllm/lora)

核心作用：多LoRA动态加载与请求级路由，允许多个LoRA同时服务于不同请求。

2.9 模块8：多模态处理 (vllm/multimodal)

核心作用：图像/音频/视频等多模态输入的编码、嵌入与token化。

关键类：MultiModalRegistry, MultiModalProcessor, ProcessingInfoFactory, MultiModalBudget

2.10 模块9：工具解析器 (vllm/tool_parsers)

核心作用：将模型生成的工具调用文本解析为结构化JSON，支持40种格式。

2.11 模块10：分词器 (vllm/tokenizers)

核心作用：分词与反分词（detokenization），支持14种tokenizer后端。

关键组件：

TokenizerLike：协议定义，统一tokenizer接口
TokenizerRegistry：注册表，按model_type选择实现
HFTokenizer：HuggingFace tokenizer的线程安全封装
MistralTokenizer/DeepSeekTokenizer/QwenVLTokenizer：专用tokenizer
DetokenizerUtils：增量解码，支持stop string检查

2.12 模块11：C++/CUDA内核 (csrc/)

核心作用：高性能GPU内核实现，Python层的计算后端。

2.13 模块12：平台抽象 (vllm/platforms)

核心作用：跨硬件平台适配，6种平台实现。

三、模块间调用关系与数据流

3.1 核心调用关系图

3.2 主流程详解：从HTTP请求到推理输出

阶段1：请求接收与预处理

HTTP POST /v1/chat/completions
  → FastAPI路由 → OpenAIServingChat.create_chat_completion()
    → 提取 messages / model / sampling_params / tools
    → ToolParserManager选择解析器（根据model_type + tool_parser参数）
    → ToolParser.adjust_request()（转换工具参数格式）
    → TokenizerRegistry.get_tokenizer()（按model_type选择tokenizer实现）
    → MultiModalProcessor.process()（编码图像/音频/视频 → mm_embeddings）
    → Tokenizer.encode()（text → token_ids）
    → InputProcessor.process() → EngineCoreRequest(msgspec序列化)

阶段2：调度决策

EngineCore.step() — 核心循环每迭代执行一次:
  → Scheduler.schedule()
    → _select_waiting_queue_for_scheduling() — 选择下一个调度队列
    → 遍历waiting请求，计算token预算(max_num_scheduled_tokens)
    → KVCacheManager.get_computed_blocks() — 前缀缓存匹配
    → KVCacheManager.allocate_slots() — 分配新KV blocks
    → 不足时 _preempt_request() — 抢占running中低优先级请求
    → 构建SchedulerOutput:
      - new_request_data: 新请求的token_ids+block_ids
      - cached_request_data: running请求的追加token+block_ids
      - grammar_output: 结构化输出的bitmask
      - kv_connector_meta: KV传输的元数据

阶段3：模型执行

Executor.execute_model(SchedulerOutput):
  → GPUWorker.execute_model()
    → GPUModelRunner._prepare_inputs():
      → 构建 input_ids, positions, block_tables
      → _build_attention_metadata()（PagedAttention所需元数据）
      → 应用LoRAMapping（请求→LoRA映射表）
      → KVConnector.bind_connector_metadata()（分离式推理）
    → GPUModelRunner.forward():
      → Model.forward(input_ids, positions, kv_caches, attn_metadata):
        → Embedding: VocabParallelEmbedding(input_ids) → hidden_states
        → N × DecoderLayer:
          → RMSNorm(hidden_states)
          → RotaryEmbedding(query, key, positions) — 应用RoPE
          → Attention(query, key, value, attn_metadata) — PagedAttention
            → torch.ops.vllm.paged_attention() — CUDA kernel
            → tp all-reduce (如果张量并行)
          → Residual connection
          → RMSNorm(hidden_states)
          → MLP 或 MoE:
            → MLP: SiluAndMul(gate×up) → Linear(down)
            → MoE: Router(top_k) → Expert Parallel → all2all
          → Residual connection
        → Final RMSNorm → Linear(logits) → LogitsProcessor
      → Sampler(logits, sampling_params) → sampled_token_ids
        → torch.ops.vllm.sample() — CUDA采样kernel
    → 构建AsyncModelRunnerOutput(logits, token_ids, kv_connector_output)

阶段4：输出处理与返回

EngineCore.update_from_output():
  → Scheduler.update_from_output()
    → 更新请求状态(RUNNING→FINISHED/STOPPED/LENGTH/...)
    → KVCacheManager.free() — 释放已完成请求的KV blocks
    → KVConnector.request_finished() — 通知连接器请求完成
  → 构建EngineCoreOutput

EngineCoreClient.get_output():
  → OutputProcessor.process()
    → Detokenizer.decode_incremental() — 增量解码token→text
    → 检查stop_strings / max_tokens / repetition
    → ToolParser.extract_tool_calls() — 如果有工具调用
    → 构建RequestOutput(text, token_ids, finish_reason, logprobs)

AsyncLLM → SSE streaming → Client

3.3 模块间数据传递汇总表

调用方	被调用方	传递数据	数据格式
API Server	AsyncLLM	用户请求	`ChatCompletionRequest(JSON)`
AsyncLLM	InputProcessor	原始prompt	`PromptType(str/list/dict) + SamplingParams`
InputProcessor	EngineCoreClient	处理后请求	`EngineCoreRequest(msgspec.Struct)`
EngineCoreClient	EngineCore	IPC传输	`ZMQ消息 + TensorIPC(共享内存)`
EngineCore	Scheduler	触发调度	内部方法调用
Scheduler	KVCacheManager	分配/释放	`KVCacheBlocks(tuple[list[KVCacheBlock],...])`
Scheduler	Executor	调度结果	`SchedulerOutput(new/cached/grammar数据)`
Executor	Worker	执行指令	`SchedulerOutput(透传)`
Worker	ModelRunner	模型输入	`input_ids + positions + block_tables + attn_metadata`
ModelRunner	Model	前向传播	`hidden_states(Tensor) + kv_caches(dict)`
Model	Attention	QKV计算	`query/key/value(Tensor) + attn_metadata`
Model	FusedMoE	专家计算	`hidden_states + router_output(top_k indices/weights)`
Worker	Executor	执行结果	`AsyncModelRunnerOutput(Future)`
EngineCore	EngineCoreClient	推理输出	`EngineCoreOutput(request_id, token_ids, finish_reason)`
OutputProcessor	Detokenizer	token→text	`token_ids(list[int]) → str`
AsyncLLM	API Server	最终结果	`RequestOutput(text+logprobs+finish_reason)`

3.4 关键设计决策总结

设计决策	选择	原因
KV Cache管理	PagedAttention(分页)	消除显存碎片，支持prefix caching和KV传输
批处理策略	Continuous Batching	迭代级调度(prefill+decode混合)，最大化GPU利用率
进程架构	Frontend/Core分离	API服务不阻塞调度循环，Core可独占GPU调度
调度算法	统一token级调度(无prefill/decode区分)	简化调度器，避免两阶段协调开销
模型加载	延迟导入(Lazy Import)	296种模型类按需加载，减少启动时间和内存
量化支持	注册表+工厂模式	25+量化方法可插拔扩展，运行时按配置选择
分布式通信	NCCL+CustomAllReduce	标准通信(兼容性) + 用户态RDMA(低延迟)
编译优化	torch.compile集成	自定义14步Pass+CUDAGraph，O0-O3渐进优化
多模态	Registry+Processor模式	不同模型的多模态处理可独立扩展
工具调用	40种解析器策略模式	兼容各厂商的不同工具调用格式
分离式推理	11种KV Connector	适配不同网络/存储后端(NIXL/Mooncake/3FS/…)
注意力后端	运行时自动选择	根据GPU架构+配置自动选择最优实现(FA3/FlashInfer/Triton)

四、总结

vLLM是一个分层管道架构的高性能LLM推理引擎，全局6层（入口→引擎→执行器→模型→内核→分布式），横切关注点(配置/分词/LoRA/多模态/平台/编译)以注册表模式注入各层。

8大核心创新点：

PagedAttention：将KV Cache按block管理，消除显存碎片，支持prefix caching和跨节点KV传输
Continuous Batching：迭代级统一token调度，动态组合prefill/decode，最大化吞吐
进程分离：EngineCore独立子进程运行调度循环，Frontend不阻塞调度
插件式注册：模型(296种)/量化(25+)/注意力后端/连接器均可动态注册扩展
5维并行：ExternalDP×DP×PP×PCP×TP的完整分布式布局+弹性扩缩容
编译优化：torch.compile集成+自定义14步Pass管线，O0-O3渐进优化
11种KV Connector：适配不同分离式推理场景(NIXL/Mooncake/3FS/LMCache/…)
40种工具解析器：兼容各厂商工具调用格式(JSON标签/XML标签/专有协议)

一句话架构总结：请求从API入口进入，经InputProcessor预处理(分词+多模态)后通过IPC发送到EngineCore子进程；Scheduler统一token级调度后下发Executor；Worker中的ModelRunner执行模型forward，经PagedAttention和CUDA内核完成推理；结果经Detokenizer解码后流式返回客户端——整个链路各层通过明确的接口和数据结构解耦，横切关注点(配置/分词/LoRA/多模态/平台)以注册表模式注入。

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

使用streamlit+ollama实现聊天小助手

AtomGit开源社区

技术速递｜以 Token 经济学驱动的架构：混合模型、AI Runway、AKS Kata MicroVM 与 MCP

2026年Agent推高云账单Token成本，本文提出云原生架构：AKS+Kata安全隔离、AI Runway分层部署、复用Copilot Token、MCP联动，兼顾安全大幅降本。

AtomGit开源社区

LangGraph多智能体能力进化：从静态配置到动态学习的机制

术语英文全称本文定义大语言模型基于Transformer架构的预训练语言模型，能够理解和生成自然语言，同时也能处理代码、图像、音频等多模态数据（本文主要讨论文本生成能力，但也会提及多模态能力）LangChain一个用于构建LLM应用的开源框架，提供了Model I/O、Retrieval、Tools、Chains、Agents等核心组件LangGraphLangChain生态下的一个用于构建可控、