从云原生走向 AI 原生：一套面向未来的架构方法论 → 阅读《AI 原生基础设施》

vLLM 源码结构与内部机制路线图

草稿

掌握源码结构是高效开发与调试 vLLM 的基础，也是理解其架构演进的关键。

vLLM 是一个高性能的大语言模型（LLM）推理与服务引擎。其源码采用分层架构设计，模块划分清晰，便于扩展和维护。下文将系统梳理 vLLM 的主要目录结构及核心源码分布，帮助开发者快速定位关键模块。

下方图片为 vLLM 代码结构的可视化示意图，便于直观把握模块分布。

图 1: vLLM 代码结构
图 1: vLLM 代码结构

入口点层

本层负责为不同使用场景提供统一入口，开发者可根据需求选择合适的方式调用 vLLM。常见入口包括：

  • LLM 类（vllm/entrypoints/llm.py）：用于离线批量推理的同步 Python API，适合脚本或数据处理场景。
  • OpenAI 兼容 API 服务器（vllm/entrypoints/openai/api_server.py）：提供 REST API 服务，便于与现有 OpenAI 生态集成。
  • CLI 命令行工具（vllm/entrypoints/cli/main.py）：通过 vllm serve 命令启动服务，适合快速部署和测试。

引擎核心层

引擎核心层是 vLLM 的关键部分，负责调度推理流程与模型执行。主要模块如下：

  • LLMEngine（vllm/engine/llm_engine.py）：核心引擎类，负责输入处理、调度、模型执行与输出。

  • AsyncLLMEngine（vllm/engine/async_llm_engine.py）：异步引擎封装，适用于在线服务场景。

  • V1 引擎架构（vllm/v1/engine/）：新一代引擎实现，代码结构更清晰，执行循环更高效，包括：

    • async_llm.py：异步接口
    • core.py：核心执行循环
    • processor.py：输入处理器
    • output_processor.py：输出处理器

配置系统

vLLM 的配置系统统一管理于 vllm/config/ 目录，便于参数化和扩展。主要配置项包括：

  • VllmConfig（vllm/config/vllm.py）：顶层配置对象，整合所有子配置。
  • ModelConfig：模型相关配置。
  • CacheConfig：KV 缓存配置。
  • ParallelConfig：并行策略配置（如张量并行、流水线并行）。
  • SchedulerConfig：调度器配置。

调度与执行层

本层负责请求调度与分布式执行，提升推理效率。核心模块如下：

  • Scheduler（vllm/v1/core/sched/scheduler.py）：请求调度器，管理请求队列、分配 KV 缓存块、批处理请求。

  • Executor（vllm/v1/executor/）：执行器抽象层，管理分布式执行。

    • abstract.py：执行器基类
    • multiproc_executor.py：多进程执行器实现

Worker 与 Model Runner

该层实现了推理任务的实际执行，负责与硬件加速器交互。主要模块包括：

  • Worker（vllm/v1/worker/）：工作进程，每个进程控制一个加速器设备（如 GPU）。
  • ModelRunner（vllm/v1/worker/gpu_model_runner.py）：模型运行器，负责准备输入张量、执行前向传播、采样 token。

模型层

模型相关的实现均位于 vllm/model_executor/ 目录，便于支持多种模型结构。主要内容如下：

  • models/：各类模型实现（如 Llama、Qwen、Mistral 等）。

  • model_loader/：模型加载逻辑。

  • layers/：模型层实现。

    • attention/：注意力机制
    • quantization/：量化方法（FP8、INT4、INT8 等）
    • fused_moe/：融合 MoE 层

注意力后端

不同的注意力机制后端实现分布在以下目录：

  • vllm/attention/backends/ 与 vllm/v1/attention/backends/：包含 FlashAttention 集成、FlashInfer 后端、Triton 实现等。

分布式通信

分布式推理相关的通信逻辑集中在 vllm/distributed/ 目录，支持多种并行策略，包括：

  • 张量并行（Tensor Parallelism, TP）
  • 流水线并行（Pipeline Parallelism, PP）
  • 数据并行（Data Parallelism, DP）
  • KV 缓存传输

多模态支持

多模态模型相关功能位于 vllm/multimodal/，支持多模态输入和注册表管理，便于扩展视觉、语音等能力。

工具与实用程序

辅助开发与集成的工具代码分布如下：

  • transformers_utils/：HuggingFace 集成工具，提升模型兼容性。
  • platforms/：平台特定代码（如 CPU、GPU、TPU、XPU）。
  • csrc/：C++/CUDA 内核实现，优化底层性能。

架构设计原则

vLLM 的架构遵循以下两大设计原则，确保可扩展性与统一性：

  • 可扩展性：所有类均接受统一的 VllmConfig 配置对象，便于新增特性时无需修改构造函数签名。
  • 统一性：模型类采用统一构造函数签名 __init__(self, *, vllm_config: VllmConfig, prefix: str = "")，便于模型运行器自动创建和初始化各类模型。

注意事项

当前 vLLM 正在推进 V1 引擎架构（vllm/v1/ 目录），这是对原有引擎的重大升级，带来更清晰的代码结构和更优化的执行循环。开发时需注意区分 V0 与 V1 的代码路径。代码所有权信息可在 .github/CODEOWNERS 文件中查阅，有助于贡献代码时了解审查者。

