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

package/src/fts.ts

@@ -0,0 +1,203 @@
+/**
+ * 关键词路的索引（0031）：**SQLite FTS5 + BM25**，中文靠我们自己的 CJK 分词喂进去。
+ *
+ * ## 为什么是这个组合
+ *
+ * 0030 之前的关键词路是 `haystack.includes(token)` 的计数打分，而 `tokens()` 只按
+ * 非字母数字切分 —— 中文没有空格，于是一句自然语言问题被切**成一个 token**：
+ * 实测 `排查`→6 命中、`指标`→8、`口径`→10，但 `怎么排查指标异常`→**0**、
+ * `销售额如何计算`→**0**。产品的主查询形态就是整句中文，所以那条路等于不存在。
+ *
+ * 修它需要三样东西，而它们必须一起来：**中文能切**、**BM25 的词权重**、**零新服务**。
+ *
+ * - FTS5 自带 BM25（`bm25()`），是 SQLite 内建的，Node 22.5+ 的 `node:sqlite` 直接能用
+ *   —— 不引入 `better-sqlite3` 这类原生模块，也不引入外部检索服务（0014 的非目标）。
+ * - FTS5 的两个内置 tokenizer 都不够用：`unicode61` 不切中文（`支付订单`→0 命中），
+ *   `trigram` 要求查询至少 3 个字符（`排查`→0、`支付`→0），而且会把整句查询拆成
+ *   **互相 AND 的三字窗口**，等于要求原文逐字包含整句。
+ * - 所以分词由我们做，**不用词典**：CJK 串切成 单字 + 相邻双字，ASCII 串整体小写成一个词。
+ *   查询走同一套切分、用 `OR` 连接、交给 BM25 排序。实测 `怎么排查指标异常` 能召回含
+ *   `排查` 的文档，`排查`（2 字）也能召回 —— 这正是 trigram 做不到的两件事。
+ *
+ * ## 分数的量纲（重要）
+ *
+ * `bm25()` 是无界的、依赖语料的，所以本模块把它按**本次查询的最高分**归一化到 0..1。
+ * 这意味着 `keywordThreshold` 是**相对**阈值：它挡得住「弱命中」，挡不住「整批都弱」
+ * （只有弱命中时，最弱的那条也会被归一成 1.0）。真正的**绝对**闸门是向量路的余弦阈值
+ * 与重排阈值 —— 这一点在 `diagnostics.abstention` 里如实标注，不假装关键词阈值能判弃答。
+ *
+ * @module
+ */
+
+import { mkdirSync, rmSync, existsSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+/** `03_compiled/fts.sqlite`：关键词索引与向量索引同级，可重建、不进备份语义。 */
+export const FTS_FILE = 'fts.sqlite'
+
+/** 一条可被索引的召回单元。只取索引需要的字段，便于单测直接构造。 */
+export interface FtsDocument {
+  unitId: string
+  title: string
+  content: string
+}
+
+export interface FtsHit {
+  unitId: string
+  /** 归一化到 0..1 的相关性（本次查询的最高分 = 1）。 */
+  score: number
+  /** 原始 `bm25()` 值（负数，越小越相关）。留给诊断与调参看。 */
+  raw: number
+}
+
+interface SqliteStatement {
+  run(...params: unknown[]): unknown
+  all(...params: unknown[]): unknown[]
+  get(...params: unknown[]): unknown
+}
+interface SqliteDatabase {
+  exec(sql: string): void
+  prepare(sql: string): SqliteStatement
+  close(): void
+}
+
+/**
+ * `node:sqlite` 是否可用。
+ *
+ * 它是 Node 22.5+ 的实验特性，而这个仓库声明支持 `node >= 20`。不可用时**不报错**：
+ * 关键词路退化成 `degraded` 并在诊断里写明原因（`ftsUnavailable`），整条链路照常跑。
+ * 这比「装不上就起不来」诚实，也比「静默用回旧打分」安全。
+ */
+let sqliteModule: { DatabaseSync: new (path: string) => SqliteDatabase } | null | undefined
+export async function loadSqlite(): Promise<{ DatabaseSync: new (path: string) => SqliteDatabase } | null> {
+  if (sqliteModule !== undefined) return sqliteModule
+  try {
+    sqliteModule = await import('node:sqlite') as unknown as { DatabaseSync: new (path: string) => SqliteDatabase }
+  } catch {
+    sqliteModule = null
+  }
+  return sqliteModule
+}
+
+/** 供同步路径查询的「上一次探测结论」；`undefined` 表示还没探过。 */
+export function sqliteProbed(): boolean | undefined {
+  return sqliteModule === undefined ? undefined : sqliteModule !== null
+}
+
+/**
+ * 分词用的切分模式。
+ *
+ * ASCII 只收 `[A-Za-z0-9]+`，**故意不把 `._:/-` 留在词里** —— 因为 FTS5 的
+ * `unicode61` 就是按它们切的（实测：索引里的 `document:ledger` 变成 `document` +
+ * `ledger`，`external_id` 变成 `external` + `id`）。这个函数有两个消费者：喂索引，
+ * 以及**在 JS 侧算查询词覆盖率**。两边切法不一致时，覆盖率会算错并悄悄把好命中丢掉
+ * （实测：查 `ledger` 时索引命中了、覆盖率却是 0，于是整条路 0 命中）。
+ */
+const CJK_RUN = /[\p{Script=Han}]+|[A-Za-z0-9]+/gu
+
+/**
+ * 把一段文本切成索引词。
+ *
+ * - CJK 串 → 每个字（单字）+ 每对相邻字（双字）。单字让 1 字查询也能命中，双字承担
+ *   真正的区分度；BM25 的 IDF 会把「的」「了」这类高频单字自动压下去。
+ * - ASCII / 数字串 → 小写，并按 `unicode61` 的口径切开（`external_id` → `external` + `id`）。
+ *   与索引保持一致比「保留整串」更重要：`T-1` 这类写法在索引里本来就是两个 token。
+ */
+export function segment(text: string): string[] {
+  const out: string[] = []
+  for (const match of text.matchAll(CJK_RUN)) {
+    const chunk = match[0]
+    if (/^\p{Script=Han}/u.test(chunk)) {
+      const chars = [...chunk]
+      for (const char of chars) out.push(char)
+      for (let index = 0; index + 1 < chars.length; index += 1) out.push(chars[index]! + chars[index + 1]!)
+    } else {
+      out.push(chunk.toLowerCase())
+    }
+  }
+  return out
+}
+
+/**
+ * 查询 → FTS5 的 MATCH 表达式。
+ *
+ * 词之间用 `OR`：召回要的是「命中任意一个词、由 BM25 排序」，而不是「逐字包含整句」。
+ * 每个词加双引号，于是 FTS5 的查询语法（`-` 被当成列过滤、`*` 被当成前缀）不会把
+ * 一个普通问题变成语法错误 —— `T-1` 就是实测踩到的例子。
+ */
+export function matchExpression(query: string): string | null {
+  const terms = [...new Set(segment(query))].filter(term => term.length > 0)
+  if (terms.length === 0) return null
+  return terms.map(term => `"${term.replace(/"/g, '""')}"`).join(' OR ')
+}
+
+/** 关键词索引。构造即打开；`null` 表示不可用（调用方降级）。 */
+export class FtsIndex {
+  private constructor(private readonly db: SqliteDatabase) {}
+
+  /**
+   * 重建索引。**整体替换**：先写临时文件再改名，于是构建失败不会留下半个索引
+   * （读路径只认改名后的那个文件）。
+   */
+  static async build(path: string, documents: FtsDocument[], DatabaseSync: new (path: string) => SqliteDatabase): Promise<void> {
+    mkdirSync(dirname(path), { recursive: true })
+    const temporary = `${path}.tmp`
+    rmSync(temporary, { force: true })
+    const db = new DatabaseSync(temporary)
+    try {
+      db.exec('PRAGMA journal_mode = OFF')
+      db.exec("CREATE VIRTUAL TABLE notes USING fts5(unit_id UNINDEXED, tokens, tokenize='unicode61 remove_diacritics 2')")
+      const insert = db.prepare('INSERT INTO notes(unit_id, tokens) VALUES (?, ?)')
+      db.exec('BEGIN')
+      for (const document of documents) {
+        // 标题重复一次：FTS5 没有字段权重，重复等于给它加权（标题命中比正文命中更值钱）。
+        const tokens = [...segment(document.title), ...segment(document.title), ...segment(document.content)]
+        insert.run(document.unitId, tokens.join(' '))
+      }
+      db.exec('COMMIT')
+      db.exec('INSERT INTO notes(notes) VALUES (\'optimize\')')
+    } finally {
+      db.close()
+    }
+    rmSync(path, { force: true })
+    const { renameSync } = await import('node:fs')
+    renameSync(temporary, path)
+  }
+
+  /** 打开已存在的索引；不存在或打不开返回 `null`（调用方降级）。 */
+  static async open(path: string, DatabaseSync: new (path: string) => SqliteDatabase): Promise<FtsIndex | null> {
+    if (!existsSync(path)) return null
+    try {
+      return new FtsIndex(new DatabaseSync(path))
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * 一次 BM25 查询。分数按本次结果的最高分归一化（见模块头的「分数的量纲」）。
+   */
+  search(query: string, limit: number): FtsHit[] {
+    const expression = matchExpression(query)
+    if (!expression) return []
+    let rows: Array<{ unit_id?: unknown; rank?: unknown }>
+    try {
+      rows = this.db.prepare('SELECT unit_id, bm25(notes) AS rank FROM notes WHERE notes MATCH ? ORDER BY rank LIMIT ?').all(expression, limit) as Array<{ unit_id?: unknown; rank?: unknown }>
+    } catch {
+      // 查询语法或索引损坏：如实返回空，由调用方的诊断说明这一路没结果。
+      return []
+    }
+    const parsed = rows
+      .map(row => ({ unitId: String(row.unit_id ?? ''), raw: Number(row.rank ?? 0) }))
+      .filter(row => row.unitId !== '' && Number.isFinite(row.raw))
+    if (parsed.length === 0) return []
+    // `bm25()` 越小越相关，所以取负号变成「越大越好」，再按最高分归一。
+    const best = Math.max(...parsed.map(row => -row.raw))
+    const scale = best > 0 ? best : 1
+    return parsed.map(row => ({ unitId: row.unitId, raw: row.raw, score: Math.max(0, Math.min(1, -row.raw / scale)) }))
+  }
+
+  close(): void {
+    try { this.db.close() } catch { /* already closed */ }
+  }
+}