【vllm】vllm/docs/configuration/optimization.md

vllm/docs/configuration/optimization.md (a5b84f1)

优化与调优

本指南涵盖 vLLM V1 的优化策略与性能调优。

!!! 提示
遇到内存不足？请参考内存节约指南。

抢占（Preemption）

由于 Transformer 架构的自回归特性，有时 KV 缓存空间不足以处理所有批处理请求。此时，vLLM 可以抢占部分请求以释放 KV 缓存空间供其他请求使用。当有足够的 KV 缓存空间时，被抢占的请求会被重新计算。发生这种情况时，您可能会看到以下警告：

WARNING 05-09 00:49:33 scheduler.py:1057 序列组 0 因 KV 缓存空间不足被抢占，抢占模式为 PreemptionMode.RECOMPUTE。这会影响端到端性能。请增加 gpu_memory_utilization 或 tensor_parallel_size 以提供更多 KV 缓存内存。total_cumulative_preemption_cnt=1

尽管这种机制保证了系统的健壮性，但抢占和重计算会对端到端延迟产生负面影响。如果您频繁遇到抢占，请考虑以下措施：

• 增加gpu_memory_utilization。vLLM 会使用该比例的内存预分配 GPU 缓存。提高利用率可以为 KV 缓存提供更多空间。
• 减小max_num_seqs或max_num_batched_tokens。这会减少批处理中的并发请求数量，从而减少 KV 缓存空间需求。
• 增加tensor_parallel_size。这将模型权重分片到多个 GPU 上，使每个 GPU 有更多内存可用于 KV 缓存。但增加该值可能导致额外的同步开销。
• 增加pipeline_parallel_size。将模型层分布到多个 GPU，减少每个 GPU 上模型权重的内存占用，间接为 KV 缓存留出更多内存。但增加该值可能导致延迟增加。

您可以通过 vLLM 暴露的 Prometheus 指标监控抢占请求的数量。此外，设置disable_log_stats=False可以记录累计的抢占请求数。

在 vLLM V1 中，默认的抢占模式是RECOMPUTE而非SWAP，因为在 V1 架构中重计算的开销更低。

