企业官网建设流程全解析

1. 为什么 RAG 系统总在 PDF 这一环翻车

做过 RAG 的人大概率都经历过这个场景：向量库搭好了，检索链路跑通了，大模型也接上了，Demo 演示时效果惊艳，结果一上真实文档就原形毕露。用户问"合同里第三页那个违约金比例是多少"，系统检索回来的却是一堆页眉页脚和表格线，答案驴唇不对马嘴。排查半天，问题不在 embedding 模型，也不在检索策略，而是最上游的 PDF 解析环节就已经把数据喂坏了。

PDF 这个格式从诞生之初就不是为了"被机器读懂"设计的。它的核心目标是"在任何设备上看起来都一样"，所以它本质上是一堆绝对定位的绘图指令集合——文字在哪、多大、什么字体、画在哪条线上，全是坐标。至于这些文字之间的语义关系、段落归属、阅读顺序，PDF 文件里压根没存。这就导致一个尴尬的现实：PDF 解析的质量，直接决定了 RAG 系统的天花板。你后面用再贵的模型、再精细的 rerank，上游喂进去的是乱序文本，下游就只能输出垃圾。

pdf-inspector这个工具就是冲着这个痛点来的。它做的事情说起来朴素——把 PDF 转成结构化的 Markdown，但真正做过的人都知道，这里面水有多深。标题层级怎么还原、跨页表格怎么拼接、双栏排版怎么按正确顺序读、扫描件里的 OCR 结果怎么和版面结构对齐，每一个都是硬骨头。我前后在三个 RAG 项目里踩过 PDF 解析的坑，从最早的 PyPDF2 硬啃，到后来上 OCR 全家桶，再到用上 pdf-inspector 这类专门做结构还原的工具，中间交的学费够写一本书了。

这篇文章适合两类人看：一类是正在搭 RAG 知识库、被 PDF 解析折磨得死去活来的工程师；另一类是手里有一堆 PDF 文档、想搞清楚"为什么我的知识库检索不准"的产品或运营同学。我会把 PDF 解析在 RAG 里的定位、pdf-inspector 的核心能力、实操流程、参数调优、常见坑全部拆开讲，尽量让你看完就能上手，少走我走过的弯路。

2. PDF 解析在 RAG 链路里的真实定位

2.1 解析质量如何决定检索上限

很多人把 RAG 理解成"向量检索 + 大模型生成"，把注意力全放在 embedding 模型选型和 prompt 调优上，却忽略了最前面那个环节。我打个比方：RAG 系统就像一条流水线，PDF 解析是第一个工位，负责把原材料（PDF）拆成标准零件（结构化文本块）。如果这个工位把螺丝和螺母混在一起、把说明书页码顺序打乱，后面装配工位（检索和生成）再厉害，装出来的也是废品。

具体来说，解析质量从三个维度影响 RAG 效果。第一是召回率，如果一段关键信息被切碎成七八个不连贯的片段，或者被页眉页脚污染，向量检索很可能就召不回它。第二是上下文完整性，一个表格被拆成上下两半，检索到上半部分却丢了表头，大模型拿到手也不知道每列是什么意思。第三是语义准确性，双栏论文如果按"从左到右、从上到下"的物理顺序读，会把左栏第一段和右栏第一段拼在一起，语义直接错乱。

我实测过一个对比：同一份 200 页的技术手册，用基础文本提取工具直接抽文字，检索准确率大概在 55% 左右；换成带版面分析的解析工具转成结构化 Markdown 后，同样的检索链路，准确率能到 82%。差距全在解析这一环，后面的配置一个字没改。

2.2 为什么是 Markdown 而不是纯文本或 JSON

这里要解释一个关键选择：为什么 pdf-inspector 这类工具的输出目标是 Markdown，而不是纯文本或者结构化 JSON。

纯文本的问题在于丢失了所有结构信息。标题和正文混在一起，表格变成一堆用空格对齐的字符，列表的层级关系全没了。你拿这种文本去切块，切出来的 chunk 语义边界是模糊的，检索时自然不准。

JSON 看起来很美，结构完整，但它有个致命问题：大模型对 JSON 的理解和生成成本更高。你把 JSON 塞进 prompt，模型需要额外消耗 token 去解析结构，而且 JSON 里的转义字符、嵌套层级容易让模型犯迷糊。更实际的问题是，JSON 不适合做文本切块——你很难优雅地把一个 JSON 对象切成多个语义完整的 chunk。

