Docling v2 迁移指南：DocumentConverter、CLI 与 DoclingDocument 的完整用法解析

Docling v2 迁移指南：DocumentConverter、CLI 与 DoclingDocument 的完整用法解析

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

Docling v2 是一次面向多格式文档理解与转换的 API 重构：它统一了 CLI 的输入输出格式声明方式（--from/--to），重写了DocumentConverter的初始化模型（按格式白名单 + 按格式定制选项），并将所有文档导出能力从ConversionResult迁移到了新的通用文档表示DoclingDocument上。读完本文，你将掌握 v2 的 CLI 语法、DocumentConverter的完整配置方式、convert/convert_all的调用与错误处理语义，以及DoclingDocument的迭代、导出、JSON 持久化与重新加载、分块（Chunking）等核心实战能力，并了解这些 API 在源码中的真实实现位置。

Docling v2 带来什么

Docling v2 引入了三类新特性（见 docs/v2.md）：

1. 多格式理解与转换：支持 PDF、MS Word、MS PowerPoint、HTML 以及多种图片格式的解析与转换；
2. 通用文档表示：产出新的通用文档表示（即DoclingDocument），可以封装完整的文档层级结构（标题、正文、表格、图片等）；
3. 全新的 API 与 CLI：转换入口、格式声明、导出方式全部围绕新的文档模型重新设计。

从源码结构看，这一“新 API”的核心入口就是 DocumentConverter：它在初始化时维护allowed_formats（允许转换的输入格式白名单）与format_to_options（每个格式对应的FormatOption，包含 pipeline 类、pipeline 选项和文档后端），转换方法统一返回携带DoclingDocument的ConversionResult。

CLI 的语法变化

Docling v2 更新了命令行语法以支持多种格式。典型用法如下（与 docs/v2.md 中一致）：

# 将单个文件转换为 Markdown（默认输出） docling myfile.pdf # 将单个文件转换为 JSON 和 Markdown，并关闭 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 # 转换输入目录中所有受支持的文件，遇到第一个错误即中止 docling ./input/dir --output ./scratch --abort-on-error

相对 Docling v1 的关键变化：

• 移除了针对不同导出格式的独立开关，统一替换为--from（输入格式）与--to（输出格式）参数；
• 新增--abort-on-error：批处理转换中一旦遇到错误立即中止；
• 移除了原来针对 PDF 的--backend选项。

这些变化都能在 CLI 源码中得到印证。docling/cli/main.py 中定义了--from与--to两个多值选项；--to缺省时默认输出 Markdown，见 docling/cli/main.py#L1270-L1271。--abort-on-error在 docling/cli/main.py#L999-L1006 中实现，帮助文本明确其为“遇到第一个错误时中止处理”。

需要说明的是，v1 的--backend虽然被移除，但当前 CLI 以--pdf-backend的方式保留了 PDF 解析后端的选择能力，其取值为PdfBackend枚举（默认THREADED_DOCLING_PARSE），见 docling/cli/main.py#L924-L926。输入格式枚举InputFormat与输出格式枚举OutputFormat定义在 docling/datamodel/base_models.py#L97-L145，--from/--to接受的具体字符串取值即以这两个枚举为准。此外，当第一个参数不是子命令时，CLI 会通过 自定义 Typer 命令组 自动路由到convert命令，因此docling myfile.pdf这种“裸调用”形式依然可用。

设置 DocumentConverter：格式白名单与按格式定制

为了容纳多种输入格式，v2 改变了DocumentConverter的初始化方式：你可以在初始化时定义一份允许的格式列表（allowed_formats），并按格式提供自定义选项（format_options）。默认情况下所有受支持格式都被允许；若未提供format_options，则所有allowed_formats都会使用各自的默认值。

