EmbeddingGemma 2 多模态嵌入模型本地部署与应用教程

EmbeddingGemma 2 是 Google DeepMind 于 2026 年 10 月发布的开源多模态嵌入模型，能把文本、图像、视频、音频统一编码到同一个 768 维向量空间，参数量仅 740M，消费级显卡即可流畅运行。本教程从零开始，在 Windows 环境下完成该模型的本地部署，跑通文本语义检索与图文跨模态搜索两大核心场景，并配套一个带网页界面的语义搜索演示服务。全文所有命令与代码均在本机 RTX 2080 Ti 上实测通过，实测基准数据一并附在文中，供部署后对照验证。

前置教程

如想快速开始学习本教程，你可能需要先完成以下前置教程：

• Embedding、Rerank与向量数据库概念详解与应用教程，理解嵌入向量、余弦相似度与向量检索等本教程反复用到的核心概念。
• Pytorch安装与版本选择问题详解，本教程依赖 GPU 版 PyTorch 运行模型，安装思路与版本选择原则一致。
• Python+FastAPI在Windows环境下创建一个基础后端服务教程，Web 语义搜索演示服务基于 FastAPI 搭建，了解后端服务的基本结构有助于理解示例代码。

资源下载

• EmbeddingGemma 2 模型包（夸克网盘 · 模型文件区），位于网盘「模型文件/Embedding/EmbeddingGemma-2」，解压后约 1.5GB，公开链接、永久有效、无提取码。
• embeddinggemma2-demo 示例项目（夸克网盘 · 示例代码区），含 Web 演示服务、入门脚本、实测套件与 7 张示例图片，公开链接、永久有效、无提取码。

1. EmbeddingGemma 2 模型介绍

1.1 模型简介

Embedding（嵌入）模型的作用是把一段文字或一张图片压缩成一个固定长度的数字向量，向量之间的距离反映了内容在语义上的接近程度。与生成式大模型逐字输出内容不同，嵌入模型只做「理解」和「压缩」，因此体积小、速度快，是语义搜索、RAG 知识库、推荐去重等系统的底层组件。

EmbeddingGemma 2 的特别之处在于多模态统一编码：文本、图像、视频、音频四类输入经过各自的编码器后，全部映射到同一个 768 维向量空间。这意味着中文句子和英文句子可以直接比相似度，一段文字和一张图片也可以直接比相似度——「用一句话搜图」因此成为可能。

1.2 多模态统一向量空间

四类输入走各自的编码器，输出落在同一向量空间，向量归一化后用内积（等价于余弦相似度）即可跨模态比较：

这一架构带来两个直接好处：其一，跨语言检索开箱即用，中文查询可以命中英文文档；其二，一套向量同时服务文本库和图片库，不用为每种模态单独维护一套检索系统。

提示：嵌入模型编码的是语义而非字面。图像分支理解的是场景、物体、风格与版面，模型不具备 OCR 能力，这一点在 6.3 节有实测说明。

2. 部署环境准备

2.1 硬件与系统要求

本教程实测环境如下，达到或高于该配置均可流畅复现：

2.2 创建 Python 虚拟环境

打开命令提示符，用 conda 创建独立环境：

conda create -n embeddinggemma python=3.10
conda activate embeddinggemma

2.3 安装 GPU 版 PyTorch

国内网络环境下，通过阿里云 PyTorch wheel 镜像安装与 CUDA 12.8 匹配的 GPU 版 torch：

uv pip install torch==2.11.0+cu128 --find-links https://mirrors.aliyun.com/pytorch-wheels/cu128

注意这里必须使用 --find-links 参数。+cu128 这类带本地版本号的 wheel 只存在于阿里云镜像的文件列表里，--extra-index-url 参数解析不到它。

提示：没有 NVIDIA 显卡的读者可跳过本步，下一步安装依赖时会自动装上 CPU 版 torch，后续命令完全一致。

2.4 安装项目依赖并验证

从资源下载区获取示例项目 embeddinggemma2-demo，解压到任意目录，在项目根目录执行：

uv pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

requirements.txt 已锁定实测可用的版本组合：

安装完成后验证 GPU 是否可用：

python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

期望输出 2.11.0+cu128 True。若输出 False，优先检查显卡驱动版本是否过旧。

3. 获取模型并完成部署验证

3.1 下载并放置模型包

