本文围绕独立实战应用《离线私密知识闪搜库》(rn-private-knowledge-vault)展开,基于 react-native-data-retrieval 接入鸿蒙中文分词建表、多路倒排策略与 RRF 重排能力,并在华为畅享 100 Pro Max 真机与 API 26 模拟器核对原生检索与 SQL LIKE 对照结果。
配套实战项目已开源在 abaoge/rn-private-knowledge-vault,所用第三方库公开基线见 abaoge/react-native-data-retrieval,有问题可到该库提 Issue,也可以来 鸿蒙系统 React Native 开源社区 交流。

前言

📱 我在做一个 React Native 鸿蒙本地笔记检索应用《离线私密知识闪搜库》,想让用户输入关键词后直接搜出相关笔记,并看清标题、标签和正文怎么影响排序。接上系统 @kit.DataAugmentationKit 后,模拟器上的系统能力探测明明通过了,真正执行检索时却报错读不到通道配置。于是我顺着调用链路补上失败阶段和错误回执,把原生检索与独立 SQL LIKE 对照拆成两栏展示。

换到真机后,应用里的 14 条测试笔记跑通了多路倒排和单路 BM25 查询,现场新增的第 15 条笔记也能立刻查出来。不过几次查询的耗时跨度不小,模拟器的原生检索依然停在配置阶段。下面从实际遇到的检索问题说起,聊聊我是怎么利用第三方库安排检索策略、写入事务和设备降级的。

一、使用场景与真实痛点

1.1 本地笔记检索遇到的三个问题

实战工程《离线私密知识闪搜库》(rn-private-knowledge-vault)在业务层准备了 14 条中英文测试笔记,内容涵盖鸿蒙开发、会议纪要、差旅报销和端侧安全。启动应用后,用户点击初始化按钮就能把笔记写入应用沙箱数据库,随后输入关键词、切换检索模式,查看命中的笔记与相关度分值;点击“+ 新增笔记即查”则会生成一条带当前时间戳的新笔记,写入后马上发起查询。

这个页面专门用来观察本地全文检索和排序表现,所以新增操作直接生成固定格式的笔记样本,没有做完整的富文本编辑、附件导入和权限管理。离线手册、个人备忘录或会议归档遇到本地搜索需求时可以参考这套做法,文中的实测数字则全部来自这组样本。

从用户操作看,输入关键词并点击检索后,RN 页面通过插件调用系统倒排检索,同时支持与普通 SQL LIKE 扫描结果并排核对:

同一手机输入关键词并查看结果,页面通过自研 RN 插件调用鸿蒙检索能力

图1 笔记检索流程

做这个页面时,我主要卡在三个具体问题上:

第一个问题是拆词与匹配范围难兼顾。如果直接拿整句关键词去跑 SQL LIKE 子串匹配,只要笔记里两个词中间隔了别的字,查询就会落空。反过来把长词拆成二字片段再用 OR 拼接,虽然能把散落在正文里的笔记捞回来,但只擦边命中一个短词的无关笔记也会挤进结果列表。

第二个问题是多字段排序缺依据。一条笔记里有标题、标签、分类和正文,命中标题显然比正文末尾出现一次更重要。普通包含判断给不出词频和词距特征,我也不想在 RN 的 JS 线程里自己维护分词词典和打分循环,更希望直接调用系统原生的多路召回与重排接口拿回现成分值。

第三个问题是能力探测通过后仍可能调用失败。不同鸿蒙设备或模拟器镜像对检索组件的支持程度不一样。哪怕启动时系统能力检查返回支持,真正创建检索器时仍可能因为底层枚举缺失而报错。应用必须拿到准确的失败阶段和错误码,才能判断该提示环境受限,还是切换到普通文本查询兜底。

1.2 所用第三方库与工程职责分工

为了把通用检索能力和具体笔记界面分开,实战工程直接引入第三方库 react-native-data-retrieval(版本 0.1.0,MIT 许可,鸿蒙原生 HAR 包名为 @rnoh/react-native-data-retrieval)。这个库基于鸿蒙 @kit.ArkData(关系型存储与中文分词虚拟表)和 @kit.DataAugmentationKit(端侧多路倒排检索与重排)封装跨端 TurboModule,内部不夹带任何演示笔记或密级字段。

