实战案例:用embeddinggemma-2-bf16构建免费私有的本地多模态RAG检索系统
实战案例:用embeddinggemma-2-bf16构建免费私有的本地多模态RAG检索系统
embeddinggemma-2-bf16 是 Google EmbeddingGemma 2 的 MLX 转换版本,可在 Apple Silicon 芯片上完全离线、免费运行,为文本、图像、音频、视频统一生成 768 维向量表示。本实战案例将带你用它在本地搭一套私有 RAG(检索增强生成)检索系统:数据不出设备、不产生任何 API 调用费用,还能跨模态"以文搜图、以文搜音频"。
为什么选择 embeddinggemma-2-bf16 搭建本地 RAG 检索?
很多新手做 RAG 检索时,习惯调用云端 Embedding API——好用,但按量收费,且文档必须上传到第三方服务器。如果你需要处理内部资料、客户合同、私有图片库,本地部署就是刚需。
📦 模型核心参数一览:
| 参数 | 说明 |
|---|---|
| 向量维度 | 768 维(支持 128 / 256 / 512 / 768 的 Matryoshka 截断) |
| 权重体积 | 1.489 GB(BF16 精度存储) |
| 支持模态 | 文本、图像、音频、视频 |
| 语言 | 多语言(multilingual) |
| 相似度度量 | 余弦相似度(cosine) |
| 运行框架 | MLX(专为 Apple Silicon 优化) |
| 许可证 | Apache-2.0(可商用、可私有化) |
💡 RAG 检索系统三大支柱,这套方案全部满足:
- Embedding 模型:把文档切片和用户问题变成同一向量空间里的坐标;
- 向量检索:用余弦相似度找出最相关的 Top-K 片段;
- 本地运行:Mac 上即可推理,无需 GPU 服务器、无需联网。
3 分钟准备:一键安装步骤
整个环境准备只需 3 步,全程免费。
第 1 步:克隆模型仓库
git clone https://gitcode.com/hf_mirrors/mlx-community/embeddinggemma-2-bf16
第 2 步:安装 MLX 推理依赖
pip install -U "mlx>=0.32.3" "transformers>=5.18.0"
⚠️ 注意:还需安装带 EmbeddingGemma 2 支持的
mlx-vlm版本,以及兼容的多模态处理器版本,具体版本要求见仓库 README.md。纯文本检索只需AutoTokenizer,依赖最简。
第 3 步:确认模型文件完整
克隆下来后,核心文件应该齐全——主权重由 model.safetensors.index.json 索引(共 1376 个张量,全部 BF16),首次运行时会自动缓存到本地。
快速上手:3 行代码检索你的知识库
下面是官方示例中最小的可用流程:加载模型 → 对"问题 + 候选文档"编码 → 用余弦相似度排序。注意查询和文档要分别加上不同的任务前缀(后文详解):
from mlx_vlm.embedding_loader import load_embedding_model
from transformers import AutoTokenizer
model = load_embedding_model("./embeddinggemma-2-bf16")
tokenizer = AutoTokenizer.from_pretrained("./embeddinggemma-2-bf16")
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 # 归一化后的 768 维向量
scores = embeddings[:1] @ embeddings[1:].T # 余弦相似度
运行后你会发现:Mars 片段的得分 0.83,Venus 片段只有 0.68——正确的答案稳稳排在第一位(该数据来自转换验证,详见 validation.json)。
多模态检索:一段文本搜出图片、音频和视频
这是它和普通文本 Embedding 模型最大的区别:所有模态被映射到同一个 768 维空间,所以"以文搜图""以文搜音频"天然成立。
from mlx_vlm import load
model, processor = load("mlx-community/embeddinggemma-2-bf16")
inputs = processor(images=[image], return_tensors="np") # image 为 PIL 图片
embedding = model(**inputs).text_embeds
各模态的预处理参数都定义在 processor_config.json 中:
| 模态 | 预处理配置 | 说明 |
|---|---|---|
| 图像 | Gemma4ImageProcessor,patch 16 |
每张图编码为 280 个 soft token |
| 音频 | Gemma4AudioFeatureExtractor,16kHz |
编码为 280 个 token |
| 视频 | EmbeddingGemma2VideoProcessor |
最多采样 32 帧,140 个 soft token |
| 文本 | GemmaTokenizer,词表 262144 |
支持超长上下文(最大 262144 位置) |
🔍 实战场景举例:把你的产品图库 + 说明文档 + 客服录音全部编码入库,用户输入一句文字描述,就能同时命中相关的图片、文档片段和语音记录——这就是"本地多模态 RAG"的完整形态。
文件目录导览:关键配置文件速查
仓库结构清晰,每个文件各管一摊:
embeddinggemma-2-bf16/
├── README.md # 官方使用说明(安装、调用、验证)
├── config.json # 模型主配置:文本/视觉/音频三大编码器
├── model.safetensors.index.json # 权重索引(1376 个 BF16 张量)
├── modules.json # sentence-transformers 流水线定义
├── 1_Pooling/config.json # 池化:mean(均值池化)
├── 2_Normalize/config.json # 归一化:单位向量输出
├── config_sentence_transformers.json # 各任务前缀 + 相似度函数
├── processor_config.json # 图像/音频/视频预处理参数
├── tokenizer_config.json # 分词器配置(含多模态特殊 token)
├── chat_template.jinja # 多模态对话模板
└── validation.json # BF16 转换的验证数据
📌 编码流水线由 modules.json 定义,分三步:
- Transformer 编码器:文本/图像/音频/视频特征提取(定义于 sentence_bert_config.json);
- 均值池化(1_Pooling/config.json):把 token 级表示压缩为 768 维句向量;
- 归一化(2_Normalize/config.json):单位化后,点积即余弦相似度,检索时可直接用矩阵乘法加速。
进阶技巧:4 个让检索效果更好的实践
1️⃣ 查询和文档要加不同的任务前缀
这是最容易忽略、却影响最大的细节。不同任务对应的前缀定义在 config_sentence_transformers.json:
| 任务 | 前缀 |
|---|---|
| 检索查询(Retrieval-query) | task: search result | query: |
| 检索文档(Retrieval-document) | title: none | text: |
| 问答(QuestionAnswering) | task: question answering | query: |
| 句相似度(STS) | task: sentence similarity | query: |
| 分类 / 聚类 / 代码检索 | 见原文件 |
2️⃣ 用 Matryoshka 截断降低存储成本
768 维向量可以直接截取前 128 / 256 / 512 维并重新归一化,用于大规模语料的低成本召回。比如向量库有百万级文档时,用 256 维初筛 + 768 维精排,是常见的高性价比组合。
3️⃣ 保持 BF16,不要转 float16
官方明确建议:权重和激活值都保持 BF16 精度,不要向 float16 强转,否则会损失数值稳定性。
4️⃣ 查询与文档必须用相同维度
做相似度比较前,确保两边嵌入维度一致(都做同样的截断 + 归一化),否则分数不可比。
验证数据:BF16 转换会影响精度吗?
对于担心"转换版本不如原版"的同学,仓库里有一份完整的数值验证报告(validation.json),所有输出均为有限值、单位归一化、768 维。与 PyTorch FP32 原始实现对比:
| 输入类型 | 最低余弦相似度(vs FP32) | 最大绝对误差 |
|---|---|---|
| 文本 | 0.999937 | 0.001468 |
| 图像 | 0.999954 | 0.001135 |
| 音频 | 0.999947 | 0.001258 |
| 文本 + 图像 | 0.999905 | 0.001864 |
| 视频 | 0.999900 | 0.001688 |
余弦相似度全部在 0.9999 以上,且 BF16 转换与源检查点逐位一致(bit-identical)——转换损耗完全可以忽略。
写在最后
✅ 用 embeddinggemma-2-bf16 搭一套本地多模态 RAG 检索系统,门槛其实很低:
- 免费:Apache-2.0 许可,1.5 GB 权重本地运行,无按量计费;
- 私有:所有数据不出设备,适合合同、内部文档、私有素材库;
- 多模态:文本、图片、音频、视频统一进一个 768 维空间,检索一次全命中;
- 可压缩:Matryoshka 截断让大规模向量库成本再降一档。
下一步,你可以把文档切片工具(如分块 + 编码 + 入库)接上任意本地向量库,再用一个开源 LLM 做答案生成——一条完整、私有的 RAG 流水线就跑通了。更多调用细节请参考仓库的 README.md。