vLLM多模态输入支持：图像、视频与音频处理

vLLM多模态输入支持：图像、视频与音频处理

在生成式 AI 快速演进的今天，大语言模型早已不再局限于“纯文本”的对话。从智能客服看图解答用户问题，到自动驾驶系统理解车载摄像头画面，再到会议助手自动总结音视频内容——多模态能力正成为下一代 AI 应用的核心竞争力。

而作为当前最主流的大语言模型推理引擎之一，vLLM凭借其创新的PagedAttention架构和对连续批处理（continuous batching）的极致优化，不仅在纯文本推理上遥遥领先，在多模态场景下的表现也同样令人瞩目。它已经不再是简单的 LLM 推理加速器，而是逐步演变为一个真正意义上的“多模态计算中枢”。

更重要的是，vLLM 对图像、视频、音频等非结构化数据的支持并非停留在实验阶段，而是具备了完整的生产级特性：从安全控制、缓存复用，到 OpenAI 兼容 API 集成，开发者可以快速构建高性能、高可用的跨模态服务。

离线推理：灵活构建多模态输入

当你在一个本地脚本或微服务中调用 vLLM 时，LLM.generate()是你最常用的入口。通过传入结构化字典，你可以轻松组合文本提示与多种媒体类型。

outputs = llm.generate({ "prompt": "USER: <image>\n这张图片是什么？\nASSISTANT:", "multi_modal_data": {"image": image_pil} })

这里的multi_modal_data字典是关键，键为模态名称（如"image"、"video"、"audio"），值则是对应的数据对象。这种设计既保持了接口的一致性，又为未来扩展新模态（比如点云、3D mesh）留下了空间。

缓存的艺术：UUID 复用与性能跃迁

如果你的应用涉及大量重复请求——比如电商平台需要反复分析同一商品图——那么multi_modal_uuids就是你提升吞吐量的秘密武器。

outputs = llm.generate({ "prompt": prompt, "multi_modal_data": {"image": [img_a, img_b]}, "multi_modal_uuids": {"image": ["product_001_front", "product_001_side"]} })

vLLM 会基于这些 UUID 建立稳定缓存。下次即使你不传图像本身，只要 UUID 匹配，就能直接复用之前提取的视觉特征 embedding：

# 第二次调用，零图像传输，仅靠 UUID 触发缓存命中 outputs = llm.generate({ "prompt": prompt, "multi_modal_data": {"image": [None, None]}, "multi_modal_uuids": {"image": ["product_001_front", "product_001_side"]} })

这在实际部署中意义重大：带宽节省了，GPU 利用率提升了，延迟也更稳定了。当然，前提是你得确保没有关闭前缀缓存或显式禁用媒体处理器缓存（disable_mm_processor_cache=True），否则这套机制将失效。

图像处理：不只是“看”那么简单

图像作为最早成熟的多模态模态，在 vLLM 中的实现也最为完善。无论是单图问答、多图对比，还是透明 PNG 的背景填充，都能找到对应的配置方式。

单图与多图推理

基础用法非常直观：

llm = LLM(model="llava-hf/llava-1.5-7b-hf") image = PIL.Image.open("cherry_blossom.jpg") outputs = llm.generate({ "prompt": "USER: <image>\n描述这幅画。\nASSISTANT:", "multi_modal_data": {"image": image} })

而对于需要比较两张产品图、分析不同视角的任务，则可通过列表传入多个图像，并在 prompt 中使用<image_1>、<image_2>等占位符进行引用：