{ #chunked-prefill }

分块预填充（Chunked Prefill）

分块预填充允许 vLLM 将大的预填充请求切分成小块，并与解码请求一起批处理。该特性通过更好地平衡计算密集型（预填充）和内存密集型（解码）操作，提高吞吐量和延迟。

在 vLLM V1 中，分块预填充默认始终启用。这与 vLLM V0 不同（V0 中基于模型特性有条件启用）。

启用分块预填充后，调度策略会优先处理解码请求。它会在调度任何预填充操作之前，批处理所有待处理的解码请求。当max_num_batched_tokens预算中有剩余 token 时，会调度待处理的预填充请求。如果一个待处理的预填充请求无法完全放入max_num_batched_tokens，它会自动分块。

该策略有两个好处：

• 改善 token 间延迟（ITL）和生成解码，因为解码请求被优先处理。
• 通过将计算密集型（预填充）和内存密集型（解码）请求放在同一个批次中，有助于实现更好的 GPU 利用率。

分块预填充的性能调优

您可以通过调整max_num_batched_tokens来调优性能：

• 较小的值（例如 2048）可以获得更好的 token 间延迟（ITL），因为较少的预填充会拖慢解码。
• 较大的值可以获得更好的首 token 时间（TTFT），因为可以在一个批次中处理更多的预填充 token。
• 为了获得最佳吞吐量，我们建议将max_num_batched_tokens设为 > 8192，特别是在大 GPU 上运行较小模型时。
• 如果max_num_batched_tokens等于max_model_len，则几乎等同于 V0 默认调度策略（除了仍然优先解码）。

fromvllmimportLLM# 设置 max_num_batched_tokens 以调优性能llm=LLM(model="meta-llama/Llama-3.1-8B-Instruct",max_num_batched_tokens=16384)

更多细节请参考相关论文（https://arxiv.org/pdf/2401.08671 或 https://arxiv.org/pdf/2308.16369）。

并行策略

vLLM 支持多种并行策略，可以组合使用以针对不同硬件配置优化性能。

张量并行（Tensor Parallelism, TP）

张量并行将每个模型层内的模型参数分片到多个 GPU 上。这是单节点内大模型推理最常用的策略。

使用场景：

• 当模型太大无法放入单个 GPU 时
• 当需要减少每个 GPU 的内存压力，以便为 KV 缓存留出更多空间，从而提高吞吐量时

fromvllmimportLLM# 将模型分片到 4 个 GPUllm=LLM(model="meta-llama/Llama-3.3-70B-Instruct",tensor_parallel_size=4)

对于无法放入单个 GPU 的模型（如 70B 参数模型），张量并行是必不可少的。

流水线并行（Pipeline Parallelism, PP）

流水线并行将模型层分布到多个 GPU 上。每个 GPU 按顺序处理模型的不同部分。

使用场景：

• 当已经用尽了高效的张量并行但仍需进一步分布模型，或者需要跨节点分布时
• 对于非常深且窄的模型，层分布比张量分片更高效

流水线并行可以与张量并行组合用于非常大的模型：

fromvllmimportLLM# 组合流水线并行和张量并行llm=LLM(model="meta-llama/Llama-3.3-70B-Instruct",tensor_parallel_size=4,pipeline_parallel_size=2)

专家并行（Expert Parallelism, EP）

专家并行是一种专门用于混合专家（MoE）模型的并行形式，不同的专家网络被分布到不同的 GPU 上。

使用场景：

• 专门用于 MoE 模型（如 DeepSeekV3、Qwen3MoE、Llama-4）
• 当需要在 GPU 之间平衡专家计算负载时

通过设置enable_expert_parallel=True启用专家并行，这将使 MoE 层使用专家并行而非张量并行。它使用与张量并行相同的并行度。

数据并行（Data Parallelism, DP）

数据并行将整个模型复制到多个 GPU 组上，并并行处理不同的请求批次。

使用场景：

• 当有足够多的 GPU 来复制整个模型时
• 当需要扩展吞吐量而非模型大小时
• 在多用户环境中，请求批次之间的隔离有益时

数据并行可以与其他并行策略组合，通过data_parallel_size=N设置。注意，MoE 层将根据张量并行大小和数据并行大小的乘积进行分片。

多模态编码器的批次级 DP

默认情况下，TP 用于对多模态编码器的权重进行分片，就像对语言解码器一样，以减少每个 GPU 上的内存和计算负载。

然而，由于多模态编码器的规模相比语言解码器非常小，TP 带来的收益相对较小。另一方面，TP 会带来显著的通信开销，因为每一层之后都要执行 all-reduce。

考虑到这一点，使用 TP 对批处理输入数据进行分片（本质上就是执行批次级 DP）可能更有利。已证明对于tensor_parallel_size=8这可以将吞吐量提高约 10%。对于使用未针对硬件优化的 Conv3D 操作的视觉编码器，与常规 TP 相比，批次级 DP 可以再提供 40% 的吞吐量提升。

尽管如此，由于多模态编码器的权重在每个 TP rank 上被复制，内存消耗会略有增加，如果模型刚好能放入内存，可能导致 OOM。

您可以通过设置mm_encoder_tp_mode="data"来启用批次级 DP，例如：

fromvllmimportLLM llm=LLM(model="Qwen/Qwen2.5-VL-72B-Instruct",tensor_parallel_size=4,# 当 mm_encoder_tp_mode="data" 时，# 视觉编码器使用 TP=4（而不是 DP=1）对输入数据进行分片，# 因此 TP 大小成为有效的 DP 大小。# 注意，这与语言解码器在专家并行设置中使用的 DP 大小无关。mm_encoder_tp_mode="data",# 无论 mm_encoder_tp_mode 如何设置，语言解码器都使用 TP=4 对权重进行分片)

!!! 重要
批次级 DP 不同于 API 请求级 DP（后者由data_parallel_size控制）。

批次级 DP 需要按模型逐一实现，并在模型类中设置supports_encoder_tp_data = True。无论如何，您需要在引擎参数中设置mm_encoder_tp_mode="data"才能使用此功能。

已知支持的模型：

• GLM-4.5V GLM-4.1V (gh-pr:23168)
• Kimi-VL (gh-pr:23817)
• Llama4 (gh-pr:18368)
• MiniCPM-V-2.5 或更高版本 (gh-pr:23327, gh-pr:23948)
• Qwen2.5-VL (gh-pr:22742)
• Step3 (gh-pr:22697)

输入处理

并行处理

您可以通过 API 服务器横向扩展 来并行运行输入处理。当输入处理（在 API 服务器内运行）相比模型执行（在引擎核心内运行）成为瓶颈，并且您有额外的 CPU 容量时，这非常有用。

# 运行 4 个 API 进程和 1 个引擎核心进程 vllm serve Qwen/Qwen2.5-VL-3B-Instruct --api-server-count 4 # 运行 4 个 API 进程和 2 个引擎核心进程 vllm serve Qwen/Qwen2.5-VL-3B-Instruct --api-server-count 4 -dp 2

!!! 注意
API 服务器横向扩展仅适用于在线推理。

!!! 警告
默认情况下，每个 API 服务器使用 8 个 CPU 线程从请求数据中加载媒体项（例如图像）。

如果使用 API 服务器横向扩展，请考虑调整 `VLLM_MEDIA_LOADING_THREAD_COUNT` 以避免 CPU 资源耗尽。

!!! 注意
API 服务器横向扩展会禁用多模态 IPC 缓存，因为它需要 API 和引擎核心进程之间一一对应。

这不会影响[多模态处理器缓存](#processor-caching)。

多模态缓存

多模态缓存避免重复传输或处理相同的多模态数据，这常见于多轮对话中。

处理器缓存

多模态处理器缓存自动启用，以避免在BaseMultiModalProcessor中重复处理相同的多模态输入。

IPC 缓存

当 API 进程（P0）和引擎核心进程（P1）之间一一对应时，多模态 IPC 缓存自动启用，以避免在它们之间重复传输相同的多模态输入。

键副本缓存（Key-Replicated Cache）

默认情况下，IPC 缓存使用键副本缓存，其中缓存键同时存在于 API 进程（P0）和引擎核心进程（P1），但实际缓存数据仅存在于P1。

共享内存缓存

当涉及多个工作进程时（例如 TP > 1），共享内存缓存更高效。可以通过设置mm_processor_cache_type="shm"启用。在此模式下，缓存键存储在P0上，而缓存数据本身位于所有进程可访问的共享内存中。

配置

您可以通过设置mm_processor_cache_gb的值（默认 4 GiB）来调整缓存大小。

如果缓存带来的收益不大，可以通过mm_processor_cache_gb=0完全禁用 IPC 和处理器缓存。

示例：

# 使用更大的缓存llm=LLM(model="Qwen/Qwen2.5-VL-3B-Instruct",mm_processor_cache_gb=8)# 使用基于共享内存的 IPC 缓存llm=LLM(model="Qwen/Qwen2.5-VL-3B-Instruct",tensor_parallel_size=2,mm_processor_cache_type="shm",mm_processor_cache_gb=8)# 禁用缓存llm=LLM(model="Qwen/Qwen2.5-VL-3B-Instruct",mm_processor_cache_gb=0)

缓存放置

根据配置，P0和P1上的多模态缓存内容如下：

K：存储多模态项的哈希值
V：存储多模态项处理后的张量数据