XERJ 索引 Notion 导出出现重复标题的排查指南:定位重复来源、幂等重索引与 YAML 误判数据库行

原创2026-10-16 20:59:571,856 阅读
文章标签:人工智能搜索引擎本地部署后端MCP 服务

XERJ 索引 Notion 导出出现重复标题的排查指南:定位重复来源、幂等重索引与 YAML 误判数据库行

导读:当把 Notion 的 Markdown + CSV 工作区导出交给 XERJ 的 autoindex 后,搜索结果里同一页面出现两条记录、同一标题出现在两个路径、数据库行却一条也搜不到,这三类现象常常被误归因于"重复索引"。本文基于一次完整捕获运行(RUN-B,2026-08-21,16 核 AMD EPYC 9645)逐步还原现象根因:重复标题来自 Notion 自身的导出布局与 XERJ 每个 Markdown 文件产出两份文档的设计,重索引本身幂等;同时给出数据库行页面被 yaml 家族识别器拒绝的判定规则与恢复手段。读完你可以精确复现排查命令、按 ax_path 归并结果,并学会用 autoindex-catalog 区分"文件数"与"文档数"。

一次捕获运行的完整结论(TL;DR)

  • 重复标题来自导出布局(Notion 把页面写成 <Title> <32-hex>.md,同时把子页面放进同名 <Title> <32-hex>/ 目录)与 XERJ 每个 Markdown 文件写 2 份文档(整文件卡片 + passage 文档)这两个事实叠加。
  • 重索引不是重复的来源。同一导出目录用同一命令索引两次,两次都返回 8 个文档,_id 逐字节一致,第二次没有任何新增。
  • 数据库行页面(Status:、Owner:、Decided: 构成的 key: value 形状)会被识别为 yaml 家族,解析失败后以 0 文档被丢弃,且没有回退到 prose 的机制;同一数据库的 <Name> <id>_all.csv 仍然正常索引,行数据实际由 CSV 兜住。

实验环境与复现命令

捕获运行的 Agent 提示词是:读取 llms.txt,启动本地 XERJ 节点,解压 Notion Markdown + CSV 工作区导出,对同一目录连续运行两次 xerj autoindex,每次运行后 POST 一个按 ax_path 与 ax_locator 排序的 match_all,逐字节比较两次返回的 _id 列表,并上报 autoindex-catalog 标记为 junk 的每个文件及其原因。下面是 4 条核心命令:

命令 1:索引解压后的 Notion 导出(同一行运行两次以验证重复)

xerj autoindex ./notion-export --url http://127.0.0.1:9200 --prefix nt --progress plain

参数说明(来自 cli.rs):--url 指定本地 Elasticsearch 兼容端点;--prefix nt 指定索引前缀(默认 ax),本运行中索引名形如 nt-*;--progress plain 把存活进度写到 stderr(可选 auto|plain|json|none,默认 auto),stdout 只保留最终结果,方便 Agent 管道分流。

命令 2:每次运行后列出全部文档(路径 + 定位符,稳定排序)

curl -s -XPOST http://127.0.0.1:9200/nt-*/_search -H 'content-type: application/json' -d '{"query":{"match_all":{}},"size":100,"_source":["ax_path","ax_format","ax_locator"],"sort":[{"ax_path":"asc"},{"ax_locator":"asc"}],"track_total_hits":true}'

命令 3:查找被 Notion 复制进 2 个不同页面的短语

curl -s -XPOST http://127.0.0.1:9200/nt-*/_search -H 'content-type: application/json' -d '{"query":{"match_phrase":{"body":"meerkat quarterly roadmap"}},"size":10,"_source":["ax_path","ax_format"],"track_total_hits":true}'

命令 4:列出每个导出文件的家族、状态与拒绝原因

curl -s -XPOST http://127.0.0.1:9200/autoindex-catalog/_search -H 'content-type: application/json' -d '{"query":{"term":{"doc_kind":"file"}},"size":500,"_source":["path","format","status","records","reason"],"sort":[{"path":"asc"}]}'

根因一:导出布局本身就在重复标题

Notion 的工作区导出遵循固定命名:一个页面写成 <Title> <32-hex>.md,其子页面放进同名的兄弟目录 <Title> <32-hex>/。于是同一个标题文本同时出现在一个文件名和一个目录名里;而"父页面与子页面都复制了同一段话"时,该短语会在两个导出的文件里各命中一次。

捕获运行中,meerkat quarterly roadmap 短语在 Engineering Handbook a1b2c3d4e5f60718293a4b5c6d7e8f90.md 与 Engineering Handbook .../Runbooks a1b2c3d4e5f60718293a4b5c6d7e8f90.md 各命中一次。这两次命中都是正确结果——文本确实存在于两个导出文件中,不是索引 bug。

根因二:每个 Markdown 文件产出 2 份文档