格式选项可以包含要使用的 pipeline 类、传给 pipeline 的选项以及文档后端。它们以格式专属类型提供，例如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 ## 默认初始化方式保持不变： # doc_converter = DocumentConverter() # 原先的 `PipelineOptions` 现在叫 `PdfPipelineOptions` pipeline_options = PdfPipelineOptions() pipeline_options.do_ocr = False pipeline_options.do_table_structure = True #... ## 自定义选项现在按格式定义。 doc_converter = ( DocumentConverter( # 下面所有参数都是可选的，内部有默认值。 allowed_formats=[ InputFormat.PDF, InputFormat.IMAGE, InputFormat.DOCX, InputFormat.HTML, InputFormat.PPTX, ], # 格式白名单，不匹配的文件会被忽略。 format_options={ InputFormat.PDF: PdfFormatOption( pipeline_options=pipeline_options, # pipeline 选项放这里。 backend=PyPdfiumDocumentBackend # 可选：选用其他后端 ), InputFormat.DOCX: WordFormatOption( pipeline_cls=SimplePipeline # 办公格式和 HTML 的默认值 ), }, ) )

提示：如果只使用默认配置，v2 的行为与 v1 完全一致。

从源码看，这一机制在 DocumentConverter.init中实现：

• allowed_formats为None时取list(InputFormat)，即全量受支持格式；
• format_to_options对每个允许的格式做“自定义选项优先，否则回落到默认选项”的填充，默认选项由内部映射表给出——例如 PDF 默认使用StandardPdfPipeline+ThreadedDoclingParseDocumentBackend，而 DOCX/PPTX/HTML/ODT 等办公与网页格式默认使用SimplePipeline，见 _get_default_option；
• FormatOption基类带有模型校验器：若未显式提供pipeline_options，会自动用pipeline_cls.get_default_options()填充，见 docling/document_converter.py#L103-L117。

BaseFormatOption的结构（pipeline_options与backend两个核心字段）定义在 docling/datamodel/base_models.py#L74-L85。完整的多格式转换示例可参考 docs/examples/run_with_formats.py，它演示了混合文件列表（PDF、DOCX、PPTX、HTML、图片等）的转换与导出；PDF 侧的 pipeline 与后端组合示例见 docs/examples/custom_convert.py。更深入的转换参数请查看参考文档 docs/reference/document_converter.md 与 docs/reference/pipeline_options.md。

转换文档：convert 与 convert_all

v2 简化了向DocumentConverter提供输入的方式，并为转换方法重新命名以获得更清晰的语义：你可以直接用单个文件、文件列表或DocumentStream对象发起转换，而无需先构造DocumentConversionInput对象。

• DocumentConverter.convert现在负责转换单个文件输入（此前为convert_single）；
• DocumentConverter.convert_all现在负责一次转换多个文件（此前为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参数，你可以控制转换在首次遇到问题时是抛出异常，还是“韧性”地把所有文件都转换完、将错误反映在每个文件的转换状态中。默认情况下，任何错误会立即抛出并中止转换（此前 v1 会吞掉异常）。

conv_results_iter = doc_converter.convert_all(input_files, raises_on_error=False) # 原先为 `convert`

源码层面，convert 内部把单个 source 包装成单元素列表后委托给 convert_all；raises_on_error=True时，只要某个结果的status不在SUCCESS/PARTIAL_SUCCESS中就会抛出ConversionError并携带各ErrorItem的错误信息（见 docling/document_converter.py#L576-L591）。转换状态枚举ConversionStatus（pending/started/failure/success/partial_success/skipped）定义在 docling/datamodel/base_models.py#L88-L94。此外，convert/convert_all均标注了@validate_call严格校验，并额外接受max_num_pages、max_file_size、page_range等限制参数，可用于控制单文档页数上限与页码范围。

访问文档结构：DoclingDocument

v2 同样简化了访问与导出转换结果的方式。通用文档表示现在以DoclingDocument对象的形式出现在转换结果中。DoclingDocument提供了一组便捷的 API，用于构建、迭代和导出文档内容：

