企业官网建设流程全解析

5 分钟跑通 docling 文档解析：PDF 表格处理指南

【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling

docling 文档解析把 PDF、DOCX、HTML、CSV、图片甚至音视频统一转换成同一个结构化文档模型，服务于要把文档喂给大模型的开发者。它跑在本地机器上，文档内容不经过第三方服务，处理过程你自己控制。

🎯 docling 解决哪几类文档处理的痛

做文档入库、RAG（检索增强生成，即让模型基于你自己的文档回答问题）之前，通常会卡在三类地方：

• 表格全乱：PDF 里的十列表格复制出来顺序错位，多栏排版按行硬读，前后两段话的语义混在一起。
• 扫描件搜不到字：扫描版文档没有内嵌文本层，Ctrl+F 搜不到任何内容，想复制也没有可复制的东西。
• 格式各写各的：一个项目里同时出现 PDF、DOCX、HTML、CSV，用不同的库分别解析，输出的结构对不上，下游代码要按格式写分支。

🔍 docling 怎么解析一份文档

入口是 DocumentConverter，它按文件扩展名查表，决定用哪个 backend（负责读原始字节的解析器）和哪条 pipeline（负责编排各处理阶段的流水线）。以 PDF 为例，pipeline 走三个阶段：布局模型先框出每块文字、图片和表格的位置；OCR（光学字符识别，即把图像里的字读成文本）负责从没有文本层的图像区域补出文字；表格结构模型把表格区域还原成行列和合并单元格。最终产出一个统一的 DoclingDocument（可理解为"任何格式文档的中间表示"），从它可以导出 Markdown、JSON、HTML 或纯文本。官方架构如下图：

✅ docling 支持哪些格式

边界说清楚：docling 做文档解析，不做排版还原和文档编辑；扫描件必须先变成图片文件再输入。完整清单见官方文档：支持格式。

🐍 docling 最小可运行示例

装完包，下面 15 行内跑通转换和导出：

# 安装：pip install docling from docling.document_converter import DocumentConverter converter = DocumentConverter() # 默认配置，全格式允许 result = converter.convert("report.pdf") # 支持本地路径或 URL doc = result.document # 统一的 DoclingDocument print(doc.export_to_markdown()) # 导出 Markdown print(doc.export_to_html()) # 导出 HTML doc.save_as_json("out.json") # 无损 JSON 序列化

把report.pdf换成 docx、html 文件同样成立，路由是自动的。result.status还会告诉你这次是 SUCCESS 还是 PARTIAL_SUCCESS；批量处理时传raises_on_error=False可以跳过坏文件继续跑。

🛠 docling 进阶技巧：OCR 开关、表格调优、本地部署

切换 OCR 引擎（docling OCR 开关）。默认按环境自动选引擎；要固定某个引擎（比如中文场景用 RapidOCR），在 pipeline 选项里指定：

from docling.datamodel.base_models import InputFormat from docling.datamodel.pipeline_options import PdfPipelineOptions, RapidOcrOptions from docling.document_converter import DocumentConverter, PdfFormatOption opts = PdfPipelineOptions(do_ocr=True, ocr_options=RapidOcrOptions()) converter = DocumentConverter(format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=opts)})

表格识别调优（docling 表格识别）。表格结构识别默认开启。如果导出后相邻两列内容被并成一列，可以关闭"预测结构回贴 PDF 原始文本单元格"这一步，让表格模型自己决定格子边界：

from docling.datamodel.pipeline_options import PdfPipelineOptions, TableStructureV2Options opts = PdfPipelineOptions(table_structure_options=TableStructureV2Options(do_cell_matching=False))

下面是一张论文 PDF 里表格区域被还原成结构化表格后裁剪出的样子：

本地部署（docling 本地部署）。模型默认首次运行时自动下载；离线或内网环境提前下载好并指向本地目录：

docling-tools models download # 预下载全部默认模型 export DOCLING_ARTIFACTS_PATH=/data/docling-models # 程序指向本地模型目录

也可以改用 PDF 管道选项 里的artifacts_path参数在代码里指定。

⚠️ 常见坑与规避

1. 扫描件导出没有文字现象：扫描版 PDF 导出的 Markdown 是空的或几乎为空。 原因：文档没有内嵌文本层，而系统里没装任何 OCR 引擎，OCR 阶段被跳过。 解法：pip install "docling[easyocr]"装上引擎，并保持do_ocr=True（默认开启）。

2. 首次转换特别慢或直接失败现象：第一次 convert 卡很久，最后报网络相关错误。 原因：首用会自动从模型仓库下载布局、表格结构等模型权重。 解法：离线环境先执行docling-tools models download，再用artifacts_path指向本地模型目录。

3. 表格多列被并成一列现象：导出表格里相邻两列的内容串到同一个格子里。 原因：默认do_cell_matching会把预测结构回贴到 PDF 原始单元格，合并单元格处容易错位。 解法：换成TableStructureV2Options(do_cell_matching=False)，由表格模型自身输出格子。

4. DOC、XLS、PPT 报格式错误现象：旧版 Office 文件转换直接失败。 原因：97–2004 的二进制格式需要先转成 OOXML，这一步依赖系统里的 LibreOffice。 解法：安装 LibreOffice 后重新转换；新项目尽量用 docx/xlsx/pptx。

先跑一遍 docs/examples 目录里的示例脚本，跑通后再按上面的选项定制自己的管道。

【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling