Sovia's Blog
VLLM V1性能优化指南2
LiuSovia 化神
  2026-02-03 01:59:27   2026-02-03 01:59:27    7.3k 字

VLLM V1性能优化指南2

12. 参考资源

12.1 官方文档

12.2 性能基准

12.3 社区资源

13. vLLM 0.11.1 V1版本参数调优

13.1 V1架构核心参数

vLLM 0.11.1引入了全新的V1架构，具有显著的性能提升和新特性。以下是V1版本专属的关键参数。

13.1.1 V1架构启用

确认V1架构已启用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
from vllm import LLM
import vllm.envs as envs

# 检查V1是否启用（默认为True）
print(f"V1 Enabled: {envs.VLLM_USE_V1}")

# 强制启用V1架构（通常已默认启用）
import os
os.environ["VLLM_USE_V1"] = "1"

llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    # V1会自动使用新的EngineCore和Scheduler
)

13.1.2 异步调度（Async Scheduling）

新特性：V1版本支持异步调度，减少GPU空闲时间，提升吞吐量和延迟。

1
2
3
4
5
6
7
8
9
10
11
12
13
# 方式1: Python API
from vllm import LLM

llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    async_scheduling=True,  # 启用异步调度（V1专属）
    tensor_parallel_size=4,
)

# 方式2: 命令行
vllm serve meta-llama/Llama-2-70b-hf \
    --async-scheduling \
    --tensor-parallel-size 4

性能提升：

  • 吞吐量提升: 5-15%（特别是高并发场景）
  • 延迟降低: 10-20%（减少调度开销）
  • GPU利用率: 提高2-8%

注意事项：

  • 不支持speculative decoding
  • 不支持pipeline parallelism
  • 适用于高并发在线服务场景

配置示例 - 高并发服务：

1
2
3
4
5
6
7
8
llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    async_scheduling=True,
    max_num_seqs=256,
    max_num_batched_tokens=16384,
    enable_chunked_prefill=True,
    gpu_memory_utilization=0.95,
)

13.1.3 V1多进程模式

新特性：V1架构支持多进程执行模式，提升稳定性和资源隔离。

1
2
3
4
5
6
7
8
# 启用V1多进程（默认True）
export VLLM_ENABLE_V1_MULTIPROCESSING=1

# 选择多进程方法
export VLLM_WORKER_MULTIPROC_METHOD=spawn  # 或 fork

vllm serve meta-llama/Llama-2-70b-hf \
    --tensor-parallel-size 4

多进程方法对比：

方法 内存开销 启动速度 稳定性 适用场景
fork 低 快 较好 Linux，单机多GPU
spawn 高 慢 最佳 Windows，跨节点，P/D分离

Python API配置：

1
2
3
4
5
6
7
8
9
10
import os
os.environ["VLLM_ENABLE_V1_MULTIPROCESSING"] = "1"
os.environ["VLLM_WORKER_MULTIPROC_METHOD"] = "spawn"

from vllm import LLM

llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    tensor_parallel_size=4,
)

13.1.4 调度器策略配置

V1架构支持多种调度策略。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
from vllm import LLM

# FCFS调度（先来先服务，默认）
llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    scheduling_policy="fcfs",
)

# 优先级调度
llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    scheduling_policy="priority",
)

# 命令行
vllm serve meta-llama/Llama-2-70b-hf \
    --scheduling-policy priority

优先级调度使用示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from vllm import LLM, SamplingParams

llm = LLM(
    model="meta-llama/Llama-2-7b-hf",
    scheduling_policy="priority",
)

prompts = [
    "High priority request",
    "Low priority request",
]

sampling_params = [
    SamplingParams(priority=0),  # 高优先级
    SamplingParams(priority=10), # 低优先级
]

outputs = llm.generate(prompts, sampling_params)

13.1.5 并发部分Prefill（V1增强）

V1版本增强了chunked prefill功能，支持更细粒度的控制。

1
2
3
4
5
6
7
8
9
10
11
12
from vllm import LLM

llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    enable_chunked_prefill=True,
    max_num_batched_tokens=8192,
    
    # V1新增参数
    max_num_partial_prefills=4,  # 最大并发部分prefill数
    max_long_partial_prefills=2,  # 长prompt并发数
    long_prefill_token_threshold=2048,  # 长prompt阈值
)

命令行配置：

1
2
3
4
5
6
vllm serve meta-llama/Llama-2-70b-hf \
    --enable-chunked-prefill \
    --max-num-batched-tokens 8192 \
    --max-num-partial-prefills 4 \
    --max-long-partial-prefills 2 \
    --long-prefill-token-threshold 2048

参数说明：

  • max_num_partial_prefills: 最多同时处理多少个部分prefill请求
  • max_long_partial_prefills: 长prompt（>阈值）最多同时处理数量
  • long_prefill_token_threshold: 长短prompt分界阈值

优势：

  • 短prompt可以插队，降低平均延迟
  • 长prompt不会完全阻塞短请求
  • 提升混合负载场景的QoS

性能对比：

配置 平均延迟 P99延迟 吞吐量
默认（=1） 基准 基准 基准
max_num_partial_prefills=4 -15% -25% +8%
+max_long=2, threshold=2048 -20% -35% +10%

13.1.6 自定义调度器（高级）

V1架构允许使用自定义调度器实现。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from vllm import LLM

# 使用自定义调度器类
llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    scheduler_cls="my_module.CustomScheduler",  # 自定义调度器
)

# 或直接传入类
from my_module import CustomScheduler

llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    scheduler_cls=CustomScheduler,
)

自定义调度器示例（需实现SchedulerInterface）：

1
2
3
4
5
6
7
8
9
10
from vllm.v1.core.sched.interface import SchedulerInterface
from vllm.v1.core.sched.scheduler import Scheduler

class CustomScheduler(Scheduler):
    """自定义调度器，优先调度短请求"""
    
    def schedule(self) -> SchedulerOutput:
        # 按prompt长度排序
        self.waiting_queue.sort(key=lambda req: req.num_prompt_tokens)
        return super().schedule()

13.1.7 混合KV Cache管理器控制

V1支持混合KV Cache管理（针对不同attention类型）。

1
2
3
4
5
6
7
8
9
10
11
from vllm import LLM

# 禁用混合KV Cache管理器（统一大小）
llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    disable_hybrid_kv_cache_manager=True,
)

# 命令行
vllm serve meta-llama/Llama-2-70b-hf \
    --disable-hybrid-kv-cache-manager

使用场景：

  • 模型有多种attention层（如full attention + sliding window）
  • 默认会为不同层分配不同大小KV cache
  • 设置为True强制所有层使用相同大小（简化但可能浪费内存）

13.2 V1性能优化配置示例

13.2.1 高吞吐量配置（批处理场景）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
from vllm import LLM
import os