从资源下载区下载模型包并解压，推荐放到统一模型库目录 C:\models\embeddinggemma-2。解压后的目录里应包含 model.safetensors 权重文件、config.json 模型配置、tokenizer.json 分词器，以及 sentence-transformers 的结构文件（modules.json、1_Pooling/ 等），整包解压即可，不要拆分文件。

示例代码按以下优先级自动查找模型：

1. config.py 中 MODEL_DIR 指向的目录（默认 C:\models\embeddinggemma-2）；
2. 示例项目内的 model/ 目录。

模型放在其他位置时，修改 config.py 的 MODEL_DIR 即可：

# config.py：模型目录改为实际解压位置
MODEL_DIR = r"D:\models\embeddinggemma-2"

3.2 首次运行验证

在示例项目根目录运行入门脚本：

python run_demo.py

这段脚本依次做了三件事，输出与上图对应：

1. 相似度矩阵：对 5 句中英混合文本两两计算余弦相似度。「法国的首都是哪里？」与它的英文版相似度高达 0.904，与无关的天气语句只有 0.639，跨语言语义区分清晰。
2. 检索排序：用「怎么做好吃的牛肉面？」在 4 篇文档中检索，正确命中牛肉面做法文档且分数 0.803，与其他文档拉开明显差距。
3. MRL 降维：以 truncate_dim=256 输出 256 维向量，验证嵌套降维能力。

首次运行时权重加载约需 2 秒（SSD），看到 [OK] 全部通过 即部署成功。

3.3 Windows 独立虚拟环境的 DLL 避坑

本教程主线使用 conda 环境，天然避开一个 Windows 特有的深坑。如果你习惯用 venv 或 uv 创建独立虚拟环境，加载 GPU 版 torch 时可能遇到：

OSError: [WinError 1114] 动态链接库(DLL)初始化例程失败。

根因在于 conda 环境的 python.exe 启动时会自动把 %CONDA_PREFIX%\Library\bin 加入 DLL 搜索路径，而独立 venv 没有这个机制，导致 torch 的 CUDA 依赖 DLL 找不全。即使系统 VC++ 运行库是最新版也一样报错。解决办法是 overlay venv：借一个「已验证 GPU torch 可用」的 conda 环境做底座：

uv venv .venv-gpu --python <conda环境路径>\python.exe --system-site-packages
uv pip install --python .venv-gpu/Scripts/python.exe sentence-transformers -i https://pypi.tuna.tsinghua.edu.cn/simple
uv pip uninstall --python .venv-gpu/Scripts/python.exe torch
.venv-gpu/Scripts/python.exe -c "import torch; print(torch.__version__, torch.cuda.is_available())"

安装 sentence-transformers 时 uv 可能又装了一份 CPU 版 torch，第三行的卸载会让底座环境的 cu128 版透出来，最后一行输出 2.11.0+cu128 True 即为成功。

提示：新装机器直接用 conda 环境运行本项目是最省事的路线，本节仅作独立 venv 用户的排查参考。

4. 文本嵌入与语义检索快速上手

4.1 生成嵌入向量与相似度矩阵

run_demo.py 中加载模型与生成向量的核心逻辑如下：

import torch
from sentence_transformers import SentenceTransformer

# 原生支持 bf16 的显卡（SM 8.0 及以上）用 bfloat16，其余用 float32
cap = torch.cuda.get_device_capability()
dtype = torch.bfloat16 if cap >= (8, 0) else torch.float32

model = SentenceTransformer(
    model_dir,
    device="cuda",
    config_kwargs={"vision_config": None, "audio_config": None},  # 只加载文本主干
    model_kwargs={"dtype": dtype},
)
embeddings = model.encode(sentences)   # 归一化的 768 维向量，形状 (N, 768)
sims = model.similarity(embeddings, embeddings)  # 两两余弦相似度矩阵

两个关键点：

• dtype 必须按显卡代际选择。Turing 及更早架构没有原生 bf16，官方模型卡要求这类显卡使用 float32，强行用 bf16 会出现性能或精度异常。
• config_kwargs 把视觉与音频分支置空，只加载文本主干，显存占用从约 1.7GB 降到约 1GB。需要图文检索时去掉这个参数即可。

完整代码请查看 embeddinggemma2-demo/run_demo.py。

4.2 任务 prompt：检索质量的关键

EmbeddingGemma 2 针对不同任务训练了专用前缀 prompt，调用时通过 prompt_name 指定，选错 prompt 会明显掉分：

检索场景的标准写法是查询与文档分别使用对应的 prompt：

