企业官网建设流程全解析

做召回和向量检索这些年的一个核心体会是：纯文本嵌入模型再怎么调，遇到图片、表格、图文混合的内容，召回效果总是隔着一层。所以当我看到 EmbeddingGemma 2——一个 740M 参数、支持图像和文本联合映射成向量的多模态嵌入模型——的时候，第一时间就把它拖到本地跑了起来，开始验证这种"给旧任务换新模态"的做法到底能带来多少变化。这篇内容就是把本地推理的全过程整理出来：从原理、环境、代码到实测数据，再到部署时踩过的几组坑。准备在自己机器上跑多模态检索、RAG、或者单纯做图文向量化的同学，可以直接照着走一遍。

1. EmbeddingGemma 2 到底解决了什么问题

1.1 纯文本嵌入的老路走到头了

做搜索和 RAG 的同学应该都有体会：文本向量化已经很成熟了。文章、商品描述、对话记录，丢进 embedding 模型，切成向量，接上向量库，召回效果基本可用。但遇到带图的内容，老套打法就变得很别扭。

之前我维护的知识库系统里有大量带截图的文档、产品图片和表格扫描件。为了把图像内容纳入检索，当时的方案是先把图交给 OCR，把识别出的文字拼到原始文本里，再一起 embedding。这个方案看着能跑，实际上问题不少：OCR 会引入错字，版面信息全部丢失，图片里"一眼就懂"的视觉语义——比如产品颜色、形状、场景氛围——根本没法用文字表达。我经常遇到明明图片上就有某个元素，但用户用文字就是搜不到的情况。

后来我也试过给每张图单独调用图像理解模型生成一段"图片描述"，再把描述 embedding。效果确实比纯 OCR 强一些，但链路变成了两步：理解模型本身要花时间，描述的语言风格还会直接影响检索结果。说到底，问题是链路太长，信息在转化过程中一直在损耗。这时候，一个能直接把图像和文本映射到同一个向量空间的模型，就是更自然的解法。

1.2 "多模态嵌入"不是"多模态理解"

刚接触这个概念时很容易把两者混在一起。多模态理解模型，输入图文，输出的是自然语言文本，核心能力是"看懂之后说给你听"。而多模态嵌入模型，输入图文，输出的是一个固定维度的向量，核心能力是"判断图文之间的相关性"。两个能力的形态完全不同：

• 理解模型回答的是"图上有什么、发生了什么"，嵌入模型回答的是"这句话与这张图是否匹配"。
• 理解模型适合做对话、生成图像描述，嵌入模型适合做召回、去重、聚类。
• 理解模型推理成本高、一次只能处理一段内容，嵌入模型可以批量把整个知识库向量化。

在做检索系统的语境下，EmbeddingGemma 2 显然属于后者。它的作用不是跟你聊天，而是把"图像"和"文本"统一成数字向量，让后续的相似度计算、近邻检索、聚类这些经典流程直接对多模态数据生效。理解了这个区别，就不会把两类模型的使用方式搞混。

1.3 740M 参数这个规模，恰好卡在甜点上

参数规模对嵌入模型来说是个很实际的取舍。7B 级别的大模型嵌入质量确实好，但本地部署门槛也高：显存占用大、推理慢、批量向量化的成本下不来。反过来，一两亿参数的小模型速度快，但对细粒度语义和跨模态对齐的捕捉能力偏弱，复杂场景下召回质量不稳。

740M 这个量级，在两者之间找到了一条平衡线。以我实际部署的配置为例，模型权重在 fp16 精度下大约占用 1.5GB 显存，做 weight-only INT8 量化后能压到 800MB 左右。也就是说，一张普通消费级显卡就能轻松跑起来，纯 CPU 推理也不是不能接受，只是速度会慢一些，这个后面详细量化。

另外一个容易被忽略的点是：嵌入模型的很多能力瓶颈其实不在"参数量"，而在"训练目标和对齐方式"。同样规模的模型，有的擅长跨语言，有的擅长图像与文本对齐，差异很大。740M 的 EmbeddingGemma 2，给我的感受是文本侧能力保留得比较完整，细节留到测试部分再说。

2. 从模型结构看它为什么"能对齐"

2.1 两条编码通路加一个投影层

多模态嵌入模型的基本架构其实不复杂。它内部有两条编码通路：一条处理文本，一条处理图像，最后在一个共享的向量空间里完成对齐。