XERJ 的 autoindex 管线为每个源文件写 1 份整文件文档 + 每 passage 1 份文档。短 Notion 页面通常就是一对,两份文档携带相同的 ax_path 与相同的标题文本,仅靠 ax_locator 区分:

ax_path ax_locator ax_format
Engineering Handbook a1b2c3d4e5f60718293a4b5c6d7e8f90.md file txt-prose
Engineering Handbook a1b2c3d4e5f60718293a4b5c6d7e8f90.md s0 txt-prose
Engineering Handbook .../Runbooks a1b2c3d4e5f60718293a4b5c6d7e8f90.md file txt-prose
Engineering Handbook .../Runbooks a1b2c3d4e5f60718293a4b5c6d7e8f90.md s0 txt-prose

定位符 file 与 s0 的源码含义

ax_locator: "file" 是 XERJ 为每个文件生成的"文件卡片"节点定位符。源码 detect/mod.rs 定义 FILE_CARD_LOCATOR: &str = "file",注释明确说明它不可能与内容定位符冲突——所有 extractor 的定位符都是"字母+数字"形状(s3、p2-s0、b1024、row7、r0 等),永远不会是裸词 file。卡片节点还承担锚点职责:corpus_file 用它派生出 anchor_doc_id,供文件级图检测(wikilink、pathcite 等)挂边。

ax_locator: "s0" 则是 passage/分节记录的定位符。在 extract/mod.rs 中,section_record 用 locator: format!("s{i}") 生成;emit_document(同文件 L694-L743)把整份文档按节流式切分,逐节产出 s0、s1……。对于纯文本 prose 文件,入口在 extract/txt.rs:标题取第一个非空行(截断到 200 字符),正文按节切分(约 32KB 一节,上限 MAX_RECORDS_PER_FILE = 4096,见 extract/mod.rs)。

所以同一个短页面出现 file + s0 两行是 XERJ 的设计而非故障。若客户端希望"每页一条结果",就在 ax_path 上做分组;排序时先 ax_path 后 ax_locator 即可让配对清晰可见:

curl -s -XPOST 'http://127.0.0.1:9200/nt-*/_search' \
  -H 'content-type: application/json' \
  -d '{"query":{"match_all":{}},"size":100,"_source":["ax_path","ax_format","ax_locator"],"sort":[{"ax_path":"asc"},{"ax_locator":"asc"}],"track_total_hits":true}'

重索引是幂等的:两次运行 8 个文档、_id 逐字节一致

捕获运行先索引一遍 Notion Markdown + CSV 导出,再用完全相同命令索引同一目录。两次都返回 8 个文档,每个 _id 逐字节匹配,第二次什么都没加。第二次运行终端报告 files=0 records=8:XERJ 识别到所有文件内容未变,没有提交任何新源文档。

幂等的底层机制在 ids.rs:

  • file_key 以内容为身份——xxh3_64(前 64KB) ‖ 文件大小,跨 mtime 变化与重复遍历保持稳定,大文件也只需读前 64KB;
  • doc_id 由 (dataset_slug, file_key, locator) 三元组确定性派生(xxh3_128,32 位十六进制),并带有 doc_id_stable 等单元测试钉死"同输入同输出、不同 locator 不同 id"的性质;
  • 因此重跑同一语料会发射字节相同的 _id,bulk 的 index 动作变成覆盖写而非新增。模块注释明言:kill -9 后重跑也能收敛,不会累积重复。

这正是"重复标题"与"重复索引"必须区分的原因:前者来自导出布局 + 双文档设计,后者在 XERJ 中根本不会发生。

注意:数据库行页面被当成 YAML 拒绝

如果导出页面的大部分非空行读起来像 YAML——一行 key: value,或一行以 - 开头——家族嗅探器会把页面归类为 yaml。Notion 把数据库行页写成"标题 + Status:、Owner:、Decided: 行",恰好就是这个形状。随后 YAML 解析失败,XERJ 以 0 文档丢弃该文件;没有回退到 prose 的机制,终端上唯一的信号是 junk 文件计数。

捕获运行中 Decisions 0f1e2d3c4b5a69788796a5b4c3d2e1f0/ 下的 3 个数据库行页面全部以此方式被拒绝,原因均为 no records extracted (yaml candidate family, 1 junk lines),该次运行报告 junk_files=3。

判定阈值与 front-matter 例外(源码级)

判定逻辑位于 sniff.rs:当 yaml_line_ratio(nonblank) >= 0.6 且正文能作为 YAML 流解析(parses_as_yaml_stream,基于 serde_yaml 的多文档迭代器)时归入 Family::Yaml;若只满足行形状但解析失败,则不会误判。被拒绝文件的终端原因字符串由 lib.rs 统一拼装为 no records extracted ({family} candidate family, {junk} junk lines),其中 {family} 来自嗅探家族,{junk} 来自 extractor 的 stats.junk。

