Docling 文档解析：让 200 份 PDF 变 RAG 就绪只需 3 行代码

Docling 文档解析：让 200 份 PDF 变 RAG 就绪只需 3 行代码

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

当 200 份 PDF 要喂进 RAG，先确认 Docling 管哪一段

你的知识库里有 200 份 PDF——一半是原生文本，一半是扫描件，里面还有合并单元格、公式和图片。如果只想要能塞进向量库的文本，纯文本抽取工具不够用：表格被打散、阅读顺序丢失、结构全平铺。Docling 文档解析做的事，就是把 PDF、DOCX、HTML 甚至音频解析成统一的 DoclingDocument，再从这一份中间表示导出 Markdown、无损 JSON 或 RAG 分块，全程本地运行，文件不出机器。

一条安装命令加 3 行代码，跑通第一次 PDF 转 Markdown

执行pip install docling装完；首次运行会自动下载版面与表格识别模型，所以第一次明显更慢，之后都快了。然后只需这几行：

from docling.document_converter import DocumentConverter source = "tests/data/pdf/sources/2206.01062.pdf" # 换成你自己的文件路径 converter = DocumentConverter() result = converter.convert(source) # 解析一次，得到统一中间表示 print(result.document.export_to_markdown()[:500]) # 立刻看到带标题层级的 Markdown

复制运行后，终端里会看到##开头的标题层级、表格行和图片占位——说明版面模型已经把页面上"哪块是标题、哪块是正文、哪块是表格"分好了，而不是按坐标顺序把字糊在一起。不写 Python 也行：docling convert report.pdf会在当前目录直接产出.md。

DoclingDocument：解析一次，导出 Markdown、JSON 和 RAG 分块

Docling 和纯 OCR 工具的差异就藏在这个中间表示里。输入到输出的链路是：后端解析（docling-parse 抽取 PDF 文本层）→ 版面检测（标题/正文/表格/图片的边界框）→ 表格结构识别（还原行列网格）→ OCR 兜底（位图区域补文字）→ 按阅读顺序拼成一棵树。

第一个值得深挖的能力是"一份表示、多种导出"。导出的 JSON 不是文本转储，页码、边界框、表格单元格都在里面，适合存档和二次开发；同一份解析结果给人看的 Markdown 和给程序用的 JSON 可以各取所需。

# 同一份解析结果按用途导出，解析只做一次 result = converter.convert("report.pdf") result.document.save_as_markdown("report.md") # 给 RAG 或人读 result.document.save_as_markdown("report.txt", strict_text=True) # 纯文本，去掉全部标记 result.document.save_as_json("report.json") # 无损存档，含页码和坐标

第二个能力是理解结构的 RAG 分块。按字数切 Markdown 迟早把表格和列表切碎；HybridChunker 直接对 DoclingDocument 分块：先按文档层级切，再用你 embedding 模型的 tokenizer 校准长度——超长的拆、过短的合并，表格跨块时自动重复表头，行含义不丢。

from docling.chunking import HybridChunker # tokenizer 必须和 embedding 模型对齐，分块长度才有意义 chunker = HybridChunker( max_tokens=512, tokenizer="sentence-transformers/all-MiniLM-L6-v2", ) for chunk in chunker.chunk(dl_doc=result.document): # contextualize 会补上标题路径等上下文，输出可直接入向量库 print(chunker.contextualize(chunk)[:80])

不想写 Python 的话，docling convert --to chunks report.pdf直接出 JSONL，--chunks-type可在 hybrid 和 hierarchical 间切换。默认配置和常见调优的差异：

高频报错速查：我们当时也踩过的 5 个坑

• 现象：首次运行挂很久甚至超时。原因：在自动下载模型权重。解决：docling convert --artifacts-path ./models report.pdf，把模型指到预下载目录，之后秒级启动。
• 现象：扫描版 PDF 出来的 Markdown 是空的。原因：页面没有文本层，默认 OCR 只处理位图区域。解决：docling convert --ocr-mode full_page scan.pdf。
• 现象：表格合并单元格识别错乱。原因：默认表格模型对这种版面不敏感。解决：docling convert --table-structure-engine docling_tableformer_v2 report.pdf。
• 现象：.doc、.xls等老 Office 格式解析失败。原因：97-2004 的旧二进制格式需要 LibreOffice 中转。解决：装系统的 libreoffice 包即可。
• 现象：HybridChunker 报 "Token indices sequence length" 警告。原因：模型没问题，这是已知的误报（官方 FAQ 确认过），可以无视。

接下来往哪走：分块调优、VLM 管道和更多格式

• 想系统调分块策略，看 docs/concepts/chunking.md 和可运行的 docs/examples/hybrid_chunking.ipynb，源码在 docling/chunking/。
• 想对复杂版面要更高精度，换 VLM 管道：docling convert --pipeline vlm --vlm-model smoldocling report.pdf，可选模型清单见 docs/usage/vision_models.md。
• 手上是 USPTO 专利 XML、XBRL 财报这类特殊格式，查 docs/usage/supported_formats.md，仓库里每种格式都有独立 backend。

一句话定位：Docling 是把异构文档变成生成式 AI 可用结构数据的本地预处理层——解析一次，处处导出。

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