Markdown 恰好卡在中间。它保留了标题层级（#、##）、列表结构（-、1.）、表格（|）、代码块（```），这些标记本身就是语义信号，切块时可以按标题层级切、按表格边界切。同时 Markdown 是纯文本，token 效率高，大模型对它的理解也非常成熟。所以"PDF 转 Markdown"成了 RAG 预处理的事实标准，pdf-inspector 走这条路是对的。

2.3 pdf-inspector 解决的核心问题清单

把 pdf-inspector 的能力拆开看，它主要解决这几类问题，我按难度从低到高排：

• 基础文本提取：把 PDF 里的文字抽出来，这是所有工具的基本功，但质量差异很大，尤其是遇到嵌入字体、特殊编码时。
• 阅读顺序还原：判断文字块的正确阅读顺序，处理双栏、多栏、图文混排的版面。
• 标题层级识别：通过字号、字重、位置等特征，推断哪些是标题、是几级标题。
• 表格结构还原：识别表格的行列结构，转成 Markdown 表格，处理合并单元格、跨页表格。
• 列表识别：识别有序列表、无序列表，还原嵌套层级。
• 扫描件 OCR：对图片型 PDF 做文字识别，并把 OCR 结果和版面结构对齐。
• 页眉页脚剔除：识别并去掉每页重复的页眉页脚、页码，避免污染正文。

这七项里，前两项是及格线，中间三项是拉开差距的地方，最后两项是加分项。pdf-inspector 的价值就在于它把后面这几项做得比较扎实，而不是只停留在"能抽出字"的层面。

3. pdf-inspector 核心能力拆解与实操要点

3.1 版面分析：让机器看懂"哪块是哪块"

版面分析是 PDF 解析的地基。它的任务是给 PDF 页面上的每个元素打标签：这是标题、这是正文段落、这是表格、这是图片、这是页眉。听起来简单，做起来要考虑的因素一大堆。

pdf-inspector 这类工具通常用一套基于规则的启发式方法，结合坐标和字体信息来判断。核心逻辑大概是这样的：先提取页面上所有文字块及其坐标、字号、字体，然后按字号聚类——字号明显大于正文的，大概率是标题；再按位置判断——位于页面顶部或底部、且每页都出现的，大概率是页眉页脚；接着按对齐方式判断——左对齐的连续文本块可能是段落，居中的短文本可能是标题。

这里有个实操要点：字号聚类的阈值需要根据文档调整。学术论文正文常用 10pt，标题 14pt 或 16pt，阈值设 1.2 倍就能区分；但有些排版紧凑的手册，正文 9pt、小标题 10pt，这时候固定阈值就会误判。我的经验是先用工具跑一遍，看输出的标题层级对不对，不对再调阈值参数。

注意：版面分析对扫描件基本无效，因为扫描件里没有文字块和字体信息，只有一张图。扫描件必须先走 OCR，OCR 引擎会返回文字及其坐标，再基于这些坐标做版面分析。

3.2 阅读顺序还原：双栏文档的噩梦

阅读顺序是 PDF 解析里最容易被低估的难点。单栏文档还好，从上到下、从左到右基本没错。但一旦遇到双栏排版（学术论文、杂志、部分技术手册），物理顺序和阅读顺序就完全对不上了。

我举个具体的例子。一个双栏页面，左栏是"1. 引言"到"1.3 相关工作"，右栏是"2. 方法"到"2.2 模型结构"。如果按物理坐标从上到下读，会变成：左栏第一行、右栏第一行、左栏第二行、右栏第二行……读出来完全是乱码。正确的做法是先判断分栏，再按"先读完左栏再读右栏"的顺序输出。

pdf-inspector 处理这个问题的方式通常是：先检测页面是否存在明显的垂直分栏线（通过分析文字块的 x 坐标分布，看是否在中间区域有空白带），如果有，就按栏分组，再在每栏内部按 y 坐标排序。这个逻辑对规整的双栏有效，但遇到不规则排版（比如某一段横跨两栏）就会出错。

我的实操心得是：对双栏文档，解析完一定要人工抽查几页，重点看跨栏的段落有没有被拆错。如果错误率高，可以考虑先用工具把 PDF 按栏切分，再分别解析。这个预处理步骤多花十分钟，能省下后面调试检索的一整天。

3.3 表格还原：从一堆坐标到 Markdown 表格

表格是 PDF 解析里最考验功力的部分。PDF 里的表格本质上是一堆线条和文字，工具需要判断哪些线构成表格边框、哪些文字属于哪个单元格、表头是哪一行。

pdf-inspector 的表格还原一般分几步：先检测表格区域（通过识别连续的横线和竖线，或者通过文字块的对齐规律），再划分单元格（根据线条交点或文字块边界），然后把每个单元格的文字填进去，最后输出成 Markdown 表格。

这里有几个坑必须提前知道。第一是无边框表格，很多现代排版用留白代替线条，这种表格检测难度大，容易漏检或误检。第二是合并单元格，Markdown 表格语法本身不支持合并单元格，工具通常只能把合并单元格的内容重复填充或留空，需要后续处理。第三是跨页表格，一个表格从上一页延续到下一页，工具如果按页独立处理，就会输出两个残缺的表格。

实操建议：对表格密集的文档，解析后单独检查表格部分。如果跨页表格被拆开，可以在后处理阶段用脚本按表头匹配把两段拼起来。这个脚本不难写，核心逻辑就是比对两个表格的第一行是否相似。

3.4 OCR 集成：扫描件和图片型 PDF 的处理

不是所有 PDF 都有文字层。扫描件、拍照生成的 PDF、部分老文档，里面只有图片，没有可提取的文字。这时候就必须上 OCR。

pdf-inspector 通常不自己实现 OCR，而是集成成熟的 OCR 引擎（比如 Tesseract、PaddleOCR 等）。流程是：先把 PDF 每页渲染成高分辨率图片，再送进 OCR 引擎识别，拿到文字和坐标，最后把 OCR 结果当作"文字块"送进版面分析流程。

这里的关键参数是渲染分辨率。分辨率太低，OCR 识别率暴跌；太高，处理速度慢且可能引入噪声。我的经验值是 300 DPI 起步，对字小的文档可以提到 400 DPI。另外，OCR 的语言包要选对，中英文混排的文档要同时加载中英文语言包，否则识别出来全是乱码。

还有个容易被忽略的点：OCR 后的版面分析要用 OCR 返回的坐标，而不是重新检测。有些工具 OCR 完就只拿文字，丢了坐标，导致版面结构全乱。选工具时要确认它是否保留了 OCR 的坐标信息。

3.5 页眉页脚剔除：小细节大影响

页眉页脚看起来是小事，但对 RAG 检索的干扰很大。想象一下，一份 100 页的文档，每页页眉都是"XX公司内部技术手册 第X章"，页脚都是页码。这些内容会被切进每个 chunk，导致每个 chunk 都包含这些无意义文本，稀释了真正的语义信息，检索时还容易误召回。

pdf-inspector 剔除页眉页脚的逻辑通常是：统计每页顶部和底部区域出现的文本，如果某个文本在超过一定比例（比如 60%）的页面上重复出现，就判定为页眉页脚并剔除。这个逻辑对规整文档有效，但遇到每页页眉略有不同的情况（比如章节名变化）就会漏剔。

我的做法是：解析后先看输出的 Markdown，如果发现大量重复的页眉页脚文本，就手动加规则剔除，或者调整工具的重复检测阈值。这一步花不了几分钟，但对检索质量提升明显。

4. 从 PDF 到 RAG 知识库的完整实操流程

4.1 环境准备与工具安装

假设你已经有一个 RAG 项目的基本环境（Python 3.9+、向量库、embedding 模型），现在要接入 pdf-inspector 做 PDF 预处理。安装通常很简单，pip 一把梭：

pip install pdf-inspector

如果涉及 OCR，还需要额外装 OCR 引擎和语言包。以 Tesseract 为例：

# Ubuntu/Debian sudo apt-get install tesseract-ocr tesseract-ocr-chi-sim tesseract-ocr-eng # macOS brew install tesseract tesseract-lang

Python 侧还需要装 pytesseract 或对应的封装库。这里提醒一句：OCR 引擎的版本和语言包要匹配，我遇到过装了新版 Tesseract 但语言包还是旧版，导致中文识别率极低的情况，排查了半天才发现是版本问题。

