LEANN：把个人数据装进笔记本的本地 RAG 索引

把私人文档、邮件、聊天记录和代码都拿来做语义检索，第一个撞上的问题是索引比原文还大。传统向量库会给每个文本片段保存一份 embedding，文档规模上去之后磁盘占用很快失控。LEANN 换了一条路：图结构选择性重算（graph-based selective recomputation）配合保度剪枝（high-degree preserving pruning），embedding 按需现场计算，不常驻落盘，只保留压缩过的图。README 给出的对照是 6000 万个文本片段占 6GB，同类方案要 201GB。

LEANN 是一个 Python 写的本地向量索引库：把文件、邮件、聊天记录、代码切段后建语义索引，输入查询、输出相关片段，索引体积比传统方案小约 97%。

它的实际形态是一个 Python 包加一组应用示例。README 里列出的可索引对象包括文件系统里的 PDF、TXT、MD，Apple Mail 邮件，浏览器历史，微信和 iMessage 聊天记录，ChatGPT 与 Claude 的对话历史，Slack 消息、Twitter 书签，以及代码库。查询侧可以接 Claude Code，仓库把这条能力做成 MCP 服务，原因是 Claude Code 自身只支持基本的 grep 式关键字搜索。

项目仓库地址是 https://github.com/StarTrail-org/LEANN ，采用 MIT 许可证，主要语言为 Python（占 99.1%）。截至 2026-09-30 的仓库数据是 12983 Star、1175 Fork、79 Watcher、45 个开放 Issue，最新版本 v0.3.8 发布于 2026-09-28。项目论文见 https://arxiv.org/abs/2506.08276 。

它不做什么

LEANN 不提供托管服务，也不调用云端 API。README 明确写了这句定位：数据不离开本机，没有 OpenAI、没有云、没有服务条款。

它也不把自己包装成开箱即用的知识库产品。仓库交付的是 Python 包、MCP 服务端和一批评测/示例应用，界面和上层的对话逻辑要自己接。

平台信息有两处不完全一致的地方。README 的平台徽章标注支持 Ubuntu、Arch、WSL、macOS（ARM64/Intel）和 Windows；同时 Issue 列表里「Add support for Windows」以 [待解决] 状态挂着，并标注了 Many requests。仓库里没有说明这两处信息的差异在哪里。

macOS 上如果要构建 DiskANN 后端，系统版本需要 13.3 或更高。

用之前先准备好什么

• Python 3.10、3.11、3.12、3.13 或 3.14。
• uv。README 把它列为前置依赖，安装方式是 curl -LsSf https://astral.sh/uv/install.sh | sh。
• 从源码构建时要拉子模块；macOS 还需要先装 libomp、boost、protobuf、zeromq、pkgconf。
• 一个 embedding 模型。Issue 里出现过的配置是 BAAI/bge-large-zh-v1.5；也支持把 Ollama 作为 embedding 提供方。
• 要索引的数据本身。仓库没有说明各类数据源的导出步骤分别是什么，只有 Issue 里出现过一位用户贴出的 ChatGPT 数据导出流程。

主要功能

• 建索引：核心命令是 leann build，Issue 里的写法为 leann build my-code-index --docs ./src --use-ast-chunking，第一个参数是索引名，--docs 指向待索引目录。
• 按需重算 embedding：索引里不常驻保存 embedding，检索时依据图结构现算。这是存储体积下降的主要来源，代价是查询阶段需要可用的 embedding 模型。
• MCP 原生集成：仓库标题里写的是 MCP Native Integration，定位是与 Claude Code 完全兼容的语义搜索 MCP 服务，接入方式见 packages/leann-mcp/README.md。
• 多数据源示例：README 列出文件系统、Apple Mail、浏览器历史、微信、iMessage、ChatGPT、Claude、Slack、Twitter 书签等多条索引路线，相关应用放在 apps/ 下。
• 文档问答应用：Issue 中出现的启动方式为 python -m apps.document_rag --index-dir /path/to/index，通过 --index-dir 指定已有索引目录。
• 知识库迁移：README 说整个知识库可以在设备之间转移，成本很低，也可以连同他人一起使用。
• 基准复现：benchmarks/contextbench/README.md 给出与 BM25 在 30 个 SWE-Bench Pro 任务上的对照数据，README 引用的结果是初始相关代码召回率 24.2% 对 11.4%，探索后覆盖率高 12.6 个百分点，token 用量少 8.4%。
• AST 切块：--use-ast-chunking 用于按语法结构切分代码，需要额外安装 astchunk 包。

安装与最短示例

README 的快速安装路线是克隆仓库、建虚拟环境、从 PyPI 装包：

git clone https://github.com/yichuan-w/LEANN.git leann
cd leann
uv venv
source .venv/bin/activate
uv pip install leann

纯 CPU 的 Linux 环境，README 提示改用 cpu 附加项，也就是 leann[cpu]。

