在构建专业级的本地素材库和音乐库时，传统的搜索架构往往面临着严峻的挑战：当用户在搜索框里输入“史诗般庞大的气势”或“宁静的钢琴”时，基于关键词拆分的数据库搜索（如 SQLite FTS5）往往只能精确匹配出字段里带有这些字的曲目。这导致了海量拥有丰富标签（但用词不一）的音频素材石沉大海。
为了彻底解决这一痛点，我们在最新的底层重构中，全面升级为结合 LanceDB 向量数据库 和 BGE-M3 端侧模型 的混合检索 (Hybrid Search) 架构。
一、突破 SQLite FTS5 的极限
在此前版本的 PureLab 中，核心搜索完全依赖于 SQLite 的全文搜索模块 (FTS5)。这种架构简单且响应极快，但在实际业务中遇到了瓶颈：
- 语义鸿沟：用户的搜索词和实际音频的标签（如 genre / mood）往往并不完全对齐（比如搜“快乐”漏掉标注为“happy”的轨道）。
- 多语言交叉匹配弱：音乐元数据极度分散于多语言描述中，单纯的分词器无法建立跨语言的语义关联。
二、双轨召回与混合架构
为引入语义层，我们并没有抛弃词法检索，而是采用 双轨召回与排序融合 (Dual-Lane Retrieval & RRF) 的模式，将 LanceDB 深度嵌入到现有的 SQLite 架构之上。
1. 独立投影表与 BGE-M3 嵌入
针对每一个归一化的用户资料库（Root），我们都在其 .lancedb/ 目录下单独建立了一张 text_vectors 投影表。
- 本地 ONNX 推理：当索引重建机制触发时（Phase B 阶段），系统会调度基于
ort的后台引擎，将元数据文本交由 BGE-M3 Int8 的 ONNX 模型本地运算，产出高质量的 1024 维f32向量并 Upsert 入库。 - 账本与重试机制 (Ledger)：为了避免大批量向量化由于设备性能原因被强行中断，我们在 SQLite 中设计了一张
text_vector_index_ledger表，追踪每一行文本状态（pending,indexed,failed），使得哪怕程序意外重启，系统也能从中断处完美继续拉起重试 Lease。
2. Lexical 与 Semantic 双提供者 (Provider)
当用户键入搜索时，架构会在后端分叉为两个核心 Provider：
- LexicalRetrievalProvider：依旧通过 FTS5 提供强关联的硬匹配（确保直接搜索文件名和明确的标签 100% 召回）。
- SemanticRetrievalProvider：加载 BGE 推理环境，计算用户 Query 的向量，并交由 LanceDB 的 ANN（近似最近邻）进行语义搜索。
三、融合排序艺术：Text-Priority RRF
把两路结果结合在一起并给出最终列表（ResultList）才是真正的难点。
我们没有采用高延迟的 Cross-encoder 重排器，而是使用了一种经过调优的 Text-Priority RRF (Reciprocal Rank Fusion) 算法进行后处理：
$$
Score_{RRF} = \frac{1}{K + \text{Rank}{Lexical}} + \frac{W{Semantic}}{K + \text{Rank}_{Semantic}}
$$
[!NOTE]
在我们的实现中：
- $K = 60$
- 词法 (Lexical) 匹配的权重 $W_{Lexical} = 1.0$
- 语义 (Semantic) 匹配的权重 $W_{Semantic} = 0.95$
通过对 Semantic 侧施加微小的权重折减（0.95），我们确保了当一个音频文件的词法直接被命中时，它永远能排在那些仅仅是“语义相近”的结果之前，最大限度还原了用户对于“搜索”的传统预期，同时又通过长尾部分补充了语义相关的宝藏轨道。
四、双库并行：针对音乐与素材的过滤
不同的应用场景有着完全不同的索引要求。在 LanceDB 检索出来的结果中（TextVectorSearchHit），我们在特征上绑定了 library_type（“music” 或 “material”）以及 surface。
这意味着即使用户同时管理几百 GB 的无损音乐专辑与音效素材集，搜索链路也能在 ANN 召回的同时执行精准的特征切分，绝不会让环境音效混进你的音乐流派播放列表中。
结语
百万级本地曲库的检索挑战，本质上是如何在端侧有限的计算资源下找到准与全的平衡点。结合 LanceDB 与轻量 ONNX 模型的混合检索架构不仅没有牺牲用户的隐私数据，反而将检索体验提升到了前所未有的高度。在未来的版本中，我们还计划探索将元数据切块（Chunking）以支持更长描述字段的检索。