llm = LLM( model="microsoft/Phi-3.5-vision-instruct", limit_mm_per_prompt={"image": 2} # 显式限制每请求最多2张图 ) outputs = llm.generate({ "prompt": "<|user|><|image_1|><|image_2|>它们有何异同？<|end|><|assistant|>", "multi_modal_data": {"image": [image1, image2]} })

这种方式尤其适合电商、医疗影像等需要并列分析的场景。

使用 chat 接口简化交互逻辑

对于习惯对话格式的开发者，vLLM 提供了LLM.chat()方法，允许以标准 message 数组形式组织输入：

conversation = [ { "role": "user", "content": [ {"type": "image_url", "image_url": {"url": "https://...jpg"}}, {"type": "image_pil", "image_pil": pil_img}, {"type": "text", "text": "这两个图像有什么区别？"} ] } ] outputs = llm.chat(conversation)

这个接口的优势在于语义清晰、易于调试，特别适合集成到前端应用或聊天机器人中。

把视频当“动图”处理：帧序列输入

对于轻量级视频理解任务，一种常见做法是提取关键帧，然后将其视为一组图像输入。例如使用 OpenCV 提取前四帧：

def extract_frames(video_path, max_frames=4): cap = cv2.VideoCapture(video_path) frames = [] while len(frames) < max_frames: ret, frame = cap.read() if not ret: break frame_rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) frames.append(PIL.Image.fromarray(frame_rgb)) cap.release() return frames

随后像处理多图一样传入即可。虽然这种方法无法捕捉时序动态，但在摘要类任务中仍具实用性，且兼容性强，几乎适用于所有视觉语言模型。

控制透明通道的渲染行为

PNG 图像常带有 Alpha 透明通道。默认情况下，vLLM 会用白色填充透明区域，但这可能影响模型判断（比如误以为背景是白墙）。为此，你可以自定义背景色：