如果安装后用 leann build 报出 Security Violation [pathsec.open]: refusing multiply-linked file，README 给出的处理是关掉 uv 的硬链接安装模式重装：

UV_LINK_MODE=copy uv pip install --reinstall leann

需要开发或要 DiskANN 后端时，走源码构建：

git clone https://github.com/yichuan-w/LEANN.git leann
cd leann
git submodule update --init --recursive

macOS 上先补依赖再同步：

brew install libomp boost protobuf zeromq pkgconf
uv sync --extra diskann

Issue 里还出现过一条用 uv 工具方式安装、并带着 astchunk 的写法：

uv tool install leann-core --with leann --with astchunk
leann build my-code-index --docs ./src --use-ast-chunking

这就是仓库里能给到的最短跑通路径：装好之后建一个索引，索引目录就是后续所有查询操作的入口。

关键参数

README 节选出来的部分没有给出完整参数表，下面这些是事实里实际出现过的字段，具体默认值仓库没有逐条说明。

• --docs：建索引时的待处理目录。
• --index-dir：指定索引所在目录，文档问答应用靠它定位已有索引。
• --use-ast-chunking：启用 AST 切块，需要 astchunk 依赖。
• --embedding-mode：Issue 中出现过 --embedding-mode ollama 的用法，即用 Ollama 生成 embedding。
• embedding_model：Issue 里给出的实际取值是 BAAI/bge-large-zh-v1.5。
• beam_width：Issue 里给出的实际取值是 10，与检索耗时相关。
• chunk-size：Issue 里有人问过怎么控制切块大小，并提到 packages/leann-mcp/README.md 里的索引 jsonl 每条 ID 很短。仓库没有直接给出默认值。

结果在哪里看

建索引阶段的结果落在 leann build 指定的索引名下，之后由 --index-dir 指过去复用。构建过程本身有终端输出，Issue 里贴出的日志形如 Processing 1 directory... 和 Processing directory: /my-docs。

查询结果有两条路：一是通过 apps/ 下的示例应用，二是接入 MCP 之后由 Claude Code 之类的客户端返回片段。基准数据在 benchmarks/ 目录下，按子目录分开。

实际使用中的坑

• 检索延迟怎么压。有用户拿单张 4090、180M 数据量、beam_width 设为 10 的配置问怎么把搜索时间做得更短，这条 Issue 有 24 条评论，目前标为 [待解决]，被标注为 warmup-question remained。参数组合与耗时之间的关系，仓库没有给出通用结论。
• Windows 支持。Issue 列表里的「Add support for Windows」带着 Many requests 标记，12 条评论，状态是 [待解决]。
• 索引增量更新。有人问代码库不断变大时更新索引的最佳做法是什么，包括重新建索引时是否会自动识别变化、有没有更好的维护流程，9 条评论，仍是 [待解决]。
• Apple M4 装不上。一条关于 MacBook Pro（M4、24GB）安装失败的报告有 11 条评论，状态为 [已解决]。
• Ollama 生成 embedding 慢。有报告指出 --embedding-mode ollama 下走串行 API 调用形成性能瓶颈，这条 9 条评论，[已解决]。
• PDF 被跳过。有用户按目录批量处理文档时，日志里出现 Skipping file outside directory scope，部分 PDF 没被索引，[已解决]。隐藏目录下的文件也曾出现扫不到的情况，[已解决]。

横向对照

下表里 LEANN 与 AnythingLLM 属于同类，都在做本地文档检索与问答；chatchat-space/Langchain-Chatchat 在任务上与本项目同属知识库问答方向，但走的是另一条技术路线。

如果目标只是把几十份 PDF 丢进去问答、还要一个现成界面，LEANN 给不了这种开箱体验，它更接近检索层，模型调用、对话界面、权限这些都得自己接上，这种情况选 AnythingLLM 一类带界面的方案更省事。反过来说，索引规模小的时候，LEANN 在存储压缩上的优势也基本看不出来。

合规与授权边界

LEANN 会扫描本机文件系统、浏览器历史、邮件和聊天记录并建立索引，这属于对个人数据的批量读取。可以用的范围是自有设备与自有账号，导入他人邮件、聊天记录、导出包之前，需要先取得对方授权。

通过平台侧数据建索引时还要看服务条款。Slack、Twitter 这类平台对数据导出和二次使用有各自规定，绕过授权抓取会带来账号与法律风险。README 提到整个知识库可以在设备之间转移，甚至与他人共用，分享索引文件前要意识到里面可能含有私密内容。

适合谁

适合手上有大量本地文档、代码或对话记录，想在自己机器上做语义检索，又对磁盘占用和隐私敏感的人。也适合已经在用 Claude Code、希望把关键字搜索换成语义检索的开发者。

不适合想要开箱即用知识库产品的人，也不适合把 Windows 当唯一工作平台、又不愿意等 Issue 里那条支持请求落地的用户。数据量很小的时候，为存储优化付出的这套额外搭建成本不划算。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 10.0 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。