doc_emb = model.encode(documents, prompt_name="Retrieval-document")
query_emb = model.encode([query], prompt_name="Retrieval-query")
scores = query_emb @ doc_emb.T   # 归一化向量，内积即余弦相似度

查询与文档侧 prompt 必须配套使用，全部用默认编码会损失检索精度。

4.3 MRL 嵌套降维

模型支持 Matryoshka Representation Learning（MRL），训练时就把高维向量的前段设计成可独立使用的低维表示，取用时不需重新训练或微调：

emb_256 = model.encode(sentences, truncate_dim=256)   # 直接截断为 256 维

在 4.4 节的实测语料上，各维度下的表现如下：

检索命中率到 256 维都没有损失，存储成本却只有原来的三分之一，向量库场景建议优先尝试 256 维；128 维出现了 1 例 Top1 滑到 Top2 的情况，对召回率敏感的业务慎用。

4.4 文本能力基准实测

示例项目内置了一套离线评测脚本，覆盖相似度回归、语义检索、MRL 降维与吞吐量四个项目：

python test_model.py            # 全量基准，离线约 1 分钟
python test_model.py --chat     # 交互式语义搜索，输入查询返回 Top-5

评测语料为 24 对人工标注的中英句对（含反义、否定、一词多义压力样本）与 10 查询对 18 文档的检索集。核心结果：Spearman ρ 达 0.733（0.70 以上为良好水平），检索 Recall@1 与 MRR 均为满分，短文本吞吐量约 270~450 条/秒（随后台负载波动）。

压力样本同时暴露了稠密嵌入模型的通病，模型给分（换算到 0~5 分制）与人工标注 2.0 的对比：

「大涨」与「大跌」这类语义翻转句相似度反而接近满分，这是因为两者话题高度重合。该短板的工程对策见 6.3 节。

5. Web 语义搜索应用

5.1 演示服务架构

示例项目用 FastAPI 把模型能力包装成两个网页可用的接口：文本语义搜索与图文跨模态搜索，前端为单页应用：

服务地址与端口、模型路径、图库目录都集中在 config.py：

MODEL_DIR = r"C:\models\embeddinggemma-2"   # 模型目录
HOST = "127.0.0.1"                          # 服务地址
PORT = 8887                                 # 服务端口
IMAGES_DIR = "images"                       # 图文搜索的图片库目录
TOP_K = 10                                  # 最多返回条数

5.2 核心代码讲解

后端启动时完整加载模型（含视觉分支，图文检索需要），文本搜索接口的核心逻辑如下：

@app.post("/api/search/text")
def search_text(req: TextSearchRequest):
    doc_emb = model.encode(documents, prompt_name="Retrieval-document")
    query_emb = model.encode([req.query.strip()], prompt_name="Retrieval-query")
    scores = (query_emb @ doc_emb.T)[0]
    order = np.argsort(-scores)[: config.TOP_K]
    return {"results": [{"text": documents[i], "score": round(float(scores[i]), 4)}
                        for i in order]}

图文搜索接口的差别只在编码对象：把图库里的图片用 Image.open(...).convert("RGB") 打开后交给 model.encode()，输出的向量与文本查询同处一个空间，直接内积排序即可。上传的图片经 PIL 校验后统一重命名存入 images/ 目录，防止路径注入与非法文件。

完整代码请查看 embeddinggemma2-demo/main.py。前端页面的完整代码请查看 embeddinggemma2-demo/index.html。

5.3 启动服务与文本搜索

在示例项目根目录执行：

python main.py

启动过程约 5 秒，控制台会打印模型路径与设备信息。浏览器访问 http://127.0.0.1:8887，页面顶部的状态栏显示模型就绪状态、设备、精度、嵌入维度与图库数量。

在「文本语义搜索」标签页中，文档库每行一条，预置了 10 条中英混合示例文档，可以随意增删改。输入查询点击搜索，结果按余弦相似度从高到低排列，分数条直观展示差距：

实测查询「哪门编程语言能保证内存安全」，讲内存安全的 Rust 文档以 0.789 排第一，同话题的 Python 文档排第二，两者与后续无关文档的分数断层清晰。

5.4 图文跨模态搜索

切换到「图文跨模态搜索」标签页，点击上传区（或直接拖拽图片）把图片加入图库，示例项目已内置 7 张示例图片，开箱即可体验。用一句话描述想找的图，中英文均可：

