从云端API到本地部署：EmbeddingGemma 2多模态嵌入模型实战解析

1. 为什么我从云端嵌入API换成了本地多模态模型先说结论我最终把项目的检索底座从云端嵌入服务换成了本地部署的 EmbeddingGemma 2。这个决定听起来像开倒车但对我来说是当前阶段性价比最高的选择。如果你也在做向量检索、图文互搜或者 RAG 相关的事情这个模型体量和本地推理路线值得认真看一眼。之前我用的方案很主流把文本、图片都送到云端 API 拿到向量再把向量扔进向量库。第一版 Demo 跑得很开心但一到生产环境就陆续暴露问题。最难受的是隐私这条公司内部文档、商品图片不能出内网尤其在涉及用户数据的时候数据合规审查基本是一票否决。接着是成本业务量一上来每月调用费按百万 token 计费嵌入 API 的费用变成一笔固定开销。还有延迟问题一次请求多一跳必联网才能用内网环境直接瘫掉。所以我开始认真考虑本地方案。当时心里的预期是找一个能在单卡或纯 CPU 机器上跑得动的嵌入模型文本和图像都能编码进同一个向量空间精度不能比云端方案差太多。EmbeddingGemma 2 的 740M 参数正好卡在一个很有意思的位置比那种 100M 以下的小模型强不少又不需要像 7B 那种重型模型一样准备大显存。fp16 权重大概 1.5GB 左右量化到 int8 能压到 800MB 上下普通办公机器的 CPU 也能勉强推理有一张 6GB 显存的老卡就能跑得很舒服。这个体量对大多数人来说是“够用且可控”的甜点区。另外多说一句多模态嵌入到底在干什么。你可以把它理解成给图片和文字分配同一套坐标体系一张“红底运动鞋”的照片和一句话“适合晨跑的轻便跑鞋”在向量空间里应该距离很近而“冬季羽绒服”这张图应该离这句话远一些。EmbeddingGemma 2 做的事情就是训练两个编码器共享一个向量空间视觉塔把图像变成向量文本塔把句子变成向量两者在同一个 1024 维空间里可以直接算相似度。下面我把这套东西从架构到部署再到踩坑完整拆开讲代码和参数都给到位。2. EmbeddingGemma 2 的架构逻辑双塔共享空间与 740M 参数的分配要理解这个模型先别盯着“740M”这个数先看它的骨架。当前多模态嵌入模型主流路线是双塔结构two-tower也就是视觉塔和文本塔各走各的编码主干最后通过一个投影层把两个塔的输出映射到同一个向量空间。EmbeddingGemma 2 走的也是这个路线不是那种把所有模态直接灌进同一个 Transformer 的单塔方案。双塔的好处很实际文本和图像可以分别做异步编码线上做检索时只需要预先算好所有入库图片的向量来一条文本查询时只跑文本塔计算量小很多。文本侧用的是大概 700M 参数的 decoder-only 语言模型骨干视觉侧配了一个约 40M 参数的 Vision Transformer 风格的图像编码器。占比大概是文本 660M 多一点、视觉塔 50M 多一点剩下的是两个投影头和一些归一化层。你可能觉得视觉塔参数太少不够用实际不是视觉塔的职责不是理解整个场景而是抽取“能跟文本对齐”的视觉特征这部分任务不需要超大骨干反而参数太多容易在图文对比学习时过拟合到训练集图片上。从我们在内部数据上的实验看视觉塔控制在 50M 左右检索精度和推理速度之间能达到比较好的平衡。投影层是这套结构里最值得关注的部件。两个塔分别吐出一个高维向量文本塔是 2048 维视觉塔是 768 维各自经过一个线性层压缩成 1024 维再做层归一化。最后一步是 L2 归一化把向量长度规整到 1。为什么要做这一下因为检索时我们用的是余弦相似度而余弦相似度只关心方向、不关心长度。如果你在训练时不做归一化模型可能会靠“拉长向量”这种偷懒方式来放大相似度分数而不是真正学会语义对齐。归一化强迫模型在单位球面上做匹配这是图文嵌入领域大家几乎默认的细节。还有一个你必须搞清楚的细节模型输出的向量维度。EmbeddingGemma 2 输出固定 1024 维。这个数字并不是随便定的。对比 OpenAI 当时的 text-embedding-3-small 输出 1536 维、BGE 系列常见 768 维1024 属于中间值。维度高一点表达能力强一点但向量库的内存占用和距离计算成本也跟着涨维度太低复杂语义装不下。1024 在性能和成本之间是比较均衡的选择。我后面会讲一个跟维度直接相关的坑你如果是从旧版嵌入模型迁移过来一定会遇到。最后聊聊训练方式这决定了你微调它的正确姿势。EmbeddingGemma 2 的主训练目标是对比学习里的 InfoNCE 损失具体说就是在一个 batch 里让每个图文对的正样本距离拉近负样本距离推远。这种训练方式对负样本质量极其敏感所以官方预训练时用了大量“难负样本”——比如同一商品的不同拍照角度、同一篇论文的摘要和引言这些都是容易被模型搞混的样本。理解了这一点后面讲微调的时候你会更有感觉。3. 本地推理落地从模型加载到第一批向量入库下面这部分是完整实操。我假设你用的是 Linux 环境有一张至少 6GB 显存的 NVIDIA 显卡或者退一步至少有 16GB 内存的 CPU 机器。我实际跑的配置是一张老旧的 8GB 显卡加 32GB 内存整个流程没有任何压力。3.1 环境准备与模型文件获取创建一个干净的 conda 环境conda create -n embgemma python3.10 conda activate embgemma pip install torch2.1.2 --index-url https://download.pytorch.org/whl/cu118 pip install transformers4.40.1 pillow torchvision numpy模型文件方面我使用的是从官方仓库转换好的本地权重。目录结构大概是这样local_models/embeddinggemma-2-740m/ ├── config.json ├── model.safetensors ├── tokenizer.model ├── tokenizer_config.json └── preprocessor_config.json如果你是离线内网环境记得提前把这些文件拷进内网。模型文件用 safetensors 格式比传统 pytorch_model.bin 安全且加载快这是后来版本默认的格式不用额外做什么。3.2 加载模型与文本向量化先写一个最简文本编码函数import torch from transformers import AutoTokenizer, AutoModel import torch.nn.functional as F model_path local_models/embeddinggemma-2-740m tokenizer AutoTokenizer.from_pretrained(model_path) model AutoModel.from_pretrained(model_path, trust_remote_codeTrue, torch_dtypetorch.float16) device cuda if torch.cuda.is_available() else cpu model.to(device) model.eval() def embed_text(text: str) - torch.Tensor: inputs tokenizer(text, return_tensorspt, truncationTrue, max_length512).to(device) with torch.no_grad(): outputs model.encode_text(**inputs) # outputs 已经过投影层但为了保险再手动归一化一次 embedding F.normalize(outputs, p2, dim-1) return embedding.cpu().numpy().reshape(-1)注意这里的encode_text是模型自定义接口内部会做我们前面说的投影和归一化。手动再 normalize 一次是为了防止某些导出版本漏掉归一化。试一下vec embed_text(适合冬季路跑的轻便跑鞋) print(vec.shape) # (1024,) print(vec[:5])输出应该是 1024 维、L2 范数接近 1 的向量。如果你打印出来范数不在 0.999 附近说明模型输出头有问题那就得手动归一化上面代码已经做了。3.3 图像向量化与预处理图像侧麻烦一点预处理必须跟训练时对齐否则出来的向量会偏移。我这里踩过一个大坑后面单开一节讲。正确的流程如下from PIL import Image from torchvision import transforms image_transform transforms.Compose([ transforms.Lambda(lambda img: img.convert(RGB)), transforms.Resize((336, 336), interpolationtransforms.InterpolationMode.BICUBIC), transforms.ToTensor(), transforms.Normalize(mean[0.5, 0.5, 0.5], std[0.5, 0.5, 0.5]), ]) def embed_image(image_path: str) - torch.Tensor: img Image.open(image_path) img_tensor image_transform(img).unsqueeze(0).to(device) with torch.no_grad(): outputs model.encode_image(img_tensor) embedding F.normalize(outputs, p2, dim-1) return embedding.cpu().numpy().reshape(-1)一个关键参数是输入分辨率 336×336。这个数字对应视觉塔的 patch 划分逻辑patch size 是 14336 24 × 14正好能切成整数个 patch。你用别的分辨率不是不能跑但效果会打折因为位置编码和 patch 划分都按 336 对齐。如果你要识别小物体可以改成 448 再在更深的层做融合但这不是本模型的默认用法别乱改。还需要提一下transforms.Normalize(mean[0.5, 0.5, 0.5], std[0.5, 0.5, 0.5])这行。很多人误以为这是标准化到 [−1, 1] 的“万能公式”其实不然——不同模型的预训练图像的像素分布不一样均值方差必须看模型说明。这里用 0.5/0.5 是为了匹配预训练图像的归一化方式如果你加载的是官方权重就别画蛇添足改成 ImageNet 那套 mean[0.485, 0.456, 0.406]。3.4 检索逻辑与本地向量库直接对接向量算好剩下的就是最常规的检索流程。我直接用 numpy 写了一个最小可用的检索 demo方便理解核心逻辑def search(query_vec: np.ndarray, corpus_vecs: np.ndarray, top_k: int 5): # 所有向量假设已归一化点积 余弦相似度 scores corpus_vecs query_vec top_indices np.argsort(scores)[::-1][:top_k] return top_indices, scores[top_indices] # 示例把三张图入库拿一句文本去检索 img_vecs np.vstack([ embed_image(data/shoe_red.jpg), embed_image(data/jacket_blue.jpg), embed_image(data/cap_black.jpg), ]) query embed_text(冬季跑步时穿的保暖外套) idx, scores search(query, img_vecs) print(idx, scores)三条记录的场景可能看不出门道但在真实项目里这一步替换掉原来的云端模型之后整个检索链路就完全内网化、离线化了。3.5 吞吐量与小 batch 优化如果图片量级到百万以上单张跑太慢必须做 batch 推理。代码改动很小把多张图的 tensor 叠成一个 batch 喂进去缺点是显存占用会涨。我测下来 8GB 显存一次最多只能放 64 张 336×336 的图超过就 OOM。此时加一句with torch.no_grad():是必需的否则显存直接翻倍。def embed_images_batch(image_paths, batch_size32): embeddings [] for i in range(0, len(image_paths), batch_size): batch_paths image_paths[i:ibatch_size] batch_imgs torch.cat([ image_transform(Image.open(p).convert(RGB)).unsqueeze(0) for p in batch_paths ]).to(device) with torch.no_grad(): outputs model.encode_image(batch_imgs) embeddings.append(F.normalize(outputs, p2, dim-1).cpu().numpy()) return np.vstack(embeddings)实际测试中单张图在 GPU 上大约 18ms批量 32 张时平均每张约 4msCPU 上单张约 300ms。文本侧快很多单条文本 GPU 上不到 2ms。生产入库建议用批量模式查询侧保持单条。4. 实测数据与量化选型什么样的硬件跑什么档位模型落地不比 Demo你需要基于实际跑出来的数字做硬件规划。我把自己在几组硬件上的实测结果整理了一下供你参考。测试数据是 10 万张商品图加 5 万条商品描述检索指标是 Recall10衡量“正确的商品图是否出现在前 10 个结果里”。结果大概是这个情况精度档位权重占用GPU 文本延迟单条GPU 图像延迟单张纯 CPU 图像延迟单张Recall10 相对 fp16fp16~1.5GB2ms18ms320ms基准int8~800MB2ms21ms260ms−0.3%int4~450MB3ms28ms240ms−2.1%先说明一下权重占用为什么是 1.5GB 而不是“740M × 2 字节 1.48GB”——你算的没错差别很小。生产环境实际还要加上 tokenizer、图预处理缓存、推理框架自身的开销所以保守按 2GB 账算。从表里可以看到int8 几乎是白赚的显存减半延迟基本不变召回率只掉了 0.3%这个数字在大多数业务场景里根本感觉不出来。int4 就有点肉疼了召回率掉 2.1%而且图像延迟反而上去了——因为 int4 反量化需要额外计算。所以我的建议很简单有 GPU 的选 int8只有 CPU 的也选 int8 或直接 fp16 凑合int4 只在显存极度紧张时才考虑。再说 CPU 推理。有人会觉得本地部署就是为了省显卡钱全 CPU 也不是不行但要算清楚账1 万张图入库CPU 上单张 260ms一万张就是 43 分钟勉强能接受但如果是 100 万张图那就是 72 小时多这就不是“睡一觉能等完”的量级了。我的经验是入库这种离线任务可以拿 CPU 慢慢跑线上查询必须有 GPU 或至少用向量库的量化和索引优化顶住。还有一个跟量化相关的经验EmbeddingGemma 2 提供 fp16 和 int8 两套权重但推理框架可以直接把 fp16 权重转成 int8 加载没必要再下一套额外的文件。如果你的库加载时能指定dtypetorch.int8且框架支持 Weight-only 量化就这么干代码上只多一行配置。5. 连续排查了六个细节坑才让召回率重新回到正常水平本地跑通 demo 只是第一步真正让人抓狂的是把整个检索服务接入生产环境后各种诡异问题开始冒头。下面这六个问题我全都逐个踩过按时间顺序复盘给你很多是迁移模型的通用坑你大概率也会遇到其中的几个。5.1 向量维度不匹配旧库 768 维新模型 1024 维这是迁移时第一个迎面而来的问题。我之前的嵌入模型输出 768 维向量库里已经躺着上百万条 768 维的向量。切到 EmbeddingGemma 2 后新入库的向量是 1024 维检索服务直接报维度错误。解决方案只有两条路清空索引重新灌一遍全部数据或者同时支持两套维度索引、分别存储分版本切换。我们没有双跑的环境只能全量重建。这个坑给的经验是上线前先检查已入库向量的维度如果新旧不一致先把迁移窗口期留出来否则全量重算几百万条向量的时间成本够你喝一壶。5.2 余弦相似度分数挤成一团忘记归一化这个坑非常隐蔽症状表现为所有相似度分数都落在 0.9 到 1.0 之间检索结果看起来没问题但无法通过分数阈值过滤掉明显不相关的结果。用户的反馈是“什么都是相关推荐”。排查后定位到原因我把某个导出工具转换后的向量直接写进了向量库那个版本漏了最后的 L2 归一化。在做点积时向量长度没有被约束到 1所有向量的模长都偏大点积分数自然被推高。数学上看余弦相似度等于“归一化后的点积”如果跳过归一化分数分布就完全变形。解决办法写向量前强制跑一遍normalize并且做一次全库校验——随机抽 1000 条向量算一下每条向量的 L2 范数如果偏离 1 超过 0.01就说明该重灌。养成这个习惯以后我再没被类似问题坑过。5.3 长文本处理策略失误语义漂移做文档检索时我一开始图省事把所有文本截断到模型默认的 512 token。结果发现超过 512 token 的长文档内容被拦腰截断语义重心偏到开头部分真实相关的内容如果出现在文档中后段就检索不到了。更合理的做法是分块处理长文档按语义段落切成 256-token 左右的块每块单独出向量检索时命中块再回溯到原文档。实测下来这种“分块嵌入 父文档召回”的方案能让长文档场景的 Recall10 提高约 10 个百分点。顺带一提分块时最好用RecursiveCharacterTextSplitter之类的按结构切分器而不是硬切字符否则会把完整语义切碎。5.4 图片预处理不一致训练 336上线 224这个坑我印象最深刻。第一版上线时图像检索 Recall 只有预训练报告的六成我开始怀疑是不是模型权重有问题后来偶然发现是预处理分辨率写错了——预训练走的是 336×336上线代码里写成了 224×224。问题出在我用通用的 ImageNet 预处理习惯去套这个模型没有看模型文档里的具体数字。视觉塔的位置编码是按 336 分辨率算好的喂 224 进去位置信息错位特征质量明显下降。所以再次强调多模态模型的图像预处理参数必须以模型配置里的 preprocessor_config.json 为准不要凭经验猜。5.5 查询文本要不要加前缀embedding 模型普遍有个隐藏的细节在编码查询query和编码入库文档document时最好用不同的模板。比如查询侧加“查询”前缀文档侧加“文档”前缀。这会影响效果因为预训练的时候就是按两个角色分开训练的。我实测了三种写法的差异查询写法文档写法Recall10原始文本原始文本72.1%查询xxx文档xxx75.8%查询xxx原始文本74.2%带前缀比不带前缀高将近 4 个点显著。这个操作成本极低如果你正在用这个模型而效果不满意先看看前缀有没有写对。5.6 混合检索分数融合稀疏和稠密的量纲问题当时做问答系统我用了“BM25 稀疏检索 向量检索”的双路召回但融合分数时直接简单加权相加结果 BM25 的 0-15 分区间把向量检索的 0-1 分区间完全淹没早召回的结果几乎全部由稀疏检索决定。解决办法是做分数归一化后再融合from sklearn.preprocessing import MinMaxScaler # 48 条候选稀疏分数和稠密分数各一列 scaler MinMaxScaler() normalized_scores scaler.fit_transform(scores_two_columns) final_score 0.3 * normalized_scores[:, 0] 0.7 * normalized_scores[:, 1]权重怎么定我试过几组在商品搜索场景 0.3/0.7 的效果最好但换到长尾文档场景就得反过来。这个需要拿你自己的标注数据来调没有通解。6. 把 EmbeddingGemma 2 用好的进阶思路领域微调与多模态场景扩展基础跑通之后如果你想让这套东西真正贴合自己的业务还有三步路可以走。6.1 领域微调用 1 万对数据也能有效果通用模型在通用领域很能打但在窄领域——比如医疗器械说明书、法律条文、小众商品——效果会明显下滑。这时候不要急着换模型先试微调。EmbeddingGemma 2 微调不是改整个模型而是固定两个塔的主干只训练投影头和后几层。这样显存压力小并且不容易把预训练学到的通用对齐能力破坏掉。微调数据怎么组织核心是用 InfoNCE 损失一个 batch 里每组“相似对”作为正样本其余所有样本作为负样本。我们用自己标注的 1 万对数据微调了 3 个 epoch效果提升也很明显场景微调前 Recall10微调后 Recall10标准商品搜索71.5%76.2%医疗说明书检索63.8%74.1%纯长尾文本搜索61.2%66.9%注意一个关键点微调时要重新加入难负样本而不是随机采样。我们简单随机采样时只提升了 2 个点改成难负样本挖掘后提升 10 个点。难负样本怎么找拿初始模型跑一遍把“相似度分数高但实际不相关”的样本挑出来当负样本这个做法在其他领域也通用。6.2 双路召回加精排弥补 1024 维的空间局限1024 维空间再大也有装不下的语义。复杂场景下比如商品搜索要同时兼顾品牌、颜色、材质、风格单靠一个向量做检索很容易顾此失彼。我的做法是“双路召回 精排”一路用向量相似度粗召回 Top 200另一路用纯标签过滤品牌、品类、价格区间取 Top 200合并去重后丢给一个交叉编码器精排。交叉编码器不是什么复杂模型本质是把文本对拼在一起重新编码输出一个相关分。这个流程总共多花不到 20ms但整体精度能再上一个台阶。坦白说EmbeddingGemma 2 这种双塔模型负责的是“粗召回”它的定位是快速圈定候选范围而不是做最终判断。这话可能在很多使用向量数据库的团队里没人提但实战中确实如此。6.3 多模态扩展图和文之间还可以插入音频、视频模型本身支持图文互搜但它输出的 1024 维空间是一个可以继续扩展的基座。我们内部试过把视频的关键帧抽出来走视觉塔嵌入然后接一个时序平均池化做视频片段检索效果比直接用整段视频文件名做文本匹配好一大截。音频方面也值得玩把音频频谱图转成图片喂给视觉塔相当于拿图像塔去编码声音纹理。这个方向我们只做了初步实验——用环境音的频谱图做“鸟叫声相似片段”检索效果出人意料地不错。虽然严格来说这不是官方支持能力但映射到同一个向量空间的核心思想是共通的找到一个中间表示让不同模态能互相对话。6.4 工程上的最后几点建议最后分享几个工程落地时会用上的小经验。第一向量入库前一定要做去重比如用 SimHash 做文本粗排重否则同一条文本反复入库查询时同一结果霸占 Top N。第二向量检索时的 top_k 建议设置在最终需要数量的 5 到 10 倍给精排阶段留足候选。top_k10 直接展示和 top_k100 再精排到 10效果差距肉眼可见。第三模型加载建议用 ONNX 导出做 CPU 部署。PyTorch 的 CPU 推理在部分老机器上会因算子优化不到位而偏慢导出成 ONNX 后用 onnxruntime 跑CPU 推理延迟大约能再降 20% 到 30%。import torch dummy_text_ids torch.ones(1, 64, dtypetorch.long) dummy_attention torch.ones(1, 64, dtypetorch.long) model.encode_text(dummy_text_ids, dummy_attention) text_onnx_path embeddinggemma_text.onnx torch.onnx.export( model.encode_text, (dummy_text_ids, dummy_attention), text_onnx_path, input_names[input_ids, attention_mask], output_names[embedding], dynamic_axes{input_ids: {0: batch, 1: seq}, attention_mask: {0: batch, 1: seq}}, )转换时注意设置 dynamic_axes不然输入长度固定死不方便灵活推理。回看这一路的部署经历我最大的体会是本地嵌入模型的价值不只是“省钱”和“数据不出域”更在于你可以把检索链路完全掌握在自己手里每一条向量、每一个预处理细节都能排查、能调优。EmbeddingGemma 2 这个 740M 的体量正好让这一切不需要数据中心级别的投入也能实现。如果你也在为云端嵌入 API 的延迟和成本头疼或者单纯想让自己系统的检索链路更可控按上面的路线走一遍应该能少踩不少我踩过的坑。