docling 文档解析如何用 3 行代码跑通：PDF、DOCX 转 Markdown 并直接喂给 RAG

docling 文档解析如何用 3 行代码跑通：PDF、DOCX 转 Markdown 并直接喂给 RAG

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

给大模型喂一份 PDF，输出却乱成一锅粥？问题多半不在模型，而在输入没处理好。docling 是一个本地优先的文档解析工具：把 PDF、DOCX、HTML、扫描件、音频等 20 多种格式解析成统一的 DoclingDocument，再用一行代码导出 Markdown 或 JSON，直接用于 RAG 和生成式 AI 工作流。

1. 3 分钟装好 docling 并完成第一次转换

安装只需一条命令，Python 3.10 及以上即可，macOS、Linux、Windows 都支持。装完用 CLI 转换，不用写一行代码：

pip install docling docling report.pdf # 同目录下生成 report.pdf.md

想要更结构化的入口，就用 Python API。官方推荐的写法在 quickstart 文档：

2. 解析结果落到哪：认识统一中间表示 DoclingDocument

不管输入是 PDF 还是 DOCX，docling 输出的都是同一个数据结构DoclingDocument。它用 pydantic 定义，把文档拆成三类东西：

• 内容项：texts（段落、标题、公式）、tables、pictures、key_value_items；
• 结构树：body存正文的阅读顺序，furniture存页眉页脚这类"家具"；
• 位置信息：每个条目可带 bounding box 和来源页，方便溯源和可视化。

可以把它理解成一份文档的"结构化病历"：正文、表格、图片各归其位，顺序由body树决定，而不是靠猜。下面这张图展示了一个 DOCX 转换后前几页在树里的嵌套关系：

字段细节见 DoclingDocument 概念文档。

3. 转换器内部在做什么：backend、pipeline 与模型的分工

DocumentConverter对外只暴露一个convert()，内部按三步走：

• backend负责"读懂原始格式"，每种格式一个实现，代码都在 docling/backend/，例如 PDF 有pdf_backend.py，DOCX 有msword_backend.py；
• pipeline负责"跑模型编排"，PDF 的标准管道会依次做版面分析、阅读顺序、表格结构识别等，实现见 docling/pipeline/；
• 模型全部本地运行，布局、表格结构（TableFormer）、OCR 各用一个专门模型。

这套路由是可参数化的：同一份 PDF，你也可以换 backend 或换一套 pipeline 选项，架构总览图在 architecture 文档：

4. 扫描件、代码、公式、图片：开关怎么开

默认管道只跑布局、阅读顺序和表格结构，速度最快。遇到扫描页、论文里的公式、图片图表时，再按需打开 enrichment 开关（这些功能默认关闭，因为每个都会增加模型推理时间）：

from docling.document_converter import DocumentConverter, PdfFormatOption from docling.datamodel.base_models import InputFormat from docling.datamodel.pipeline_options import PdfPipelineOptions opts = PdfPipelineOptions() opts.do_ocr = True # 扫描页文字识别 opts.do_formula_enrichment = True # 公式转 LaTeX opts.do_code_enrichment = True # 代码块识别语言 conv = DocumentConverter(format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=opts)}) print(conv.convert("report.pdf").document.export_to_markdown())

常见开关速查（完整说明在 enrichments 文档）：

另外，CLI 也支持整页走 VLM 的路线：docling --pipeline vlm --vlm-model granite_docling FILE，用的是 258M 参数的 GraniteDocling 模型，同样本地跑。

5. 给 RAG 喂数据：docling 的分块怎么做

导出 Markdown 再手动切块是一种办法，但更干净的方式是直接对DoclingDocument做原生分块，每个 chunk 自带标题上下文。HybridChunker按文档结构切分并控制 token 数：

from docling.chunking import HybridChunker doc = conv.convert("report.pdf").document chunker = HybridChunker() for chunk in chunker.chunk(doc): print(chunker.contextualize(chunk)) # 带上下文的 RAG 片段

分块器都继承自BaseChunker，你可以替换成自定义实现，代码入口在 docling/chunking/，概念说明见 chunking 文档。对接 LangChain、LlamaIndex、Haystack 时用的就是这套接口，现成示例在 docs/integrations/ 目录（langchain.md、llamaindex.md等），仓库 examples 里还有完整的 RAG notebook，如docs/examples/rag_langchain.ipynb。

6. 选型与常见坑清单

按场景选路线：

• 只要 Markdown/JSON：默认标准管道，或 CLI 直接跑，最快；
• 版面复杂、想省得调参：VLM 管道（GraniteDocling 258M，本地推理）；
• 批量服务化：用 docling-serve 起 API 服务，或经 MCP server 接给任意 Agent，说明见 docs/usage/api_server/；
• 敏感数据、断网环境：所有模型默认本地运行，用docling-tools models download预取到~/.cache/docling/models，再配DOCLING_ARTIFACTS_PATH指定离线模型目录，方法在 advanced_options 文档。

几个高频坑（来源：FAQ）：

1. Python 3.9 在 2.70.0 版本起不再支持，请用 3.10+；
2. 旧版二进制 Office 格式（.doc/.xls/.ppt，97–2004）需要本机装 LibreOffice；
3. 音频/视频解析（WAV、MP3、MP4 等）要加asr依赖，视频还要ffmpeg；
4. Docker 或无图形界面的 Linux 报libGL.so.1缺失，是opencv-python与opencv-python-headless冲突，二选一；
5. macOS x86_64 老 Intel 机器上装 PyTorch 有版本坑，按 FAQ 锁定numpy<2.0.0即可。

收尾：从一份文档到一座文档库

docling 的定位很克制：把"文档进、结构化数据出"这一件事做扎实——格式路由交给 backend，模型编排交给 pipeline，下游要分块、要导出、要接框架，都走DoclingDocument这一个出口。从单文件转换到批量服务，再到接给 Agent，仓库里 docling/service_client/ 和 CLI 工具（docling-tools）已经给出了现成路径，可以按自己的规模逐步上量。

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