# 环境变量
os.environ["VLLM_USE_V1"] = "1"
os.environ["VLLM_ENABLE_V1_MULTIPROCESSING"] = "1"

llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    
    # V1异步调度
    async_scheduling=True,
    
    # 大batch配置
    max_num_seqs=256,
    max_num_batched_tokens=16384,
    
    # Chunked prefill优化
    enable_chunked_prefill=True,
    max_num_partial_prefills=8,
    max_long_partial_prefills=4,
    long_prefill_token_threshold=2048,
    
    # 内存和并行
    gpu_memory_utilization=0.95,
    tensor_parallel_size=4,
    
    # 前缀缓存
    enable_prefix_caching=True,
    
    # 调度策略
    scheduling_policy="fcfs",
)

预期性能（4×A100 80GB）：

  • 吞吐量: 2500-3000 tokens/s
  • 并发请求: 200+
  • GPU利用率: 90%+

13.2.2 低延迟配置（在线服务）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
from vllm import LLM
import os

os.environ["VLLM_USE_V1"] = "1"
os.environ["VLLM_ENABLE_V1_MULTIPROCESSING"] = "1"

llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    
    # V1异步调度（降低调度延迟）
    async_scheduling=True,
    
    # 小batch，低延迟
    max_num_seqs=64,
    max_num_batched_tokens=4096,
    
    # Chunked prefill（快速响应）
    enable_chunked_prefill=True,
    max_num_partial_prefills=2,
    max_long_partial_prefills=1,
    
    # 优先级调度
    scheduling_policy="priority",
    
    # 并行配置
    tensor_parallel_size=4,
    gpu_memory_utilization=0.90,
)

预期性能（4×A100 80GB）：

  • TTFT (Time to First Token): 50-100ms
  • TPOT (Time per Output Token): 15-25ms
  • P99延迟: <500ms

13.2.3 混合负载配置（通用场景）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 环境变量配置
export VLLM_USE_V1=1
export VLLM_ENABLE_V1_MULTIPROCESSING=1
export VLLM_WORKER_MULTIPROC_METHOD=spawn

# 启动服务
vllm serve meta-llama/Llama-2-70b-hf \
    --async-scheduling \
    --max-num-seqs 128 \
    --max-num-batched-tokens 8192 \
    --enable-chunked-prefill \
    --max-num-partial-prefills 4 \
    --max-long-partial-prefills 2 \
    --long-prefill-token-threshold 1024 \
    --scheduling-policy fcfs \
    --tensor-parallel-size 4 \
    --gpu-memory-utilization 0.92 \
    --enable-prefix-caching \
    --dtype bfloat16

13.3 V1调试与监控

13.3.1 V1日志配置

1
2
3
4
5
6
# 启用详细日志
export VLLM_LOGGING_LEVEL=DEBUG
export VLLM_LOG_STATS_INTERVAL=5.0  # 每5秒输出统计

vllm serve meta-llama/Llama-2-70b-hf \
    --async-scheduling

13.3.2 V1性能分析

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import os

# 启用Torch Profiler（V1兼容）
os.environ["VLLM_TORCH_PROFILER_DIR"] = "./profiler_output"
os.environ["VLLM_TORCH_CUDA_PROFILE"] = "1"

from vllm import LLM

llm = LLM(
    model="meta-llama/Llama-2-7b-hf",
    async_scheduling=True,
)

# 运行推理（会生成profiler数据）
outputs = llm.generate(["Hello"] * 10)

13.4 V1环境变量完整列表

V1核心环境变量

变量名 默认值 说明
VLLM_USE_V1 True 启用V1架构（0.11.1默认）
VLLM_ENABLE_V1_MULTIPROCESSING True V1多进程模式
VLLM_WORKER_MULTIPROC_METHOD fork 多进程方法（fork/spawn）
VLLM_V1_OUTPUT_PROC_CHUNK_SIZE 128 输出处理chunk大小
VLLM_V1_USE_OUTLINES_CACHE False 启用Outlines缓存
VLLM_V1_USE_PREFILL_DECODE_ATTENTION False Prefill/Decode分离attention

通用性能环境变量

变量名 默认值 说明
VLLM_ATTENTION_BACKEND None 强制Attention后端
VLLM_USE_FLASHINFER_SAMPLER None FlashInfer采样器
VLLM_FUSED_MOE_CHUNK_SIZE 65536 MoE融合chunk大小
VLLM_LOGGING_LEVEL INFO 日志级别
VLLM_LOG_STATS_INTERVAL 10.0 统计日志间隔（秒）

13.5 V1迁移指南

如果从V0迁移到V1，注意以下变化：

API兼容性

1
2
3
4
5
6
# V0和V1 API完全兼容
from vllm import LLM, SamplingParams

# 这段代码在V0和V1都能运行
llm = LLM(model="meta-llama/Llama-2-7b-hf")
outputs = llm.generate(["Hello"], SamplingParams(max_tokens=100))

新增参数

仅V1可用的参数：

  • async_scheduling
  • max_num_partial_prefills
  • max_long_partial_prefills
  • long_prefill_token_threshold
  • scheduler_cls
  • disable_hybrid_kv_cache_manager

性能提升

指标 V0 V1 提升
吞吐量 基准 1.15-1.30x +15-30%
TTFT 基准 0.85-0.90x -10-15%
GPU利用率 85-90% 90-95% +5-10%
调度开销 基准 0.70-0.80x -20-30%

13.6 V1故障排除

问题1: 异步调度不生效

1
2
3
4
5
6
7
8
# 检查是否与不兼容功能同时使用
llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    async_scheduling=True,
    # pipeline_parallel_size=2,  # ❌ 不兼容
    # speculative_config={...},  # ❌ 不兼容
    tensor_parallel_size=4,  # ✅ 兼容
)

问题2: 多进程启动失败

1
2
3
4
5
6
# Windows或跨节点场景使用spawn
export VLLM_WORKER_MULTIPROC_METHOD=spawn

# P/D分离架构必须使用spawn
export VLLM_ENABLE_V1_MULTIPROCESSING=1
export VLLM_WORKER_MULTIPROC_METHOD=spawn

问题3: 自定义调度器报错

1
2
3
4
5
6
7
8
9
10
# 确保调度器实现了SchedulerInterface
from vllm.v1.core.sched.interface import SchedulerInterface

class MyScheduler(SchedulerInterface):
    # 必须实现所有抽象方法
    def schedule(self) -> SchedulerOutput:
        ...
    
    def add_request(self, request: Request) -> None:
        ...

13.7 max_model_len与上下文长度优化

max_model_len是vLLM中最重要的配置参数之一，直接影响内存占用、性能和可处理的序列长度。

13.7.1 max_model_len基础概念

定义：

  • max_model_len: 模型可处理的最大序列长度（prompt + output）
  • 如果不指定，会从模型配置中自动推断（通常是max_position_embeddings）
