XERJ 索引 Notion 导出出现重复搜索结果:导出布局、文档切分与 YAML 误判的完整排查指南

原创2026-10-16 22:46:241,615 阅读
文章标签:人工智能搜索引擎本地部署后端MCP 服务

XERJ 索引 Notion 导出出现重复搜索结果:导出布局、文档切分与 YAML 误判的完整排查指南

导读:Notion 的 Markdown + CSV 导出被 xerj autoindex 索引后,同一页面标题会在搜索结果中重复出现,很多人第一反应是"索引跑重了"。本篇以一次完整捕获实验(RUN-B)为骨架,结合 XERJ autoindex 源码(xerj-autoindex),解释重复结果真正来自 Notion 导出布局与"每文件两个文档"的切分机制,并给出验证幂等、按 ax_path 聚合、识别 YAML 误拒、使用数据库 CSV 兜底的完整实操方法。

TL;DR:重复来自导出布局与文档切分,而不是重复索引

一次捕获运行将同一个 Notion Markdown + CSV 导出连续索引了两次,两次都返回 8 个文档,且每次的 _id 字节级一致、第二次运行没有新增任何内容。

  • 重复标题来自 Notion 导出布局本身:同一标题同时出现在文件名和同名目录名中;
  • 每个 Markdown 文件由 XERJ 写成 2 个文档(整文件文档 + 首个文本段落文档),所以一个页面出现 2 条命中是设计行为;
  • 重新索引是幂等的:第二次运行终端显示 files=0 records=8,XERJ 识别出所有文件未变化,未提交任何新源文档;
  • 需要留意的是:Notion 的数据库行页面(标题下只有 Status:、Owner:、Decided: 这类 key: value 行)会被家庭嗅探器误判为 yaml 并被拒收,但同一数据库导出的 CSV 文件仍正常工作,可以兜底。

所有结果来自 2026-08-21 捕获的 RUN-B,运行在 16 核 AMD EPYC 9645 主机上。

Notion 导出布局:一个标题出现在两个路径里

Notion 的导出会把一个页面写成 <Title> <32-hex>.md,并把它的子页面放进同级目录 <Title> <32-hex>/。因此同一个标题文本同时出现在一个文件名和一个目录名中,这就是"重复标题"的第一个来源。

实验中,一句被 Notion 同时复制进父页面和子页面的短语(meerkat quarterly roadmap)返回了 2 条命中:

  • Engineering Handbook a1b2c3d4e5f60718293a4b5c6d7e8f90.md
  • Engineering Handbook .../Runbooks a1b2c3d4e5f60718293a4b5c6d7e8f90.md

这两条命中都是正确的:这段文本确实存在于两个导出的文件里。导出目录结构在设计上就让标题在路径层重复,这不是索引错误。

如果你希望按页面收敛结果,可以在客户端按 ax_path 分组;如果希望让成对结果显式可见,就按 ax_path 再按 ax_locator 排序。

每个 Markdown 文件产生 2 个文档:file 与 s0

XERJ 对散文类文件会写 1 个整文件文档 + 每个文本段落 1 个文档。对于一篇短 Notion 页面来说就是一对,两个文档携带相同的 ax_path 和相同的标题文本:

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

源码印证:文档切分如何决定 s0

在 extract/txt.rs 中,extract_prose 读取整个文件后调用 emit_document 生成段落记录;而 extract/mod.rs 中的 section_record 会把段落序号写进 locator:locator: format!("s{i}")。因此一篇短文件的第一段就是 s0。整文件文档的 locator 则是 file(在端到端测试 detect/e2e.rs 中可见其被用于筛选整文件文档)。

值得注意的切分参数(见 extract/txt.rs):

  • 散文文件读取上限 TXT_CAP 为 16 MiB;
  • 每块 CHUNK_LINES = 40 行、块间重叠 CHUNK_OVERLAP = 10 行(保证跨块答案两侧都可检索);
  • 单块字节上限 CHUNK_MAX_BYTES = 8 KiB,防止超长行产生巨型 _source;
  • 整文件解析上限 MAX_WHOLE_FILE = 64 MiB(见 extract/mod.rs)。

最终 ax_locator 字段在 sync_executor.rs 中写入源文档:每个记录同时被标记 ax_path(相对路径)、ax_file(内容寻址 id)、ax_locator(locator 原样透传)与 ax_dataset。

实战:用稳定排序列出全部文档并观察成对

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}'

按 ax_path 升序、ax_locator 升序排序后,file 与 s0 会相邻出现,重复来源一目了然。如果你的客户端希望"每页一条结果",直接按 ax_path 分组即可。

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

捕获实验用同一条命令把同一导出目录索引了两遍:

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

两次运行都返回 8 个文档,每次的 _id 与上一次字节级一致,第二次没有新增任何内容。第二次运行时终端报告 files=0 records=8——XERJ 识别出每个文件都未变化(内容寻址命中),于是没有提交任何新源文档。

这印证了幂等的三个来源:

  1. 稳定的 id:段落 chunk 的 locator 取自窗口首行的字节偏移(extract/txt.rs),跨重跑保持稳定;文档 id 由 slug + content_id + locator 组成(sync_executor.rs);
  2. 内容寻址:未变化的文件复用既有 artifact,不重复提取、不重复嵌入(sync_executor.rs);
  3. --prefix 隔离:索引前缀(默认 ax,见 cli.rs)决定写入的索引名,重复跑同一前缀不会叠加新文档。

