unsloth/embeddinggemma-2-GGUF · Hugging Face

来源：https://huggingface.co/unsloth/embeddinggemma-2-GGUF

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#read-our-how-to-run-embeddinggemma-2-guide阅读我们的《如何运行 EmbeddingGemma 2》指南！ (https://unsloth.ai/docs/models/embeddinggemma-2)

Hugging Face (https://huggingface.co/google/embeddinggemma-2) | GitHub (https://github.com/google-gemma) | 发布博客 (https://blog.google/innovation-and-ai/technology/developers-tools/embeddinggemma-2) | 文档 (https://ai.google.dev/gemma/docs/embeddinggemma) | 许可协议：Apache 2.0 (https://ai.google.dev/gemma/docs/gemma_4_license) | 作者：Google DeepMind (https://deepmind.google/models/gemma/)

EmbeddingGemma 2 是 Google DeepMind 构建的开源多模态 embedding 模型，能够将文本（含代码）、图像、视频和音频输入——以及它们的任意组合——映射到同一个统一的 768 维向量空间中。模型总参数量为 7.4 亿，由一个 2.7 亿参数的文本模型与模块化的视觉（1.7 亿）和音频（3 亿）编码器组合而成。

EmbeddingGemma 2 专为在移动设备、笔记本电脑等消费级硬件上运行而设计，可为端侧应用（如搜索、检索增强生成（RAG）、分类和聚类）提供低延迟的语义表示。

EmbeddingGemma 2 在 Gemma 4 的架构和能力基础上进一步提升，具备以下核心特性：

• **原生多模态：**将四种模态（文本、图像、视频和音频）统一到同一个共享的 768 维 embedding 空间中。
• **多语言与代码：**EmbeddingGemma 2 支持 100 多种语言，在代码任务上相比前代模型提升约 14%。
• **灵活的模型体积：**由 2.7 亿参数的文本骨干（1.3 亿 transformer + 1.4 亿 embedder）与可按需加载的视觉（1.7 亿）和音频（3 亿）编码器组合而成，开发者可以只加载自己用例所需的模态。
• Matryoshka 表示学习（MRL）：原生支持将嵌入截断到 128d、256d、512d 和 768d，最高可降低 6 倍的向量存储成本，而质量损失极小。
• **上下文长度：**8K token 上下文窗口，能够处理数分钟的音频或视频。
• **任务导向的表示：**通过轻量级的文本指令前缀，针对不同任务（搜索、分类、聚类、语义相似度等）优化 embedding。

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#model-overviewModel 概览

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#benchmark-results基准测试结果

EmbeddingGemma 2 在文本、代码、视觉、视觉文档、视频和音频 embedding 基准上进行了评估。以下报告的所有结果均使用全精度检查点。

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#overall-evaluation-results-768d整体评估结果（768d）

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#evaluation-results-with-vector-truncation向量截断后的评估结果

借助 MRL，EmbeddingGemma 2 的表示可以截断到低于原生 768d 的 128d、256d 和 512d 表示，并进行重新归一化。这样模型用户可以降低存储需求，直到 256d 质量损失都很小。128d 最适合纯文本负载。

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#quick-start快速开始

安装 sentence-transformers 库：

pip install -U sentence-transformers transformers

生成文本嵌入：

from sentence_transformers import SentenceTransformer

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

query = "What causes the northern lights?"
document = "The northern lights are caused by charged particles from the sun."

query_emb = model.encode(query, prompt_name="SearchQuery")
doc_emb = model.encode(document, prompt_name="Document")
print(model.similarity(query_emb, doc_emb))

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#best-practices最佳实践

为了获得最优的 embedding 质量和运行时效率，请遵循以下配置和最佳实践：

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#1-task-instruction-prefixes1. 任务指令前缀

EmbeddingGemma 2 在训练时会在文本输入前附加简短的任务指令前缀。使用正确的前缀可以提升质量；省略前缀仍然可用，但会降低精度。前缀仅适用于文本。图像、视频和音频输入不需要附加任何前缀。

带有真实标题的文档应格式化为 title: \{title\} \| text: \{content\}。没有标题时使用 title: none。

前缀表示法与用法

我们根据 embedding 在任务中的使用方式提供两类任务前缀。任务分为两种类型：

• **非对称任务（例如检索）：**查询使用查询前缀，语料库条目使用文档前缀。
• 对称任务（例如分类、相似度）：对所有需要比较的输入应用相同的任务前缀。

请注意：prompt\_name="Document" 会应用 title: none；带标题的文档仍必须手动格式化，例如 model\.encode\(f"title: \{title\} \| text: \{document\}"\)。

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#2-selective-encoder-loading2. 选择性加载编码器

视觉和音频编码器是独立组件。为了在部署纯文本或单模态流水线时降低内存消耗，可以通过 SentenceTransformer 的 config\_kwargs 禁用未使用的模态编码器：

**请注意：**不同模型库在加载 EmbeddingGemma 2 时省略部分编码器的配置方式有所不同；请参阅相应文档以获取更多信息。

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#3-matryoshka-dimension-truncation3. Matryoshka 维度截断

EmbeddingGemma 2 使用 Matryoshka 表示学习进行训练，因此 768 维输出向量可以通过仅保留前若干维度来缩短。支持的维度为 768、512、256 和 128。更短的向量可以降低存储开销并加快相似度搜索速度，但会牺牲一定的质量。

运行时请遵循以下指南：

• **截断后必须重新归一化：**切分单位长度向量无法保持单位长度。缩短后的向量在用于余弦相似度之前必须进行 L2 归一化。跳过这一步会悄悄降低排序质量——它会产生看似合理的分数，而不会报错。
• **查询和文档必须共享相同维度。**768 维的查询无法与 128 维的语料库进行评分。
• 为了避免自己进行截断和归一化，你可以在调用 model\.encode\(\) 时传入 truncate\_dim 和 normalize\_embeddings 字段：

query_emb = model.encode(
   query,
   truncate_dim=128, # 或 512、256
   normalize_embeddings=True,
)

各维度下的模型质量在上文基准测试结果部分的截断表格中列出。低至 256 维时质量接近无损。128 维会显著降低多模态质量，采用前应针对你自己的工作负载进行验证。

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#4-numerical-precision4. 数值精度

请使用 bfloat16 或 float32 运行推理。不要使用 float16。

EmbeddingGemma 2 的激活值范围超出了 float16 的动态范围。在 float16 下，模型会返回 NaN 或悄悄退化的嵌入，而不是抛出错误，因此失败很容易被忽略。

bfloat16 是安全的，与 float32 具有相同的 8 位指数。这是支持原生 bfloat16 的硬件上推荐的默认设置，相比 float32 可节省一半内存。在其他场景（包括大多数 CPU 上）请使用 float32。

在 SentenceTransformers 中，可以通过 model\_kwargs 进行设置，并通过 is\_bf16\_supported 以编程方式判断：

dtype = torch.bfloat16 if torch.cuda.is_bf16_supported() else torch.float32

model = SentenceTransformer("google/embeddinggemma-2", model_kwargs={"torch_dtype": dtype})

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#5-multimodal-input5. 多模态输入

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#interleaving交错输入

单个输入可以将文本与图像、视频和音频混合使用，共享同一个 8,192 token 的上下文。

每个媒体项在序列中的位置通过模型词表中的占位符 token 在文本中标记：

• <\|image\|> 标记图像输入的位置
• <\|video\|> 标记视频输入的位置
• <\|audio\|> 标记音频输入的位置

例如，一个为搜索建立索引的商品列表可能被编码为：

emb_interleaved = model.encode({
    "text": "Waterproof running shoes. <|image|> Featuring a breathable mesh upper. <|image|> Grip test on wet rock: <|video|>",
    "image": ["shoe.jpg", "mesh.jpg"],
    "video": "demo.mp4",
})

文本中的每个占位符会按顺序从对应键中填充。该调用返回一个同时表示文本、图像和视频的单一嵌入。该嵌入可以直接与任何其他 EmbeddingGemma 2 嵌入进行比较；例如，一个纯文本查询如 “waterproof shoes for trail running”。

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#context-limits上下文限制

所有模态共享同一个 8,192 token 的上下文窗口。每个模态以固定速率消耗这一配额：

请注意，当使用较低的视觉 token 预算（见下文）时，图像和视频的最大输入可达约 114 张图或帧。

上述最大值假设为无伴随文本的单一模态。交错输入消耗同一个配额，因此混合模态会减少每种模态可容纳的量。另请注意，当使用较低的视觉 token 预算（见下文）时，图像和视频的最大输入可达约 114 张图或帧。

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#vision-token-budget视觉 token 预算

模型用户可以放弃输入图像 / 视频帧的默认序列长度，改用 70 到 1120 之间的“软 token“数量来表示图像。为输入图像增加视觉预算会以延迟和 token 数量为代价换取质量。

一般来说，更长的输入序列长度能捕获更多信息。扩大输入序列长度意味着更富有表现力的输入表示；因此，增加输入序列长度会改善细粒度视觉理解，提升嵌入质量以及下游用例中的性能。

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#input-sampling-defaults输入采样默认值

音频和视频输入的默认采样率如下：

• 默认情况下，视频以每秒 1 帧的采样帧通过视觉编码器处理；FPS 采样率可配置。
• 音频应以单声道 16 kHz提供。

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#model-data模型数据

我们的预训练数据集是大规模、多样的数据集合，涵盖广泛的领域和模态，包括网页文档、代码、图像、视频和音频，数据截止日期为 2025 年 1 月。其中包括：

• **网页文档：**多样的网页文本确保模型接触到广泛的语言风格、主题和词汇。训练数据集包含 140 多种语言的内容。
• **代码：**让模型接触代码有助于它学习编程语言的语法和模式，从而提升其理解代码相关语义的能力。
• **图像：**多样的图像使模型能够执行图像分析和视觉数据提取任务。
• **视频：**覆盖多样视觉场景、人类动作和时序动态的视频序列和片段。
• **音频：**涵盖多种语言的语音录音、环境声音和声学事件。
• **跨模态样本：**成对的文本、图像、视频和音频数据，用于对齐不同模态间的表示。

https://huggingface.co/unsloth/embeddinggemma-2-GGUF#data-processing数据处理

对训练数据应用了多种数据清洗和过滤方法：

• CSAM 过滤：在数据准备过程的多个阶段实施了严格的 CSAM（儿童性虐待材料）过滤，以确保排除有害和非法内容。
• 敏感数据过滤：作为让 Gemma 预训练模型安全可靠的一部分，使用自动化技术从训练集中过滤掉某些个人信息和其他敏感数据。
• 其他方法：基于内容质量和安全性进行过滤，符合