llm = LLM( model="llava-hf/llava-1.5-7b-hf", media_io_kwargs={"image": {"rgba_background_color": (0, 102, 204)}} # 品牌蓝 )

支持 RGB 列表[R,G,B]或元组(R,G,B)，取值范围 0–255。这一细节看似微小，但在工业检测、UI 截图分析等对颜色敏感的场景中却至关重要。

原生视频理解：让模型真正“看懂”动态世界

随着 LLaVA-OneVision、Qwen2.5-VL 等模型的出现，vLLM 开始支持原生视频输入。这意味着模型不仅能“看到”画面，还能理解动作、事件和时间演变。

要启用该功能，需将视频 URL 以特定格式嵌入消息：

messages = [ {"role": "user", "content": [ {"type": "text", "text": "请描述这个视频的内容"}, { "type": "video", "video": "https://example.com/demo.mp4", "min_pixels": 16 * 28 * 28, "max_pixels": 20480 * 28 * 28 } ]} ]

注意：process_vision_info是 Qwen 官方提供的工具函数，用于解析此类复合消息。其他模型可能需要自行实现类似逻辑。

启动服务时也要注意资源分配：

vllm serve llava-hf/llava-onevision-qwen2-0.5b-ov-hf --max-model-len 8192

由于视频数据庞大，建议设置合理的超时时间：

export VLLM_VIDEO_FETCH_TIMEOUT=60

这类能力非常适合用于短视频审核、教育内容摘要、安防日志回溯等场景，真正实现了“一句话总结一段视频”的理想。

音频理解：听见声音背后的含义

语音作为信息的重要载体，也在 vLLM 中得到了良好支持。目前主要面向如 Ultravox 这类专为语音增强训练的模型。

输入格式为(array, sampling_rate)元组：

audio_array, sr = sf.read("audio.wav") # shape: (T,), sr: int outputs = llm.generate({ "prompt": "USER: <audio>\n这段话讲了什么？\nASSISTANT:", "multi_modal_data": {"audio": (audio_array, sr)} })

客户端可通过两种方式上传音频：

方式一：Base64 内联上传（input_audio）

适合短语音、实时通话记录等小文件场景：

response = client.chat.completions.create( messages=[{ "role": "user", "content": [ {"type": "text", "text": "音频里说了什么？"}, { "type": "input_audio", "input_audio": {"data": base64_data, "format": "wav"}, "uuid": "call_001" } ] }], model="fixie-ai/ultravox-v0_5-llama-3_2-1b" )

方式二：远程 URL 引用（audio_url）

适合已有存储路径的大文件：

{ "type": "audio_url", "audio_url": {"url": "https://example.com/audio.wav"}, "uuid": "meeting_recording_01" }

默认超时 10 秒，可通过环境变量延长：

export VLLM_AUDIO_FETCH_TIMEOUT=20

这种灵活性使得 vLLM 能够无缝接入电话客服系统、播客分析平台、语音笔记应用等多种业务流程。

直接注入 Embedding：跳过预处理，释放算力

有时候你并不想每次都重新编码图像。比如你的系统已经有 CLIP 或 SigLIP 提取好的视觉特征，这时就可以绕过 vLLM 的视觉编码器，直接注入 embedding。

image_embeds = torch.load("image_embeds.pt") # shape: (1, N, hidden_size) outputs = llm.generate({ "prompt": "USER: <image>\n这是什么？\nASSISTANT:", "multi_modal_data": {"image": image_embeds} })

这对高频调用、低延迟要求的场景极为有利——相当于把昂贵的视觉编码工作前置到了离线流水线中。

但要注意，某些模型还需要额外的元信息才能正确解码：

• Qwen2-VL需要image_grid_thw表示网格结构：

python mm_data = { "image": { "image_embeds": image_embeds, "image_grid_thw": torch.tensor([[1, 3, 3]]) } }

• MiniCPM-V则依赖原始图像尺寸：

python mm_data = { "image": { "image_embeds": image_embeds, "image_sizes": [(512, 512), (768, 512)] } }

这些细节提醒我们：多模态不是“通用即插即用”，而是需要深入理解模型架构与 tokenizer 设计的工程实践。

在线服务：OpenAI 兼容 API 加速落地

vLLM 内置了一个高度兼容 OpenAI 格式的服务器，只需一条命令即可启动一个多模态推理服务：

vllm serve microsoft/Phi-3.5-vision-instruct \ --trust-remote-code \ --max-model-len 4096 \ --limit-mm-per-prompt '{"image": 2}'

此后，任何使用 OpenAI SDK 的客户端都可以无缝对接：

from openai import OpenAI client = OpenAI(api_key="EMPTY", base_url="http://localhost:8000/v1") response = client.chat.completions.create( model="phi-3-vision", messages=[{"role": "user", "content": "..."}] )

这种设计极大降低了迁移成本。许多企业现有的 RAG 系统、Agent 框架、聊天界面只需更换 endpoint，就能获得数倍性能提升。

安全加固：防止 SSRF 与非法访问

开放媒体下载功能的同时，必须防范 SSRF（服务器端请求伪造）攻击。强烈建议通过以下参数限制域名：

--allowed-media-domains upload.wikimedia.org github.com cdn.example.com

并禁用重定向以防跳转至内网地址：

export VLLM_MEDIA_URL_ALLOW_REDIRECTS=0

在容器环境中，进一步限制网络权限：

docker run --network=none ...

或通过 Kubernetes NetworkPolicy 实现微隔离。安全从来不是事后补救，而是从架构设计之初就要考虑的底线。

性能优势与生产适配

vLLM 的成功不仅仅在于功能丰富，更在于其为企业级部署所做的深度优化：

这些能力已在电商图文审核、智能客服、自动驾驶日志分析等多个高并发场景中得到验证。某头部直播平台甚至利用 vLLM 实现了每秒数千次的实时弹幕+画面联合推理，真正做到了“边看边聊”。

多模态时代的大门已经打开。vLLM 不再只是一个推理引擎，而是一个连接文本、图像、声音与视频的“认知枢纽”。它的设计理念告诉我们：未来的 AI 系统不应是单一模态的堆叠，而是多种感知能力的有机融合。

而你要做的，或许只是换一个更强大的后端。