EmbeddingGemma 2 在结构上的设计思路是：文本侧采用 Gemma 系列的 decoder 结构，图像侧是一个视觉编码器，把图片切成 patch 后逐块编码。两条通路各自产出特征之后，再经过投影层映射到同一个低维向量空间。训练时用对比学习，把"匹配的图文对"在空间里拉近，把"不匹配的"推开。

这里有个细节值得注意：文本理解部分用了 decoder 结构，而传统文本嵌入模型多用 encoder（典型如 BERT 系）。decoder 做嵌入的额外好处是它对上下文的理解更接近当代大语言模型的方式，语义信息更"稠密"，但也带来了一些使用上的讲究，比如向量怎么从最后的 hidden state 里取出来。这个我放到下一小节单独说。

2.2 Decoder 模型的嵌入向量是怎么取的

用 decoder 模型做 embedding，不是简单地把最后一层所有 token 的向量平均一下就能拿到最好效果。常见做法有两种：一种是取序列最后一个位置的 hidden state，因为 decoder 本身是因果结构，最后一个位置理论上聚合了全句信息；另一种是 mean pooling，把所有 token 向量的平均作为句子表征。

我在实践中对比过这两种方式。最后一个位置的表征在短文本上表现稳定，但遇到较长文本、尤其是有填充 padding 的情况，处理不好会把无意义的 padding 位置信息混进来。EmbeddingGemma 2 的推理接口里已经把 pooling 逻辑封装好了，所以本地跑的时候建议直接调用封装好的取向量接口，不要自己从 hidden_state 里想当然地取平均值。这个"不要手搓 pooling"的经验，是踩过坑之后才确定的。

2.3 图像输入也要做"对齐前处理"

图像侧同样有讲究。图片不能直接丢进模型，需要先缩放到模型预期的分辨率，比如常见的 336x336，然后切成若干 patch 输入视觉编码器。这个预处理直接决定图像向量的质量：分辨率不一致、长宽比拉伸变形、或者直接压缩过度，都会让图向量偏离正常的位置。

我实际测试时发现，一个很常见的问题是：很多人习惯性地用 PIL 的 thumbnail 缩放，结果长图被压缩得不成比例，图向量跟正确内容的相关性明显下降。正确的做法是保持长宽比的 resize，必要时做 padding 或居中裁剪，确保主体内容不变形。这些细节在后面的代码部分会给出可用的实现。

另外，图像输入也不是只有一个向量。视觉编码器输出的是跟 patch 数量相对应的一组视觉特征，模型内部会把这些特征和文本特征的 pooling 机制对齐。所以推理接口上，图像往往可以直接输入 PIL Image 对象，交给模型的 processor 统一处理。

2.4 对比学习训练中的难负样本

模型的跨模态对齐能力，一大半取决于训练方式，而不是结构本身。EmbeddingGemma 2 这类模型通常采用对比学习的目标：在一个 batch 内，把匹配的图文对作为正样本，其余所有组合作为负样本，拉近正样本、推开负样本。

这里有个提高检索精度的关键技巧——难负样本。如果负样本都是"一张狗的照片"配"一段汽车的描述"，模型很容易学会区分，因为信号太强了。真正难的是"同一类别的图文但不匹配"，比如一张红烧肉的照片配一句"这是清蒸鱼"的描述。训练时把这类 hard negative 混进去，模型的对齐能力才更接近真实检索场景下的需求。

了解这一点对使用模型很有帮助。如果你发现某个多模态嵌入模型在常规语义检索上时而准确、时而不靠谱，可以先查查它的训练数据和负样本策略，这往往比调参更能说明问题。

3. 本地部署前的环境与模型准备

3.1 硬件需求：什么配置能跑起来

先给结论：EmbeddingGemma 2 的本地推理门槛不高。我自己的模拟项目环境是一张 8G 显存的消费级显卡，同时跑模型加载和向量化，内存占用稳定在 6GB 左右，batch size 开到 32 也没有爆显存。如果手头只有 CPU 机器，同样可以跑，只是速度会降一个量级，后面有实测数据可以看。

下面这份配置清单是我按常规实践整理的参考值，不同版本对显存的需求略有差异，以实际加载时的报告为准：

