XERJ 索引 Notion 导出出现重复搜索结果:导出布局、文档切分与 YAML 误判的完整排查指南
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.mdEngineering 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 识别出每个文件都未变化(内容寻址命中),于是没有提交任何新源文档。
这印证了幂等的三个来源:
- 稳定的 id:段落 chunk 的 locator 取自窗口首行的字节偏移(extract/txt.rs),跨重跑保持稳定;文档 id 由
slug + content_id + locator组成(sync_executor.rs); - 内容寻址:未变化的文件复用既有 artifact,不重复提取、不重复嵌入(sync_executor.rs);
--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-testprofile 构建,因此本运行中的任何墙钟耗时数据不作为性能数字发布。
排查清单:把"重复结果"一次性查清楚
把上述要点浓缩成一套可执行流程:
- 确认来源:用
match_phrase命中短语,观察是否命中 2 个不同ax_path——是则来自导出布局的父子页面文本重复; - 确认切分:按
ax_path+ax_locator排序,观察每个ax_path是否出现file/s0成对——是则来自"每文件两个文档"的机制; - 排除重复索引:同命令跑两遍,对比两次
_id列表是否字节级一致,第二次是否files=0; - 检查漏索引:查询
autoindex-catalog,对比文件数 vs 文档数,留意status: junk与reason,重点关注yaml candidate family拒收的数据库行页面; - CSV 兜底:确认同名
_all.csv已按csv家庭索引出整文件文档 + 行文档,行数据没有真正丢失。
相关主题可继续阅读:将 Markdown 索引进 Elasticsearch API、用 autoindex map 盘点文件、中断后恢复 autoindex 运行。