做本地 RAG 或站内语义搜索的人，过去都得维护一排嵌入模型：文本一个、代码一个、图像一个、音频一个，各自的内存预算和向量维度还不一样。10 月上旬 Google DeepMind 发布的 EmbeddingGemma 2 把这件事压缩成了一个 740M 参数的模型——文本、代码、图像、音频、视频全部映射进同一个 768 维空间，Apache 2.0 协议，权重已经挂在 Hugging Face 和 Kaggle。
我在自己的 Apple M4 MacBook 上把文本检索部分完整跑了一遍，过程踩了三个环境坑，也发现了一个官方文档没写清楚的行为差异。这篇文章把可复制的代码、真实耗时和踩坑过程全部写出来，你照着做就能在自己电脑上跑通。
它到底是什么
EmbeddingGemma 2 基于 Gemma 4 架构，740M 参数，但设计是模块化的：纯文本工作负载只需要约 270M 参数的骨干，视觉编码器（170M）和音频编码器（300M）按需加载。官方给出的几个关键数字：
- 8K token 上下文，是上一代 EmbeddingGemma 的 4 倍，官方称可一次处理约 5.5 分钟音频或 29 张图片；
- MTEB Code 从 68.76 提升到 78.68，官方称在 1B 以下多模态嵌入模型里领先；
- Matryoshka 表示学习：768 维向量可以直接截断到 512 / 256 / 128 维，官方称向量库存储最多省 6 倍；
- 上一代模型下载量已过 2000 万，这一代支持 sentence-transformers、Ollama、llama.cpp、vLLM、MLX 等一整排部署路径。
对我这种主要写中文技术博客的人来说，最实际的卖点是：数据不出本机。你完全可以像之前本地部署大模型那样，把检索这一环也留在本地。
实测环境
- 硬件：Apple M4 MacBook（arm64，10 核）
- 系统：macOS，Python 3.13.12（受管 venv）
- 依赖：sentence-transformers 6.1.0、torch 2.14.0、transformers 5.19.0、torchvision（后两个是踩坑后升级/补装的，下面细说）
- 模型：google/embeddinggemma-2，safetensors 权重实测 1489 MB
完整代码，可直接复制运行
先装依赖（注意 transformers 必须是 5.19.0 及以上，原因见下一节）：
python -m venv venv && source venv/bin/activate
pip install sentence-transformers torchvision
pip install "transformers>=5.19.0"然后是检索测试脚本：
import time
import numpy as np
from sentence_transformers import SentenceTransformer
t0 = time.time()
model = SentenceTransformer("google/embeddinggemma-2")
print(f"模型加载 {time.time()-t0:.1f}s，维度 {model.get_sentence_embedding_dimension()}")
docs = [
"如何用 Python 批量压缩图片并保持清晰度",
"本地部署大模型后如何搭建私人知识库",
"今天北京的天气适合骑车通勤",
"compress images in batch with Python while keeping quality",
"前端性能优化：首屏加载时间从 3 秒降到 1 秒",
]
query = ["免费图片压缩工具怎么用"]
doc_vecs = model.encode(docs, prompt_name="Retrieval-document")
q_vec = model.encode(query, prompt_name="Retrieval-query")
sims = doc_vecs @ q_vec[0] / (np.linalg.norm(doc_vecs, axis=1) * np.linalg.norm(q_vec[0]))
for doc, s in sorted(zip(docs, sims), key=lambda x: -x[1]):
print(f"{s:.4f} {doc}")我跑出来的真实结果（M4，权重 1489 MB，首次加载 15.5 秒）：
0.7980 如何用 Python 批量压缩图片并保持清晰度
0.7250 compress images in batch with Python while keeping quality
0.6020 今天北京的天气适合骑车通勤
0.5960 本地部署大模型后如何搭建私人知识库
0.6000 前端性能优化：首屏加载时间从 3 秒降到 1 秒中文查询命中了中文文档第一、英文同义句第二，语义排序完全正确。稳态吞吐我另测了一轮：200 条短文档 batch_size=64，编码耗时 0.98 秒，约 205 条/秒——这个速度做个人知识库的增量索引绰绰有余。
三个坑，全是我亲手踩的
坑一：transformers 版本不够，直接报 KeyError: 'embedding_gemma2'。 我第一轮用的是 venv 里现成的 transformers 5.17.0，加载时抛出「does not recognize this architecture」。EmbeddingGemma 2 的 model_type 是全新的 embedding_gemma2，5.19.0 才收录。如果你像我一样在旧环境里跑，先 pip install -U transformers。
坑二：升级完还不够，还得装 torchvision。 第二轮报的是 ModuleNotFoundError: Could not import module 'EmbeddingGemma2Processor'，追到堆栈底层是从 Gemma 4 的图像处理模块里 import torchvision 失败。哪怕你只想做纯文本嵌入，这个 processor 也会被加载——torchvision 是硬依赖，装上就好。这两个坑叠加起来，意味着官方 README 里”pip install sentence-transformers 就能跑”的说法对新环境并不成立，至少在我的 Python 3.13 + torch 2.14 组合上不行。
坑三：不传 prompt 也能跑，但分数会变。 我对比了带 Retrieval-query/Retrieval-document prompt 和裸 encode 的结果：不带 prompt 时查询「免费图片压缩工具怎么用」对第一条文档的相似度是 0.850，带 prompt 后降到 0.798；而且模型的 default_prompt_name 是 None——也就是说你不手动指定 prompt，它不会自动帮你加。语义排序两种方式都正确，但如果你打算用绝对阈值（比如「相似度 > 0.8 才算命中」）做过滤，带不带 prompt 会直接改变你的阈值含义。检索场景请明确传 prompt_name，并且阈值要按你自己的方式重新标定。
Matryoshka 截断：top-1 稳，全排序不稳
官方宣传「截到 128 维省 6 倍存储」，我实测了一把这个承诺的边界：768 维下的完整排序是 [0, 3, 2, 4, 1]，截断到 512 / 256 / 128 维后，top-1 全部保持不变，但完整排序都发生了变化。结论很实在：做召回（只要前几名）截到 256 甚至 128 维问题不大；如果你的下游有重排或者依赖完整排序的逻辑，截断前先验证一遍。
相似度的”地板值”比你想的高
看我跑出来的分数：连「今天北京的天气适合骑车通勤」这种完全无关的文档都有 0.60 左右的相似度，最大最小分差只有 0.2 左右。这是很多嵌入模型的通病——绝对余弦值不能直接当”相关度百分比”用。如果你从 OpenAI 或 Cohere 的云 API 迁移过来，原来调好的阈值基本要全部重标。这一点上我没有做与云端 API 的横向对比（未实测，需人工确认），只能提醒你迁移时留个心眼。
什么时候不建议用
- 纯文本、超大规模：740M 的多模态能力你用不上时，一个专用的纯文本嵌入模型可能更省。我的实测只覆盖了文本检索，图像/音频/视频编码器的实际效果未实测，需人工确认后再下结论。
- 对延迟极度敏感的移动端：官方说 Pixel 上量化后文本只需 191MB 内存，但我没有移动端设备验证（未实测，需人工确认）。桌面端首载 15.5 秒是实测的，做常驻服务没问题，做按需加载会明显卡。
- 需要像素级图像理解：它是嵌入模型不是 VLM，只输出向量，不能描述图片内容。想找图片描述能力请看别的。
这东西适合谁
一句话总结：如果你在做本地知识库、隐私敏感的站内搜索、或者跨模态媒体检索，EmbeddingGemma 2 是目前唯一一个「一个模型打包五种模态 + Apache 2.0 + 手机都能跑」的选项，环境踩坑成本大概半小时（就是我上面那三个坑）。如果你只是给博客加个语义搜索，从之前测评过的本地部署方案延伸过来搭一条「Ollama 生成 + 本地嵌入检索」的 RAG 管线，这台 M4 上的 205 条/秒吞吐量完全够用。
配套工具也可以串起来用：批量入库前先用图片压缩工具把图片瘦身再入库；如果团队要共享这套检索配置和 Prompt 规范，之前实测过的 TeamAI 的 Git 分发思路同样适用于嵌入管线的配置管理。更多 AI 工具的实战场景可以翻这篇应用指南。
嵌入模型这个品类，站里是第一次写。后面如果读者需求多，我打算再补一篇「EmbeddingGemma 2 + 向量库搭建完整本地 RAG」的进阶教程——想看的在评论区说一声。