企业官网建设流程全解析

LEANN 配置指南：从嵌入模型、推理端点到索引与参数的完整调优实战

【免费下载链接】LEANN[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.项目地址: https://gitcode.com/GitHub_Trending/le/LEANN

LEANN 是一款运行在个人设备上的 RAG（检索增强生成）向量数据库，其核心思路是"对一切数据进行 RAG"，并通过图基选择性重计算（graph-based selective recomputation）与高保真剪枝（high-degree preserving pruning）实现约 97% 的存储节省。本文以仓库内的 docs/configuration-guide.md 为骨架，结合 packages/leann-core/src/leann/cli.py、packages/leann-core/src/leann/settings.py、packages/leann-core/src/leann/api.py 等源码，系统讲解如何针对不同使用场景优化 LEANN：从嵌入模型选型、本地/远程推理端点配置、任务特定提示模板、索引后端选型、LLM 引擎对比，到--build-complexity、--top-k、--thinking-budget、--graph-degree等关键参数的调优，以及无 GPU 环境下的低资源部署方案。读完本文，你将能够根据自己的数据规模、硬件条件与隐私需求，构建出一套可复制、可运行且性能均衡的 LEANN 配置。

快速开始：简单优先

首次尝试 LEANN 时，建议先用小数据集快速验证方案是否可行，避免在尚未确认整体流程正确前就投入长时间的处理。

文档 RAG：默认的data/目录即可直接使用，其中包含 2 篇 AI 研究论文、文学著作《傲慢与偏见》以及一份技术报告：

python -m apps.document_rag --query "What techniques does LEANN use?"

其他数据源：先限制数据集规模做快速测试。所有 RAG 应用脚本（位于apps/目录）都通过--max-items控制处理数量，例如：

# WeChat：只测试最近的消息 python -m apps.wechat_rag --max-items 100 --query "What did we discuss about the project timeline?" # 浏览器历史：最近几天 python -m apps.browser_rag --max-items 500 --query "Find documentation about vector databases" # 邮件：最近的收件箱 python -m apps.email_rag --max-items 200 --query "Who sent updates about the deployment status?"

--max-items的默认值在不同应用中有所不同：例如 apps/chatgpt_rag.py 与 apps/claude_rag.py 中self.max_items_default = -1（默认处理全部会话），而 apps/base_rag_example.py 中该参数允许子类覆盖默认值。传递-1表示处理全量数据。

验证通过后，再逐步扩大规模：

• 100 篇文档 → 1,000 篇 → 10,000 篇 → 全量数据集（--max-items -1）
• 这样可以在投入长时间处理之前尽早发现问题

嵌入模型选型：理解权衡

基于 LEANN 开发过程中的经验，嵌入模型大致可分为三类，选择的核心是在"语义理解能力"与"计算/延迟开销"之间做权衡。

小型模型（参数 < 100M）

示例：sentence-transformers/all-MiniLM-L6-v2（22M 参数）

• 优点：轻量，索引构建与推理都快
• 缺点：语义理解能力较弱，可能遗漏细微关系
• 适用场景：速度优先、查询简单、交互式模式或只是想快速尝试 LEANN。如果时间不是约束条件，建议考虑更大/更好的嵌入模型

从源码看，LEANN 的默认嵌入模型选择逻辑（packages/leann-core/src/leann/cli.py 中的_default_embedding_model()）也与这一分类呼应：检测到 NVIDIA GPU 时默认使用BAAI/bge-base-en-v1.5，macOS 与其他 CPU 平台默认使用sentence-transformers/all-MiniLM-L6-v2。

中型模型（100M–500M 参数）

示例：facebook/contriever（110M 参数）、BAAI/bge-base-en-v1.5（110M 参数）

• 优点：性能均衡、多语言支持良好、速度合理
• 缺点：相比小型模型需要更多算力
• 适用场景：在不过分苛求算力的前提下追求更高质量的结果，适用于通用 RAG 应用

大型模型（500M+ 参数）

示例：Qwen/Qwen3-Embedding-0.6B（600M 参数）、intfloat/multilingual-e5-large（560M 参数）

• 优点：语义理解最强，能捕捉复杂关系，多语言支持出色；按官方文档描述，Qwen3-Embedding-0.6B的嵌入质量接近 OpenAI API 水平
• 缺点：推理更慢、索引构建时间更长
• 适用场景：质量优先且算力充足。强烈推荐用于生产环境

快速上手：云端与本地嵌入选项

OpenAI 嵌入（搭建最快）

如果希望不下载本地模型就立即测试（或者没有 GPU、且不太在意文档数据外泄，因为此时嵌入计算与重计算都通过 OpenAI API 完成），可以使用：

# 设置 OpenAI 嵌入（需要 OPENAI_API_KEY） --embedding-mode openai --embedding-model text-embedding-3-small

Ollama 嵌入（隐私优先）

完全本地、全程私密的嵌入方案：

# 首先拉取嵌入模型 ollama pull nomic-embed-text # 然后使用 Ollama 嵌入 --embedding-mode ollama --embedding-model nomic-embed-text

云端 vs 本地权衡

• OpenAI 嵌入（text-embedding-3-small/large）：无需本地算力、速度稳定、质量高；但需要 API Key、按量付费、数据离开本机，且对某些语言存在已知局限
  • 何时使用：原型验证、非敏感数据、需要立即出结果
• 本地嵌入：完全隐私、无持续成本、完全可控，某些情况下甚至可以超过 OpenAI 嵌入的效果；但比云端 API 慢、需要本地算力
  • 何时使用：生产系统、敏感数据、对成本敏感的应用

补充说明：当使用归一化嵌入模型（如 OpenAI 的text-embedding-ada-002、text-embedding-3-small/large，或 Voyage、Cohere 系列）时，packages/leann-core/src/leann/api.py 中的LeannBuilder会自动检测到归一化特征并自动设置distance_metric="cosine"，同时给出警告提示——归一化嵌入（L2 范数为 1）应使用余弦相似度而非 MIPS，这是保证检索质量的一个底层细节。

本地与远程推理端点

本节内容同时适用于 LLM（leann ask）与嵌入（leann build）。

LEANN 将 Ollama、LM Studio 以及其他兼容 OpenAI 协议的运行时视为一等公民（first-class providers）。你可以通过几个命令行参数或环境变量，将 LEANN 指向任何兼容端点——无论是本机还是跨网络的远程机器。

一次性环境变量配置

# 适用于兼容 OpenAI 协议的运行时：LM Studio、vLLM、SGLang、llamafile 等 export OPENAI_API_KEY="your-key" # 本地服务器不校验 key 时可留空 export OPENAI_BASE_URL="http://localhost:1234/v1" # 兼容 Ollama 协议的运行时（Ollama、其他主机上的 Ollama、llamacpp-server 等） export LEANN_OLLAMA_HOST="http://localhost:11434" # 依次回退到 OLLAMA_HOST 或 LOCAL_LLM_ENDPOINT

从 packages/leann-core/src/leann/settings.py 的resolve_ollama_host()与resolve_openai_base_url()可以看到精确的优先级链：

• Ollama 兼容端点：显式参数 >LEANN_LOCAL_LLM_HOST>LEANN_OLLAMA_HOST>OLLAMA_HOST>LOCAL_LLM_ENDPOINT> 默认http://localhost:11434
• OpenAI 兼容端点：显式参数 >LEANN_OPENAI_BASE_URL>OPENAI_BASE_URL>LOCAL_OPENAI_BASE_URL> 默认https://api.openai.com/v1

因此 LEANN 也识别LEANN_LOCAL_LLM_HOST（最高优先级）、LEANN_OPENAI_BASE_URL与LOCAL_OPENAI_BASE_URL，已有脚本可以无缝继续工作。

按命令传递端点

# 使用远程嵌入服务器构建索引 leann build my-notes \ --docs ./notes \ --embedding-mode openai \ --embedding-model text-embedding-qwen3-embedding-0.6b \ --embedding-api-base http://192.168.1.50:1234/v1 \ --embedding-api-key local-dev-key # 通过兼容 OpenAI 协议的本地 LM Studio 实例查询 leann ask my-notes \ --llm openai \ --llm-model qwen3-8b \ --api-base http://localhost:1234/v1 \ --api-key local-dev-key # 查询运行在另一台机器上的 Ollama 实例 leann ask my-notes \ --llm ollama \ --llm-model qwen3:14b \ --host http://192.168.1.101:11434

⚠️务必确保端点可达：当推理服务器运行在家用/工作站上、而索引/检索任务运行在云端时，服务器必须能够访问到你配置的主机。常见方案包括：

• 在托管 LM Studio/Ollama 的机器上暴露公网 IP（并开放相应端口）
• 配置路由器或云服务商的端口转发
• 通过tailscale、cloudflared或ssh -R等工具建立隧道

在构建索引时设置这些选项，LEANN 会将其写入meta.json。此后任何leann ask或检索进程都会自动复用同一套 provider 设置——即使是在后台派生嵌入服务器时也是如此。这使"云端无 GPU 服务器对接本地工作站"的工作流开箱即用。

提示：如果你的运行时不需要 API Key（很多本地栈都不需要），请直接省略--api-key，LEANN 会自动跳过凭据注入。

Python API 用法

同样的配置可以通过 Python 传入：

from leann.api import LeannBuilder builder = LeannBuilder( backend_name="hnsw", embedding_mode="openai", embedding_model="text-embedding-qwen3-embedding-0.6b", embedding_options={ "base_url": "http://192.168.1.50:1234/v1", "api_key": "local-dev-key", }, ) builder.build_index("./indexes/my-notes", chunks)

embedding_options会被持久化到索引的meta.json中，因此后续的LeannSearcher或LeannChat会话会自动复用相同的 provider 设置（嵌入服务器管理器会替你将其转发给 provider）。从 packages/leann-core/src/leann/api.py 的build_index()实现可以看到，meta_data中会写入"embedding_options": self.embedding_options字段，这正是持久化机制的来源。

可选嵌入特性

任务特定提示模板（Prompt Templates）

部分嵌入模型在训练时使用了任务特定提示，用以区分文档与查询。最典型的例子是Google 的 EmbeddingGemma，不同使用场景需要不同的提示：

• 索引文档时："title: none | text: "
• 检索查询时："task: search result | query: "

LEANN 通过--embedding-prompt-template参数支持自动前置提示：

# 使用 EmbeddingGemma 构建索引（通过 LM Studio 或 Ollama） leann build my-docs \ --docs ./documents \ --embedding-mode openai \ --embedding-model text-embedding-embeddinggemma-300m-qat \ --embedding-api-base http://localhost:1234/v1 \ --embedding-prompt-template "title: none | text: " \ --force # 使用查询专用提示检索 leann search my-docs \ --query "What is quantum computing?" \ --embedding-prompt-template "task: search result | query: "

开发过程中用于构建 LEANN 仓库自身索引的完整示例：

source "$LEANN_PATH/.venv/bin/activate" && \ leann build --docs $(git ls-files | grep -Ev '\.(png|jpg|jpeg|gif|yml|yaml|sh|pdf|JPG)$') --embedding-mode openai \ --embedding-model text-embedding-embeddinggemma-300m-qat \ --embedding-prompt-template "title: none | text: " \ --query-prompt-template "task: search result | query: " \ --embedding-api-key local-dev-key \ --embedding-api-base http://localhost:1234/v1 \ --doc-chunk-size 1024 --doc-chunk-overlap 100 \ --code-chunk-size 1024 --code-chunk-overlap 100 \ --ast-chunk-size 1024 --ast-chunk-overlap 100 \ --force --use-ast-chunking --no-compact --no-recompute

重要说明：

• 只用于兼容的模型：仅限 EmbeddingGemma 及类似的按任务区分的模型
• 不要用于常规模型：给nomic-embed-text、text-embedding-3-small、bge-base-en-v1.5等模型添加提示会破坏嵌入质量
• 模板会被保存：构建期的模板会保存到.meta.json供参考；构建阶段可以同时传--embedding-prompt-template与--query-prompt-template，这样 MCP 查询会自动拾取查询模板
• 提示灵活：可以使用任意提示字符串，也可以留空（""）

Python API 示例：

from leann.api import LeannBuilder builder = LeannBuilder( embedding_mode="openai", embedding_model="text-embedding-embeddinggemma-300m-qat", embedding_options={ "base_url": "http://localhost:1234/v1", "api_key": "lm-studio", "prompt_template": "title: none | text: ", }, ) builder.build_index("./indexes/my-docs", chunks)

对应到 CLI，build子命令支持--embedding-prompt-template与--query-prompt-template两个参数；search子命令也支持--embedding-prompt-template（见 packages/leann-core/src/leann/cli.py），两者共同构成"构建期模板保存 + 查询期模板自动复用"的完整链路。

LM Studio 自动检测（可选）

当通过兼容 OpenAI 协议的 API 使用 LM Studio 时，LEANN 可以选用 LM Studio SDK 自动检测模型上下文长度，从而免去手动配置 token 上限。

前置条件：

# 安装 Node.js（如果尚未安装） # 然后全局安装 LM Studio SDK npm install -g @lmstudio/sdk

工作原理：

1. LEANN 识别 LM Studio URL（URL 中包含:1234或lmstudio）
2. 通过 Node.js 子进程查询模型元数据
3. 查询后自动卸载模型（尊重你的 JIT auto-evict 设置）
4. SDK 不可用时回退到静态注册表

无需额外配置——只要安装了 SDK 就会自动生效：

leann build my-docs \ --docs ./documents \ --embedding-mode openai \ --embedding-model text-embedding-nomic-embed-text-v1.5 \ --embedding-api-base http://localhost:1234/v1 # SDK 可用时自动检测上下文长度 # 否则回退到注册表默认值（2048）

收益：

• ✅ 自动检测 token 上限
• ✅ 尊重 LM Studio 的 JIT auto-evict 设置
• ✅ 无需手动维护注册表
• ✅ SDK 不可用时优雅回退

注意：这完全是可选的。即使没有 SDK，LEANN 也能借助内置的 token 上限注册表正常工作。

从源码看，这一机制实现在 packages/leann-core/src/leann/embedding_compute.py 的get_model_token_limit()中：它采用混合策略——Ollama 通过/api/show动态发现上下文长度，LM Studio 通过 SDK 动态发现，否则回退到内置的EMBEDDING_MODEL_LIMITS注册表（例如nomic-embed-text: 2048、bge-m3: 8192、text-embedding-3-small/large: 8192），并以(model_name, base_url)为键缓存结果，避免重复调用。

索引选型：匹配你的规模

HNSW（分层可导航小世界图）

适用：中小规模数据集（< 1000 万向量）——默认选项，且是极低存储需求下的推荐项

• 需要完整重计算（full recomputation）
• 构建阶段内存占用高
• 召回率优秀（按文档描述可达 95%+）

# 适合大多数场景 --backend-name hnsw --graph-degree 32 --build-complexity 64

DiskANN

适用：大规模数据集，尤其是希望使用recompute=True时。

关键优势：

• 大规模数据集上检索更快（按文档描述，多数场景相比 HNSW 有 3 倍以上加速）
• 智能存储：recompute=True启用自动图分区，索引更小
• 扩展性更好：面向 10 万+ 文档设计

重计算行为：

• recompute=True（推荐）：纯 PQ 遍历 + 最终重排序——更快，且支持图分区
• recompute=False：遍历过程中使用 PQ + 部分真实距离——更慢但精度更高

# 推荐用于大多数场景 --backend-name diskann --graph-degree 32 --build-complexity 64

性能基准：可运行uv run benchmarks/diskann_vs_hnsw_speed_comparison.py（benchmarks/diskann_vs_hnsw_speed_comparison.py）在你的系统上对比 DiskANN 与 HNSW。

补充说明：CLI 的build子命令通过--backend-name选择后端（可选值hnsw、diskann、ivf，默认hnsw，见 packages/leann-core/src/leann/cli.py）。各后端以独立包形式注册进BACKEND_REGISTRY（packages/leann-core/src/leann/registry.py），例如leann-backend-hnsw、leann-backend-diskann、leann-backend-ivf。

LLM 选型：引擎与模型对比

LLM 引擎

OpenAI（--llm openai）

• 优点：质量最佳、性能稳定、无需本地资源
• 缺点：按量付费、需要联网、存在数据隐私顾虑
• 模型：gpt-4o-mini（快且便宜）、gpt-4o（质量最佳）、o3（推理）、o3-mini（推理且更便宜）
• Thinking Budget：o 系列推理模型（o3、o3-mini、o4-mini）可使用--thinking-budget low/medium/high
• 注意：目前是 LEANN 的默认引擎，但官方建议多数场景切换为 Ollama

Ollama（--llm ollama）

• 优点：完全本地、免费、隐私保护、模型种类丰富
• 缺点：需要本地 GPU/CPU 资源、比云端 API 慢、需要额外安装 Ollama 应用并预先通过ollama pull下载模型
• 模型：qwen3:0.6b（极快）、qwen3:1.7b（均衡）、qwen3:4b（质量较好）、qwen3:7b（高质量）、deepseek-r1:1.5b（推理）
• Thinking Budget：推理模型如gpt-oss:20b可使用--thinking-budget low/medium/high

HuggingFace（--llm hf）

• 优点：有免费档、模型选择极多、直接加载模型（不同于 Ollama 的服务器方案）
• 缺点：初始配置更复杂
• 模型：Qwen/Qwen3-1.7B-FP8

LiteLLM（--llm litellm）

• 优点：通过单一接口对接 100+ 后端（OpenAI、Anthropic、Gemini、Bedrock、Vertex、Azure、Groq、OpenRouter 等），模型前缀自动选择后端
• 缺点：需要可选依赖（pip install "leann-core[litellm]"）
• 模型：为模型加上 provider 前缀，例如gpt-4o（OpenAI）、anthropic/claude-haiku-4-5、gemini/gemini-2.5-flash、openrouter/meta-llama/llama-3.1-70b-instruct
• 凭据：自动读取各 provider 自己的环境变量（OPENAI_API_KEY、ANTHROPIC_API_KEY等）。若要经由自托管 LiteLLM 代理转发，请传--api-base http://localhost:4000 --api-key <virtual-key>（或设置LITELLM_BASE_URL/LITELLM_API_KEY）
• Thinking Budget：--thinking-budget low/medium/high映射到 LiteLLM 统一的reasoning_effort参数；对不支持推理的模型会被丢弃

# 通过 LiteLLM 查询，路由到 Anthropic（自动读取 ANTHROPIC_API_KEY）： leann ask my-docs --llm litellm --llm-model anthropic/claude-haiku-4-5 # 或指向自托管的 LiteLLM 代理： leann ask my-docs --llm litellm --llm-model gpt-4o \ --api-base http://localhost:4000 --api-key sk-my-virtual-key

从源码看，packages/leann-core/src/leann/chat.py 中实现了OllamaChat、OpenAIChat、HFChat等后端，并通过 packages/leann-core/src/leann/settings.py 的各resolve_*函数统一解析端点与凭据；ask子命令支持的 provider 还包括anthropic、minimax、novita、atlascloud等（见 packages/leann-core/src/leann/cli.py 的--llmchoices）。

参数调优指南

检索复杂度参数

--build-complexity（索引构建期）

• 控制索引构建时的搜索彻底程度
• 越大 = 召回越好，但构建越慢
• 建议取值：
  • 32：快速原型验证
  • 64：均衡（默认）
  • 128：生产系统
  • 256：追求极致质量

--search-complexity（查询期）

• 控制检索的彻底程度
• 越大 = 结果越好，但越慢
• 建议取值：
  • 16：快速/交互式检索
  • 32：高质量且兼顾多样性
  • 64+：追求最大准确度

CLI 中build的--complexity默认值为 64，search与ask的--complexity默认值分别为 64 与 32（见 packages/leann-core/src/leann/cli.py），与上述建议一致。

Top-K 选择

--top-k（返回的检索块数量）

• 块越多 = 上下文越充分，但 LLM 处理越慢
• 应始终小于--search-complexity
• 参考准则：
  • 10–20：一般性问题（默认 20）
  • 30+：需要全面上下文的复杂多跳推理

权衡公式：

• 检索时间 ∝ log(n) × search_complexity
• LLM 处理时间 ∝ top_k × chunk_size
• 总上下文 = top_k × chunk_size 个 token

推理模型的 Thinking Budget

--thinking-budget（推理努力程度）

• 控制推理模型的计算投入
• 可选值：low、medium、high
• 参考准则：
  • low：响应快、基础推理（简单查询的默认值）
  • medium：速度与推理深度均衡
  • high：最大推理投入，适合复杂分析类问题
• 支持模型：
  • Ollama：gpt-oss:20b、gpt-oss:120b
  • OpenAI：o3、o3-mini、o4-mini、o1（o 系列推理模型）
• 注意：不支持推理的模型会给出警告并跳过推理参数
• 示例：复杂分析类问题使用--thinking-budget high

详细的用法示例与实现细节可参阅 docs/THINKING_BUDGET_FEATURE.md。从该文档可知：Ollama 后端将thinking_budget转换为reasoning: {"effort": ..., "exclude": False}参数，OpenAI 后端则对 o 系列模型（o3、o3-mini、o4-mini、o1等）设置reasoning_effort，参数通过 CLI → RAG 示例脚本 →LeannChat→ LLM 后端的链路完整传播。

快速示例：

# OpenAI o 系列推理模型 python apps/document_rag.py --query "What are the main techniques LEANN explores?" \ --index-dir hnswbuild --backend hnsw \ --llm openai --llm-model o3 --thinking-budget medium # Ollama 推理模型 python apps/document_rag.py --query "What are the main techniques LEANN explores?" \ --index-dir hnswbuild --backend hnsw \ --llm ollama --llm-model gpt-oss:20b --thinking-budget high

图度数（HNSW/DiskANN）

--graph-degree

• 图中每个节点的连接数
• 越大 = 召回越好，但内存占用越高
• HNSW：16–32（默认 32）
• DiskANN：32–128（默认 64）

性能优化清单

嵌入太慢怎么办

1. 切换到更小的模型：

   # 从大模型 --embedding-model Qwen/Qwen3-Embedding-0.6B # 换到小模型 --embedding-model sentence-transformers/all-MiniLM-L6-v2

2. 为测试限制数据集规模：

   --max-items 1000 # 只处理前 1k 条

3. 在 Apple Silicon 上使用 MLX（可选优化）：

   --embedding-mode mlx --embedding-model mlx-community/Qwen3-Embedding-0.6B-8bit

   需要注意：MLX 可能不是最优选择——根据实测，MLX 相对 HuggingFace 仅有约 1.3 倍加速，因此生成嵌入时使用 Ollama 也许是更好的选择。

4. 使用 Ollama：

   --embedding-mode ollama --embedding-model nomic-embed-text

   可以在 Ollama 的嵌入模型目录中寻找更多候选模型，请务必选择与你需求匹配的模型规模。

检索质量不佳怎么办

1. 增加检索数量：

   --top-k 30 # 检索更多候选

2. 升级嵌入模型：

   # 针对英文 --embedding-model BAAI/bge-base-en-v1.5 # 针对多语言 --embedding-model intfloat/multilingual-e5-large

理解各项权衡

每一个配置选择都涉及权衡：

关键是为你的具体场景找到合适的平衡点：从小而简单的配置开始，测量性能，然后只在需要的地方逐步扩展。

关于块大小，packages/leann-core/src/leann/cli.py 给出了可精确控制的参数：--doc-chunk-size（默认 256 tokens，512-token 模型建议 350）、--doc-chunk-overlap（默认 128，额外叠加在块大小之上）、--code-chunk-size（默认 512）、--code-chunk-overlap（默认 50），以及启用--use-ast-chunking后的--ast-chunk-size（默认 300 字符）与--ast-chunk-overlap（默认 64 字符）——这些值直接决定了"总上下文 = top_k × chunk_size"公式中的 chunk_size。

低资源配置方案

如果本地没有 GPU，或者构建/检索太慢，可以使用以下一个或多个方案。

1) 使用 OpenAI 嵌入（零本地算力）

