RAG Part 1:文档加载与文本分块

Catalogue
  1. 1. 文件、Document 和 Node 分别是什么
  2. 2. 加载之前,先看文件里是什么
    1. Markdown:保留已有的标题和代码边界
    2. PDF:有文字层,也不代表结构已经正确
  3. 3. 先把 PDF 和 Markdown 加载出来
    1. 准备输入和环境
    2. 第一段:得到正文与来源信息
  4. 4. 分块时,到底在选择什么
    1. 常见策略怎样选
    2. chunk_size 与 chunk_overlap
  5. 5. 把标题和页码带进每个块
    1. 第二段:先分章节,再限制长度
    2. 第三段:导出,打开看一遍
    3. 为什么正文常常没有 256 token
  6. 6. 改参数,观察块数和重复内容
  7. 7. 普通提取不够用时,怎样接入解析工具
  8. 8. 用几个问题检查切分结果

《LangChain 检索与 LCEL 入门》用几段手写的退款规则演示了检索。换成真实资料,输入往往是一份 PDF 手册、一篇 Markdown 笔记,甚至是扫描件。程序首先要把文件里的内容读对,才有可供检索的文字。

接着还要决定:一次拿多大一段内容去检索?整份手册包含太多主题;切得过碎,又可能把“支持退款”和“不支持退款的条件”分到两处。加载与分块共同决定了后面的检索器能拿到什么资料。

本篇使用 LlamaIndex 完成一个不调用大模型的练习:加载 PDF 和 Markdown,保留页码、标题等来源信息,切分文本并导出结果。读完后,应当能判断一份文件需要普通文本提取、OCR 还是版面解析,并通过观察输出调整分块策略。文中的退款规则均为虚构教学资料。

1. 文件、Document 和 Node 分别是什么

LlamaIndex 是用于构建文档检索、问答等应用的框架。这里用到它的两类组件:Reader 负责把来源资料加载并整理成 Document,Node Parser 负责把 Document 切成较小的 Node。Document 和 Node 都能保存正文与来源信息,下面会通过文件与文本块的对应关系解释它们。

Reader 的加载过程可以包含文档解析。例如,本文的 PDFReader 会在内部调用 pypdf 提取 PDF 文字,再将每页文字包装成 Document 返回。Reader 负责接入和组织数据,具体的解析能力取决于它使用的工具。

Unstructured、MinerU、Docling 是文档解析工具,可以提取文字,并根据所选功能处理 OCR、表格或版面结构。接入 LlamaIndex 时,可以由相应的 Reader 封装对工具的调用,也可以自己先调用工具,再把结果包装成 Document。后文的 Docling 示例采用第二种方式。因此,它们与 Reader 可以协作:解析工具处理文件内容,Reader 将结果接入框架。

先把数据流连起来看:

1
2
3
4
5
6
7
PDF / Markdown 文件
↓ Reader 加载(可调用解析工具),或自行解析并包装
Document:正文 + 来源信息
↓ 按标题、句子等边界切分
Node:较小的正文片段 + 来源信息
↓ 后续文章再接入
向量化、存储、检索

在本篇的纯文本例子中,可以这样区分几个对象:

对象 装的是什么 本篇例子
文件 原始资料 refund.md、policy.pdf
Document 加载得到的文本及 metadata 元数据 一篇 Markdown,或者 PDF 的一页
TextNode 一段准备参与检索的文本及其元数据、关联信息 “申请条件”章节中的一个小块

一个文件不一定对应一个 Document。 比如 PDF 可以按页加载,每页各得到一个 Document;一个 Document 又可以拆成多个 Node。Node 的文字部分常被称为 chunk,即文本块。LlamaIndex 的 Documents / Nodes 说明

metadata 是随正文一起保存的字典,例如文件名、页码和章节标题。它让程序在命中一段退款说明时,还能指出这段话来自哪个文件、哪一页。LlamaIndex 默认会把 Document 的元数据传给从它切出的 Node。

前文使用的是 LangChain 的 Document(page_content=...);本篇使用 LlamaIndex 的 Document(text=...)。两者都能保存文本和元数据,但属于不同库,属性和接口不能直接混用。

2. 加载之前,先看文件里是什么

Markdown:保留已有的标题和代码边界

Markdown 本身就是文本,#、##、空行、列表和代码围栏已经提供了一部分结构信息。加载时先保留这些标记,后面才能按章节切分。例如:

