docling 完全指南：3 行代码完成多格式文档解析与 Markdown 转换-平芜编程栈

docling 完全指南：3 行代码完成多格式文档解析与 Markdown 转换

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

如果你正准备搭一套 RAG 系统，而语料里混着扫描版论文、Word 合同和 Excel 台账，第一件事大概就是把它们统一变成带结构的 Markdown。docling 做的就是这件事：它是一个支持多格式文档解析与文档转换的开源工具，把 PDF、DOCX、HTML 等输入统一读入同一个 DoclingDocument 数据模型，再按需导出为 Markdown、HTML 或无损 JSON。以下内容基于仓库内 README、docs 目录与源码整理，类名与参数均可在对应路径中找到。

3 行代码跑通第一次 docling 入门转换

安装很简单，pip install docling（需要 Python 3.10 及以上）。最小可运行示例如下：

from docling.document_converter import DocumentConverter converter = DocumentConverter() result = converter.convert("thesis_scan.pdf") print(result.document.export_to_markdown())

输出的是一段带标题层级、列表与表格结构的 Markdown 字符串，官方 README 里给出的样例输出以## Docling Technical Report[...]开头。不想写 Python 的话，终端里执行docling 文件名也能直接在当前目录生成 .md 文件。

格式支持速览：从 PDF 解析到音视频

完整清单见 docs/usage/supported_formats.md，这里按输入格式归纳：

输入格式	常用输出	典型场景
PDF（含扫描件）	Markdown、JSON、HTML	学术论文解析、扫描件 OCR
DOCX / PPTX / XLSX	Markdown、JSON	办公报告摘要与入库
HTML、Markdown、AsciiDoc、LaTeX	Markdown、DocLang	网页抓取内容、排版文档转换
PNG / JPEG / TIFF / WEBP	Markdown、JSON	图片扫描件数字化
WAV / MP3、MP4 等音视频	文本、WebVTT	会议录音、视频字幕转写
USPTO / JATS / XBRL 等 XML	Markdown、JSON	专利、期刊、财报解析

输出侧除 Markdown 与 HTML 外，还有无损 JSON、Doctags 以及面向 RAG 的 Chunks（JSONL），也就是说分块这一步可以交给 docling 自己做。

工作原理：一套统一文档模型，几条可插拔管道

设计思路是“后端 + 管道”两层：每个格式有自己的后端（位于 docling/backend/）负责把原始文件读出来，而管道负责跑模型阶段。PDF 走 StandardPdfPipeline，依次完成布局分析、OCR、表格结构等步骤，且支持线程化流水线并行；Word、HTML 这类本身就有结构信息的格式走 SimplePipeline，直读即可。两条线的终点都是同一个 DoclingDocument，它用树状结构记录页面、段落、表格与图片，导出方法就挂在上面。文本条目还带有置信度，机制见 docs/concepts/confidence_scores.md。

docling 表格识别与 OCR 的关键开关一览表

PDF 相关格式的行为由PdfPipelineOptions控制，定义在 docling/datamodel/pipeline_options.py，几个最值得知道的开关：

参数	作用	何时开启
`do_ocr`	对页面执行 OCR，默认 True	扫描件必须开；纯数字 PDF 可关掉以省时
`do_table_structure`	检测表格并重建行列结构，默认 True	财报、论文表格类文档保持开启
`do_formula_enrichment`	公式识别并转 LaTeX，默认 False	解析含公式的学术论文时开启
`do_code_enrichment`	面向代码块的感知处理，默认 False	文档含大量代码或终端输出时开启
`images_scale`	生成图片的缩放倍数，默认 1.0	需要放大图表给下游视觉模型时调高

只针对 PDF 调整配置：

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

OCR 引擎与表格模型细节还可以继续调ocr_options、table_structure_options两个子对象。

docling RAG 集成：接 LangChain 与 LlamaIndex

LangChain 侧有官方扩展 DoclingLoader，加载文档几行搞定：

from langchain_docling import DoclingLoader loader = DoclingLoader(file_path="thesis_scan.pdf") pages = loader.load()

LlamaIndex 侧拆成 Reader 与 Node Parser 两个组件，前者读文件，后者利用文档结构切出适合 embedding 的节点：

from llama_index.readers.docling import DoclingReader documents = DoclingReader().load_data(file_path="report.docx")

集成文档见 docs/integrations/langchain.md。除此之外，docling 自带 docling/chunking/ 分块模块，可以直接对 DoclingDocument 生成层级式分块，配合 JSONL 输出即可跳过下游框架的分块逻辑。仓库 examples 目录下的 rag_langchain.ipynb、rag_llamaindex.ipynb 给了完整可复现的 RAG 链路。

生产环境建议：本地化、敏感数据与批量重试

全程本地运行：模型权重下载到本地，推理在自有 CPU/GPU 上完成，适合处理敏感材料；离线环境可把预置权重目录配到artifacts_path，避免运行时联网。
批量容错：用convert_all(paths, raises_on_error=False)，单个文件失败不会中断整批，失败结果里带ConversionResult.status与错误明细，方便记录后重试。
资源护栏：convert与convert_all都支持max_num_pages、max_file_size，防止个别超大文件拖垮进程；官方建议在批处理系统里再叠加文档级超时保护。
横向扩展：docling-serve 可以把转换能力部署成 HTTP 服务（见 docs/usage/api_server/），配套的客户端 SDK 在 docling/service_client/。
模型增强是可选的：图片描述、图表理解等 enrichment 能力按需开启，详见 docs/usage/enrichments.md。

常见问题

扫描版 PDF 转出来为什么没有文字或很乱？扫描件没有文本层，需要保证do_ocr=True且 OCR 引擎（Tesseract、EasyOCR 等）已正确安装；管道会对缺文本层的页面自动走 OCR 补全。

导出的 Markdown 里表格结构不对，怎么排查？表格是由结构模型重建的，合并单元格多的复杂表格容易出错。可以换更准的表格模型（table_structure_options），或开启generate_page_images=True后调用TableItem.get_image()导出表格原图，人工核对。

遇到 docling 不支持的格式会怎样？不会静默通过：默认raises_on_error=True时直接抛 ConversionError；关掉后结果状态为 SKIPPED 或 FAILURE，并在 errors 里写明原因。用allowed_formats白名单还能提前拦掉无关格式。