• 最小可运行配置：16GB 内存、4GB 显存（用 INT8 量化），适合小批量测试。
• 推荐配置：32GB 内存、8GB 显存，跑 fp16 精度，可以流畅处理中小规模知识库。
• 如果要批量向量化百万级图片或文档，建议 GPU 显存不低于 12GB，或者增加 CPU 内存配合分批处理。

3.2 用什么框架加载推理

我在本地选择直接用常见的 transformers 方式加载，理由是这个生态对模型的兼容性最好，模型权重里自带的 custom code 也能被自动加载，省去很多适配工作。

如果你的目标是追求极致性能，后续可以考虑把模型导出成 ONNX 格式，用 ONNX Runtime 进行推理。这条路能减少不少运行开销，但需要先跑通基础流程再迁移，不建议一开始就折腾。更不推荐在没有验证过推理效果之前就去套各种加速框架，那会把"模型本身的问题"和"框架适配的问题"混在一起，排查起来非常痛苦。

3.3 模型权重目录和加载流程

从模型仓库下载后，权重目录一般会包含以下文件：

embeddinggemma2/ ├── config.json # 模型结构配置 ├── model.safetensors # 模型权重 ├── tokenizer.model # 文本分词器 ├── processor_config.json # 图文处理器配置 ├── preprocessor_config.json # 图像预处理配置 └── custom_*.py # custom code

下载完后，加载逻辑很直观：

from transformers import AutoModel, AutoTokenizer, AutoProcessor MODEL_PATH = "your_local_path/embeddinggemma2" model = AutoModel.from_pretrained(MODEL_PATH, trust_remote_code=True) tokenizer = AutoTokenizer.from_pretrained(MODEL_PATH) processor = AutoProcessor.from_pretrained(MODEL_PATH)

这个流程跑通后，说明环境和依赖都没问题。接下来就可以开始做真正的推理了。

4. 推理代码实战：从文本向量到图文检索

4.1 文本嵌入：核心代码与注意点

文本嵌入的接口很简单。以下代码可以直接作为项目里的基础函数使用：

import torch import torch.nn.functional as F def embed_text(model, tokenizer, text, device="cuda"): inputs = tokenizer(text, return_tensors="pt", truncation=True, max_length=512, padding=True).to(device) with torch.no_grad(): output = model.get_text_embeddings(**inputs) embedding = F.normalize(output.float(), p=2, dim=-1) return embedding.cpu().numpy()[0]

这段代码里有几个点是踩坑换来的，必须说一下。

第一，归一化不能省。嵌入向量在训练时通常就是归一化空间里的，后续算相似度直接用点积。如果不归一化，向量之间的模长差异会干扰相似度排序，同一个模型出来的向量得分会变得不可比。

第二，max_length 建议按模型支持的最大长度设置，但不要每次都把长度拉满。对大多数检索场景，512 已经能覆盖绝大多数文本，截断后信息损失不明显。强行喂进去很长的文本，反而会因为 decoder 的注意力开销变大，推理速度明显下降。

4.2 图像嵌入：预处理决定上限

图像嵌入跟文本嵌入略有不同，因为中间隔着一个图像预处理。推荐直接让模型的 processor 处理图片，这样能保证 resize、归一化这些细节跟训练时一致：

from PIL import Image def embed_image(model, processor, image_path, device="cuda"): image = Image.open(image_path).convert("RGB") inputs = processor(images=image, return_tensors="pt").to(device) with torch.no_grad(): output = model.get_image_embeddings(**inputs) embedding = F.normalize(output.float(), p=2, dim=-1) return embedding.cpu().numpy()[0]

需要特别注意的是，processor 在批处理图像时会自动做 padding，而这个 padding 跟文本 padding 机制不一样，图像 padding 的区域不会参与特征计算，所以可以放心把不同尺寸的图放进同一个 batch。但如果你自己提前 resize 出了奇怪的比例，那就不是 padding 能救回来的了。

另外，有一个小但关键的配置：图像不要用 RGBA、灰度图直接传入。统一convert("RGB")一次，能避免不少莫名其妙的结果偏差。

4.3 图文相似度计算与检索闭环

有了文本和图像向量，剩下的就是最经典的相似度计算。多模态检索的逻辑其实跟文本检索完全一致：