内部机制深入路线（撰写中）

以下主题来自原《vLLM 教程》的写作大纲，目前尚未成文，仅保留一句话摘要作为路线图，随本书演进逐步补齐。其中的调度、KV Cache 与吞吐机制，可先结合 vLLM 与 LLM 推理的物理层两章的治理视角阅读；性能核心主题（架构分层、PagedAttention、动态批处理、引擎对比）与 Speculative Decoding 的支持现状，已先行在 vLLM 推理加速与 vLLM 生产调优中展开入门版本，路线图中的同名条目指更深入的源码级拆解。

vLLM 架构

建立 vLLM 的全局架构框架，理解核心组件与系统流转。

  • 总体架构分层（入口 / 调度 / 执行 / 模型）：梳理 vLLM 的主要架构分层与职责。
  • 核心组件关系（AsyncLLM → EngineCore → Scheduler → Worker）：解析 vLLM 内部核心组件的协作关系。
  • 请求在系统内部的高层级流转图：展示请求在 vLLM 系统中的流转路径。
  • 与其他推理引擎的架构差异点：对比 vLLM 与主流推理引擎的架构差异。

性能核心原理

了解 vLLM 的性能核心实现原理。

  • PagedAttention（KV 分页、block 索引）：解析 vLLM 的 PagedAttention 机制与底层实现。
  • Continuous Batching（prefill/decode 分离）：理解 vLLM 的连续批处理与 prefill/decode 分离机制。
  • Prefix Caching：分析 vLLM 的前缀缓存机制与应用场景。
  • EngineCore 主循环与调度决策点：深入解析 EngineCore 的主循环与调度逻辑。

源码解析：从 API 到 EngineCore

了解 vLLM 的源码结构和实现原理。

  • LLM / AsyncLLM 的调用链：梳理 LLM 与 AsyncLLM 的调用链路。
  • Processor（输入 token 化、验证、特征构造）：解析 Processor 的输入处理与特征构造流程。
  • EngineCoreClient（inproc / multiproc 路径）：分析 EngineCoreClient 的多进程与单进程调用路径。
  • EngineCore 主流程解析（step、调度、执行、回写）：详细解析 EngineCore 的主流程与关键环节。
  • OutputProcessor（detokenize、输出结构化）：解析 OutputProcessor 的 detokenize 与输出结构化流程。

调度机制与批处理

了解 vLLM 的批处理调度实现原理。

  • Scheduler 队列模型：解析 vLLM Scheduler 的队列模型与调度逻辑。
  • Prefill / Decode 的分段执行逻辑：分析 prefill 与 decode 的分段执行机制。
  • 动态 batch 的合并与拆分：讲解动态 batch 的合并与拆分策略。
  • 资源压力下的抢占（preempt）：解析 vLLM 在资源压力下的抢占机制。

KVCache 深度与实验

了解 KV 缓存的实现原理和使用方法。

  • KV Cache 架构（BlockAllocator、block table）：解析 KV Cache 的架构与核心数据结构。
  • 分配 / 回收 / 复用策略：讲解 KV Cache 的分配、回收与复用机制。
  • 前缀缓存实验（prefix hit）：通过实验验证前缀缓存的性能提升。
  • 长上下文模拟与内存演化可视化：模拟长上下文推理并可视化内存演化过程。

模型系统

抽象层面理解 vLLM 的模型识别、配置与权重加载。

  • ModelRegistry 的模型识别逻辑：解析 ModelRegistry 的模型识别与注册机制。
  • 模型配置解析流（ModelConfig, CacheConfig…）：梳理模型配置的解析流程与关键参数。
  • 权重加载路径（HF、GGUF、Quantization）：解析权重加载的多种路径与格式支持。
  • tiny 模型实验（toy 模型 + mock runner）：通过 tiny 模型实验验证系统可扩展性。

构建与扩展

深入了解如何构建和扩展 vLLM 系统。

  • vLLM 编译体系（CMake + Python build）：梳理 vLLM 的编译体系与构建流程。
  • CUDA/HIP 扩展模块的结构（CPU 环境走读）：解析 CUDA/HIP 扩展模块在 CPU 环境下的结构。
  • 修改源码后的增量构建：讲解源码修改后的增量构建流程。
  • 构建错误排查：总结 vLLM 构建过程中的常见错误与排查方法。

高级特性与综合实践

多方向应用与综合实践，串联 vLLM 的高级能力。

  • Speculative Decoding（draft/target 协同）：解析 Speculative Decoding 的原理与协同机制。
  • 多模态与适配器体系（LoRA 等）：讲解多模态与适配器体系在 vLLM 的应用。
  • Chunked Prefill：解析 Chunked Prefill 的实现与应用场景。
  • 教学版 mini-vLLM（简化 scheduler + 简化 runner + 简化 kv）：通过教学版 mini-vLLM 理解系统核心抽象。

总结

本文系统梳理了 vLLM 项目的目录结构与核心源码分布，帮助开发者快速定位关键模块，理解架构演进脉络。掌握源码结构不仅有助于高效开发，也为后续功能扩展和性能优化奠定坚实基础。后续的内部机制主题（调度、KV Cache、PagedAttention、源码解析等）将按上文路线图逐步展开。

创建于 2025/11/14 更新于 2026/09/18 3621 字 阅读约 8 分钟