1
2
3
4
5
6
from vllm import LLM

llm = LLM(
    model="meta-llama/Llama-2-7b-hf",
    max_model_len=4096,  # 显式设置最大序列长度
)

命令行配置：

1
2
3
4
5
6
7
8
9
# 基本配置
vllm serve meta-llama/Llama-2-7b-hf \
    --max-model-len 4096

# 支持人类可读格式
vllm serve meta-llama/Llama-2-7b-hf \
    --max-model-len 8k    # 8,000
    # --max-model-len 8K  # 8,192
    # --max-model-len 16k # 16,000

自动推断示例：

1
2
3
4
5
6
7
8
9
10
from vllm import LLM

# 自动从模型配置推断
llm = LLM(
    model="meta-llama/Llama-2-7b-hf",
    # max_model_len 自动设置为 4096 (模型的max_position_embeddings)
)

print(f"Max model len: {llm.llm_engine.model_config.max_model_len}")
# Output: Max model len: 4096

13.7.2 max_model_len与相关参数关系

核心参数关系图：

1
2
3
4
5
6
7
8
9
10
max_model_len (序列长度)
    ↓
    ├─→ max_num_batched_tokens (token预算)
    │   └─→ 影响吞吐量和并发能力
    │
    ├─→ KV Cache大小
    │   └─→ 影响GPU内存占用
    │
    └─→ max_num_seqs (并发请求数)
        └─→ 受max_num_batched_tokens约束

1. max_model_len vs max_num_batched_tokens

1
2
3
4
5
6
7
8
from vllm import LLM

llm = LLM(
    model="meta-llama/Llama-2-7b-hf",
    max_model_len=8192,           # 单个序列最大长度
    max_num_batched_tokens=16384, # 单次处理的总token数
    # 关系：max_num_batched_tokens >= max_model_len
)

重要约束：

1
2
3
4
5
6
7
# 合法配置
max_model_len=4096
max_num_batched_tokens=8192  # >= max_model_len

# 非法配置（会报错）
max_model_len=8192
max_num_batched_tokens=4096  # < max_model_len

2. max_model_len vs max_num_seqs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 场景1：长序列、少并发
llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    max_model_len=32768,          # 长上下文
    max_num_batched_tokens=65536,
    max_num_seqs=2,               # 少并发 (65536/32768=2)
)

# 场景2：短序列、高并发
llm = LLM(
    model="meta-llama/Llama-2-7b-hf",
    max_model_len=2048,           # 短上下文
    max_num_batched_tokens=16384,
    max_num_seqs=128,             # 高并发 (16384/2048=8, 但可设更高)
)

3. max_model_len与KV Cache

KV Cache内存占用与max_model_len成正比：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# 计算KV Cache大小
def estimate_kv_cache_memory(max_model_len, num_layers, num_kv_heads, 
                            head_dim, dtype_bytes, num_blocks):
    """
    max_model_len: 最大序列长度
    num_layers: 层数
    num_kv_heads: KV头数
    head_dim: 头维度
    dtype_bytes: 数据类型字节数 (2 for fp16/bf16, 1 for fp8)
    num_blocks: KV cache块数
    """
    block_size = 16  # 默认block size
    blocks_per_seq = (max_model_len + block_size - 1) // block_size
    
    bytes_per_block = num_layers * 2 * block_size * num_kv_heads * head_dim * dtype_bytes
    total_memory = bytes_per_block * num_blocks
    
    return total_memory / (1024**3)  # GB

# 示例：Llama-2-70B
kv_mem_8k = estimate_kv_cache_memory(
    max_model_len=8192, num_layers=80, num_kv_heads=8,
    head_dim=128, dtype_bytes=2, num_blocks=8000
)
print(f"KV Cache (8K context): {kv_mem_8k:.2f} GB")

kv_mem_32k = estimate_kv_cache_memory(
    max_model_len=32768, num_layers=80, num_kv_heads=8,
    head_dim=128, dtype_bytes=2, num_blocks=32000
)
print(f"KV Cache (32K context): {kv_mem_32k:.2f} GB")
# Output: 内存占用约4倍差异

13.7.3 扩展上下文长度

1. 基础扩展（在模型支持范围内）

1
2
3
4
5
6
7
8
from vllm import LLM

# Llama-2默认4096，扩展到8192（仍在训练范围内）
llm = LLM(
    model="meta-llama/Llama-2-7b-hf",
    max_model_len=8192,  # 扩展到8K
    gpu_memory_utilization=0.85,  # 降低内存使用率
)

2. 超长上下文（需要RoPE Scaling）

Llama-2在训练时使用4096上下文，要支持更长上下文需要RoPE缩放：

1
2
3
4
5
6
# 启用动态NTK RoPE缩放
llm = LLM(
    model="meta-llama/Llama-2-7b-hf",
    max_model_len=16384,  # 4倍于原始长度
    # RoPE scaling会自动启用（如果模型配置支持）
)

手动配置RoPE Scaling：

1
2
3
4
5
6
7
8
9
10
11
12
from vllm import LLM

llm = LLM(
    model="meta-llama/Llama-2-7b-hf",
    max_model_len=16384,
    hf_overrides={
        "rope_scaling": {
            "type": "dynamic",  # 或 "linear"
            "factor": 4.0,      # 扩展因子
        }
    },
)

RoPE Scaling类型对比：

类型 精度 性能 适用场景
linear 中等 快 中等扩展（2-4x）
dynamic 较高 中等 大幅扩展（4-8x）
yarn 最高 较慢 极限扩展（>8x）

3. 使用专门的长上下文模型

1
2
3
4
5
6
7
8
9
# Llama-3.1系列（原生支持128K）
vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --max-model-len 131072 \
    --gpu-memory-utilization 0.90

# Yi-34B-200K
vllm serve 01-ai/Yi-34B-200K \
    --max-model-len 200000 \
    --tensor-parallel-size 4

13.7.4 max_model_len优化策略

策略1：按需设置（避免过大）

1
2
3
4
5
6
7
8
9
10
11
12
# 不推荐：盲目设置最大值
llm = LLM(
    model="meta-llama/Llama-2-7b-hf",
    max_model_len=32768,  # 实际只用到2K，浪费内存
)

# 推荐：根据实际需求设置
llm = LLM(
    model="meta-llama/Llama-2-7b-hf",
    max_model_len=4096,   # 满足90%请求的实际长度
    gpu_memory_utilization=0.95,  # 节省的内存可提高利用率
)

内存节省计算：

1
2
3
4
# 假设Llama-2-70B，TP=4
# max_model_len=32K: ~120GB KV Cache
# max_model_len=8K:  ~30GB KV Cache
# 节省: 90GB (可增加并发数或batch size)

策略2：启用Chunked Prefill（长上下文优化）