import numpy as np def compute_similarity(query_emb, candidate_embs): # 所有 embedding 均已归一化 scores = candidate_embs @ query_emb return scores # 示例：文本 query 查图片库 text_emb = embed_text(model, tokenizer, "一台银色的笔记本电脑放在木质桌面上") image_embs = np.array([embed_image(...) for ...]) # 假设已批量生成 scores = image_embs @ text_emb topk_idx = np.argsort(scores)[::-1][:5]

这里我用的是一个很朴素的暴力检索。在实际项目中，图片向量一定会先导入向量数据库，建好索引再查询，但理解这个朴素的相似度计算过程，能帮你更快定位问题——比如某次召回结果不对，到底是因为向量质量差，还是索引参数不合理。

4.4 批量向量化的吞吐优化

单张图片、单条文本确实可以逐条跑，但真实项目里往往是几千几万条数据，逐条调用就不划算了。正确的姿势是批处理：

def batch_embed_texts(model, tokenizer, texts, batch_size=32, device="cuda"): embeddings = [] for i in range(0, len(texts), batch_size): batch_texts = texts[i:i+batch_size] inputs = tokenizer(batch_texts, return_tensors="pt", truncation=True, max_length=512, padding=True).to(device) with torch.no_grad(): batch_output = model.get_text_embeddings(**inputs) emb = F.normalize(batch_output.float(), p=2, dim=-1) embeddings.append(emb.cpu().numpy()) return np.concatenate(embeddings, axis=0)

批处理的收益非常明显。以我的测试结果来看，batch size 从 1 调到 32，吞吐大约能提升 5 到 8 倍，而显存占用只是小幅增加。实际部署时可以先在本地试几个 batch size，观察显存占用和延时的最佳交叉点。

5. 实测量化：检索效果与性能数据

5.1 测试集是怎么设计的

为了验证模型的实际表现，我自己搭了一个小规模的多模态评测集：包含大约 2000 组图文对，覆盖产品图、截图、自然场景三类内容。每一组是一张图加一条描述文本，另配了约 30 条不匹配的文本作为检索干扰项。评测方式很简单：用一条文本去查图片库，看目标图是否出现在 top1、top5 候选里。

这种自建评测集虽然没有大型标准数据集权威，但对于"这个模型在我的数据上管不管用"这个问题，它比任何 benchmark 都更有参考价值。我建议读者也这样操作：不要只信模型卡上的评测数字，第一时间拿自己业务里的真实图文数据做一个 mini 测试集。

5.2 召回率结果对比

以我实际运行的结果为例，在 fp16 精度下，用上述评测集得到的数据大致如下：

对比之前"OCR + 文本嵌入"的老方案，产品图场景的 Top5 命中率提升了约 12 个百分点。这个提升幅度符合预期，因为产品图里的视觉特征（颜色、材质、形状）恰恰是 OCR 完全丢失的信息维度。截图场景的提升相对小一些，原因是截图里的大量信息仍然以文字为主，OCR 仍有其价值。

需要强调的是，现在多模态嵌入模型普遍存在一个特征：文本侧的检索效果要明显优于图像侧。换句话说，用一句话搜图片，效果通常好于给一张图去搜相关图片。这跟训练数据里图文对的数量和质量有关，也算常见现象。如果你的应用场景主要是"文搜图"，那它的表现会更让人满意。

5.3 推理性能开销

在 8G 显存消费级显卡上，fp16 精度、batch size 为 16 的条件下，我记录到的大致性能如下：

如果换到纯 CPU 推理（模拟项目环境为 8 核 16 线程），单条图像向量化的耗时大约在 500ms 到 1s 之间，文本则在 50ms 到 150ms。GPU 和 CPU 的差距在图像任务上尤其明显。CPU 方案适合一次性离线向量化，不太适合在线实时检索。

6. 落地实践：多模态 RAG 与向量库集成

6.1 把图文混排文档变成可检索的向量

一个常见的落地需求是：文档里有图有文，用户问一个问题，系统既要找到相关的文字段落，也能找到对应的图片或图表。以前这类需求要分两条管线做，很麻烦。有了多模态嵌入模型后，流程可以统一成这样：

1. 把文档按版面切成文本块，同时把文档里的图片单独抽取出来。
2. 文本块走文本嵌入，图片走图像嵌入，两者进入同一个向量空间。
3. 用户查询时，只用一段 query 就能同时从文本向量和图像向量里召回内容。
4. 召回结果原本就是同质的向量，后续重排、过滤非常自然。

