Github 项目 LEANN是一个创新的向量数据库，旨在通过图基选择性重计算和高维度保持修剪等技术，实现极高的存储效率（相比传统解决方案可节省高达 97% 的存储空间），让用户能够在个人设备上运行快速、准确且完全私密的 RAG（检索增强生成）应用。

以下是它的使用教程。

LEANN 详细使用教程

1. 核心概念

LEANN 的主要特点是其轻量级设计。它不存储所有的嵌入向量，而是按需计算（on-demand computation），极大地减少了存储和内存开销，使得在笔记本电脑等资源有限的设备上进行大规模语义搜索成为可能。

2. 环境准备

LEANN 是一个 Python 包，推荐使用 uv 进行安装，这是一个快速的 Python 包安装和管理工具。

2.1 安装 uv (如果尚未安装)

Bash

# 在 Linux/macOS 上curl -LsSf https://astral.sh/uv/install.sh | sh# 或者使用 pippip install uv

2.2 安装 LEANN

使用 uv 从 PyPI 安装 LEANN：

Bash

uv pip install leann

3. 基本使用：构建和搜索索引

LEANN 的核心功能是通过 LeannBuilder 构建索引，并通过 LeannSearcher 或 LeannChat 进行搜索或问答。

3.1 示例代码：文本索引和搜索

以下是一个使用 LEANN 构建索引和执行语义搜索的基本 Python 示例。

Python

from leann import LeannBuilder, LeannSearcher, LeannChatfrom pathlib import Pathimport shutil# 定义索引存储路径INDEX_DIR = Path("./leann_demo_index")INDEX_PATH = str(INDEX_DIR.resolve() / "demo.leann")# 清理旧的索引目录 (可选)if INDEX_DIR.exists():    shutil.rmtree(INDEX_DIR)print(f"Index will be stored at: {INDEX_PATH}")# --- 步骤 1: 构建索引 (LeannBuilder) ---print("--- 1. Building Index ---")# 1.1 初始化 LeannBuilder# backend_name="hnsw" 是一个常用的高性能后端builder = LeannBuilder(backend_name="hnsw", index_path=INDEX_PATH)# 1.2 添加数据# 可以添加文本、文件、目录等builder.add_text("LEANN 节省了 97% 的存储空间，比传统向量数据库更高效。",                  metadata={"source": "LEANN Homepage"})builder.add_text("这是一个关于向量数据库和RAG技术的示例。",                 metadata={"source": "Tutorial"})builder.add_text("在本地设备上运行AI应用不再是梦想。",                  metadata={"source": "Vision"})# 1.3 完成构建 (将数据写入磁盘)builder.build()print(f"Index built successfully at {INDEX_PATH}")# --- 步骤 2: 语义搜索 (LeannSearcher) ---print("\n--- 2. Semantic Search ---")# 2.1 初始化 LeannSearchersearcher = LeannSearcher(index_path=INDEX_PATH)# 2.2 执行搜索query = "什么是 LEANN 的核心优势？"top_k = 2  # 返回最相关的2条结果results = searcher.search(query=query, top_k=top_k)print(f"Query: **{query}**")for i, res in enumerate(results):    print(f"\nResult {i+1}:")    print(f"  Text: {res.text}")    print(f"  Source: {res.metadata.get('source', 'N/A')}")    # res.score 表示相似度得分# --- 步骤 3: 问答/RAG (LeannChat) ---print("\n--- 3. Retrieval-Augmented Generation (RAG) ---")# 3.1 初始化 LeannChat# 默认使用本地的或配置的LLM（需要确保已配置或安装相应的模型）chat = LeannChat(index_path=INDEX_PATH)# 3.2 提出问题question = "LEANN是如何让本地AI应用成为可能的？"# 注意：初次运行时可能会下载模型，请耐心等待。# `ask` 方法会检索相关文档，并用这些文档来指导LLM生成答案。answer = chat.ask(question=question)print(f"Question: **{question}**")print(f"Answer: {answer}")# 3.3 清理（可选）# shutil.rmtree(INDEX_DIR)

4. 索引更复杂的数据

LEANN 旨在实现 RAG Everything，支持索引各种类型的数据：

示例：索引本地目录

Python

# 假设你有一个名为 'docs' 的文件夹# builder.add_dir("./docs")

5. 常见配置和最佳实践

LEANN 的性能和准确性取决于其配置，主要包括：

5.1 后端选择 (backend_name)

在初始化 LeannBuilder 时，可以指定向量索引后端：

• hnsw (默认且推荐): HNSW (Hierarchical Navigable Small World)，通常提供最好的速度和准确性。
• ivf (可选): IVF (Inverted File Index)，适用于超大规模数据集。
• 其他 Faiss 支持的后端。

Python

builder = LeannBuilder(backend_name="hnsw", ...) 

5.2 模型选择 (embedding_model_name)

LEANN 使用嵌入模型来生成文本的向量表示。您可以在构建索引和搜索时指定模型（默认会使用一个高性能的 Sentence Transformer 模型）。

Python

# 在构建时指定模型builder = LeannBuilder(embedding_model_name="BAAI/bge-small-en-v1.5", ...)# 在搜索时指定模型 (需与构建索引时保持一致)searcher = LeannSearcher(embedding_model_name="BAAI/bge-small-en-v1.5", ...)

5.3 配置指南

为了获得最佳性能，请查阅 LEANN 的官方 Configuration Guide，其中包含关于优化技巧、模型选择和常见问题解决方案的详细信息（这些通常位于 GitHub 仓库的 README 或专门的文档页面）。

总结

希望这份详细教程能帮助您开始使用 LEANN，充分利用其高效的本地 RAG 能力！