LMDeploy 部署 Qwen2.5-VL 多模态模型实战：安装、离线推理与源码解析

人工智能大模型模型推理服务推理引擎本地部署模型量化【免费下载链接】lmdeployLMDeploy is a toolkit for compressing, deploying, and serving LLMs.项目地址https://gitcode.com/gh_mirrors/lm/lmdeploy点击查看免费下载LMDeploy 通过 PyTorch 推理引擎完整支持 Qwen2.5-VL 系列3B / 7B / 32B / 72B视觉语言模型提供从pipeline离线推理到 OpenAI 兼容api_server在线服务的全链路能力。本文以 Qwen2.5-VL-7B-Instruct 为例带读者掌握环境安装、单图/多图/视频多轮对话的完整用法并结合仓库源码剖析其视觉预处理、图片 token 注入与分辨率控制等底层原理。Qwen2.5-VL 在 LMDeploy 中的支持情况LMDeploy 支持 Qwen-VL 系列模型支持情况如下表所示ModelSizeSupported Inference EngineQwen2.5-VL3B, 7B, 32B, 72BPyTorch从源码结构看Qwen2.5-VL 属于 PyTorch 引擎支持的多模态模型。在 lmdeploy/archs.py 的模型架构注册表中Qwen2_5_VLForConditionalGeneration与Qwen2VLForConditionalGeneration、Qwen3VLForConditionalGeneration等架构一同被识别为可支持的视觉语言模型lmdeploy/vl/model/qwen2.py 中的Qwen2VLModel视觉模型类也通过_arch [Qwen2VLForConditionalGeneration, Qwen2_5_VLForConditionalGeneration]同时承接了 Qwen2-VL 与 Qwen2.5-VL 两类模型的预处理与特征提取逻辑。本文将以 Qwen2.5-VL-7B-Instruct 为例演示使用 LMDeploy 部署 Qwen2.5-VL 系列模型的方法。安装请参考安装文档安装 LMDeploy并安装上游 Qwen2.5-VL 模型库所需的依赖。LMDeploy 默认面向 NVIDIA CUDA 环境编译安装并同时启用 TurboMind 和 PyTorch 两个后端需要 CMake 3.25.2、CUDA 工具包 12.0 与支持 C20 的编译器如 GCC 10Qwen2.5-VL 依赖的是其中的 PyTorch 后端。# Qwen2.5-VL requires the latest transformers (transformers 4.49.0) pip install githttps://github.com/huggingface/transformers # Its highly recommended to use [decord] feature for faster video loading. pip install qwen-vl-utils[decord]0.0.8两点说明transformers 4.49.0Qwen2.5-VL 的Qwen2_5_VLForConditionalGeneration架构与动态分辨率处理器需要较新的 transformers 版本支持因此建议直接从官方仓库安装最新版。[decord]特性qwen-vl-utils 的 decord 扩展用于视频的高效解码处理视频输入时强烈推荐安装。离线推理基础用法以下是使用 pipeline 进行离线推理的示例更多用法参考 VLM 离线推理 pipeline。from lmdeploy import pipeline from lmdeploy.vl import load_image pipe pipeline(Qwen/Qwen2.5-VL-7B-Instruct) image load_image(https://raw.githubusercontent.com/open-mmlab/mmdeploy/main/tests/data/tiger.jpeg) response pipe((fdescribe this image, image)) print(response)这里的pipe接受(prompt, image)元组形式的多模态提示词其中load_image由 lmdeploy/vl/utils.py 提供支持从 URL、本地路径或 base64 字符串三种来源加载图片。pipe同样支持 OpenAI 风格的 messages 格式from lmdeploy import pipeline pipe pipeline(Qwen/Qwen2.5-VL-7B-Instruct) prompts [ { role: user, content: [ {type: text, text: describe this image}, {type: image_url, image_url: {url: https://raw.githubusercontent.com/open-mmlab/mmdeploy/main/tests/data/tiger.jpeg}} ] } ] response pipe(prompts) print(response)两种写法底层等价collect_multimodal_items会从 messages 中抽取所有type非text的多模态条目及其参数见 lmdeploy/vl/model/base.py随后统一交给视觉处理器完成特征提取。多图多轮对话Qwen2.5-VL 支持同时输入多张图片并在此基础上进行多轮追问。实现方式与纯文本多轮对话一致把每轮的输出追加回 messages再继续调用 pipeline。from lmdeploy import pipeline, GenerationConfig pipe pipeline(Qwen/Qwen2.5-VL-7B-Instruct, log_levelINFO) messages [ dict(roleuser, content[ dict(typetext, textDescribe the two images in detail.), dict(typeimage_url, image_urldict(urlhttps://raw.githubusercontent.com/QwenLM/Qwen-VL/master/assets/mm_tutorial/Beijing_Small.jpeg)), dict(typeimage_url, image_urldict(urlhttps://raw.githubusercontent.com/QwenLM/Qwen-VL/master/assets/mm_tutorial/Chongqing_Small.jpeg)) ]) ] out pipe(messages, gen_configGenerationConfig(top_k1)) messages.append(dict(roleassistant, contentout.text)) messages.append(dict(roleuser, contentWhat are the similarities and differences between these two images.)) out pipe(messages, gen_configGenerationConfig(top_k1))要点messages中content为列表文本与图片条目按顺序排列多张图片只需追加多个image_url条目GenerationConfig(top_k1)表示贪心解码让首轮回答尽量稳定便于后续轮次在其基础上继续提问多图场景下输入 token 数会显著增多若上下文较长通常需要配合增大session_len可参考 VLM 离线推理 pipeline 中PytorchEngineConfig(session_len...)的用法。控制图片分辨率加速推理Qwen2.5-VL 采用动态分辨率视觉编码动态 patch 切分图片会按min_pixels/max_pixels约束被切分为多个 28×28 的 patch。通过收窄像素范围可以显著减少视觉 token 数量从而加速推理、降低显存占用from lmdeploy import pipeline, GenerationConfig pipe pipeline(Qwen/Qwen2.5-VL-7B-Instruct, log_levelINFO) min_pixels 64 * 28 * 28 max_pixels 64 * 28 * 28 messages [ dict(roleuser, content[ dict(typetext, textDescribe the two images in detail.), dict(typeimage_url, image_urldict(min_pixelsmin_pixels, max_pixelsmax_pixels, urlhttps://raw.githubusercontent.com/QwenLM/Qwen-VL/master/assets/mm_tutorial/Beijing_Small.jpeg)), dict(typeimage_url, image_urldict(min_pixelsmin_pixels, max_pixelsmax_pixels, urlhttps://raw.githubusercontent.com/QwenLM/Qwen-VL/master/assets/mm_tutorial/Chongqing_Small.jpeg)) ]) ] out pipe(messages, gen_configGenerationConfig(top_k1)) messages.append(dict(roleassistant, contentout.text)) messages.append(dict(roleuser, contentWhat are the similarities and differences between these two images.)) out pipe(messages, gen_configGenerationConfig(top_k1))这里min_pixels max_pixels 64 * 28 * 28表示将图片分辨率固定为恰好 64 个 28×28 patch 对应的像素规模。从源码看这两个参数正是视觉预处理器真正消费的字段在 lmdeploy/vl/model/qwen2.py 的preprocess中optional_keys {min_pixels, max_pixels}会从图片条目参数中提取这两个键并透传给 HF 的image_processor随后merge_length merge_size ** 2每个图片产生的视觉 token 数为image_grid_thw.prod(dim1) // merge_length。也就是说图片切分的 patch 数量直接决定视觉 token 数量而视觉 token 会进一步膨胀输入序列——收窄min_pixels/max_pixels即从源头压缩序列长度。视频多轮对话Qwen2.5-VL 的视频理解本质上是对视频抽帧后逐帧按图片处理。下面示例使用 decord 按时间均匀抽取 8 帧将每帧以 base64 图片形式传入并在首轮让模型逐帧描述、次轮要求整体总结实现视频的多轮对话import numpy as np from lmdeploy import pipeline, GenerationConfig from decord import VideoReader, cpu from lmdeploy.vl.constants import IMAGE_TOKEN from lmdeploy.vl import encode_image_base64 from PIL import Image pipe pipeline(Qwen/Qwen2.5-VL-7B-Instruct, log_levelINFO) def get_index(bound, fps, max_frame, first_idx0, num_segments32): if bound: start, end bound[0], bound[1] else: start, end -100000, 100000 start_idx max(first_idx, round(start * fps)) end_idx min(round(end * fps), max_frame) seg_size float(end_idx - start_idx) / num_segments frame_indices np.array([ int(start_idx (seg_size / 2) np.round(seg_size * idx)) for idx in range(num_segments) ]) return frame_indices def load_video(video_path, boundNone, num_segments32): vr VideoReader(video_path, ctxcpu(0), num_threads1) max_frame len(vr) - 1 fps float(vr.get_avg_fps()) pixel_values_list, num_patches_list [], [] frame_indices get_index(bound, fps, max_frame, first_idx0, num_segmentsnum_segments) imgs [] for frame_index in frame_indices: img Image.fromarray(vr[frame_index].asnumpy()).convert(RGB) imgs.append(img) return imgs video_path red-panda.mp4 imgs load_video(video_path, num_segments8) question for i in range(len(imgs)): question question fFrame{i1}: {IMAGE_TOKEN}\n question What is the red panda doing? content [{type: text, text: question}] for img in imgs: content.append({type: image_url, image_url: {max_dynamic_patch: 1, url: fdata:image/jpeg;base64,{encode_image_base64(img)}}}) messages [dict(roleuser, contentcontent)] out pipe(messages, gen_configGenerationConfig(top_k1)) messages.append(dict(roleassistant, contentout.text)) messages.append(dict(roleuser, contentDescribe this video in detail. Don\t repeat.)) out pipe(messages, gen_configGenerationConfig(top_k1))代码拆解IMAGE_TOKEN定义在 lmdeploy/vl/constants.py值为IMAGE_TOKEN是 LMDeploy 统一使用的图片占位符。默认情况下 LMDeploy 会根据对话模板自动把图片 token 插入 user prompt但在视频抽帧这种需要把 token 与帧一一对应的场景手动拼接更可控。encode_image_base64见 lmdeploy/vl/utils.py把 PIL 图片编码为 base64再以data:image/jpeg;base64,...形式作为image_url传入。max_dynamic_patch: 1限制单帧图片最多切分为 1 个动态 patch视频帧序列较长时能有效控制总视觉 token 数。从源码看视频帧最终仍走图片处理通道在Qwen2VLModel.preprocess中每帧图片独立经image_processor得到image_grid_thw并在to_pytorch_auxlmdeploy/vl/model/base.py中把IMAGE_TOKEN按image_tokens数量展开为等长的图片 token id 序列与文本 token 拼接后交给 PyTorch 引擎。面向更多场景的 pipeline 能力除了上述示例VLM 离线推理 pipeline 还系统介绍了可复用到 Qwen2.5-VL 的进阶能力建议按需查阅设置多卡并行 / 上下文长度通过PytorchEngineConfig(tp2, session_len8192)激活张量并行并定制最大上下文窗口自定义采样参数GenerationConfig(top_k40, top_p0.8, temperature0.6)控制生成随机性提示词批处理把多个(prompt, image)元组放入 list 即可一次推理多条请求显式释放 pipeline调用pipe.close()或使用with pipeline(...) as pipe上下文管理器纯语言模型模式对于 Qwen3-VL 等混合模型可只加载语言模型部分Qwen2.5-VL 场景按需参考该文档。在线服务api_server离线 pipeline 之外LMDeploy 还支持将 VLM 部署为 OpenAI 兼容的 RESTful 服务启动方式与参数说明详见 部署 VLM 类 openai 服务。基本用法为lmdeploy serve api_server Qwen/Qwen2.5-VL-7B-Instruct --backend pytorch --server-port 23333常用参数包括--tp张量并行、--session-len最大上下文窗口、--cache-max-entry-countKV cache 内存占比等完整参数可通过lmdeploy serve api_server -h查看。服务启动后即可通过 OpenAI 风格接口以image_url支持 base64或视频帧形式发送多模态请求。多模态消息的字段格式可参考多模态输入文档。源码层面的工作原理小结结合上述示例Qwen2.5-VL 在 LMDeploy 中的完整推理链路可以归纳为架构匹配lmdeploy/archs.py识别Qwen2_5_VLForConditionalGeneration路由到 PyTorch 后端视觉预处理Qwen2VLModel.build_preprocessorlmdeploy/vl/model/qwen2.py从模型仓库加载AutoProcessor并记录image_token与image_token_idpreprocess按min_pixels/max_pixels调用image_processor计算每张图片的image_grid_thw与视觉 token 数token 拼接to_pytorch_aux把 prompt 按IMAGE_TOKEN切段在每个占位处插入等长的图片 token id同时记录每个多模态条目的offset供引擎在正确位置注入视觉特征模型前向视觉特征与文本 embedding 在 lmdeploy/pytorch/models/qwen2_5_vl.py 定义的Qwen2_5_VLForConditionalGeneration含Qwen2_5_PatchEmbed、Qwen2_5_VisionRotaryEmbedding、Qwen2_5_VLPatchMerger等组件中融合配合 mRoPE 位置编码完成多模态生成。注意事项使用本地下载的 Qwen2.5-VL 权重时将示例中的模型名替换为本地目录路径即可若本地目录名与官方不一致导致对话模板匹配失败可通过ChatTemplateConfig(model_name...)显式指定模板视频或高分辨率多图场景输入序列较长务必评估session_len是否足够必要时显式增大若运行示例出现ImportError请按提示补装 transformers、qwen-vl-utils、decord 等依赖本文所述版本与命令均以当前仓库为准Qwen2.5-VL 推理依赖 PyTorch 引擎表中所列为Supported Inference Engine相关引擎参数请以lmdeploy serve api_server -h与安装文档为准。赞分享人工智能大模型模型推理服务推理引擎本地部署模型量化【免费下载链接】lmdeployLMDeploy is a toolkit for compressing, deploying, and serving LLMs.项目地址https://gitcode.com/gh_mirrors/lm/lmdeploy点击查看免费下载相关推荐LMDeploy 部署 Gemma3 多模态模型实战从离线推理 Pipeline 到源码级原理解析LMDeploy 部署 Gemma3 多模态模型实战从离线推理 Pipeline 到源码级原理解析 LMDeploy 已原生支持 Google Gemma3人工智能大模型模型推理服务推理引擎本地部署模型量化终极指南如何用NSC_BUILDER一站式管理你的Switch游戏文件库终极指南如何用NSC_BUILDER一站式管理你的Switch游戏文件库 你是否曾为Switch游戏文件的杂乱无章而烦恼NSP、XCI、NSZ、XCZ等各种人工智能大模型模型推理服务推理引擎本地部署模型量化Escrcpy实用指南图形化Scrcpy多设备镜像与群控Escrcpy实用指南图形化Scrcpy多设备镜像与群控 Escrcpy是一款基于Electron开发的图形化Scrcpy客户端支持多设备同时镜像、广播输入人工智能大模型模型推理服务推理引擎本地部署模型量化上一篇deb-get支持的200软件清单总有一款你需要的工具下一篇Sinon spy.getCall(n) 完全指南按索引精确访问间谍调用的底层实现与实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考