《WaLiAPI 本地 LLM API 网关》第3-4节实战：向量化、HNSW 索引与检索基础设施构建

• 文档
• 教程
• 后端

本篇技术指南围绕 WaLiAPI 知识库流水线的"承上启下"环节展开——在完成知识库数据模型与文档解析后，如何让分块后的文本真正"活"起来：复用网关渠道调度能力完成向量化（embedder）、构建轻量级 HNSW 索引、编排 processor 处理流水线、打通 importer 多源导入，并落地 FTS5 全文索引，为下一节的混合检索与 RAG 问答铺平道路。读者读完将掌握一套零外部依赖的本地知识库索引实现思路，以及"向量索引 + 关键词全文索引"混合检索的设计动机。

一、本章诉求

上一节（第3-3节：知识库数据模型与文档解析）完成了知识库四张表（kb_knowledge_bases、kb_documents、kb_chunks、kb_tasks）的设计与文档解析，文档被切成 chunk 存进了数据库。但此时 chunk 只是"躺"在库里的一堆文本，还不能被语义检索。本节要让 chunk 具备被检索的能力，核心诉求共六条：

1. 实现 embedder 模块——复用 WaLiAPI 的渠道调度能力调用 Embeddings API
2. 实现轻量级 HNSW 索引——构建 / 搜索 / 持久化 / 增量更新
3. 实现 processor 流水线——文档处理的完整生命周期
4. 实现 importer 多源导入——Git / URL / 本地目录
5. 实现 FTS5 全文索引——为混合检索提供关键词搜索能力
6. 理解向量索引 + FTS5 混合检索的设计动机

这六条诉求共同勾勒出知识库流水线中段的完整轮廓：向量化 → 索引构建 → 全文索引 → 多源导入，全部服务于下一节（第3-5节：知识库检索与RAG问答）的"检索 → 生成"输出端。

二、向量化：embedder.rs

2.1 为什么复用渠道调度

知识库需要调用 Embeddings API 将文本转换为向量，这是向量化环节的必经之路。但 WaLiAPI 本身就是一个本地运行的 LLM API 网关，已经具备完善的渠道调度（Dispatcher）、重试机制、多渠道 fallback 能力。

为什么不直接用这些能力，而要另起炉灶？这是本章第一个关键设计决策。直接复用意味着：不需要额外配置，用户已有的渠道设置（渠道、模型、密钥、负载策略）可以原封不动地服务于知识库向量化。embedder 的调用流程如下：

┌─────────────────────────────────────────────────────┐ │ embedder 调用流程 │ │ │ │ texts → embed() → get_enabled_channels() │ │ → Dispatcher::select_channels(model) │ │ → try_embed_with_channel() → channel 1 │ │ → 失败？ → try next channel → channel 2 │ │ → 成功 → Vec<Vec<f32>> │ │ │ │ 不需要额外配置，复用用户已有的渠道设置 │ └─────────────────────────────────────────────────────┘

从流程可见，embedder 的容错哲学是"逐渠道重试、失败则 fallback"：只要用户配置的渠道中有一个可用，向量化就能成功。这与 WaLiAPI 网关在处理 LLM 对话请求时"多渠道 fallback"的调度策略完全一致，也让知识库的向量化能力天然继承了网关的渠道治理能力。

在真实使用层面，WaLiAPI - 端到端，知识库（RAG） 明确指出：下载后要配置 LLM 模型渠道，确保渠道可用，有可使用的向量模型，推荐text-embedding-3-small。新建知识库时，向量模型默认使用text-embedding-3-small，并可在设置中绑定具体渠道——这正是 embedder 复用渠道调度能力的落地形态。

2.2 embed 函数

embedder 的核心入口是embed函数，其签名与逻辑如下：

