了解了宏观架构后,让我们深入代码层面,看看项目的”筋骨”是如何搭建的。

📁 目录组织逻辑

vLLM的目录组织非常清晰,体现了”关注点分离”的设计原则:

vllm/                          # Python包主目录

├── engine/                    # 核心引擎(调度、内存管理)

│   ├── llm_engine.py         # LLMEngine – 核心调度引擎

│   ├── async_llm_engine.py   # AsyncLLMEngine – 异步引擎

│   ├── arg_utils.py          # 参数解析和配置

│   └── metrics_types.py      # 监控指标定义

│

├── core/                      # 核心调度和内存管理逻辑

│   ├── scheduler.py          # 请求调度器(Continuous Batching)

│   ├── block_manager_v1.py   # PagedAttention内存管理(V0架构)

│   └── block_manager_v2.py   # 改进的内存管理(V1架构)

│

├── attention/                 # Attention机制实现

│   ├── backends/             # 不同后端的Attention实现

│   │   ├── flash_attn.py    # FlashAttention后端

│   │   ├── flashinfer.py    # FlashInfer后端

│   │   └── xformers.py      # xformers后端

│   └── ops/                  # Attention操作的具体实现

│

├── model_executor/            # 模型执行相关

│   ├── models/               # 各种模型的实现(Llama, Mixtral等)

│   ├── layers/               # 自定义层(量化层、MoE层等)

│   └── parallel_utils/       # 张量并行/流水线并行工具

│

├── worker/                    # 工作器(实际运行模型的单元)

│   ├── worker.py             # Worker基类

│   ├── model_runner.py       # 模型运行器(准备输入、执行推理)

│   └── cache_engine.py       # KV Cache管理

│

├── executor/                  # 执行器(管理分布式workers)

│   ├── gpu_executor.py       # 单机GPU执行器

│   ├── ray_gpu_executor.py   # 分布式GPU执行器(基于Ray)

│   └── executor_base.py      # 执行器基类

│

├── entrypoints/               # 用户入口

│   ├── llm.py                # 离线批量推理入口(LLM类)

│   ├── openai/               # OpenAI兼容API服务器

│   │   └── api_server.py    # API服务器实现

│   └── cli/                  # 命令行工具

│

├── distributed/               # 分布式通信

│   ├── parallel_state.py     # 并行状态管理

│   └── communication_op.py   # 通信原语

│

├── inputs/                    # 输入处理

│   ├── parse.py              # 输入解析

│   └── preprocess.py         # 输入预处理

│

├── multimodal/                # 多模态支持

│   ├── image.py              # 图像输入处理

│   └── video.py              # 视频输入处理

│

├── lora/                      # LoRA适配器支持

├── spec_decode/               # 推测解码

├── compilation/               # 编译优化(Torch Compile)

├── v1/                        # V1新架构(1.7x加速)

└── transformers_utils/        # HuggingFace集成工具

csrc/                          # C++/CUDA源代码

├── attention/                 # Attention内核

│   ├── attention_kernels.cu  # CUDA Attention实现

│   └── flash_attn/           # FlashAttention集成

├── cache_kernels.cu          # KV Cache操作内核

├── activation_kernels.cu     # 激活函数内核

├── layernorm_kernels.cu      # LayerNorm内核

├── quantization/             # 量化内核

├── moe/                      # MoE (Mixture of Experts) 内核

└── torch_bindings.cpp        # Python绑定
examples/                      # 示例代码

├── offline_inference/         # 离线推理示例

│   └── basic/                # 基础示例(从这里开始!)

├── online_serving/            # 在线服务示例

└── lmcache/                  # 缓存优化示例
benchmarks/                    # 性能基准测试

tests/                         # 测试套件(552个测试文件!)

docs/                          # 文档