LEANN

python 2026-01-21

LEANN

2026-01-21

珍惜时间的名言警句：最浪费不起的是时间。——丁肇中

LEANN：把你的笔记本变成“能理解一切”的私有 RAG 系统

LEANN 是一个主打“轻量、高效、私有”的向量数据库与检索框架，目标非常大胆：在个人设备上运行一个速度快、准确度高、并且节省 97% 存储空间的 RAG（检索增强生成）应用，让你的文件系统、邮件、聊天记录、浏览历史、AI 对话等“分散的个人知识”，都能被统一索引起来并随时问答。

仓库：yichuan-w/LEANN
描述：RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.
许可：MIT
Python 版本：3.9 ~ 3.13（README 徽章）
平台：Ubuntu、Arch、WSL、macOS（ARM64/Intel）（README 徽章）
MCP：原生集成（README 徽章）

一句话印象：The smallest vector index in the world. RAG Everything with LEANN!

为什么是 LEANN

官方给了一个很直观的对比图和数据：在个人机器上，LEANN 能通过“图式选择性重计算 + 高度保留的剪枝”策略，将 embedding 从“全部持久化”转变为“按需计算”，配合 CSR 格式等优化，极大降低存储和内存开销。

97% 存储节省：比如“索引 6000 万文本块，仅需 6GB（传统方案需要 201GB）”
隐私：数据不离开你的设备，不依赖云服务
轻量可携带：知识库可在设备间转移，个人 AI 记忆跟你走
可扩展：个人数据“又杂又多”也能稳住，易处理增长与 Agent 的生成记忆
准确度不妥协：在大幅节省存储的同时保持检索质量

此外，LEANN 还是一个“Drop-in 的语义搜索 MCP 服务”，与 Claude Code 兼容，补齐 Claude 端只有 grep 式关键词搜索的短板。

它如何做到“既省又准”

核心思想是“Graph-based selective recomputation with high-degree preserving pruning”（图式选择性重计算 + 高度保留剪枝）：

不把所有 embedding 都落库，而是按需计算
构图时保留高连接度的重要节点，减少图存储体量
用 CSR（Compressed Sparse Row）这种格式把图的存储开销进一步压缩
搜索时通过图遍历和复杂度参数控制性能与效果平衡

后端支持 HNSW 与 DiskANN 两种索引后端，均有配置参数可控。

安装与启动（极简）

推荐先安装 uv 包管理器（Astral 的 Python 管理工具），然后用 PyPI 装 LEANN：

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 拉仓库并进入示例目录
git clone https://github.com/yichuan-w/LEANN.git leann
cd leann

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate

# 安装 LEANN
uv pip install leann

如果你希望开发或使用 DiskANN 等后端，也可以按 README 的“Build from Source”部分，为 macOS / Ubuntu / Arch / RHEL 等平台安装所需依赖（如 libomp / boost / protobuf / zeromq / Intel MKL 等），并使用 uv sync --extra diskann 同步依赖。不同发行版的细节参见 README 的对应章节与 Issue 指引。

“写配置就能 RAG”：Python 最小示例

LEANN 的声明式 API 让你“写几行就能跑”，从索引构建到搜索，再到基于你数据的问答：

from leann import LeannBuilder, LeannSearcher, LeannChat
from pathlib import Path
INDEX_PATH = str(Path("./").resolve() / "demo.leann")

# 构建索引
builder = LeannBuilder(backend_name="hnsw")
builder.add_text("LEANN saves 97% storage compared to traditional vector databases.")
builder.add_text("Tung Tung Tung Sahur called—they need their banana‑crocodile hybrid back")
builder.build_index(INDEX_PATH)

# 搜索
searcher = LeannSearcher(INDEX_PATH)
results = searcher.search("fantastical AI-generated creatures", top_k=1)

# 对话（基于你的数据）
chat = LeannChat(INDEX_PATH, llm_config={"type": "hf", "model": "Qwen/Qwen3-0.6B"})
response = chat.ask("How much storage does LEANN save?", top_k=1)

也可以直接打开 demo.ipynb 或 Colab 运行。

RAG Everything：数据源覆盖面非常广

LEANN 提供了一系列“开箱即用”的 RAG 应用（CLI/Python 模块），将你的个人数据统一处理与检索。下面是官方 README 中的典型场景与命令示例：

文档（PDF / TXT / MD）

