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

macOS：

注意：DiskANN 需要 macOS 13.3 或更高版本。

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

Linux（Ubuntu/Debian）：

注意：在 Ubuntu 20.04 上，您可能需要编译更新的 Abseil 库，并锁定 Protobuf 版本（例如 v3.20.x），以便成功构建 DiskANN。有关逐步说明，请参阅 Issue #30。

您可以手动安装 Intel oneAPI MKL，而不是使用 libmkl-full-dev 来为 DiskANN 提供支持。此外，如果您只想构建 HNSW 索引，可以通过在以下命令中移除 --extra diskann 参数来使用 libopenblas-dev。

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

Linux（Arch Linux）：

sudo pacman -Syu && sudo pacman -S --needed base-devel cmake pkgconf git gcc \
  boost boost-libs protobuf abseil-cpp libaio zeromq

# 用于 DiskANN 中的 MKL
sudo pacman -S --needed base-devel git
git clone https://aur.archlinux.org/paru-bin.git
cd paru-bin && makepkg -si
paru -S intel-oneapi-mkl intel-oneapi-compiler
source /opt/intel/oneapi/setvars.sh

uv sync --extra diskann

Linux（RHEL / CentOS Stream / Oracle / Rocky / AlmaLinux）：

更多详细信息请参阅 Issue #50。

sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y libomp-devel boost-devel protobuf-compiler protobuf-devel \
  abseil-cpp-devel libaio-devel zeromq-devel pkgconf-pkg-config

# 用于 DiskANN 中的 MKL
sudo dnf install -y intel-oneapi-mkl intel-oneapi-mkl-devel \
  intel-oneapi-openmp 或者 sudo dnf install -y intel-oneapi-compiler
source /opt/intel/oneapi/setvars.sh

uv sync --extra diskann

Windows：

需要安装带有 C++ 桌面开发 工作负载的 Visual Studio 2022 Build Tools，以及 vcpkg。

# 安装工具链（如果尚未安装）
choco install cmake swig pkgconfiglite nuget.commandline -y

