我们继续聊 RAG 文档解析。这一期专门讲 bbox边界框bounding box实战针对两类让解析结果变“脏”的典型情况多栏排版和带水印的 PDF。如果你平时用 PyMuPDFfitz或 pdfplumber 处理过文档应该遇到过这种场景明明版面看着挺整齐抽出来的文本却左一截右一截句子被拦腰截断段落顺序乱成一团。更别提那种满屏“内部资料”“请勿外传”水印的 PDF抽出来的文字全是重复的干扰词喂给 RAG 做切分检索效果直接被拉垮。这个项目的核心思路很简单不要只按 PDF 自带的文本顺序抽字而是先把每个文本块的位置bbox拿到手再用坐标信息做版面分析。多栏排版就按栏切分按阅读顺序重组水印就靠坐标、字体、透明度特征识别出来直接剔除。文章会从 bbox 的基本结构讲起给出一套可复用的 Python 处理流程最后附上我在实际项目中踩过的坑和排查思路。这套东西适用于所有需要高质量文本抽取的 RAG 项目尤其是处理论文、双栏教材、带机构标识的正式文档。1. 多栏排版为什么是 RAG 解析的“老大难”1.1 PDF 解包后的文本顺序不等于阅读顺序先想一个问题PDF 里的文字在文件内部存储的顺序是“阅读顺序”吗答案经常不是。PDF 页面上的每个文本元素本质上是散落在版面里的独立对象。解析器默认按对象在文件流里的出现顺序输出文本而这个顺序取决于生成 PDF 时排版引擎的写入顺序和人类的阅读习惯没有任何关系。我用 PyMuPDF 实测过一份双栏论文抽取结果的第一行长这样Abstract—This paper proposes a novel approach for (§ I Introduction两栏内容被按列交错拼接。原因是文本对象在文件流里的先后顺序是右栏的一部分、左栏的一部分、右栏继续、左栏继续……解析器按顺序导出就把两个栏的碎片缝合在一起了。这种结果进 RAG 之后会出现两个致命问题切分单位不对按 token 或按字符数硬切会把两个栏的语义片段拼在一起造出“伪段落”。检索召回率下降查询词被切到两个不同的 chunk 里BM25 或向量检索都匹配不到完整的上下文。1.2 水印噪声让检索质量断崖式下跌水印类型很多大致分三类水印类型特点对解析的影响平铺文字水印每页重复几十次“内部文件”“Do Not Copy”文本量虚高检索被高频词污染对角大字水印字号很大旋转 45 度半透明被识别为一整条文本块破坏段落连续性图片水印以图片形式嵌入页面OCR 时可能被识别为文字前两类对文本抽取的破坏最直接。我处理过一份 30 页的招标文件每页平铺了 26 次“机密”水印抽取后总文本量暴增 30%而且这些高频词会持续干扰 embedding 模型的表示导致语义向量整体偏移。1.3 版面分析与纯文本抽离的本质区别纯文本抽离extraction只做一件事把文字从页面里摘出来。版面分析layout analysis则多了一步——先理解文字之间的空间关系再决定输出顺序和保留哪些内容。bbox 就是空间关系的最小载体。每一段文字在页面上占据一个矩形区域这个矩形由四个数字描述左上角 x、左上角 y、右下角 x、右下角 y。有了坐标就能回答这些关键问题两个文本块是否在同一行它们的 y 中心是否接近某个文本块属于左栏还是右栏它的 x 中心在页面水平方向的位置文本块之间谁是先后的顺序按 y 轴从上到下、x 轴从左到右排序某个文本块是不是水印它是否与内容区重叠、是否重复出现、是否倾斜这一层信息在纯文本抽取里是全部丢掉的但它恰恰是解决多栏和水印问题最关键的线索。1.3 bbox 数据长什么样以 PyMuPDF 的page.get_text(dict)为例每个文本块block返回的数据结构包含这些关键字段{ bbox: (72.0, 54.0, 315.0, 72.0), # (x0, y0, x1, y1) lines: [ { bbox: (72.0, 54.0, 315.0, 61.0), spans: [ { bbox: (72.0, 54.0, 315.0, 61.0), text: 基于多栏版面分析的RAG文档解析研究, font: SimSun, size: 10.5, } ] } ] }坐标单位是 PDF 的点point1 point 1/72 英寸。页面左下角是 (0, 0)向左上延伸。这个坐标系和我们习惯的图像坐标系左上角为原点不一样但没关系我们只需要做相对位置判断不涉及跨坐标系换算。有了bbox后剩下的工作就非常机械对文本块按位置做聚类、排序、过滤。下面进入实战部分。2. 环境准备与 bbox 获取方案2.1 工具选型为什么选 PyMuPDF解析 PDF 的 Python 库有好几个主流的是 PyMuPDFfitz、pdfplumber、pypdf。我的选型建议是PyMuPDF首选。速度极快解析精度高get_text(dict)直接输出带 bbox 的块级结构C 底层实现处理几百页的大文件也不吃力。pdfplumber适合需要精确查看字符级坐标的场景但它默认输出行级和字符级的细节直接拿来做版面分析反而信息太碎而且速度比 PyMuPDF 慢一些。pypdf纯 Python 实现不做版面分析只适合简单的文本抽取。本项目核心依赖就一个 PyMuPDF安装方式pip install pymupdf我用的版本是 1.24.x不同版本之间 API 有细微差别但page.get_text(dict)这个接口非常稳定从 1.18 到 1.24 都没改过结构代码可以直接复用。2.2 获取页面级 bbox 的完整代码下面是一个标准化的 PDF 文本块提取函数返回按页码组织的文本块列表import fitz # PyMuPDF def extract_blocks_with_bbox(pdf_path): doc fitz.open(pdf_path) pages_data [] for page_idx, page in enumerate(doc): # 获取页面尺寸后面判断栏位会用到 page_rect page.rect page_width page_rect.width page_height page_rect.height # 核心调用获取带坐标的文本结构 text_dict page.get_text(dict) blocks [] for block in text_dict[blocks]: # 过滤掉图片块type 1 是图片 if block[type] ! 0: continue bbox block[bbox] # 拼接该块内的所有文本 block_text for line in block[lines]: for span in line[spans]: block_text span[text] blocks.append({ page: page_idx, bbox: bbox, text: block_text.strip(), # 顺便记下字体和字号后面水印过滤要参考 fonts: list(set( span[font] for line in block[lines] for span in line[spans] )), sizes: list(set( round(span[size], 1) for line in block[lines] for span in line[spans] )), }) pages_data.append(blocks) doc.close() return pages_data注意这里我做了两件事一是过滤了图片块因为我们做文本抽取对图片不感兴趣二是对每个 block 提取了字体和字号列表这两个字段在后面判断水印时很有用。2.3 先看坐标分布快速定位版面问题拿到 blocks 后我习惯先做一个可视化检查把坐标画出来确认版面是不是真的多栏。这一步能在动手写算法之前就发现不少隐藏问题比如有些 PDF 虽然长成单栏但每行前面塞了个大号背景色块实际解析出来的文本块坐标异常错位。可视化代码很简单import matplotlib.pyplot as plt def visualize_layout(pages_data, page_idx0): fig, ax plt.subplots(figsize(8, 10)) page_width max(b[bbox][2] for b in pages_data[page_idx]) page_height max(b[bbox][3] for b in pages_data[page_idx]) ax.set_xlim(0, page_width) ax.set_ylim(0, page_height) ax.invert_yaxis() # 让 y 轴朝下符合阅读习惯 for block in pages_data[page_idx]: x0, y0, x1, y1 block[bbox] rect plt.Rectangle((x0, y1), x1-x0, y0-y1, fillFalse, edgecolorred, linewidth1) ax.add_patch(rect) plt.show()画出来的矩形图能非常直观地显示每个文本块处在页面的什么位置是否有明显的左右分栏间隙水印文本是不是零散地分布在整个页面。我建议在正式处理任何一批新 PDF 之前先跑一遍可视化比你盯着文本输出猜问题高效得多。3. 核心实操一多栏排版的自动识别与切分3.1 用 x 坐标判断文本块的“栏归属”多栏排版的本质是不同区域的文本块在垂直方向y 方向上共生它们的 x 中心位置呈现明显的分簇特征。左栏的每个块x 中心都靠近页面左侧右栏的每个块x 中心都靠近页面右侧。中间栏间隙区域的 x 坐标不会有任何块中心。所以识别多栏的任务本质上是一个一维聚类问题把所有文本块的 x 中心坐标提出来看它们能聚成几簇。聚出两簇就是双栏聚出三簇就是三栏聚成一簇就是正常单栏。实现上有两种路径方法一手动阈值判断适合栏位结构固定的文档def detect_columns(blocks, page_width, threshold_ratio0.35): 粗略判断如果页面左侧 x0 page_width*0.4 和右侧 x1 page_width*0.6 的块都存在且存在明显中间空隙 就认为是双栏 left_blocks [b for b in blocks if b[bbox][2] page_width * 0.5] right_blocks [b for b in blocks if b[bbox][0] page_width * 0.5] if left_blocks and right_blocks: # 进一步检查中间是否有空隙 left_max_x max(b[bbox][2] for b in left_blocks) right_min_x min(b[bbox][0] for b in right_blocks) gap right_min_x - left_max_x if gap 20: # 中间间隙大于 20pt 认为是真实分栏 return 2 return 1这个方案虽然粗糙但在处理固定排版风格的论文数据库时反而很稳因为每个期刊的排版规范都是固定的阈值调一次能管很久。方法二KMeans 聚类适合不固定来源的混合文档from sklearn.cluster import KMeans def detect_columns_kmeans(blocks, max_cols3): if len(blocks) 5: return 1 # 取每个块中心的 x 坐标做聚类特征 x_centers [[bbox][0] b[bbox][2]) / 2 for b in blocks] x_centers [[x] for x in x_centers] # 转换形状 best_k 1 best_inertia None for k in range(1, max_cols 1): kmeans KMeans(n_clustersk, random_state0, n_init10) kmeans.fit(x_centers) inertia kmeans.inertia_ # 肘部法则当新增聚类带来的 inertia 下降明显变小时停止 if best_inertia is not None and (best_inertia - inertia) / best_inertia 0.15: break best_k k best_inertia inertia return best_k这里用了一个简单的手写肘部法则。实际测试中单栏文档在k2时 inertia 下降通常会超过 30%双栏文档在k2时下降很小在k3时几乎没有变化。阈值 0.15 经过几批文档的调参效果稳定。3.2 栏位重组按阅读顺序拼接文本确定有双栏之后关键一步是按栏重排文本。规则很简单分两步走每个块按照所属栏分组左栏一组、右栏一组。组内按 y 坐标从上到下排序。输出顺序左栏全部块按序拼接然后右栏全部块按序拼接。这里要特别注意一个细节不能简单地整块按 y 排序后再拼接。因为双栏文档里左栏底部的内容和右栏顶部的内容可能在同一水平位置上如果整体按 y 排序会把左右栏交错输出跟原来的乱序问题没区别。正确的顺序永远是“先分栏再栏内按 y 排序”。def reorder_blocks_for_multicol(blocks, page_width, x_center_thresholdNone): 按栏重排文本块 if len(blocks) 0: return [] if x_center_threshold is None: # 自动计算中线页面宽度中点 x_center_threshold page_width / 2 left_blocks [] right_blocks [] for b in blocks: x0, y0, x1, y1 b[bbox] x_center (x0 x1) / 2 if x_center x_center_threshold: left_blocks.append(b) else: right_blocks.append(b) # 组内按 y 排序y0 越小越靠上 left_blocks.sort(keylambda b: b[bbox][1]) right_blocks.sort(keylambda b: b[bbox][1]) # 拼接结果 ordered_text \n.join([b[text] for b in left_blocks]) ordered_text \n if right_blocks else ordered_text \n.join([b[text] for b in right_blocks]) return ordered_text这里的分栏边界用的是页面宽度的一半。实际论文排版中双栏的分界不一定正好在正中可能左栏宽右栏窄。更稳妥的办法是用前面 KMeans 聚类算出来的簇中心做边界取两个簇中心坐标的平均值作为分界线。3.3 边界情况复杂的多栏嵌套和跨栏标题版面分析里最容易翻车的不是双栏正文而是跨栏元素——比如标题横跨左右两栏、单行摘要横跨两栏、图注放在页面底部横跨整栏。如果都按左右分组处理这些跨栏元素会被强行塞进某一栏导致顺序错乱。我的处理方案是在做分栏排序前先识别出“通栏”文本块——即宽度超过页面宽度 60%~70% 的块。这些块通常是标题、副标题、页眉页脚或图注它们的阅读顺序优先级最高先输出通栏块再按栏输出栏内正文。def reorder_blocks_smart(blocks, page_width): 识别通栏元素并按阅读顺序组织 span_threshold page_width * 0.6 full_width_blocks [] column_blocks [] for b in blocks: x0, y0, x1, y1 b[bbox] if (x1 - x0) span_threshold: full_width_blocks.append(b) else: column_blocks.append(b) # 通栏块按 y 排序 full_width_blocks.sort(keylambda b: b[bbox][1]) # 分栏块按前述逻辑拼接 column_centers [[bbox][0] b[bbox][2]) / 2 for b in column_blocks] # 用中位数作为分界比固定中线更鲁棒 import statistics split statistics.median(column_centers) if column_centers else page_width / 2 left [b for b in column_blocks if (b[bbox][0] b[bbox][2]) / 2 split] right [b for b in column_blocks if (b[bbox][0] b[bbox][2]) / 2 split] left.sort(keylambda b: b[bbox][1]) right.sort(keylambda b: b[bbox][1]) # 输出顺序通栏块 → 左栏 → 右栏 lines [] for b in full_width_blocks: lines.append(b[text]) for b in left: lines.append(b[text]) for b in right: lines.append(b[text]) return \n.join(lines)这个“通栏优先”策略实测能覆盖论文、标准文档、合同等九成以上的情况。剩下 10% 里最常见的失败场景是通栏检测阈值不适用于某些特殊排版比如特别宽的图注需要根据文档来源微调。4. 核心实操二水印 PDF 的识别与剔除4.1 基于文本重复模式的水印检测最有效水印文本的最大特征是重复——同一句话在页面内出现很多次且出现在不同的位置。正常正文里同一句话很少在单页里重复十几次除非是刻意的排比句。结合 bbox 和文本内容可以做一个非常可靠的检测逻辑统计该页每个文本块的内容出现次数。如果同一个文本块内容在页面内出现超过min_freq次比如 5 次判定为水印。同时检查这个文本块和其他重复块的位置是否分布在不同区域且 x/y 坐标呈现某种规律比如均匀网格。from collections import Counter def detect_watermark_by_repetition(blocks, min_freq5): 基于文本重复频率识别水印块返回水印块索引集合 if len(blocks) min_freq: return set() # 按文本内容做频率统计 text_list [b[text] for b in blocks] counter Counter(text_list) repeated_texts {text for text, cnt in counter.items() if cnt min_freq} watermark_indices set() for i, b in enumerate(blocks): if b[text] in repeated_texts: # 额外检查水印块通常长度较短且不是标题 if len(b[text]) 30: watermark_indices.add(i) return watermark_indices限制len(text) 30是为了防止把真正的短标题误判比如论文里“Abstract”这个单词在每页顶部出现但不应该被当成水印。这里的阈值5和30可以按项目实际情况调处理标准论文时这两个参数都很稳。4.2 基于坐标与内容特征的水印检测兜底方案不是所有水印都满足“重复”特征。有些 PDF 的水印是单次放置的对角大字一页只出现一两次这种就要靠坐标特征判断。常用的判别规则透明度高PyMuPDF 的 span 对象里有color字段但透明度需要从字符的渲染模式里间接判断。更实用的做法是看字号和位置。倾斜角度水印常用 45 度旋转可以通过线条 bbox 的对角线斜率来判断但get_text(dict)不直接给出旋转角需要依赖span[dir]字段。这个字段是 (cosθ, sinθ) 形式代表文本方向。尺寸异常水印字号通常大于正文比如 24pt 对比 10.5pt且 bbox 覆盖页面中心区域与正文文本块重叠。实战中最稳的思路是先按重复频率过滤再对残余水印用“字号方向”规则补刀。我给一个综合方案的骨架import math def detect_watermark_by_features(blocks, page_width, page_height): 基于字号、位置、方向的综合水印检测 watermark_indices set() # 先做重复检测 watermark_indices | detect_watermark_by_repetition(blocks) for i, b in enumerate(blocks): x0, y0, x1, y1 b[bbox] block_w x1 - x0 block_h y1 - y0 x_center (x0 x1) / 2 y_center (y0 y1) / 2 # 规则1大字体的斜向文本方向向量角度明显偏离水平 # 方向角度判断需要访问 span这里简化为 text 长度 字号 max_font_size max(b.get(sizes, [0])) if max_font_size 20: # 规则1a长度短而字号大且中心在页面中心区域 if len(b[text]) 20: if 0.25 * page_width x_center 0.75 * page_width: if 0.25 * page_height y_center 0.75 * page_height: watermark_indices.add(i) continue # 规则2宽高比极度异常的文本块内容文本一般长宽比有限 if block_w 0 and block_h / block_w 5: if x_center page_width * 0.1 or x_center page_width * 0.9: watermark_indices.add(i) return watermark_indices注意这些规则阈值都是从经验里调出来的不是放之四海而皆准。建议对每个新来源的文档先抽样人工检查一轮再把阈值调整到“误伤率低于 1%”的程度。4.3 多次页面叠加策略跨页统计提升准确率单独一页里出现 3 次相同文本不足以判定水印但如果这类文本在 30 页里每页都出现 20 次那基本可以锤死是水印。跨页统计能大幅提高水印判定的置信度同时避免整块误删。实际做法是先用轻量规则跑完全部页面提取候选水印文本。做一个全局Counter统计候选水印在所有页面上的出现总次数。只剔除那些总次数超过阈值的文本。比如某份文档 20 页每页都有“机密”二字出现 15 次那么总次数就是 300远超阈值。相反某句话只在某一页出现 6 次比如论文里的同一组实验条件描述总次数才 6不会被误删。def extract_clean_text_with_watermark_filter(pdf_path): doc fitz.open(pdf_path) # 第一遍统计所有页面文本频率建立全局水印词库 global_counter Counter() all_pages_blocks [] for page in doc: text_dict page.get_text(dict) page_blocks [] for block in text_dict[blocks]: if block[type] ! 0: continue block_text .join( span[text] for line in block[lines] for span in line[spans] ).strip() if not block_text: continue page_blocks.append({ bbox: block[bbox], text: block_text, sizes: [round(span[size], 1) for line in block[lines] for span in line[spans]], }) global_counter[block_text] 1 all_pages_blocks.append(page_blocks) # 全局判定水印总出现次数 单页块数的 4 倍 # 简化版总次数 页数 * 3 且文本长度 20 num_pages len(doc) watermark_texts set() for text, cnt in global_counter.items(): if cnt num_pages * 3 and len(text) 20: watermark_texts.add(text) # 第二遍输出干净的过滤后文本 clean_text_pages [] for page_blocks in all_pages_blocks: filtered_blocks [b for b in page_blocks if b[text] not in watermark_texts] # 这里可以接上文的多栏重排逻辑 clean_text_pages.append(filtered_blocks) doc.close() return clean_text_pages这个方法的优势在于num_pages * 3这个阈值自动适应文档长度。单页文档1 页里同样的文本出现 3 次就会被标记100 页文档里文本需要出现 300 次才会被标记。在实际项目中我遇到过一份 50 页的 PDF其中 10 页包含相同的免责声明每页只出现 1 次总次数 10远小于 150顺利保留这个逻辑非常可靠。5. 从 bbox 处理到 RAG 落地的完整流程5.1 一个完整的解析管线示例把上面所有模块串起来就是一套可直接套用的解析管线。这个管线输入 PDF 路径输出干净的、按阅读顺序组织的纯文本可以直接交给后续的切分chunking和 embedding 环节。def pdf_to_clean_text(pdf_path, max_pagesNone): 完整解析管线带 bbox 过滤、版面重排、水印剔除 doc fitz.open(pdf_path) all_pages [] if max_pages: page_range range(min(max_pages, len(doc))) else: page_range range(len(doc)) for page_idx in page_range: page doc[page_idx] page_width page.rect.width page_height page.rect.height text_dict page.get_text(dict) blocks [] for block in text_dict[blocks]: if block[type] ! 0: continue block_text .join( span[text] for line in block[lines] for span in line[spans] ).strip() if not block_text: continue blocks.append({ bbox: block[bbox], text: block_text, sizes: [round(span[size], 1) for line in block[lines] for span in line[spans]], }) # 1. 水印过滤基于重复 特征规则 watermark_indices detect_watermark_by_features( blocks, page_width, page_height ) blocks [b for i, b in enumerate(blocks) if i not in watermark_indices] # 2. 多栏版面重排 if len(blocks) 0: num_cols detect_columns_kmeans(blocks) if num_cols 1: page_text reorder_blocks_smart(blocks, page_width) else: # 单栏直接按 y 排序拼接 blocks.sort(keylambda b: b[bbox][1]) page_text \n.join(b[text] for b in blocks) else: page_text all_pages.append(page_text) doc.close() return \n\n.join(all_pages)5.2 处理后的切分与 embedding 决策版面重排之后文本质量已经有质的提升。接下来 RAG 管线的后续环节有几个决策点值得专门说切分粒度我倾向于按语义段落切分。用 bbox 处理完的多栏重排结果天然保留了段落边界——每个文本块基本就是一个段落或列表项。按“块”切分远好于按固定字符数硬切。具体可以做一次后处理如果块内文本超过 512 个 token再按句子边界二次切分如果太短则与相邻块合并。以页面还是跨页面为切分单元多栏重排后的结果每个页面是一段逻辑完整的内容可以直接作为 RAG 的基本检索单元。跨页面的内容如果有持续语义可以给相邻页面之间做重叠滑动窗口。要不要做 OCR上面所有方案都建立在 PDF 自带文本图层的基础上。如果 PDF 是扫描件get_text(dict)返回空那必须先 OCR。建议先用len(page.get_text())快速探查文本量如果某页文本长度小于 10 个字符就标记为图片页走 OCR 流程。OCR 后的文本也可以用坐标信息重建 bbox但那是另一个话题我们后面专门写一篇。5.3 直接复用模块时的参数清单模块关键参数建议初始值调参经验栏目检测threshold_ratio0.4~0.5论文类双栏多为 0.5 中分混合版面需跑 KMeans通栏识别span_threshold0.6 × 页面宽度页面宽度要先取page.rect.width重复水印过滤min_freq单页重复次数5对横幅型水印如“资料”可降到 3全局水印过滤num_pages * 3文档页数 ×3页数太少时可临时改为 ×2 或 ×1水印文本最大长度最大文本长度20有些水印里带编号可放宽到 30这些参数是处理过 500 份 PDF 后沉淀下来的初始值。特别注意不同来源的文档知网下载的论文、政府公告、公司年报参数差异非常大通用初始值只能保证“能用”不能保证“最优”。正式项目中建议对每类新文档源跑一次抽样人工确认几个版面样例后再固化参数。6. 常见问题排查与避坑指南6.1 文本块之间缺少空格/换行这是最常见的问题。get_text(dict)输出的 span 文本是严格按照 PDF 内部指令解析的如果 PDF 里相邻单词之间用的是位置偏移而不是空格字符抽出来的词组就会黏在一起。最经典的场景是英文论文里的斜体连字符换行以及某些排版软件把空格压缩成微小偏移。排查方法把抽取文本按字符数画直方图如果发现大量块文本长度异常偏低比如 3~5 个字符多半是粘连问题。解决思路有两个用span[dir]和相邻 span 的 bbox 差值推算需不需要补空格——两个相邻 span 的x0差值大于前一个 span 的字体宽度时补一个空格。直接用page.get_text(text)配合sortTrue参数PyMuPDF 自带一定的空格恢复逻辑但同样适用于无复杂版面的文档。我的经验是如果文档以中文为主这个问题基本不会遇到因为中文排版中每个字符天然独立如果以英文为主务必做一次相邻 span 的空格恢复。一个简单的实现def add_missing_spaces(blocks): 根据 span bbox 间隙自动补空格 for block in blocks: for line in block[lines]: spans line[spans] for i in range(len(spans) - 1): current_span spans[i] next_span spans[i1] gap next_span[bbox][0] - current_span[bbox][2] # 间隙超过当前字号的 0.3 倍时补空格 if gap current_span[size] * 0.3: current_span[text] 6.2 水印过滤把正文误删了仅次于粘连问题的高频事故。我遇到过一份 PDF正文里每页都出现 6 次“联系电话400-123-456”被重复过滤逻辑标记成了水印。后来加了两个保护条件才解决文本内容中含数字且比例超过 30% 的不判为水印电话、编号、日期不属于水印常用形态。文本块中包含 URL 或邮箱地址的不判为水印。另外标题重复也容易误伤。比如每章开头都有“第X章 实验与分析”在 10 页文档里出现 10 次按num_pages * 3的规则可能被标记。解决方式是给水印词库增加一个白名单或者复用水印过滤逻辑时增加字号判断标题字号通常大于正文且颜色更深水印通常半透明或低灰度。6.3 bbox 坐标单位与图像坐标的混淆如果你用 PyMuPDF 提取线框、图片或其他元素与文本块做交叉分析要注意坐标单位的一致性。page.get_text(dict)返回的坐标单位是 PDF 点page.get_pixmap()生成的图片分辨率里每个像素对应 72 dpi如果先渲染成 300 dpi 的图像再做 OCR坐标需要乘 300/72 的缩放系数。最容易出错的场景是“把文本块的 bbox 画到渲染图上对比”。正确换算方式# PDF 点转渲染图像像素坐标 scale render_dpi / 72 pix_x0 block_bbox[0] * scale pix_y0 block_bbox[1] * scale pix_x1 block_bbox[2] * scale pix_y1 block_bbox[3] * scale6.4 多栏检测失效的罕见版面几个踩过多次的版面类型三栏 中间窄栏有时论文的中间栏是注释或侧栏宽度只有其他栏的 1/3。KMeans 分簇能分出 3 簇但排序逻辑需要额外处理。可以把每簇的中心 x 坐标排序后再按簇顺序输出。通栏标题 双栏正文已在前文处理逻辑里覆盖。双栏但栏间隙极小比如某些 Latex 生成的文档栏间隙只有 10pt 左右靠默认的阈值判断分栏容易失效。可以把栏间隙阈值从 20 降到 5但这样也可能把真正的整段文本误切。这种极端情况建议人工确认版面后再决定参数。6.5 PyMuPDF 读取异常文件加密和损坏处理处理批量 PDF 时偶尔会遇到加密文件打开需要密码或损坏文件。PyMuPDF 默认遇到加密文件会抛出异常我一般在项目入口做一个兜底def safe_open_pdf(pdf_path): try: doc fitz.open(pdf_path) except Exception as e: print(f无法打开文件: {pdf_path}, 错误: {e}) return None if doc.is_encrypted: # 尝试空密码解密 try: doc.authenticate() except Exception as e: print(f解密失败: {pdf_path}) return None return doc批量处理时给每个 PDF 包一层这个安全打开函数能避免一个坏文件让整个流水线崩溃。6.6 性能调优大批量 PDF 处理的内存管理用 PyMuPDF 处理几百个 PDF每份几十页到几百页内存里如果积压每个页面的 blocks 数据很容易 OOM。我通常会边读边写不把所有页面数据都在内存里攒齐def process_large_pdf(pdf_path, output_txt_path): doc fitz.open(pdf_path) with open(output_txt_path, w, encodingutf-8) as f: for page_idx in range(len(doc)): page doc[page_idx] page_text extract_clean_page_text(page) # 前面写的各种逻辑 f.write(page_text) f.write(\n\n) if page_idx % 50 0 and page_idx 0: # 每 50 页强制告诉垃圾回收器处理一下 import gc gc.collect() doc.close()在这个模式里任意时间点内存里只保留一个页面的数据即使 1000 页的 PDF 也能稳定跑完。7. 后续扩展方向与个人经验总结回头总结一下整个项目的核心心法解析 PDF 时永远先拿坐标再讲逻辑。bbox 是版面分析的骨架多栏重组、水印剔除、通栏识别全都是围绕坐标规则展开的。只做文本抽取不做版面分析的 RAG 管线就像盲人摸象——大家都在瞎猜自己摸到的那块是大象的哪个部分。下一步我计划在这套管线基础上做两个扩展。一是接入 OCR 流程把扫描版 PDF 用 PaddleOCR 跑一遍文字识别再把 OCR 结果的文本框坐标对齐到 PDF 坐标系这样上面的所有 bbox 逻辑可以直接复用二是把版面分析结果升级成结构化输出阅读顺序 标题层级 图片与表格的坐标标注直接生成带元数据的 Markdown这样 RAG 切分后每块文本都能带上上下文结构信息检索效果可以更进一步。最后分享一个我踩过很多次的坑参数调优时一定要保留“黄金测试集”。开始集成调试之前从真实业务文档里挑 20~30 个有代表性的 PDF 存成固定测试集每次改动完参数先跑一遍黄金集对比输出差异不要用手头的临时文件反复试。上面提到的min_freq5、num_pages*3、span_threshold0.6这些初始参数都是在这个黄金集上调出来的每次调参都能量化地看到效果改进还是退化而不只是“感觉好像好一点”。对 RAG 文档解析这种最容易被低估的环节可量化的测试集比任何“优化技巧”都值钱。