最近一直在搞知识库问答和文档智能处理和不少同行交流后发现一个几乎被所有人低估的环节文档解析与切片。很多人一上来就调大模型、调向量库结果召回效果一塌糊涂回头才意识到问题出在最前面——文档都没解析干净切片也切得乱七八糟。我经常打一个比方这就像盖房子打地基地基歪了后面装修再好看也是白搭。这篇就专门聊聊文档解析和切片这件事把里面容易踩的坑、背后的原理、可复现的实操方案一次讲清楚。这篇文章适合正在做知识库、RAG应用、AI文档处理的朋友尤其是被“召回不准”“上下文断裂”“表格读不出来”折腾过的人。即便你只是听说过“文档结构化解析”“python数组切片”这类词但还没系统理清它们和实际业务的关系这篇文章也能帮你把概念落地成能跑的流程。1. 文档解析先把“纸面世界”变成“机器世界”文档解析是整个流程的地基它的任务用一句话概括把PDF、Word、扫描件这类非结构化的文件变成结构清晰、机器可读的文本和元素。这里的“结构清晰”是重点不光是拿到一堆字符串而是要知道哪段是标题、哪段是正文、表格的边界在哪里、图片在哪个位置。如果没有这层结构后面切片时就会把标题和正文切开把表格的某一行单独拉出来把跨页的段落切得七零八落。这就导致向量化的文本失去语义完整性最后检索出来的内容自然没法看。很多人觉得解析就是“用pypdf把文本提取出来”实际上这远远不够。PDF里的文本有两种来源一种是数字原生的有文本层可以提取另一种是扫描件本质上是一堆图片必须做OCR。即便是数字原生的PDF文本也可能因为内容流组织混乱提取出来顺序不对。Word文档相对好一些但里面的表格、页眉页脚、分节符同样需要处理。所以解析这件事关键是选对工具并理解它的输出逻辑。实测下来我目前最推荐的解析工具是marker。这个开源项目的定位就是“高精度地PDF转Markdown”特别适合LLM场景。它做的不仅仅是提取文字而是把整篇文档转成结构化的Markdown格式标题用#标记表格转成真实的Markdown表格图片单独抽取出来段落顺序也能基本保持正确。marker采用深度学习模型识别版面区分标题、正文、表格、图片、公式等不同的区域然后按阅读顺序重组。效果好的时候一篇双栏论文也能正确还原成线性文本段落衔接自然。这一点非常关键因为向量化模型对句子边界和段落顺序很敏感marker的这一步处理直接提高了后面切片的准确率。那是不是所有场景都该用深度学习式的解析也不一定。对于纯文本PDF、代码仓库里的Markdown文件这类简单场景直接读取文本层即可没必要杀鸡用牛刀。但对于年报、论文、扫描合同这类复杂文档强烈建议上marker或类似的版面分析方案。这一点需要自己在项目启动前评估清楚你的文档复杂度属于哪一类能用多花10分钟换来更高召回率那就值得。1.1 结构化解析到底“结构化”了什么很多人在用marker的时候只把它当作一个“更好用的文本提取器”其实错过了它的核心价值。我们说的结构化至少包含四个层面逻辑结构标题层级、章节顺序、段落归属、列表关系。这是最重要的直接影响切片时是否把同一个语义块拆散。表格结构每个单元格的边界、行和列的对应关系、合并单元格的还原。marker会输出规范的Markdown表格后续如果要做表格问答可以直接解析这个表格结构。版面结构页眉页脚、页码、脚注、侧栏、多栏文本的阅读顺序。这一步很多PDF工具都做不好尤其是双栏论文普通提取会从左栏第一行直接跳到右栏第一行读起来完全错乱。非文本元素图片、公式、手写批注的位置和上下文。marker会把图片单独保存并在Markdown中嵌入图片路径或占位符方便后续做多模态检索。举一个我实际处理过的例子一份证券公司的研究报告双栏排版内嵌了大量图表标题层级混乱。用pypdf直接提取跑出来的文本里段落的顺序完全被打乱正文和表格内容混在一起。导入向量库后问“该报告对宏观经济的判断是什么”召回的片段里甚至出现了表格里的百分比和正文混在一起的乱码简直没法看。换成marker解析后输出是规范的Markdown再配合针对标题的切片策略问答质量和从前判若两样。这就是结构化的意义。1.2 解析工具选型marker之外还有什么如果你还没确定用什么工具我按场景整理了一张对比表方便你决策。工具适用场景优点不足marker复杂PDF、扫描件、论文、报告结构识别能力强输出Markdown支持表格、图片、公式精度高对显存有一定要求首次运行需要下载模型速度偏慢PyMuPDF (fitz)数字原生PDF需要快速提取速度快支持文本、图片、注释Python API友好无法处理扫描件版面分析能力弱pdfplumber需要精细提取表格、坐标信息表格提取精度高可精确控制区域大文件速度慢不输出结构语义PaddleOCR / Tesseract中文扫描件、图片型PDF中文识别效果好尤其PaddleOCR可配合版面分析需要额外做版面恢复工具链较长unstructured多种格式统一入口PDF、Word、HTML接口统一可配合LangChain使用底层依赖多复杂版面容易翻车我的个人建议是如果项目刚起步文档种类又比较杂直接上marker作为主干再用PyMuPDF做快速预检和兜底。这样既能在高难度文档上稳住精度又不会因为marker处理太慢而影响整体流程。Word文档则可以直接用python-docx读取段落和表格不需要经过PDF中转。另外无论选哪个工具都要记住一个原则宁可多花时间在解析前观察文档也不要解析完再返工。盲目的批量解析十个不同版本的报表最后能用的可能只有三个那就彻底白干了。建议先抽样三到五份代表文档人工检查解析输出的Markdown是否保留了标题层级、表格是否完整、页眉页脚是否被剔除。检查通过了再全量跑能省下后面的大量调试时间。2. 切片为什么不能“一刀切”文档解析完成后紧接着就是切片。切片是把长文档切成若干段落的过程目的很明确喂给向量模型时每个片段是一个整体语义单元检索时命中的片段要尽可能覆盖到用户问题的上下文。这个概念理解起来很简单但做好的门槛很高。先做个类比。python数组切片比如a [1,2,3,4,5]a[1:3]取的是索引1到2之间的元素这是程序员都懂的基础操作。但文档切片不同面对的是一段连续的、有语境的文本边界切在哪个词上会直接影响检索效果。如果像数组切片一样按固定长度硬切比如20个字符一刀很可能把“虽然今天天气不错但是明天会下雨”切成“虽然今天天气不错但”和“是明天会下雨”这样两个片段都丢失了完整的转折语义。向量化之后这两个片段和“明天会下雨”这个完整问题之间的相似度都会降低导致检索不准确。所以文档切片本质上是“按语义边界做分割”。语义边界一般出现在段落结尾、标题切换、列表结束、表格整体等位置。怎么找到这些边界有很多种实现方式最基础的是按段落分割准确但粒度不统一进一步是按标题层级做分割适合结构清晰的文档再进阶是利用嵌入模型计算相邻句子或窗口的相似度在语义差异较大的地方断开还有一种是交给大模型判断是否该在这里截断。不同方式各有优劣但永远不会存在一个万能参数能解决所有问题。2.1 切片参数的底层逻辑chunk_size和overlap聊切片必然绕不开两个参数chunk_size和overlap。chunk_size决定每个切片的最大长度overlap决定相邻切片之间重叠多少。这两个参数为什么存在因为我们要在“上下文完整性”和“检索精准度”之间找个平衡。切片太短上下文不够比如一个切片只包含表格的表头缺少数据行的说明切片太长向量化时容易稀释核心语义而且超出向量模型的输入上限后还得二次截断反而更糟。overlap则用来缓解边界丢失问题把前一时段的结尾再带进下一段的开头确保一个连续的话题即使被切断也能在相邻的切片里找到“接续感”。那么这两个参数怎么定实践中有几个常见基准向量模型的输入上限是硬约束。OpenAI的text-embedding-3-small支持8192 tokens但很多国产模型只有512或1024 tokens。chunk_size不能超过这个上限一般建议取模型上限的50%到70%作为安全值。中文场景下用“字数”而非“tokens”来估算比较简单。毕竟多数切片器内置的是按字符切分。一个中文汉字约1到2个token所以如果你的模型上限是512 tokenschunk_size取256个字左右比较稳妥。overlap默认取chunk_size的10%到20%。如果两个切片之间有强依赖关系比如对话、连续的法条overlap可以提到20%以上甚至30%但不要超过50%否则多余的重叠会让向量库里面有大量冗余内容检索时相关性反而被稀释。有一类特殊场景表格。表格最好不要和其他文本混在一个切片里否则向量化时表格的二维信息会被压平语义严重丢失。更合理的做法是把表格整体视为一个独立切片或者把表格的行拆成带表头的键值对文本再作为单独切片。marker解析出的Markdown表格正好能支持这个需求。2.2 从“数组切片”到“语义切片”的思维升级很多开发者的第一次实操都是从“写一个Python切片函数”开始的。比如这样一行代码text 这是一个很长的文档内容…… chunks [text[i:i 200] for i in range(0, len(text), 200)]这就是典型的python数组切片思维把文本当成字符列表硬按索引切。这种方式在简单测试里能用但放到RAG项目里几乎必出问题句子被拦腰截断、段落被劈开、一个完整的标题和其正文被分到两个不同的chunk里。更要命的是这种硬切对中文极不友好一个语义单元经常在“的”“了”这类虚词附近被切断向量化后这个切片的主题一点都不明确。升级到语义切片后我们至少要做几件事先按段落把文本拆开每个段落是基础单元再根据段落长短动态合并太短的段落比如单个标题和相邻段落合并太长的段落超过chunk_size再按句子边界二次切分合并或切分时都要保留标题信息最好把标题作为前缀加到正文切片的前面如果文档有明确的Markdown标题层级可以优先按标题边界作为切片边界。这里要特别注意切片不是“切完就完”每个切片还需要附带元数据。比如来源文档名称、页码、章节路径、切片序号。这些元数据在后续做相关性重排序、引用溯源时非常重要。很多人忽略了这一点导致回答内容没有出处出了问题也没法追溯。用代码举个例子下面是一个基于LangChain的递归字符文本分割器from langchain.text_splitter import RecursiveCharacterTextSplitter text_splitter RecursiveCharacterTextSplitter( chunk_size300, chunk_overlap50, separators[\n\n, \n, 。, , , , , , ], ) chunks text_splitter.split_text(markdown_text)注意分隔符的优先级设置。它先按段落(\n\n)切再按换行切再按句号切。这样做的意图是优先保持语义完整性只有段落过长时才在标点处截断。这段代码看起来简单但里面隐含了最大努力原则——尽量不破坏语义边界。如果你是自己实现切片也非常推荐参照这个优先级来设计。还有更高级的方案比如通过embedding模型计算相邻句子的向量相似度在相似度低于某个阈值时断开。这种“语义切分”方式适合对话、文学类文本但计算成本略高。我自己的经验是对于排版规范的技术文档、法律文书、研究报告先用Markdown标题结构切分再用递归字符分割做兜底效果已经完全够用没有必要上太复杂的方案。3. 实操从原始文档到可用切片的完整流程理论讲了一堆现在把整个流程串起来给你一份可以照着跑的方案。下面的流程以一份论文PDF为例主要分为“环境准备”“解析”“切片”“清洗与产出”四步。3.1 环境准备与工具安装在开始之前先把需要的库装好。我建议用Python 3.10以上的版本并创建一个独立的虚拟环境避免依赖冲突。pip install marker-pdf pymupdf langchain-text-splittersmarker-pdf是marker在Python里的包名。安装后它会自动拉取模型权重第一次运行会慢一点。另外marker目前支持GPU加速如果你的机器有CUDA环境可以装torch的GPU版这样解析速度能快上数倍。没有GPU的话CPU也能跑就是慢很多一篇三四十页的PDF可能要几分钟。然后是数据准备。把待处理的文档放到一个文件夹里比如docs/raw/。注意看一下文件命名最好起个有规律的名字后面生成元数据时可以直接用文件名做来源标识。3.2 使用marker解析文档并检查输出解析代码很短下面这段就是完整流程from marker.converters.pdf import PdfConverter from marker.models import create_model_dict from marker.output import text_from_rendered converter PdfConverter( artifact_dictcreate_model_dict(), processor_list... # 默认配置即可 ) rendered converter(docs/raw/example.pdf) text, ext, images text_from_rendered(rendered) # 保存解析结果 with open(docs/parsed/example.md, w, encodingutf-8) as f: f.write(text) # 保存图片 import shutil shutil.copytree(images, docs/images/)核心就三行创建converter、传入PDF路径、得到输出。输出的text是Markdown格式的字符串images是一个临时目录里面存放提取出来的图片。如果你不想保存图片可以忽略images部分。拿到example.md后一定要打开检查三件事标题层级是否正确比如一级标题是不是#二级是不是##表格是否被正确转换为Markdown表格而不是拼接成一段乱文本阅读顺序是否连贯尤其双栏文档看看左栏到右栏的切换是否符合人的阅读习惯。如果检查发现marker跑出来的效果不好比如某个表格被拆开了可以尝试调整PdfConverter的processors参数开启或关闭某些后处理模块。另外marker也有批量处理命令marker_single docs/raw/example.pdf docs/parsed/ --output_format markdown批量的方式建议配合日志使用方便定位失败的文件。总而言之解析这一步的目标不是跑完脚本而是亲眼看到高质量的Markdown输出后再继续。3.3 切片方案设计与代码实现拿到Markdown之后开始切片。我一般推荐两种方案结合先按标题切再在超长标题块内部用递归字符切。这样既能保留章节结构又能控制切片长度。先看一个用标题切分的实现思路import re def split_by_heading(markdown_text): lines markdown_text.splitlines() chunks [] current_title 开头 current_lines [] for line in lines: if re.match(r^#{1,4}\s, line): # 碰到标题 chunks.append({title: current_title, content: \n.join(current_lines).strip()}) current_title line.strip().strip(#).strip() current_lines [] else: current_lines.append(line) chunks.append({title: current_title, content: \n.join(current_lines).strip()}) return chunks这里有个细节每碰到一个新标题就把之前累积的内容作为一个chunk并用当前标题作为元数据存下来。这样切出来的每个chunk开头都有一个明确的章节信息。但这样切大概率会出现超长或超短的情况所以还需要一个后处理函数把超长chunk按句子拆分把超短chunk比如只有标题没有正文合并到下一个chunk或前一个chunk。下面是我常用的后处理逻辑from langchain.text_splitter import RecursiveCharacterTextSplitter def normalize_chunk(chunk, max_len300, overlap50): content chunk[content] if len(content) max_len: return [chunk] splitter RecursiveCharacterTextSplitter( chunk_sizemax_len, chunk_overlapoverlap, separators[\n\n, \n, 。, , , ], ) parts splitter.split_text(content) result_chunks [] for i, part in enumerate(parts): if i 0: # 第一个子块带上标题 text f## {chunk[title]}\n{part} else: # 后续子块不带标题但保留标题引用 text f接 {chunk[title]}\n{part} result_chunks.append({ title: chunk[title], content: text, seq: i, }) return result_chunks这里的max_len取300是基于“中文embedding模型512上限”的一个保守值。实际项目中你完全可以根据模型调整。还有一点seq字段用来标记子块顺序方便最后还原完整的文档结构。把所有chunk再拼到一起最后输出成一个JSONL文件每一行是一个切片字段包括id、title、content、source、page、seq。后面不管接向量库还是做精排这些字段都用得上。3.4 切片完成后的质量自检切片跑完不要急着入库先做一轮自检。我常用的方法是随机抽十个chunk逐个检查下面几个问题这个chunk是否有明确主题如果一句话都说不清楚那就说明切得太碎。首尾是否完整有没有句子在中间断掉分段符后面是否跟了莫名其妙的半句话标题信息是否保留如果别人只看这个chunk能否知道它属于文档哪个章节是否有大量重复内容如果overlap设置过大相邻chunk会大量重叠这也是要调整的信号。还有一个快速检测办法把所有chunk按seq顺序拼接看看能否还原出接近原文的文本。如果拼接后大量内容断裂或重复说明切片参数不合理。我之前遇到过一种情况overlap设成80但chunk_size只有100结果下一块几乎一半是上一块的尾巴拼回去后重复文本一堆检索时同一个信息被命中好几次浪费向量额度还干扰排序。后来把overlap调成20就正常了。4. 常见问题与排查技巧这里把我实际踩过的坑和解决办法汇总一下做成一个速查表方便你遇到问题时直接查。现象可能原因排查方法解决方案解析后文本出现乱码或特殊符号PDF使用了非标准字体、编码映射问题抽取一小段原始PDF字符流检查字体编码改用marker的OCR模式或对扫描件做PaddleOCR表格内容缺失或错乱PDF表格无实线边框或技术扫描件对比marker输出和原始页面看表格是否有合并单元格针对表格区域单独用pdfplumber提取或将表格整体作为一个切片双栏文档阅读顺序错乱未启用版面分析检查是否用了marker普通的pypdf不会处理双栏强制使用marker并开启版面恢复不要用pypdf直接提取切片截断句子的情况太多分隔符优先级不合理打印切分结果中每一个chunk的结尾字符多数为句号则合适调整splitter的separators顺序把“。”放在更前面召回结果总是少了关键上下文overlap太小或chunk_size太小查看命中的相邻chunk看关键信息是否分布在两个chunk里适当增大chunk_overlap到20%或者扩大chunk_size同一片内容反复被检索到overlap太大或重复文档统计chunk间的重复率降低overlap增加去重逻辑向量化时超长被截断chunk_size过大查看embedding模型的输入限制将chunk_size限制在模型上限的70%以内切出的chunk空内容原文档本来就是空页或页眉页脚被误判为正文打印chunk的数量和长度分布解析后先过滤空行、页码页眉切片时跳过空chunk除了这张表我还想单独强调几个容易被忽略的坑。第一个是目录和页眉页脚的干扰。很多PDF解析出来后目录页会生成一大堆无用的章节文本页眉页脚也会混进正文。这些内容如果不提前清理切出来就会变成垃圾切片严重干扰检索。最简单的办法是在解析后用正则匹配页码、页眉以及“第X页共X页”这类模板批量剔除。还可以借助marker本身的版面信息它会在Markdown中把页眉页脚和正文分开处理但不够彻底仍然需要人工后处理。第二个是标题层级信息的保留。很多切片器会把Markdown的标题号也切掉导致每个chunk没有语义“锚点”。我建议在切片前就把标题提取出来作为每个子块的前缀。这会让向量化的文本结构更清晰。实测在相同参数下带标题前缀的chunk比不带标题前缀的chunk检索命中率能提升10%到15%。这个提升虽然不是特别夸张但对于RAG系统来说已经是很大的差距了。第三个是动态调整参数的问题。很多人喜欢把chunk_size设为固定值然后跑所有文档。但不同文档的段落长度差异巨大法律文件和营销软文的合理切片大小完全不是一个量级。更好的做法是先统计语料中段落长度的分布比如中位数、90分位数然后把chunk_size设置为略高于中位数的值再结合overlap去调节。下面分享一个统计分布的小工具代码from collections import Counter def get_len_distribution(chunks): lengths [len(c[content]) for c in chunks] lengths.sort() total len(lengths) median lengths[total // 2] p90 lengths[int(total * 0.9)] print(f总chunk数: {total}, 中位长度: {median}, P90长度: {p90}) return Counter(lengths)跑一次就能看到你的语料适合多大的chunk_size避免拍脑袋定参数。5. 进阶优化解析与切片的协同调优如果基础流程已经跑通你可能会发现自己生成的chunk量太大向量库爆满或者部分chunk质量还是低。这时就需要做协同调优。所谓协同调优就是把解析和切片放在同一个测试闭环里通过检索结果反向调整解析和切片参数。具体做法是先准备几十个有标准答案的测试问题然后建立一个简单的检索流程向量检索TopK不断调整解析方案和切片参数观察答案命中率的变化。比如你发现所有表格相关的问题都答不准那就要单独判断是表格解析的问题还是切片把表格和正文混在一起了。可以先修改解析环节把表格单独输出再修改切片逻辑让表格作为独立chunk进入向量库。反复几次后整个系统的表现会越来越稳。还有一个关键点切片数量和去重。向量库的规模直接影响检索速度和成本。每减少10%的低质量切片整个系统的性能都能提升一点。我通常会在切片后用simhash做一次粗粒度去重把内容重复率超过85%的chunk合并或删除。这能避免重复信息占据向量库空间也能防止检索结果被同一段文字刷屏。在做切片的时候不妨利用好文档本身的结构。marker输出的Markdown里包含标题层级这些标题本身就是天然的分组标志。沿着标题做切片就是利用了文档作者的信息组织逻辑这比任何启发式算法都稳妥。如果你处理的文档没有明确的标题再退回到基于段落和句子的递归切割。最后再说一下marker本身的一个小技巧它支持从Markdown反向生成其他格式比如JSON。你可以让marker输出带bbox边界框和块类型标注的JSON这对后续精细切片非常有用。如果你要做“按内容类型切片”比如只切表格、只切正文这个JSON格式就是你的利器。比如marker_single docs/raw/example.pdf docs/parsed/ --output_format json这个JSON会包含每个块的类型信息Title、Text、Table、Picture、Formula等。拿到这些块之后你可以根据类型定制切片策略比如表格块作为一个chunk连续多个图片块合并成一个chunk标题块和紧跟其后的正文块合并。这种精细化处理是提升RAG上限的必备手段。按照我个人这两年的习惯一个高质量的知识库流水线通常是marker解析JSON → 清洗 → 按块类型分级切片 → 向量化 → 入向量库。每一步都保留足够的元数据后面才能做到可追踪、可复现。如果你现在还在用“字符串切片”的方式做RAG真心建议抽出一天时间把解析和切片这一层重做一遍。你会发现很多之前莫名其妙的“模型回答不准”问题其实根本不是模型的问题而是输入给模型的内容从一开始就是残缺的。文档解析和切片这件事本身不炫酷但它是整个知识库体系的承重墙。这堵墙不结实天花板装得再好也会塌。希望这篇分享能帮你少走一些弯路把地基打得扎实一点。