vLLM-05-Config模块-概览

模块职责

Config 模块负责vLLM 的配置管理，包括：

  • 定义各类配置结构（ModelConfig、CacheConfig、ParallelConfig 等）
  • 验证配置参数的合法性
  • 提供配置的序列化和反序列化
  • 支持从命令行参数、环境变量、配置文件加载配置
  • 配置的版本兼容和迁移

核心配置类

VllmConfig（顶层配置）

@dataclass
class VllmConfig:
    """vLLM 顶层配置，聚合所有子配置"""
    model_config: ModelConfig                      # 模型配置
    cache_config: CacheConfig                      # KV Cache 配置
    parallel_config: ParallelConfig                # 并行策略配置
    scheduler_config: SchedulerConfig              # 调度器配置
    device_config: DeviceConfig                    # 设备配置
    load_config: LoadConfig                        # 模型加载配置
    lora_config: Optional[LoRAConfig]              # LoRA 配置
    speculative_config: Optional[SpeculativeConfig] # 推测解码配置
    observability_config: ObservabilityConfig      # 可观测性配置
    compilation_config: Optional[CompilationConfig] # 编译配置

###Model ModelConfig（模型配置）

@dataclass
class ModelConfig:
    """模型相关配置"""
    model: str                          # 模型路径/名称
    tokenizer: Optional[str]            # Tokenizer 路径
    tokenizer_mode: str                 # Tokenizer 模式
    trust_remote_code: bool             # 是否信任远程代码
    dtype: str                          # 数据类型（auto/float16/bfloat16/float32）
    seed: int                           # 随机种子
    max_model_len: Optional[int]        # 最大序列长度
    quantization: Optional[str]         # 量化方式（gptq/awq/fp8）
    enforce_eager: bool                 # 是否强制 eager mode
    max_context_len_to_capture: int     # CUDA Graph 最大长度

关键字段说明：

  • model：HuggingFace 模型名称或本地路径
  • dtype：推理数据类型，auto 根据模型配置自动选择
  • max_model_len：支持的最大序列长度，默认从模型配置读取
  • quantization：量化方式，支持 GPTQ、AWQ、FP8 等

CacheConfig（KV Cache 配置）

@dataclass
class CacheConfig:
    """KV Cache 相关配置"""
    block_size: int                     # Block 大小（tokens）
    gpu_memory_utilization: float       # GPU 内存利用率（0-1）
    swap_space: int                     # CPU swap 空间（GB）
    cache_dtype: str                    # Cache 数据类型
    num_gpu_blocks: Optional[int]       # GPU blocks 数量（profiling 后填充）
    num_cpu_blocks: Optional[int]       # CPU blocks 数量（profiling 后填充）
    enable_prefix_caching: bool         # 是否启用 Prefix Caching
    cpu_offload_gb: float               # CPU offload 大小（GB）

关键字段说明：

  • block_size：PagedAttention 的块大小，默认 16
  • gpu_memory_utilization：GPU 内存利用率，默认 0.9
  • enable_prefix_caching：启用后可复用相同 prefix 的 KV cache

ParallelConfig（并行配置）

@dataclass
class ParallelConfig:
    """并行策略配置"""
    pipeline_parallel_size: int          # 流水线并行大小
    tensor_parallel_size: int            # 张量并行大小
    decode_context_parallel_size: int    # Decode context 并行大小
    data_parallel_size: int              # 数据并行大小
    world_size: int                      # 总 GPU 数量
    rank: int                            # 当前 rank
    distributed_executor_backend: Optional[str]  # 分布式后端（ray/mp）

关键字段说明：

  • tensor_parallel_size：TP 大小，模型切分到多个 GPU
  • pipeline_parallel_size：PP 大小，模型层切分到多个 GPU
  • world_size = TP × PP × DP

SchedulerConfig（调度器配置）

