LEANN 高效向量数据库详细部署教程

LEANN 是一个创新的向量数据库，通过基于图的选择性重计算技术，在保持高检索精度的同时，将存储空间需求降低了 97%。它能让您在个人设备上轻松运行 RAG（检索增强生成）应用，索引海量数据（如电子邮件、聊天记录、浏览器历史等），且完全本地化、注重隐私。本教程将指导您完成 LEANN 的安装、配置与核心应用。

📋 目录

  1. LEANN 是什么
  2. 核心优势与工作原理解析
  3. 系统要求与准备
  4. 安装步骤
  5. 快速开始
  6. 核心功能与 RAG 应用
  7. 命令行界面与高级配置
  8. 更新与卸载
  9. 常见问题排查

LEANN 是什么

LEANN（Low-storage Embedding bAsed on recomputatioN）是一个为个人设备设计的轻量级向量数据库。它的核心创新是不存储所有向量，而是存储一个压缩的图结构，并在查询时按需重计算部分向量，从而大幅降低存储消耗。

关键突破：

  • 97% 存储节省：索引 6000 万文本块仅需 6GB（传统方案需 201GB）。
  • 无损精度：保持与 FAISS 等传统方案相同的检索质量。
  • 完全本地化：所有数据在本地处理，无云端依赖，保护隐私。

核心优势与工作原理解析

LEANN 通过在查询时动态重计算向量来实现高压缩率。

传统向量数据库 LEANN
存储所有向量 存储压缩图结构
查询时直接读取向量 查询时重计算所需向量
高存储成本 97% 存储节省
精度高 精度无损
依赖大量资源 适合个人设备

核心技术：

  • 基于图的选择性重计算：仅在搜索路径中计算节点向量。
  • 高节点度保留剪枝：保留关键枢纽节点，剪除冗余连接。
  • 动态批处理：高效利用 GPU 进行向量计算。
  • 两阶段搜索：智能图遍历优先访问高潜力节点。

系统要求与准备

基础要求

  • 操作系统：macOS（13.3+）、Linux（Ubuntu/Debian/Arch/RHEL 系）或 Windows（需 Visual Studio 2022）。
  • Python：版本 3.8 或更高。
  • 包管理器：uv。

安装 uv

1
curl -LsSf https://astral.sh/uv/install.sh | sh

可选依赖

  • DiskANN 后端（高性能搜索）需要额外安装依赖（见下文）。
  • GPU 加速（CUDA 或 Apple Silicon MPS）可提升计算速度。

安装步骤

1. 克隆仓库

1
2
git clone https://github.com/yichuan-w/LEANN.git leann
cd leann

2. 创建虚拟环境并安装基础包

1
2
3
4
uv venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows
uv pip install leann

3. （可选）安装 DiskANN 后端

根据操作系统安装依赖并同步：

macOS:

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

Linux (Ubuntu/Debian):

1
2
3
4
sudo apt-get update && sudo apt-get install -y \
  libomp-dev libboost-all-dev protobuf-compiler libzmq3-dev \
  pkg-config libabsl-dev libaio-dev libprotobuf-dev libmkl-full-dev
uv sync --extra diskann

Windows：需安装 Visual Studio 2022 Build Tools、vcpkg 并配置环境，详见项目 README。

快速开始

构建索引与搜索

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from leann import LeannBuilder, LeannSearcher
from pathlib import Path

INDEX_PATH = str(Path("./").resolve() / "demo.leann")

# 1. 构建索引
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)

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

使用聊天功能（RAG）

1
2
3
4
5
from leann import LeannChat

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)
print(response)

核心功能与 RAG 应用

LEANN 支持对多种个人数据进行 RAG 索引和查询。以下是一些主要应用场景。

文档 RAG (PDF, TXT, MD)

1
2
# 索引文档目录并查询
python -m apps.document_rag --data-dir ./my_documents --query "What are the main techniques LEANN explores?"

代码库语义搜索

1
2
# 索引代码库
python -m apps.code_rag --repo-dir ./my_codebase --query "How does authentication work?"

浏览器历史搜索 (Chrome)

1
python -m apps.browser_rag --query "Tell me my browser history about machine learning"

