dsh-data-domain-knowledge 0.1.0-alpha.1

package/src/recall-rank.ts

@@ -0,0 +1,299 @@
+/**
+ * 召回链路的**纯函数**部分（0031）：融合、boost、去冗余、证据抽取。
+ *
+ * 与 `graph/layout.ts`、`problem-domains.ts` 同一个理由：把不依赖 runtime、不碰磁盘的
+ * 那部分单独放，于是它们可以在 `node:test` 里被直接断言。这里的每个函数都对应 0031
+ * 的一个设计决定，注释写的是**为什么**，不是做了什么。
+ *
+ * @module
+ */
+
+import type { RecallEvidence, RecallRoute } from './types.js'
+import { segment } from './fts.js'
+
+/** 一路的排序结果（已过阈值、已按分数降序）。 */
+export interface RouteRanking {
+  unitId: string
+  /** 该路自己的分数，只用于阈值与展示 —— 融合不读它。 */
+  score: number
+}
+
+export interface FusedHit {
+  unitId: string
+  score: number
+  /** 每一路的名次（1 起）。缺失 = 那一路没有召回它。 */
+  ranks: Partial<Record<RecallRoute, number>>
+}
+
+export interface RrfOptions {
+  /** RRF 的平滑常数；越大越平（削弱第一名）。WeKnora 默认 60。 */
+  k: number
+  weights: Partial<Record<RecallRoute, number>>
+}
+
+/**
+ * 名次级融合（Reciprocal Rank Fusion）。
+ *
+ * **为什么不用分数加权和**：三路的分数是三个不同的量纲 —— 关键词是归一化 BM25、
+ * 向量是余弦、图谱是命中分/最大命中分。把它们乘权重相加，等于假设「0.5 的关键词分」
+ * 与「0.5 的余弦」一样好，而这个假设没有任何依据。0030 的实际后果就是：向量路输出
+ * 常数时，hybrid 的 55% 权重全是噪声，排序退化成 `unitId` 字典序（实测 4 条命中
+ * 分数完全相同：`0.2753 = 0.5 × 0.55`）。
+ *
+ * RRF 只吃**名次**，所以量纲问题从根上消失，而权重变成「我更信哪一路的排序」——
+ * 这是一个可以校准、也可以被解释的量。
+ */
+export function rrfFuse(rankings: Partial<Record<RecallRoute, RouteRanking[]>>, options: RrfOptions): FusedHit[] {
+  const { k, weights } = options
+  const ranks = new Map<string, Partial<Record<RecallRoute, number>>>()
+  const scores = new Map<string, number>()
+  const order: RecallRoute[] = ['fts', 'vector', 'graph']
+  for (const route of order) {
+    const list = rankings[route]
+    if (!list || list.length === 0) continue
+    const weight = weights[route] ?? 0
+    if (weight <= 0) continue
+    // 同一路里同一 unitId 只认第一次出现（更好的名次）——重复条目不该把分数抬两次。
+    const seen = new Set<string>()
+    let rank = 0
+    for (const item of list) {
+      if (seen.has(item.unitId)) continue
+      seen.add(item.unitId)
+      rank += 1
+      const entry = ranks.get(item.unitId) ?? {}
+      entry[route] = rank
+      ranks.set(item.unitId, entry)
+      scores.set(item.unitId, (scores.get(item.unitId) ?? 0) + weight / (k + rank))
+    }
+  }
+  return [...scores.entries()]
+    .map(([unitId, score]) => ({ unitId, score, ranks: ranks.get(unitId) ?? {} }))
+    .sort((left, right) => right.score - left.score || left.unitId.localeCompare(right.unitId))
+}
+
+/**
+ * 图谱作为**boost**，不是第三路。
+ *
+ * 0009/0014 都把知识图谱定位为**构建产物**（wiki→图谱），没有把它当作召回路线；
+ * 而 0030 把它做成第三路时，匹配逻辑与关键词路同源（词面匹配 title / id / 关系词），
+ * 等于把关键词路的弱点复制一遍，还多贡献了一份不可比的分数。
+ *
+ * 现在的语义是：图谱命中的实体及其 1 跳邻居，**只给已经在候选池里的条目**加一个
+ * RRF 项。它因此不能凭自己制造候选（那是「路」的权力），只能重排（那是「boost」的
+ * 职责）—— 于是它既保留了「命中实体 → 带出邻居」的价值，又不会污染融合。
+ */
+export function graphBoost(fused: FusedHit[], graphRanking: RouteRanking[], options: RrfOptions): { hits: FusedHit[]; applied: number } {
+  const weight = options.weights.graph ?? 0
+  if (weight <= 0 || graphRanking.length === 0 || fused.length === 0) return { hits: fused, applied: 0 }
+  const rankOf = new Map<string, number>()
+  let rank = 0
+  for (const item of graphRanking) {
+    if (rankOf.has(item.unitId)) continue
+    rank += 1
+    rankOf.set(item.unitId, rank)
+  }
+  let applied = 0
+  const boosted = fused.map(hit => {
+    const rank = rankOf.get(hit.unitId)
+    if (rank === undefined) return hit
+    applied += 1
+    return {
+      ...hit,
+      score: hit.score + weight / (options.k + rank),
+      ranks: { ...hit.ranks, graph: rank },
+    }
+  })
+  return { hits: boosted.sort((left, right) => right.score - left.score || left.unitId.localeCompare(right.unitId)), applied }
+}
+
+/**
+ * 按阈值裁剪一路的候选，并给出这一路的诊断。
+ *
+ * 关键词路的分是**相对**归一的（见 `fts.ts` 的量纲说明），所以这里的阈值挡得住
+ * 「弱命中」、挡不住「整批都弱」；向量路的分是原始余弦，是绝对的。两者都要如实
+ * 写进诊断，不能让人以为「过了阈值」等于「相关」。
+ */
+export function applyThreshold(ranking: RouteRanking[], threshold: number): { kept: RouteRanking[]; dropped: number; topScore: number } {
+  const topScore = ranking.length > 0 ? Math.max(...ranking.map(item => item.score)) : 0
+  const kept = ranking.filter(item => item.score >= threshold)
+  return { kept, dropped: ranking.length - kept.length, topScore }
+}
+
+/**
+ * 从原文里挑出与查询最相关的若干段，作为**证据片段**。
+ *
+ * 为什么要有这一步：`context` 原来只带 wiki 卡片，模型要核对原文还得再调一次工具。
+ * 把证据放进上下文，「每一个数字都能指回它的口径定义与原始文档」才在上下文层面
+ * 成立，而不是靠模型自觉去查。
+ *
+ * 段落按空行切（Markdown 的自然段），逐段算**查询词覆盖率**，取最高的几段。
+ * 覆盖率是绝对的，所以「找不到相关段落」会如实返回空数组，而不是硬塞一段无关文字。
+ */
+export function evidenceExcerpts(sourceId: string, title: string | undefined, text: string, queryTerms: string[], options: { maxExcerpts?: number; maxChars?: number; minCoverage?: number } = {}): RecallEvidence[] {
+  const maxExcerpts = options.maxExcerpts ?? 2
+  const maxChars = options.maxChars ?? 1200
+  const minCoverage = options.minCoverage ?? 0.15
+  const terms = [...new Set(queryTerms)].filter(term => term.length > 0)
+  if (terms.length === 0 || text.trim() === '') return []
+
+  const blocks: Array<{ text: string; offset: number }> = []
+  const pattern = /[^\n]*(?:\n(?!\s*\n)[^\n]*)*/g
+  for (const match of text.matchAll(pattern)) {
+    const block = match[0]
+    if (block.trim().length < 8) continue
+    blocks.push({ text: block.trim(), offset: match.index ?? 0 })
+  }
+  if (blocks.length === 0) return []
+
+  const scored = blocks.map(block => {
+    const haystack = block.text.toLowerCase()
+    const hit = terms.filter(term => haystack.includes(term)).length
+    return { ...block, coverage: hit / terms.length }
+  }).filter(block => block.coverage >= minCoverage)
+
+  return scored
+    .sort((left, right) => right.coverage - left.coverage || left.offset - right.offset)
+    .slice(0, maxExcerpts)
+    .map(block => ({
+      sourceId,
+      ...(title ? { title } : {}),
+      excerpt: block.text.length > maxChars ? `${block.text.slice(0, maxChars)}…` : block.text,
+      offset: block.offset,
+      coverage: Number(block.coverage.toFixed(4)),
+    }))
+}
+
+/**
+ * 一条 note 进关键词索引的**完整文本**。
+ *
+ * 它包含三部分：标题、正文、以及**溯源身份**（它引用的 sourceId 与那些来源的标题）。
+ * 溯源身份不是锦上添花：图谱降为 boost 之后，「只提到某份来源、没提到任何卡片正文」
+ * 的查询再也没有第二条路可走，所以「这份台账派生出了哪些结论」必须由关键词路回答。
+ *
+ * 这个函数被**两处**共用 —— 建索引时写进去的文本，与召回时算查询词覆盖率的文本。
+ * 两处各写一份的话，覆盖率会对着不同的文本算，好命中会被静默丢掉（实测：查 `ledger`
+ * 时索引命中了、覆盖率却是 0）。
+ */
+export function noteIndexText(note: { title: string; content: string; sourceRefs: string[] }, titleOf: (sourceId: string) => string | undefined): string {
+  const titles = note.sourceRefs.map(ref => titleOf(ref) ?? '').filter(Boolean).join(' ')
+  const provenance = [note.sourceRefs.join(' '), titles].filter(Boolean).join(' ')
+  return provenance ? `${note.title}\n${note.content}\n${provenance}` : `${note.title}\n${note.content}`
+}
+
+/** 一段文本的词集合，用于 MMR 的冗余度（Jaccard）。 */
+export function tokenSet(text: string): Set<string> {
+  return new Set(segment(text))
+}
+
+function jaccard(left: Set<string>, right: Set<string>): number {
+  if (left.size === 0 || right.size === 0) return 0
+  let shared = 0
+  for (const token of left) if (right.has(token)) shared += 1
+  return shared / (left.size + right.size - shared)
+}
+
+export interface MmrOptions<T> {
+  /** 相关性（通常就是融合分）。 */
+  relevance: (item: T) => number
+  /** 该条目的词集合。 */
+  tokens: (item: T) => Set<string>
+  /** 该条目属于哪张 wiki —— 用于「每张卡最多几条」的硬约束。 */
+  wikiKey: (item: T) => string
+  /** 相关性 vs 多样性的权衡；0.7 = 偏相关性（与 WeKnora 的 grep_chunks 一致）。 */
+  lambda?: number
+  /** 每张 wiki 最多入选几条。 */
+  perWikiCap?: number
+  /** 总共要几条。 */
+  limit: number
+}
+
+/**
+ * 选上下文条目：**每张 wiki 封顶 + MMR 去冗余**。
+ *
+ * 为什么必须有：0030 的图谱路刻意给同一张 wiki 的分节 note 0.8 的权重，于是 5 条上下文
+ * 可以全部来自同一张卡 —— 一屏塞满、信息量为 1。这是「召回质量差」里最容易被忽略的一半：
+ * 前 5 条不是「5 条相关」，而是「1 条相关的 5 个片段」。
+ *
+ * 冗余度用**词集合的 Jaccard**，不用向量：它对编码器是否可用不敏感，因此去冗余在
+ * 向量路降级时依然生效 —— 依赖一个可能坏掉的组件的功能，等于把它的可靠性绑在那个组件上。
+ */
+export function selectContext<T>(items: T[], options: MmrOptions<T>): T[] {
+  const lambda = options.lambda ?? 0.7
+  const perWikiCap = options.perWikiCap ?? 2
+  const pool = [...items].sort((left, right) => options.relevance(right) - options.relevance(left))
+  const selected: T[] = []
+  const selectedTokens: Array<Set<string>> = []
+  const perWiki = new Map<string, number>()
+  const remaining = [...pool]
+  while (selected.length < options.limit && remaining.length > 0) {
+    let bestIndex = -1
+    let bestValue = Number.NEGATIVE_INFINITY
+    for (let index = 0; index < remaining.length; index += 1) {
+      const candidate = remaining[index]!
+      const wiki = options.wikiKey(candidate)
+      if ((perWiki.get(wiki) ?? 0) >= perWikiCap) continue
+      const tokens = options.tokens(candidate)
+      let redundancy = 0
+      for (const taken of selectedTokens) redundancy = Math.max(redundancy, jaccard(tokens, taken))
+      const value = lambda * options.relevance(candidate) - (1 - lambda) * redundancy
+      if (value > bestValue) { bestValue = value; bestIndex = index }
+    }
+    if (bestIndex < 0) break
+    const chosen = remaining.splice(bestIndex, 1)[0]!
+    selected.push(chosen)
+    selectedTokens.push(options.tokens(chosen))
+    const wiki = options.wikiKey(chosen)
+    perWiki.set(wiki, (perWiki.get(wiki) ?? 0) + 1)
+  }
+  return selected
+}
+
+/** `match` 字段由名次推导：两路及以上命中 = hybrid。 */
+export function matchOf(ranks: Partial<Record<RecallRoute, number>>): 'fts' | 'vector' | 'graph' | 'hybrid' {
+  const used = (['fts', 'vector', 'graph'] as RecallRoute[]).filter(route => ranks[route] !== undefined)
+  if (used.length >= 2) return 'hybrid'
+  return used[0] ?? 'fts'
+}
+
+/** 展示用的概率：`rerankScore` 是 logit 的 sigmoid。 */
+export function sigmoidLogit(logit: number): number {
+  return 1 / (1 + Math.exp(-logit))
+}
+
+export interface RerankOutcome<T> {
+  /** 过阈值的条目，按 logit 降序；`rerankScore` 是 logit 的 sigmoid。 */
+  kept: Array<T & { rerankScore: number }>
+  /** 被阈值丢掉的条数。 */
+  dropped: number
+  /** 候选池里最高的 logit —— 跨查询可比的「这一批到底有多相关」。 */
+  topLogit: number
+}
+
+/**
+ * Stage 4：**在 logit 刻度上**过阈值，展示值才做一次 sigmoid。
+ *
+ * 刻度必须只有一个。cross-encoder 的价值就在于此：它的分是**跨查询可比**的，
+ * 所以「低于 0.2 就不要」是一个绝对判据，而关键词/向量的阈值做不到这一点。
+ * 0031 落地时这里错了两层：
+ *
+ * 1. worker 用 `CrossEncoder.predict` 的默认行为，拿到的是 **sigmoid 之后**的值
+ *    （(0,1)），却按 logit 阈值 0.2 去比 —— 于是 `dropped` 恒为 0，绝对闸门从未生效。
+ * 2. Host 又 sigmoid 了一次做展示，把无关文档（logit −10.2）显示成 `0.500`
+ *    —— 一个「看起来刚好在门槛上」的分数。
+ *
+ * 现在 worker 返回 logit（`predict_raw`），阈值与排序都在 logit 上，展示只 sigmoid 一次。
+ * 这个函数是纯的，所以刻度这件事可以在 `node:test` 里被钉住。
+ */
+export function applyRerank<T extends { unitId: string }>(scores: number[], items: T[], threshold: number): RerankOutcome<T> {
+  if (scores.length !== items.length) throw new Error(`RERANK_COUNT_INVALID: expected ${items.length}, got ${scores.length}`)
+  if (scores.some(value => !Number.isFinite(value))) throw new Error('RERANK_SCORE_INVALID: 返回了非有限分数')
+  const scored = items.map((item, index) => ({ item, logit: scores[index]! }))
+  const kept = scored.filter(entry => entry.logit >= threshold)
+  return {
+    kept: kept
+      .map(entry => ({ ...entry.item, rerankScore: sigmoidLogit(entry.logit) }))
+      .sort((left, right) => right.rerankScore - left.rerankScore || left.unitId.localeCompare(right.unitId)),
+    dropped: scored.length - kept.length,
+    topLogit: scored.length > 0 ? Math.max(...scored.map(entry => entry.logit)) : 0,
+  }
+}