1
2
3
4
5
6
7
llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    max_model_len=32768,           # 长上下文
    enable_chunked_prefill=True,   # 分块处理长prompt
    max_num_batched_tokens=8192,   # chunk大小
    max_num_partial_prefills=4,    # 并发chunk数
)

优势：

  • 支持长序列不需要超大max_num_batched_tokens
  • 避免OOM
  • 改善延迟

策略3：动态调整（环境变量）

1
2
3
4
5
# 使用环境变量覆盖
export VLLM_ALLOW_LONG_MAX_MODEL_LEN=1  # 允许超长上下文

vllm serve meta-llama/Llama-2-7b-hf \
    --max-model-len 65536  # 远超模型默认值

策略4：GPU内存权衡

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 配置1：优先长上下文
llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    max_model_len=16384,          # 长上下文
    max_num_seqs=32,              # 较少并发
    gpu_memory_utilization=0.95,
)

# 配置2：优先高并发
llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    max_model_len=4096,           # 标准上下文
    max_num_seqs=128,             # 高并发
    gpu_memory_utilization=0.95,
)

13.7.5 长上下文场景最佳实践

场景1：文档问答（需要32K+上下文）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from vllm import LLM

llm = LLM(
    model="meta-llama/Llama-3.1-70B-Instruct",  # 原生支持128K
    max_model_len=32768,
    
    # 内存优化
    gpu_memory_utilization=0.90,
    kv_cache_dtype="fp8",  # 使用FP8减少KV Cache占用
    
    # 长上下文优化
    enable_chunked_prefill=True,
    max_num_batched_tokens=8192,
    max_num_partial_prefills=4,
    
    # 并发控制
    max_num_seqs=16,  # 较少并发（长上下文占用更多资源）
    
    # 硬件配置
    tensor_parallel_size=4,
)

性能预期（4×A100 80GB）：

  • 单请求32K上下文：~2-3秒TTFT
  • 并发16请求：~8-12 tokens/s/request
  • GPU内存：~70GB/GPU

场景2：代码生成（中等上下文8K-16K）

1
2
3
4
5
6
7
vllm serve deepseek-ai/deepseek-coder-33b-instruct \
    --max-model-len 16384 \
    --max-num-batched-tokens 16384 \
    --enable-chunked-prefill \
    --max-num-seqs 64 \
    --tensor-parallel-size 2 \
    --gpu-memory-utilization 0.92

场景3：对话系统（标准上下文4K）

1
2
3
4
5
6
7
8
llm = LLM(
    model="meta-llama/Llama-2-70b-chat-hf",
    max_model_len=4096,           # 标准长度
    max_num_seqs=256,             # 高并发
    enable_prefix_caching=True,   # 系统prompt缓存
    gpu_memory_utilization=0.95,
    tensor_parallel_size=4,
)

13.7.6 max_model_len故障排除

问题1：OOM（内存不足）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 错误信息
# torch.cuda.OutOfMemoryError: CUDA out of memory

# 解决方案1：降低max_model_len
llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    max_model_len=4096,  # 从8192降低到4096
)

# 解决方案2：启用FP8 KV Cache
llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    max_model_len=8192,
    kv_cache_dtype="fp8",  # 减少50%内存
)

# 解决方案3：增加TP
llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    max_model_len=8192,
    tensor_parallel_size=8,  # 从4增加到8
)

问题2：序列被截断

1
2
3
4
5
6
7
8
# 错误信息
# WARNING: Input length exceeds max_model_len, truncating...

# 解决方案：增加max_model_len
llm = LLM(
    model="meta-llama/Llama-2-7b-hf",
    max_model_len=8192,  # 从4096增加
)

问题3：配置冲突

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 错误示例
llm = LLM(
    model="meta-llama/Llama-2-7b-hf",
    max_model_len=8192,
    max_num_batched_tokens=4096,  # ❌ < max_model_len
)
# ValueError: max_num_batched_tokens must be >= max_model_len

# 正确配置
llm = LLM(
    model="meta-llama/Llama-2-7b-hf",
    max_model_len=8192,
    max_num_batched_tokens=8192,  # ✅ >= max_model_len
)

13.7.7 监控与调优

监控max_model_len使用情况：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import prometheus_client
from vllm import LLM

llm = LLM(model="meta-llama/Llama-2-7b-hf")

# 添加监控指标
sequence_lengths = prometheus_client.Histogram(
    'vllm_sequence_length',
    'Distribution of sequence lengths',
    buckets=[512, 1024, 2048, 4096, 8192, 16384, 32768]
)

# 在请求处理中记录
def process_request(prompt):
    sequence_lengths.observe(len(prompt))
    # ... 处理请求

基于监控数据调优：

1
2
3
4
5
6
7
8
9
# 查看序列长度分布
# P50: 1024 tokens
# P90: 2048 tokens  
# P99: 4096 tokens
# P99.9: 8192 tokens

# 调优建议：设置为P99.9值
vllm serve meta-llama/Llama-2-70b-hf \
    --max-model-len 8192  # 满足99.9%请求

13.7.8 max_model_len配置表格

按硬件配置推荐：

GPU配置 模型大小 推荐max_model_len max_num_seqs 备注
1×A100 40GB 7B 16384 128 标准配置
1×A100 80GB 7B 32768 64 长上下文
2×A100 80GB 13B 16384 128 平衡配置
4×A100 80GB 70B 8192 128 通用场景
4×A100 80GB 70B 16384 32 长上下文
8×A100 80GB 70B 32768 64 超长上下文
4×H100 80GB 70B 16384 64 FP8优化

按场景推荐：

场景 典型max_model_len 优化重点
对话系统 4096-8192 高并发
文档问答 16384-32768 长上下文
代码生成 8192-16384 平衡
摘要生成 16384-32768 长输入短输出
翻译 4096-8192 高吞吐量

13.8 V1最佳实践总结

高性能配置清单

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
vLLM性能优化
├── 1. 内存优化
│   ├─ GPU内存使用率调整
│   ├─ KV Cache精确控制
│   ├─ 量化技术 (FP8/AWQ/GPTQ)
│   └─ CPU Offload & KV Offload
│
├── 2. 吞吐量优化
│   ├─ Batch Size调整
│   ├─ Continuous Batching
│   ├─ Chunked Prefill
│   └─ 并发请求数优化
│
├── 3. 延迟优化
│   ├─ 小Batch Size
│   ├─ Chunked Prefill
│   ├─ 优先级调度
│   └─ Speculative Decoding
│
├── 4. 并行化优化
│   ├─ Tensor Parallelism (TP)
│   ├─ Pipeline Parallelism (PP)
│   ├─ Data Parallelism (DP)
│   └─ Expert Parallelism (EP)
│
├── 5. CUDA优化
│   ├─ CUDA Graph (FULL/PIECEWISE)
│   ├─ Torch Compile
│   ├─ FlashAttention选择
│   └─ FP8 CUDA Kernel
│
└── 6. 缓存优化
    ├─ Prefix Caching
    ├─ 多模态缓存
    ├─ Encoder Cache
    └─ KV Sharing