无本地 GPU 需求的最快路径。设置 API Key 后，在构建与检索时使用 OpenAI 嵌入：

export OPENAI_API_KEY=sk-... # 使用 OpenAI 嵌入构建 leann build my-index \ --embedding-mode openai \ --embedding-model text-embedding-3-small # 使用 OpenAI 嵌入检索（查询时重计算） leann search my-index "your query" \ --recompute

2) 使用 SkyPilot 进行远程构建（云 GPU）

使用 SkyPilot。

# 一次性：安装并配置 SkyPilot pip install skypilot # 使用默认参数启动（L4:1），将 ./data 挂载到 ~/leann-data，构建会自动运行 sky launch -c leann-gpu sky/leann-build.yaml # 通过 -e key=value 覆盖参数（可选） sky launch -c leann-gpu sky/leann-build.yaml \ -e index_name=my-index \ -e backend=hnsw \ -e embedding_mode=sentence-transformers \ -e embedding_model=Qwen/Qwen3-Embedding-0.6B # 将构建好的索引复制回本地 .leann（使用 rsync） rsync -Pavz leann-gpu:~/.leann/indexes/my-index ./.leann/indexes/

从模板文件看，sky/leann-build.yaml提供了完整的可覆盖环境变量：backend（hnsw/diskann）、complexity（默认 64）、graph_degree（默认 32）、num_threads（默认 8）、embedding_mode（sentence-transformers/openai/mlx/ollama）、embedding_model（默认facebook/contriever）、recompute（默认 true，推荐）、compact（仅 HNSW）、force（默认 true）；run阶段会把这些变量拼装为python -m leann.cli build命令，并输出索引目录供下游 rsync 使用。

