magpie 本地语义搜索
内容提要
magpie 是一款本地语义搜索工具，支持文件、GitHub 星标和浏览器书签。它通过关键词和语义双路检索，支持文本与图片搜索，数据本地存储，不联网。用户可用快捷键快速查找，索引高效，支持多种文件格式，并注重隐私和性能优化。
延伸解读
本地优先与隐私设计
magpie 强调本地运行、不联网、不扫全盘，所有数据（包括索引、向量、缩略图）都存储在用户目录下的 SQLite 文件中。嵌入模型通过 ONNX 本地运行，下载完成后可完全离线使用。这种设计避免了云端处理带来的隐私泄露风险，适合对数据敏感的用户。但需注意，首次使用需下载约 700 MB 的模型，且模型下载源可切换至 hf-mirror.com 以应对网络问题。
混合检索机制
magpie 采用关键词（BM25）与语义（向量）双路检索，通过倒数排名融合（RRF）合并结果，避免直接加权因量纲不同而难以调参的问题。语义模型 e5 支持多语言，中文查询可命中英文内容。关键词路使用 FTS5 前缀匹配，支持边输入边出结果。这种设计兼顾了精确匹配与语义理解，但向量暴力比对在数据量极大时可能成为瓶颈，文章也提到未来可引入 sqlite-vec 优化。
索引与性能优化细节
magpie 在索引构建上做了多项优化：文件读取前嗅探二进制、基于 mtime 和哈希的改动检测、长文本分块嵌入（每块 1600 字符，重叠 200），以及 README 的清洗与身份头添加。全文索引使用 FTS5 外部内容表，避免数据冗余。这些细节提升了索引效率和检索准确性，但也意味着索引构建需要一定计算资源，尤其是首次索引大量文件时。
使用限制与注意事项
magpie 目前不支持 OCR，扫描件 PDF 和截图中的文字无法检索，只能按文件名查找。macOS 版本未签名，安装时需额外操作（如右键打开或执行 xattr -cr）。此外，向量暴力比对在数据量达到几十万块时可能需要更换检索结构。用户需注意这些限制，合理评估其适用场景。
Q&A
magpie 是什么？
magpie 是一款本地语义搜索工具，支持文件、GitHub 星标和浏览器书签的搜索。它通过关键词和语义双路检索，支持文本与图片搜索，数据本地存储，不联网。
magpie 支持哪些搜索源？
magpie 支持三个搜索源：本地文件、GitHub 星标和浏览器书签。本地文件需要手动添加目录，GitHub 星标需要提供 token，书签直接读取本地文件。
magpie 如何保护用户隐私？
magpie 完全本地运行，不联网，不扫描全盘，只索引用户显式添加的目录。数据存储在本地 SQLite 文件中，嵌入模型在本地运行，没有数据发出。
magpie 的快捷键有哪些？
magpie 使用 Alt+Space 唤出或收起面板，Tab 切换源，Shift+Tab 切换范围或排序，Enter 打开结果，Ctrl+Enter 将输入交给浏览器，Esc 清除图片查询、关闭设置或收起窗口。
magpie 支持哪些文件格式？
magpie 支持 78 种纯文本与代码扩展名，以及 PDF、docx、xlsx、pptx 等格式。视频、压缩包和二进制文件只索引文件名，图片（jpg、png 等）通过视觉模型进行语义搜索。
magpie 的语义搜索是如何工作的？
magpie 使用 e5 多语言模型进行文本嵌入，SigLIP 2 进行图片嵌入。文本和图片共享同一向量空间，支持跨语言搜索。检索时结合关键词（BM25）和语义（余弦相似度）两路结果，通过倒数排名融合。
magpie 如何处理长文档？
magpie 将长内容切块，每块 1600 字符，重叠 200 字符，每块生成一个向量。检索时按最佳块计分，避免长文档中关键信息被稀释。
magpie 如何安装？
可以从 GitHub Releases 下载安装包：Windows 有 NSIS 安装包，macOS 有 dmg（Apple Silicon），Linux 有 AppImage、deb、rpm。macOS 包未签名，需用 curl 安装或右键打开。也可以自行编译，需要 Rust、Node 和 pnpm。