1
2
3
4
5
6
7
# 退款说明

## 申请条件
普通商品在签收后七天内可以申请退款。

## 到账时间
审核通过后,款项在三个工作日内原路退回。

直接删除所有 #,会让后面的分块器失去章节边界;把全文压成一行,也可能破坏列表和代码格式。本篇用 Python 的 Path.read_text(encoding="utf-8") 读入原文,再创建 Document,让读文件和分章节两个动作清楚地分开。

PDF:有文字层,也不代表结构已经正确

PDF 的页面外观相似,内部内容却可能不同:

文件情况 首先尝试什么 需要检查什么
带可提取文字层、排版简单 普通 PDF 文本提取 是否漏字、乱码,段落顺序是否正常
页面主要是扫描图片 OCR,把图片中的字符识别出来 数字、否定词、专有名词是否识别错
双栏、复杂表格、公式较多 能分析版面与结构的解析工具 阅读顺序、表格行列、公式与正文的关系

这些情况可以同时出现:同一份 PDF 的前几页有文字层,附录却是扫描图片;扫描件也可能已经附带一层 OCR 文字。能选中和复制文字,只能作为初步线索。

本篇使用的 PDFReader 调用 pypdf 提取已有文字层,不会自动做 OCR。只有图片的页面可能得到空文本;提取出了很多文字,也不能据此认定双栏顺序和表格结构正确。pypdf 文本提取说明

切分前,至少将抽取文本与原文件中的一页对照。确认反复出现的文字是页眉、页脚后再移除;保留段落、列表、表头和单位。不要一开始就用全局替换删除所有换行,或者凭一个正则把每页首尾都裁掉。

假如一张表原本表达“普通商品:七天;定制商品:不支持”,抽取后变成“普通商品 定制商品 七天 不支持”,行列对应关系已经丢失。后面把块切得再小,也无法可靠恢复这个关系。

3. 先把 PDF 和 Markdown 加载出来

准备输入和环境

下载本文示例包,解压后进入 rag-part1-example 目录。包内包含完整脚本和自制教学文件;policy.pdf 是带文字层的两页 PDF,不是扫描件。

1
2
3
4
5
6
7
rag-part1-example/
├── data/
│ ├── refund.md
│ └── policy.pdf
├── prepare_chunks.py
├── compare_chunks.py
└── requirements.txt

本例使用 Python 3.12。创建虚拟环境后安装固定版本依赖:

1
2
3
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Windows PowerShell 的激活命令为 .venv\Scripts\Activate.ps1。示例依赖为 llama-index-core==0.14.25、llama-index-readers-file==0.7.0、pypdf==6.19.0 和 tiktoken==0.14.0。只加载和切分文档,不需要 API Key;首次使用分词器时可能下载词表,安装和首次运行应允许联网。

下面把 prepare_chunks.py 按执行顺序拆成三段解释。它们组成同一个文件,后文会沿用前面定义的变量;下载包已包含完整代码。

第一段:得到正文与来源信息

先加载 Markdown,再逐页加载 PDF。md_document 是包含整篇 Markdown 的单个 Document,此时所有章节都在它的正文中,还没有按标题拆开;pdf_documents 是按页加载得到的 Document 列表。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import json
from pathlib import Path

from llama_index.core import Document
from llama_index.core.node_parser import MarkdownNodeParser, SentenceSplitter
from llama_index.readers.file import PDFReader

md_path = Path("data/refund.md")
md_text = md_path.read_text(encoding="utf-8")
md_document = Document(
text=md_text,
id_="refund-md",
metadata={"source": md_path.name},
)

pdf_path = Path("data/policy.pdf")
pdf_documents = PDFReader(return_full_document=False).load_data(file=pdf_path)

for page_number, document in enumerate(pdf_documents, start=1):
document.id_ = f"policy-pdf-page-{page_number}"
document.metadata["source"] = pdf_path.name
document.metadata["page_number"] = page_number
print("PDF", page_number, document.metadata["page_label"], document.text[:25])

Document(text=...) 把 Markdown 原文包装起来,id_ 是这个文档的标识。source 是本例自行约定的元数据字段,用于记录来源文件名;它不是框架自动追踪文件的开关。

