企业官网建设流程全解析

• 人工智能
• 大模型
• 模型推理服务
• 推理引擎
• 本地部署
• 模型量化

LMDeploy 已原生支持 Google Gemma3 系列多模态模型（1B–27B 参数规模），覆盖文本与图像输入、文本输出场景。本文以官方文档 gemma3.md 为核心骨架，结合仓库内 VLM 推理 Pipeline 用法、视觉模型注册与 PyTorch 后端实现源码，讲解如何在 LMDeploy 中完成 Gemma3 的安装准备、离线多模态推理，以及滑动窗口注意力、视觉塔与多模态投影器等底层机制，帮助你快速上手并理解其部署原理。

Gemma3 模型简介

Gemma 是 Google 基于 Gemini 同源研究与技术构建的轻量级开放模型系列。Gemma3 是其中的多模态版本，具备以下核心特性：

• 多模态能力：同时处理文本与图像输入，输出文本结果，同时提供预训练（pre-trained）与指令微调（instruction-tuned）两种开源权重变体；
• 超长上下文：支持高达 128K token 的上下文窗口；
• 多语言支持：覆盖 140 多种语言；
• 多种尺寸：相比前代提供更多参数量版本（1B–27B）；
• 轻量可部署：适合问答、总结、推理等文本生成与图像理解任务，可在笔记本电脑、桌面端乃至自有云基础设施等资源受限环境中运行。

在 LMDeploy 的 支持模型列表 中，Gemma3 被标记为 MLLM（多模态大语言模型），并支持 PyTorch 后端推理。

快速开始：安装与准备

安装 LMDeploy

按照安装指南完成 LMDeploy 的安装。

部署前准备

部署Gemma3模型前，请安装最新版本的 transformers。这一点至关重要，原因在于 LMDeploy 对 Gemma3 的适配依赖 transformers 的处理器（processor）与模型配置实现：

• 视觉侧通过AutoProcessor.from_pretrained加载 HuggingFace 处理器（见 lmdeploy/vl/model/gemma3_vl.py），并从中读取image_token的 token id 与image_seq_length；
• 文本侧通过build_model_from_hf_config基于 HF 配置构建语言模型（见 lmdeploy/pytorch/models/gemma3_vl.py），老版本 transformers 可能缺少 Gemma3 相关配置字段而导致构建失败。

离线推理 Pipeline：Hello World

LMDeploy 将多模态视觉语言模型（VLM）的推理流程抽象为与 LLM Pipeline 一致、开箱即用的pipeline接口。下面的示例演示了 Gemma3 最基本的图生文推理：

from lmdeploy import pipeline from lmdeploy.vl import load_image if __name__ == "__main__": pipe = pipeline('google/gemma-3-12b-it') image = load_image('https://raw.githubusercontent.com/open-mmlab/mmdeploy/main/tests/data/tiger.jpeg') response = pipe(('describe this image', image)) print(response)

代码要点：

• pipeline('google/gemma-3-12b-it')：传入 HuggingFace 模型仓库路径（或本地模型目录），LMDeploy 自动识别模型架构并选用 PyTorch 后端引擎；
• load_image(...)：加载网络或本地图片，返回可被 pipeline 直接消费的图像对象；
• pipe(('describe this image', image))：推理 prompt 采用(prompt, image)元组结构，其中图片必须放在 prompt 之后。

若执行时出现ImportError，请按照提示安装缺失的依赖包（例如最新版 transformers）。

深入源码：Gemma3 在 LMDeploy 中的实现结构

为了让读者理解上述示例背后的推理链路，下面结合仓库源码剖析 Gemma3 的适配实现。

视觉模型注册与消息预处理

Gemma3 的视觉模型在 lmdeploy/vl/model/gemma3_vl.py 中通过VISION_MODELS.register_module()注册为Gemma3VisionModel，架构名称为Gemma3ForConditionalGeneration：

• build_preprocessor：加载 HF 处理器，提取image_token_id与image_tokens（单图产生的视觉 token 数量）；
• preprocess：调用处理器对图像做缩放、归一化与 crop 预处理，默认关闭 pan-and-scan（do_pan_and_scan=False），相关默认参数包括最小裁剪尺寸 256、最大裁剪数 4、激活比例 1.2（见 Gemma3ProcessorKwargs 定义）；
• proc_messages：将多模态消息中的每张图片替换为\n\n<IMAGE_TOKEN>\n\n占位符后交给 chat template 组装 prompt（见 proc_messages 实现）。

多模态条件生成模型

PyTorch 后端的核心实现位于 lmdeploy/pytorch/models/gemma3_vl.py 的Gemma3ForConditionalGeneration，整体结构由三部分构成：

1. 视觉塔SiglipVisionModel：基于 SigLIP 的视觉编码器（vision_config），负责将pixel_values编码为视觉特征；
2. 多模态投影器Gemma3MultiModalProjector：完成从视觉特征空间到文本嵌入空间的映射。其实现细节包括：先将视觉输出 reshape 为 2D patch 网格，经AvgPool2d平均池化压缩 token 数量，再经 RMSNorm 归一化后与投影权重矩阵相乘（见 Gemma3MultiModalProjector）；
3. 语言模型Gemma3ForCausalLM骨架：由build_model_from_hf_config(text_config, ...)基于text_config构建，负责最终的文本生成。

前向推理时，forward会先计算视觉特征vit_embeds，再通过lang_embeds.masked_scatter_(image_mask[..., None], vit_embeds)将视觉 token 嵌入替换到image_mask标记的位置，从而把图像信息注入语言模型输入（见 forward 实现）。

