Retrieval and Indexing zh CN

检索与索引设计

语言： English · 简体中文

LWC 使用确定性 lexical retrieval，而不是 embedding。每个结果都能追溯到规范化 term、field match、可选图证据与可审计调整。

调优检索、解释 --explain、修改 tokenizer 或判断图状态是否应影响排序时，应阅读本页。

检索流水线

query
  -> 规范化并去重 terms
  -> FTS5 document 或 span candidates
  -> mode、kind 与 source-summary filter
  -> lexical field contributions
  -> 可审计 weight 与 exact-query feedback
  -> 有界 Wiki-link graph reranking
  -> mixed-granularity fusion 与可选 grouping
  -> 按 type/rank/identifier 确定性排序

整个流程不会调用外部模型。Store、query、options 和 adjustment state 相同，排序就相同。

分词

LWC 会把字母数字 term 转成小写，移除一小组固定中英文 stop words，并保留稳定 UTF-8 position。

对于连续 CJK 文本：

• query tokenizer 产生相邻 bigram；
• 单个 CJK 字符仍可检索；
• index tokenizer 还会存储 unigram，以保证单字查询 recall。

这种无词典设计无需外部分词服务，也能稳定处理产品名、代码名、混合语言和新词。Query 中重复 term 按首次出现顺序去重。

只包含标点或 stop word 的 query 不会产生 candidate。Document 与 span search 最多接受 64 个可检索 term。

索引字段

Document FTS 有四个 indexed field，当前 BM25 权重如下：

字段	权重
Title terms	8
Path terms	6
Summary terms	4
Body terms	1

Page 与 Source 共用一份索引。Document type、identifier 等 metadata column 不参与检索，用于筛选以及连接规范记录。

Span FTS 会索引 title、path 和准确 passage 或 sentence body terms。Span text 仍保存在规范 Page 或 Source 内，通过 byte range 读取，不再维护第二份可变副本。

Document、Passage 与 Sentence 粒度

lwc --scope project search "checkpoint graph recovery" --granularity document
lwc --scope project search "checkpoint graph recovery" --granularity passage
lwc --scope project search "checkpoint graph recovery" --granularity sentence
lwc --scope project search "checkpoint graph recovery" --granularity all --group-by document

Markdown-aware segmenter 能识别 heading、paragraph、list item、block quote、table row、code block 与 HTML。普通文本按 Unicode sentence boundary 切分，代码块则按非空代码行切分。

每个 locator 都包含 document identity、parent、ordinal、UTF-8 byte range、fingerprint 与 segmenter version。文档变化后，旧 locator 会失效，而不是返回相似但未经证明的新文本。

Lexical 排序

SQLite BM25 产生 base rank，数值越小越靠前。LWC 再叠加可解释贡献：

• title 完全匹配或接近 phrase match 时获得最强提升；
• path match 获得较小提升；
• 与 query 无关的通用导航/index 文档会受到 generic penalty；
• 最后使用稳定 type 与 identifier 打破平分。

当前贡献常量为 title -32、path -16、generic marker +8，分别乘以规范化 signal。这些数值会通过 --explain 暴露，但属于实现细节，不要求用户手算 rank。

Page 优先与 Source 行为

在 auto 和 all target mode 下，维护后的 Page 排在 raw Source 前面。auto 还会在已有 kind=source Page 总结某份 Source 时，隐藏对应 raw Source 结果。

这样既能优先展示 synthesis，也保留返回不可变证据的路径。任务明确要求原始 Source match 时，应使用 --target source。

可审计调整

Manual weight 接受 -2、-1、1 或 2。正数提升、负数降低已有 lexical candidate。Exact-query feedback 会把 relevant 或 irrelevant 记录到规范化 term 的 SHA-256 fingerprint。

lwc --scope project weight set page recovery-rules 2 \
  --reason "Core recovery guidance" \
  --provenance user-provided
lwc --scope project weight feedback page recovery-rules \
  --query "checkpoint graph recovery" \
  --signal relevant \
  --reason "Verified expected answer" \
  --provenance agent-observed

当前最大贡献为：正向 manual weight -2，relevant feedback -1.5；相反 signal 按同等幅度降低排序。同一 target 和 adjustment class 同时存在两种来源时，user-provided 优先于 agent-observed。

调整不能创造 candidate，文档必须先命中 lexical term。Feedback 只作用于准确 normalized-query fingerprint，不会暗中迁移到自然改写。

Wiki Link 图重排

LWC 最多取前三个 lexical Page candidate 作为 graph seed。规范 Wiki link 与共享 Source citation 提供有界 related-page evidence：

• 结构证据匹配最多提升 Page 0.25 个 rank unit；
• 通用高出度导航 Page 可能受到最多 4 的 hub penalty；
• 靠后的 seed 按位置折扣贡献。

重排读取规范 SQLite Page relation，不依赖外部文档图引擎，也不能把不在 lexical candidate set 中的 Page 凭空救回。

混合粒度融合

--granularity all 会通过 reciprocal-rank 风格融合 document、passage 与 sentence。Sentence 和 passage 带有小幅 prior，各粒度按 prior / (60 + position) 贡献。

使用 --group-by document 后，每个 document 最多组合三个最佳 match，权重依次为 1、0.5、0.25。响应会保留这些 match locator，调用方仍能查看准确证据。

解释结果

lwc --scope project search "checkpoint graph recovery" --limit 10 --explain

explanation 会给出：

• BM25 base rank；
• title、path、generic、manual、feedback、graph-match 与 graph-hub signal；
• 各项数值贡献；
• final rank；
• 存在时的 graph seed evidence。

修改 weight 之前应先看解释。结果不理想可能来自缺少术语、标题过于通用、内容过期、raw-source target mode 或没有 lexical candidate，而不是常量设置错误。

Reindex 与一致性

Page 和 Source mutation 会在 transaction 内更新对应 FTS 与 span row。lint 能发现缺失、重复或 orphan document index row。

投影状态损坏时，运行 maintenance Work 并检查结果：

lwc --scope project maintenance reindex
lwc --scope project work watch <work-id>
lwc --scope project lint

Reindex 是修复手段，不是日常检索准备步骤。普通读取绝不会隐式重建索引。

检索验收

持久知识变更至少应预声明两项检查：

1. 预期准确表述；
2. 使用不同表面词汇的自然改写。

两种问法都应在前五名找到目标 Page，并检查 Source citation。Changeset commit 后还要在 live 状态重复验收。不要为了掩盖一篇写得不好的 Page 而调全局 weight。

下一篇：性能与可扩展性