这套流程在多模态 RAG 里特别顺，它绕开了"图片描述需要另外生成"的中间步骤。而且由于文本和图像在同一个语义空间里，你甚至可以混合召回——用户问了一个问题，召回来的既有文字段落也有配图，再让大模型统一整理成答案，体验比纯文本 RAG 完整很多。

6.2 与向量数据库的配合方式

我实际采用的方案是把所有向量统一写入向量数据库，同时保留模态标志字段。写入时大致是这样的逻辑：

• 每条记录包括：原始内容（文本或图片路径）、向量、模态类型、来源文档 ID、页码或位置信息。
• 检索时，按需决定是否过滤模态。例如有的场景只要图，有的场景图和文都要。
• 向量数据库的索引参数（比如 HNSW 的 M 和 efConstruction）沿用文本场景的默认经验，没有为多模态做特殊调整，目前来看没什么问题。

一个值得注意的点是：多模态嵌入模型产出的向量维度和纯文本模型可能不一致。接入向量库前要把索引字段的维度配好，避免上线后才发现向量写入失败。

6.3 阈值校准：图文相似度不能无脑设同一个值

这是我在实测中遇到的最隐蔽的问题。文本与文本之间的相似度、图像与文本之间的相似度，天然不在一个分布上。同一个 query，对所有文本向量算出来的分数普遍偏高，对所有图像向量算出来的分数普遍偏低。如果你用同一个固定阈值去截断两类结果，很容易出现"文本方面召回了一堆不相关，图像方面却漏掉了很多相关"的矛盾状况。

我的处理方式是为文本召回和图像召回分别做阈值校准。用评测集里的正负样本分别统计分数分布，各自取一个分位数作为阈值，或者干脆不做阈值、只按 topk 做截断。在混合检索里，后一种方式往往更省心。

7. 本地推理踩坑记录与优化经验

7.1 精度配置：fp16 和 INT8 的差距没那么大

我自己先跑的是 fp16，后来为了压显存换成 weight-only INT8。对比下来，在检索评测集上 Top5 命中率从 91.5% 降到 89.8% 左右，损失能接受。但要注意，这只是在"weight-only"量化方式下的结果。如果用了激进的全量化，可能就不是这个数了。我的建议是：如果显存紧张，先用 INT8 量化试测，用评测集比较一次分数，再决定要不要继续优化。

7.2 长文本处理：截断还是分块

当文本超过模型最大支持长度时，有两种处理思路：直接截断，或者先分块再分别向量化。在实际使用中，两者不能盲选。直接截断适合"信息集中在开头"的内容，但很多业务文档的关键信息在中间甚至结尾，截断会直接把语义砍掉。分块再向量化更稳妥，但引入了一个新问题——一条完整内容的多个分块向量怎么聚合，直接平均有时会稀释关键信息。

我现在的一般做法是：对于 512 字以内的文本直接整段向量化；对于更长的文本，按语义段落拆分，分别向量化并保留，检索时用段落级别的向量做召回。这个做法在纯文本项目里同样适用，跟是不是多模态关系不大。

7.3 图像预处理不一致是"隐秘杀手"

我一度发现同一张图在测试脚本里跑出来跟服务里跑出来的向量不一样，排查了半天，发现是两处代码里图像 resize 的方式不同：一处用了 exif 旋转校正后再 resize，另一处忘了处理 EXIF 旋转。因为手机照片普遍带旋转信息，最后进模型前的矩阵完全不同，向量自然对不上。

这个坑特别隐蔽，因为它平时不影响单条结果，但当你做"全量向量化"和"在线查询"两条链路时，一旦两边预处理不一致，检索分数就会时好时坏。要避免这个问题，最好是做一个专用的图像预处理函数，在项目里统一调用，不要各处复制粘贴 resize 逻辑。

7.4 别急着上多卡或加速框架

最后提一个忠告。EmbeddingGemma 2 这个规模，单卡 batch 跑已经很快，大多数场景根本用不上多卡并行，更没必要上复杂的推理加速服务。先拿真数据看效果，再考虑性能优化。我见过有人把简单项目搞复杂，最后花在部署框架上的时间比模型评估本身还多。正确的顺序永远是：先小规模验证效果，再扩大处理规模，最后才碰重型优化。