AI Agent Guide Interactive
模块三 · RAG 检索与证据 预计阅读 12 分钟 · 3 个交互实验台

文档解析与分块策略:RAG 检索不准,问题可能出在向量化之前

很多人第一次搭建 RAG,会把精力全花在 Embedding 模型、向量数据库和 Prompt 上。系统跑起来后,检索结果依然很乱。往上游排查,问题往往早就发生在文档解析、清洗和切片阶段。上游数据已经失真,后面换模型、调 Prompt,通常只是给脏数据做精装修。

30 秒速览 · 本章 3 个核心工程判断
  1. 01 解析顺序错了,切片和 Embedding 救不回来。多栏错位、表格打平、扫描件缺文字层,必须先升级解析环节或抽样验收。
  2. 02 切片没有通用最优值,但中文基线必须显式加入全角分隔符并保留标点;先用 Recursive 建基线,再由查询集调参。
  3. 03 元数据有两条去向:进 payload 负责过滤与溯源,拼入文本前缀补足孤立语义但会增加 token 并改变相似度分布。

长上下文时代为什么还要做 RAG,以及上游为何最先出事

长上下文解决“能放多少”,RAG 解决“应该放什么”。上游文档处理决定了检索系统能看到什么,数据一旦在这里被切碎或错位,下游环节无法修复。

大模型的上下文窗口越来越长,文件搜索也逐渐成为模型平台的内置能力。但上下文再长,也不适合每次都把整套产品文档、公司制度和历史资料全量塞给模型。除了浪费 token 和混入噪音,当数据持续更新、不同用户权限不同、回答必须附带可靠出处时,模型仍然要先找证据,再基于证据回答。

如今的 RAG 正在成为 AI 应用和 Agent 的知识层:Agent 决定什么时候查、查什么、是否继续查;检索系统负责从真实数据中召回可靠证据。而整条链路的第一步,就是把原始文档变成质量稳定、来源清晰的 DocumentChunk。

RAG 文档预处理流水线:四个处理阶段与上游失真高发点 结构示意
主链路 · 从原始文件到可检索证据 原始文档 PDF / Markdown 1. 解析提取 恢复阅读顺序 2. 文本清洗 去噪与归一化 3. 切片重叠 保留自然边界 4. 元数据注入 DocumentChunk[] 高频失真点 · 一旦出错下游无法修复 多栏错位 · 表格打平 正则误吞标题与列表 句中硬切 · 丢失标点 裸文本失源 · 权限失效

PDF 解析,难点不只是读取文字

Markdown 和纯文本可以直接读取,但 PDF 麻烦得多。PDF 本质上关心页面如何精准排版呈现,不保证程序能直接恢复人类阅读顺序。普通 PDF 需要解析器根据字符坐标推断段落、栏位和表格,而推断经常在三类文档上翻车:多栏布局打乱顺序、表格丢失行列对应、以及扫描件根本没有文字层。

实验 01 · 上游故障与清洗器诊所

亲眼看看 PDF 解析翻车,以及“通用清洗正则”如何制造新脏数据

切换三类常见 PDF 故障,并在“文本清洗”标签下逐条开关正则规则,观察标题与列表被误吞并的瞬间。

交互诊断沙盒
故障场景:
解析方式:
原始 PDF 视觉版面 人眼看到的页面
解析器输出的文本流 语义错乱

            

在 Node.js 生态里,处理有可靠文字层、版式相对规整的 PDF,可以从 pdf-parse 起步。它用 TypeScript 编写、自带类型声明,不需要原生编译扩展,除文字和图片提取外也提供基础表格检测。但面对复杂多栏、跨页表格或扫描件时,不要指望切片算法修复错误的阅读顺序:需要底层字符坐标时可选用 Mozilla 的 pdfjs-dist;若文档布局复杂且表格是核心证据,可评估 LlamaParse 等专门解析服务(接入前请结合官方定价页的积分计费方式与真实文档抽样效果做验证)。

