DigUp 保姆级上手指南:10分钟把"发掘/检索"项目跑起来
DigUp 保姆级上手指南:10分钟把"发掘/检索"项目跑起来
如果说 Spotlight 解决的是"我记不住文件名了"的问题,那么 DigUp 解决的是更进一步的那个问题——"我记得它长什么样、说了什么,但我完全忘了它在哪"。这个开源项目让 Mac 用户可以用一句大白话去检索整个磁盘里的照片、PDF、录音、视频乃至源代码:输入 "zebra in a video",它能把视频定位到斑马出现的那一秒;输入 "where they talk about sleep",它跳到播客里讨论睡眠的那一分钟。这一切都跑在本机,基于 Google DeepMind 的多模态嵌入模型 EmbeddingGemma 2,通过 llama.cpp 在 Apple Silicon 的 GPU 上推理。
DigUp 目前在 GitHub 上已收获 1500+ Star、99 个 Fork,MIT 协议开源,无账号、无遥测。本文从零带你把项目跑起来:先讲清楚它在"挖"什么,再给出成品安装与源码构建两条路径,然后走一遍 digup CLI 的索引—检索最小闭环,最后列出新手最常踩的坑与后续深入路线。
一、先弄清楚 DigUp 到底在"挖"什么
DigUp 的自我定位是一句话:"Describe it. Dig it up."——你负责描述,它负责挖。与向量检索、RAG 这些过去两年在开发者社区持续升温的话题一脉相承:把非结构化内容变成向量,再按语义距离召回。但 DigUp 把这条路线做成了一个普通 Mac 用户双击就能用的桌面应用,而不是一个需要自己搭服务的库。
它能在文件里找到这些东西(见 README.md):
- 视频里的画面:"zebra in a video" 直接定位到斑马出现的镜头时刻;
- 音频里的段落:"where they talk about sleep" 跳到播客对应的一分钟;
- PDF 的某一页:"the clause about pets in the lease" 打开租赁合同那一页并高亮关键词;
- 截图里的报错文本:"payment declined error" 能找到那张支付失败的截图;
- 跨语言检索:用英文搜可以命中用孟加拉语、阿拉伯语写的笔记,反过来也行(模型覆盖 100+ 种语言);
- 代码语义检索:
code: retry a failed call with backoff能找到项目里做指数退避重试的那个函数,无论它叫什么名字。
除了"按意思找",精确字符串同样重要。发票编号、错误码、人名这类内容不会被 embedding 精确保存,所以 DigUp 同时维护了一个 FTS5 关键词索引,对精确命中做加权——这正是 Searcher.swift 里混合检索(hybrid search)的设计:语义向量负责"意思",关键词负责"写死的字符"。
与 Spotlight 的本质区别
FAQ 里作者直接给出了答案:Spotlight 按文件名、文本和元数据检索;DigUp 额外按"内容展示了什么、说了什么"检索,并且能把结果定位到具体页面或时间点。两者互补,可以并存使用。
隐私底线
DigUp 对隐私的处理几乎是教科书级别的克制:README.md 明确写明"Nothing you index leaves your Mac"。它只在你选定的文件夹里读取内容,联网仅发生在两件事上——首次下载模型、每天一次检查更新(可关闭)。它从不读取密钥、证书、密码文件、~/.ssh 这类隐藏目录、应用包与缓存;对仅存在于 iCloud 云端的未下载文件直接跳过,绝不擅自拉取。对应的规则全部实现在 Rules.swift 里,包括跳过 node_modules、venv 等开发目录,以及用启发式识别"看起来像数据集"的文件夹(300+ 个机器命名媒体文件)并跳过。
二、环境准备:前置条件与获取代码
硬性门槛
DigUp 不是跨平台项目,需要 Apple Silicon Mac(M 系列芯片)和 macOS 14 或以上,官方在 macOS 26 上测试过。这与它依赖 Metal 跑 llama.cpp 直接相关——想在 x86 或 Linux 上跑,只能研究其架构而不能直接开箱。
路线 A:成品安装(真正意义上的 10 分钟)
不想碰源码的话,两条命令即可完成安装:
- 从 Releases 下载 DMG,把 DigUp 拖入 Applications;
- 或用 Homebrew:
brew install --cask arahim3/tap/digup
首次启动会下载 865 MB 的模型(文本部分 310 MB + 图像/音频编码器 555 MB,应用本体只有约 20 MB),下载期间可以在引导界面选好要检索的文件夹。之后在任何应用里按 ⇧⌘Space 呼出搜索面板,输入自然语言描述即可。从安装到第一次搜索成功,10 分钟是现实的时间。
路线 B:从源码构建(开发者的正确打开方式)
想改代码、跑评测、或者单纯想看看这个千星项目内部长什么样,走源码路线。前置要求:Xcode 26、git、CMake(或 uv)。README 特别提醒:如果 xcode-select -p 显示的是 Command Line Tools,要先切回 Xcode(sudo xcode-select -s /Applications/Xcode.app),因为 Command Line Tools 缺少 SwiftUI 和 Swift Testing 的宏。
git clone https://github.com/ARahim3/DigUp && cd DigUp
scripts/build-llama.sh # 编译 llama.cpp:固定 tag + 一行补丁,几分钟
swift build -c release && swift test
./build.sh # → build.noindex/DigUp.app
构建脚本 scripts/build-llama.sh 做了件很讲究的事:把 llama.cpp 固定在 tag b11461(EmbeddingGemma 2 最早可用的版本之后),打上一个"去掉 logits 输出"的一行补丁——嵌入模型永远不会产生 logits,但不打这个补丁,每个输入 token 都会白白分配 1 MiB 的 26 万词表 logits。构建产物是静态库 Vendor/llama/lib/libllamacpp.a,Metal shader 在首次使用时编译,无需额外工具链。
工程结构在 Package.swift 里一目了然,四个 target 各司其职:
DigUpKit:引擎层,无 UI——爬虫、抽取器、索引存储、搜索全部在这;LlamaRuntime:llama.cpp 绑定与 EmbeddingGemma 2 的加载推理;digup:开发者 CLI,同时是 App 的索引助手和查询编码器;DigUpApp:菜单栏 + 快捷键的主应用(产物名刻意不叫 "DigUp",避免与digupCLI 二进制在不区分大小写的磁盘上冲突)。
三、从 README 看懂核心概念速通
EmbeddingGemma 2:一切检索的地基
Google DeepMind 在 2026 年 10 月发布的多模态嵌入模型,740M 参数,Apache 2.0 开源。它的关键特性是把文本、图像、音频、视频放进同一个 768 维向量空间:一张海滩上的狗的照片,和一句 "a dog on the beach",向量距离很近;一段谈论睡眠的录音,和 "where they talk about sleep" 相邻。这正是 DigUp 能用一条查询同时给视频帧、PDF 页、照片排名的原因。
DigUp 跑的是 ggml-org 做的 Q8_0 量化 GGUF 版本(ModelFiles.swift 固定了仓库、revision 和两个文件的 SHA-256),文本模型与媒体编码器分开加载:查询时只需要 310 MB 的文本部分,且只在搜索期间驻留内存,用完即退。
索引:一个 SQLite 文件装下所有向量
架构在 README 里画得很直白:
your folders ─► readers (ImageIO, PDFKit, AVFoundation, Vision for screenshots)
─► EmbeddingGemma 2 on llama.cpp (Metal) ─► 一个 SQLite 文件:
每张图、每页 PDF、每段文本、每帧视频、每 30 秒音频一个向量 + 关键词索引
your words ─► 同一模型的文本部分 ─► 最近邻向量 + 精确词匹配
IndexStore.swift 的注释说得更直白:向量和描述它们的行放在同一个数据库里,崩溃永远不会导致两者失步;在这个规模(约 2 万向量、30 MB)下,对内存副本做暴力搜索只要几毫秒,"根本不需要向量数据库"。主索引是 index.sqlite,代码索引是独立的 code.sqlite——代码搜索有自己的语义标尺和关键词结果,开关代码搜索也只是删除一个文件的事。
向量的存储细节在 Vectors.swift:768 维 float16(每个 1.5 KB),用 mmap 映射以便真正释放内存,用 vImage 批量转 float32 打分。
混合检索与"诚实的结果"
Searcher.swift 实现了混合检索的核心逻辑:
- 语义:每条查询向量与索引全部向量做余弦相似度,按 z-score 归一化,只有显著突出的片段(
zGate,默认 2.0)才算语义命中——这也给了用户一个诚实的"没有找到"; - 关键词:FTS5 精确匹配得到 boost(默认权重 2.0),因为再好的 embedding 也记不住一张发票编号;
- 代码:关键词权重降到 1.0(代码里到处都是 "app"、"running" 这类词),按名字查定义处而非调用处。
快捷键速查(安装版用户必背)
| 按键 | 作用 |
|---|---|
| ⇧⌘Space | 从任意应用呼出搜索面板(可在设置里改) |
| ↓ ↑ | 在结果间移动 |
| ↩ | 打开结果:视频/录音定位到时刻,PDF 在 Preview 中高亮词,代码在编辑器里定位到行 |
| Space | Quick Look 预览(定位到页面或时刻) |
| ⌘↩ | 在 Finder 中显示 |
| ⌘C | 复制文件到剪贴板 |
| ⌘O | 在更大的窗口中以图片网格 + 过滤条件重复同一搜索 |
DigUp 常驻菜单栏,可以看到索引进度、暂停或打开设置。视频首次定位到时刻时,macOS 会询问是否允许 DigUp 控制 QuickTime Player——那是它实现"跳到那一秒"的方式,正常授权即可。
四、跑通第一个示例:CLI 最小闭环
源码路线自带一个开发者 CLI(.build/release/digup),它同时也是 App 的索引助手。用它跑一遍"索引—检索"是最短的学习路径。五个子命令在 Sources/digup/main.swift 里:
digup estimate <folder>... [--json] 预估会索引什么、首次索引多久
digup index <folder>... [--limit N] 同步索引并嵌入新内容
digup search <words>... [--kind K,K] [-n 10] [--json]
digup status 查看索引内容
digup eval <queries.json> [-n 10] 评测召回率(evals/ 提供用例)
第一步:造一个测试沙盒(强烈推荐)
直接指自己的目录做实验也行,但项目贴心地提供了 scripts/make-testbed.sh(需要 ffmpeg,brew install ffmpeg 即可):它会在 ~/DigUpTestbed 造出一个可随意删除的测试场,包含四类内容:
real/:你真实文件的 APFS 克隆样本(零额外磁盘空间,删除不影响原件,切勿提交到 git);synthetic/:内容已知的合成媒体——含斑马/企鹅/鹦鹉的视频、TTS 语音、UI 截图、PDF、孟加拉语和阿拉伯语文档——这是自动评测的 ground truth;traps/:爬虫必须处理对的边界情况:被 Spotlight 误判为视频的 TypeScript 文件、真正的 MPEG-TS 视频、代码项目(只应索引其中的截图)、node_modules、隐藏目录、app bundle、迷你图标、600 个剪辑的数据集文件夹、带空格和非 ASCII 的文件名、重复图片;code/:四个带已知函数的小 git 仓库,用于代码搜索评测。
第二步:确认模型就位
CLI 会按顺序找模型文件:$DIGUP_MODELS 环境变量 → ~/Library/Application Support/DigUp/Models → Hugging Face 缓存。最省事的方式是让 App 装过一次模型,或直接用 hf download:
hf download ggml-org/embeddinggemma-2-GGUF embeddinggemma-2-Q8_0.gguf mmproj-embeddinggemma-2-Q8_0.gguf --revision bfcd298762cc34d0357ece5ebdd31791a3a374d8
第三步:估时 → 索引 → 检索
# 预估:会索引哪些文件、首次索引大概多久
digup estimate ~/DigUpTestbed/synthetic
# 建立索引(首次嵌入全部内容;--limit N 可限制单批处理量)
digup index ~/DigUpTestbed/synthetic
# 查看索引状态:多少向量、各类型文件数、索引体积
digup status
# 检索:按语义 + 精确词混合打分
digup search "a penguin"
digup search "black and white striped animal"
digup search "payment declined error"
digup search "code: retry a failed call with backoff" --code
search 命令的输出设计得很工程化:每条结果带 kind(文件类型)、命中片段定位(PDF 页 p. 2、音频/视频 at 0:12 (sound)、代码 lines 8–29)、z-score 与关键词排名,最后一行还会告诉你这次查询编码器启动耗时多少、向量打分多少毫秒——这些正是做 A/B 评测时要盯的指标。
验证"挖"得准:跑官方评测
evals/ 目录里三份评测数据是作者衡量每次排名改动的事实基准:
- evals/synthetic.json:图片、截图、PDF 页、文档、音频、视频时刻、精确词、超长文件共 30+ 条查询,例如 "a penguin" 期望同时命中图片、重复副本和视频的 0–6 秒段;
- evals/code.json:代码语义查询("retry a failed call with exponential backoff")与按名查询("code: PaymentDeclined"),每条都标了期望命中的行区间;
- evals/multilingual.json:孟加拉语、阿拉伯语的文档/PDF/截图/音频跨语言检索。
跑法:先建好 testbed 并索引,然后
digup eval evals/synthetic.json
digup eval evals/code.json --code # 代码索引用独立参数
输出会给出每个 tag 的 R@1 / R@5 / R@10 与 MRR。作者在 CONTRIBUTING.md 里要求:任何改动搜索结果的功能,PR 前后必须各跑一次 evals 并附上两份结果。
五、常见报错与排查
1. 模型找不到:no embeddinggemma-2-Q8_0.gguf in ...
CLI 在模型缺失时会抛出 WorkerError.notFound,错误信息直接给出修复命令(hf download ... --revision bfcd298762...,见 LlamaModels.swift)。注意 App 只认 $DIGUP_MODELS 指向的目录——开发者自己的 Hugging Face 缓存不能遮蔽一次缺失的下载。
2. 索引指纹不匹配:re-run with --reindex
索引记录了生成它的模型版本与设置指纹。换模型或改设置后继续索引会报 fingerprintMismatch,提示 --reindex 重建。App 场景下由 Indexer.resetOnModelChange 自动处理(清空重嵌),CLI 场景需要手动 digup index --reindex。
3. macOS 隐私权限导致目录"读不了"
digup index 对每个文件夹做可读性校验(main.swift 里的 isReadable):如果被 macOS 的"文件与文件夹"隐私提示拒绝,目录看起来是空的,绝不能把"读不了"误当"目录是空的"。报错形如 can't read ... (macOS privacy settings?),去系统设置 → 隐私与安全里授权即可。一次授权失败不会拖垮整个索引批次。
4. xcode-select 指向 Command Line Tools
构建阶段最常见的坑:Command Line Tools 缺少 SwiftUI 与 Swift Testing 宏,swift build 会失败。用 sudo xcode-select -s /Applications/Xcode.app 切回完整 Xcode 再试。
5. 为什么 .ts 文件没被当视频?
macOS 的 Spotlight 会把大量 TypeScript 文件标记为 MPEG-2 视频。DigUp 的 Rules.swift 用 600 字节的嗅探区分:真正的 MPEG-TS 传输流每 188 字节同步字节 0x47,连续命中才算视频,否则按代码/数据文件处理。这是从真实开发者 Mac 上总结的经验——README 提到有人机器上 5.7 万个 .ts 文件全被 Spotlight 误判成电影。
6. 索引跳过了一堆文件?先看"为什么跳过"
digup estimate 和 digup index 会逐项打印跳过原因:skipped: developer folder(node_modules 等)、looks like a dataset (skipped)(600 个机器命名剪辑)、in the cloud, not downloaded(iCloud 未落盘文件)、app or bundle、small image(低于 256px 的图标)、code or data file(代码项目内的源码默认不索引)。这些大多符合预期;若确实想收进索引,CLI 提供了 --include-code、--include-datasets、--exclude / --exclude-ext 等开关。
7. 构建测试床报 "needs ffmpeg"
scripts/make-testbed.sh 依赖 ffmpeg 生成合成视频与音频,缺失会直接退出。brew install ffmpeg 后重跑即可。
六、跑起来之后:怎么继续深入
玩 CLI 的进阶姿势:scripts/dev-run.sh 可以把构建出的 App 指向 testbed、用独立的 .dev/ 目录存放索引、模型与设置,绝不碰真实文件夹、真实索引和真实设置,还能透传 -debugQuery "zebra" -debugSnapshot /tmp/panel.png -debugQuit YES 这类调试参数做无头快照。
读源码的推荐路线:按数据流读——Rules.swift(什么该索引)→ Crawler.swift(怎么走目录,只读元数据)→ Extractors.swift(ImageIO 解码缩略图、Vision OCR 读截图文字、PDFKit 逐页抽取)→ Indexer.swift(抽取与嵌入流水线、双索引同步)→ Searcher.swift(混合打分)。worker/ 目录下的 digup_worker.py 是官方 mlx-vlm 参考实现的嵌入 worker,用来做评测对照(DIGUP_WORKER_DIR=worker 切换)。
关注质量工程细节:Tests/LlamaRuntimeTests/ReferenceVectorTests.swift 会用 Tests/LlamaRuntimeTests/Reference/vectors.json 里的参考向量校验每一次 llama.cpp 升级,保证升级不改变向量、不逼用户重建索引——这是它敢固定模型版本并自动更新的底气。索引里记录了向量来源,一旦来源不匹配,检索前会直接报错而非静默产出不可比的结果。
从一条 git clone 到跑通 digup search "a penguin",再到读懂混合检索与评测闭环,DigUp 既是开箱即用的生产力工具,也是一个把"本地多模态语义检索"讲得明明白白的教科书级工程样本。剩下的,就交给你的文件夹和想象力了。