层次负责的内容使用边界
HarmonyOS 系统提供关系型数据库、CUSTOM_TOKENIZER 中文分词、倒排召回与 RRF 重排实际可用性受设备与系统镜像影响
第三方库 react-native-data-retrieval参数校验、沙箱开库、读写守卫与事务同步、多路检索配置、分值转换和分段计时不内置业务样本,原样带回底层错误码与失败阶段
实战工程 rn-private-knowledge-vault维护 14 条测试笔记、处理搜索输入与模式切换、展示双通道对比卡片与回执日志消费第三方库演示检索场景,不包含完整商业笔记编辑流

表1 职责分工

第三方库对外提供八个异步方法:能力探测 getCapabilities、开库切库 openStore、批量与单条写入 upsertDocuments / upsertDocument、按主键删除 removeDocument、全库清空 clearDocuments、多路倒排检索 search 以及独立对照查询 sqlLikeSearch。库自带的示例页只放基础按钮验证接口回执;完整的档案馆风格界面、14 条测试样本和卡片内展示的 S2 至 S4 密级标签(存放在通用文档的 metadata 扩展对象里),都留在独立的实战工程 rn-private-knowledge-vault 中。

二、真机结果与模拟器边界

2.1 测试环境与计时口径

我在华为畅享 100 Pro Max 真机和 HarmonyOS API 26 直板模拟器上安装了同一份实战工程构建,逐项核对建库、检索、切换模式和新增即查的表现。

项目实测配置
开发与构建工具DevEco Studio 26.0.0.865(编译 SDK 26.0.0,最低兼容 6.0.0(20))
React Native / RNOH0.84.1 / 0.84.6
所用第三方库react-native-data-retrieval 0.1.0(@rnoh/react-native-data-retrieval),固定提交 10ace8e6
独立实战工程rn-private-knowledge-vault 1.0.0,固定提交 b6ea385f,通过 git+https 依赖上述库
真机环境华为畅享 100 Pro Max(YEW-AL80),7.0.0.100 / OpenHarmony-7.0.0.105(API 26)
模拟器环境HarmonyOS 直板模拟器(emulator),7.0.0.107 / OpenHarmony-7.0.0.105(API 26)
样本量与返回上限初始写入 14 条,现场新增后 15 条;页面 topK 设为 8

表2 环境配置

页面用蓝色标识原生 DataAugmentationKit 通道,用琥珀色标识独立 RDB SQL LIKE 对照,红色用于故障提示和清库操作。各操作的耗时彼此独立:原生总耗时从插件进入检索算起,包含开库检查、策略构造、系统检索和结果转换,不包含 RN 页面渲染,也不包含后面单独发起的 LIKE 对照查询。

2.2 华为畅享 100 Pro Max 真机实测

首页能力探测

第三方库的 getCapabilities 在未开库时只检查系统能力与分词器,不会偷偷创建默认数据库文件。实战应用冷启动后先调 openStore 打开沙箱数据库 private_knowledge_vault.db(安全等级设为 SecurityLevel.S3),再读取能力状态。首屏识别出机型、API 26 与 CUSTOM_TOKENIZER 中文分词器,此时库内索引条数为 0:

华为畅享 100 Pro Max 真机首页能力探测

图2 首页能力

初始化 14 条样本

点击“导入 14 篇演示笔记”,实战工程把 14 条中英文笔记传给 upsertDocuments。原生模块排入串行写队列,在单个显式 RDB 事务里同时写入主表和 FTS5 倒排虚拟表。这次调用返回耗时 21.53 ms(涵盖参数解析、写锁排队、事务提交和行数统计),顶部状态栏随即更新为“S3 倒排就绪 · 收录 14 篇加密笔记”:

真机初始化私密知识库并同步 FTS5 倒排索引

图3 初始化结果

多路倒排与 SQL LIKE 同词对照

保持默认的 multi_path 模式(同时启用 BM25、精确匹配和邻近匹配,并用 RRF 重排),搜索“端侧安全加密”。实战页面拿到原生检索结果后,会再调一次独立的 sqlLikeSearch 放在右栏做同词对比:

真机多路倒排与 RDB LIKE 同词检索对照

图4 多路查询