实测查询「日落时湖面上粉紫色的晚霞」，晚霞风景照片以 0.717 排第一，手写书法类图片全部排在 0.65 以下，视觉语义检索的效果一目了然。图片库支持随时删除，上传的图片保存在示例项目的 images/ 目录中。

6. 图文检索实测与使用建议

6.1 示例图库与检索实测

示例项目内置 7 张内容各异的图片，覆盖书法、手写、照片、插画四类视觉风格：

运行图文检索脚本可复现完整测试：

python test_multimodal.py

6 条中英文查询的 Top1 全部命中，书写工具级别（毛笔与钢笔）的风格差异也能被稳定区分：

图图相似度矩阵进一步验证了聚类能力：五张手写/书法图片两两相似度平均 0.788，与照片、插画跨类图片的平均相似度只有 0.601；其中两幅毛笔作品之间相似度最高（0.888），说明风格聚类的粒度细于「手写与照片」的粗分类。

6.2 实测基准汇总

RTX 2080 Ti（fp32）上的完整实测结果如下，供部署后对照：

6.3 已知局限与使用建议

• 否定、反义与事实矛盾不敏感。4.4 节压力样本显示语义翻转句相似度普遍高达 4.6 以上（0~5 分制），这是稠密嵌入模型的共性短板。审核、矛盾检测等需要严格区分语义翻转的业务，应在向量召回之后接 reranker（交叉编码器）做二次精排，思路见前置教程中对 Rerank 的讲解。
• 图像嵌入不具备 OCR 能力。模型编码的是视觉语义。实测用诗句原文搜「写了这首词的书法作品」，写该词的两张图分列第 1、3 名，内容信号确实存在，但与「毛笔」等风格信号纠缠，按图中文字精确检索需搭配 OCR 加文本嵌入的组合方案。
• 老显卡务必用 float32。Turing（SM 7.5）及更早架构无原生 bf16，dtype 选择代码见 4.1 节。
• 检索必须配对使用任务 prompt。查询用 Retrieval-query、文档用 Retrieval-document，混用默认编码会掉点。
• 降维到 256 维是存储与召回的平衡点。128 维仅适用于对成本极敏感、可接受约 10% Top1 滑动的场景。

7. 总结

7.1 核心内容回顾

• EmbeddingGemma 2 用 740M 参数实现文本、图像、视频、音频到统一 768 维向量空间的多模态嵌入，Apache 2.0 协议，消费级显卡约 1.7GB 显存即可运行完整模型。
• 部署三步：conda 环境装 GPU 版 torch 与锁定版本的依赖，网盘模型包解压到 C:\models\embeddinggemma-2，运行 run_demo.py 验证。
• 检索质量两个关键开关：查询与文档分别使用 Retrieval-query / Retrieval-document 任务 prompt；利用 MRL 在 256 维实现零召回损失的存储优化。
• 示例项目的 Web 演示服务把模型能力变成了可交互的网页：文档库即改即搜的文本语义搜索，上传图片即可用文字搜图的跨模态检索。
• 实测基准：STS ρ 0.733、检索 Recall@1 100%、文搜图 6/6 命中、吞吐量数百条每秒，中小规模语义搜索与 RAG 建库场景完全够用。

7.2 常见问题与解答

问：没有 NVIDIA 显卡能跑本教程吗？

答：能。跳过 2.3 节的 GPU torch 安装，依赖会自动装上 CPU 版 torch，所有脚本与 Web 服务功能一致，只是编码速度明显变慢，适合功能验证。

问：加载模型时报 model type embedding_gemma2 but Transformers does not recognize this architecture 怎么办？

答：transformers 版本过旧，该模型发布较新，需要 5.19.0 及以上版本。requirements.txt 已锁定合规版本，此报错通常出现在往旧环境里混装依赖时，升级 transformers 即可。

问：独立 venv 里报 WinError 1114 动态链接库初始化例程失败？

答：这是 3.3 节讲解的 Windows DLL 搜索路径问题，conda 环境不受影响。坚持用独立 venv 时，按 3.3 节的 overlay 方案借 conda 环境做底座即可。

问：网页打不开或提示服务未连接？

答：确认 python main.py 正在运行且控制台打印了 Uvicorn running on http://127.0.0.1:8887；浏览器访问地址需与 config.py 的 HOST/PORT 一致。首次启动前确认 MODEL_DIR 指向已解压的模型目录，模型缺失时启动会直接报错提示路径。