DigUp如何实现本地多模态搜索:llama.cpp + EmbeddingGemma 2 架构全解

原创2026-10-13 14:48:121,722 阅读

DigUp如何实现本地多模态搜索:llama.cpp + EmbeddingGemma 2 架构全解

DigUp 是一款完全运行在 Mac 本地的多模态语义搜索工具:它用 llama.cpp 在 Apple GPU 上运行 Google DeepMind 的 EmbeddingGemma 2 嵌入模型,把你的照片、PDF、录音、视频乃至代码切分成段落,各自变成一个 768 维向量存入本地 SQLite,再用"向量相似度 + 关键词精确匹配"的混合搜索帮你按"内容含义"找到文件——所有计算都在本地完成,文件从不离开你的 Mac。

DigUp 多模态搜索演示:在视频中定位斑马、在播客中跳转谈话时刻、在 PDF 中标出条款,并用英文、孟加拉文、阿拉伯文找到同一张海滩照片

统一向量空间:照片、PDF、录音为何能被同一句查询命中

EmbeddingGemma 2 是一个 740M 参数的多模态嵌入模型,它把文本、图像、音频放进同一个向量空间:海滩上狗的照片,会和"a dog on the beach"这句话落在相近的位置;一段谈到睡眠的播客,会和"where they talk about sleep"靠近。它理解 100 多种语言,所以你用英文搜,能命中孟加拉文或阿拉伯文写成的笔记。

用于测试的示例风景照片:绿丘、松树与太阳,经视觉编码器后与描述性文本落在同一向量空间

DigUp 的搜索正是基于这个共享空间:

  • 查询侧:你的话被编码成向量,毫秒级完成;
  • 索引侧:图片走视觉编码器(软 token 预算 70/140/280 等档位),音频按 30 秒一窗编码,文本直接编码;
  • 比较侧:查询向量与所有已存向量做点积,得到余弦相似度。

因为"一张视频的帧"和"一页 PDF 的文字"是同一空间里的向量,一句查询可以同时给视频帧和 PDF 页排序——这就是 digup search "zebra in a video" 能直接打开斑马出现的那一刻、code: retry a failed call with backoff 能定位到函数定义行的底层原因。

llama.cpp 如何把 EmbeddingGemma 2 跑上 Mac 的 GPU

DigUp 选择 ggml-org 发布的 Q8_0 GGUF 转换版本,通过 llama.cpp 在 Metal 上推理。模型分两个文件(见 ModelFiles.swift):

文件 大小 作用
embeddinggemma-2-Q8_0.gguf 310 MB 文本部分,查询编码只需它
mmproj-embeddinggemma-2-Q8_0.gguf 555 MB 图像 + 音频编码器

两个文件合计 865 MB,就是首次安装下载量的来源(应用本身只有约 20 MB)。为什么不用 F16?源码里写得很直接:模型的激活值会溢出 float16,Q8_0 是唯一稳妥的精度选择(ModelFiles.swift)。

一行补丁,省掉每个 token 约 1 MB 的浪费

llama.cpp 默认假设模型会输出 logits(下一个词的 262k 维概率分布),而嵌入模型从不产生 logits——不处理的话,每个输入 token 都会白占约 1 MiB 内存。DigUp 用一行补丁让"非因果的嵌入上下文"直接跳过 logits 预留(llama.cpp-no-logits.patch),并把 llama.cpp 固定到指定 tag(build-llama.sh 中的 TAG=b11461):

  • 补丁参数:build-llama.sh 的 PATCH=scripts/llama.cpp-no-logits.patch;
  • CMake 只构建需要的库:Metal 后端开启(-DGGML_METAL=ON)、Metal shader 内嵌编译、多模态库 mtmd 开启(build-llama.sh)。

上下文与批处理配置同样服务于嵌入场景:媒体输入给 2048 token 上限(够装一张 1120 token 的图或 30 秒音频),文本查询只需 512;池化方式为 mean,输出的均值向量再 L2 归一化后即最终向量(LlamaEmbedder.swift)。

进程架构:索引与查询为何各开一个随时退出的进程

