Docling v2

有什么新内容

Docling v2 引入了几个新功能：

理解并转换PDF、MS Word、MS Powerpoint、HTML和多种图像格式
生成一个新的、通用的文档表示，可以封装文档层次结构
带来了全新的API和CLI

Docling v2中的更改

命令行接口

我们更新了Docling v2的命令行语法，以支持多种格式。以下是一些示例。

# 将单个文件转换为Markdown（默认）
docling myfile.pdf

# 将单个文件转换为Markdown和JSON，且不使用OCR
docling myfile.pdf --to json --to md --no-ocr

# 将输入目录中的PDF文件转换为Markdown（默认）
docling ./input/dir --from pdf

# 将输入目录中的PDF和Word文件转换为Markdown和JSON
docling ./input/dir --from pdf --from docx --to md --to json --output ./scratch

# 将输入目录中所有支持的文件转换为Markdown，但在遇到第一个错误时中止
docling ./input/dir --output ./scratch --abort-on-error

Docling v1 的显著变化：

不同导出格式的独立开关已被移除，并被 --from 和 --to 参数取代，以分别定义输入和输出格式。
新的 --abort-on-error 将在遇到错误时立即中止任何批量转换
PDF的 --backend 选项已被移除

设置一个 `DocumentConverter`

为了适应多种输入格式，我们改变了设置 DocumentConverter 对象的方式。现在，您可以在 DocumentConverter 初始化时定义一个允许的格式列表，并根据需要为每种格式指定自定义选项。默认情况下，所有支持的格式都是允许的。如果您不提供 format_options，则默认将用于所有 allowed_formats。

格式选项可以包括要使用的管道类、提供给管道的选项以及文档后端。它们以格式特定的类型提供，例如 PdfFormatOption 或 WordFormatOption，如下所示。

from docling.document_converter import DocumentConverter
from docling.datamodel.base_models import InputFormat
from docling.document_converter import (
    DocumentConverter,
    PdfFormatOption,
    WordFormatOption,
)
from docling.pipeline.simple_pipeline import SimplePipeline
from docling.pipeline.standard_pdf_pipeline import StandardPdfPipeline
from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.backend.pypdfium2_backend import PyPdfiumDocumentBackend

## Default initialization still works as before:
# doc_converter = DocumentConverter()


# previous `PipelineOptions` is now `PdfPipelineOptions`
pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = False
pipeline_options.do_table_structure = True
#...

## Custom options are now defined per format.
doc_converter = (
    DocumentConverter(  # all of the below is optional, has internal defaults.
        allowed_formats=[
            InputFormat.PDF,
            InputFormat.IMAGE,
            InputFormat.DOCX,
            InputFormat.HTML,
            InputFormat.PPTX,
        ],  # whitelist formats, non-matching files are ignored.
        format_options={
            InputFormat.PDF: PdfFormatOption(
                pipeline_options=pipeline_options, # pipeline options go here.
                backend=PyPdfiumDocumentBackend # optional: pick an alternative backend
            ),
            InputFormat.DOCX: WordFormatOption(
                pipeline_cls=SimplePipeline # default for office formats and HTML
            ),
        },
    )
)

注意: 如果你仅使用默认设置，所有内容将与 Docling v1 保持一致。

以下示例单元展示更多选项：

转换文档

我们简化了输入到DocumentConverter的方式，并为转换方法重新命名以获得更好的语义。您现在可以直接使用单个文件、输入文件列表或DocumentStream对象调用转换，而无需先构造DocumentConversionInput对象。

DocumentConverter.convert 现在转换单个文件输入（之前是 DocumentConverter.convert_single）。
DocumentConverter.convert_all 现在一次可以转换多个文件（之前是 DocumentConverter.convert）。

...
from docling.datamodel.document import ConversionResult
## 转换单个文件（来自 URL 或本地路径）
conv_result: ConversionResult = doc_converter.convert("https://arxiv.org/pdf/2408.09869") # 之前是 `convert_single`