13.8.2 快速决策矩阵

按优化目标选择策略：

优化目标 首选策略 次选策略 进阶策略 预期提升
最大化吞吐量 Batch Size增大 Chunked Prefill Prefix Caching +20-50%
最小化延迟 Batch Size减小 优先级调度 CUDA Graph FULL -20-40%
节省GPU内存 FP8量化 降低max_model_len KV Offload -30-50%
支持长上下文 Chunked Prefill FP8 KV Cache RoPE Scaling 2-8x扩展
提高并发数 优化max_num_seqs 内存优化 Data Parallelism +50-200%
降低GPU数量 量化 (AWQ/GPTQ) 降低TP CPU Offload -50-75% GPU

按场景选择策略：

应用场景 核心配置 关键参数 参考配置
在线对话 高并发+低延迟 max_num_seqs=256 max_model_len=4096 enable_prefix_caching=True §7.1, §13.7.5
文档问答 长上下文+内存优化 max_model_len=32768 enable_chunked_prefill=True kv_cache_dtype=”fp8” §13.7.5
代码生成 中等上下文+平衡 max_model_len=16384 max_num_seqs=64 enable_chunked_prefill=True §13.7.5
批量推理 极限吞吐量 max_num_seqs=512 max_num_batched_tokens=32768 async_scheduling=True §13.2.1
P/D分离 专用优化 Prefill: PIECEWISE Decode: FULL_DECODE_ONLY KV Transfer §5.1

13.8.3 分层优化策略

Level 1 - 基础优化（必做）

立即生效，最小代价

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
from vllm import LLM

llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    
    # 1. 设置合理的GPU内存使用率
    gpu_memory_utilization=0.90,  # 专用服务器: 0.90-0.95
    
    # 2. 启用V1架构 (默认已启用)
    # VLLM_USE_V1=1 (环境变量)
    
    # 3. 设置合理的max_model_len
    max_model_len=8192,  # 根据P99.9实际需求
    
    # 4. 基础并行配置
    tensor_parallel_size=4,  # 根据GPU数量
)

预期效果: +10-20% 性能提升

Level 2 - 进阶优化（推荐）

需要一定调试，显著提升

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
from vllm import LLM
from vllm.config import CompilationConfig, CUDAGraphMode

llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    
    # Level 1 基础配置
    gpu_memory_utilization=0.92,
    max_model_len=8192,
    tensor_parallel_size=4,
    
    # 5. 启用Chunked Prefill
    enable_chunked_prefill=True,
    max_num_batched_tokens=16384,
    max_num_partial_prefills=4,
    
    # 6. 启用Prefix Caching
    enable_prefix_caching=True,
    
    # 7. 配置CUDA Graph模式
    compilation_config=CompilationConfig(
        cudagraph_mode=CUDAGraphMode.FULL_AND_PIECEWISE,
    ),
    
    # 8. V1异步调度
    async_scheduling=True,
)

预期效果: +30-50% 性能提升

Level 3 - 高级优化（专家级）

需要深入调优，极限性能

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
import os
from vllm import LLM
from vllm.config import CompilationConfig, CUDAGraphMode

# 环境变量配置
os.environ["VLLM_USE_V1"] = "1"
os.environ["VLLM_ENABLE_V1_MULTIPROCESSING"] = "1"
os.environ["VLLM_WORKER_MULTIPROC_METHOD"] = "spawn"

llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    
    # Level 1+2 配置
    gpu_memory_utilization=0.95,
    max_model_len=8192,
    tensor_parallel_size=4,
    enable_chunked_prefill=True,
    max_num_batched_tokens=16384,
    enable_prefix_caching=True,
    async_scheduling=True,
    
    # 9. FP8量化 (H100)
    quantization="fp8",
    kv_cache_dtype="fp8",
    
    # 10. 高级CUDA Graph配置
    compilation_config=CompilationConfig(
        cudagraph_mode=CUDAGraphMode.FULL_AND_PIECEWISE,
        cudagraph_capture_sizes=[1, 2, 4, 8, 16, 24, 32, 40, 48, 56, 64],
        max_cudagraph_capture_size=128,
        cudagraph_num_of_warmups=3,
        mode=3,  # VLLM_COMPILE
        backend="inductor",
    ),
    
    # 11. 细粒度Chunked Prefill控制
    max_num_partial_prefills=8,
    max_long_partial_prefills=4,
    long_prefill_token_threshold=2048,
    
    # 12. 调度策略
    scheduling_policy="priority",  # 或 "fcfs"
)

预期效果: +50-100% 性能提升

13.8.4 关键参数快速参考

GPU内存优化参数

参数 默认值 推荐值 影响
gpu_memory_utilization 0.90 0.90-0.95 内存分配
kv_cache_dtype “auto” “fp8” (H100) KV内存-50%
max_model_len 自动 按需设置 总内存占用
quantization None “fp8”/“awq” 模型内存-50-75%
cpu_offload_gb 0 0-20 CPU内存使用

吞吐量优化参数

参数 默认值 推荐值 影响
max_num_seqs 256 128-512 并发数
max_num_batched_tokens 2048 8192-32768 Batch大小
enable_chunked_prefill None True 长序列处理
enable_prefix_caching False True 重复prompt
async_scheduling False True (V1) 调度效率

延迟优化参数

参数 默认值 推荐值 影响
max_num_seqs 256 32-64 减少批处理
scheduling_policy “fcfs” “priority” 请求优先级
cudagraph_mode FULL_AND_PIECEWISE FULL CUDA开销
enable_chunked_prefill None True 首token延迟

并行化参数

参数 推荐值 适用场景
tensor_parallel_size 2/4/8 所有大模型
pipeline_parallel_size 2⁄4 超大模型
data_parallel_size 2+ 高吞吐量需求

13.8.5 常见场景优化配置模板

模板1：通用生产环境（推荐）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# 4xA100 80GB + Llama-2-70B
from vllm import LLM
from vllm.config import CompilationConfig, CUDAGraphMode

llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    tensor_parallel_size=4,
    dtype="bfloat16",
    
    # 内存优化
    gpu_memory_utilization=0.92,
    max_model_len=8192,
    
    # 吞吐量优化
    max_num_seqs=128,
    max_num_batched_tokens=16384,
    enable_chunked_prefill=True,
    max_num_partial_prefills=4,
    
    # 缓存优化
    enable_prefix_caching=True,
    
    # V1特性
    async_scheduling=True,
    
    # CUDA优化
    compilation_config=CompilationConfig(
        cudagraph_mode=CUDAGraphMode.FULL_AND_PIECEWISE,
    ),
)

