第三章：LEANN的实践与开发

第三章：LEANN的实践与开发

本章跟着一条线走：先把环境跑起来，再用命令行把索引建好，然后写 Python 把能力接进业务，最后用配置把参数收拢到一处。

前两章我们在「设计」层面，这一章落到「操作」层面。LEANN 的工程取向是：能脚本化的别手写，能配置化的别硬编码。所以你会看到 CLI 负责把重复动作固化，API 负责把能力暴露给业务，配置负责把零散参数集中。

这一章最容易踩的坑是「环境不一致」：开发机跑得好好的，到边缘设备缺一个依赖就崩。我们会在 3.1 给出可校验的环境自检，3.2 给出可复现的 CLI 流程，3.3 给出最小可运行 API，3.4 给出配置schema。

读完本章你能考核四件事：环境如何自检、CLI 如何建索引、API 如何编程、配置如何管理与优化。下一章深入检索本身的高级玩法。

四节是怎么安排的

• 3.1 环境搭建与开发准备：从零装好依赖，给出一套可校验的环境自检，杜绝「开发机能跑、边缘设备缺依赖就崩」。
• 3.2 命令行工具（CLI）使用：把建索引、检索、导出这些重复动作固化成命令，可复现、可脚本化。
• 3.3 Python API 编程指南：把能力接进真实业务，讲清 retrieve 与 augment 的职责划分与资源管理。
• 3.4 配置管理与优化：把散落在各处的参数收拢到一处，环境不同、配置不同，代码不用改。

学本章前要确认的几件事

• 有一台能跑 Python 3.9 的机器，有 pip 安装权限。
• 会看命令行帮助（--help）和最基本的 Python 语法。
• 建议准备一份几十篇文档的小语料，全章的练习都围着它转，建出的索引就是后续章节的实验基地。

本章最大的坑：环境不一致

开发机跑得好好的，到边缘设备缺一个依赖就崩，这是本章最常遇到的事故。对策有三条：依赖写死版本号、提供环境自检命令、在目标设备上做一次干净环境演练。3.1 到 3.4 每一步都该在这套纪律下执行，先自检、再动手、后验收。

为什么是 CLI 而不是临时脚本

建索引这类动作如果每次靠人写 Python 脚本，团队里十个人就有十种写法，目录结构、参数、输出格式全不一样。CLI 把流程固化成同一个命令，配合配置管理，任何人拿到同一份输入都能得到同一份输出。这是「能脚本化的别手写」这句话落地的第一步。

学完自检清单

• 能否在全新环境下一键完成自检并通过。
• 能否用 CLI 从语料建出索引并检索出正确结果。
• 能否用 Python API 完成「加载→检索→增强→回答」四步。
• 能否用配置管理不同设备的参数而不改代码。

与前后章节的衔接

第三章把第二章的架构设计落成可运行代码，是全书动手量最大的章节；第四章的过滤、混合、增量更新都要基于第三章的索引与 API 继续叠加。这一章的工具（CLI、API、配置）会一直用到第五、六章。

建议的节奏与验收时刻

本章适合边读边敲：读完 3.1 就把环境装好，读完 3.2 建出第一份索引，读完 3.3 写完第一段检索代码。每节末尾的可考核点就是下一个动手任务的验收标准。建议整章保留一个练习目录，把命令和代码集中存放，方便后续章节回查。

三个验收时刻值得记下来：装完环境跑通自检输出 OK；建完索引用 CLI 检索出正确命中的文档；写完 API 后脚本连续查询 20 次内存不回涨。

下一章进入高级检索：近似最近邻、过滤聚合、混合策略与增量更新。