DigUp 保姆级上手指南10分钟把发掘/检索项目跑起来【免费下载链接】DigUpSearch your computer by whats in your files: photos, PDFs, documents, recordings, videos and code. On-device on Mac, Windows and Linux, built on Google DeepMinds EmbeddingGemma 2.项目地址: https://gitcode.com/gh_mirrors/di/DigUp如果说 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 个 ForkMIT 协议开源无账号、无遥测。本文从零带你把项目跑起来先讲清楚它在挖什么再给出成品安装与源码构建两条路径然后走一遍digupCLI 的索引—检索最小闭环最后列出新手最常踩的坑与后续深入路线。一、先弄清楚 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 MacM 系列芯片和 macOS 14 或以上官方在 macOS 26 上测试过。这与它依赖 Metal 跑 llama.cpp 直接相关——想在 x86 或 Linux 上跑只能研究其架构而不能直接开箱。路线 A成品安装真正意义上的 10 分钟不想碰源码的话两条命令即可完成安装从 Releases 下载 DMG把 DigUp 拖入 Applications或用 Homebrewbrew 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要先切回 Xcodesudo 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 固定在 tagb11461EmbeddingGemma 2 最早可用的版本之后打上一个去掉 logits 输出的一行补丁——嵌入模型永远不会产生 logits但不打这个补丁每个输入 token 都会白白分配 1 MiB 的 26 万词表 logits。构建产物是静态库Vendor/llama/lib/libllamacpp.aMetal shader 在首次使用时编译无需额外工具链。工程结构在 Package.swift 里一目了然四个 target 各司其职DigUpKit引擎层无 UI——爬虫、抽取器、索引存储、搜索全部在这LlamaRuntimellama.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.swift768 维 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 中高亮词代码在编辑器里定位到行SpaceQuick 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需要 ffmpegbrew install ffmpeg即可它会在~/DigUpTestbed造出一个可随意删除的测试场包含四类内容real/你真实文件的 APFS 克隆样本零额外磁盘空间删除不影响原件切勿提交到 gitsynthetic/内容已知的合成媒体——含斑马/企鹅/鹦鹉的视频、TTS 语音、UI 截图、PDF、孟加拉语和阿拉伯语文档——这是自动评测的 ground truthtraps/爬虫必须处理对的边界情况被 Spotlight 误判为视频的 TypeScript 文件、真正的 MPEG-TS 视频、代码项目只应索引其中的截图、node_modules、隐藏目录、app bundle、迷你图标、600 个剪辑的数据集文件夹、带空格和非 ASCII 的文件名、重复图片code/四个带已知函数的小 git 仓库用于代码搜索评测。第二步确认模型就位CLI 会按顺序找模型文件$DIGUP_MODELS环境变量 →~/Library/Application Support/DigUp/Models→ Hugging Face 缓存。最省事的方式是让 App 装过一次模型或直接用hf downloadhf 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 --codesearch命令的输出设计得很工程化每条结果带 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 的 R1 / R5 / R10 与 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 的文件与文件夹隐私提示拒绝目录看起来是空的绝不能把读不了误当目录是空的。报错形如cant 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 foldernode_modules 等、looks like a dataset (skipped)600 个机器命名剪辑、in the cloud, not downloadediCloud 未落盘文件、app or bundle、small image低于 256px 的图标、code or data file代码项目内的源码默认不索引。这些大多符合预期若确实想收进索引CLI 提供了--include-code、--include-datasets、--exclude/--exclude-ext等开关。7. 构建测试床报 needs ffmpegscripts/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.swiftImageIO 解码缩略图、Vision OCR 读截图文字、PDFKit 逐页抽取→ Indexer.swift抽取与嵌入流水线、双索引同步→ Searcher.swift混合打分。worker/目录下的digup_worker.py是官方 mlx-vlm 参考实现的嵌入 worker用来做评测对照DIGUP_WORKER_DIRworker切换。关注质量工程细节Tests/LlamaRuntimeTests/ReferenceVectorTests.swift会用 Tests/LlamaRuntimeTests/Reference/vectors.json 里的参考向量校验每一次 llama.cpp 升级保证升级不改变向量、不逼用户重建索引——这是它敢固定模型版本并自动更新的底气。索引里记录了向量来源一旦来源不匹配检索前会直接报错而非静默产出不可比的结果。从一条git clone到跑通digup search a penguin再到读懂混合检索与评测闭环DigUp 既是开箱即用的生产力工具也是一个把本地多模态语义检索讲得明明白白的教科书级工程样本。剩下的就交给你的文件夹和想象力了。【免费下载链接】DigUpSearch your computer by whats in your files: photos, PDFs, documents, recordings, videos and code. On-device on Mac, Windows and Linux, built on Google DeepMinds EmbeddingGemma 2.项目地址: https://gitcode.com/gh_mirrors/di/DigUp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考