Docling v2 遷移指南DocumentConverter、CLI 與 DoclingDocument 的完整用法解析【免費(fèi)下載鏈接】doclingGet your documents ready for gen AI項(xiàng)目地址: https://gitcode.com/GitHub_Trending/do/doclingDocling v2 是一次面向多格式文檔理解與轉(zhuǎn)換的 API 重構(gòu)它統(tǒng)一了 CLI 的輸入輸出格式聲明方式--from/--to重寫了DocumentConverter的初始化模型按格式白名單 按格式定制選項(xiàng)并將所有文檔導(dǎo)出能力從ConversionResult遷移到了新的通用文檔表示DoclingDocument上。讀完本文你將掌握 v2 的 CLI 語法、DocumentConverter的完整配置方式、convert/convert_all的調(diào)用與錯(cuò)誤處理語義以及DoclingDocument的迭代、導(dǎo)出、JSON 持久化與重新加載、分塊Chunking等核心實(shí)戰(zhàn)能力并了解這些 API 在源碼中的真實(shí)實(shí)現(xiàn)位置。Docling v2 帶來什么Docling v2 引入了三類新特性見 docs/v2.md多格式理解與轉(zhuǎn)換支持 PDF、MS Word、MS PowerPoint、HTML 以及多種圖片格式的解析與轉(zhuǎn)換通用文檔表示產(chǎn)出新的通用文檔表示即DoclingDocument可以封裝完整的文檔層級(jí)結(jié)構(gòu)標(biāo)題、正文、表格、圖片等全新的 API 與 CLI轉(zhuǎn)換入口、格式聲明、導(dǎo)出方式全部圍繞新的文檔模型重新設(shè)計(jì)。從源碼結(jié)構(gòu)看這一“新 API”的核心入口就是 DocumentConverter它在初始化時(shí)維護(hù)allowed_formats允許轉(zhuǎn)換的輸入格式白名單與format_to_options每個(gè)格式對(duì)應(yīng)的FormatOption包含 pipeline 類、pipeline 選項(xiàng)和文檔后端轉(zhuǎn)換方法統(tǒng)一返回?cái)y帶DoclingDocument的ConversionResult。CLI 的語法變化Docling v2 更新了命令行語法以支持多種格式。典型用法如下與 docs/v2.md 中一致# 將單個(gè)文件轉(zhuǎn)換為 Markdown默認(rèn)輸出 docling myfile.pdf # 將單個(gè)文件轉(zhuǎn)換為 JSON 和 Markdown并關(guān)閉 OCR docling myfile.pdf --to json --to md --no-ocr # 將輸入目錄中的 PDF 文件轉(zhuǎn)換為 Markdown默認(rèn) docling ./input/dir --from pdf # 將輸入目錄中的 PDF 和 Word 文件轉(zhuǎn)換為 Markdown 和 JSON docling ./input/dir --from pdf --from docx --to md --to json --output ./scratch # 轉(zhuǎn)換輸入目錄中所有受支持的文件遇到第一個(gè)錯(cuò)誤即中止 docling ./input/dir --output ./scratch --abort-on-error相對(duì) Docling v1 的關(guān)鍵變化移除了針對(duì)不同導(dǎo)出格式的獨(dú)立開關(guān)統(tǒng)一替換為--from輸入格式與--to輸出格式參數(shù)新增--abort-on-error批處理轉(zhuǎn)換中一旦遇到錯(cuò)誤立即中止移除了原來針對(duì) PDF 的--backend選項(xiàng)。這些變化都能在 CLI 源碼中得到印證。docling/cli/main.py 中定義了--from與--to兩個(gè)多值選項(xiàng)--to缺省時(shí)默認(rèn)輸出 Markdown見 docling/cli/main.py#L1270-L1271。--abort-on-error在 docling/cli/main.py#L999-L1006 中實(shí)現(xiàn)幫助文本明確其為“遇到第一個(gè)錯(cuò)誤時(shí)中止處理”。需要說明的是v1 的--backend雖然被移除但當(dāng)前 CLI 以--pdf-backend的方式保留了 PDF 解析后端的選擇能力其取值為PdfBackend枚舉默認(rèn)THREADED_DOCLING_PARSE見 docling/cli/main.py#L924-L926。輸入格式枚舉InputFormat與輸出格式枚舉OutputFormat定義在 docling/datamodel/base_models.py#L97-L145--from/--to接受的具體字符串取值即以這兩個(gè)枚舉為準(zhǔn)。此外當(dāng)?shù)谝粋€(gè)參數(shù)不是子命令時(shí)CLI 會(huì)通過 自定義 Typer 命令組 自動(dòng)路由到convert命令因此docling myfile.pdf這種“裸調(diào)用”形式依然可用。設(shè)置 DocumentConverter格式白名單與按格式定制為了容納多種輸入格式v2 改變了DocumentConverter的初始化方式你可以在初始化時(shí)定義一份允許的格式列表allowed_formats并按格式提供自定義選項(xiàng)format_options。默認(rèn)情況下所有受支持格式都被允許若未提供format_options則所有allowed_formats都會(huì)使用各自的默認(rèn)值。格式選項(xiàng)可以包含要使用的 pipeline 類、傳給 pipeline 的選項(xiàng)以及文檔后端。它們以格式專屬類型提供例如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 ## 默認(rèn)初始化方式保持不變 # doc_converter DocumentConverter() # 原先的 PipelineOptions 現(xiàn)在叫 PdfPipelineOptions pipeline_options PdfPipelineOptions() pipeline_options.do_ocr False pipeline_options.do_table_structure True #... ## 自定義選項(xiàng)現(xiàn)在按格式定義。 doc_converter ( DocumentConverter( # 下面所有參數(shù)都是可選的內(nèi)部有默認(rèn)值。 allowed_formats[ InputFormat.PDF, InputFormat.IMAGE, InputFormat.DOCX, InputFormat.HTML, InputFormat.PPTX, ], # 格式白名單不匹配的文件會(huì)被忽略。 format_options{ InputFormat.PDF: PdfFormatOption( pipeline_optionspipeline_options, # pipeline 選項(xiàng)放這里。 backendPyPdfiumDocumentBackend # 可選選用其他后端 ), InputFormat.DOCX: WordFormatOption( pipeline_clsSimplePipeline # 辦公格式和 HTML 的默認(rèn)值 ), }, ) )提示如果只使用默認(rèn)配置v2 的行為與 v1 完全一致。從源碼看這一機(jī)制在 DocumentConverter.init中實(shí)現(xiàn)allowed_formats為None時(shí)取list(InputFormat)即全量受支持格式format_to_options對(duì)每個(gè)允許的格式做“自定義選項(xiàng)優(yōu)先否則回落到默認(rèn)選項(xiàng)”的填充默認(rèn)選項(xiàng)由內(nèi)部映射表給出——例如 PDF 默認(rèn)使用StandardPdfPipelineThreadedDoclingParseDocumentBackend而 DOCX/PPTX/HTML/ODT 等辦公與網(wǎng)頁格式默認(rèn)使用SimplePipeline見 _get_default_optionFormatOption基類帶有模型校驗(yàn)器若未顯式提供pipeline_options會(huì)自動(dòng)用pipeline_cls.get_default_options()填充見 docling/document_converter.py#L103-L117。BaseFormatOption的結(jié)構(gòu)pipeline_options與backend兩個(gè)核心字段定義在 docling/datamodel/base_models.py#L74-L85。完整的多格式轉(zhuǎn)換示例可參考 docs/examples/run_with_formats.py它演示了混合文件列表PDF、DOCX、PPTX、HTML、圖片等的轉(zhuǎn)換與導(dǎo)出PDF 側(cè)的 pipeline 與后端組合示例見 docs/examples/custom_convert.py。更深入的轉(zhuǎn)換參數(shù)請(qǐng)查看參考文檔 docs/reference/document_converter.md 與 docs/reference/pipeline_options.md。轉(zhuǎn)換文檔convert 與 convert_allv2 簡(jiǎn)化了向DocumentConverter提供輸入的方式并為轉(zhuǎn)換方法重新命名以獲得更清晰的語義你可以直接用單個(gè)文件、文件列表或DocumentStream對(duì)象發(fā)起轉(zhuǎn)換而無需先構(gòu)造DocumentConversionInput對(duì)象。DocumentConverter.convert現(xiàn)在負(fù)責(zé)轉(zhuǎn)換單個(gè)文件輸入此前為convert_singleDocumentConverter.convert_all現(xiàn)在負(fù)責(zé)一次轉(zhuǎn)換多個(gè)文件此前為convert。from docling.datamodel.document import ConversionResult ## 轉(zhuǎn)換單個(gè)文件支持 URL 或本地路徑 conv_result: ConversionResult doc_converter.convert(https://arxiv.org/pdf/2408.09869) # 原先為 convert_single ## 一次轉(zhuǎn)換多個(gè)文件 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參數(shù)你可以控制轉(zhuǎn)換在首次遇到問題時(shí)是拋出異常還是“韌性”地把所有文件都轉(zhuǎn)換完、將錯(cuò)誤反映在每個(gè)文件的轉(zhuǎn)換狀態(tài)中。默認(rèn)情況下任何錯(cuò)誤會(huì)立即拋出并中止轉(zhuǎn)換此前 v1 會(huì)吞掉異常。conv_results_iter doc_converter.convert_all(input_files, raises_on_errorFalse) # 原先為 convert源碼層面convert 內(nèi)部把單個(gè) source 包裝成單元素列表后委托給 convert_allraises_on_errorTrue時(shí)只要某個(gè)結(jié)果的status不在SUCCESS/PARTIAL_SUCCESS中就會(huì)拋出ConversionError并攜帶各ErrorItem的錯(cuò)誤信息見 docling/document_converter.py#L576-L591。轉(zhuǎn)換狀態(tài)枚舉ConversionStatuspending/started/failure/success/partial_success/skipped定義在 docling/datamodel/base_models.py#L88-L94。此外convert/convert_all均標(biāo)注了validate_call嚴(yán)格校驗(yàn)并額外接受max_num_pages、max_file_size、page_range等限制參數(shù)可用于控制單文檔頁數(shù)上限與頁碼范圍。訪問文檔結(jié)構(gòu)DoclingDocumentv2 同樣簡(jiǎn)化了訪問與導(dǎo)出轉(zhuǎn)換結(jié)果的方式。通用文檔表示現(xiàn)在以DoclingDocument對(duì)象的形式出現(xiàn)在轉(zhuǎn)換結(jié)果中。DoclingDocument提供了一組便捷的 API用于構(gòu)建、迭代和導(dǎo)出文檔內(nèi)容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 ## 查看轉(zhuǎn)換后的文檔結(jié)構(gòu) conv_result.document.print_element_tree() ## 按閱讀順序迭代元素含層級(jí)級(jí)別 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(docconv_result.document) print(table_df.to_markdown()) elif ...: #...??廢棄說明對(duì) Docling v1 文檔表示conv_result.legacy_document的支持已被完全移除現(xiàn)在必須使用 v2 格式## 使用更新后的 v2 文檔表示 conv_result.document導(dǎo)出為 JSON、Markdown、Doctags注意v1 中ConversionResult上的所有render_...方法已在 Docling v2 中移除現(xiàn)統(tǒng)一掛在DoclingDocument上DoclingDocument.export_to_dictDoclingDocument.export_to_markdownDoclingDocument.export_to_document_tokensconv_result: ConversionResult doc_converter.convert(https://arxiv.org/pdf/2408.09869) # 原先為 convert_single ## 導(dǎo)出為所需格式 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的導(dǎo)出路徑已被完全移除。作為歷史參考v1 的舊寫法如下在當(dāng)前版本中會(huì)失敗## ? 已移除此 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 側(cè)的實(shí)現(xiàn)可以看到當(dāng)前支持的完整導(dǎo)出面export_documents 中依次處理了 JSON、YAML、HTML含按頁拆分、Text、Markdown、Doctags、WebVTT、DocLang、DCLX 與 Chunks 等格式其中 Markdown 導(dǎo)出為空時(shí)還會(huì)回寫ErrorItem并把狀態(tài)置為FAILURE。這印證了 v2 的設(shè)計(jì)導(dǎo)出邏輯全部收斂在DoclingDocument之上ConversionResult只負(fù)責(zé)攜帶文檔與轉(zhuǎn)換元數(shù)據(jù)。從 JSON 重新加載 DoclingDocument你可以把DoclingDocument以 JSON 格式保存到磁盤并在之后重新加載# 保存到磁盤 doc: DoclingDocument conv_res.document # 由轉(zhuǎn)換結(jié)果產(chǎn)出 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) # 用標(biāo)準(zhǔn) pydantic API 填充文檔由于DoclingDocument是 Pydantic 模型export_to_dict與model_validate構(gòu)成一對(duì)可逆操作先導(dǎo)出為 dict 保證序列化口徑一致再用標(biāo)準(zhǔn)的 Pydantic API 反序列化。這意味著DoclingDocument的 JSON 文件可以作為文檔資產(chǎn)獨(dú)立流轉(zhuǎn)、入庫或作為下游任務(wù)如分塊、檢索、再加工的中間格式而無需重新運(yùn)行轉(zhuǎn)換管線。Chunking面向檢索的分塊Docling v2 定義了新的分塊基類體系BaseMetachunk 元數(shù)據(jù)BaseChunk包含 chunk 文本與元數(shù)據(jù)BaseChunker分塊器基類從DoclingDocument產(chǎn)出 chunks。在此之上v2 提供了更新后的HierarchicalChunker實(shí)現(xiàn)它利用新的DoclingDocument輸出更豐富的 chunk 格式包括用于定位grounding的相應(yīng) doc items適用的標(biāo)題headings作為上下文適用的題注captions作為上下文。分塊的完整用法包括HybridChunker、LineBasedTokenChunker以及分塊依賴的安裝方式請(qǐng)參閱 Chunking 概念文檔CLI 中--to chunks選項(xiàng)也內(nèi)置了hybrid/hierarchical兩種分塊器見 docling/cli/main.py#L177-L180。相關(guān)示例還包括 docs/examples/hybrid_chunking.ipynb 與 docs/examples/trivial_chunking.py。遷移要點(diǎn)小結(jié)主題Docling v1Docling v2CLI 格式聲明各導(dǎo)出格式獨(dú)立開關(guān)--from/--to參數(shù)批處理錯(cuò)誤吞掉異常新增--abort-on-errorAPI 側(cè)默認(rèn)raises_on_errorTruePDF 后端--backend移除現(xiàn)由--pdf-backendAPI 側(cè)為PdfFormatOption.backend表達(dá)轉(zhuǎn)換入口convert_single/convertconvert單文件/convert_all多文件文檔結(jié)果legacy_documentrender_...conv_result.documentDoclingDocumentexport_to_*初始化全局PipelineOptionsallowed_formats白名單 按格式的PdfFormatOption等整體上v2 的遷移路徑是清晰的如果你只依賴默認(rèn)配置代碼可以原樣保留一旦需要定制把“全局 pipeline 選項(xiàng)”思維切換為“按格式定制”思維format_options并把所有文檔訪問與導(dǎo)出改走conv_result.document即可完成從 v1 到 v2 的平滑過渡。更多 API 細(xì)節(jié)可繼續(xù)參考 docs/reference/docling_document.md 與 docs/reference/cli.md?！久赓M(fèi)下載鏈接】doclingGet your documents ready for gen AI項(xiàng)目地址: https://gitcode.com/GitHub_Trending/do/docling創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考