内存优化¶

大型模型可能会导致您的机器内存不足 (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.cuda.set_device）。否则，您可能会遇到类似 RuntimeError: Cannot re-initialize CUDA in forked subprocess 的错误。

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

注意

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

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

量化¶

量化模型占用内存更少，但精度较低。

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

动态量化也通过 quantization 选项支持——更多细节请参见此处。

上下文长度和批量大小¶

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

from vllm import LLM

llm = LLM(model="adept/fuyu-8b", 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 RAM 不足，请尝试以下选项。

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

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

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 图¶

调整缓存大小¶

多模态输入限制¶

可配置选项¶

多模态处理器参数¶