首页 / Docs /

Docling 完整开发与技术参考手册

核心概览 (TL;DR)

Docling 是 100% 免费开源（MIT）的文档解析引擎，支持将 PDF、DOCX、PPTX、XLSX、扫描件及音频转换为结构化 Markdown、HTML 和 JSON。
内置版面视觉分析、阅读顺序恢复及针对复杂跨行合并单元格的 TableFormer v2 表格模型。
支持多语言 OCR，集成了 RapidOCR、Tesseract（tesserocr）、EasyOCR 和 OcrMac。
100% 本地运行零遥测，原生支持离线局域网（Air-Gapped）、REST API（docling-serve）与 MCP 智能体服务（docling-mcp）。

1. 架构总览

Docling 是由 IBM Research 开发并在 LF AI & Data 托管的开源文档解析框架。与单纯提取纯文本的工具不同，Docling 通过模块化流水线理解页面几何布局、检测目标包围盒（Bounding Box）、精准还原复杂合并单元格表格，并输出专为大模型和向量数据库设计的标准结构。

2. 安装与环境配置

Docling 支持在 Windows、macOS 和 Linux 上的 Python 3.9 至 3.14（64位）环境中运行：

bash — 标准安装

$pip install docling

2.1 Windows 10/11 C++ 生成工具配置指南

在 Windows 系统上必须使用 64 位 Python。当通过 pip 编译 tesserocr 等原生 C++ 扩展时，需要安装 Microsoft Visual C++ 14.0+：

Visual C++ Build Tools 安装命令

以管理员身份打开 PowerShell 运行：

PS>winget install Microsoft.VisualStudio.2022.BuildTools --override "--passive --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

推荐方案（无需安装 C++ 编译器）： 使用 Astral uv 直接下载预编译好的二进制 Wheel 包：

powershell — astral uv

PS>uv add docling

3. 快速上手

python — 基础转换代码

from docling.document_converter import DocumentConverter

converter = DocumentConverter()
result = converter.convert("https://arxiv.org/pdf/2408.09869")
print(result.document.export_to_markdown()[:500])

4. DoclingDocument 核心数据模型

DoclingDocument 是解析输出的核心对象，维护完整的章节、表格、代码块及图表对象树结构，包含精确的页面坐标，可通过 result.document.export_to_json() 导出无损 JSON。

5. 处理流水线与 Granite Docling 视觉模型

5.1 Granite Docling VLM 配置

python — granite docling vlm

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import VlmPipelineOptions
from docling.document_converter import DocumentConverter, PdfFormatOption

vlm_options = VlmPipelineOptions()
vlm_options.vlm_model = "granite_docling"

converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=vlm_options)}
)
result = converter.convert("document.pdf")

6. OCR 引擎与性能调优

6.1 禁用 OCR 加速数字 PDF 处理（速度提升10倍）

python — 禁用 ocr

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.document_converter import DocumentConverter, PdfFormatOption

pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = False  # 数字 PDF 极速处理

converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)}
)
result = converter.convert("report.pdf")

7. 多格式提取 (Excel XLSX, PowerPoint PPTX, CAD 图纸与音频)

python — 解析 excel 与 ppt

from docling.document_converter import DocumentConverter

converter = DocumentConverter()
excel_res = converter.convert("financial.xlsx")
print(excel_res.document.export_to_markdown())

8. RAG 结构化分块 (`HybridChunker`)

python — hybridchunker 用于 RAG

from docling.document_converter import DocumentConverter
from docling.chunking import HybridChunker

converter = DocumentConverter()
result = converter.convert("paper.pdf")

chunker = HybridChunker(max_tokens=512, merge_peers=True)
for chunk in chunker.chunk(result.document):
    print(chunk.meta.headings, chunk.text[:80])

9. GPU 批量加速与性能调优

python — gpu 批量加速

from docling.datamodel.accelerator_options import AcceleratorDevice, AcceleratorOptions
from docling.datamodel.pipeline_options import ThreadedPdfPipelineOptions

accel = AcceleratorOptions(device=AcceleratorDevice.CUDA)
pipe_opts = ThreadedPdfPipelineOptions(accelerator_options=accel, page_batch_size=8)

10. 框架集成 (LangChain 与 LlamaIndex)

python — langchain docling

from langchain_docling import DoclingLoader

loader = DoclingLoader(file_path="report.pdf")
docs = loader.load()

11. VLM 视觉模型目录

模型标识	出品方	核心优势	CLI 参数
granite_docling	IBM Research	极高精度的 PDF 版面几何理解与 OCR	--vlm-model granite_docling
smoldocling	Hugging Face / IBM	针对 CPU 环境高度优化的轻量模型	--vlm-model smoldocling

12. FastAPI 服务部署 (`docling-serve`) 与 MCP 协议

bash — docker docling-serve

$docker run -p 5001:5001 ghcr.io/docling-project/docling-serve:latest

12.1 Claude Desktop 的 MCP 服务配置

json — claude_desktop_config.json

{
  "mcpServers": {
    "docling": {
      "command": "uvx",
      "args": ["--from=docling-mcp", "docling-mcp-server"]
    }
  }
}

13. 企业级安全与物理隔离网络部署 (Air-Gap)

bash — 离线环境模型预下载

export DOCLING_CACHE_DIR="/opt/docling_models"
docling-tools models download --all

export HF_HUB_OFFLINE=1
export DOCLING_CACHE_DIR="/opt/docling_models"
docling document.pdf --to md

14. 开发者诊断与常见报错解决

错误提示 / 现象	根本原因	解决方案
cannot import name 'BoundingBox'	Docling v2 模块结构迁移。	修改引用为 from docling_core.types.doc import BoundingBox。
RapidOCR: text detection result empty	扫描件图片分辨率过低。	设置 pipeline_options.images_scale = 2.0 提升 DPI。
检查安装版本	版本校验。	在终端执行 docling --version。

15. CLI 命令行参数速查表

命令行参数	类型	默认值	功能说明
--to	md, json, html, doctags	md	指定目标导出文档格式。
--no-ocr	Boolean	-	禁用 OCR 模块以大幅加速原生数字 PDF 转换。
--version	Flag	-	输出当前安装的 Docling 版本号。