Docling DocumentConverter API 详解：从格式注册到批量转换的文档处理核心

Docling DocumentConverter API 详解从格式注册到批量转换的文档处理核心【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/doclingDocumentConverter是 Docling 将 PDF、Office、HTML、Markdown、图片、音视频等多源文档统一转换为DoclingDocument的主入口。本文以官方 API 参考页 docs/reference/document_converter.md 中列出的核心组件DocumentConverter、ConversionResult、ConversionStatus、FormatOption、InputFormat及各格式选项类为主线结合 docling/document_converter.py 的源码实现完整讲解其构造参数、三种转换方法、输入源类型、错误处理策略与管线缓存机制帮助你在生产环境中正确配置和调用 Docling 的文档转换能力。1. 参考文档覆盖的组件全景docs/reference/document_converter.md 是通过 mkdocstrings 自动生成的docling.document_converter模块 API 参考它显式列出以下成员组件类型职责DocumentConverter类转换主入口负责格式分发、管线管理与批量转换ConversionResult类单个文档的转换结果状态、错误、文档、计时等ConversionStatus枚举转换状态PENDING / STARTED / FAILURE / SUCCESS / PARTIAL_SUCCESS / SKIPPEDFormatOption类格式选项基类绑定「管线类 后端 管线选项」InputFormat枚举全部受支持的输入格式标识PdfFormatOption/ImageFormatOption类PDF 与图片格式的默认选项走StandardPdfPipelineWordFormatOption/PowerpointFormatOption类DOCX / PPTX 格式选项走SimplePipelineMarkdownFormatOption/AsciiDocFormatOption/HTMLFormatOption类标记语言格式选项StandardPdfPipeline/SimplePipeline类两类核心转换管线重模型管线 vs 轻量管线其中两个核心枚举与基类的真实定义位于 docling/datamodel/base_models.pyBaseFormatOptionL74-L85所有FormatOption的基类声明pipeline_options与backend字段并允许arbitrary_types_allowedConversionStatusL88-L94六个状态值的str枚举用于标记每个文档的转换结局InputFormatL97-L130枚举了 30 余种输入格式从PDF、DOCX、IMAGE到XML_USPTO、LATEX、EMAIL、AUDIO、VIDEO等。2. 构造 DocumentConverterallowed_formats 与 format_optionsDocumentConverter的构造函数docling/document_converter.py接受两个参数from docling.document_converter import DocumentConverter from docling.datamodel.base_models import InputFormat # 1) 默认构造所有支持的格式均被允许 converter DocumentConverter() # 2) 白名单只允许 PDF 与 DOCX converter DocumentConverter( allowed_formats[InputFormat.PDF, InputFormat.DOCX] ) # 3) 为特定格式定制管线选项 from docling.datamodel.pipeline_options import PdfPipelineOptions from docling.document_converter import PdfFormatOption converter DocumentConverter( format_options{ InputFormat.PDF: PdfFormatOption(pipeline_optionsPdfPipelineOptions()), } )构造过程中的三个关键行为均可从源码确认默认格式表补全对每个allowed_formats中的格式若format_options未提供自定义选项则调用_get_default_option(format)docling/document_converter.py填充该格式的默认FormatOption。该函数内置了一张完整的「格式 → 默认选项」映射表例如InputFormat.PDF映射到PdfFormatOption()InputFormat.JSON_DOCLING映射到使用DoclingJSONBackend的SimplePipeline选项。IMAGE 格式归一化L387-L410若你为InputFormat.IMAGE传入了使用其他后端如旧的 PDF 后端的选项Docling 会发出DeprecationWarning并自动将其改写为ImageFormatOption使用ImageDocumentBackend同时保留你传入的pipeline_cls、pipeline_options与backend_options——这是为了保证旧代码的向后兼容。管线缓存容器初始化实例持有initialized_pipelines字典以(管线类, 选项哈希)为键缓存已构建的管线实例详见第 6 节。3. FormatOption 体系管线、后端与后端选项的三元绑定参考文档列出的PdfFormatOption、WordFormatOption、PowerpointFormatOption、MarkdownFormatOption、AsciiDocFormatOption、HTMLFormatOption、ImageFormatOption都是FormatOptiondocling/document_converter.py的子类。FormatOption本身新增了两个字段class FormatOption(BaseFormatOption): pipeline_cls: Type[BasePipeline] # 该格式使用的管线类 backend_options: Optional[BackendOptions] None # 该格式的后端级选项它还有一个model_validator当pipeline_options未显式提供时自动调用self.pipeline_cls.get_default_options()填充管线默认选项——这就是为什么PdfFormatOption()空参构造也能直接工作。各格式选项的绑定关系可归纳为三类依据 docling/document_converter.py 中的子类定义类别格式选项管线后端重模型管线PdfFormatOption、ImageFormatOption、MetsGbsFormatOptionStandardPdfPipelineThreadedDoclingParseDocumentBackend/ImageDocumentBackend/MetsGbsDocumentBackend轻量结构化管线WordFormatOption、PowerpointFormatOption、MarkdownFormatOption、AsciiDocFormatOption、HTMLFormatOption、ExcelFormatOption等SimplePipeline各自的专用后端如MsWordDocumentBackend、HTMLDocumentBackend多媒体管线AudioFormatOption、VideoFormatOptionAsrPipeline/VideoPipelineNoOpBackend内容直接由管线处理部分格式的选项类携带专属的backend_options类型用于向解析后端传递细粒度配置例如WordFormatOption.backend_options是MsWordBackendOptionsHTMLFormatOption.backend_options是HTMLBackendOptionsPdfFormatOption.backend_options是PdfBackendOptionsLatexFormatOption携带LatexBackendOptionsEpubFormatOption携带EpubBackendOptions。一个值得注意的实现细节是HTMLFormatOption.backend_options_for_inputL177-L190当以本地文件路径作为输入时它会自动把源文件路径注入HTMLBackendOptions.source_uri使 HTML 后端能够解析相对路径引用的图片等资源——这正是「后端选项随输入源动态适配」的典型范例。完整格式支持情况含 DOC/XLS/PPT 旧二进制格式需要 LibreOffice、音频视频需要asrextra 等前提见 docs/usage/supported_formats.md。4. 四种输入源类型convert/convert_all的source参数类型为Union[Path, str, DocumentStream, HttpSource]均通过 Pydantic 的validate_call(configConfigDict(strictTrue))做严格校验docling/document_converter.py输入类型说明Path本地文件路径str本地路径或 HTTP(S) URLDocling 自动下载DocumentStream内存流来自docling_core.types.io携带name与字节流HttpSource见下文URL 与其专属请求头的捆绑体HttpSource定义在 docling/datamodel/base_models.py包含url与headers两个字段。convert方法另有一个headers参数用于 URL 输入源的全局请求头两者合并规则在 docling/datamodel/document.py 中实现逐源HttpSource的 headers 覆盖批量级headers按 key 合并即{**batch_headers, **source.headers}。5. 三个转换方法convert、convert_all、convert_string5.1 单文档转换 convertconverter DocumentConverter() # 本地文件 result converter.convert(path/to/document.pdf) print(result.document.export_to_markdown()) # URL result converter.convert(https://example.com/paper.pdf) # 内存流 from io import BytesIO from docling.datamodel.base_models import DocumentStream buf BytesIO(bhtmlbodyHello/body/html) stream DocumentStream(namepage.html, streambuf) result converter.convert(stream)convert的完整参数docling/document_converter.py参数默认值含义source必填单文档源Path/str/DocumentStream/HttpSourceheadersNoneURL 输入时的请求头对HttpSource被其自带 headers 按 key 覆盖raises_on_errorTrue为True时首个非SUCCESS/PARTIAL_SUCCESS结果即抛出ConversionError为False时错误被记录在ConversionResult中max_num_pagessys.maxsize单文档页数上限超出则不转换max_file_sizesys.maxsize文件字节数上限超限时该源被判为POLICY类策略拒绝page_rangeDEFAULT_PAGE_RANGE要转换的页码区间实现上convert是convert_all的单元素封装内部以source[source]调用convert_all并取第一个结果。5.2 批量转换 convert_allconvert_alldocling/document_converter.py返回Iterator[ConversionResult]参数与convert一致但source是可迭代对象from pathlib import Path paths list(Path(docs/).glob(*.pdf)) for result in converter.convert_all(paths, max_file_size20 * 1024 * 1024): print(result.input.file.name, result.status) print(result.document.export_to_markdown()[:100])错误处理细节L573-L599raises_on_errorTrue时遇到状态不是SUCCESS/PARTIAL_SUCCESS的结果会抛出ConversionError消息中包含input.file与状态值若结果携带errors各error_message会以分号拼接附在消息末尾。异常通过__cause__链接底层原始异常例如加密 PDF 会链接PdfiumError调用方可据此做失败分类若迭代未产出任何结果且raises_on_errorTrue抛出「文件格式不可识别或不在允许列表内」的ConversionError。5.3 字符串转换 convert_stringconvert_stringdocling/document_converter.py仅支持InputFormat.MD、InputFormat.HTML与InputFormat.XML_DOCLANG三种格式内部将字符串包成DocumentStream后复用convertfrom docling.datamodel.base_models import InputFormat result converter.convert_string( # Title\nSome text., formatInputFormat.MD ) result converter.convert_string( h1Title/h1pSome text./p, formatInputFormat.HTML, namemy_page, )规则细节name缺省时使用时间戳%Y-%m-%d_%H-%M-%S若name未带扩展名会按格式自动补上.md/.html/.dclg.xml传入其他格式直接抛ValueError。5.4 批处理与并发doc_batch_size / doc_batch_concurrency底层_convert方法L676-L712揭示了批量执行的真正机制所有输入先被chunkify按settings.perf.doc_batch_size分批当settings.perf.doc_batch_concurrency 1且doc_batch_size 1时通过ThreadPoolExecutor(max_workersdoc_batch_concurrency)并发处理每个批次否则顺序处理并逐条打印耗时日志。也就是说批量并发度由全局settings.perf配置驱动而不是convert_all的参数——调整这两项即可控制吞吐。6. 管线初始化与实例级缓存每个格式最终映射到一条管线。_get_pipelinedocling/document_converter.py的查找逻辑从format_to_options取该格式的FormatOption读出pipeline_cls与pipeline_options用create_pipeline_options_hash(pipeline_options)来自 docling/utils/pipeline_cache.py对管线选项做哈希以(pipeline_cls, options_hash)作为缓存键在全局_PIPELINE_CACHE_LOCK保护下命中则复用已有管线实例未命中才构造pipeline_cls(pipeline_options...)并写入缓存。这意味着同一个DocumentConverter实例在处理成百上千个同格式文档时只构建一次例如一次重量级的StandardPdfPipeline避免重复加载模型而不同管线选项会产生不同的哈希从而各缓存一份独立实例。initialize_pipeline(format)L429-L447则提供一个显式的「预热」接口——在真正转换前校验/构建某格式的管线构建失败抛ConversionError本地模型文件缺失时可能抛FileNotFoundError适合在服务启动阶段做快速失败检查。7. ConversionResult 与 ConversionStatus7.1 ConversionStatus 六态定义于 docling/datamodel/base_models.py状态含义PENDING初始状态ConversionAssets字段默认值STARTED转换已启动SUCCESS全部成功PARTIAL_SUCCESS部分成功如部分页面失败FAILURE失败含无管线可用、输入无效等SKIPPED被跳过——典型场景是格式不在allowed_formats白名单内_process_document在 docling/document_converter.py 中记录POLICY类错误并置为SKIPPED7.2 ConversionResult 的字段与错误分类助手ConversionResult继承自ConversionAssetsdocling/datamodel/document.py、L590-L597字段包括class ConversionResult(ConversionAssets): input: InputDocument # 输入文档元信息 assembled: AssembledUnit # 组装中间产物 # 继承自 ConversionAssets # version: DoclingVersion # 转换所用 Docling 版本 # timestamp: str | None # 保存时间戳 # status: ConversionStatus # errors: list[ErrorItem] # 结构化错误列表 # pages: list[Page] # timings: dict[str, ProfilingItem] # 各阶段计时 # confidence: ConfidenceReport # 置信度报告 # document: DoclingDocument # 转换产物本体ConversionAssets提供了一组面向运维监控的错误分类助手L411-L432has_errors(categoryNone)是否存在任意或指定FailureCategory的错误has_timeout_errors()是否存在TIMEOUT类错误has_inference_errors()是否存在INFERENCE_FAILURE类错误模型推理失败;has_parse_errors()是否存在BACKEND_FAILURE类错误后端解析失败。在批量场景下这些方法可以让你区分「模型超时导致的偶发失败」与「文件本身损坏/被策略拒绝」进而决定重试还是丢弃。7.3 结果持久化 save()save(filename...)docling/datamodel/document.py将整个转换结果序列化为一个内存 ZIP 归档内含timestamp.json、version.json、status.json、errors.json、pages.json、timings.json、confidence.json、document.json等逐项 JSON 文件ZIP_DEFLATED压缩。对应地类方法可从该归档反序列化还原含document.json的DoclingDocument.model_validate适合把转换产物连同诊断信息一起落盘归档。8. 端到端实战示例综合以上要点一个带格式白名单、错误捕获与结果导出的健壮转换流程如下from pathlib import Path from docling.document_converter import DocumentConverter, PdfFormatOption from docling.datamodel.base_models import InputFormat from docling.datamodel.pipeline_options import PdfPipelineOptions converter DocumentConverter( allowed_formats[InputFormat.PDF, InputFormat.DOCX, InputFormat.IMAGE], format_options{ InputFormat.PDF: PdfFormatOption(pipeline_optionsPdfPipelineOptions()) }, ) # 预热 PDF 管线模型缺失等问题在此快速暴露 converter.initialize_pipeline(InputFormat.PDF) paths list(Path(reports/).glob(*.pdf)) for res in converter.convert_all(paths, raises_on_errorFalse, max_file_size50 * 1024 * 1024): if res.status in (res.status.SUCCESS, res.status.PARTIAL_SUCCESS) if False else True: pass if res.has_errors(): print(res.input.file.name, res.status, [e.error_message for e in res.errors]) continue Path(fout/{res.input.file.stem}.md).write_text( res.document.export_to_markdown(), encodingutf-8 )上例中raises_on_errorFalse保证单文档失败不会中断整批max_file_size限制超大文件进入管线错误经has_errors()与ErrorItem.error_message分类输出。对应的最小用例可参考 docs/getting_started/quickstart.md 与 docs/examples/minimal.py端到端行为验证可查阅 tests/test_e2e_conversion.py。9. 小结与延伸阅读DocumentConverter的设计要点可以概括为格式 →FormatOption管线类 后端 选项→ 管线实例缓存 →ConversionResult状态 结构化错误 DoclingDocument的四段式解耦。掌握allowed_formats/format_options的注册机制、convert三方法各自的适用边界、ConversionStatus六态与错误分类助手以及settings.perf批量并发配置即可覆盖绝大多数文档处理集成场景。延伸阅读均为仓库内相对路径docling/document_converter.py本文所有类与方法的完整实现docling/datamodel/base_models.pyInputFormat、ConversionStatus、HttpSource、BaseFormatOption定义docling/datamodel/document.pyConversionResult/ConversionAssets与输入解析docs/usage/supported_formats.md输入/输出格式全表与 extra 依赖说明docs/reference/pipeline_options.mdPipelineOptions相关选项的 API 参考docs/reference/cli.mdCLI 侧对应能力的参考CLI 内部同样经由DocumentConverter驱动。【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考