PDFReader(return_full_document=False) 每页返回一个 Document。循环中的 enumerate(..., start=1) 同时给出从 1 开始的序号和当前页对象。本例将这个序号保存为 page_number,表示文件中的物理页序;Reader 原有的 page_label 来自 PDF 页标签,可能是 i、ii、1,不一定等于物理页序。PDFReader 实现

运行到这里,应能看到两页的标题预览。预览只是快速发现空文本或明显乱码的办法;检查段落顺序时,还要读取完整的 document.text。打印成功不代表解析质量已经合格。

如果换成自己的文件,保留这一步检查。扫描页没有提取出文本时,先更换解析方式,不要把空字符串继续交给分块器。

选读:文件多起来后,用 SimpleDirectoryReader 批量加载

SimpleDirectoryReader 可以遍历目录,并按扩展名选择 Reader。下面是一个独立的批量加载示意,不加入本篇主脚本:

1
2
3
4
5
6
7
from llama_index.core import SimpleDirectoryReader

documents = SimpleDirectoryReader(
input_dir="data",
required_exts=[".pdf", ".md"],
recursive=True,
).load_data()

返回值仍是 Document 列表。recursive=True 才会进入子目录;不同格式的默认 Reader 可能改变文本组织方式,仍应检查内容和元数据。本文显式读取 Markdown,是为了保留原始标题与代码围栏,便于观察后面的标题切分。SimpleDirectoryReader 官方说明

4. 分块时,到底在选择什么

分块要同时考虑长度和边界。长度影响一个块装多少内容;边界决定哪些内容应当一起出现。

例如,资料中写着:

1
签收后七天内可以提交退款申请。定制商品不适用无理由退款。

如果按固定字符数从中间截断,可能得到一个只谈申请期限的块,另一个块才有例外条件。即使切在句号后,句子完整了,也未必保留了回答问题所需的全部条件。因此,检查分块时要带着问题读,不能只看每块是否低于长度限制。

常见策略怎样选

策略 怎样决定边界 适合的起点与局限
固定字符或 token 长度 达到给定长度就切 容易建立基线,但可能截断句子、代码和表格;先确认长度单位
按段落、句子逐级切分 优先保留自然边界,过长时继续拆小 适合普通正文;一个句子很长时仍可能被拆开
按标题或文档元素切分 先分章节、段落、表格,再限制长度 适合结构清楚的 Markdown 或解析后的文档;单个章节仍可能过长
语义分块 用相邻句子的向量相似度辅助寻找主题变化 可作为后续对照,需要嵌入模型与阈值调试;不必作为本篇起点

第 5 节将实现“Markdown 先按标题,过长章节再按句子切;PDF 先保留页边界,再按句子切”的基线。这里先理解负责长度切分的 SentenceSplitter:它会优先考虑段落、句子,必要时再使用更细的分隔方式;它不能保证每块都是完整章节,也不是调用大模型理解全文后再切。Node Parser 官方说明

chunk_size 与 chunk_overlap

第 5 节将使用 chunk_size=256、chunk_overlap=32。它们是便于在小样本上观察行为的起始参数,没有“所有文档都适用”的含义。

  • chunk_size:切分器使用的块大小预算。SentenceSplitter 按 token 计量,token 是分词器切出来的单位,不等于汉字数、单词数或 Python 的 len(text)。
  • chunk_overlap:希望在相邻块之间保留的尾部重叠预算,单位也为 token。重复一部分上下文,可以缓解信息恰好落在边界附近的问题,同时会增加重复内容。

下面只用字母代表小片段,演示重叠的含义,不是程序的实测输出:

1
2
3
4
原文:A B C D E F

无重叠:块 1 = A B C 块 2 = D E F
有重叠:块 1 = A B C 块 2 = C D E 块 3 = E F

在 SentenceSplitter 中,重叠指的是对同一段输入文本切分时,让后一个块保留前一个块的部分尾部内容。重叠按已切出的句子或更小片段组织,所以配置 32 不代表每对相邻块恰好重复 32 token。某个完整片段放不进重叠预算时,实际重叠可以更少,甚至为零。

块小,更容易聚焦局部,也更容易缺少条件;块大,保留的上下文多,也可能混入无关主题。 比如问题是“定制商品能无理由退款吗”,至少要保住“定制商品”和“不适用无理由退款”的关系;问题是“整个退款流程是什么”,则可能需要后续检索多个块共同作答。