扫描件快速排查与 OCR 验收
在 PDF 阅读器里尝试选中文字可以做一次快速判断:选不中往往意味着需要 OCR(不过字体轮廓化或复制权限限制也会导致无法选中)。进入切片前,务必抽样核对标题、数字、专有名词和表格,检索系统不会察觉 OCR 错字,只会忠实地把错误内容召回。

三种切片策略、中文分隔符与 Overlap

切片要在“内容足够小、语义足够聚焦”和“上下文足够完整、能独立回答问题”之间找平衡。

切片太大,一个 chunk 混进多个话题,向量很难准确代表其中任何一个;切片太小,只剩半句话;切割位置不对,关键结论被劈成两半,任意一个 chunk 都答不全问题。

先猜再验证 基于 Embedding 相似度找主题边界的 Semantic(语义切片) 听起来更高级。在公开基准测试中,它是否稳定击败了 Recursive 或 Page-level 切片?
实证结论:Vectara 在 NAACL 2025 发表的对比研究 来源:Vectara NAACL 2025 ↗ 表明,语义切片在文档检索、证据检索与生成任务中并没有表现出稳定优势,其额外的 Embedding 计算成本缺乏一致收益支撑。NVIDIA 在 2025 年的切片实验 来源:NVIDIA 2025 ↗ 也发现,不同数据集的最佳 chunk size 各不相同,整体平均表现最好的是 page-level 切片,15% overlap 的收益也只出现在特定组合中。
实验 02 · 真实算法切片沙盒

调节策略、中文分隔符、Chunk Size 与 Overlap,实时观察断句与粘连

下方直接运行本章的 fixedSizeChunk、splitRecursive 与 addOverlap 算法。拖动参数,检查高亮的重叠区与截断告警。

教学沙盒 · 字符上限演示
切片策略:
Overlap 空间:
CHUNK_SIZE(字符上限) 80 字符
OVERLAP(重叠比例) 15%(12 字符)
原文切刀实时投影(切割点直接落在原文上,方便观察是否腰斩句子)
自然边界切刀 句中硬切警报 Overlap 借位重叠区
查看当前参数对应的 TypeScript 切片实现(实时同步)
chunking-strategies.ts · 参数与分隔符实时同步

工程上更稳妥的推进顺序是:先用 Fixed-size 或 Recursive 建立基线,把 256~512 token 和 10%~15% overlap 放进初期候选范围,再用自己的真实查询集做检索评估。另外要区分字符与 token:不同模型的 tokenizer 切分规则不同,不能用固定比例把中文字数精确换算成 token。本文示例为方便直接运行采用字符上限,接入真实 Embedding 模型后应改用对应 tokenizer 计算长度。

处理中文文档时,尤其要注意两点:显式把全角标点 。?!;, 加入分隔符优先级列表,并且在 split() 后把命中的标点拼接回片段末尾,避免出现“训练的Transformer”这种标点丢失造成的文本粘连。

元数据注入的两条路径与完整处理链路

切片不能只存一段裸文本。至少要记录来源文档、所属章节和切片序号,并明确元数据是只进向量库 payload,还是拼进待向量化的文本前缀。

source 负责引用溯源与文档级过滤,section 保存标题路径用于定位,chunkIndex 与 totalChunks 则为相邻切片扩展和线上排查提供位置依据。

元数据注入的两条路径:Payload 过滤溯源 vs 标题前缀补足语义 架构示意
DocumentChunk text: "普通工单 4 小时内响应..." source · section · chunkIndex 路径 A:写入向量库 Payload 权限隔离 · 元数据过滤 · 来源展示 不改变切片本身的向量语义 路径 B:标题前缀拼入文本 [文档 / 章节] + 正文一起 Embedding 补孤立语义,但增 token 且改相似度分布 向量索引记录 vector: float[] payload: { source, ... }
实验 03 · 元数据双路径 X-Ray