pub async fn embed( texts: &[String], model: &str, repo: &Repository, ) -> Result<Vec<Vec<f32>>, String> { // 1. 获取启用的渠道 let channels = repo.get_enabled_channels().await...; // 2. 选择支持该模型的渠道 let selected = Dispatcher::select_channels(&channels, model); let candidates = if selected.is_empty() { channels.clone() } else { selected }; // 3. 逐个尝试 for channel in &candidates { match try_embed_with_channel(texts, model, channel).await { Ok(embeddings) => return Ok(embeddings), Err(e) => continue, // fallback to next channel } } Err("All channels failed for embedding model".to_string()) }

这段代码可以拆解为三个关键步骤：

• 步骤 1：获取启用的渠道——从仓储层读取用户已启用（enabled）的渠道列表。这里的"启用"状态与 WaLiAPI 渠道管理模块中渠道的启停开关一致，确保知识库只会使用用户主动放开的渠道。
• 步骤 2：按模型筛选候选渠道——Dispatcher::select_channels(&channels, model)依据模型名筛选出支持该 Embeddings 模型的渠道。candidates的取值逻辑很巧妙：如果筛选结果为空（没有任何渠道声明支持该模型），则退而求其次使用全部启用渠道，避免因渠道元数据缺失导致能力空转；否则使用筛选结果。
• 步骤 3：逐个渠道尝试——对每个候选渠道依次调用try_embed_with_channel，成功即返回Vec<Vec<f32>>（每个输入文本对应一个 f32 向量），失败则continue跳到下一个渠道，全部失败才返回错误"All channels failed for embedding model"。这一"宁可遍历全部候选，也不轻易失败"的设计，正是网关多渠道 fallback 思想在知识库场景的移植。

从返回类型Vec<Vec<f32>>可以看出，向量化输出的是稠密浮点向量数组，这与 第3-3节 中kb_chunks表的embedding BLOB字段对应——向量在落库时通过 bincode 序列化为二进制存入 BLOB，比 JSON 存储节省约 50% 空间。embedder 产出的向量正是后续 HNSW 索引构建与检索的"燃料"。

三、轻量级 HNSW 索引

3.1 什么是 HNSW

HNSW，全称Hierarchical Navigable Small World（分层可导航小世界图），是一种**近似最近邻搜索（ANN）**算法，专门用来在海量向量中快速找到最相似的几个。通俗地说，HNSW 是让向量搜索从"挨个比对"变成"按图导航"的技术——这也是 WaLiAPI 知识库索引方案选型的核心原因。

在 WaLiAPI 中，HNSW 的定位是"轻量级"：不依赖外部向量数据库，而是作为进程内索引与 SQLite 协同工作——向量本体以 BLOB 形式存在kb_chunks.embedding中，HNSW 图结构负责提供近似最近邻的快速导航。

3.2 构建 / 搜索 / 持久化 / 增量更新

本章诉求要求 HNSW 索引具备四个完整能力：

• 构建（build）：从知识库的全部 chunk 向量构建分层图结构，将高维向量空间组织成可导航的小世界网络。
• 搜索（search）：给定查询向量，在图中从高层（粗粒度）逐层下探到低层（细粒度），快速返回 top_k 个最相似向量的位置编号。
• 持久化（persist）：索引构建完成后序列化落盘，避免每次启动都重新构建。在 WaLiAPI - 端到端，知识库（RAG） 的使用说明中，创建的知识库会通过 HNSW 构建索引，前端【索引】页提供"重新构建索引"入口——这正是持久化与重建机制的交互体现。
• 增量更新（incremental update）：知识库新增文档、新增 chunk 后，在已有索引基础上增量插入新向量，而不是全量重建。

这些能力在下一节的检索链路中会完整兑现：从 第3-5节 的search函数可以看到，检索时优先load_index(kb_id)加载 HNSW 索引并执行index.search(query_embedding, top_k)，随后把索引返回的 position id 映射回 chunk_id 与 chunk 内容；当索引不存在或维度不匹配时（如换了 embedding 模型导致维度变化），则自动降级为线性扫描——逐 chunk 从 BLOB 解码 embedding、计算余弦相似度、排序取 top_k。这一"索引优先、扫描兜底"的容错设计，保证了知识库在任何情况下都能检索，只是性能不同。

四、processor 流水线：文档处理的生命周期

向量化与索引只是能力单元，真正把它们串起来的是 processor 模块——文档处理的完整生命周期编排。结合第3-3节的数据库设计，一条文档从进入到可检索，要经历完整的状态流转：

pending → processing → ready / failed

• pending：文档刚上传/导入，等待处理；
• processing：正在执行解析、分块、向量化、索引构建；
• ready：向量与索引就绪，可被检索；
• failed：处理过程出错，error_message记录失败原因。

kb_tasks表专门记录这种异步处理的进度——task_type（embed / index / import）、progress、done_items / total_items共同支撑起"异步任务追踪"：用户在前端看到的是"处理中 X/Y"，底层就是 processor 在推进这些字段。这也解释了为什么第3-3节要在kb_documents.status上设计pending→processing→ready→failed状态机——文档处理是异步的，需要状态追踪。

processor 流水线的核心价值在于：把解析、分块、向量化、索引更新这些步骤编排成一条可观测、可失败重试的管道，为 importer 和上传两种入口提供统一的处理出口。

五、importer 多源导入：Git / URL / 本地目录

知识库的价值不仅在于上传单个文件，更在于把整个代码库"喂"进来。importer 模块支持三种来源：

• Git 仓库：直接拉取远程仓库（或本地仓库路径），将代码库转换为知识库；
• URL：抓取网页内容入库；
• 本地目录：扫描本地目录下的全部文件入库。

这一能力在 WaLiAPI - 端到端，知识库（RAG） 的产品说明中对应"来源上传"功能——支持 Git 仓库、URL、本地目录，"这样可以非常方便的把代码库转换为知识库"。配合第3-3节实现的 tree-sitter 符号感知代码解析（code_parser.rs），代码库导入后可以按函数、类、符号维度分块，而不是简单按行切分——这是知识库能检索代码语义的关键前提。

从kb_documents表结构可以印证导入路径的设计：file_path字段专门记录"本地文件路径（如果是导入）"，而content_hash（SHA256）用于防止重复导入同一文档——hash 相同则跳过，避免多次导入同一 Git 仓库造成数据膨胀。

六、FTS5 全文索引：关键词检索的基石

向量检索擅长语义相似，但对精确关键词匹配（函数名、报错码、专有名词）力不从心。为此，本章诉求要求实现 FTS5 全文索引——SQLite 内置的全文检索扩展，为混合检索提供关键词搜索能力。

FTS5 在 WaLiAPI 检索体系中的角色，从 第3-5节 的"检索能力层次"图中可以看得非常清楚：系统同时具备Vector Search（语义相似度、cosine distance）与FTS5 Search（关键词匹配、rank scoring）两条检索通道，再通过Hybrid Search做加权融合，最后叠加Symbol Filter（基于symbol_kind、symbol_name的代码检索增强）输出SearchResult[]（chunk_id, content, score, meta）。

需要说明的是，FTS5 对中文检索天然不友好（按空格/标点分词），这一点在后续的 第3-8节：混合检索调优与检索可视化 中通过 CJK Bigram 中文分词得到补强——这是后话，但说明"全文索引"这一层在设计之初就为混合检索预留了演进空间。

七、向量索引 + FTS5 混合检索的设计动机

为什么要同时构建 HNSW 向量索引和 FTS5 全文索引，而不是二选一？核心动机是：不同查询类型的"最优检索方式"完全不同。

语义向量能把"线程安全"关联到"锁机制"，这是 FTS5 做不到的；而 FTS5 能精确命中tokio::spawn这种符号级关键词，语义向量在此时反而会"漂移"。

因此本节的索引构建是"双轨制"：HNSW 管语义召回，FTS5 管精确匹配，二者在检索阶段做加权融合。从 第3-5节 与 第3-8节 可以看到，融合权重默认写死为0.7 * vector + 0.3 * fts5，这一默认值在 3-8 节被参数化并交给用户调整——但"混合检索"这一设计动机，正是本节构建 HNSW 与 FTS5 两份索引的根本原因：没有双索引，就没有混合检索；没有混合检索，就无法同时满足语义召回与精确匹配两类查询。

八、承上启下：为检索与 RAG 铺路

至此，本节完成了知识库流水线的中段闭环：

1. embedder复用网关渠道调度，把 chunk 文本批量转为向量（Vec<Vec<f32>>）；
2. HNSW 索引提供轻量级近似最近邻搜索，支持构建 / 搜索 / 持久化 / 增量更新；
3. processor 流水线编排文档处理生命周期，kb_tasks追踪异步进度；
4. importer打通 Git / URL / 本地目录三种来源，把代码库便捷地转换为知识库；
5. FTS5 全文索引补齐关键词检索能力；
6. 双索引并存为混合检索奠定基础。

下一节（第3-5节：知识库检索与RAG问答）将把这些基础设施组合成"输出端"：retriever模块执行 HNSW 向量搜索 + FTS5 关键词搜索 + 加权融合 + 符号过滤，rag模块完成多轮对话、Token 限制降级与来源引用，最终通过 handlers / routes / Tauri commands 暴露给用户。如果你还想了解这套检索基础设施在前端如何被调优和可视化，可继续阅读 第3-8节：混合检索调优与检索可视化。

• 文档
• 教程
• 后端