这里的 token 计数采用示例环境的 LlamaIndex 分词器。之后接入具体 Embedding 模型时,还应使用那个模型的 tokenizer 检查实际输入长度,不能把这里的 256 直接当成任何模型都接受的 256 token。

5. 把标题和页码带进每个块

第二段:先分章节,再限制长度

继续编写 prepare_chunks.py。前面的 md_document 仍包含整篇 Markdown;现在才由 MarkdownNodeParser 按标题将它拆成多个 TextNode,用 sections 保存这个列表。为了让长章节切分后的每个子块都知道当前章节名,本例再补充一个 section_title 字段。

1
2
3
4
5
6
7
8
9
10
11
12
markdown_parser = MarkdownNodeParser()
sections = markdown_parser.get_nodes_from_documents([md_document])

for section in sections:
first_line = section.text.splitlines()[0]
section.metadata["section_title"] = first_line.lstrip("# ").strip()
print("MD", section.metadata["header_path"], section.metadata["section_title"])

splitter = SentenceSplitter(chunk_size=256, chunk_overlap=32)
md_nodes = splitter.get_nodes_from_documents(sections)
pdf_nodes = splitter.get_nodes_from_documents(pdf_documents)
nodes = md_nodes + pdf_nodes

Markdown 在这里经过两次切分:

  1. MarkdownNodeParser 利用 #、## 等标题,把一个 Document 拆成多个章节节点,存入 sections。这个步骤保留结构,不负责把每个章节都压到 256 token 内。
  2. SentenceSplitter.get_nodes_from_documents(sections) 分别处理列表中的每个章节节点,将过长的章节切小,再汇总为 md_nodes。它不会先把 sections 拼回一篇完整文章。

因此,chunk_overlap=32 只作用于同一个章节节点切出的相邻块。例如,“申请条件”内部的两个块可以保留重叠内容,但不会自动把该章节的结尾带到“退款到账”的开头。这里的章节边界是第一步按标题切分后形成的;到第二步时,分别接受长度切分的已经是各个章节节点。

PDF 没有经过标题切分,SentenceSplitter 直接分别处理 pdf_documents 中的每页 Document,得到 pdf_nodes。同理,重叠只在同一页切出的相邻块之间生效,不会自动跨页。最后的 md_nodes + pdf_nodes 只是合并两个节点列表,没有拼接节点的正文。

在本例版本中,header_path 记录的是祖先标题路径。“申请条件”节点的 header_path 是 /退款说明/,当前标题 ## 申请条件 在节点正文里。后续子块不一定仍包含那一行,所以额外保存 section_title="申请条件" 有实际用途。MarkdownNodeParser 实现

first_line.lstrip("# ").strip() 是本例根据“每个章节以标题开头”的输入约定提取标题,不是通用 Markdown 解析算法。如果原文在第一个标题前有导语,这段导语也可能独立成块,此时应另外处理,不能把它的第一行硬当作标题。

示例文件还放了一段带 # 查询退款状态 注释的 Python 代码。标题解析器能识别本例使用的三反引号围栏,不会把围栏内的注释当作新章节。这只说明标题切分阶段正确识别了围栏;后续的 SentenceSplitter 不会将代码围栏、函数或表格视为必须完整保留的单元,仍可能在它们内部切分。

把代码或表格识别为独立元素,并不能防止它们再次被拆分。 如果要求整个元素保持完整,应让它绕过 SentenceSplitter,直接创建独立的 TextNode,并保留来源信息。同时,要用后续 Embedding 模型的分词器检查实际输入长度,包括会拼入输入的元数据,确认没有超过模型限制。

如果一个元素本身超过长度限制,就需要进一步处理:代码可优先按类、函数等结构边界拆分,表格可按行组拆分并保留表头和单位;单个函数或行组仍过长时,还需继续细分。处理后的片段应直接创建节点,避免再次经过通用文本切分而破坏已选好的边界。本篇示例仍将整个章节交给 SentenceSplitter,没有实现这种按内容类型分别处理的流程,不能据此保证任意长代码或表格都完整保留。

PDF 逐页切分的好处是页码容易对应,代价是跨页段落被分开了。如果原文的一条规则从上一页延续到下一页,应先根据结构合并相关内容,再记录页码范围;不能期待 chunk_overlap 自动补回另一页的句子。