当两份年度制度的孤立切片正文几乎一模一样时,检索怎么分清谁是 2025 版?

测试查询:“2025 年售后工单响应时限改成多久了?”。切换三种入库方式,对比送入 Embedding 的文本、Payload 载荷与检索排序后果。

模拟召回排序演示
实际入库结构(Embedding 输入 + Payload) 额外前缀约 +18 字符

          
检索结果排序(无显式过滤条件时)

跑通完整文档处理链路

把解析、清洗、预留 Overlap 的递归切片和元数据注入串起来,就能得到可直接喂给下游 Embedding 环节的 DocumentChunk[]。完整可运行脚本与测试样例保存在公开仓库 examples/rag/document-parsing-chunking/。

查看完整的 processDocument() TypeScript 流水线
examples/rag/document-parsing-chunking/parse-and-chunk.ts
import path from "path";
import { PDFParse } from "pdf-parse";

interface DocumentChunk {
  text: string;
  metadata: {
    source: string;
    section?: string;
    chunkIndex: number;
    totalChunks: number;
  };
}

async function parsePDF(filePath: string): Promise<string> {
  const parser = new PDFParse({ url: filePath });
  const data = await parser.getText();
  return data.text;
}

async function processDocument(filePath: string): Promise<DocumentChunk[]> {
  const fileName = path.basename(filePath);
  const rawText = await parsePDF(filePath);
  const cleanedText = cleanText(rawText);

  const CHUNK_SIZE = 512;
  const OVERLAP = Math.floor(CHUNK_SIZE * 0.15);

  // 预留 overlap 空间,保证最终切片仍不超过 CHUNK_SIZE
  const splitChunks = splitRecursive(cleanedText, CHUNK_SIZE - OVERLAP);
  const textChunks = addOverlap(splitChunks, OVERLAP);

  return textChunks.map((text, index) => ({
    text,
    metadata: {
      source: fileName,
      chunkIndex: index,
      totalChunks: textChunks.length,
    },
  }));
}
真实运行踩坑:NFKC 之后仍可能残留兼容字形
在真实 PDF 样本上跑完完整脚本后,部分 PDF 字体编码产生的兼容字形在 normalize("NFKC") 后依然可能残留。遇到这类问题时,应针对具体文档来源补充字符映射或更换解析器,不要假设一次通用清洗就能解决所有异常。另外,处理 Markdown 时不要硬套纯文本正则,应使用 Markdown 解析器生成语法树,先按标题层级切分 section,再对过长段落递归切片。

工程选型速查矩阵

文档处理没有银弹,按文档形态与检索目标做决策,并用抽样检查和真实查询集验证每一步改动。

解析选型
版式规整、带文字层的 PDF

先用 pdf-parse 跑通基础链路,保存原始文本与清洗后文本做抽样对比,确认阅读顺序正确再进入切片。

解析选型
多栏论文、复杂表格或扫描件

优先升级解析层(底层坐标重建用 pdfjs-dist,复杂版面评估 LlamaParse 或 OCR),绝不指望下游切片修复错位文本。

切片策略
第一版基线与参数候选

从 Recursive(或按页结构完整的 Page-level)起步,初期测试 256~512 token 与 10%~15% overlap,确认有痛点再评估 Semantic 切片。

清洗与中文
中文技术文档与合同

显式加入 。?!;, 分隔符并保留标点;清洗规则必须先看样本噪音再逐条添加,避免软换行正则吞并标题与列表。

清洗与结构
Markdown 知识库与 API 文档

利用 Markdown 解析器生成 AST,先按标题层级切分 section 并保护代码围栏与表格,只对超长 section 做二次递归切片。

元数据设计
多版本制度与权限隔离

source、section、chunkIndex 必入 payload 管过滤与引用;若切片脱离标题后语义模糊,再按需拼接轻量标题前缀进 Embedding 文本。