多模态嵌入实战:用 EmbeddingGemma 2 4-bit 一站式编码图像、音频与视频
多模态嵌入实战:用 EmbeddingGemma 2 4-bit 一站式编码图像、音频与视频
EmbeddingGemma 2 4-bit 是面向 Apple Silicon 的多模态嵌入模型:它将 Google EmbeddingGemma 2 转换为 4-bit 量化格式,基于 MLX 框架运行,能一次性把文本、图像、音频、视频四种内容编码为归一化的 768 维向量,总权重仅约 1.1 GB,非常适合在 Mac 上构建跨模态向量检索系统。
📦 为什么需要"4-bit 版"?
完整版 EmbeddingGemma 2 使用 BF16 精度存储,显存/内存开销较大。而 mlx-community/embeddinggemma-2-4bit 采用了更激进的压缩方案:
| 项目 | 说明 |
|---|---|
| 量化模式 | affine,4 bits,group size 64 |
| 量化范围 | 文本编码器 + 音频投影层 |
| 保留 BF16 | 视觉塔、音频塔、视觉投影层 |
| 权重体积 | 1.098 GB(十进制) |
| 验证硬件 | Apple M3 Ultra |
简单说:该量化的量化,该保精度的保精度,在体积和嵌入质量之间做了平衡。模型架构与量化配置记录在 config.json 的 quantization 字段中。
🔍 模型概览:一个模型编码四种模态
EmbeddingGemma 2 内部由多个专用"塔"(encoder)组成,统一输出到 768 维空间:
- 文本塔:24 层,混合滑动窗口注意力 + 全注意力,支持超长上下文
- 视觉塔:16 层,patch size 16,每张图像最多 280 个 soft tokens
- 音频塔:12 层,16 kHz 采样率,40 ms/token,音频序列上限 280 token
- 视频:按 1 fps 抽帧(最多 32 帧),每段视频最多 140 个 soft tokens
所有模态的输出都会经过同一套后处理管线(见 modules.json):
- Transformer:编码器前向计算
- Pooling:mean 池化,且包含任务前缀(1_Pooling/config.json)
- Normalize:L2 归一化,输出单位向量(2_Normalize/config.json)
归一化后的向量可以直接用余弦相似度比较(similarity_fn_name: cosine,见 config_sentence_transformers.json),这是向量检索的标准做法。
💡 模型还支持 Matryoshka 截断:可以只取向量前 128 / 256 / 512 维再重新归一化,用更小的维度换取更低的存储与计算成本。
🚀 快速上手:3 步生成第一个嵌入
第 1 步:安装环境
pip install -U "mlx>=0.32.3" "transformers>=5.18.0"
同时需要安装包含 EmbeddingGemma 2 支持的 mlx-vlm 实现版本(README.md 中给出了对应的实现修订号)。
第 2 步:加载模型
from mlx_vlm.embedding_loader import load_embedding_model
from mlx_vlm.utils import get_model_path
from transformers import AutoTokenizer
path = get_model_path("mlx-community/embeddinggemma-2-4bit")
model = load_embedding_model(path)
tokenizer = AutoTokenizer.from_pretrained(path)
第 3 步:编码文本并计算相似度
inputs = tokenizer([
"task: search result | query: Which planet is known as the Red Planet?",
"title: none | text: Mars is known as the Red Planet.",
"title: none | text: Venus is often called Earth's twin.",
], padding=True, return_tensors="np")
embeddings = model(**inputs).text_embeds
print(embeddings[:1] @ embeddings[1:].T) # Mars 得分高于 Venus ✅
查询语句会明显更接近"火星"文档而远离"金星"文档——这就是嵌入模型检索能力的直观体现。
🎬 图像、音频、视频:多模态编码怎么做
文本只用到 AutoTokenizer,而图像/音频/视频需要通过多模态处理器(EmbeddingGemma2Processor)统一预处理:
from mlx_vlm import load
model, processor = load("mlx-community/embeddinggemma-2-4bit")
inputs = processor(images=[image], return_tensors="np") # image 为 PIL 图像
embedding = model(**inputs).text_embeds
各模态的关键预处理参数(来自 processor_config.json):
| 模态 | 关键参数 | 备注 |
|---|---|---|
| 图像 | patch 16、bilinear 重采样、280 soft tokens | 输入自动转 RGB |
| 音频 | 16 kHz、mel 特征 128 维、40 ms/token | 参数细节见 preprocessor_config.json |
| 视频 | 1 fps 抽帧、最多 32 帧、140 soft tokens | 帧数超限时均匀采样 |
这意味着你可以把"一张产品图 + 一段用户评价 + 一段语音"全部投进同一个向量空间,用余弦相似度跨模态检索。
🏷️ 任务前缀:容易被忽略的关键细节
EmbeddingGemma 2 对不同任务使用不同的指令前缀,全部定义在 config_sentence_transformers.json 中:
| 场景 | 前缀 |
|---|---|
| 检索查询(query) | task: search result | query: |
| 待检索文档 | title: none | text: |
| 句子相似度 | task: sentence similarity | query: |
| 分类 | task: classification | query: |
| 问答 | task: question answering | query: |
两条铁律:
- 查询侧和文档侧必须各自带上正确的前缀(上例中 query 和 document 前缀不同);
- 双方的嵌入维度必须一致(都用 768,或都截断到同一维度),否则无法比较。
📊 精度验证:4-bit 嵌入有多可靠?
官方用 Apple M3 Ultra 对五种输入做了数值冒烟测试(对比 PyTorch FP32 基线),完整数据在 validation.json:
| 输入类型 | 最低余弦相似度 | 最大绝对误差 |
|---|---|---|
| 图像 | 0.9904 | 0.0170 |
| 文本 + 图像 | 0.9864 | 0.0193 |
| 视频 | 0.9861 | 0.0212 |
| 文本 | 0.9809 | 0.0224 |
| 音频 | 0.9744 | 0.0371 |
所有输出均为有限的 768 维单位向量,文本检索冒烟测试中"火星"段落正确排在"金星"之前。
⚠️ 注意:这些是数值冒烟检查,不是检索质量基准(如 MTEB)。4-bit 版本存在可测量的嵌入漂移,如果你的业务对检索精度敏感,建议在自己的数据上对比 BF16 或 8-bit 版本。
🗂️ 仓库文件结构速查
| 文件 | 作用 |
|---|---|
| model.safetensors / model.safetensors.index.json | 模型权重(1816 个张量)及索引 |
| config.json | 架构、量化配置与各塔超参数 |
| processor_config.json | 多模态处理器配置(图/音/视频) |
| config_sentence_transformers.json | 任务前缀与相似度函数 |
| modules.json | 编码器 → 池化 → 归一化 模块链 |
| 1_Pooling/config.json | 池化方式(mean,含前缀) |
| 2_Normalize/config.json | 向量归一化配置 |
| tokenizer.json / tokenizer_config.json | 分词器 |
| validation.json | 精度验证完整数据 |
⚠️ 实用建议与常见坑位
- 保持 BF16,不要转 float16:非量化权重与激活都是 BF16,强行转 fp16 会引入额外误差。
- 多模态依赖处理器版本:图像/音频/视频输入需要能暴露
EmbeddingGemma2Processor的 Transformers 构建(上游为 5.18.0.dev0);纯文本路径不受影响。 - 前缀别忘:漏掉任务前缀会直接拉低检索效果,这是最常见的翻车点。
- 体积敏感就截断:对精度要求不极端的场景,可只用前 256 维,向量库存储和检索成本直降 3 倍。
- 多语言可用:模型面向多语言训练,中英文混合语料同样适用。
写在最后
embeddinggemma-2-4bit 把"一个模型、四种模态、一套向量空间"的体验带到了约 1.1 GB 的体积上,是 Apple Silicon 平台上搭建跨模态搜索、以图搜文、语音检索等应用的理想起点。模型沿用 Apache-2.0 许可,可放心用于个人与商业项目。