第三段:导出,打开看一遍

最后把节点正文与元数据写成 JSONL。JSONL 文件每行是一个完整的 JSON 对象,便于逐块检查。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
with Path("chunks.jsonl").open("w", encoding="utf-8") as output:
for node in nodes:
record = {
"id": node.node_id,
"text": node.text,
"metadata": node.metadata,
"ref_doc_id": node.ref_doc_id,
}
output.write(json.dumps(record, ensure_ascii=False) + "\n")

print(f"Markdown: {len(sections)} 个章节 → {len(md_nodes)} 个块")
print(f"PDF: {len(pdf_documents)} 页 → {len(pdf_nodes)} 个块")
print(f"已写入 chunks.jsonl,共 {len(nodes)} 行")
print("首块:", nodes[0].metadata, nodes[0].ref_doc_id)

node_id 标识当前块,ref_doc_id 关联来源 Document。本例已核对:Markdown 子块的 ref_doc_id 为 refund-md,PDF 子块分别关联 policy-pdf-page-1 或 policy-pdf-page-2。节点自身的 ID 默认自动生成,即使文本相同,每次运行得到的 ID 也可能不同。

chunks.jsonl 保存本次生成的文本块与来源信息,供检查和后续向量化使用。代码中的 open("w", ...) 使用覆盖写入模式,因此每次运行都会重新写入文件。到这里完成的是文本块的导出,后续的向量检索还需要完成向量化和索引构建。

在解压目录执行:

1
python prepare_chunks.py

Python 3.12.7、前述依赖版本下,示例文件的实测输出末尾为:

1
2
3
4
Markdown: 4 个章节 → 5 个块
PDF: 2 页 → 4 个块
已写入 chunks.jsonl,共 9 行
首块: {'source': 'refund.md', 'header_path': '/', 'section_title': '退款说明'} refund-md

这里的“4 个章节”是解析器得到的四个部分:根标题下的说明,以及“申请条件”“退款到账”“查询示例”。其中“申请条件”继续切成两个块,其余部分各一个块。

打开 chunks.jsonl,可以在“申请条件”的两个块里都找到 source、header_path 和 section_title;第二个块虽然不再以 ## 申请条件 开头,仍能确定所属章节。两个块都出现了“消费者应保存沟通记录和物流单号,以便查询处理进度。”,这是这次切分实际保留的重叠内容。

PDF 的块则保留 page_number 和 page_label。提取结果中仍能看到 PDF 排版带来的换行,本例没有自动消除这些换行。替换成自己的资料后,应根据原页检查是否需要合并行,避免误删有意义的段落边界。

为什么正文常常没有 256 token

除了句子边界,元数据也影响可用长度。SentenceSplitter.get_nodes_from_documents() 会考虑节点的元数据文本,并为其预留 token 预算;元数据越长,留给正文的空间可能越少。元数据本身超过预算时,还可能抛出长度错误。SentenceSplitter 实现

因此,不要把整段摘要、整份目录都塞进每个块的元数据里,再困惑为什么正文变得很短。本例只保存简短的来源与定位字段。

还要区分“保存了元数据”和“元数据会不会进入模型输入”。LlamaIndex 默认可将元数据拼入供 Embedding 和语言模型使用的文本,node.text 只展示正文。后续向量化时,应检查 get_content(metadata_mode=MetadataMode.EMBED) 的结果;需要保留但不参与向量化的字段,可以用 excluded_embed_metadata_keys 配置。元数据定制说明

6. 改参数,观察块数和重复内容

为了单独观察长度与重叠,下面的 compare_chunks.py 暂时绕过标题切分和元数据,对同一个 refund.md 原文直接调用 split_text()。返回值是字符串列表,不是 Node 列表。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
from pathlib import Path
from llama_index.core.node_parser import SentenceSplitter
from llama_index.core.utils import get_tokenizer

text = Path("data/refund.md").read_text(encoding="utf-8")
tokenizer = get_tokenizer()
print("原文字符数:", len(text))
print("原文 token 数:", len(tokenizer(text)))

for size, overlap in [(128, 0), (128, 32), (256, 0), (256, 32)]:
splitter = SentenceSplitter(chunk_size=size, chunk_overlap=overlap)
chunks = splitter.split_text(text)
token_lengths = []
for chunk in chunks:
token_lengths.append(len(tokenizer(chunk)))
total_tokens = sum(token_lengths)
print(size, overlap, len(chunks), token_lengths, total_tokens)