"会不会拖慢我的 Mac"是这类本地模型应用绕不开的问题,DigUp 的答案是进程化(Engine.swift 的注释把整个思路讲清楚了):

  • 索引侧:应用启动辅助进程 digup index-service(位于 Contents/Helpers/digup),用 ImageIO / PDFKit / AVFoundation 读取文件、用 Vision 做截图 OCR,再在进程内加载完整模型(约 1 GB)做嵌入;干完活进程就退出,内存归还系统。提取本身很吃内存——光 Vision OCR 就常驻约 100 MB 的模型,所以必须放进程外。
  • 查询侧:打开搜索面板时才启动 digup worker,只加载 310 MB 的文本部分(约 0.25 GB),冷启动约 0.35 秒;空闲一段时间就自动退出,向量内存随之释放,关键词搜索不受影响。
  • 两者通信是极简的 JSON 行协议:一行请求、一行回复,模型加载完先报 {"ready": true} 再干活(协议在 digup_worker.py,Swift 侧客户端见 Worker.swift)。

这套设计保证:搜索永远不阻塞索引,索引永远不拖累搜索(SQLite 的 WAL 模式允许读写并发),空闲时应用回到"小而安静"。

用于参考向量测试的示例截图:模拟的文档界面,含红色高亮标题与蓝色按钮,是验证图像向量一致性的固定输入

768 维向量怎么存、混合搜索怎么打分

文件被切成可搜索的段落:图片、PDF 每一页(含扫描版)、文档段落、音频的 30 秒窗口、视频的关键帧(每 3 秒一帧)加音轨。每个段落的向量以 float16 存储(768 维 × 2 字节 = 1.5 KB),与文件名、关键词索引一起写进同一个 SQLite 文件。

搜索时的混合打分(Searcher.swift):

  1. 含义分:查询向量与每个向量做矩阵-向量乘(Accelerate 加速,float16 按块转 float32),得余弦相似度;
  2. 关键词分:SQLite FTS5 在文件名、OCR 文本、文档正文上做精确匹配,覆盖度加成权重 2.0;
  3. 融合:分数 = 含义z分 + 2.0 × 关键词覆盖度^1.5,查询若是"K7Q2LM"这类代码/ID,关键词权重再翻倍。

两个容易踩的坑,源码注释里都有答案:

  • 模态偏置:同一主题下文本向量的相似度天然高于图像/音频向量,直接比分会让 PDF 页永远压过照片。解法是先按模态减均值、再除以全局标准差做 z 归一化(Searcher.swift);
  • 精确词兜底:发票号、错误码这种"含义为零、字面一切"的内容,靠 FTS5 救回来——嵌入向量存不准一个单号,关键词能。

向量版本与 llama.cpp 更新如何互不破坏

索引会记录自己是用哪套"模型 + 运行时 + 精度"生成的向量(指纹),不同来源的向量绝不混用。关键是它记录的是 vectorVersion,而不是 llama.cpp 的构建号——一次不改向量的 llama.cpp 升级,索引就原样保留。

每次升级 llama.cpp 前,必须通过参考向量测试:用固定输入(多语言文本、截图、照片、30 秒音频)重新生成向量,与存好的参考库比对,余弦相似度必须 ≥ 0.999(ReferenceVectorTests.swift);不达标就继续用旧版本,或把 vectorVersion 加一、全部索引重嵌。

参考向量测试的固定输入:多语言文本、截图、照片与音频,用于每次 llama.cpp 更新时比对向量一致性

全链路总结:一条查询在本地走了多远

把前面的模块串起来,一次 ⇧⌘Space 搜索的完整路径是:

你的文件夹 ─► 提取器(ImageIO / PDFKit / AVFoundation / Vision)
             ─► EmbeddingGemma 2 on llama.cpp(Metal,独立进程,用完即退)
             ─► 一个 SQLite:图片、页、段落、帧、30 秒音频的 768 维向量 + 关键词索引
你的话     ─► 文本编码器(~310 MB,仅搜索时加载)─► 最近邻向量 + 精确词

几个值得记住的数字:向量 768 维、每条 1.5 KB;下载 865 MB(310 + 555 MB),只下一次;查询冷启动约 0.35 秒;空闲时模型内存归零;应用上线只为下载模型和每日更新检查,无任何账号与遥测。

延伸阅读(仓库内相对路径):

登录后查看全文
DigUp