@dataclass
class SchedulerConfig:
    """调度器相关配置"""
    max_num_batched_tokens: int          # 单批最大 token 数
    max_num_seqs: int                    # 最大并发请求数
    max_model_len: int                   # 最大模型长度
    use_v2_block_manager: bool           # 是否使用 V2 block manager
    num_lookahead_slots: int             # Lookahead slots 数量
    delay_factor: float                  # 延迟因子
    enable_chunked_prefill: bool         # 是否启用 Chunked Prefill
    preemption_mode: str                 # 抢占模式（swap/recompute）
    cuda_graph_sizes: list[int]          # CUDA Graph 大小列表

关键字段说明：

  • max_num_seqs：控制并发度，影响吞吐量和延迟
  • enable_chunked_prefill：将长 prompt 分块处理，降低 TTFT
  • preemption_mode：内存不足时的抢占策略

LoRAConfig（LoRA 配置）

@dataclass
class LoRAConfig:
    """LoRA 适配器配置"""
    max_lora_rank: int                   # 最大 LoRA rank
    max_loras: int                       # 最大 LoRA 数量
    max_cpu_loras: Optional[int]         # CPU 缓存的最大 LoRA 数量
    lora_dtype: Optional[str]            # LoRA 数据类型
    lora_extra_vocab_size: int           # LoRA 额外词表大小

ObservabilityConfig（可观测性配置）

@dataclass
class ObservabilityConfig:
    """可观测性配置"""
    otlp_traces_endpoint: Optional[str]  # OpenTelemetry 端点
    collect_model_forward_time: bool     # 是否收集前向传播时间
    collect_model_execute_time: bool     # 是否收集执行时间

配置流程

从 EngineArgs 创建配置

from vllm import EngineArgs

# 1. 创建 EngineArgs
engine_args = EngineArgs(
    model="meta-llama/Llama-2-7b-hf",
    tensor_parallel_size=4,
    dtype="auto",
    max_model_len=4096,
    gpu_memory_utilization=0.9,
    enable_prefix_caching=True,
)

# 2. 生成 VllmConfig
vllm_config = engine_args.create_engine_config()

# 3. 访问子配置
print(vllm_config.model_config.model)            # "meta-llama/Llama-2-7b-hf"
print(vllm_config.parallel_config.tensor_parallel_size)  # 4
print(vllm_config.cache_config.gpu_memory_utilization)   # 0.9

配置验证

def validate_model_config(self):
    """验证 ModelConfig"""
    # 1. 验证 dtype
    if self.dtype not in ["auto", "float16", "bfloat16", "float32"]:
        raise ValueError(f"Invalid dtype: {self.dtype}")
    
    # 2. 验证 max_model_len
    if self.max_model_len is not None:
        if self.max_model_len <= 0:
            raise ValueError("max_model_len must be positive")
    
    # 3. 验证量化配置
    if self.quantization is not None:
        if self.quantization not in ["gptq", "awq", "fp8", "int8"]:
            raise ValueError(f"Unsupported quantization: {self.quantization}")

配置覆盖优先级

优先级从高到低：

  1. 代码中显式设置：EngineArgs(model="...")
  2. 环境变量：VLLM_MODEL_PATH=...
  3. 配置文件：--config config.yaml
  4. 默认值：代码中的默认值

常用配置组合

高吞吐量配置

engine_args = EngineArgs(
    model="meta-llama/Llama-2-7b-hf",
    max_num_seqs=128,                    # 大批量
    max_num_batched_tokens=8192,         # 大 token 批量
    enable_prefix_caching=True,          # 启用 Prefix Caching
    cuda_graph_sizes=[1, 2, 4, 8, 16, 32, 64],  # CUDA Graph
    gpu_memory_utilization=0.95,         # 高内存利用率
)

低延迟配置

engine_args = EngineArgs(
    model="meta-llama/Llama-2-7b-hf",
    max_num_seqs=4,                      # 小批量
    enable_chunked_prefill=True,         # Chunked Prefill（降低 TTFT）
    enable_prefix_caching=True,          # 加速 prompt 处理
    gpu_memory_utilization=0.8,          # 预留内存
)

大模型分布式配置

engine_args = EngineArgs(
    model="meta-llama/Llama-2-70b-hf",
    tensor_parallel_size=4,              # 4-GPU TP
    pipeline_parallel_size=2,            # 2-stage PP
    dtype="bfloat16",                    # 混合精度
    max_model_len=4096,
    gpu_memory_utilization=0.9,
)