同一个查询词在两条通道里的表现差别很直观:

  • 原生多路倒排:创建检索器 getRetriever 耗时 3113 us,执行 retrieveRdb 耗时 13778 us,总阶段耗时 17.72 ms,精准返回 3 条安全相关笔记。排在首位的是《端侧安全加密与 SecurityLevel.S3 沙箱零出域合规基线》,RRF 融合得分为 0.10,底层特征里原始 BM25 为 210.7、命中核心词组 2 个,相关度等级 LOW (1)。
  • RDB SQL LIKE 对照:把完整词和滑动切出的二字片段“端侧”“侧安”“安全”“全加”“加密”用 OR 组合,在四列上执行带转义的 LIKE ? ESCAPE '\\' 扫描,耗时 2.77 ms(2773 us),一共扫出 9 条候选,按 topK=8 截断展示前 8 条,里面混进了只包含“端侧”或“安全”单个短词的其他主题笔记。
切换单路 BM25 查询

接着切到 bm25_only 模式(仅使用 BM25 策略配合 FUSION_SCORE),搜索“会议纪要差旅”:

真机切换 BM25 单路检索会议纪要实测

图5 单路查询

原生通道同样返回 3 条记录,排第一的是《离线会议决策纪要:端侧私密知识库 Q4 架构定型与里程碑评审》,分值 1.00(BM25 137.5,Core 2,相关度 MEDIUM (2))。不过这次 getRetriever 用了 1510 us,retrieveRdb 却花了 283510 us,总耗时升到 285.88 ms;右侧 LIKE 对照耗时 4.18 ms(4183 us),匹配并展示 4 条。由于这一步同时换了检索模式和查询词,单凭这一次读数还判断不出慢在哪里,后续要固定词条和模式连跑多轮才能排查波动原因。

现场新增笔记并立即检索

切回 multi_path,点击“+ 记一条即查”。应用构造一条时间戳为 23:55:44 的 S4 笔记,调用 upsertDocument 在事务内写主表并同步 FTS5 索引,写入耗时 2.42 ms,库内总数变为 15 条,紧接着自动检索“零信任隔离”:

真机实时新增私密笔记后即刻倒排召回

图6 新增后查询

原生通道耗时 7.26 ms(getRetriever 481 us、retrieveRdb 6484 us),唯一命中的就是刚写入的这条新笔记(BM25 290.7,Core 2)。同词 LIKE 对照耗时 1.38 ms(1382 us),因为二字词“信任”顺带扫到了另一条旧样本,共返回 2 条。这说明单条事务写入后,倒排索引不用重启或手动重建就能立刻查到新内容。

查看原始调用日志

切到“回执日志”页签,前面从开库探测到新增即查的 6 次调用按时间倒序排列,保留了每次接口返回的毫秒和微秒读数,方便和卡片上的展示值逐条核对:

真机原始 API 回执与诊断日志流水截图

图7 调用日志

从初始化 14 条私密样本、多路倒排与 SQL LIKE 同词检索,到现场新增笔记后立即召回的连续真机操作过程如下:

真机连续完成样本初始化、多路倒排对照与新增即查

图8 真机连续检索

2.3 模拟器异常回执与对照查询

把同一个包安装到 HarmonyOS API 26 直板模拟器后,首页的能力检查同样显示“SysCap 已就绪”和 CUSTOM_TOKENIZER:

HarmonyOS API 26 模拟器首页截图

图9 模拟器首页

写入 14 条样本后搜索“端侧安全加密”,原生通道立刻报错中断:

API 26 模拟器异常透传与 SQL LIKE 对照结果

图10 模拟器查询

⚠️ 模拟器上 canIUse 虽然返回 true,但原生层构造配置读取 retrieval.ChannelType.INVERTED_INDEX_DATABASE 时直接抛出 Cannot read property ChannelType of undefined。插件捕获异常后把中断阶段标记为 getRetriever(两项子调用均为 0 us),并在返回对象的 sqlLikeFallback 字段里附带执行了 LIKE 兜底查询(耗时 1.09 ms / 1093 us,匹配 9 条、展示 8 条)。左栏红标如实提示服务受限,下方仍能看到主表里的文本匹配结果。

2.4 从这组记录看出的三件事

操作与查询词真机原生通道真机 LIKE 对照模拟器表现
初始化 14 条样本21.53 ms,主表与 FTS5 同步完成不适用14 条主表与 FTS5 写入正常
多路检索:端侧安全加密17.72 ms,命中 3 条2.77 ms,匹配 9 条、展示 8 条getRetriever 失败;LIKE 1.09 ms、展示 8 条
单路 BM25:会议纪要差旅285.88 ms,命中 3 条4.18 ms,匹配 4 条、展示 4 条未单独采样
新增后检索:零信任隔离写入 2.42 ms,查询 7.26 ms、命中 1 条1.38 ms,匹配 2 条、展示 2 条未单独采样

