2、vLLM基础与日志体系：vLLM架构简介、日志类型、输出位置与格式

vLLM 作为当前生产环境中部署大语言模型（LLM）的主流推理框架，其核心优势在于高吞吐与内存管理效率。然而，任何生产级系统都离不开可观测性支撑。理解 vLLM 的架构是解读日志的前提，而掌握日志体系则是故障排查的第一道防线。本章将系统梳理 vLLM 的架构组件、日志分类、输出路径与格式规范，帮助读者建立从“看到日志”到“读懂日志”的完整认知链路。

上图展示了 vLLM 内部核心组件与日志类型之间的映射关系。在实际运维中，我们通常通过日志反推架构层的行为：API Server 层的日志反映请求入口状态，Scheduler 层日志揭示排队与调度策略，Executor/Worker 层日志暴露模型推理与显存使用细节，而 KV Cache 管理器日志则直接关联吞吐量瓶颈。理解这种映射关系，是后续进行日志分析的基础。

2.1 vLLM 核心架构组件与日志产生点

vLLM 的架构设计围绕“PagedAttention”机制展开，其核心组件包括：API Server（负责 HTTP 接口与请求解析）、LLM Engine（调度与推理核心）、Scheduler（管理连续批处理与抢占）、Worker/Executor（实际执行模型前向计算）、KV Cache Manager（显存分页管理）。每个组件在运行过程中都会产生特定类型的日志记录。

理解日志产生点有助于快速定位问题域。例如，当请求超时时，若 API Server 日志显示请求已接收但 Scheduler 日志无调度记录，则问题可能出在排队环节；若 Scheduler 已分配但 Worker 日志无推理记录，则可能是显存分配失败或模型执行异常。

2.2 日志类型深度解析

vLLM 的日志体系可划分为四大类，每类日志在故障排查中扮演不同角色。

2.2.1 系统日志

系统日志记录 vLLM 进程的生命周期事件，包括启动参数、配置加载、GPU 资源检测、模型权重加载、优雅关闭等。这类日志通常以 INFO 级别输出，但在资源不足或配置错误时会升级为 WARNING 或 ERROR。例如，启动时检测到 GPU 显存小于模型所需 KV Cache 空间，会输出类似 WARNING Not enough memory to allocate KV cache 的警告。

# 典型系统日志示例
INFO 2025-06-01 10:00:01,234 vllm.engine.llm_engine: Initializing an LLM engine with config:
model='meta-llama/Llama-3-8B', dtype='auto', max_num_seqs=256, max_model_len=8192
INFO 2025-06-01 10:00:03,567 vllm.worker.worker: GPU 0 memory: 40960 MiB total, 38123 MiB free
INFO 2025-06-01 10:00:05,890 vllm.model_executor: Loading model weights took 12.3 seconds

2.2.2 请求日志

请求日志是排查在线服务问题的核心依据。vLLM 默认会为每个请求记录开始与结束事件，包含请求 ID、输入 token 数、输出 token 数、延迟、吞吐等关键指标。在 --log-requests 开启后，日志会详细记录每个请求的完整生命周期。

# 请求日志示例（默认格式）
INFO 2025-06-01 10:00:10,123 vllm.entrypoints.openai.api_server: Received request req_abc123: prompt='Explain quantum computing', num_prompt_tokens=12
INFO 2025-06-01 10:00:10,456 vllm.entrypoints.openai.api_server: Finished request req_abc123: num_output_tokens=256, latency=0.333s, throughput=768.8 tokens/s

2.2.3 错误日志

错误日志记录异常情况，包括模型推理错误、显存溢出（OOM）、非法参数、CUDA 错误等。这类日志通常包含堆栈跟踪，是定位根因的关键。例如，当输入序列长度超过 max_model_len 时，会抛出 ValueError 并记录完整调用栈。

2.2.4 访问日志

访问日志记录所有 HTTP 请求的元数据，包括客户端 IP、请求方法、路径、状态码、响应时长。vLLM 基于 FastAPI 构建，可通过 --access-log 参数控制。这类日志对于安全审计和流量分析至关重要。

# 访问日志示例
INFO 2025-06-01 10:00:10,123 uvicorn.access: 192.168.1.5:52314 - "POST /v1/completions HTTP/1.1" 200 OK

2.3 日志输出位置与格式配置

vLLM 提供灵活的日志输出配置，适应不同部署环境（裸机、Docker、Kubernetes）。

2.3.1 输出位置

• 标准输出（stdout/stderr）：默认输出位置，适合容器化部署，由 Docker/K8s 日志采集器统一收集。
• 文件输出：通过 --log-file 参数指定日志文件路径，适合需要持久化存储的场景。
• 结构化输出：通过 --log-format json 将日志输出为 JSON 格式，便于日志系统（如 ELK、Loki）解析。
• OpenTelemetry 导出：vLLM 支持将指标和追踪导出至 OTLP Collector，实现与监控系统深度集成。

2.3.2 日志格式字段

2.4 实战场景：从日志定位“高延迟”问题

假设生产环境反馈 API 响应变慢，平均延迟从 200ms 升至 800ms。我们通过日志分析定位根因。

初始现象：监控面板显示 P99 延迟飙升，但 CPU 和 GPU 利用率均未饱和。

日志分析过程：

1. 查看访问日志，确认延迟升高集中在 /v1/completions 端点。
2. 检查请求日志，发现 num_prompt_tokens 平均值从 50 升至 300，输入长度显著增加。
3. 进一步查看系统日志，发现 max_num_seqs 参数为 256，但当前并发请求数达到 250，接近上限。
4. 结合 Scheduler 日志，发现批处理大小从 32 降至 8，导致 GPU 利用率下降。

根因判断：输入 token 数增加导致 KV Cache 占用增大，Scheduler 被迫缩小批处理大小以适配显存，从而降低了吞吐并增加延迟。

解决方案：调整 --gpu-memory-utilization 从 0.9 降至 0.85，预留更多 KV Cache 空间；同时将 --max-num-seqs 降至 128，避免过度并发。

2.5 常见误区与最佳实践

误区一：将所有日志级别设为 DEBUG 以获取更多信息。这会导致日志量爆炸，且关键信息被淹没。生产环境建议保持 INFO 级别，仅在排查特定问题时临时开启 DEBUG。

误区二：忽略 WARNING 级别日志。vLLM 的许多 WARNING（如显存不足、缓存命中率低）是性能劣化的前兆，应视为需要关注的事件。

误区三：日志格式不统一。默认格式适合人类阅读，但不利于自动化分析。建议在 Kubernetes 环境中使用 --log-format json，并配合日志采集器提取结构化字段。