docling

Docling 文档解析器

Docling 是一个文档解析库，可将 PDF、Word 文档、PowerPoint、图像及其他格式转换为具备高级版面理解能力的结构化数据。

快速开始

基本文档转换：

from docling.document_converter import DocumentConverter

source = "https://arxiv.org/pdf/2408.09869"  # URL, Path, or BytesIO
converter = DocumentConverter()
result = converter.convert(source)
print(result.document.export_to_markdown())

核心概念

DocumentConverter

文档转换的主要入口。支持各种输入格式和转换选项。

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

# Basic converter (all formats enabled)
converter = DocumentConverter()

# Restricted formats
converter = DocumentConverter(
    allowed_formats=[InputFormat.PDF, InputFormat.DOCX]
)

# Custom pipeline options
pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.do_table_structure = True

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)
    }
)

ConversionResult

所有转换操作都会返回一个 ConversionResult，其中包含：

• document：解析后的 DoclingDocument
• status：ConversionStatus.SUCCESS、PARTIAL_SUCCESS 或 FAILURE
• errors：转换过程中遇到的错误列表
• input：源文档信息

from docling.datamodel.base_models import ConversionStatus

result = converter.convert("document.pdf")

if result.status == ConversionStatus.SUCCESS:
    markdown = result.document.export_to_markdown()
    html = result.document.export_to_html()
    data = result.document.export_to_dict()

支持的格式

输入格式

• 文档：PDF、DOCX、PPTX、XLSX
• 标记语言：HTML、Markdown、AsciiDoc
• 数据：CSV、JSON（Docling 格式）
• 图像：PNG、JPEG、TIFF、BMP、WEBP
• 音频：WAV、MP3
• 视频文本：WebVTT
• 特定架构：USPTO XML、JATS XML、METS-GBS

输出格式

• Markdown：export_to_markdown() 或 save_as_markdown()
• HTML：export_to_html() 或 save_as_html()
• JSON：export_to_dict() 或 save_as_json()（注意：没有 export_to_json() 方法）
• 文本：export_to_text()、export_to_markdown(strict_text=True) 或 save_as_markdown(strict_text=True)
• DocTags：export_to_doctags() 或 save_as_doctags()

常见模式

单文件转换

from docling.document_converter import DocumentConverter

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

# Export to different formats
markdown = result.document.export_to_markdown()
html = result.document.export_to_html()
json_data = result.document.export_to_dict()

# Or save directly to file
result.document.save_as_markdown("output.md")
result.document.save_as_html("output.html")
result.document.save_as_json("output.json")

批量处理

有关 convert_all() 的详情，请参阅 references/batch.md。

URL 转换

converter = DocumentConverter()
result = converter.convert("https://example.com/document.pdf")

二进制流转换

from io import BytesIO
from docling.datamodel.base_models import DocumentStream

with open("document.pdf", "rb") as f:
    buf = BytesIO(f.read())

source = DocumentStream(name="document.pdf", stream=buf)
result = converter.convert(source)

特定格式的选项

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

# Configure PDF-specific options
pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.ocr_options.lang = ["en", "es"]
pipeline_options.do_table_structure = True
pipeline_options.generate_page_images = True

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)
    }
)

资源限制

converter = DocumentConverter()

# Limit file size (bytes) and page count
result = converter.convert(
    "large_document.pdf",
    max_file_size=20_971_520,  # 20 MB
    max_num_pages=100
)

文档分块

有关 RAG 集成，请参阅 references/chunking.md。

DoclingDocument 结构

DoclingDocument 是表示已解析内容的 Pydantic 模型：

# Access document structure
doc = result.document

# Content items (lists)
doc.texts         # TextItem instances (paragraphs, headings, etc.)
doc.tables        # TableItem instances
doc.pictures      # PictureItem instances
doc.key_value_items  # Key-value pairs

# Structure (tree nodes)
doc.body          # Main content hierarchy
doc.furniture     # Headers, footers, page numbers
doc.groups        # Lists, chapters, sections

# Iterate all elements in reading order
for item, level in doc.iterate_items():
    print(f"{'  ' * level}{item.label}: {item.text[:50]}")

高级功能

OCR 配置

from docling.datamodel.pipeline_options import (
    PdfPipelineOptions,
    EasyOcrOptions,
    TesseractOcrOptions,
    TesseractCliOcrOptions,
    OcrMacOptions,
    RapidOcrOptions
)

# EasyOCR (default)
pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.ocr_options = EasyOcrOptions(lang=["en", "de"])