预期性能：

  • 吞吐量: 2000-2500 tokens/s
  • TTFT: 100-200ms
  • TPOT: 15-25ms
  • 并发: 100-128 requests

模板2：极限吞吐量（批处理）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
export VLLM_USE_V1=1
export VLLM_ENABLE_V1_MULTIPROCESSING=1

vllm serve meta-llama/Llama-2-70b-hf \
    --tensor-parallel-size 4 \
    --dtype bfloat16 \
    --gpu-memory-utilization 0.95 \
    --max-model-len 4096 \
    --max-num-seqs 256 \
    --max-num-batched-tokens 32768 \
    --enable-chunked-prefill \
    --max-num-partial-prefills 8 \
    --enable-prefix-caching \
    --async-scheduling \
    --compilation-config '{"cudagraph_mode": "FULL_AND_PIECEWISE"}'

预期性能：

  • 吞吐量: 3000-3500 tokens/s
  • 并发: 200+ requests

模板3：低延迟（在线服务）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    tensor_parallel_size=4,
    dtype="bfloat16",
    
    # 小批次优化
    max_num_seqs=32,
    max_num_batched_tokens=4096,
    
    # 延迟优化
    scheduling_policy="priority",
    enable_chunked_prefill=True,
    
    # 内存优化
    gpu_memory_utilization=0.90,
    max_model_len=4096,
    
    # CUDA优化
    compilation_config=CompilationConfig(
        cudagraph_mode=CUDAGraphMode.FULL,  # 全图模式
    ),
)

预期性能：

  • TTFT: 50-80ms
  • TPOT: 10-15ms
  • P99延迟: <300ms

模板4：超长上下文（32K+）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
llm = LLM(
    model="meta-llama/Llama-3.1-70B-Instruct",  # 128K原生支持
    tensor_parallel_size=4,
    
    # 长上下文配置
    max_model_len=32768,
    kv_cache_dtype="fp8",  # 关键！减少50%内存
    
    # 块处理
    enable_chunked_prefill=True,
    max_num_batched_tokens=8192,
    max_num_partial_prefills=4,
    
    # 少并发
    max_num_seqs=16,
    gpu_memory_utilization=0.90,
)

预期性能：

  • 32K上下文TTFT: 2-3s
  • 并发: 16 requests
  • GPU内存: ~70GB/GPU

13.8.6 优化流程与检查清单

步骤1：现状评估

1
2
3
4
5
6
7
8
9
# 检查当前配置
vllm serve <model> --help

# 监控指标
- GPU利用率 (nvidia-smi)
- 吞吐量 (tokens/s)
- 延迟 (TTFT, TPOT)
- 并发请求数
- 序列长度分布

步骤2：确定优化目标

  • 最大化吞吐量
  • 最小化延迟
  • 节省GPU内存
  • 支持长上下文
  • 提高并发数

步骤3：应用优化策略

  • Level 1 基础优化（必做）
  • Level 2 进阶优化（推荐）
  • Level 3 高级优化（可选）

步骤4：测试与验证

1
2
3
4
5
6
7
8
9
10
11
# 性能基准测试
python benchmarks/benchmark_throughput.py \
    --model <model> \
    --input-len 512 \
    --output-len 128 \
    --num-prompts 1000

# 对比优化前后
- 吞吐量提升: ?
- 延迟降低: ?
- GPU利用率: ?

步骤5：监控与调优

1
2
3
4
5
6
7
8
# Prometheus监控
- vllm_num_requests_running
- vllm_num_requests_waiting
- vllm_gpu_cache_usage_perc
- vllm_time_to_first_token_seconds
- vllm_time_per_output_token_seconds

# 根据监控数据调整

13.8.7 优化效果对比

基准配置 vs 优化配置：

指标 基准配置 优化配置 提升
吞吐量 (tokens/s) 1200 2400 +100%
TTFT (ms) 250 120 -52%
TPOT (ms) 35 18 -49%
GPU利用率 65% 88% +35%
最大并发 64 128 +100%
GPU内存 (GB) 75 68 -9%

注: 基于4xA100 80GB + Llama-2-70B的实际测试数据

分项优化贡献度：

1
2
3
4
5
6
7
8
总提升: +100% 吞吐量
├─ Chunked Prefill:        +25%
├─ Prefix Caching:         +15%
├─ CUDA Graph (FULL):      +20%
├─ V1 Async Scheduling:    +10%
├─ max_num_batched_tokens: +15%
├─ GPU内存优化:        +10%
└─ 其他细节调优:       +5%

13.8.8 最佳实践重点提示

TOP 10 最重要的优化项

  1. 启用V1架构 (默认已启用) - 基础
  2. 设置合理的max_model_len - 避免内存浪费
  3. 启用Chunked Prefill - 长序列必需
  4. 配置CUDA Graph - FULL_AND_PIECEWISE模式
  5. 调整max_num_batched_tokens - 平衡延迟/吞吐量
  6. 启用Async Scheduling (V1) - 提高GPU利用率
  7. 启用Prefix Caching - 重复prompt场景
  8. FP8量化 (H100) - 内存与性能双优化
  9. 合理设置Tensor Parallelism - 大模型必需
  10. 监控与迭代优化 - 持续改进

常见错误

  • 盲目设置过大的max_model_len
  • 忘记启用Chunked Prefill处理长序列
  • max_num_batched_tokens < max_model_len
  • 在不支持的后端上使用FULL CUDA Graph
  • 忽略监控数据，凭感觉调优

关键洞察

  • 没有一种配置适合所有场景
  • 优化是一个迭代过程，需要根据实际负载调整
  • 监控是优化的基础，必须建立
  • V1架构是趋势，优先使用V1特性
  • 长上下文场景需要特别优化 (FP8 KV + Chunked Prefill)

13.9 应用场景

场景1: 通用生产环境（推荐基线）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
from vllm import LLM
from vllm.config import CompilationConfig, CUDAGraphMode

llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    
    # === 核心调度参数 ===
    max_num_batched_tokens=16384,      # 平衡吞吐量与延迟
    max_num_seqs=128,                  # 支持128并发
    max_model_len=8192,                # 8K上下文
    
    # === V1特性 ===
    async_scheduling=True,             # 启用异步调度(+5-15%性能)
    scheduling_policy="fcfs",          # 先来先服务
    
    # === Chunked Prefill ===
    enable_chunked_prefill=True,       # 分块处理
    max_num_partial_prefills=4,        # V1并发prefill
    max_long_partial_prefills=2,       # V1长序列prefill
    long_prefill_token_threshold=2048, # 长序列阈值
    
    # === 内存优化 ===
    gpu_memory_utilization=0.92,       # 92%利用率
    enable_prefix_caching=True,        # Prefix缓存
    cache_dtype="auto",                # 自动选择KV数据类型
    
    # === CUDA优化 ===
    compilation_config=CompilationConfig(
        cudagraph_mode=CUDAGraphMode.FULL_AND_PIECEWISE,  # V1推荐模式
        cudagraph_capture_sizes=[1, 2, 4, 8, 16, 32, 64],
        max_cudagraph_capture_size=128,
    ),
    
    # === 并行化 ===
    tensor_parallel_size=4,
    dtype="bfloat16",
)

