节约内存¶

大型模型可能会导致您的机器内存不足 (OOM)。以下是一些有助于缓解此问题的选项。

张量并行 (TP)¶

张量并行 (tensor_parallel_size 选项) 可用于将模型拆分到多个 GPU 上。

以下代码将模型拆分到 2 个 GPU 上。

from vllm import LLM

llm = LLM(model="ibm-granite/granite-3.1-8b-instruct", tensor_parallel_size=2)

警告

为确保 vLLM 正确初始化 CUDA，您应该在初始化 vLLM 之前避免调用相关函数（例如 torch.accelerator.set_device_index）。否则，您可能会遇到类似 RuntimeError: Cannot re-initialize CUDA in forked subprocess 的错误。

要控制使用哪些设备，请改为设置 CUDA_VISIBLE_DEVICES 环境变量。

注意

启用张量并行后，每个进程将读取整个模型并将其拆分为块，这使得磁盘读取时间更长（与张量并行的大小成比例）。

您可以使用 examples/features/sharded_state/load_sharded_state_offline.py 将模型检查点转换为分片检查点。转换过程可能需要一些时间，但之后您可以更快地加载分片检查点。模型的加载时间应保持不变，无论张量并行的大小如何。

量化¶

量化模型以降低精度为代价占用更少的内存。

静态量化模型可以从 HF Hub 下载（一些流行的模型可在 Red Hat AI 获取），并直接使用，无需额外配置。

还支持通过 quantization 选项进行动态量化 —— 有关更多详细信息，请参阅此处。

上下文长度和批量大小¶

您可以通过限制模型的上下文长度 (max_model_len 选项) 和最大批量大小 (max_num_seqs 选项) 来进一步减少内存使用。

from vllm import LLM

llm = LLM(model="Qwen/Qwen2.5-VL-3B-Instruct", max_model_len=2048, max_num_seqs=2)

减少 CUDA 图¶

默认情况下，我们使用 CUDA 图优化模型推理，这会占用 GPU 中的额外内存。

您可以调整 compilation_config 以在推理速度和内存使用之间取得更好的平衡

代码

from vllm import LLM
from vllm.config import CompilationConfig, CompilationMode

llm = LLM(
    model="meta-llama/Llama-3.1-8B-Instruct",
    compilation_config=CompilationConfig(
        mode=CompilationMode.VLLM_COMPILE,
        # By default, it goes up to max_num_seqs
        cudagraph_capture_sizes=[1, 2, 4, 8, 16],
    ),
)

您可以通过 enforce_eager 标志完全禁用图捕获

from vllm import LLM

llm = LLM(model="meta-llama/Llama-3.1-8B-Instruct", enforce_eager=True)

调整缓存大小¶

如果您遇到 CPU 内存不足，请尝试以下选项

（仅限多模态模型）您可以通过设置 mm_processor_cache_gb 引擎参数来设置多模态缓存的大小（默认 4 GiB）。
（仅限 CPU 后端）您可以使用 VLLM_CPU_KVCACHE_SPACE 环境变量设置 KV 缓存的大小（默认 4 GiB）。

您可以允许每个提示的多模态项数量更少，以减少模型的内存占用

from vllm import LLM

# Accept up to 3 images and 1 video per prompt
llm = LLM(
    model="Qwen/Qwen2.5-VL-3B-Instruct",
    limit_mm_per_prompt={"image": 3, "video": 1},
)

您可以更进一步，通过将其限制设置为零来完全禁用未使用的模态。例如，如果您的应用程序只接受图像输入，则无需为视频分配任何内存。

from vllm import LLM

# Accept any number of images but no videos
llm = LLM(
    model="Qwen/Qwen2.5-VL-3B-Instruct",
    limit_mm_per_prompt={"video": 0},
)

您甚至可以运行一个多模态模型进行纯文本推理

from vllm import LLM

# Don't accept images. Just text.
llm = LLM(
    model="google/gemma-3-27b-it",
    limit_mm_per_prompt={"image": 0},
)

可配置选项¶

limit_mm_per_prompt 也接受每个模态的可配置选项。在可配置形式中，您仍然可以指定 count，并且可以选择提供大小提示，这些提示控制 vLLM 如何为您的多模态输入进行性能分析和预留内存。这有助于您根据实际期望的媒体调整内存，而不是模型的绝对最大值。

按模态可配置的选项

image: {"count": int, "width": int, "height": int}
video: {"count": int, "num_frames": int, "width": int, "height": int}
audio: {"count": int, "length": int}

详细信息请参阅 ImageDummyOptions、VideoDummyOptions 和 AudioDummyOptions。

示例

from vllm import LLM

# Up to 5 images per prompt, profile with 512x512.
# Up to 1 video per prompt, profile with 32 frames at 640x640.
llm = LLM(
    model="Qwen/Qwen2.5-VL-3B-Instruct",
    limit_mm_per_prompt={
        "image": {"count": 5, "width": 512, "height": 512},
        "video": {"count": 1, "num_frames": 32, "width": 640, "height": 640},
    },
)

为了向后兼容，传递整数仍然有效，并被解释为 {"count": <int>}。例如

limit_mm_per_prompt={"image": 5} 等同于 limit_mm_per_prompt={"image": {"count": 5}}
您可以混合使用格式：limit_mm_per_prompt={"image": 5, "video": {"count": 1, "num_frames": 32, "width": 640, "height": 640}}

注意

大小提示仅影响内存分析。它们用于塑造计算预留激活大小的虚拟输入。它们不改变推理时输入实际的处理方式。
如果提示超出模型可接受的范围，vLLM 会将其限制在模型的有效最大值，并可能记录警告。

警告

这些大小提示目前仅影响激活内存分析。编码器缓存大小由运行时实际输入决定，不受这些提示的限制。

对于某些模型，您可以调整多模态处理器参数，以减少处理后的多模态输入的大小，从而节省内存。

以下是一些示例

from vllm import LLM

# Available for Qwen2-VL series models
llm = LLM(
    model="Qwen/Qwen2.5-VL-3B-Instruct",
    mm_processor_kwargs={"max_pixels": 768 * 768},  # Default is 1280 * 28 * 28
)

# Available for InternVL series models
llm = LLM(
    model="OpenGVLab/InternVL2-2B",
    mm_processor_kwargs={"max_dynamic_patch": 4},  # Default is 12
)

节约内存¶

张量并行 (TP)¶

量化¶

上下文长度和批量大小¶

减少 CUDA 图¶

调整缓存大小¶

多模态输入限制¶

可配置选项¶

多模态处理器参数¶