执行 python compare_chunks.py。同一环境、同一份示例文件的实测结果如下,原文为 772 个字符、680 token:

chunk_size chunk_overlap 块数 各块正文 token 数 正文 token 总数
128 0 6 109、125、108、100、114、124 680
128 32 8 109、102、80、108、101、103、108、124 835
256 0 3 234、238、208 680
256 32 3 234、238、238 710

这个表能说明两件具体的事。保持大小为 128 时,增加重叠使块数从 6 变成 8,总正文量也增加了;大小为 256 时,增加重叠没有改变块数,却仍然增加了正文量。

表中的“正文 token 总数”是用本例分词器对每个块分别计数,再将结果相加。它与原文 token 数的差值表示分块后的计数增量,不能仅凭这个差值确定有多少 token 来自重叠文字,因为同一段文字整体分词,与拆开后分别分词,得到的 token 总数可能不同。

例如,用本例同一环境的分词器实测,hello 是 1 token,hel 和 lo 也各是 1 token。手动将 hello 拆成两段,结果如下:

1
2
3
4
5
原文:hello                  → 1 token

块 1:hel → 1 token
块 2:lo → 1 token
分块后合计: 2 token

这里没有重复任何字符,总数却增加了 1 token。原因是分词器能将完整的 hello 编成一个 token;分别处理 hel 和 lo 时,只能各自编码。这个例子手动选择切分位置,用来说明计数原理,不代表 SentenceSplitter 会这样切分 hello。

因此,表中的 835 − 680 = 155 表示:按本例分词器计数,分别处理这些块的正文,比处理原文多了 155 token。这个增量可能同时受到重叠文字和切分边界的影响,不能直接称为“重复了 155 token”。

这些结果没有证明哪组参数检索效果更好。本篇没有运行向量检索,表里也没有检索准确率。更有用的下一步是打开每块正文,检查“定制商品的例外条件”“到账时间的起点”等内容是否仍然完整。可以在内层循环加入 print(repr(chunk)),同时观察真实边界和换行。

实际调整时,一次只改一个变量:固定标题处理方式后再改 chunk_size,固定大小后再改 chunk_overlap。如果正文缺失或顺序错了,回到加载步骤;如果只是一个完整条件被分到两块,再检查切分边界、大小与重叠。

7. 普通提取不够用时,怎样接入解析工具

前面的练习适合排版简单、有文字层的 PDF。遇到扫描页、复杂表格或双栏论文,可以选择或编写调用以下工具的 Reader,将解析结果整理成 Document;也可以自己调用工具,手动创建 Document,再执行分块。下面的 Docling 示例采用后一种方式。三者是可选择的解析方式,不需要在同一个练习里依次安装。

工具 主要输出 本篇中适合解决的问题 使用前要注意
Unstructured Title、NarrativeText、Table 等文档元素及元数据 统一处理 PDF、Markdown 等格式,按元素类型组织内容 PDF 的 fast、ocr_only、hi_res 采用不同处理路线;OCR 和版面推理需要额外依赖
MinerU Markdown、结构化结果,具体取决于使用入口 处理 PDF 中的扫描文字、表格、公式和复杂版面 模型与硬件要求随处理层级变化,安装时按当前版本文档选择运行方式
Docling 统一的 DoclingDocument,可导出 Markdown、JSON 解析多种格式,保留文档结构,再接入下游处理 默认首次使用可能下载模型;导出纯 Markdown 后仍需处理来源信息映射

这张表依据官方文档整理,三款工具未在本文环境中进行解析实测或准确率比较。可以根据手头文件暴露的问题选择一种尝试,再对照原页检查结果。

Unstructured 的 partition 先得到文档元素,chunking 再组合元素;单个元素过长时才继续做文本切分。它的 max_characters、overlap 使用字符计量,不能直接照搬本篇以 token 为单位的参数。Unstructured 分块说明

无论选择哪种工具,都先比较“原始页面”和“解析后的内容”。OCR 识别出文字后,仍要检查“七天”有没有读错,否定词有没有漏掉;恢复了表格外观后,还要检查每行是否对应正确的表头。

选读:Docling 转 Markdown 后,如何交给 LlamaIndex