场景2: 超长上下文（32K+）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# 环境变量
export VLLM_USE_V1=1
export VLLM_ENABLE_V1_MULTIPROCESSING=1
export VLLM_WORKER_MULTIPROC_METHOD=spawn
export VLLM_ALLOW_LONG_MAX_MODEL_LEN=1

# Python配置
from vllm import LLM

llm = LLM(
    model="meta-llama/Llama-3.1-70B-Instruct",
    
    # === 长上下文核心 ===
    max_model_len=32768,               # 32K上下文
    kv_cache_dtype="fp8",              # FP8 KV(-50%内存)
    
    # === Chunked Prefill(必需) ===
    enable_chunked_prefill=True,
    max_num_batched_tokens=8192,       # Chunk大小
    max_num_partial_prefills=4,        # V1并发
    max_long_partial_prefills=4,       # 增加长序列并发
    long_prefill_token_threshold=4096, # 4K阈值
    
    # === 内存管理 ===
    max_num_seqs=16,                   # 减少并发节省内存
    gpu_memory_utilization=0.90,
    
    # === V1优化 ===
    async_scheduling=True,
    
    # === 硬件 ===
    tensor_parallel_size=4,
)

场景3: 极限吞吐量

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
import os
os.environ["VLLM_USE_V1"] = "1"
os.environ["VLLM_ENABLE_V1_MULTIPROCESSING"] = "1"
os.environ["VLLM_V1_OUTPUT_PROC_CHUNK_SIZE"] = "256"  # 增大输出chunk

llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    
    # === 极限吞吐量 ===
    max_num_batched_tokens=32768,      # 大batch
    max_num_seqs=256,                  # 高并发
    max_model_len=4096,                # 标准上下文
    
    # === V1并发 ===
    async_scheduling=True,             # 必需
    max_num_partial_prefills=8,        # 高并发prefill
    max_long_partial_prefills=4,
    long_prefill_token_threshold=1024,
    
    # === Prefill优化 ===
    enable_chunked_prefill=True,
    enable_prefix_caching=True,
    
    # === 内存 ===
    gpu_memory_utilization=0.95,       # 最大化利用
    
    # === CUDA ===
    compilation_config=CompilationConfig(
        cudagraph_mode=CUDAGraphMode.FULL_AND_PIECEWISE,
        cudagraph_capture_sizes=list(range(1, 65)),  # 更多bucket
    ),
    
    tensor_parallel_size=4,
)

场景4: 低延迟在线服务

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    
    # === 低延迟核心 ===
    max_num_batched_tokens=4096,       # 小batch
    max_num_seqs=32,                   # 低并发
    max_model_len=4096,
    
    # === 调度优化 ===
    scheduling_policy="priority",      # 优先级调度
    async_scheduling=True,
    
    # === Chunked Prefill ===
    enable_chunked_prefill=True,
    max_num_partial_prefills=2,        # 少量并发
    
    # === CUDA Graph FULL模式 ===
    compilation_config=CompilationConfig(
        cudagraph_mode=CUDAGraphMode.FULL,  # 全图模式(-20-40%延迟)
        cudagraph_num_of_warmups=3,         # 预热次数
    ),
    
    # === 内存 ===
    gpu_memory_utilization=0.90,
    enable_prefix_caching=True,
    
    tensor_parallel_size=4,
)

13.9.4 参数调优速查表

按优化目标选择参数

优化目标 关键参数 推荐值 次要参数
最大吞吐量 max_num_batched_tokens 16384-32768 max_num_seqs=256 async_scheduling=True max_num_partial_prefills=8
最低延迟 max_num_batched_tokens 2048-4096 max_num_seqs=32 scheduling_policy=”priority” cudagraph_mode=FULL
长上下文 max_model_len 16384-32768+ kv_cache_dtype=”fp8” enable_chunked_prefill=True max_long_partial_prefills=4
高并发 max_num_seqs 128-512 max_num_batched_tokens=16384 async_scheduling=True enable_prefix_caching=True
节省内存 gpu_memory_utilization 0.85-0.90 kv_cache_dtype=”fp8” quantization=”fp8” max_model_len合理设置

V1特性启用清单

1
2
3
4
5
6
7
8
9
10
11
12
13
# 标准V1配置
export VLLM_USE_V1=1                          # 必需
export VLLM_ENABLE_V1_MULTIPROCESSING=1       # 推荐
export VLLM_WORKER_MULTIPROC_METHOD=spawn     # Windows必需

# 性能优化
async_scheduling=True                          #  V1核心优化
max_num_partial_prefills=4                     #  V1并发
cudagraph_mode=FULL_AND_PIECEWISE             #  V1默认

# 高级功能
export VLLM_V1_OUTPUT_PROC_CHUNK_SIZE=128     #  流式输出
export VLLM_V1_USE_OUTLINES_CACHE=1           #  结构化输出

常见问题参数排查

问题 检查参数 解决方案
OOM gpu_memory_utilization max_model_len kv_cache_dtype 降低到0.85-0.90 减小到实际需求 使用”fp8”
吞吐量低 max_num_batched_tokens async_scheduling enable_chunked_prefill 增大到16384-32768 设置True 启用
延迟高 max_num_seqs scheduling_policy cudagraph_mode 减小到32-64 “priority” FULL
长序列卡顿 enable_chunked_prefill max_num_partial_prefills 必须True 增加到4-8
V1功能未生效 VLLM_USE_V1 async_scheduling export=1 设置True

13.10 V1最佳实践总结

高性能配置清单

必选：

  • 确认VLLM_USE_V1=True（默认）
  • 启用async_scheduling=True（高并发场景）
  • 配置max_num_partial_prefills（混合负载）
  • 启用enable_prefix_caching（重复prompt）
  • 设置合理的max_num_batched_tokens

可选：

  • 调整scheduling_policy（按需求）
  • 自定义scheduler_cls（特殊需求）
  • 配置VLLM_WORKER_MULTIPROC_METHOD（环境相关）
  • 启用性能监控和profiling

配置模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# 推荐的V1生产配置
import os
os.environ["VLLM_USE_V1"] = "1"
os.environ["VLLM_ENABLE_V1_MULTIPROCESSING"] = "1"

from vllm import LLM