source .venv/bin/activate
python -m apps.document_rag --query "What are the main techniques LEANN explores?"
# 更多：
# python -m apps.document_rag --data-dir "~/Documents/Papers" --chunk-size 1024
# python -m apps.document_rag --data-dir "./docs" --file-types .md .py
# AST感知代码分块：
# python -m apps.document_rag --enable-code-chunking --data-dir "./my_project"
# 专用代码 RAG：
# python -m apps.code_rag --repo-dir "./my_codebase" --query "How does authentication work?"

ColQwen：多模态 PDF 检索（Vision-Language Models）

# 构建索引
python -m apps.colqwen_rag build --pdfs ./my_papers/ --index research_papers
# 文本查询
python -m apps.colqwen_rag search research_papers "How does attention mechanism work?"
# 交互式问答
python -m apps.colqwen_rag ask research_papers --interactive

依赖：uv pip install colpali_engine pdf2image pillow matplotlib qwen_vl_utils einops seaborn，macOS 还需 brew install poppler。支持 colqwen2 与 colpali。

Apple Mail（邮件）

python -m apps.email_rag --query "What's the food I ordered by DoorDash or Uber Eats mostly?"
# 指定账户或包含HTML内容：
# python -m apps.email_rag --mail-path "~/Library/Mail/V10/WORK_ACCOUNT"
# python -m apps.email_rag --query "receipt order confirmation invoice" --include-html

注：需为终端/IDE开启 Full Disk Access（macOS）。

Chrome 浏览历史

1
2
3

python -m apps.browser_rag --query "Tell me my browser history about machine learning?"
# 指定 Profile：
# python -m apps.browser_rag --chrome-profile "~/Library/Application Support/Google/Chrome/Work Profile" --max-items 5000

WeChat（聊天记录）

# 首先安装 WeChatTweak-CLI
brew install sunnyyoung/repo/wechattweak-cli
# 或手动：
# sudo packages/wechat-exporter/wechattweak-cli install

# 搜索
python -m apps.wechat_rag --query "Show me all group chats about weekend plans"
# 强制重新导出：
# python -m apps.wechat_rag --force-export --query "work schedule"

ChatGPT / Claude 对话历史

# ChatGPT 导出（HTML/ZIP/目录）
python -m apps.chatgpt_rag --export-path chatgpt_export.html --query "How do I create a list in Python?"

# Claude 导出（JSON/ZIP/目录）
python -m apps.claude_rag --export-path claude_export.json --query "What did I ask about Python dictionaries?"

iMessage（短信）

1
2
3

python -m apps.imessage_rag --query "What did we discuss about the weekend plans?"
# 指定数据库路径：
# python -m apps.imessage_rag --db-path /path/to/backup/chat.db

注：同样需要在 macOS 的 Privacy 里开启 Full Disk Access。

MCP 集成：从 Slack 与 Twitter 等平台“拉实时数据”

LEANN 原生支持 MCP（Model Context Protocol），可以把 Slack、Twitter 等平台的数据实时接入，形成你的知识库。

Slack

1 2	`# 测试 MCP 连接 python -m apps.slack_rag --mcp-server "slack-mcp-server" --test-connection`

索引并搜索

python -m apps.slack_rag
–mcp-server “slack-mcp-server”
–workspace-name “my-team”
–channels general dev-team random
–query “What did we decide about the product launch?”

- Twitter 书签
```bash
# 测试 MCP 连接
python -m apps.twitter_rag --mcp-server "twitter-mcp-server" --test-connection

# 索引并搜索
python -m apps.twitter_rag \
  --mcp-server "twitter-mcp-server" \
  --max-bookmarks 1000 \
  --query "What AI articles did I bookmark about machine learning?"

也可以将 MCP 数据与 CLI 命令结合（先用 MCP 应用索引，再用 leann search / leann ask 查询）。

LLM 与 Embedding 后端：本地与云兼容

LEANN 支持 HuggingFace、本地 Ollama、Anthropic，以及各种 OpenAI 兼容的 API。推荐“本地优先”的 Ollama 方案，隐私与可控性更强。

OpenAI（默认示例）

1 2	`export OPENAI_API_KEY="your-api-key-here" # CLI 时加 --llm openai 并指定模型名（--llm-model）`

OpenAI 兼容端点（如 LM Studio、vLLM、llama.cpp、SGLang、LiteLLM 等）

