EmbeddingGemma 2 API：本地部署与多模态应用场景

如果你在搜索 EmbeddingGemma 2 API，首先要分清两个容易混淆的产品：Google 托管的嵌入 API 是 Gemini Embedding 2，而 EmbeddingGemma 2 是一款主要面向本地和边缘推理的开放模型。它很适合构建注重隐私的多模态搜索系统，但代价是你需要自行选择并维护模型服务层。

EmbeddingGemma 2 是否提供 Google API？

EmbeddingGemma 2 已正式发布，但 Google 当前的托管 Gemini API 文档列出的是 gemini-embedding-2，而不是 embeddinggemma-2。EmbeddingGemma 2 模型卡和Google 开发者指南介绍的是一个可下载的模型，通常通过 Sentence Transformers 等本地库使用。

本地的 /v1/embeddings 端点由你部署的运行时提供，而不是 Google Cloud 提供。如果你想使用托管服务，请参考 Gemini Embedding 2 文档中的云端 SDK 和请求格式；模型名应使用 gemini-embedding-2，而不是 embeddinggemma-2。

from google import genai

client = genai.Client()
result = client.models.embed_content(
    model="gemini-embedding-2",
    contents="A private semantic search service",
)
print(result.embeddings)

上面的托管调用使用的是 Google 云端 API；本地模型则受你所部署运行时的凭据要求和资源限制约束。

EmbeddingGemma 2 本地模型里到底有什么

EmbeddingGemma 2 是一款拥有 7.4 亿参数的多模态嵌入模型。它将 2.7 亿参数的文本核心与可选的视觉、音频编码器分开设计，因此部署时可以只加载实际需要的模态。Google 和 DeepMind 将它定位为文本、代码、图像、视频和音频检索模型，而不是文本生成模型。

模型卡介绍了一个可用于跨模态比较的共享向量空间。740M 指的是完整模型的规模；Google 的开发者指南则展示了按需选择编码器的用法。因此，在只处理文本、无需加载视觉和音频模块时，运行时内存占用和实际计算量都可能更低。

根据部署目标选择服务方式

Python 应用：使用 Sentence Transformers

对于 Python 服务，官方文档推荐通过 Sentence Transformers加载 google/embeddinggemma-2 检查点。这种方式可以直接控制批处理、设备分配、提示词、归一化以及向量截断。

检索流程应当为查询和文档分别使用对应的指令。Google 的示例会为查询添加搜索查询前缀，并将文档组织成类似 title: none | text: ... 的格式。更稳妥的做法是，在 model.encode 中使用相应的提示词名称，而不是用一个通用调用同时处理两端。

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("google/embeddinggemma-2")

query_vector = model.encode(
    "How do I rotate an API key?",
    prompt_name="query",
    normalize_embeddings=True,
)
document_vectors = model.encode(
    [
        "title: API keys | text: Rotate keys from the security settings page.",
        "title: Billing | text: Download invoices from the billing page.",
    ],
    prompt_name="document",
    normalize_embeddings=True,
)

如果你需要在 Python 层面进行细致控制，选择这条路线；如果多个服务都需要稳定统一的接口，则应使用提供 HTTP 服务的运行时。

Ollama：快速搭建本地 REST 端点

Ollama 的 EmbeddingGemma 2 页面提供了一个简单的本地 API，地址为 http://localhost:11434/api/embed：

ollama pull embeddinggemma-2

curl http://localhost:11434/api/embed \\
  -d '{
    "model": "embeddinggemma-2",
    "input": "A private semantic search service"
  }'

Ollama 列出了 270m、440m、570m 和 740m 等模型标签；页面显示的安装包大小大约从 378 MB 到 1.3 GB 不等。应把它们理解为分别打包的模型变体，而不是完整 740M 检查点可以随意互换的标签。正式定义生产接口前，请先确认已安装的标签以及支持的输入模态：整个模型系列的定位是多模态，但页面上不同变体对各模态的说明并不完全一致。

无论选择哪种方式，你都需要保持任务前缀一致，确保模型和向量维度匹配；一旦更换模型，还需要重建索引。