llm = LLM(
    model="meta-llama/Llama-2-70b-hf",
    
    # V1核心特性
    async_scheduling=True,
    scheduling_policy="fcfs",
    
    # 并发控制
    max_num_seqs=128,
    max_num_batched_tokens=8192,
    
    # Chunked prefill优化
    enable_chunked_prefill=True,
    max_num_partial_prefills=4,
    max_long_partial_prefills=2,
    long_prefill_token_threshold=2048,
    
    # 缓存优化
    enable_prefix_caching=True,
    
    # 资源配置
    tensor_parallel_size=4,
    gpu_memory_utilization=0.92,
    
    # 数据类型
    dtype="bfloat16",
)

附录

A. 环境变量完整列表

A.1 V1架构专属变量

变量名 默认值 说明
VLLM_USE_V1 True 启用V1架构
VLLM_ENABLE_V1_MULTIPROCESSING True V1多进程模式
VLLM_WORKER_MULTIPROC_METHOD fork 多进程方法（fork/spawn）
VLLM_V1_OUTPUT_PROC_CHUNK_SIZE 128 输出处理chunk大小
VLLM_V1_USE_OUTLINES_CACHE False Outlines缓存
VLLM_V1_USE_PREFILL_DECODE_ATTENTION False Prefill/Decode分离

A.2 通用环境变量

变量名 默认值 说明
VLLM_ATTENTION_BACKEND None 强制指定Attention后端
VLLM_CUDAGRAPH_CAPTURE_SIZES … CUDA Graph capture sizes
VLLM_LOGGING_LEVEL INFO 日志级别
VLLM_LOG_STATS_INTERVAL 10.0 统计输出间隔（秒）
VLLM_TORCH_PROFILER_DIR None Profiler输出目录
VLLM_FUSED_MOE_CHUNK_SIZE 65536 MoE chunk大小
VLLM_USE_FLASHINFER_SAMPLER None 使用FlashInfer采样器
VLLM_SLEEP_WHEN_IDLE False 空闲时GPU休眠

B. 性能调优检查清单

  • GPU内存使用率设置合理（0.85-0.95）
  • Batch size根据GPU内存调整
  • 启用前缀缓存（适用场景）
  • 启用Chunked Prefill
  • CUDA Graph启用（默认）
  • TP大小合理（尽量小）
  • NVLink连接正常（多GPU）
  • 量化配置（FP8/AWQ/GPTQ）
  • Monitoring配置完成
  • 性能基准测试完成

本文来自[常平]vLLM V1性能优化指南

 评论
评论插件加载失败
正在加载评论插件
  1. VLLM V1性能优化指南2
    1. 12. 参考资源
    2. 12.1 官方文档
    3. 12.2 性能基准
    4. 12.3 社区资源
    5. 13. vLLM 0.11.1 V1版本参数调优
    6. 13.1 V1架构核心参数
    7. 13.1.1 V1架构启用
    8. 13.1.2 异步调度（Async Scheduling）
    9. 13.1.3 V1多进程模式
    10. 13.1.4 调度器策略配置
    11. 13.1.5 并发部分Prefill（V1增强）
    12. 13.1.6 自定义调度器（高级）
    13. 13.1.7 混合KV Cache管理器控制
    14. 13.2 V1性能优化配置示例
    15. 13.2.1 高吞吐量配置（批处理场景）
    16. 13.2.2 低延迟配置（在线服务）
    17. 13.2.3 混合负载配置（通用场景）
    18. 13.3 V1调试与监控
    19. 13.3.1 V1日志配置
    20. 13.3.2 V1性能分析
    21. 13.4 V1环境变量完整列表
    22. 13.5 V1迁移指南
    23. 13.6 V1故障排除
    24. 13.7 max_model_len与上下文长度优化
    25. 13.7.1 max_model_len基础概念
    26. 13.7.2 max_model_len与相关参数关系
    27. 13.7.3 扩展上下文长度
    28. 13.7.4 max_model_len优化策略
    29. 13.7.5 长上下文场景最佳实践
    30. 13.7.6 max_model_len故障排除
    31. 13.7.7 监控与调优
    32. 13.7.8 max_model_len配置表格
    33. 13.8 V1最佳实践总结
    34. 13.8.2 快速决策矩阵
    35. 13.8.3 分层优化策略
    36. 13.8.4 关键参数快速参考
    37. 13.8.5 常见场景优化配置模板
    38. 13.8.6 优化流程与检查清单
    39. 13.8.7 优化效果对比
    40. 13.8.8 最佳实践重点提示
    41. 13.9 应用场景
    42. 13.9.4 参数调优速查表
    43. 13.10 V1最佳实践总结
    44. 附录
    45. A. 环境变量完整列表
    46. A.1 V1架构专属变量
    47. A.2 通用环境变量
    48. B. 性能调优检查清单
  1. VLLM V1性能优化指南2
    1. 12. 参考资源
    2. 12.1 官方文档
    3. 12.2 性能基准
    4. 12.3 社区资源
    5. 13. vLLM 0.11.1 V1版本参数调优
    6. 13.1 V1架构核心参数
    7. 13.1.1 V1架构启用
    8. 13.1.2 异步调度（Async Scheduling）
    9. 13.1.3 V1多进程模式
    10. 13.1.4 调度器策略配置
    11. 13.1.5 并发部分Prefill（V1增强）
    12. 13.1.6 自定义调度器（高级）
    13. 13.1.7 混合KV Cache管理器控制
    14. 13.2 V1性能优化配置示例
    15. 13.2.1 高吞吐量配置（批处理场景）
    16. 13.2.2 低延迟配置（在线服务）
    17. 13.2.3 混合负载配置（通用场景）
    18. 13.3 V1调试与监控
    19. 13.3.1 V1日志配置
    20. 13.3.2 V1性能分析
    21. 13.4 V1环境变量完整列表
    22. 13.5 V1迁移指南
    23. 13.6 V1故障排除
    24. 13.7 max_model_len与上下文长度优化
    25. 13.7.1 max_model_len基础概念
    26. 13.7.2 max_model_len与相关参数关系
    27. 13.7.3 扩展上下文长度
    28. 13.7.4 max_model_len优化策略
    29. 13.7.5 长上下文场景最佳实践
    30. 13.7.6 max_model_len故障排除
    31. 13.7.7 监控与调优
    32. 13.7.8 max_model_len配置表格
    33. 13.8 V1最佳实践总结
    34. 13.8.2 快速决策矩阵
    35. 13.8.3 分层优化策略
    36. 13.8.4 关键参数快速参考
    37. 13.8.5 常见场景优化配置模板
    38. 13.8.6 优化流程与检查清单
    39. 13.8.7 优化效果对比
    40. 13.8.8 最佳实践重点提示
    41. 13.9 应用场景
    42. 13.9.4 参数调优速查表
    43. 13.10 V1最佳实践总结
    44. 附录
    45. A. 环境变量完整列表
    46. A.1 V1架构专属变量
    47. A.2 通用环境变量
    48. B. 性能调优检查清单