表3 调用记录

对照表里的几组数字,在做业务决策时要注意三点:

  1. 静态能力标志代替不了运行期异常捕获:真机跑通了全部倒排查询,模拟器却在通过 canIUse 检查后死在枚举读取上,前端必须按每次调用的 nativeRetrievalOk 处理失败分支。
  2. 命中条数少往往是因为过滤更准,而不是漏检:图 4 里 LIKE 扫出 9 条、原生只回 3 条,是因为二字短词 OR 会把只含单个常用词的记录全捞出来;另外 totalMatched 代表截断前总数,列表长度受 topK=8 限制,所以“展示 8 条 / 匹配 9 条”是两个不同维度的计数。
  3. 不同查询词的单次耗时不能直接相减比快慢:17.72 ms、285.88 ms 和 7.26 ms 对应的查询词、策略组合与先后顺序都不同;评估大规模笔记下的性能时,还得准备固定标注语料做多轮重复测试。

三、原理与核心代码

3.1 跨端调用链路与双通道设计

在第三方库内部,JS 侧通过 NativeDataRetrieval.ts 声明 TurboModule 接口,经 RNOH 代码生成工具桥接到 ArkTS 原生模块 RNDataRetrievalTurboModule.ts,底层同时管理关系型主表、FTS5 中文分词虚拟表与系统检索器:

RN 页面经插件调用系统检索与独立 LIKE 对照

图11 跨端调用

整个检索调用按三步推进:先校验输入并确保沙箱数据库已打开;接着根据模式组装召回策略调用 retrieval.getRetriever 与 retrieveRdb;最后把命中的记录、原始特征分值和分段耗时打包成结构化对象返回给 RN 页面。

为了不误导上层业务,原生检索成功时,库绝不会把 SQL LIKE 的结果混进 records 列表(实战页面右栏的对照数据是页面收到成功回执后另调 sqlLikeSearch 拿到的,普通业务接入时无需多查这一步)。只有当原生检索中途报错或分词表不可用时,插件才会把 LIKE 兜底结果塞进独立的 sqlLikeFallback 字段,交由页面决定是否降级展示。

3.2 多路倒排策略与 RRF 重排

系统 @kit.DataAugmentationKit 支持在一个倒排召回条件里同时挂载多种策略:Bm25Strategy 负责词频相关性打分,ExactMatchingStrategy 约束精确词项匹配,ProximityStrategy 衡量分词结果在文本里的邻近距离。

三种倒排策略通过一次原生调用交给系统检索与 RRF 重排

图12 检索流程

multi_path 模式把这三路策略一次性传给 retrieveRdb,并指定 RerankType.RRF 按各路名次倒数融合重排,避免某一路原始分值过大直接冲掉其他特征;bm25_only 则只传单路 BM25 并使用 FUSION_SCORE。注意页面显示的 RRF 分值(如 0.10)和单路分值(如 1.00)量纲不同,它们只用于同一次查询内部排序,不能当成百分比准确率来读。