边缘运行时：部署到设备端

Google AI Edge 在其Universal Embedder 指南中介绍了 EmbeddingGemma V2；而 LiteRT-LM 嵌入模型文档则说明了本地 OpenAI 兼容 /v1/embeddings 服务的实现方式。如果你更看重离线运行和设备端隐私，而不是传统云部署的便利性，这条路线更合适。

如果是在普通硬件上运行服务器，建议先从 Sentence Transformers 或 Ollama 开始。只有当离线运行、隐私、启动占用或设备集成成为核心要求时，再转向专门的边缘运行时。

哪些多模态场景值得使用更大的模型

当项目需要让不同媒体类型共享同一个检索空间时，EmbeddingGemma 2 的优势最明显。

代码搜索与开发者检索

已发布的评测表显示，在引用的代码基准测试中，EmbeddingGemma 2 的 MTEB Code 得分为 78.68，而 EmbeddingGemma 1 为 68.76。这使它值得用于代码仓库搜索、API 文档检索和面向代码的 RAG，但并不意味着它一定适合你的语言组合或代码库。

什么时候没必要迁移到更大的模型

如果你的流程只接收普通 OCR 文本，多模态支持可能会增加复杂度，却未必带来更好的检索质量。一位 Paperless-ngx 用户这样描述了其中的取舍：

“我不确定 embeddinggemma-2 处理 paperless-ngx 发送给模型的纯 OCR 文本时，是否真的比普通 embeddinggemma 更好。感觉只是多了很多工作，结果却一样。”——u/Great-Cow7256，Reddit

这不是基准测试结论，但它点出了迁移时最应该做的验证：先在自己的真实语料上比较检索质量，再决定是否重建一个已经能够正常工作的纯文本索引。

如何选择向量维度：768d、512d、256d 还是 128d

Google 的嵌入文档说明，EmbeddingGemma 2 支持类似 Matryoshka 的向量截断，因此可以在编码后选择更小的表示。更短的向量能够减少索引存储和传输开销，但在最激进的压缩设置下，质量也会下降。

以上数据来自 Ollama 模型页面公布的评测表。新建多模态索引时，可以从 768d 开始；如果存储空间比较紧张，可考虑 512d 或 256d；至于 128d，建议只有在测试过以文本为主的工作负载后再采用。

不要在同一个向量索引中混用不同维度。如果现有数据库存储的是 768 维向量，切换到 256d 就意味着必须重新嵌入已建立索引的文档，并重建索引。查询向量和文档向量必须使用相同的模型、提示词、归一化方式以及向量维度。

根据工作流做决定，而不是只看模型大小

需要托管 Google 端点时，使用 Gemini Embedding 2；需要在 Python 层面精细控制时，选择 Sentence Transformers；想快速搭建本地 HTTP 服务，可以使用 Ollama；如果重点是离线设备部署，则选择 AI Edge/LiteRT-LM。

如果语料只是普通 OCR 文本，并且现有索引已经达到相关性目标，就继续使用更小的纯文本模型。EmbeddingGemma 2 确实可以简化多模态架构，但不会自动提升纯文本架构的效果。

EmbeddingGemma 2 API 常见问题

EmbeddingGemma 2 能通过 Gemini API 使用吗？

Google 当前的托管 Gemini API 文档标识的是 gemini-embedding-2。EmbeddingGemma 2 主要作为支持本地推理的开放模型提供文档说明，不过本地运行时可以暴露兼容 API 的端点。

EmbeddingGemma 2 能在 CPU 上运行吗？

如果本地运行时明确提供 CPU 后端，就可以使用 CPU 推理；Google 的AI Edge 嵌入文档是相关运行时的参考资料。实际性能仍取决于硬件、量化方式、批大小和所使用的模态。

现有向量需要重建吗？

通常需要，尤其是在更换嵌入模型、任务格式、归一化策略或向量维度时。建议将模型标识、向量维度和预处理元数据一并记录在索引中，以便后续复现迁移过程。