vllm 学习笔记

Appearance

架构概览 — 代码走读 ​

入口点走读 ​

CLI 入口 — vllm/entrypoints/cli/main.py ​

vllm 命令行工具的入口，注册了以下子命令：

python
# 简化的命令注册
subparsers = parser.add_subparsers()

serve_parser = subparsers.add_parser("serve")
serve_parser.set_defaults(func=run_server)

openai_parser = subparsers.add_parser("openai")
openai_parser.set_defaults(func=run_openai_server)

关键路径：vllm serve → run_server() → 创建 AsyncLLM → 启动 FastAPI。

OpenAI API Server — vllm/entrypoints/openai/api_server.py ​

FastAPI 应用入口，负责：

  1. 注册路由：/v1/chat/completions、/v1/completions、/v1/embeddings、/v1/responses
  2. 初始化 AsyncLLMEngine（实际是 AsyncLLM 的别名）
  3. 配置中间件（CORS、限流、健康检查）
python
# 简化的初始化
engine = AsyncLLMEngine.from_engine_args(engine_args)
app = FastAPI()
app.include_router(chat_router)
app.include_router(completion_router)

离线 LLM 类 — vllm/entrypoints/llm.py ​

提供同步的批处理推理接口，采用 Mixin 组合架构：

python
llm = LLM(model="meta-llama/Llama-3-8B")
outputs = llm.generate(["Hello, world!"])

# 推测解码快捷参数
llm = LLM(model="...", spec_method="ngram", spec_tokens=5)

内部创建 LLMEngine（V1 中是 AsyncLLM 的同步包装），循环调用 step() 直到所有请求完成。

LLM 类的继承链：

LLM → BeamSearchOfflineMixin → PoolingOfflineMixin → OfflineInferenceMixin

核心推理逻辑在 OfflineInferenceMixin（entrypoints/offline_utils.py），beam search 在 entrypoints/generate/beam_search/offline.py。

引擎初始化走读 ​

EngineCore 创建流程 ​

关键文件路径：

  • vllm/engine/arg_utils.py — CLI 参数解析为 EngineArgs
  • vllm/v1/engine/core.py — EngineCore 初始化与主循环
  • vllm/v1/executor/multiproc_executor.py — 多进程 Worker 创建

配置系统走读 ​

VllmConfig 聚合 — vllm/config/vllm.py ​

VllmConfig 是所有子配置的聚合器：

python
@dataclass
class VllmConfig:
    model_config: ModelConfig
    cache_config: CacheConfig
    parallel_config: ParallelConfig
    scheduler_config: SchedulerConfig
    compilation_config: CompilationConfig
    # ... 30+ 子配置

配置验证链 ​

配置之间有复杂的依赖关系。例如：

  1. ModelConfig 确定模型的 head_dim 和 num_layers
  2. CacheConfig 依赖这些参数计算 block_size
  3. SchedulerConfig 依赖 CacheConfig 确定 max_num_seqs

模块组织走读 ​

源码目录结构 ​

vllm/
├── entrypoints/          # 入口层
│   ├── cli/              # CLI 子命令：serve、openai
│   ├── openai/           # OpenAI API Server
│   │   ├── api_server.py # FastAPI 应用
│   │   └── dp_supervisor.py # 多端口数据并行管理器
│   ├── llm.py            # LLM 离线类（Mixin 组合）
│   ├── offline_utils.py  # OfflineInferenceMixin
│   └── generate/
│       └── beam_search/  # beam search 拆分模块
├── models/               # 外部模型包（特殊硬件依赖）
│   └── deepseek_v4/      # DeepSeek V4（自定义 CUDA kernel）
├── engine/               # 引擎层：EngineClient 协议、EngineArgs
├── v1/
│   ├── engine/           # V1 引擎实现：Core、AsyncLLM、CoreClient
│   ├── core/             # 调度层：Scheduler、KVCacheManager
│   ├── executor/         # 执行层：MultiProc、Ray、UniProc
│   ├── worker/           # Worker：GPU/CPU/XPU、ModelRunner
│   ├── attention/        # 注意力后端：FlashAttn、FlashInfer 等
│   ├── spec_decode/      # 推测解码：EAGLE、Medusa、N-gram
│   ├── structured_output/ # 结构化输出：xgrammar、outlines
│   ├── sample/           # 采样：top-k、top-p、temperature
│   ├── metrics/          # 指标：Prometheus、统计
│   └── kv_offload/       # KV 缓存卸载（含文件系统分层）
├── model_executor/
│   ├── models/           # 200+ 模型实现
│   ├── layers/           # 可复用 NN 层（含 fused_moe、mamba/gdn）
│   └── quantization/     # 量化方法
├── config/               # 30+ 配置 dataclass
├── distributed/          # 分布式：TP、PP、DP、EP（含 Elastic EP）
├── multimodal/           # 多模态：图像、音频、视频
├── lora/                 # LoRA 适配器
├── platforms/            # 硬件平台：CUDA、ROCm、CPU、TPU
├── tokenizers/           # 分词器
└── compilation/          # torch.compile、CUDA Graph

关键函数索引 ​

函数/类文件职责
EngineCore.__init__()v1/engine/core.py初始化调度器、执行器、KV 缓存
EngineCore.run_loop()v1/engine/core.py主循环：调度 → 执行 → 输出处理
AsyncLLM.generate()v1/engine/async_llm.py异步推理入口
LLM.generate()entrypoints/llm.py同步推理入口
EngineArgs.create_engine_config()engine/arg_utils.pyCLI 参数 → VllmConfig
Scheduler.schedule()v1/core/sched/scheduler.py连续批处理调度决策
Executor.execute_model()v1/executor/abstract.py执行层抽象接口
ModelRunner.forward()v1/worker/gpu_model_runner.pyGPU 模型前向传播