下面是 RNDataRetrievalTurboModule.ts 中组装策略数组的完整核心函数,支持调用方通过 SearchOptions 覆盖默认列权重与词距窗口:

  /**
   * 按检索模式组装倒排策略数组,通过一次 retrieveRdb 调用统一提交给系统重排
   */
  private buildStrategies(prefs: NormalizedSearchPrefs): Array<retrieval.InvertedIndexStrategy> {
    // 四列权重与词距键名必须完全一致,否则真机 KnowledgeRetrievalCore 会抛 1021201002 参数错误
    const columnWeight: Record<string, number> = {
      'title': prefs.columnWeights['title'] ?? 2.5,
      'tags': prefs.columnWeights['tags'] ?? 1.8,
      'category': prefs.columnWeights['category'] ?? 1.2,
      'content': prefs.columnWeights['content'] ?? 1.0
    };
    const columnSlops: Record<string, number> = {
      'title': prefs.columnSlops['title'] ?? 5,
      'tags': prefs.columnSlops['tags'] ?? 4,
      'category': prefs.columnSlops['category'] ?? 3,
      'content': prefs.columnSlops['content'] ?? 8
    };

    // 单路模式:只按 BM25 词频相关性打分,用于单独观察基础倒排得分
    if (prefs.mode === 'bm25_only') {
      const bm25Only: retrieval.Bm25Strategy = {
        bm25Weight: 1.0,
        columnWeight: columnWeight
      };
      return [bm25Only];
    }

    // 精确优先模式:叠加精确匹配与词距邻近度,让连续短语命中的笔记排在前面
    if (prefs.mode === 'exact_priority') {
      const exactStrategy: retrieval.ExactMatchingStrategy = {
        exactMatchingWeight: 2.0,
        columnWeight: columnWeight
      };
      const proxStrategy: retrieval.ProximityStrategy = {
        proximityWeight: 1.0,
        columnWeight: columnWeight,
        columnSlops: columnSlops
      };
      return [exactStrategy, proxStrategy];
    }

    // 默认多路模式:组合 BM25、精确与邻近三路召回,真机要求各路策略权重均 >= 1.0
    const bm25Strategy: retrieval.Bm25Strategy = {
      bm25Weight: 1.5,
      columnWeight: columnWeight
    };
    const exactStrategy: retrieval.ExactMatchingStrategy = {
      exactMatchingWeight: 1.2,
      columnWeight: columnWeight
    };
    const proximityStrategy: retrieval.ProximityStrategy = {
      proximityWeight: 1.0,
      columnWeight: columnWeight,
      columnSlops: columnSlops
    };
    return [bm25Strategy, exactStrategy, proximityStrategy];
  }

3.3 读写并发协调与显式事务回滚

RN 业务层可能在首屏刚挂载时并发触发开库和查询,也可能在用户连点按钮时交错发起写入、删除与切库。模块内部通过四个私有状态把并发顺序管住:storeOpeningPromise 合并首次并发开库请求,避免重复建表竞态;runWithReadGuard 为在途查询维护引用计数,切库或销毁前先等待读取归零再安全关闭旧连接;writeQueuePromise 把所有增删清操作串成单条队列顺序执行;isDestroyed 则在生命周期钩子 __onDestroy__ 里第一时间置位,拦截实例销毁后迟到的异步请求。

排进写队列后,每次写入都要同时修改通用主表 retrieval_docs 和倒排虚拟表 retrieval_fts。如果主表写成功了、FTS5 插入却报错,两边数据就会对不上。因此我用 runInTransaction 把两张表的更新包进同一个显式事务:

  /**
   * 在显式 RDB 事务内同步主表与 FTS5 虚拟表,任一步抛错立即回滚,防止主表与倒排索引不一致
   */
  private async runInTransaction<T>(
    store: relationalStore.RdbStore,
    work: (tx: relationalStore.Transaction) => Promise<T>
  ): Promise<T> {
    let tx: relationalStore.Transaction | null = null;
    try {
      tx = await store.createTransaction();
      const result = await work(tx);
      await tx.commit();
      return result;
    } catch (err) {
      if (tx !== null) {
        try {
          await tx.rollback();
        } catch (_rbErr) {
          // 回滚本身失败时忽略二次异常,向上层保留最初的写入错误
        }
      }
      if (err instanceof Error) {
        throw err;
      }
      // 将底层非 Error 异常转为带原生错误码的异常对象,供前端定位失败原因
      const details = extractErrorDetails(err as Object);
      throw new NativeOperationError(details.code, `Transaction failed: ${details.message}`);
    }
  }

具体写入文档时,模块先把标签数组加上前导换行符拼接落盘(这样标签里包含英文逗号如 C++, JSI 也能原样拆回),用冲突替换策略更新主表,再在同一个 tx 事务句柄里按主键删旧增新同步 retrieval_fts。此外,独立 sqlLikeSearch 在扫描前会先用 escapeSqlLikePattern 转义输入中的 %、_ 和反斜杠,并对四字及以上的中文短语做步进为 1 的二字滑动切词,查询结束后在 finally 中关闭结果集游标防止句柄泄漏。完整实现可查看公开仓库 abaoge/react-native-data-retrieval。

四、踩坑与边界条件

4.1 排查 1021201002 参数错误

真机联调多路检索时,我一开始踩过系统抛出的 1021201002 参数异常。逐项缩减策略排查后发现两处约束:一是真机底层要求多路策略权重不能小于 1.0(最终定为 1.5、1.2、1.0),二是 columnWeight 和 columnSlops 必须同时配齐 title、tags、category、content 四列键名。