下面只演示替换加载步骤的接口衔接,未实测,不属于示例包的运行依赖。需要另行安装 Docling,并具备所选解析流程要求的模型、网络或本地模型文件条件。接口依据 Docling 官方 Python 示例。

1
2
3
4
5
6
7
8
9
10
11
from docling.document_converter import DocumentConverter
from llama_index.core import Document

converter = DocumentConverter()
result = converter.convert("data/policy.pdf")
markdown_text = result.document.export_to_markdown()

document = Document(
text=markdown_text,
metadata={"source": "policy.pdf", "parser": "docling"},
)

convert() 返回转换结果,其中的 result.document 是 Docling 文档对象;export_to_markdown() 得到字符串,最后才包装成 LlamaIndex Document。此后可以使用前面介绍的标题与长度切分。

这段代码把整份 PDF 导出的 Markdown 放进一个 Document,填写的元数据只有 source 和 parser。它记录了文字来自哪个文件,但没有记录每段文字来自第几页。 后续分块可以继承这些已填写的字段,分块器不会根据句子内容自动补出原始页码。

假设另一份两页 PDF 包含下面两句话,且各自切成一个块。下表演示希望保留的对应关系,不是上述代码的实际输出:

原始位置 文本块 该块应记录的页码
第 1 页 签收后七天内可以申请退款。 page_number: 1
第 2 页 退款通常需要三个工作日到账。 page_number: 2

按上面的代码处理,这两个块的来源元数据都只包含文件名和解析器名称。如果直接给整份 Document 加上 page_number=1,两个块都会继承这个值,第二页的内容就会被错标成第一页。

要得到表中的页码对应关系,需要读取 Docling 结构化结果中相应文档元素的来源信息,在创建或切分 Document、Node 时,保留“这段文字来自哪些页”的对应关系,并将页码写入相应节点的元数据。这里的 page_number 是自行约定的字段,上述示例尚未实现这一步;若还要定位到页面上的具体区域,则需同时保留相应的坐标信息。DoclingDocument 结构说明

本段 Docling 示例在加载阶段将整份 PDF 的 Markdown 放进一个 Document,其中已经包含多页内容。后续按标题和长度分块时,如果切分边界没有落在原来的换页位置,一个最终文本块就可能同时包含上一页末尾和下一页开头的文字,此时应记录该块实际涉及的页码。跨页块来自对已有多页文本的切分,SentenceSplitter 没有主动合并两个页面对象。前面的 PDFReader(return_full_document=False) 示例则每页创建一个 Document,并分别切分,因此那段代码不会产生跨页块。

8. 用几个问题检查切分结果

完成练习后,先不接大模型,直接打开 chunks.jsonl,带着下面的问题检查内容:

问题 应在块中检查的内容
定制商品能无理由退款吗? “定制商品”与“不适用无理由退款”是否一起保留,有没有丢失否定词
退款什么时候到账? 是否同时保留发起退款的前提、三个工作日、节假日顺延等条件
Python 注释有没有变成文章标题? # 查询退款状态 是否仍在代码围栏内,而没有生成一个新章节
这段说明来自哪里? Markdown 能否定位到文件与章节,PDF 能否定位到文件与原页

检查通过,说明这些样本中的必要文字和来源信息保留了下来;它还不能证明将来的检索器一定能找到正确块。检索效果需要在接入 Embedding 和存储后,使用实际问题继续验证。

接下来可以把示例中的一个文件换成自己的资料,对照原文件检查提取文本,再查看块边界。根据问题出现的阶段排查:

  1. 刚提取出的文本就缺字、乱码或顺序错误,先检查解析工具及其配置。 例如,扫描页可能需要 OCR,双栏内容错序可能需要支持版面分析的解析方式。
  2. 提取文本夹杂重复页眉、页脚,或一句话被排版换行打断,检查文本清洗规则。 这里的“清洗”指提取后、分块前的文本整理,例如删除确认无用的页眉页脚、合并同一句中的排版断行;不能直接删除所有换行,以免破坏段落、列表、代码或表格结构。本文主示例没有单独实现这一步。
  3. 分块前的文字和结构正确,但分块后完整条件被切开,检查分块方式。 对照原文查看切分边界,再判断是否需要调整块大小、重叠,或对代码、表格和跨页内容单独处理。

保留确认过的文本块和来源信息,就有了下一步“向量化与存储”的输入。