3) 关闭重计算，用存储换速度

如果对延迟更敏感、且存储/内存充足，可以关闭重计算。这会存储完整嵌入，避免在检索时重算。

# 无重计算构建（HNSW 在此模式下必须使用非紧凑存储） leann build my-index --no-recompute --no-compact # 无重计算检索 leann search my-index "your query" --no-recompute

何时使用：

• 极致低延迟需求（高 QPS、交互式助手）
• 读多写少、存储比延迟便宜的工作负载
• 没有常驻可用的 GPU

约束条件：

• HNSW：设置--no-recompute时，LEANN 会自动在构建期禁用紧凑模式。这一行为在 packages/leann-core/src/leann/api.py 的LeannBuilder.__init__中有明确实现：当backend_name == "hnsw"且is_recompute=False而is_compact=True时，会自动强制is_compact=False并发出警告
• DiskANN：支持；--no-recompute会跳过检索期的选择性重计算

存储影响：

• 以 float32 存储 N 个 D 维嵌入，约需 N × D × 4 字节
• 示例：1,000,000 个块 × 768 维 × 4 字节 ≈ 2.86 GB（另加图与元数据）

转换已有索引（需要重建）：

# 原地重建（请确保仍保留原始文档或能重新生成块） leann build my-index --force --no-recompute --no-compact