为了帮调用方提前拦住常见误传,第三方库在参数校验层把自定义 columnWeights 限制在 1.0 至 100.0,把 columnSlops 限制为 1 至 100 的正整数,遇到四列以外的未知列名直接返回错误码 401。如果在其他新机型上仍遇到底层参数报错,建议先切到 bm25_only 单路验证建表是否正常,再逐个叠加策略定位具体字段。

4.2 分段计时口径与能力探测盲区

原生耗时优先读取 systemDateTime 的开机单调时钟,避免系统时间跳变干扰差值。返回结构里的 getRetrieverElapsedUs 只计创建检索器耗时,retrieveRdbElapsedUs 只计查询调用耗时,totalRetrievalElapsedMs 则包住整个原生检索流程。像模拟器在读取枚举属性时瞬间抛错,根本没走到两个子调用,就会出现子耗时为 0 us、总阶段耗时 0.35 ms 的情况,排查时看一眼 phase 字段就能明白卡在哪一步。

这也印证了模拟器上的那个坑:canIUse 和分词器检测都返回支持,不等于所有运行期对象都已在镜像里实现。前端页面处理返回结果时,如果业务强依赖多路重排顺序,应当直接向用户提示当前设备环境不支持;如果允许退回普通文本筛选,也要像实战项目一样明确标出当前展示的是 SQL LIKE 降级结果,别让用户误以为倒排检索仍在工作。

4.3 参数防呆、跨词防串台与无分词器降级

在写入与检索边界上,库和实战页面还做了几层防呆处理:

  • 严格返回 401 而非静默吞错:空查询、损坏的 JSON 字符串、单批超过 500 条文档、超长主键或正文、未知模式以及越界 topK,原生侧都会直接返回错误码 401,不会悄悄退回默认数据库或塞入假数据;空库检索直接返回 0 条命中。
  • 前端异步序号防串台:实战工程 App.tsx 用同步忙碌锁 busyRef 拦住重复点击,并用递增序号 searchSeqRef 丢弃过期的慢请求回执。用户改了关键词单独点“RDB LIKE 对照”或重置 14 条样本时,页面会清掉上一轮旧词留下的卡片;切到 rdb_like_compare 模式时主动收起原生面板,而在 SQL LIKE 自身执行报错时单独亮起红色错误条,不把报错空数组当成“匹配 0 条”。
  • 缺少中文分词器时跳过裸表:如果目标系统既不支持 CUSTOM_TOKENIZER 也不支持 ICU_TOKENIZER,模块不会去建默认按空格切词的裸 FTS5 表(否则存中文永远查出 0 条),而是只写主表并在检索时返回 ftsUnavailable 阶段与 LIKE 结果。另外,模块内的串行写锁只管当前 TurboModule 实例,不要从别的进程或原生模块绕过该库并发写同一个数据库文件。

4.4 安全等级、文件加密与平台范围

⚠️ 许多初次接入关系型存储的同学容易把 SecurityLevel.S3 当成数据库加密。其实 S3 只是鸿蒙沙箱的数据安全分级标签,数据库文件默认仍是明文页;真要开启落盘加密,必须在调用 openStore 时显式传入 encrypt: true,并配套做好业务鉴权与日志脱敏(例如生产环境不要像演示台那样把用户输入的搜索词明文打进诊断面板)。实战样本 metadata 里的 S4 同样只是前端展示用的业务分类字段。

当前这个库的原生全文检索实现面向 HarmonyOS 6.0.0(20) 及以上版本(本文编译与测试基于 API 26);Android 和 iOS 侧仅保留参数校验与不支持状态回执,尚未接入对应平台的原生全文检索引擎。

五、结论与可直接复用的建议

借助 react-native-data-retrieval,React Native 鸿蒙应用不用自己维护中文分词和打分逻辑,就能在本地沙箱里完成事务化建库、多路倒排检索和失败降级判断。

5.1 安装第三方库与宿主配置

目前第三方库与配套实战工程均通过 AtomGit 仓库公开分发,固定提交如下:

npm install git+https://atomgit.com/abaoge/react-native-data-retrieval.git#10ace8e6bc81fa4e4d727c9ebaec58ba61bd0089
git clone https://atomgit.com/abaoge/rn-private-knowledge-vault.git && cd rn-private-knowledge-vault && git checkout b6ea385fc193e092921e7b6eebdbb95ad0f570e3