## 同时转换多个文件：

input_files = [
    "tests/data/html/wiki_duck.html",
    "tests/data/docx/word_sample.docx",
    "tests/data/docx/lorem_ipsum.docx",
    "tests/data/pptx/powerpoint_sample.pptx",
    "tests/data/2305.03393v1-pg9-img.png",
    "tests/data/pdf/2206.01062.pdf",
]

# 直接将文件或流的列表传递给 `convert_all`
conv_results_iter = doc_converter.convert_all(input_files) # 之前是 `convert`

通过 raises_on_error 参数，您还可以控制在首次遇到问题时转换是否应引发异常，或者先弹性地转换所有文件，并在每个文件的转换状态中反映错误。默认情况下，任何错误都会立即引发并中止转换（之前是抑制异常）。

...
conv_results_iter = doc_converter.convert_all(input_files, raises_on_error=False) # previously `convert`

访问文档结构

我们简化了您访问和导出转换后的文档数据的方式。我们的通用文档表示现在可以在转换结果中作为一个 DoclingDocument 对象使用。 DoclingDocument 提供了一整套 API，用于构建、迭代和导出文档中的内容，如下面所示。

conv_result: ConversionResult = doc_converter.convert("https://arxiv.org/pdf/2408.09869") # previously `convert_single`

## Inspect the converted document:
conv_result.document.print_element_tree()

## Iterate the elements in reading order, including hierachy level:
for item, level in conv_result.document.iterate_items():
    if isinstance(item, TextItem):
        print(item.text)
    elif isinstance(item, TableItem):
        table_df: pd.DataFrame = item.export_to_dataframe()
        print(table_df.to_markdown())
    elif ...:
        #...

注意：虽然它已被弃用，但您仍然可以使用Docling v1文档表示，现有的表示为：

conv_result.legacy_document # 提供之前ExportedCCSDocument类型的表示

导出为 JSON、Markdown、Doctags

注意: 所有 render_... 方法在 ConversionResult 中已在 Docling v2 中移除，现在可以在 DoclingDocument 中找到：

DoclingDocument.export_to_dict
DoclingDocument.export_to_markdown
DoclingDocument.export_to_document_tokens

conv_result: ConversionResult = doc_converter.convert("https://arxiv.org/pdf/2408.09869") # previously `convert_single`

## Export to desired format:
print(json.dumps(conv_res.document.export_to_dict()))
print(conv_res.document.export_to_markdown())
print(conv_res.document.export_to_document_tokens())

注意: 尽管它已被弃用，但您可以仍然导出Docling v1 JSON格式。这可以通过与DoclingDocument类型相同的方法实现：

## 导出旧版文档表示为所需格式，以兼容v1:
print(json.dumps(conv_res.legacy_document.export_to_dict()))
print(conv_res.legacy_document.export_to_markdown())
print(conv_res.legacy_document.export_to_document_tokens())

重新加载存储为JSON的 `DoclingDocument`

您可以使用以下代码将DoclingDocument以JSON格式保存和重新加载到磁盘：

# Save to disk:
doc: DoclingDocument = conv_res.document # produced from conversion result...

with Path("./doc.json").open("w") as fp:
    fp.write(json.dumps(doc.export_to_dict())) # use `export_to_dict` to ensure consistency

# Load from disk:
with Path("./doc.json").open("r") as fp:
    doc_dict = json.loads(fp.read())
    doc = DoclingDocument.model_validate(doc_dict) # use standard pydantic API to populate doc

分块

Docling v2 定义了新的基础类用于分块：

BaseMeta 用于块元数据
BaseChunk 包含块文本和元数据，以及
BaseChunker 用于分块器，从 DoclingDocument 生成块。

此外，它提供了一个更新的 HierarchicalChunker 实现，该实现利用了新的 DoclingDocument 并提供了一种新的、更丰富的块输出格式，包括：

用于基础的相应文档项
任何适用的上下文标题
任何适用的上下文标题

例如，可以查看 Chunking usage。