做文档知识库或者 RAG 类的项目最容易让人把信心耗光的环节不是选模型不是调 Prompt而是数据怎么进来、怎么被切碎。在这套体系里,文档解析和切片——也就是把 PDF、Word、HTML 这些非结构化文件先变成干净的文本再切成一块块能够被向量检索的“最小信息单元”——是真正决定整个系统成色的地基。地基如果打歪了后面不管用什么向量库、什么重排序模型结果都是一样的查不到、答不准、越修越乱。这篇是文档工作流系列的第二篇我会把解析和切片这两步拆开来讲包括为什么结构化解析能救你一命Python 切片思路如何迁移到文本分块上以及我实际跑过多个项目后总结出来的坑。1. 为什么说解析和切片是整套系统的地基先说一个常识大模型知识库的本质不是让模型“记住”你的文档而是把文档切成小段后灌进向量库每次提问时检索出最相关的几段再交给大模型做归纳和理解。这个链路里,模型本身不是你内容质量的救世主,它只能回答“检索到的内容里有什么”。如果解析阶段把段落顺序打乱、表格拆散、页眉页脚混进正文或者切片阶段把一句话从中间硬切两半那么索引里存的就是一堆语义残缺的碎片。检索时看着相似度挺高拉回来一看文字前言不搭后语模型的输出自然也是胡言乱语。我见过不少团队在这儿反复折腾——换大模型、调 Prompt、换向量化模型最后发现根子还是原始文本没处理好。1.1 解析和切片在整条流水线里的位置一套标准的文档处理流程大概是这样的原始文件进来先做格式识别和内容抽取再经过清洗和结构化整理然后根据语义边界切成若干块每一块配上页码、章节、来源等元数据最后送进嵌入模型变成向量写入向量库。解析决定了你能拿到什么切片决定了你存进去的是什么。说它们决定检索上限并不过分。解析做得好哪怕切片策略保守一点结果往往也还行解析稀烂切得再精细垃圾进垃圾出只是把垃圾切得更整齐罢了。另一个容易被忽略的点是元数据。解析阶段顺手把标题层级、页码、表格位置、生成时间这些信息保留下来等于给每个切片后续的筛选和溯源留了后路。很多项目初期不觉得元数据有用等到要按来源过滤、按章节定位、或者给回答做原文脚注时才后悔没留。1.2 三种典型场景对解析和切片的要求完全不同不同场景对解析和切片的要求差得很远我先列三个最常见的方向方便你对号入座。第一类是企业内部问答机器人输入多是制度文件、操作手册、产品文档。这类场景最看重标题层级和语义完整性切片适合按章节或小节走保持父子结构否则用户问“请假流程里需要几步”时模型只检索到一小段细节回答就没有上下文。第二类是合同审查和条款比对输入多是 PDF 扫描件或 Word 合同。核心难点在表格和条款编号签章页、页脚、附件的干扰也很常见。这种场景下解析必须保留表格结构和条款序号切片粒度反而可以小一些按“条款”切往往比按字符切靠谱得多。第三类是研报和技术文档的知识挖掘输入常有图表混排、多栏排版。解析时必须处理版式顺序切片既要避免切断图表标题和正文内容的关联也要保留统计数字所在的上下文。这类材料最考验版面分析能力纯文本抽提取容易丢信息。2. 文档解析先把非结构化数据变成结构化文本文档解析的目标从来不是“把字提出来”这么简单而是把 PDF 里的坐标、字体、表格线、图片说明这些视觉信息转译成有顺序、有层级、可检索的文本结构。这个过程在行业内通常叫文档结构化解析也叫版面分析。它和“从 PDF 里复制一段文字”有本质区别——复制出来的文字往往丢失阅读顺序多栏文档更是惨不忍睹。2.1 “结构化解析”到底在解析什么结构化解析要抓住的信息包括四层物理层是页面上的坐标位置、字体大小、颜色逻辑层是标题、正文、段落、列表、表格、页眉页脚语义层是章节归属、条款逻辑、图文关系还有一层是阅读顺序也就是同一页里多栏内容谁先谁后跨页段落怎么衔接。举个例子一份双栏排版的行业报告如果用顺序抽取很可能把右栏第一行接到左栏第二行下面整段文字完全错乱。正确做法是按坐标聚簇识别栏目边界再按从上到下、从左到右的顺序重组文本。市面上成熟一点的解析服务会调用版面分析模型直接输出块级结构但自己动手时也可以用 PyMuPDF、pdfplumber 这类工具配合坐标排序做基础处理。2.2 常见格式与工具选型不同格式的解析难度差异极大先给一张工具选型表后面再展开讲文件类型推荐解析方式工具举例主要风险文本型 PDF坐标块抽取 版面排序PyMuPDF、pdfplumber、pdfminer.six多栏错序、表格断裂扫描件 PDFOCR/视觉模型PaddleOCR、RapidOCR、商业解析服务识别错字、表格错乱WorddocxXML 结构直接解析python-docx、docx2txt样式嵌套、批注混入HTML/网页DOM 解析 正文提取BeautifulSoup、Readability导航噪音、评论混入Markdown/纯文本正则 标题正则化原生处理表格语法变形实战里 PDF 占比最高也是最难搞的。文本型 PDF 优先考虑 PyMuPDF它速度快能拿到块级坐标还带简单的表格识别功能需要精确表格时再用 pdfplumber 兜底。扫描型 PDF 的问题不在“文字识别”本身而是版面还原——OCR 跑完之后还得做坐标归类否则表格线、标题、正文全都平铺成一段文字结构全丢。DOCX 反而简单python-docx 可以直接读段落和表格对象结构天然存在。HTML 要注意先用 Readability 一类工具把正文主体提取出来再用 BeautifulSoup 按标题标签做层级划分不然导航栏和评论区的文字会污染语料。2.3 表格与多栏布局不能丢表格是结构化解析里翻车率最高的一块。表格信息密度高、结构敏感切成文本后如果丢失行列关系语义会直接崩掉。比如产品参数表里“电压220V、功率1500W”这种键值对平铺成纯文本后机器还能勉强理解但那种多行多列的复杂表一旦行列错位所有数字就全对不上号了。我自己的处理思路是优先把表格转成 Markdown 表格语法保留表头和行列对应关系而不是直接拼接成纯文本。用 pdfplumber 提取表格后可以自己拼一个简单的 Markdown 表格串再用“表格开始”“表格结束”这样的特殊标记包起来。这样切分时能识别表格块必要时整表独立成块避免表格被拦腰切断。很多现成解析服务会直接返回表格的 HTML 或 Markdown也是同一个道理。3. 切片策略先搞懂“切”再写代码切片这个说法在 Python 里本来就是数组和列表的一种操作方式。写代码的人早就熟悉list[start:end:step]这种写法——从一段序列里按位置截取片段。文本分块本质上干的是同样的事把一长串字符序列按某种规则截成一段段区间。区别在于数组切片切出来的是元素序列想怎么分都行文本切片要切完还能让人读懂、让语义不散那就得先用一套“窗口思维”把切法想清楚。3.1 从 Python 列表切片说起先花两分钟把 Python 切片的语法理一遍因为后面所有分块代码都建立在这套索引机制上。列表切片的基本形式是seq[start:stop:step]start 是起始下标stop 是结束下标(不含)step 是步长。省略 start 表示从头开始省略 stop 表示一直到尾step 为负数时表示反向截取。字符串本质上也是序列所以text[100:300]可以直接取出第 100 到第 299 个字符——这就是最原始的字符级切片。分块器里用到最多的其实是两层普通切片text[start:end]负责取窗口遍历时用range(0, len(text), step)这类逻辑控制窗口滑动。很多分块算法写到最后本质就是维护两个下标指针在大文本上滑出一个一个窗口。用 Python 写滑动窗口时最重要的两个边界问题一是 stop 不能越界二是重叠切分时 start 的推进逻辑要对否则要么少切一段要么重复切出大量空文本。3.2 常用的分块流派与适用场景带着切片的概念再来看文本分块思路就会清楚很多。目前主流的分块流派大致有四类固定长度切片是最直观的一种按字符数或 token 数硬切。它实现简单、速度飞快但完全不感知语义边界经常把一句话从中间剪断导致检索结果读不通。适合对检索精度要求不高、只想快速跑通 demo 的场景。按段落或标题结构切是工程上最常用的方案。先按 Markdown 标题、HTML 的 h1/h2 或 PDF 的章节标记把文档拆成“段落块”再对超长段落做二次细分。这样切出来的块天然有上下文边界检索时还能带上父级标题的信息效果明显好于硬切。按句子和语义边界切可以看作前两种的折中。先用句号、问号、感叹号把文本切成句子列表再把相邻句子合并进一个块直到接近预设长度。这个思路能避免切断句子但对超长列表和复杂从句仍不够保险。基于向量相似度的语义切块属于进阶玩法。先把文本切成小句计算相邻句子的 embedding 相似度相似度低的地方就是语义边界从那里切开。效果理论上最好但计算成本高、实现复杂适合段落之间主题跳变明显的材料。3.3 重叠、节流与 token 预算切片时最常被忽略的参数是重叠overlap。如果没有重叠跨越切片边界的语义信息会被硬生生切断比如一个问题的背景在上一块结尾关键词却在下一块开头检索时两块都匹配不完整。设置重叠窗口后前一块的尾部会和后一块的头部重复相当于给检索加了一点冗余保险。重叠率一般控制在 10%~20% 之间太高会浪费存储和计算资源太低兜不住语义衔接。token 预算则要结合嵌入模型的上限来定。现在的向量模型输入长度通常在 512 到 8192 token 之间。中文场景里一个字大概折算 0.6 到 1 个 token512 token 大概对应 500 到 800 个汉字所以很多项目把块大小设在 500~1000 字之间。这里有个经验宁可块小一点不要块大一点。块越大向量语义越分散检索精度越差块越小上下文越窄召回后还需要更多拼接。比较稳的做法是主块控制在 600~800 字重叠 100 字左右后续再按测试结果微调。4. 实操全流程一份合同文件从解析到切片理论说了不少直接上一套完整流程。我以一份 PDF 合同为例演示从解析到切片的关键代码和处理逻辑。先说明一下完整生产系统里会有更多细节但下面的骨架是我在多个项目里验证过的通用做法。4.1 解析层读取、清洗、抽取结构与表格第一段代码用 PyMuPDF 读取 PDF按坐标块抽取文本先按页保留再按块排序。这一步解决的是“把文字和排版顺序一起捞出来”。坐标块的好处是同一块的文本天然连贯跨块顺序可以通过 y 坐标和 x 坐标排序来还原。import fitz def extract_pdf_blocks(pdf_path): doc fitz.open(pdf_path) pages [] for page in doc: raw_blocks page.get_text(blocks) blocks [] for b in raw_blocks: x0, y0, x1, y1, text, block_no, block_type b if block_type 1: # 图片块跳过 continue text .join(text.split()) if text: blocks.append((x0, y0, x1, y1, text, block_no)) # 按 y 坐标排序保持同一行阅读顺序 blocks.sort(keylambda b: (round(b[1]), b[0])) pages.append(blocks) return pages提取出来的文本块还是散的下一步做清洗。常见清洗规则包括剔除页眉页脚通过正则匹配页码和固定文本、压缩多余空白、去掉制表符和断行符。页面底部的页码和页眉导航信息必须处理否则每一页都会给语料注入相同噪音切片后这些噪音会反复出现在多个块里检索时严重干扰。表格部分用 pdfplumber 单独处理。提取出表格后转成 Markdown 表格字符串同时用特殊标记包裹方便后续切片时识别。import pdfplumber def extract_table_markdown(pdf_path, page_index): with pdfplumber.open(pdf_path) as pdf: page pdf.pages[page_index] tables page.extract_tables() md_lines [] for table in tables: if not table: continue header table[0] md_lines.append(| | .join(str(c).replace(\n, ) if c else for c in header) |) md_lines.append(| |.join([---] * len(header)) |) for row in table[1:]: md_lines.append(| | .join(str(c).replace(\n, ) if c else for c in row) |) return \n.join(md_lines)这里专门用了一个函数处理表格而不是直接走文本抽取是因为表格如果以纯文本形式拼进正文行列关系就丢了。Markdown 表格格式虽然占用的字符多一点但结构信息完整后续切片时可以把整张表格当作一个不可分割的原子块。对于真正的扫描版 PDF这个环节要替换成 OCR 版面分析表格识别复杂度会再上一个台阶通常需要接入视觉模型或专门的文档解析服务不是简单调一个开源库就能搞定的。4.2 切片层按标题建树再用滑动窗口切段解析出的文本拿到手之后先做标题层级识别。如果来源是 Markdown 或 HTML标题标签是现成的如果是 PDF 里抽出来的纯文本可以用字体大小、加粗状态和“第X章”“X.”这类模式去猜标题。我通常会解析出一个多层结构文档、章、节、段落。切片时优先以“节”为基本单位这能最大程度保留语义完整性。def parse_headings(lines): tree [] current_h1 None current_h2 None for line in lines: stripped line.strip() if re.match(r^第.[章节], stripped) or re.match(r^\d\.\s, stripped): if stripped.startswith((1 , 一、)): ...这里需要注意标题识别的正则要根据你的文档类型反复迭代不可能一套规则通吃所有文件。工程上比较省力的做法是对接文档解析服务直接拿结构化输出自己写规则时优先用“字号/加粗/缩进”这些版式特征正则只能当辅助。对于已经按节拆好的文本我一般先判断长度。如果一节在 200 字以内直接整节作为一个切片如果超过 800 字就用带重叠的滑动窗口进一步细分。滑动窗口的代码可以复用前面说的 Python 切片思想def sliding_window_chunk(text, size600, overlap100): chunks [] start 0 text_len len(text) while start text_len: end min(start size, text_len) chunk text[start:end] chunks.append(chunk) if end text_len: break start end - overlap return chunks这段代码看着简单实际踩过不少坑。最典型的是 start 推进距离是end - overlap而不是end否则重叠等于没设另一个问题是如果文本里有换行符和标点硬切时会把句子切断。所以我一般在滑动窗口前先做一次句子边界对齐——找到距离 end 最近的句号或换行符把 end 挪到那里再生成切片。4.3 元数据与原始定位给每个切片加上通行证切片生成之后如果直接拿去向量化后面排查问题时你一定会发疯。我给每个切片额外挂一套元数据用字典结构保存最后再转成列表切片统一管理def build_chunk_records(text, source, title, page, section, chunker): raw_chunks chunker(text) records [] for idx, chunk in enumerate(raw_chunks): records.append({ id: f{source}-{page}-{section}-{idx}, text: chunk, source: source, title: title, page: page, section: section, chunk_index: idx, char_len: len(chunk), }) return records这里我把每个切片都跟来源文件、页码、章节名、块内序号对应起来。后续不管是做按来源过滤、去重、人工质检还是定位线上坏例都能直接回源到原始文档。有些人觉得这是多此一举但等到系统上线后用户反馈“答案引用的原文位置不对”时这套元数据就是你排查的抓手。5. 常见问题与排查技巧实录做文档解析和切片翻车是常态关键在于能不能快速定位问题出在哪个环节。我把这些年遇到的高频问题整理成速查表再讲几个排查思路。5.1 高频翻车现场现象根因处理办法检索结果里反复出现页眉页脚文字解析时没清理页眉页脚用正则剔除页码、导航文本做一次全局噪音清洗表格数据散落各处数字对不上表格被当作普通文本切碎表格单独抽取并转 Markdown切片时整表成块用户问题明明提到某关键词检索却找不到切片把关键词所在句子切断了引入重叠切片并在句子边界处对齐窗口切片数量爆炸向量库很大没有按标题分层全局硬切先按标题结构拆再对超长节做滑动窗口扫描 PDF 识别结果惨不忍睹没有 OCR 或 OCR 后版式丢失接入 OCR 并做版面分析保留标题与表格结构切片内容很多是乱码或空格PDF 有自定义编码或字体问题换 pdfplumber 或其他解析引擎必要时人工抽样检查5.2 排查思路回源、还原、验证排查的第一步永远是回源。别看着向量库里某条文本干瞪眼直接翻原始 PDF 第几页确认原文长什么样。如果原文正常、切片错乱问题出在解析或切片如果连原文都是乱的那是文件本身或 OCR 的问题。我经常拿一批典型文档做“黄金语料”也就是人工核过答案的样本每次改动解析或切片规则都用这批样本回归能快速知道改动有没有引入新的坏例。第二步是还原结构。解析完后从解析结果里抽样打印几个页面肉眼对比原文。看标题层级在不在、列表缩进有没有、表格行列是否对齐、段落的阅读顺序对不对。这步不能用程序自动检查代替因为版式的坑往往只有人眼能看出来。第三步是验证切片的可读性。切片完成之后随机抽几十条切片打印出来看一眼是不是完整的句子、有没有孤立的数字、有没有从表格中间断开的残行。还可以做一个简单的链路测试拿一份文档人工想出 5 个问题再去检索看关键词落在哪些切片里这些切片是否足够回答用户问题。如果前三刀都切歪了说明问题已经在数据进库之前发生了这时候去调 embedding 模型、调重排序参数都是在给地基填土土填得再平地上还是歪的。最后再聊两句我的体会做到现在我最大的感触是解析规则一定要先定标准再写代码切片效果一定要靠肉眼抽查不能只信指标。先把你拥有的文档类型列出来明确哪些字段必须保留哪些噪音必须去掉哪些结构必须原样保存然后再动手写解析器。切片那边也一样不要觉得切得越小越灵活切太碎会让检索结果缺乏上下文切太整又会让向量语义模糊。我个人的操作习惯是每改一次解析或切片逻辑都把产物存一份纯文本快照放到一个临时目录里抽查。这个习惯救了我很多次很多问题不是在代码里看出来的是翻开切片文本一眼看出来的。这套环节稳定之后后面做 embedding、做重排序、做检索链路都会顺很多——地基稳了上层建筑才敢往上摞。