在自己的 RN 鸿蒙工程里装好依赖后,只需完成三处宿主挂载(完整写法可对照实战工程或库内 README.harmony.md):

  1. 在宿主应用级 build-profile.json5 中把最低兼容版本设为 "6.0.0(20)" 及以上,并将模块 data_retrieval 指向 node_modules/react-native-data-retrieval/harmony/data_retrieval。
  2. 在 entry/oh-package.json5 中添加 @rnoh/react-native-data-retrieval 本地文件依赖。
  3. 在 RNPackagesFactory.ets、CMakeLists.txt 和 PackageProvider.cpp 中注册 RNDataRetrievalPackage。

5.2 业务接入核心代码

下面这段完整函数展示了业务页面打开数据库、写入自有文档并发起多路检索的标准写法:

import DataRetrieval, {
  RetrievalMode,
  type RetrievalDocInput,
  type SearchResult,
} from 'react-native-data-retrieval';

/**
 * 打开业务沙箱库、增量同步文档并执行多路倒排检索
 */
export async function indexAndSearchDocs(
  docs: RetrievalDocInput[],
  keyword: string,
): Promise<SearchResult> {
  // 1. 显式打开业务数据库;若需落盘加密可追加 encrypt: true
  const storeRes = await DataRetrieval.openStore({
    dbName: 'business_docs.db',
    securityLevel: 'S3',
  });
  if (!storeRes.ok) {
    throw new Error(`开库失败(${storeRes.errorCode ?? 'UNKNOWN'}): ${storeRes.errorMessage ?? ''}`);
  }

  // 2. 传入非空文档数组时增量更新主表与 FTS5 索引(同 id 自动覆盖,扩展字段放 metadata)
  if (docs.length > 0) {
    const upsertRes = await DataRetrieval.upsertDocuments(docs, { replaceAll: false });
    if (!upsertRes.ok) {
      throw new Error(`写入失败(${upsertRes.errorCode ?? 'UNKNOWN'}): ${upsertRes.errorMessage ?? ''}`);
    }
  }

  // 3. 校验非空查询词后发起三路倒排 + RRF 重排检索
  const query = keyword.trim();
  if (query.length === 0) {
    throw new Error('请输入检索词');
  }
  return DataRetrieval.search(query, {
    topK: 8,
    mode: RetrievalMode.MULTI_PATH,
  });
}

拿到 SearchResult 后,先看 nativeRetrievalOk:为真时直接渲染 records;为假时读取 retrievalStage.phase 与 errorCode 判断中断位置,若业务决定展示 sqlLikeFallback 里的兜底列表,记得同时检查 sqlLikeFallback.executed 和 sqlLikeFallback.ok,避免把底层 SQL 查询报错误显示成“没有搜到内容”。需要按条删除或清空全库时,分别调用 removeDocument(id) 和 clearDocuments() 即可。

5.3 检索模式选择参考

模式启用的底层策略适用场景
multi_pathBM25 + 精确匹配 + 邻近匹配 + RRF 重排兼顾标题权重、短语紧密度与正文召回,适合作为默认首选
bm25_only单路 BM25 + FUSION_SCORE只看词频相关性得分,接入后建议结合真实数据观察耗时
exact_priority精确匹配 + 邻近匹配 + RRF 重排优先把包含完整连续词组的笔记排到前面
rdb_like_compare独立 SQL LIKE 多列转义扫描设备不支持原生检索或仅需简单子串筛选时的对照与兜底

表4 检索模式

如果业务里只有几十条固定短文本、做简单子串过滤就够用,直接查普通表反而省事;当文档变长、需要根据标题和标签调整排序权重时,再引入这套多路倒排检索会更合适。

小结

把《离线私密知识闪搜库》在真机和模拟器上跑完一圈后,这组本地笔记既能按多路策略排好序,也能在单条新增后马上搜出来 🎉。回头看整个开发过程,最让我踏实的改动不是调某一个权重参数,而是把主表落盘、FTS5 同步、原生检索和普通文本兜底这四件事的状态拆得明明白白——哪一步成功、哪一步在什么阶段报错,页面都能拿到准话,遇到模拟器缺枚举这类环境差异时自然不会抓瞎。

真到自己项目里选型时,我建议先拿真实长度的业务文档在目标真机上测几轮耗时和排序效果,再决定默认用三路融合还是单路策略;毕竟小样本里的单次快慢只能帮我们摸清链路,最终还得靠业务自己的语料说话。

Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