# 通过 vcpkg 安装 C++ 依赖项
vcpkg install zeromq:x64-windows openblas:x64-windows lapack:x64-windows `
  boost-program-options:x64-windows protobuf:x64-windows

# 设置环境变量（将 VCPKG_ROOT 调整为您的 vcpkg 路径）
$env:CMAKE_PREFIX_PATH = "$env:VCPKG_ROOT\installed\x64-windows"
$env:PKG_CONFIG_PATH = "$env:VCPKG_ROOT\installed\x64-windows\lib\pkgconfig"
$env:PKG_CONFIG_EXECUTABLE = "C:\ProgramData\chocolatey\bin\pkg-config.exe"
$env:OPENBLAS_LIB = "$env:VCPKG_ROOT\installed\x64-windows\lib\openblas.lib"
$env:PATH += ";$env:VCPKG_ROOT\installed\x64-windows\bin"
$env:PATH += ";$env:VCPKG_ROOT\installed\x64-windows\tools\protobuf"

uv sync --extra diskann

将您的 OpenAI API 密钥设置为环境变量：

export OPENAI_API_KEY="your-api-key-here"

使用 CLI 时，请务必使用 --llm openai 标志。您还可以使用 --llm-model <model-name> 标志指定模型名称。

得益于 OpenAI API 格式的广泛采用，LEANN 出厂即与大量 LLM 和嵌入提供商兼容。只需设置 OPENAI_BASE_URL 和 OPENAI_API_KEY 环境变量，即可连接到您首选的服务。

export OPENAI_API_KEY="xxx"
export OPENAI_BASE_URL="http://localhost:1234/v1" # 提供商的基本 URL

若要在 CLI 界面中使用兼容 OpenAI 的端点：

如果您用于文本生成，请确保使用 --llm openai 标志，并用 --llm-model <model-name> 标志指定模型名称。

如果您用于嵌入，则应设置 --embedding-mode openai 标志，并用 --embedding-model <MODEL> 标志指定模型名称。

以下是常见提供商的基本 URL 列表，供您参考。

🖥️ 本地推理引擎（建议用于完全隐私保护）

☁️ 云服务提供商

🚨 隐私提示： 在选择云服务提供商之前，请仔细阅读其隐私和数据保留政策。根据他们的条款，您的数据可能会被用于其自身目的，包括但不限于人工审核和模型训练，若处理不当，可能导致严重后果。

💡 小贴士：使用不同的嵌入服务提供商

若要为嵌入使用不同的提供商（例如 Jina AI），同时为 LLM 使用另一家提供商，请使用 --embedding-api-base 和 --embedding-api-key：

leann build my-index --docs ./docs \
  --embedding-mode openai \
  --embedding-model jina-embeddings-v3 \
  --embedding-api-base https://api.jina.ai/v1 \
  --embedding-api-key $JINA_API_KEY

如果您的提供商未在此列表中，也不用担心！请查阅其文档以找到与 OpenAI 兼容的端点——很可能它也是 OpenAI 兼容的！

macOS：

首先，下载 Ollama for macOS。

# 拉取一个轻量级模型（推荐用于消费级硬件）
ollama pull llama3.2:1b

Linux：

# 安装 Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# 手动启动 Ollama 服务
ollama serve &

# 拉取一个轻量级模型（推荐用于消费级硬件）
ollama pull llama3.2:1b

所有 RAG 示例都共享这些常用参数。交互模式在所有示例中均可使用——只需不带 --query 参数运行，即可开始连续问答会话，您可以在其中提出多个问题。输入 'quit' 即可退出。

# 环境变量（GPU 设备选择）
LEANN_EMBEDDING_DEVICE       # 用于嵌入模型的 GPU（例如 cuda:0, cuda:1, cpu）
LEANN_LLM_DEVICE             # 用于 HFChat LLM 的 GPU（例如 cuda:1，或 "cuda" 表示多 GPU 自动分配）

# 核心参数（所有示例的通用预处理）
--index-dir DIR              # 存储索引的目录（默认：当前目录）
--query "YOUR QUESTION"      # 单次查询模式。省略则进入交互式聊天模式（输入 'quit' 可退出），此时您可以与索引进行交互式操作
--max-items N                # 限制数据预处理的数量（默认：-1，即处理全部数据）
--force-rebuild              # 强制重建索引，即使索引已存在

# 嵌入参数
--embedding-model MODEL      # 例如 facebook/contriever, text-embedding-3-small, mlx-community/Qwen3-Embedding-0.6B-8bit 或 nomic-embed-text
--embedding-mode MODE        # sentence-transformers, openai, mlx 或 ollama

# LLM 参数（文本生成模型）
--llm TYPE                   # LLM 后端：openai, ollama, hf 或 anthropic（默认：openai）
--llm-model MODEL            # 模型名称（默认：gpt-4o），例如 gpt-4o-mini, llama3.2:1b, Qwen/Qwen2.5-1.5B-Instruct
--thinking-budget LEVEL      # 思考预算，适用于推理模型：low/medium/high（支持 o3, o3-mini, GPT-Oss:20b 等推理模型）

# 检索参数
--top-k N                    # 返回的结果数量（默认：20）
--search-complexity N        # 图遍历的搜索复杂度（默认：32）

# 分块参数
--chunk-size N               # 文本分块的大小（默认因来源而异：大多数为 256，微信为 192）
--chunk-overlap N            # 分块之间的重叠部分（默认因来源而异：25–128）

# 索引构建参数
--backend-name NAME          # 使用的后端：hnsw 或 diskann（默认：hnsw）
--graph-degree N             # 构建索引时的图度数（默认：32）
--build-complexity N         # 索引构建的复杂度（默认：64）
--compact / --no-compact     # 是否使用紧凑存储（默认：true）。若要进行“不重新计算”的构建，则必须设置为“no-compact”。
--recompute / --no-recompute # 是否启用嵌入重新计算（默认：启用）。不应在“重新计算”的构建中执行“不重新计算”的检索。

参数

--data-dir DIR           # 包含待处理文档的目录（默认：data）
--file-types .ext .ext   # 按特定文件类型筛选（可选；若省略则处理所有 LlamaIndex 支持的类型）

示例命令

# 处理所有文档，并为学术论文使用更大的分块
python -m apps.document_rag --data-dir "~/Documents/Papers" --chunk-size 1024

# 仅筛选 Markdown 和 Python 文件，并使用较小的分块
python -m apps.document_rag --data-dir "./docs" --chunk-size 256 --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 "认证是如何工作的？"

先决条件

# 安装依赖
uv pip install colpali_engine pdf2image pillow matplotlib qwen_vl_utils einops seaborn
brew install poppler  # 仅限 macOS，用于 PDF 处理

构建索引

python -m apps.colqwen_rag build \
  --pdfs ./pdf_directory/ \
  --index my_index \
  --model colqwen2  # 或 colpali

搜索

python -m apps.colqwen_rag search my_index "你的问题在这里" --top-k 5

模型

• ColQwen2 (colqwen2)：最新视觉-语言模型，性能更优
• ColPali (colpali)：经过验证的多模态检索器

有关详细用法，请参阅 ColQwen 指南。

参数

--mail-path PATH         # 特定邮件目录的路径（省略时自动检测）
--include-html          # 在处理中包含 HTML 内容（适用于新闻通讯）

示例命令

# 搜索来自特定账户的工作邮件
python -m apps.email_rag --mail-path "~/Library/Mail/V10/WORK_ACCOUNT"

# 查找所有收据和订单确认邮件（包含 HTML）
python -m apps.email_rag --query "收据 订单确认 发票" --include-html

索引构建完成后，你可以提出如下问题：

• “查找我老板关于截止日期的邮件”
• “John 对项目时间表说了什么？”
• “给我看看关于差旅费用的邮件”

参数

--chrome-profile PATH    # Chrome 配置文件目录的路径（省略时自动检测）

示例命令

# 搜索浏览历史中的学术研究
python -m apps.browser_rag --query "arxiv 论文 机器学习 变压器架构"

# 跟踪工作配置文件中的竞争对手分析
python -m apps.browser_rag --chrome-profile "~/Library/Application Support/Google/Chrome/Work Profile" --max-items 5000

默认的 Chrome 配置文件路径是为典型的 macOS 设置配置的。如果你需要找到自己的特定 Chrome 配置文件：

1. 打开终端
2. 输入：ls ~/Library/Application\ Support/Google/Chrome/
3. 查看类似“Default”、“Profile 1”、“Profile 2”等文件夹
4. 将完整路径作为 --chrome-profile 参数使用

常见的 Chrome 配置文件位置：

• macOS：~/Library/Application Support/Google/Chrome/Default
• Linux：~/.config/google-chrome/Default

索引构建完成后，你可以提出如下问题：

• “我访问过哪些关于机器学习的网站？”
• “查找我关于编程的搜索历史”
• “我最近看了哪些 YouTube 视频？”
• “给我看看我访问过的旅行规划相关网站”

首先，你需要安装 WeChat 导出工具，

brew install sunnyyoung/repo/wechattweak-cli

或者手动安装（如果 Homebrew 出现问题）：

sudo packages/wechat-exporter/wechattweak-cli install

故障排除：

• 安装问题：请查看 WeChatTweak-CLI 的问题页面
• 导出错误：如果你遇到以下错误，请尝试重启微信：

  导出微信数据失败。请确保微信正在运行，并且已安装 WeChatTweak。
  未找到或无法导出微信数据。退出。
  

参数

--export-dir DIR         # 存储导出的微信数据的目录（默认：wechat_export_direct）
--force-export          # 强制重新导出，即使已有数据

示例命令

# 搜索群聊中讨论的旅行计划
python -m apps.wechat_rag --query "旅行计划" --max-items 10000

# 重新导出并搜索最近的聊天记录（新消息后很有用）
python -m apps.wechat_rag --force-export --query "工作日程"

索引构建完成后，你可以提出如下问题：

• “我想买魔术师约翰逊的球衣，给我一些对应聊天记录?” (中文：给我看看关于购买魔术师约翰逊球衣的聊天记录)

分步导出流程：

1. 登录 ChatGPT
2. 点击右上角的个人资料图标
3. 前往设置 → 数据控制
4. 在“导出数据”下点击“导出”
5. 确认导出请求
6. 从邮件链接下载 ZIP 文件（有效期 24 小时）
7. 解压或直接使用 LEANN 工具

支持的格式：

• ChatGPT 导出的 .html 文件
• ChatGPT 的 .zip 存档
• 包含多个导出文件的目录

参数

--export-path PATH           # ChatGPT 导出文件（.html/.zip）或目录的路径（默认：./chatgpt_export）
--separate-messages         # 分别处理每条消息，而非合并后的对话
--chunk-size N              # 文本块大小（默认：512）
--chunk-overlap N           # 块之间的重叠部分（默认：128）

示例命令

# 使用 HTML 导出的基本用法
python -m apps.chatgpt_rag --export-path conversations.html

# 处理来自 ChatGPT 的 ZIP 存档
python -m apps.chatgpt_rag --export-path chatgpt_export.zip

# 使用特定查询进行搜索
python -m apps.chatgpt_rag --export-path chatgpt_data.html --query "Python 编程帮助"

# 处理单个消息以实现精细化搜索
python -m apps.chatgpt_rag --separate-messages --export-path chatgpt_export.html

# 处理包含多个导出文件的目录
python -m apps.chatgpt_rag --export-path ./chatgpt_exports/ --max-items 1000

当您的 ChatGPT 对话被索引后，您可以使用以下查询进行搜索：

• “我曾向 ChatGPT 询问过哪些关于 Python 编程的问题？”
• “给我展示关于机器学习算法的对话”
• “查找关于 Web 开发框架的讨论”
• “ChatGPT 给了我哪些编程建议？”
• “搜索关于调试技巧的对话”
• “找到 ChatGPT 推荐的学习资源”

分步导出流程：

1. 在浏览器中打开 Claude
2. 前往设置（寻找齿轮图标或设置菜单）
3. 在账户设置中找到导出/下载选项
4. 下载对话数据（通常为 JSON 格式）
5. 将文件放置在项目目录中

注意：Claude 的导出方法可能因您使用的界面而异。请查阅 Claude 的帮助文档，以获取最新的导出说明。

支持的格式：

• .json 文件（推荐）
• 包含 JSON 数据的 .zip 存档
• 包含多个导出文件的目录

参数

--export-path PATH           # Claude 导出文件（.json/.zip）或目录的路径（默认：./claude_export）
--separate-messages         # 分别处理每条消息，而非合并后的对话
--chunk-size N              # 文本块大小（默认：512）
--chunk-overlap N           # 块之间的重叠部分（默认：128）

示例命令

# 使用 JSON 导出的基本用法
python -m apps.claude_rag --export-path my_claude_conversations.json

# 处理来自 Claude 的 ZIP 存档
python -m apps.claude_rag --export-path claude_export.zip

# 使用特定查询进行搜索
python -m apps.claude_rag --export-path claude_data.json --query "机器学习建议"

# 处理单个消息以实现精细化搜索
python -m apps.claude_rag --separate-messages --export-path claude_export.json

# 处理包含多个导出文件的目录
python -m apps.claude_rag --export-path ./claude_exports/ --max-items 1000

当您的 Claude 对话被索引后，您可以使用以下查询进行搜索：

• “我曾向 Claude 询问过哪些关于 Python 编程的问题？”
• “给我展示关于机器学习算法的对话”
• “查找关于软件架构模式的讨论”
• “Claude 曾给我哪些调试建议？”
• “搜索关于数据结构的对话”
• “找到 Claude 推荐的学习资源”

iMessage 数据位置：

iMessage 对话存储在你 Mac 上的 SQLite 数据库中，路径为：

~/Library/Messages/chat.db

重要设置要求：

1. 授予终端或 IDE 完全磁盘访问权限：

   • 打开 系统偏好设置 → 安全性与隐私 → 隐私
   • 在左侧栏选择 完全磁盘访问权限
   • 点击 + 按钮，添加你的终端应用（Terminal、iTerm2）或 IDE（VS Code 等）
   • 授予访问权限后，请重启你的终端/IDE

2. 替代方案：使用备份数据库

   • 如果你有 Time Machine 备份或手动复制的数据库
   • 使用 --db-path 指定自定义路径

支持的格式：

• 直接访问 ~/Library/Messages/chat.db（默认）
• 使用 --db-path 指定自定义数据库路径
• 也适用于数据库的备份副本

参数

--db-path PATH                    # chat.db 文件路径（默认：~/Library/Messages/chat.db）
--concatenate-conversations       # 按对话分组消息（默认：True）
--no-concatenate-conversations    # 将每条消息单独处理
--chunk-size N                    # 文本块大小（默认：1000）
--chunk-overlap N                 # 文本块之间的重叠量（默认：200）

示例命令

# 基本用法（需要完全磁盘访问权限）
python -m apps.imessage_rag

# 使用特定查询进行搜索
python -m apps.imessage_rag --query "家庭聚餐计划"

# 使用自定义数据库路径
python -m apps.imessage_rag --db-path /path/to/backup/chat.db

# 不按对话分组，而是单独处理每条消息
python -m apps.imessage_rag --no-concatenate-conversations

# 限制处理数量以进行测试
python -m apps.imessage_rag --max-items 100 --query "周末"

一旦你的 iMessage 对话被索引，你就可以使用以下查询进行搜索：

• “我们讨论过哪些度假计划？”
• “查找关于餐厅推荐的消息”
• “给我显示与 John 关于项目的对话”
• “搜索关于科技的分享链接”
• “查找关于周末活动的群聊讨论”
• “妈妈对家庭聚会说了什么？”

Slack 查询：

• “团队讨论了关于项目截止日期的哪些内容？”
• “查找有关新功能发布的消息”
• “向我展示关于预算规划的对话”
• “开发团队频道中做出了哪些决定？”

Twitter 查询：

• “上个月我收藏了哪些 AI 文章？”
• “查找有关机器学习技术的推文”
• “向我展示有关创业建议的已收藏话题串”
• “我保存了哪些 Python 教程？”

希望添加对其他平台的支持吗？LEANN 的 MCP 集成设计为易于扩展：

1. 找到或创建适用于你平台的 MCP 服务器
2. 按照 apps/slack_data/slack_mcp_reader.py 中的模式创建读取类
3. 按照 apps/slack_rag.py 中的模式创建 RAG 应用程序
4. 测试后贡献回社区！

可探索的热门 MCP 服务器：

• GitHub 仓库和问题
• Discord 消息
• Notion 页面
• Google Drive 文档
• 以及 MCP 生态系统中的更多选项！

LEANN 具有智能代码分块功能，能够保留语义边界（函数、类、方法），适用于 Python、Java、C# 和 TypeScript，相比基于文本的分块方式，能更好地理解代码。

📖 阅读 AST 分块指南 →

您可以使用 leann --help，或 leann build --help、leann search --help、leann watch --help、leann ask --help、leann list --help、leann remove --help 来获取完整的 CLI 参考。

构建命令：

leann build INDEX_NAME --docs DIRECTORY|FILE [DIRECTORY|FILE ...] [OPTIONS]

选项：
  --backend {hnsw,diskann}     使用的后端（默认：hnsw）
  --embedding-model MODEL      嵌入模型（默认：facebook/contriever）
  --graph-degree N             图的度数（默认：32）
  --complexity N               构建复杂度（默认：64）
  --force                      强制重建现有索引
  --compact / --no-compact     使用紧凑存储（默认：true）。若选择不重新计算，则必须设置为 --no-compact。
  --recompute / --no-recompute 启用重新计算（默认：true）

搜索命令：

leann search INDEX_NAME QUERY [OPTIONS]

选项：
  --top-k N                     结果数量（默认：5）
  --complexity N                搜索复杂度（默认：64）
  --recompute / --no-recompute  是否启用嵌入重新计算（默认：启用）。在重新计算模式下构建的索引不应使用不重新计算的搜索。
  --pruning-strategy {global,local,proportional}

监听命令：

leann watch INDEX_NAME

# 将当前文件系统状态与上次检查点（Merkle 树快照）进行比较，
# 并报告哪些文件被添加、删除或修改，以及它们对应的分块 ID。
#
# - 检测到更改后会自动保存新的检查点
# - 每次运行都会与最近的检查点进行对比
# - 文件变更检测采用 SHA-256 内容哈希算法，并通过 Merkle 树实现
#
# 示例输出：
#   === 自上次检查点以来的变更 ===
#   已修改 (1):
#     - /path/to/file.py
#       分块：42、43、44

提问命令：

leann ask INDEX_NAME [OPTIONS]

选项：
  --llm {ollama,openai,hf,anthropic}    LLM 提供商（默认：ollama）
  --model MODEL                         模型名称（默认：qwen3:8b）
  --interactive                         交互式聊天模式
  --top-k N                             检索数量（默认：20）

列出命令：

leann list

# 列出所有项目中的所有索引，并附带状态标识：
# ✅ - 索引已完成且可使用
# ❌ - 索引不完整或已损坏
# 📁 - 由 CLI 创建的索引（位于 .leann/indexes/ 目录中）
# 📄 - 由应用创建的索引（*.leann.meta.json 文件）

移除命令：

leann remove INDEX_NAME [OPTIONS]

选项：
  --force, -f    强制移除，无需确认

# 智能移除：自动查找并安全移除索引
# - 显示跨项目的所有匹配索引
# - 跨项目移除需要确认
# - 当找到多个匹配项时支持交互式选择
# - 同时支持 CLI 和应用创建的索引