vLLM 内存节省实战在有限显存中跑起大模型的七种配置手段【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm当模型规模超出单机显存时直接加载往往会触发 OOM。vLLM 官方文档docs/configuration/conserving_memory.md系统性地给出了应对方案。本篇以该文档为骨架逐条拆解其推荐的每一类内存削减手段——张量并行、量化、上下文与批大小限制、CUDA Graph 裁剪、缓存大小调整、多模态输入限制与处理器参数调优——并结合仓库源码vllm/config/下的配置定义与环境变量实现说明每个选项在引擎内部的真实作用点帮助读者不仅会用参数还能判断参数生效的边界与默认值。内存都花在了哪里先定位再削减在展开具体手段之前先明确 vLLM 中显存/内存的大头构成这样文档中每个选项对应削减哪一块就一目了然模型权重由模型本身和精度决定对应文档中的 TP分摊与 Quantization压缩两条主线KV cache与上下文长度max_model_len、并发序列数max_num_seqs成正比对应文档的 Context length and batch size 一节CUDA Graph 捕获的静态内存每个捕获的 batch size 都占用一份图内存对应 Reduce CUDA Graphs 一节多模态处理缓存与编码器激活对应 Adjust cache size 与 Multi-modal input limits 两节。张量并行TP把模型切到多张 GPUtensor_parallel_size选项可以把一个模型切分到多张 GPU 上这是大模型装不下时最直接的手段from vllm import LLM llm LLM(modelibm-granite/granite-3.1-8b-instruct, tensor_parallel_size2)原文档给出两条重要注意事项均值得在实际部署中遵守不要在初始化 vLLM 之前手动设置设备索引。如果你在LLM(...)之前调用了torch.accelerator.set_device_index之类的函数可能触发RuntimeError: Cannot re-initialize CUDA in forked subprocess。正确的做法是用CUDA_VISIBLE_DEVICES环境变量控制使用哪些卡让 vLLM 自己完成 CUDA 初始化TP 会放大模型加载时间。启用张量并行后每个进程都会读取整个模型再切分磁盘读取时间随tensor_parallel_size线性增长。针对第二点文档推荐把 checkpoint 预先转换为分片sharded格式可以使用 examples/features/sharded_state/load_sharded_state_offline.py 完成转换。转换本身耗时但转换之后无论 TP 度多大模型加载时间都保持恒定。量化用精度换显存量化模型以更低的精度存储权重直接降低显存占用。vLLM 支持两条路径静态量化模型直接从 Hugging Face Hub 下载已经量化好的 checkpoint文档提到 Red Hat AI 组织提供了多个常用量化模型无需任何额外配置即可加载使用动态量化通过quantization选项在加载时指定量化方式完整支持列表与用法见 量化功能总览。对只关心能不能装下的场景静态量化模型是零成本选项需要自己控制精度/性能权衡时再走quantization动态路线。上下文长度与批大小压 KV cache 的两个旋钮KV cache 是推理期最吃内存的动态部分。文档给出两个直接的限制选项from vllm import LLM llm LLM(modelQwen/Qwen2.5-VL-3B-Instruct, max_model_len2048, max_num_seqs2)max_model_len限制单条请求允许的最大上下文长度。上下文越长每条序列预留的 KV cache 槽位越多max_num_seqs限制调度器同时处理的最大序列数控制并发带来的 KV cache 总量。从源码结构看max_num_seqs还向下游影响 CUDA Graph 的默认捕获范围见下一节因此它是同时压制 KV cache 与图内存的关键参数而不只是一个并发上限。削减 CUDA Graph 占用从裁剪捕获尺寸到彻底禁用vLLM 默认使用 CUDA Graph 优化推理把固定 batch size 下的内核启动序列录制为图回放避开 Python 分发开销但每个捕获尺寸都占一份静态显存。文档给出两级手段。裁剪捕获尺寸通过compilation_config显式指定要捕获哪些 batch size在推理速度与显存之间取舍from vllm import LLM from vllm.config import CompilationConfig, CompilationMode llm LLM( modelmeta-llama/Llama-3.1-8B-Instruct, compilation_configCompilationConfig( modeCompilationMode.VLLM_COMPILE, # 默认会一直捕获到 max_num_seqs cudagraph_capture_sizes[1, 2, 4, 8, 16], ), )如果不指定vLLM 会按 vllm/config/vllm.py 中_set_cudagraph_sizes的默认策略生成捕获列表cudagraph_capture_sizes [1, 2, 4] list(range(8, 256, 8)) list( range(256, max_cudagraph_capture_size 1, 16))其中上限max_cudagraph_capture_size默认为min(max_num_seqs * 2, 512)数据中心级 Blackwell GPU 为 1024再与max_num_batched_tokens取小见 max_cudagraph_capture_size 字段定义。源码注释明确说明该默认上限的设计目的避免在内存紧张的小max_num_seqs场景下 OOM。运行时行为实际 batch 不超过某个捕获尺寸时用最近的图超过最大捕获尺寸则回退到不用 CUDA Graph 的执行路径。此外从 cudagraph_mode 的字段定义 看还可以按更细的粒度控制捕获策略默认的FULL_AND_PIECEWISE对 decode 批捕获完整图、对 prefill 批做分段捕获如果部署的是纯 decode 实例如 P/D 分离中的解码端可选FULL_DECODE_ONLY只捕获 decode 批以节省 prefill 侧的图内存。彻底禁用enforce_eager内存极其紧张时可以完全关掉图捕获from vllm import LLM llm LLM(modelmeta-llama/Llama-3.1-8B-Instruct, enforce_eagerTrue)源码中enforce_eager一旦为真_set_cudagraph_sizes整体跳过捕获逻辑代价是失去图回放带来的启动开销优化。调整缓存大小应对 CPU 内存不足文档区分了两类缓存型内存多模态处理器缓存多模态模型mm_processor_cache_gb控制大小默认 4 GiB。从 vllm/config/multimodal.py 的字段定义看该缓存在每个 API 进程和 engine core 进程中各有一份副本总占用为mm_processor_cache_gb * (api_server_count data_parallel_size)——这一点在开多 API server 或数据并行时尤其要算进预算单个处理项超过该预算时会带警告地不缓存直接服务而不是报错设为0可彻底关闭。CPU KV cache仅 CPU 后端用环境变量VLLM_CPU_KVCACHE_SPACE调整未设置时按 vllm/envs.py 的注释按 4 GiB 处理实际解析逻辑见 vllm/platforms/cpu.py。多模态输入限制limit_mm_per_prompt多模态模型会为每类输入预留处理/编码资源。文档给出三个层级的收敛方式。限制每请求的多模态条目数from vllm import LLM # 每个 prompt 最多接受 3 张图片和 1 个视频 llm LLM( modelQwen/Qwen2.5-VL-3B-Instruct, limit_mm_per_prompt{image: 3, video: 1}, )直接禁用不用的模态设0即可让引擎不为该模态分配任何内存from vllm import LLM # 只接受任意数量的图片完全不接受视频 llm LLM( modelQwen/Qwen2.5-VL-3B-Instruct, limit_mm_per_prompt{video: 0}, )甚至可以让多模态模型跑纯文本推理from vllm import LLM # 不接受图片只处理文本 llm LLM( modelgoogle/gemma-3-27b-it, limit_mm_per_prompt{image: 0}, )可配置尺寸提示按真实业务分布预留激活内存limit_mm_per_prompt的值除了整数还接受每模态的可配置选项。文档给出了各模态的字段形态image:{count: int, width: int, height: int}video:{count: int, num_frames: int, width: int, height: int}audio:{count: int, length: int}对应源码定义在 vllm/config/multimodal.py 的ImageDummyOptions/VideoDummyOptions/AudioDummyOptions。以源码为准可以补充两点细节所有选项的count默认值为 999即不限尺寸字段width/height/num_frames/length默认为None且要求为正数。from vllm import LLM # 每 prompt 最多 5 张图按 512x512 做内存剖析 # 每 prompt 最多 1 个视频按 32 帧、640x640 做内存剖析 llm LLM( modelQwen/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}, }, )兼容性与语义边界文档明确说明整数写法向后兼容{image: 5}等价于{image: {count: 5}}两种形式可以混用尺寸提示只影响内存剖析profiling它们塑造的是用于计算预留激活大小的 dummy 输入不改变推理时真实输入的处理方式提示值超过模型实际能接受的最大值时vLLM 会将其钳制到模型有效最大值并可能打印警告注意边界这些提示目前只作用于激活内存剖析编码器缓存大小由运行时真实输入决定不受这些提示限制。调整多模态处理器参数从源头缩小处理后的输入尺寸对特定模型族可以直接调处理器参数让编码前的多模态特征本身变小从而省下激活与显存from vllm import LLM # 适用于 Qwen2-VL 系列 llm LLM( modelQwen/Qwen2.5-VL-3B-Instruct, mm_processor_kwargs{max_pixels: 768 * 768}, # 默认 1280 * 28 * 28 ) # 适用于 InternVL 系列 llm LLM( modelOpenGVLab/InternVL2-2B, mm_processor_kwargs{max_dynamic_patch: 4}, # 默认 12 )从 mm_processor_kwargs 的字段定义 看它会被原样转发给模型 processor即对transformers.AutoProcessor.from_pretrained加载的 processor 做参数覆盖具体可覆盖哪些键取决于所选模型——例如 Phi-3-Vision 支持{num_crops: 4}。这意味着该选项属于按模型定制的手段先用上面文档中的模型族示例作参照再对照所用模型 processor 的实际参数来设置。小结按内存压力来源选择手段内存压力来源首选选项备注权重装不下单卡tensor_parallel_size注意用CUDA_VISIBLE_DEVICES控卡大 TP 度建议预转分片 checkpoint想进一步压缩权重静态量化模型或quantization以精度为代价KV cache 过大max_model_lenmax_num_seqs两者同时压制 KV cache 与 CUDA Graph 默认范围CUDA Graph 占用高compilation_config.cudagraph_capture_sizes极端时enforce_eager默认捕获到 512Blackwell 1024且随max_num_seqs缩放CPU RAM 不足mm_processor_cache_gb多模态/VLLM_CPU_KVCACHE_SPACECPU 后端前者在每 API/DP 进程中各有一份副本多模态输入太重limit_mm_per_prompt含尺寸提示与mm_processor_kwargs尺寸提示只影响内存剖析不影响运行时处理以上所有代码与参数均出自 官方内存节省文档参数默认值与内部行为可在 vllm/config/compilation.py、vllm/config/multimodal.py、vllm/config/vllm.py 与 vllm/envs.py 中交叉核对。【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考