一个关键例外:文件顶部的 --- front-matter 块本身不会触发 YAML 归类。在 sniff.rs 中,若文件以 --- 开头且有闭合 ---,嗅探器会跳过 front-matter,按其后的正文形状分类:正文仍像 YAML(yaml_line_ratio * 2 < body.len() 不成立)则维持 YAML;正文不像 YAML 则交给结构化家族分类或 txt_kind(prose)。这是 #587/#1142 修复的产物——历史版本曾把带 front-matter 的 Markdown 正文误送 YAML extractor 造成静默丢数据。

3 文件最小复现(脱离 Notion 同样成立)

  • prose-no-colons.txt → 家族 txt-prose,正常索引;
  • speaker-colons.txt(如剧本的 Speaker: 台词 形状)→ 家族 yaml,被丢弃;
  • markdown-bullets.md(大量 - 行)→ 家族 yaml,被丢弃。

可见"行内有冒号"或"行首是 - "的正文在达到比例阈值且能按 YAML 解析时就会被归为 yaml,与是否来自 Notion 无关。

数据库 CSV 仍然可用,行数据没有丢

Notion 还会把每个数据库导出为 <Name> <id>_all.csv。捕获运行中该文件被归入 csv 家族,产出 4 个文档:1 份整文件文档 + 3 份行文档,定位符分别为 r0、r1、r2(行定位符 r{i} 的生成见 extract/csv_x.rs)。

因此,被拒绝的 Markdown 行页面丢失的行数据,实际由同名 _all.csv 兜住了。每次运行后都去读 autoindex-catalog,把文件数与文档数对账,再下结论:

curl -s -XPOST 'http://127.0.0.1:9200/autoindex-catalog/_search' \
  -H 'content-type: application/json' \
  -d '{"query":{"term":{"doc_kind":"file"}},"size":500,"_source":["path","format","status","records","reason"],"sort":[{"path":"asc"}]}'

autoindex-catalog 是 autoindex 维护的目录索引(映射定义在 catalog.rs),每条 doc_kind: file 记录携带 path、format(家族)、status、records(文档数)、junk 与 reason 字段——其中 reason 正是上面那句 no records extracted (...)。查询它就能在报告"文档数"之前先确认文件层面发生了什么。

本次捕获不覆盖的范围(结论边界)

  • 导出目录来自 fixture 生成器,按 Notion 自身命名规则书写;宿主机上从未运行过 Notion,也未连接任何工作区。XERJ 没有 Notion connector,全程不产生网络抓取。
  • XERJ 本次以单节点运行,无复制、无故障转移。
  • XERJ 默认 embedder 是词法特征哈希(lexical feature hashing),因此查询与其改写(paraphrase)若不含共同词则不会匹配;神经向量嵌入需通过 --embed-mode neural 显式开启(ONNX 实验后端另需 --embed-mode onnx-experimental --onnx-model ... --onnx-tokenizer ...,且只对推断为 semantic_text 的长文本字段生效,见 cli.rs)。
  • 文中所用数字均来自 RUN-B(2026-08-21 捕获)。该二进制为 ci-test 配置构建,因此本次运行的任何 wall-clock 数值都不作为性能数据发布。

FAQ

对同一份 Notion 导出索引两次会产生重复吗?

不会。捕获运行对同一导出索引两次,两次均得到 8 个文档,_id 逐字节一致,第二次零新增。原因是 doc_id 由内容哈希派生的 file_key 与定位符确定性生成,bulk 覆盖写而非追加。

为什么同一个 Markdown 页面出现 2 条结果?

每个 Markdown 文件产出 2 份文档:ax_locator 为 file 的整文件文档,与 ax_locator 为 s0 的 passage 文档。两者 ax_path 与标题相同,属预期设计。

为什么一个标题出现在 2 个不同路径?

Notion 把页面写成 <Title> <32-hex>.md,把子页面放进同名 <Title> <32-hex>/ 目录;复制进两个页面的文本自然命中两次。

为什么我的 Notion 数据库行一条也搜不到?

3 个数据库行页面全部被归类为 yaml 并以 0 文档拒绝。凡是"非空行多数读作 key: value"的 prose 文件都可能以这种方式被丢弃,且没有回退到 prose 的机制。

如何把重复命中折叠成 1 页?

在客户端按 ax_path 分组。捕获运行的列目录查询先按 ax_path、再按 ax_locator 排序,让 file/s0 配对直接可见。

Notion 为数据库导出的 CSV 能正常索引吗?

能。捕获运行将 Decisions <id>_all.csv 以 csv 家族索引,产出 4 个文档:1 份整文件文档 + 3 份行文档(r0/r1/r2)。

这些结果来自哪里?

全部来自 2026-08-21 在 16 核 AMD EPYC 9645 宿主机上捕获的 RUN-B。

相关阅读

登录后查看全文
xerj