export OPENAI_API_KEY="xxx"
export OPENAI_BASE_URL="http://localhost:1234/v1"  # 以 LM Studio 为例
# 生成用 --llm openai --llm-model <name>
# 向量用 --embedding-mode openai --embedding-model <name>

Ollama（推荐）

1 2	`# macOS 下载 App 后拉模型 ollama pull llama3.2:1b`

Linux 安装并启动服务

curl -fsSL https://ollama.ai/install.sh | sh
ollama serve &
ollama pull llama3.2:1b

---

## 常用参数（节选）

几乎所有示例都支持下列参数（详见 README“Flexible Configuration”）：

```bash
# 环境变量（设备选择）
LEANN_EMBEDDING_DEVICE     # 例如 cuda:0 / cpu
LEANN_LLM_DEVICE           # 例如 cuda:1 或 "cuda"

# 索引与搜索
--index-dir DIR            # 索引目录
--top-k N                  # 返回结果数（默认 20）
--search-complexity N      # 图遍历复杂度（默认 32）

# 切块
--chunk-size N             # 默认依数据源而定（如文档 256，微信 192）
--chunk-overlap N          # 默认 25~128 之间

# 嵌入模型
--embedding-model MODEL    # 如 facebook/contriever、text-embedding-3-small、nomic-embed-text
--embedding-mode MODE      # sentence-transformers / openai / mlx / ollama

# LLM
--llm TYPE                 # openai / ollama / hf / anthropic
--llm-model MODEL          # 如 gpt-4o / gpt-4o-mini / llama3.2:1b / Qwen2.5-1.5B-Instruct
--thinking-budget LEVEL    # low/medium/high（o3/o3-mini/GPT-Oss:20b 等推理模型）

# 构建后端
--backend-name NAME        # hnsw 或 diskann（默认 hnsw）
--graph-degree N           # 构图度（默认 32）
--build-complexity N       # 构建复杂度（默认 64）
--compact / --no-compact   # 压缩存储（默认 true）
--recompute / --no-recompute  # 是否开启重计算（默认开启）

基准与测试：稳、准、可验证

LEANN 提供完整的基准与测试集，帮助你在不同后端与配置下做性能/准确性验证。

速度对比（DiskANN vs HNSW）

1 2	`# 快速对比：500 文档、10 查询 python benchmarks/diskann_vs_hnsw_speed_comparison.py`

更大规模

python benchmarks/diskann_vs_hnsw_speed_comparison.py 2000 20

- 距离度量验证（MIPS / L2 / Cosine）
```bash
uv run python tests/sanity_checks/test_distance_functions.py
uv run python tests/sanity_checks/test_l2_verification.py

README 示例与基本功能的 pytest 测试（含 C++ 扩展加载、索引构建/搜索）

1 2	`pytest tests/ # 或带覆盖率：pytest tests/ --cov=leann --cov-report=html pytest tests/ -n auto # 并行更快`

CI/CD：在 GitHub Actions 上，覆盖多 Python 版本（3.9~3.13）、Ubuntu 与 macOS 平台，自动运行测试与发布流程。

适配器与场景建议

个人知识统一索引：文件系统、邮件、聊天、浏览、AI 对话 → 提问即检索
代码库问答：AST 感知分块或专用代码 RAG
PDF 研究：ColQwen2/ColPali 多模态处理复杂版式
团队协作：MCP 接入 Slack 等平台，实时把团队知识变成你的检索语料
私有部署：Ollama/vLLM 等本地引擎，配合 OpenAI 兼容端点映射，保留隐私与可控性

小结

LEANN 的“路线”很清晰：把 embedding 存储的负担转为按需重算，把图结构做得足够聪明与紧凑，让个人设备“承载得起一个全量的个人知识库”。当你能在本地对任何数据源做语义检索与问答，RAG 就不再是云端的大工程，而是你每天用的“个人助手”。

如果你想要这一套“本地优先、节省存储、覆盖面广”的检索增强工作流——现在就装上 LEANN，先跑文档与浏览历史，再把邮件、聊天和 AI 对话也接进来。接着用 MCP 勾上你的团队平台，让知识从分散走向统一，一切都在你的机器里、你的掌控下。

更多信息与完整命令，请直接阅读仓库 README 与各应用的说明：

仓库：yichuan-w/LEANN
PyPI：leann