import pandas as pd from docling_core.types.doc import TextItem, TableItem conv_result: ConversionResult = doc_converter.convert("https://arxiv.org/pdf/2408.09869") # 原先为 `convert_single` ## 查看转换后的文档结构： conv_result.document.print_element_tree() ## 按阅读顺序迭代元素（含层级级别）： 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(doc=conv_result.document) print(table_df.to_markdown()) elif ...: #...

⚠️废弃说明：对 Docling v1 文档表示（conv_result.legacy_document）的支持已被完全移除，现在必须使用 v2 格式：

## 使用更新后的 v2 文档表示 conv_result.document

导出为 JSON、Markdown、Doctags

注意：v1 中ConversionResult上的所有render_...方法已在 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") # 原先为 `convert_single` ## 导出为所需格式： print(json.dumps(conv_res.document.export_to_dict())) print(conv_res.document.export_to_markdown()) print(conv_res.document.export_to_document_tokens())

⚠️废弃说明：legacy_document的导出路径已被完全移除。作为历史参考，v1 的旧写法如下（在当前版本中会失败）：

## ❌ 已移除：此 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())

从 CLI 侧的实现可以看到当前支持的完整导出面：export_documents 中依次处理了 JSON、YAML、HTML（含按页拆分）、Text、Markdown、Doctags、WebVTT、DocLang、DCLX 与 Chunks 等格式，其中 Markdown 导出为空时还会回写ErrorItem并把状态置为FAILURE。这印证了 v2 的设计：导出逻辑全部收敛在DoclingDocument之上，ConversionResult只负责携带文档与转换元数据。

从 JSON 重新加载 DoclingDocument

你可以把DoclingDocument以 JSON 格式保存到磁盘，并在之后重新加载：

# 保存到磁盘： doc: DoclingDocument = conv_res.document # 由转换结果产出 with Path("./doc.json").open("w") as fp: fp.write(json.dumps(doc.export_to_dict())) # 用 `export_to_dict` 保证一致性 # 从磁盘加载： with Path("./doc.json").open("r") as fp: doc_dict = json.loads(fp.read()) doc = DoclingDocument.model_validate(doc_dict) # 用标准 pydantic API 填充文档

由于DoclingDocument是 Pydantic 模型，export_to_dict与model_validate构成一对可逆操作：先导出为 dict 保证序列化口径一致，再用标准的 Pydantic API 反序列化。这意味着DoclingDocument的 JSON 文件可以作为文档资产独立流转、入库或作为下游任务（如分块、检索、再加工）的中间格式，而无需重新运行转换管线。

Chunking：面向检索的分块

Docling v2 定义了新的分块基类体系：

• BaseMeta：chunk 元数据；
• BaseChunk：包含 chunk 文本与元数据；
• BaseChunker：分块器基类，从DoclingDocument产出 chunks。

在此之上，v2 提供了更新后的HierarchicalChunker实现，它利用新的DoclingDocument，输出更丰富的 chunk 格式，包括：

• 用于定位（grounding）的相应 doc items；
• 适用的标题（headings），作为上下文；
• 适用的题注（captions），作为上下文。

分块的完整用法（包括HybridChunker、LineBasedTokenChunker以及分块依赖的安装方式）请参阅 Chunking 概念文档；CLI 中--to chunks选项也内置了hybrid/hierarchical两种分块器，见 docling/cli/main.py#L177-L180。相关示例还包括 docs/examples/hybrid_chunking.ipynb 与 docs/examples/trivial_chunking.py。

迁移要点小结

整体上，v2 的迁移路径是清晰的：如果你只依赖默认配置，代码可以原样保留；一旦需要定制，把“全局 pipeline 选项”思维切换为“按格式定制”思维（format_options），并把所有文档访问与导出改走conv_result.document，即可完成从 v1 到 v2 的平滑过渡。更多 API 细节可继续参考 docs/reference/docling_document.md 与 docs/reference/cli.md。

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