38,000 条历史记录仅占 6MB 存储。

电子邮件搜索 (Apple Mail, macOS)

1
python -m apps.email_rag --query "What's the food I ordered by DoorDash?"

780,000 封邮件仅占 78MB 存储。

微信聊天记录搜索 (macOS)

1
python -m apps.wechat_rag --query "Show me all group chats about weekend plans"

400,000 条消息仅占 64MB 存储。

ChatGPT 与 Claude 对话历史

1
2
3
4
5
# 索引 ChatGPT 导出文件
python -m apps.chatgpt_rag --export-path chatgpt_export.html --query "How do I create a list in Python?"

# 索引 Claude 导出文件
python -m apps.claude_rag --export-path claude_export.json --query "What did I ask about Python dictionaries?"

iMessage 搜索 (macOS)

1
python -m apps.imessage_rag --query "What did we discuss about the weekend plans?"

MCP 集成：实时数据（Slack, Twitter）

1
2
3
4
5
# 索引 Slack 消息
python -m apps.slack_rag --mcp-server "slack-mcp-server" --query "What did we decide about the product launch?"

# 索引 Twitter 书签
python -m apps.twitter_rag --mcp-server "twitter-mcp-server" --query "What AI articles did I bookmark?"

命令行界面与高级配置

LEANN 提供了一个强大的 CLI，方便进行索引构建、搜索和交互。

全局安装 CLI

1
uv tool install leann-core --with leann

基本 CLI 命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 构建索引
leann build my-docs --docs ./your_documents

# 搜索
leann search my-docs "machine learning concepts"

# 交互式问答
leann ask my-docs --interactive

# 检测文件变化
leann watch my-docs

# 列出所有索引
leann list

# 删除索引
leann remove my-docs

配置 LLM 与嵌入模型

LEANN 支持多种 LLM 和嵌入提供者，只需设置环境变量或使用 CLI 参数。

使用 OpenAI:

1
2
export OPENAI_API_KEY="your-api-key"
leann build my-docs --docs ./docs --llm openai --embedding-mode openai

使用本地 Ollama（推荐隐私保护）:

1
2
3
export OPENAI_BASE_URL="http://localhost:11434/v1"
export OPENAI_API_KEY="ollama"  # 任意值
leann build my-docs --docs ./docs --llm ollama --llm-model llama3.2:1b

使用 Jina AI 作为嵌入模型:

1
2
3
4
python -m apps.document_rag --embedding-mode openai \
  --embedding-model jina-embeddings-v3 \
  --embedding-api-base https://api.jina.ai/v1 \
  --embedding-api-key $JINA_API_KEY

更新与卸载

更新 LEANN

1
2
3
4
cd leann
git pull
git submodule update --init --recursive
uv sync --extra diskann  # 如有 DiskANN

卸载

1
2
3
4
# 删除项目目录即可
cd .. && rm -rf leann
# 如全局安装 CLI
uv tool uninstall leann-core

常见问题排查

问题：安装 DiskANN 时编译失败。

  • 解决：确保所有系统依赖已安装。Ubuntu 20.04 用户可能需要更新 Protobuf 版本，详见 Issue #30。

问题：运行 macOS 应用（如 email_rag）时提示权限不足。

  • 解决：在 系统设置 → 隐私与安全性 → 完全磁盘访问权限 中添加您的终端或 IDE。

问题：MCP 集成（如 Slack）连接失败。

  • 解决：确保已安装对应的 MCP 服务器（如 npm install -g slack-mcp-server），并正确设置了 API 密钥。检查 MCP 服务器的日志输出。

问题：索引构建慢。

  • 解决：
    • 设置 LEANN_EMBEDDING_DEVICE="cuda:0" 或 "mps" 以启用 GPU 加速。
    • 使用 --max-items N 限制处理的数据量。
    • 考虑使用更轻量的嵌入模型。

通过以上步骤，您应能顺利部署并开始使用 LEANN。这个工具将极大提升您处理个人数据的能力，让您能轻松构建私密、高效的 RAG 应用。如需了解更多高级用法或贡献代码，请查阅项目官方文档和 GitHub 仓库。