# Tesseract
pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.ocr_options = TesseractOcrOptions(lang=["eng", "deu"])

# RapidOCR
pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.ocr_options = RapidOcrOptions()

表格提取选项

from docling.datamodel.pipeline_options import (
    PdfPipelineOptions,
    TableFormerMode
)

pipeline_options = PdfPipelineOptions()
pipeline_options.do_table_structure = True

# Use cell matching (map to PDF cells)
pipeline_options.table_structure_options.do_cell_matching = True

# Or use predicted cells
pipeline_options.table_structure_options.do_cell_matching = False

# Choose accuracy mode
pipeline_options.table_structure_options.mode = TableFormerMode.ACCURATE

页面图像

pipeline_options = PdfPipelineOptions()
pipeline_options.generate_page_images = True  # Needed for HTML export with images

# Export with embedded images
result.document.save_as_html(
    "output.html",
    image_mode=ImageRefMode.EMBEDDED
)

错误处理

from docling.datamodel.base_models import ConversionStatus

result = converter.convert("document.pdf")

if result.status == ConversionStatus.SUCCESS:
    print("Conversion successful")
elif result.status == ConversionStatus.PARTIAL_SUCCESS:
    print("Partial conversion:")
    for error in result.errors:
        print(f"  {error.error_message}")
else:  # FAILURE
    print("Conversion failed:")
    for error in result.errors:
        print(f"  {error.error_message}")

批量处理中的错误处理：

# Continue processing on errors
results = converter.convert_all(
    ["doc1.pdf", "doc2.pdf", "doc3.pdf"],
    raises_on_error=False
)

for result in results:
    if result.status == ConversionStatus.SUCCESS:
        result.document.save_as_markdown(f"{result.input.file.stem}.md")
    else:
        print(f"Failed: {result.input.file}")

门槛检查

在将输出视为完整内容或传递给下游环节（RAG、评估、存储）之前：

1. 从 convert() 获取 result，或遵循 references/batch.md 中的批处理顺序。
2. 通过条件：result.status 为 ConversionStatus.SUCCESS；或者为 PARTIAL_SUCCESS，并且你已阅读 result.errors，且明确接受任务使用部分输出；或者已处理 FAILURE（除非有意为之，否则失败时不要导出或分块）。
3. 只有满足以上条件后，才能调用 references/chunking.md 中的 export_to_*、save_as_* 或分块器。

对于 convert_all：只有当每个输入都对应一个结果，且在写入输出之前对每个 result.status 都进行了分类时，才算通过（参见 references/batch.md）。

CLI 用法

# Basic conversion
docling document.pdf

# Convert to specific output
docling --to markdown document.pdf

# With custom model path
docling --artifacts-path /path/to/models document.pdf

# Using VLM pipeline
docling --pipeline vlm --vlm-model granite_docling document.pdf

参考文档

• 解析选项 - DocumentConverter 初始化、特定格式的选项、OCR 配置
• 批量处理 - convert_all()、错误处理、并发模式
• 分块 - HierarchicalChunker、HybridChunker、RAG 集成
• 输出格式 - export_to_markdown()、export_to_html()、export_to_dict()、文档结构

关键类型

• DocumentConverter：主要转换类
• ConversionResult：包含文档和状态的转换结果
• DoclingDocument：统一的文档表示（Pydantic 模型）
• InputFormat：支持的输入格式枚举
• ConversionStatus：SUCCESS、PARTIAL_SUCCESS、FAILURE
• PdfPipelineOptions：PDF 流水线的配置
• ImageRefMode：EMBEDDED、REFERENCED、PLACEHOLDER

集成示例

LangChain

from docling.document_converter import DocumentConverter
from langchain_text_splitters import MarkdownTextSplitter

converter = DocumentConverter()
result = converter.convert("document.pdf")
markdown = result.document.export_to_markdown()

splitter = MarkdownTextSplitter(chunk_size=1000)
chunks = splitter.split_text(markdown)

LlamaIndex

from docling.document_converter import DocumentConverter
from docling.chunking import HybridChunker
from llama_index.core import Document

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

chunker = HybridChunker()
chunks = list(chunker.chunk(result.document))

documents = [
    Document(text=chunk.text, metadata=chunk.meta.export_json_dict())
    for chunk in chunks
]

备注

• Docling 使用同步 API（不原生支持异步）
• 模型会在首次使用时自动下载（可提前下载）
• 支持在隔离网络环境中本地运行
• 支持使用 GPU 加速 OCR 和表格检测
• 默认模型在 CPU 上运行；使用 GPU 需要进行配置