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 文档）：
| 开关 | 作用 | 典型场景 |
|---|---|---|
do_ocr | 识别扫描页/图片中的文字 | 扫描发票、旧报纸 |
do_code_enrichment | 识别代码块并标注语言 | 技术白皮书 |
do_formula_enrichment | 公式提取为 LaTeX，HTML 导出时渲染 | 学术论文 |
do_picture_classification | 图片分类（图表类型、流程图、logo 等） | 行业报告 |
do_picture_description | 用视觉模型给图片写描述，可本地也可连远程 API | 图片问答、RAG |
另外，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）：
- Python 3.9 在 2.70.0 版本起不再支持，请用 3.10+；
- 旧版二进制 Office 格式（.doc/.xls/.ppt，97–2004）需要本机装 LibreOffice；
- 音频/视频解析（WAV、MP3、MP4 等）要加
asr依赖，视频还要ffmpeg； - Docker 或无图形界面的 Linux 报
libGL.so.1缺失，是opencv-python与opencv-python-headless冲突，二选一； - 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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