混合注意力：全局因果掩码 + 1024 滑动窗口

Gemma3 的文本骨干使用了滑动窗口注意力机制。prepare_attn_masks（见 源码实现）同时构造了两套注意力掩码：

• 全局因果掩码（global_attn_masks）：标准的因果下三角掩码，但对图像 token 所在行列额外开放双向注意力（img_mask == 2的位置置 0），使视觉 token 之间可以互相 attend；
• 局部滑动窗口掩码（local_attn_masks）：基于torch.tril(..., diagonal=-self.sliding_window)构造，窗口大小为 1024，窗口外的 token 无法互相 attend，从而降低长序列下的计算与显存开销。

self.sliding_window取自text_config.sliding_window（见 模型构造）。值得注意的是，LMDeploy 的配置构建器在 lmdeploy/pytorch/configurations/gemma.py 中会将cfg.sliding_window显式置为-1，并在GemmaVLModelConfigBuilder.condition中通过architectures[0] == 'Gemma3ForConditionalGeneration'识别 Gemma3 多模态架构，保证推理时混合注意力掩码按预期生效。

输入处理与权重加载

Gemma3VLInputProcessor（见 实现）负责将预处理阶段产生的pixel_values与offset、image_token_id、image_tokens等信息封装为MultiModalData供引擎调度；load_weights（见 实现）则处理权重加载，其中将 HF 的q_proj/k_proj/v_proj分片权重合并为 LMDeploy 的qkv_proj融合参数，语言模型部分权重单独透传。

进阶用法：多图、批量与多轮对话

基于 VLM 离线推理 Pipeline 指南，Gemma3 同样支持以下进阶场景（以下示例中模型名可替换为google/gemma-3-12b-it等 Gemma3 权重）。

多图推理

将多张图片放入一个列表即可一次完成描述：

from lmdeploy import pipeline, TurbomindEngineConfig from lmdeploy.vl import load_image pipe = pipeline('google/gemma-3-12b-it', backend_config=TurbomindEngineConfig(session_len=8192)) image_urls = [ 'https://raw.githubusercontent.com/open-mmlab/mmdeploy/main/demo/resources/human-pose.jpg', 'https://raw.githubusercontent.com/open-mmlab/mmdeploy/main/demo/resources/det.jpg' ] images = [load_image(img_url) for img_url in image_urls] response = pipe(('describe these images', images)) print(response)

多图会显著增加输入 token 数，建议同步调大session_len（上下文窗口长度）。

批量 prompt 推理

将多个(prompt, image)元组放入列表即可批量推理：

from lmdeploy import pipeline, TurbomindEngineConfig from lmdeploy.vl import load_image pipe = pipeline('google/gemma-3-12b-it', backend_config=TurbomindEngineConfig(session_len=8192)) image_urls = [ "https://raw.githubusercontent.com/open-mmlab/mmdeploy/main/demo/resources/human-pose.jpg", "https://raw.githubusercontent.com/open-mmlab/mmdeploy/main/demo/resources/det.jpg" ] prompts = [('describe this image', load_image(img_url)) for img_url in image_urls] response = pipe(prompts) print(response)

多轮对话

使用pipe.chat接口并回传session即可进行多轮图文对话：

from lmdeploy import pipeline, TurbomindEngineConfig, GenerationConfig from lmdeploy.vl import load_image pipe = pipeline('google/gemma-3-12b-it', backend_config=TurbomindEngineConfig(session_len=8192)) image = load_image('https://raw.githubusercontent.com/open-mmlab/mmdeploy/main/demo/resources/human-pose.jpg') gen_config = GenerationConfig(top_k=40, top_p=0.8, temperature=0.8) sess = pipe.chat(('describe this image', image), gen_config=gen_config) print(sess.response.text) sess = pipe.chat('What is the woman doing?', session=sess, gen_config=gen_config) print(sess.response.text)

采样参数与上下文窗口

创建 pipeline 时可通过TurbomindEngineConfig(tp=2, session_len=8192)开启张量并行（tp）并定制上下文窗口；推理时通过GenerationConfig(top_k=40, top_p=0.8, temperature=0.6)控制随机采样行为。多模态消息的完整格式（image/video/audio 等）可参考多模态输入参考。

显式释放资源

Pipeline 会持有引擎资源，可调用close()显式释放，或使用with上下文管理器：

from lmdeploy import pipeline from lmdeploy.vl import load_image with pipeline('google/gemma-3-12b-it') as pipe: image = load_image('https://raw.githubusercontent.com/open-mmlab/mmdeploy/main/tests/data/tiger.jpeg') response = pipe(('describe this image', image)) print(response) import torch import gc torch.cuda.empty_cache() gc.collect()

总结

通过 LMDeploy，Gemma3 多模态模型可以像普通 LLM 一样通过pipeline接口快速完成图生文推理，且原生支持多图、批量、多轮对话与张量并行等生产级特性。其底层实现由注册的Gemma3VisionModel（HF 处理器 + SigLIP 视觉塔 + 平均池化投影器）与 PyTorch 后端的Gemma3ForConditionalGeneration（融合 QKV 权重加载、<IMAGE_TOKEN>掩码注入、全局因果 + 1024 滑动窗口混合注意力）协同完成。如需查看更多模型配置细节，可查阅支持模型列表与多模态 Pipeline 文档。

• 人工智能
• 大模型
• 模型推理服务
• 推理引擎
• 本地部署
• 模型量化