所以:"重复搜索结果"不是"重复索引"造成的。要验证这一点,只需跑两次同样的命令,然后对比两次 match_all 查询返回的 _id 列表。

警惕:数据库行页面会被当作 YAML 拒收

现象

如果导出页面的大部分非空行读起来像 YAML——形如 key: value 的行,或 - 开头的行——家庭嗅探器会把该页面分类为 yaml。Notion 的数据库行页面正是这种形状:一个标题下面只有 Status:、Owner:、Decided: 这样的键值行。随后 YAML 解析失败,XERJ 以 0 文档拒收该文件,且没有回退到散文,终端上唯一的信号是 junk 文件计数。

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

源码印证:YAML 判定与 frontmatter 例外

在 sniff.rs 中,分类逻辑对 key: value 形状先行判断,然后执行两条关键规则:

  • frontmatter 例外(#551):文件以 --- 开头且存在闭合 ---,并且其后正文本身不像 YAML 时,按正文分类,而不是把整个文件丢给 YAML 提取器。因此 Markdown 顶部带 --- front-matter 块不会单独触发 YAML 误判——文件会按 front-matter 之下的正文来分类;
  • 真 YAML 闸门(#1142):只有当 yaml_line_ratio >= 0.6 且 文本能真正解析为 YAML 流时才判定为 Family::Yaml。纯 key: value 的"标签化散文"(如 NIST/OSCAL 控制文件形状)被列为已知误判案例,仓库源码中对此有明确注释。

Notion 数据库行页面恰好落在边界上:行形状像 YAML,但作为整体又无法解析成合法 YAML 流,最终被归入 yaml 候选家庭并拒收。拒收原因字符串 no records extracted ({} candidate family, {} junk lines) 生成于 lib.rs,并作为 reason 写入 autoindex-catalog。

最小复现:与 Notion 无关的 3 个文件

XERJ 对一组最小文件做了同样的验证:

  • prose-no-colons.txt → 分类为 txt-prose,正常索引;
  • speaker-colons.txt(如 Speaker: xxx 形状)→ 判为 yaml 家庭,拒收;
  • markdown-bullets.md(- 开头占多数)→ 判为 yaml 家庭,拒收。

这说明"看起来像 YAML"的判定是内容形状驱动的,与是否来自 Notion 无关。

数据库 CSV 仍然可用:4 个文档的兜底方案

Notion 还会为每个数据库写出 <Name> <id>_all.csv。本次捕获中 XERJ 将该文件归类为 csv 家庭,产出 4 个文档:1 个整文件文档 + 3 个行文档,locator 分别为 r0、r1、r2。

因此:被拒收的 Markdown 行页面丢失的行数据,可以通过同名 CSV 找回来。每次运行后都建议先读 autoindex-catalog,在汇报文档数之前先对比"文件数 vs 文档数":

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(含 junk、duplicate)、records、reason 等字段。被拒文件会以 status: "junk" 写入(lib.rs)。查询结果会直接告诉你:

  • 哪些文件被判定为哪种格式(format);
  • 每个文件产出了几条记录(records);
  • 哪些文件被拒、为什么被拒(status + reason)。

定位到具体命中:短语查询示例

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}'

此查询用来确认同一个短语被 Notion 导出进了 2 个不同页面,是排查"重复命中"的第一步。

本次捕获的运行边界(数据可信度说明)

  • 导出文件夹来自 fixture 生成器,按 Notion 自己的文件命名规则生成;Notion 从未在本机运行,也未连接任何 workspace。XERJ 没有 Notion 连接器,不会通过网络抓取任何内容;
  • 运行是单节点,无复制、无故障转移;
  • XERJ 的默认嵌入器是词法特征哈希(lexical feature hashing),因此与查询没有共享词汇的改写句不会匹配;神经嵌入需通过 --embed-mode neural 显式开启;
  • 以上所有数字来自 2026-08-21 捕获的 RUN-B;该二进制为 ci-test profile 构建,因此本运行中的任何墙钟耗时数据不作为性能数字发布。

排查清单:把"重复结果"一次性查清楚

把上述要点浓缩成一套可执行流程:

  1. 确认来源:用 match_phrase 命中短语,观察是否命中 2 个不同 ax_path——是则来自导出布局的父子页面文本重复;
  2. 确认切分:按 ax_path + ax_locator 排序,观察每个 ax_path 是否出现 file/s0 成对——是则来自"每文件两个文档"的机制;
  3. 排除重复索引:同命令跑两遍,对比两次 _id 列表是否字节级一致,第二次是否 files=0;
  4. 检查漏索引:查询 autoindex-catalog,对比文件数 vs 文档数,留意 status: junk 与 reason,重点关注 yaml candidate family 拒收的数据库行页面;
  5. CSV 兜底:确认同名 _all.csv 已按 csv 家庭索引出整文件文档 + 行文档,行数据没有真正丢失。

相关主题可继续阅读:将 Markdown 索引进 Elasticsearch API、用 autoindex map 盘点文件、中断后恢复 autoindex 运行。

登录后查看全文
xerj