量化推理配置

engine_args = EngineArgs(
    model="TheBloke/Llama-2-7B-GPTQ",
    quantization="gptq",                 # GPTQ 量化
    dtype="auto",
    max_model_len=4096,
    gpu_memory_utilization=0.9,
)

配置最佳实践

1. GPU 内存管理

# 推荐：0.85-0.95
gpu_memory_utilization=0.9

# 内存不足时：降低利用率
gpu_memory_utilization=0.7

# 内存充足时：提高利用率
gpu_memory_utilization=0.95

2. 批量大小调优

# 吞吐量优先：增大批量
max_num_seqs=128
max_num_batched_tokens=8192

# 延迟优先：减小批量
max_num_seqs=4
max_num_batched_tokens=2048

# 平衡：中等批量
max_num_seqs=32
max_num_batched_tokens=4096

3. 数据类型选择

# 默认：自动选择
dtype="auto"  # 根据模型配置选择

# FP16：兼容性最好
dtype="float16"

# BF16：数值稳定性更好（需 Ampere+ GPU）
dtype="bfloat16"

# FP32：最高精度（内存消耗大）
dtype="float32"

4. 并行策略选择

# 小模型（< 13B）：单 GPU
tensor_parallel_size=1

# 中等模型（13B-70B）：TP
tensor_parallel_size=4

# 大模型（> 70B）：TP + PP
tensor_parallel_size=4
pipeline_parallel_size=2

# 高并发：DP
data_parallel_size=4

配置文件示例

YAML 配置文件

# vllm_config.yaml
model:
  model: "meta-llama/Llama-2-7b-hf"
  tokenizer: null
  dtype: "auto"
  max_model_len: 4096
  trust_remote_code: false

cache:
  block_size: 16
  gpu_memory_utilization: 0.9
  enable_prefix_caching: true
  swap_space: 4

parallel:
  tensor_parallel_size: 4
  pipeline_parallel_size: 1
  distributed_executor_backend: "ray"

scheduler:
  max_num_seqs: 256
  max_num_batched_tokens: 8192
  enable_chunked_prefill: true
  cuda_graph_sizes: [1, 2, 4, 8, 16, 32]

observability:
  otlp_traces_endpoint: "http://localhost:4317"
  collect_model_forward_time: true

从配置文件加载

import yaml
from vllm import EngineArgs

# 加载配置文件
with open("vllm_config.yaml") as f:
    config_dict = yaml.safe_load(f)

# 创建 EngineArgs
engine_args = EngineArgs(**config_dict)

# 生成 VllmConfig
vllm_config = engine_args.create_engine_config()

环境变量

vLLM 支持通过环境变量覆盖配置：

环境变量 说明 默认值
VLLM_USE_V1 是否使用 V1 架构 1
VLLM_ATTENTION_BACKEND Attention 后端 "FLASH_ATTN"
VLLM_GPU_MEMORY_UTILIZATION GPU 内存利用率 0.9
VLLM_MAX_NUM_SEQS 最大并发请求数 256
VLLM_TENSOR_PARALLEL_SIZE TP 大小 1
VLLM_LOGGING_LEVEL 日志级别 "INFO"

示例：

export VLLM_USE_V1=1
export VLLM_GPU_MEMORY_UTILIZATION=0.95
export VLLM_MAX_NUM_SEQS=128

python your_script.py

总结

Config 模块是 vLLM 的配置中心，提供了：

  1. 统一配置结构：VllmConfig 聚合所有子配置
  2. 灵活配置方式：支持代码、环境变量、配置文件
  3. 配置验证：确保参数合法性
  4. 版本兼容：V0 → V1 平滑迁移

核心配置类：

  • ModelConfig：模型相关配置
  • CacheConfig：KV Cache 配置
  • ParallelConfig：并行策略配置
  • SchedulerConfig：调度器配置
  • LoRAConfig：LoRA 配置

通过合理配置，可以在吞吐量、延迟、内存使用之间取得平衡。