Docling 完整指南：5 分钟把 PDF、DOCX 变成 AI 能读懂的结构化数据

Docling 完整指南：5 分钟把 PDF、DOCX 变成 AI 能读懂的结构化数据

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

Docling（Docling 文档解析）是一个开源文档解析库，由 Linux 基金会孵化，核心任务是把 PDF、DOCX、XLSX、HTML、EPUB 等二十多种格式统一转成结构化的DoclingDocument——带标题层级、表格结构、公式、图像位置的中间表示，可以直接喂给 RAG 和 LLM 流水线。

这篇文章不讲功能清单，而是用一个具体任务带你走完全程：你拿到一批产品文档（含扫描版 PDF 和带表格的 PDF），要给团队的 RAG 知识库供货。从安装到产出可入库的文本块，一共四步。

这张图展示了 Docling 的整体链路：所有格式进入同一条解析流水线，产出统一的文档模型，再按需导出成 Markdown、无损 JSON、DocLang XML，或直接接入下游 AI 应用。对你来说这意味着一件事——无论上游文件长什么样，下游代码只面对一种数据。

任务准备：Docling 安装步骤与两种上手方式

用 uv 或 pip 二选一，macOS、Linux、Windows 都支持，注意 Python 需要 3.10 及以上：

# 安装 Docling（官方推荐使用 uv，pip 同样可用） uv tool install docling

装完就有两个入口：

• 命令行：最快出活。docling 报告.pdf会在当前目录生成一个.md文件，结构化的内容直接可读；
• Python API：推荐用于集成。DocumentConverter一个类包打天下，转换结果上挂着一堆导出方法。

# Python 最小示例：把本地文件转成结构化文档 from docling.document_converter import DocumentConverter converter = DocumentConverter() result = converter.convert("产品手册.pdf") print(result.document.export_to_markdown()) # 带标题层级的 Markdown

注意两点：首次转换会自动从 HuggingFace 下载布局、表格等模型，离线机器要提前把模型挪进缓存；另外 CLI 默认走的是 CPU 上的标准流水线，后面会讲怎么调。

基础解析：扫描版 PDF 用 OCR，表格 PDF 单独开增强

这是整个任务里唯一的"重头戏"。Docling 处理 PDF 的默认流水线默认开着 OCR 和表格结构提取（对应参数do_ocr和do_table_structure，在PdfPipelineOptions里），但按你的文档类型裁剪一下配置，效果和时间都更好：

# 为"扫描件 + 表格报告"这类文档定制解析流水线 from docling.datamodel.backend_options import PdfPipelineOptions from docling.document_converter import DocumentConverter, Format options = PdfPipelineOptions( do_ocr=True, # 扫描件必须开 OCR（需系统装好 Tesseract） do_table_structure=True, # 保留表格行列结构，而不是拍平成文字 do_formula_enrichment=True, # 报告里有公式时，识别并转成 LaTeX ) converter = DocumentConverter(allowed_formats=[Format.PDF], pipeline_options=options) result = converter.convert("季度报告.pdf")

三个实用提醒：

• 扫描件：OCR 默认用 Tesseract，系统里要装好 Tesseract 二进制；多语言场景（如中英文混排）可以在 OCR 选项里指定语言组合，参考 docs/concepts/OCR.md。
• 表格密集的报告：标准表格结构模型之外，仓库提供了 Granite Vision 视觉模型方案，见示例 docs/examples/granite_vision_table_structure.py。
• 追求更高保真：CLI 可以直接切到视觉语言模型（VLM）流水线，把整页当图像"读"出来：docling --pipeline vlm --vlm-model granite_docling 文件.pdf。质量上限更高，但速度慢一个量级，适合精而不在多。

进阶：用置信度评分给 RAG 入库做质量门控

批量转换最怕的不是"全部失败"，而是"大部分成功、少数悄悄出错"。Docling 从 v2.34 起在转换结果上附带confidence字段，对每一页和整份文档给出 0.0–1.0 的分数，并折算成 POOR / FAIR / GOOD / EXCELLENT 四级评级，覆盖布局识别、OCR、文本解析三个维度。

这张图是置信度报告的实际形态：你可以看到文档级和每页的分数与评级。对批量任务的直接用法就是设一条阈值——评级低于 FAIR 的文件自动进人工复核队列，其余直接入库，不用逐份人肉检查。

接入 RAG：Docling 分块与向量库对接

文档转出来只是半成品，RAG 还要分块。Docling 内置分层分块器（HierarchicalChunker），按文档自身的标题结构切，块与块之间保留章节元数据，比"每 N 个 token 一刀切"的朴素分块语义完整得多：

# 分块 + 组装进向量库：每块带上章节路径元数据 from docling.chunking import HierarchicalChunker chunks = list(HierarchicalChunker().chunk(result.document)) for c in chunks: text = c.text meta = c.meta.model_dump() # 含页码、章节层级等定位信息 # embeddings_client.add(text, metadata=meta) # 换成你的向量库调用

分块的更多玩法（混合分块、按 token 上限裁剪）见 docs/concepts/chunking.md 和 docs/examples/hybrid_chunking.ipynb。

这张图展示了 Docling 在 AI 生态里的位置：解析出的文档模型可以直连 LangChain、LlamaIndex、Haystack 等框架的加载器，也能通过 MCP 服务器让任何 Agent 直接调用解析能力。也就是说，"文档 → 向量库"这条路上它只占第一棒，但这一棒的质量决定整条链路的上限。

实战结论：适合谁，不适合谁，以及几个坑

真正值得用的三点：

• 本地运行：所有解析在本地完成，敏感文档不出内网，这对合规场景是硬性价值；
• 无损 JSON：export_to_json()是结构完整保真的序列化，可以当持久化格式反复消费；
• 可服务化：团队规模变大时，用docling-serve把解析能力部署成 HTTP 服务（见 docs/usage/api_server/），客户端不用各自装模型。

局限也要心里有数：

• 默认流水线在 CPU 上处理大 PDF 较慢，OCR + 表格 + 公式全开更慢——官方建议只开自己用的功能；GPU 部署参考 docs/usage/gpu.md 和 docs/examples/run_with_accelerator.py；
• OCR 依赖系统安装的 Tesseract；首次运行要联网下模型，完全离线环境需提前准备缓存；
• 手写体、严重模糊的扫描件，模型也救不回来，仍要人工兜底。

人群速判：

• RAG 开发者、要批量结构化文档的数据工程师——适合，这正是它的主场；
• 合规、金融行业需要文档不出域的团队——适合；
• 只需要纯文本、不在乎结构的场景——不必，轻量工具更快。

从 docs/getting_started/quickstart.md 可以按图索骥地补全所有细节，docs/examples/目录下还有按场景组织的示例代码，需要哪段抄哪段。

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