4.2 单文件解析：先跑通再批量

不要一上来就批量处理几百个 PDF，先用一个文件跑通全流程。选一个你熟悉的、结构有代表性的文档，比如一份带目录、带表格、带图的技术手册。

from pdf_inspector import PDFInspector inspector = PDFInspector( ocr_enabled=True, ocr_lang='chi_sim+eng', ocr_dpi=300, remove_header_footer=True, detect_tables=True, heading_detection=True ) result = inspector.parse('sample.pdf') markdown_text = result.to_markdown() with open('sample.md', 'w', encoding='utf-8') as f: f.write(markdown_text)

跑完后打开生成的 Markdown，重点检查这几项：标题层级对不对、表格有没有还原、双栏有没有读错、页眉页脚有没有剔除干净。这一步是调参的依据，别跳过。

4.3 参数调优：根据文档类型调整策略

不同文档类型需要不同的参数组合。我整理了一个对照表，是我在多个项目里总结出来的经验值：

调参的核心原则是：先保证正文提取正确，再追求结构还原精细。如果正文都提不准，标题层级再漂亮也没用。

4.4 切块策略：解析完只是开始

PDF 转成 Markdown 后，下一步是切块（chunking）。这一步和解析质量强相关，解析得好，切块就能按语义边界切；解析得烂，切块只能按固定长度硬切。

我的切块策略是这样的：优先按标题层级切，其次按段落切，最后才按长度切。具体来说，遇到##标题就开一个新 chunk，把该标题下的所有内容归到这个 chunk；如果某个 chunk 超过 800 token，再按段落拆；如果单个段落还超长，才按句子或固定长度硬切。

def chunk_markdown(md_text, max_tokens=800): chunks = [] current_chunk = [] current_tokens = 0 for line in md_text.split('\n'): # 遇到二级标题，开新 chunk if line.startswith('## ') and current_chunk: chunks.append('\n'.join(current_chunk)) current_chunk = [line] current_tokens = len(line) else: line_tokens = len(line) if current_tokens + line_tokens > max_tokens: chunks.append('\n'.join(current_chunk)) current_chunk = [line] current_tokens = line_tokens else: current_chunk.append(line) current_tokens += line_tokens if current_chunk: chunks.append('\n'.join(current_chunk)) return chunks

这个切块逻辑的好处是，每个 chunk 尽量对应一个完整的语义单元（一个章节或一个段落），检索时召回的上下文更完整。代价是 chunk 长度不均匀，但这对检索质量的影响远小于语义完整性。

4.5 元数据注入：让检索更精准

光有文本还不够，给每个 chunk 加上元数据能显著提升检索精度。我通常注入这几类元数据：

• 来源文件：哪个 PDF 来的，方便溯源。
• 页码：对应原文档第几页，用户问"第几页"时能定位。
• 章节路径：比如"第3章 > 3.2节 > 表格数据"，提供层级上下文。
• 文档类型：合同、手册、论文，不同类型检索策略可能不同。

这些元数据在切块时就能拿到，存进向量库的 metadata 字段。检索时可以按元数据过滤，比如"只在合同类文档里搜"，精度提升立竿见影。

5. 常见问题与排查技巧实录

5.1 解析出来全是乱码怎么办

乱码是 PDF 解析最常见的问题，原因通常有三种。第一种是字体编码问题，PDF 用了非标准编码或嵌入字体子集，工具无法正确映射到 Unicode。这种情况可以尝试换解析库，或者用 OCR 兜底。第二种是加密 PDF，有些 PDF 设置了权限密码，虽然能打开但禁止提取文字，需要先解密。第三种是扫描件没走 OCR，工具把图片当文字处理，自然全是乱码。

排查顺序：先确认是不是扫描件（用工具看有没有文字层），再看是不是加密（看 PDF 属性），最后才怀疑编码问题。我遇到过最坑的一次是 PDF 既加密又是扫描件，双重问题叠加，排查了半天。

5.2 表格还原错位怎么修

表格错位通常表现为：列对不齐、单元格内容串行、表头丢失。原因可能是表格线检测失败（无边框表格）、单元格划分错误（合并单元格）、或者跨页表格被拆开。