Python API 用法：

from leann import LeannSearcher searcher = LeannSearcher("/path/to/my-index.leann") results = searcher.search("your query", top_k=10, recompute_embeddings=False)

权衡：

• 查询期延迟更低、网络跳数更少
• 存储显著增大（相比选择性重计算约 10–100 倍）
• 构建与检索期的内存占用略高

快速基准结果（来自 benchmarks/benchmark_no_recompute.py，5k 文本、complexity=32）：

• HNSW

  recompute=True: search_time=0.818s, size=1.1MB recompute=False: search_time=0.012s, size=16.6MB

• DiskANN

  recompute=True: search_time=0.041s, size=5.9MB recompute=False: search_time=0.013s, size=24.6MB

该基准脚本会为 HNSW 与 DiskANN 各构建recompute=True/False两个变体，用中位数多次计时，并统计索引目录总大小，可直接复现上表数据。

结论：

• HNSW：no-recompute显著更快（无需重算嵌入），但存储需求大得多（需存储全部嵌入）
• DiskANN：no-recompute在遍历中使用 PQ + 部分真实距离（更慢但精度更高）；而recompute=True使用纯 PQ 遍历 + 最终重排序（遍历更快，且支持构建期图分区，存储更小）

延伸阅读

• 本文参考的官方配置文档：docs/configuration-guide.md
• Thinking Budget 特性实现细节：docs/THINKING_BUDGET_FEATURE.md
• SkyPilot 远程构建模板：sky/leann-build.yaml
• 无重计算基准脚本：benchmarks/benchmark_no_recompute.py
• DiskANN vs HNSW 速度对比脚本：benchmarks/diskann_vs_hnsw_speed_comparison.py
• LEANN 技术论文（MLSys 2026 Best Paper）：即项目描述中提到的论文（arXiv: 2506.08276），其中详细阐述了选择性重计算与图剪枝的存储节省原理

总结：LEANN 的配置哲学是"从小处着手、按需扩展"。嵌入模型决定检索质量上限，索引后端决定规模化能力，LLM 引擎决定回答质量与成本，而--build-complexity、--search-complexity、--top-k、--graph-degree、--thinking-budget以及--recompute等参数则构成了一套细粒度的"质量-速度-存储"调节旋钮。结合本文给出的环境变量优先级、命令行参数与 Python API 示例，你可以为文档、代码、邮件、聊天记录乃至任意个人数据，搭建一套完全符合自身硬件与隐私需求的 LEANN RAG 系统。

【免费下载链接】LEANN[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.项目地址: https://gitcode.com/GitHub_Trending/le/LEANN