只有橘子复杂 PDF 文档怎么结构化？pdf-document-layout-analysis 搭建教程
做知识库、RAG 检索或者文档审批系统时，很容易遇到同一个拦路虎：拿到手的是扫描版 PDF，有标题、有正文、有表格、有公式、有页眉页脚，有的还两栏排版。常规的 pdfplumber、PyPDF2 只能把字符串抽出来，版式信息基本全废。后来我找到 pdf-document-layout-analysis 这个开源项目，花了一个晚上搭建起来，成功把复杂 PDF 的版面区域（标题、正文、图片、表格、公式）自动切分并输出为结构化 JSON。这篇文章我会把搭建过程、模型原理、踩坑记录和落地用法一起写清楚。
全文核心就是一句话：用深度学习模型识别 PDF 的视觉版面，再把版面区域映射成结构化数据。如果你正在做知识库解析、试卷结构化、论文拆解，或者任何需要"把 PDF 变成 JSON"的场景，这篇可以直接照抄。
1. 为什么 PDF 结构化难，以及这个工具到底解决什么
1.1 解析 PDF 不等于读文本
几乎所有做过 PDF 解析的人都有这种体验：文本能抽出来，但结构全碎了。
PDF 文件本质上是一堆图形指令的集合——文字、线条、色块由坐标定位，没有 HTML 里那种 <h1>、<p>、<table> 的概念。所以在复杂排版下，解析出来的内容顺序是乱的，标题和正文混在一起，表格线框丢失，公式变成乱码。
举个例子：一篇论文 PDF 首页，常见结构是"标题 → 作者 → 摘要 → 关键词 → 正文两栏 → 图注 → 表头"。用 pdfplumber 按坐标从上到下读，得到的是三个线性流，根本没有"哪个区域是标题、哪个区域是摘要"的语义信息。
更麻烦的是扫描版 PDF。它本质是图片，连文本层都没有，不 OCR 的话抽出来的就是空字符串。而扫描件里的表格、公式，即使 OCR 也只能得到无排版的纯文字。
所以"PDF 结构化"真正要解决的不是"能不能读出字"，而是能不能告诉下游程序"每个字属于哪个语义区域"。这就是版面分析（Layout Analysis）的核心任务。
1.2 pdf-document-layout-analysis 的定位与输出结果
pdf-document-layout-analysis 是 GitHub 上的一个开源项目，专门做 PDF 版面分析。它把每个页面图像输入给目标检测模型，模型输出不同区域的边界框（Bounding Box），每个框带一个类别标签。
项目支持的区域类别通常包括下面几大类：
| 类别 | 说明 | 用途 |
|---|---|---|
| 段落（Paragraph） | 连续正文块 | 章节切分、文本抽取 |
| 标题（Title） | 各级标题 | 文档目录生成、层级重建 |
| 图片 | 图区域 | 图表抽取 |
| 表格 | 表格区域 | 表格结构识别 |
| 公式 | 独立公式或内联公式 | 数学公式抽取、LaTeX 还原 |
| 页眉页脚 | 页面的头尾区域 | 去噪 |
| 页码 | 页码区域 | 去噪 |
输出结果是一个结构化 JSON，每个区域包含类别、置信度和四个坐标值（x1, y1, x2, y2），以及单词级别的词框列表。拿到这个 JSON，就相当于把一个页面变成了语义标注图：哪块是标题，哪块是正文，哪块是公式，都清清楚楚。
也就是说：这个工具解决的是"文本 + 位置 + 语义"三合一的难题。它是很多 PDF 处理 pipeline 的第一环，后面再接 OCR 识别、表格还原、文本清洗，就能得到高质量的文档结构化结果。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 搭建前的准备：环境、依赖与模型权重获取
2.1 环境要求和安装步骤
项目基于 PyTorch 和 Detectron2，如果你之前只玩过文本类 NLP 模型，这个环境需要多花一点耐心。
我实测的环境配置如下：
- Ubuntu 20.04 / CentOS 7+（Windows 也能跑，但建议 WSL2 配合 GPU）
- Python 3.8 ~ 3.10
- CUDA 11.3+，显存推荐 8GB 以上
- PyTorch 1.10+（建议 1.13 或 2.0 系列）
- detectron2
建议用 conda 建一个独立的 Python 环境，别直接装到 base 里：
bash复制conda create -n layout python=3.9
conda activate layout
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
pip install detectron2 -f https://dl.fbaipublicfiles.com/detectron2/wheels/cu118/torch1.13/index.html
pip install pdf2image opencv-python pytesseract pillow tqdm
其中 pdf2image 依赖 poppler，Ubuntu 下要单独安装：
bash复制apt install poppler-utils
macOS 则用：
bash复制brew install poppler
pytesseract 还额外需要 Tesseract OCR 引擎和语言包：
bash复制apt install tesseract-ocr tesseract-ocr-chi-sim tesseract-ocr-eng
这步很容易漏。如果后续跑代码报 tesseract not found，大概率就是缺了这一步。
2.2 模型权重的获取与常见卡点
环境准备好了，接下来是从 Hugg