修复思路分两层。第一层是调工具参数，比如调整表格检测的灵敏度、开启合并单元格处理。第二层是后处理，写脚本修。比如跨页表格，可以检测相邻两个表格的表头是否相似，相似就合并。列对不齐的问题，可以在 Markdown 层面重新对齐，虽然麻烦但能救回来。

我的经验：表格密集的文档，别指望工具一次到位，预留 20% 的时间做人工校对和后处理。这是现实，不是工具不行，是 PDF 表格本身太复杂。

5.3 检索召回不准，怎么定位是解析问题还是检索问题

这是个诊断问题。我的方法是做对照实验：手动把某段已知答案的文本，直接从 PDF 里复制出来，构造一个"完美 chunk"，塞进向量库，然后检索。如果这个完美 chunk 能被召回，说明检索链路没问题，是解析质量拖了后腿；如果连完美 chunk 都召不回，那是 embedding 或检索策略的问题。

这个实验能快速定位问题环节，避免在错误的方向上瞎调。我见过太多人一遇到检索不准就去换 embedding 模型，结果换了三四个模型都没用，最后发现是 PDF 解析把关键段落切碎了。

5.4 常见问题速查表

5.5 几个我踩过的坑

第一个坑是盲目追求全自动。我一开始想做一个完全自动化的 PDF 入库流水线，结果发现不同文档类型差异太大，一套参数走天下根本不行。后来改成"按文档类型分组 + 每组一套参数 + 人工抽查"，效率反而更高。

第二个坑是忽略 OCR 的坐标信息。早期我用 OCR 只拿文字，丢了坐标，导致扫描件的版面结构全乱。后来换成保留坐标的 OCR 方案，扫描件的解析质量直接上了一个台阶。

第三个坑是切块时把表格切碎。表格是强语义单元，切碎了检索就废了。我现在的策略是表格整体作为一个 chunk，哪怕它超过长度限制也不切，宁可让 embedding 模型处理长文本，也不破坏表格完整性。

第四个坑是没做解析质量监控。上线后文档源源不断进来，解析质量参差不齐，但没人知道。后来我加了一个简单的质量检查：解析后统计标题数量、表格数量、平均段落长度，异常值报警。这样能及时发现解析失败的文档，避免脏数据污染知识库。

6. 解析质量监控与持续优化

6.1 建立解析质量基线

RAG 系统上线后，PDF 解析不是一劳永逸的。新文档不断进来，解析质量会波动。我的做法是建立一个质量基线：选一批有代表性的文档作为"金标准"，人工标注正确的解析结果，然后每次调整解析参数或工具版本时，用这批文档跑一遍，对比输出和标注的差异。

差异指标可以量化：标题识别准确率、表格还原准确率、正文提取完整率。这三个指标能覆盖大部分解析质量问题。基线建立后，任何改动都要过这一关，避免"改了一个参数，修好了 A 文档，弄坏了 B 文档"。

6.2 用户反馈闭环

最直接的优化信号来自用户。当用户反馈"检索结果不对"时，别急着调检索，先看召回的 chunk 对应的原始 PDF 页面，检查解析是否正确。如果解析错了，问题在解析环节；如果解析对了但检索没召回，问题在检索环节。

我习惯把用户反馈的 bad case 收集起来，定期分析。如果发现某类文档解析问题集中，就针对性优化。这个闭环跑起来后，解析质量会持续提升，而不是上线即巅峰然后慢慢腐烂。

6.3 工具选型的再思考

pdf-inspector 不是唯一选择，市面上还有不少同类工具。选型时我建议关注这几点：是否支持 OCR 且保留坐标、表格还原能力、阅读顺序处理、可调参数丰富度、社区活跃度。没有完美的工具，关键是找到匹配你文档类型的那个。

我的实际做法是：主力工具用 pdf-inspector，遇到它处理不好的文档，用其他工具兜底，或者写针对性的后处理脚本。工具是死的，需求是活的，别被工具绑架。

最后分享一个我在实际项目里的小技巧：解析结果一定要存原始 Markdown，不要只存切好的 chunk。因为切块策略会变，embedding 模型会换，但原始 Markdown 是稳定的。存了原始 Markdown，以后想重新切块、重新 embedding 都方便，不用重新解析 PDF。这个习惯帮我省了无数次重跑解析的时间，尤其是那些 OCR 慢得要命的扫描件。