Docling 富化Enrichment深度解析代码理解、公式理解与图像分类/描述的全链路配置指南【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/doclingDocling 的转换流水线默认只负责把文档解析为结构化表示而富化Enrichment机制允许在基础转换之上追加专门的模型步骤对文档中的特定组件代码块、公式、图片做深加工。本篇指南系统讲解 Docling 内置的四类默认富化能力——代码理解、公式理解、图片分类、图片描述如何在命令行和 Python API 中开启、各参数的默认值与取值范围如何确定以及这些富化阶段在 standard_pdf_pipeline.py 与 pipeline_options.py 中的真实接线方式帮助读者在自己的文档解析流水线中安全地启用并验证这些能力。富化能力总览Docling 允许在转换流水线中加入额外步骤来处理特定文档组件例如代码块、图片等。由于这些额外步骤通常需要执行额外的模型推理会持续增加处理耗时因此大多数富化模型默认是关闭的对应选项类中相关布尔字段默认值均为False。当前内置的默认富化模型如下表所示FeatureParameterProcessed itemDescriptionCode understandingdo_code_enrichmentCodeItem对代码块做高级解析并识别编程语言Formula understandingdo_formula_enrichmentlabel 为FORMULA的TextItem提取公式的 LaTeX 表示Picture classificationdo_picture_classificationPictureItem用DocumentFigureClassifier为图片打类型标签Picture descriptiondo_picture_descriptionPictureItem用视觉语言模型为图片生成文字描述从源码结构看这四个开关都定义在 pipeline_options.py 的选项模型中do_code_enrichment、do_formula_enrichment位于 PDF 流水线选项默认False约 L1961-L1978do_picture_classification、do_picture_description位于分页流水线基类选项默认False约 L1313-L1349。在 CLI 侧cli/main.py 提供对应的--enrich-code、--enrich-formula、--enrich-picture-classes、--enrich-picture-description选项并在构造流水线选项时一一映射到上述do_*字段约 L1331-L1339。代码理解Code understanding代码理解步骤允许对文档中发现的代码块使用高级解析。该富化模型同时会把识别出的语言写入CodeItem的code_language属性。模型规格参见 Hugging Face 上的ds4sd/CodeFormula模型卡。命令行示例docling --enrich-code FILEPython API 示例from docling.document_converter import DocumentConverter, PdfFormatOption from docling.datamodel.pipeline_options import PdfPipelineOptions from docling.datamodel.base_models import InputFormat pipeline_options PdfPipelineOptions() pipeline_options.do_code_enrichment True converter DocumentConverter(format_options{ InputFormat.PDF: PdfFormatOption(pipeline_optionspipeline_options) }) result converter.convert(https://arxiv.org/pdf/2501.17887) doc result.document源码级实现CodeFormulaVlmModel代码与公式共用同一个富化阶段类 CodeFormulaVlmModel在 standard_pdf_pipeline.py 的_enrichment装配逻辑中可以看到流水线会把do_code_enrichment/do_formula_enrichment两个开关改写为code_formula_options的extract_code/extract_formulas字段然后以任一开关为真即启用的方式实例化CodeFormulaVlmModel并将其置于enrichment_pipe首位。阅读该实现可以得到几个对调优有直接意义的细节可处理元素判定is_processable只对CodeItem且extract_codeTrue或 label 为FORMULA的TextItem且extract_formulasTrue返回 True即两个开关可以独立作用于两类元素见 code_formula_vlm_model.py批处理与分辨率类属性elements_batch_size 5、images_scale 1.67约 120 dpi与训练数据分辨率对齐、expansion_factor 0.18裁剪区域外扩比例这些是模型内部固定行为与选项类里通用的images_scale不是一回事语言识别模型输出以_language_前缀形式携带语言名_extract_code_language用正则^_([^_])_\s*(.*)剥离前缀并把剩余文本写回item.text再把语言名映射到CodeLanguageLabel枚举无效值回退为UNKNOWN这正是code_language属性的来源见 code_formula_vlm_model.py。code_formula_options默认使用CodeFormulaVlmOptions.from_preset(codeformulav2)预设见 pipeline_options.py也支持通过from_preset切换到其他 VLM 预设以适配不同的推理引擎Transformers、MLX、API 等。公式理解Formula understanding公式理解步骤会分析文档中的方程公式并提取其 LaTeX 表示。DoclingDocument的 HTML 导出功能会利用该公式结果通过 mathml HTML 语法进行可视化渲染。模型规格同样参见ds4sd/CodeFormula模型卡。命令行示例docling --enrich-formula FILEPython API 示例from docling.document_converter import DocumentConverter, PdfFormatOption from docling.datamodel.pipeline_options import PdfPipelineOptions from docling.datamodel.base_models import InputFormat pipeline_options PdfPipelineOptions() pipeline_options.do_formula_enrichment True converter DocumentConverter(format_options{ InputFormat.PDF: PdfFormatOption(pipeline_optionspipeline_options) }) result converter.convert(https://arxiv.org/pdf/2501.17887) doc result.document与代码理解一样公式提取复用CodeFormulaVlmModelprompt 为formula输出经_post_process清洗去掉/formula、end_of_utterance等特殊 token后写入对应TextItem的text字段见 code_formula_vlm_model.py。另外值得注意在 standard_pdf_pipeline.py 中只要开启do_code_enrichment、do_formula_enrichment、do_picture_classification、do_picture_description、do_chart_extraction中任意一项流水线就会设置keep_backendTrue——因为富化阶段需要基于 backend 渲染出的页面图像裁剪出对应元素的图块这些开关直接影响转换时的内存与产物行为。图片分类Picture classification图片分类步骤用DocumentFigureClassifier模型为文档中的PictureItem打标签。该模型专门用于理解文档中图片的类别例如不同类型的图表chart、流程图、logo、签名等。模型规格参见docling-project/DocumentFigureClassifier-v2.5模型卡。命令行示例docling --enrich-picture-classes FILEPython API 示例from docling.document_converter import DocumentConverter, PdfFormatOption from docling.datamodel.pipeline_options import PdfPipelineOptions from docling.datamodel.base_models import InputFormat pipeline_options PdfPipelineOptions() pipeline_options.generate_picture_images True pipeline_options.images_scale 2 pipeline_options.do_picture_classification True converter DocumentConverter(format_options{ InputFormat.PDF: PdfFormatOption(pipeline_optionspipeline_options) }) result converter.convert(https://arxiv.org/pdf/2501.17887) doc result.document注意前两个附加设置generate_picture_images True负责真正生成图片图块images_scale 2控制图块分辨率——这与 document_picture_classifier.py 中DocumentPictureClassifier的类属性images_scale 2保持一致。实现层面见 document_picture_classifier.py只有PictureItem且分类器启用时才会被处理is_processable分类结果写入item.meta.classificationPictureClassificationMetaField含 class_name、confidence、created_by同时出于向后兼容仍会追加到已弃用的item.annotationsPictureClassificationData默认选项为DocumentPictureClassifierOptions.from_preset(document_figure_classifier_v2)见 pipeline_options.py。图片分类还是图表数据提取的前置依赖在 base_pipeline.py 中可以看到do_chart_extraction会自动隐含启用图片分类do_picture_classification do_picture_classification or do_chart_extraction。图片描述Picture description图片描述步骤允许用视觉语言模型为图片添加标注即通常所说的 captioning 任务。Docling 流水线既支持完全本地加载并运行模型也支持连接任何兼容 chat template 的远程 API。默认启用from docling.document_converter import DocumentConverter, PdfFormatOption from docling.datamodel.pipeline_options import PdfPipelineOptions from docling.datamodel.base_models import InputFormat pipeline_options PdfPipelineOptions() pipeline_options.do_picture_description True converter DocumentConverter(format_options{ InputFormat.PDF: PdfFormatOption(pipeline_optionspipeline_options) }) result converter.convert(https://arxiv.org/pdf/2501.17887) doc result.document不开启时不消耗任何推理资源开启后描述模型由 base_pipeline.py 通过工厂创建并挂入enrichment_pipe创建时统一传入do_picture_description开关、picture_description_options以及enable_remote_services标志。Granite Vision 模型模型规格参见ibm-granite/granite-vision-3.1-2b-preview模型卡。在 Docling 中的用法from docling.datamodel.pipeline_options import granite_picture_description pipeline_options.picture_description_options granite_picture_description该预置对象在 pipeline_options.py 中定义为PictureDescriptionVlmOptions(repo_idibm-granite/granite-vision-3.3-2b, promptWhat is shown in this image?)——注意当前仓库默认指向的 repo 是 granite-vision-3.3-2b而文档正文引用的是 3.1-2b-preview 模型卡两者均为 Granite Vision 系列具体以你实际部署的模型为准。SmolVLM 模型模型规格参见HuggingFaceTB/SmolVLM-256M-Instruct模型卡。用法from docling.datamodel.pipeline_options import smolvlm_picture_description pipeline_options.picture_description_options smolvlm_picture_description对应定义在 pipeline_options.py。此外PdfPipelineOptions.picture_description_options的默认值本身就是基于 smolvlm 预设的PictureDescriptionVlmEngineOptions见 pipeline_options.py因此不显式指定时也走 SmolVLM。其他视觉模型选项类PictureDescriptionVlmOptions允许使用 Hugging Face Hub 上的任意其他模型from docling.datamodel.pipeline_options import PictureDescriptionVlmOptions pipeline_options.picture_description_options PictureDescriptionVlmOptions( repo_id, # -- 在这里填入你偏好的 VLM 的 Hugging Face repo_id promptDescribe the image in three sentences. Be concise and accurate., )该类pipeline_options.py还暴露generation_config默认{max_new_tokens: 200, do_sample: False}与padding_side默认left两个参数。本地运行时picture_description_vlm_model.py 会用AutoModelForImageTextToText以 bfloat16 加载模型在 CUDA 上可选 flash-attention并用apply_chat_template把prompt包装成对话消息后批量生成。远程视觉模型选项类PictureDescriptionApiOptions允许使用托管在远程平台上的模型例如通过 VLLM、Ollama 等本地端点服务或 IBM watsonx.ai 等云服务商。注意在大多数情况下该选项会把你的数据发送到远程服务提供商。from docling.datamodel.pipeline_options import PictureDescriptionApiOptions # 允许连接远程服务 pipeline_options.enable_remote_servicesTrue # -- 必需 # 使用本地运行的模型例如通过 VLLM 服务 # $ vllm serve MODEL_NAME pipeline_options.picture_description_options PictureDescriptionApiOptions( urlhttp://localhost:8000/v1/chat/completions, paramsdict( modelMODEL NAME, seed42, max_completion_tokens200, ), promptDescribe the image in three sentences. Be concise and accurate., timeout90, )其中enable_remote_servicesTrue是硬性前置条件该标志会随选项一路传到富化模型的创建工厂见 base_pipeline.py 中传入enable_remote_services的位置。PictureDescriptionApiOptions的完整参数面还包括headers鉴权头如{Authorization: Bearer TOKEN}、concurrency默认 1、provenance来源元信息等见 pipeline_options.py。捕获 API 用量元数据usage metadataPictureDescriptionApiOptions可以把 API 响应中的原始用量usage负载保留在每条图片描述上。默认情况下Docling 从 OpenAI 兼容 chat-completions 响应的usage字段读取用量。如果你的提供商把用量数据放在别处例如providerUsage或meta.usage把usage_response_key设为对应的 JSON key 或点分路径即可设为None则关闭捕获。pipeline_options.picture_description_options PictureDescriptionApiOptions( urlhttps://example.com/v1/chat/completions, headers{Authorization: Bearer ...}, params{model: my-vision-model}, promptDescribe the image., usage_response_keyusage, )捕获到的负载存放在图片描述的 metadata 中可通过如下方式读取usage picture.meta.description.get_custom_part()[docling__usage]端到端脚本示例含 Azure OpenAI 端点构造参见 picture_description_api_usage.py针对 IBM watsonx.ai 的完整示例参见 pictures_description_api.py。描述阶段的过滤参数无论使用本地还是远程模型PictureDescriptionBaseOptionspipeline_options.py都提供一组控制哪些图片值得描述的公共参数可用于控制成本batch_size默认 8单批处理图片数越大吞吐越高但内存占用越大scale默认 2.0送入视觉模型前的图片缩放倍率picture_area_threshold默认 0.05图片占页面面积的最小比例0.0-1.0小于该阈值的图片会被跳过classification_allow/classification_deny基于图片分类标签的白/黑名单——可与上一节的图片分类联动只对或排除特定类型如仅描述图表、排除 logo的图片做描述classification_min_confidence默认 0.0分类置信度阈值低于该值的图片被跳过。开发新的富化模型除了参考上文所列所有模型的实现Docling 文档还提供了专门讲解富化模型实现的示例develop_picture_enrichment.py如何开发图片富化模型develop_formula_understanding.py如何开发公式富化模型。这两个示例与内置实现共享同一套基类富化阶段通常继承 base_model.py 中的元素-图片富化模型基类实现is_processable(doc, element)与__call__(doc, element_batch)两个方法再挂入流水线的enrichment_pipe即可。小结开启富化时的检查清单先确认成本每个富化开关都会引入额外模型推理按需开启do_code_enrichment/do_formula_enrichment/do_picture_classification/do_picture_description避免一次全部打开图片类富化需要先生成图块设置generate_picture_images True并按需调整images_scale远程模型必须同时设置pipeline_options.enable_remote_services True并留意数据外发问题需要成本核算时用usage_response_key捕获 API 用量从picture.meta.description.get_custom_part()[docling__usage]读取开启任一富化开关会令流水线保持 backendkeep_backendTrue用于元素图像裁剪属于预期行为。【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Docling 富化（Enrichment）深度解析：代码理解、公式理解与图像分类/描述的全链路配置指南
Docling 富化Enrichment深度解析代码理解、公式理解与图像分类/描述的全链路配置指南【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/doclingDocling 的转换流水线默认只负责把文档解析为结构化表示而富化Enrichment机制允许在基础转换之上追加专门的模型步骤对文档中的特定组件代码块、公式、图片做深加工。本篇指南系统讲解 Docling 内置的四类默认富化能力——代码理解、公式理解、图片分类、图片描述如何在命令行和 Python API 中开启、各参数的默认值与取值范围如何确定以及这些富化阶段在 standard_pdf_pipeline.py 与 pipeline_options.py 中的真实接线方式帮助读者在自己的文档解析流水线中安全地启用并验证这些能力。富化能力总览Docling 允许在转换流水线中加入额外步骤来处理特定文档组件例如代码块、图片等。由于这些额外步骤通常需要执行额外的模型推理会持续增加处理耗时因此大多数富化模型默认是关闭的对应选项类中相关布尔字段默认值均为False。当前内置的默认富化模型如下表所示FeatureParameterProcessed itemDescriptionCode understandingdo_code_enrichmentCodeItem对代码块做高级解析并识别编程语言Formula understandingdo_formula_enrichmentlabel 为FORMULA的TextItem提取公式的 LaTeX 表示Picture classificationdo_picture_classificationPictureItem用DocumentFigureClassifier为图片打类型标签Picture descriptiondo_picture_descriptionPictureItem用视觉语言模型为图片生成文字描述从源码结构看这四个开关都定义在 pipeline_options.py 的选项模型中do_code_enrichment、do_formula_enrichment位于 PDF 流水线选项默认False约 L1961-L1978do_picture_classification、do_picture_description位于分页流水线基类选项默认False约 L1313-L1349。在 CLI 侧cli/main.py 提供对应的--enrich-code、--enrich-formula、--enrich-picture-classes、--enrich-picture-description选项并在构造流水线选项时一一映射到上述do_*字段约 L1331-L1339。代码理解Code understanding代码理解步骤允许对文档中发现的代码块使用高级解析。该富化模型同时会把识别出的语言写入CodeItem的code_language属性。模型规格参见 Hugging Face 上的ds4sd/CodeFormula模型卡。命令行示例docling --enrich-code FILEPython API 示例from docling.document_converter import DocumentConverter, PdfFormatOption from docling.datamodel.pipeline_options import PdfPipelineOptions from docling.datamodel.base_models import InputFormat pipeline_options PdfPipelineOptions() pipeline_options.do_code_enrichment True converter DocumentConverter(format_options{ InputFormat.PDF: PdfFormatOption(pipeline_optionspipeline_options) }) result converter.convert(https://arxiv.org/pdf/2501.17887) doc result.document源码级实现CodeFormulaVlmModel代码与公式共用同一个富化阶段类 CodeFormulaVlmModel在 standard_pdf_pipeline.py 的_enrichment装配逻辑中可以看到流水线会把do_code_enrichment/do_formula_enrichment两个开关改写为code_formula_options的extract_code/extract_formulas字段然后以任一开关为真即启用的方式实例化CodeFormulaVlmModel并将其置于enrichment_pipe首位。阅读该实现可以得到几个对调优有直接意义的细节可处理元素判定is_processable只对CodeItem且extract_codeTrue或 label 为FORMULA的TextItem且extract_formulasTrue返回 True即两个开关可以独立作用于两类元素见 code_formula_vlm_model.py批处理与分辨率类属性elements_batch_size 5、images_scale 1.67约 120 dpi与训练数据分辨率对齐、expansion_factor 0.18裁剪区域外扩比例这些是模型内部固定行为与选项类里通用的images_scale不是一回事语言识别模型输出以_language_前缀形式携带语言名_extract_code_language用正则^_([^_])_\s*(.*)剥离前缀并把剩余文本写回item.text再把语言名映射到CodeLanguageLabel枚举无效值回退为UNKNOWN这正是code_language属性的来源见 code_formula_vlm_model.py。code_formula_options默认使用CodeFormulaVlmOptions.from_preset(codeformulav2)预设见 pipeline_options.py也支持通过from_preset切换到其他 VLM 预设以适配不同的推理引擎Transformers、MLX、API 等。公式理解Formula understanding公式理解步骤会分析文档中的方程公式并提取其 LaTeX 表示。DoclingDocument的 HTML 导出功能会利用该公式结果通过 mathml HTML 语法进行可视化渲染。模型规格同样参见ds4sd/CodeFormula模型卡。命令行示例docling --enrich-formula FILEPython API 示例from docling.document_converter import DocumentConverter, PdfFormatOption from docling.datamodel.pipeline_options import PdfPipelineOptions from docling.datamodel.base_models import InputFormat pipeline_options PdfPipelineOptions() pipeline_options.do_formula_enrichment True converter DocumentConverter(format_options{ InputFormat.PDF: PdfFormatOption(pipeline_optionspipeline_options) }) result converter.convert(https://arxiv.org/pdf/2501.17887) doc result.document与代码理解一样公式提取复用CodeFormulaVlmModelprompt 为formula输出经_post_process清洗去掉/formula、end_of_utterance等特殊 token后写入对应TextItem的text字段见 code_formula_vlm_model.py。另外值得注意在 standard_pdf_pipeline.py 中只要开启do_code_enrichment、do_formula_enrichment、do_picture_classification、do_picture_description、do_chart_extraction中任意一项流水线就会设置keep_backendTrue——因为富化阶段需要基于 backend 渲染出的页面图像裁剪出对应元素的图块这些开关直接影响转换时的内存与产物行为。图片分类Picture classification图片分类步骤用DocumentFigureClassifier模型为文档中的PictureItem打标签。该模型专门用于理解文档中图片的类别例如不同类型的图表chart、流程图、logo、签名等。模型规格参见docling-project/DocumentFigureClassifier-v2.5模型卡。命令行示例docling --enrich-picture-classes FILEPython API 示例from docling.document_converter import DocumentConverter, PdfFormatOption from docling.datamodel.pipeline_options import PdfPipelineOptions from docling.datamodel.base_models import InputFormat pipeline_options PdfPipelineOptions() pipeline_options.generate_picture_images True pipeline_options.images_scale 2 pipeline_options.do_picture_classification True converter DocumentConverter(format_options{ InputFormat.PDF: PdfFormatOption(pipeline_optionspipeline_options) }) result converter.convert(https://arxiv.org/pdf/2501.17887) doc result.document注意前两个附加设置generate_picture_images True负责真正生成图片图块images_scale 2控制图块分辨率——这与 document_picture_classifier.py 中DocumentPictureClassifier的类属性images_scale 2保持一致。实现层面见 document_picture_classifier.py只有PictureItem且分类器启用时才会被处理is_processable分类结果写入item.meta.classificationPictureClassificationMetaField含 class_name、confidence、created_by同时出于向后兼容仍会追加到已弃用的item.annotationsPictureClassificationData默认选项为DocumentPictureClassifierOptions.from_preset(document_figure_classifier_v2)见 pipeline_options.py。图片分类还是图表数据提取的前置依赖在 base_pipeline.py 中可以看到do_chart_extraction会自动隐含启用图片分类do_picture_classification do_picture_classification or do_chart_extraction。图片描述Picture description图片描述步骤允许用视觉语言模型为图片添加标注即通常所说的 captioning 任务。Docling 流水线既支持完全本地加载并运行模型也支持连接任何兼容 chat template 的远程 API。默认启用from docling.document_converter import DocumentConverter, PdfFormatOption from docling.datamodel.pipeline_options import PdfPipelineOptions from docling.datamodel.base_models import InputFormat pipeline_options PdfPipelineOptions() pipeline_options.do_picture_description True converter DocumentConverter(format_options{ InputFormat.PDF: PdfFormatOption(pipeline_optionspipeline_options) }) result converter.convert(https://arxiv.org/pdf/2501.17887) doc result.document不开启时不消耗任何推理资源开启后描述模型由 base_pipeline.py 通过工厂创建并挂入enrichment_pipe创建时统一传入do_picture_description开关、picture_description_options以及enable_remote_services标志。Granite Vision 模型模型规格参见ibm-granite/granite-vision-3.1-2b-preview模型卡。在 Docling 中的用法from docling.datamodel.pipeline_options import granite_picture_description pipeline_options.picture_description_options granite_picture_description该预置对象在 pipeline_options.py 中定义为PictureDescriptionVlmOptions(repo_idibm-granite/granite-vision-3.3-2b, promptWhat is shown in this image?)——注意当前仓库默认指向的 repo 是 granite-vision-3.3-2b而文档正文引用的是 3.1-2b-preview 模型卡两者均为 Granite Vision 系列具体以你实际部署的模型为准。SmolVLM 模型模型规格参见HuggingFaceTB/SmolVLM-256M-Instruct模型卡。用法from docling.datamodel.pipeline_options import smolvlm_picture_description pipeline_options.picture_description_options smolvlm_picture_description对应定义在 pipeline_options.py。此外PdfPipelineOptions.picture_description_options的默认值本身就是基于 smolvlm 预设的PictureDescriptionVlmEngineOptions见 pipeline_options.py因此不显式指定时也走 SmolVLM。其他视觉模型选项类PictureDescriptionVlmOptions允许使用 Hugging Face Hub 上的任意其他模型from docling.datamodel.pipeline_options import PictureDescriptionVlmOptions pipeline_options.picture_description_options PictureDescriptionVlmOptions( repo_id, # -- 在这里填入你偏好的 VLM 的 Hugging Face repo_id promptDescribe the image in three sentences. Be concise and accurate., )该类pipeline_options.py还暴露generation_config默认{max_new_tokens: 200, do_sample: False}与padding_side默认left两个参数。本地运行时picture_description_vlm_model.py 会用AutoModelForImageTextToText以 bfloat16 加载模型在 CUDA 上可选 flash-attention并用apply_chat_template把prompt包装成对话消息后批量生成。远程视觉模型选项类PictureDescriptionApiOptions允许使用托管在远程平台上的模型例如通过 VLLM、Ollama 等本地端点服务或 IBM watsonx.ai 等云服务商。注意在大多数情况下该选项会把你的数据发送到远程服务提供商。from docling.datamodel.pipeline_options import PictureDescriptionApiOptions # 允许连接远程服务 pipeline_options.enable_remote_servicesTrue # -- 必需 # 使用本地运行的模型例如通过 VLLM 服务 # $ vllm serve MODEL_NAME pipeline_options.picture_description_options PictureDescriptionApiOptions( urlhttp://localhost:8000/v1/chat/completions, paramsdict( modelMODEL NAME, seed42, max_completion_tokens200, ), promptDescribe the image in three sentences. Be concise and accurate., timeout90, )其中enable_remote_servicesTrue是硬性前置条件该标志会随选项一路传到富化模型的创建工厂见 base_pipeline.py 中传入enable_remote_services的位置。PictureDescriptionApiOptions的完整参数面还包括headers鉴权头如{Authorization: Bearer TOKEN}、concurrency默认 1、provenance来源元信息等见 pipeline_options.py。捕获 API 用量元数据usage metadataPictureDescriptionApiOptions可以把 API 响应中的原始用量usage负载保留在每条图片描述上。默认情况下Docling 从 OpenAI 兼容 chat-completions 响应的usage字段读取用量。如果你的提供商把用量数据放在别处例如providerUsage或meta.usage把usage_response_key设为对应的 JSON key 或点分路径即可设为None则关闭捕获。pipeline_options.picture_description_options PictureDescriptionApiOptions( urlhttps://example.com/v1/chat/completions, headers{Authorization: Bearer ...}, params{model: my-vision-model}, promptDescribe the image., usage_response_keyusage, )捕获到的负载存放在图片描述的 metadata 中可通过如下方式读取usage picture.meta.description.get_custom_part()[docling__usage]端到端脚本示例含 Azure OpenAI 端点构造参见 picture_description_api_usage.py针对 IBM watsonx.ai 的完整示例参见 pictures_description_api.py。描述阶段的过滤参数无论使用本地还是远程模型PictureDescriptionBaseOptionspipeline_options.py都提供一组控制哪些图片值得描述的公共参数可用于控制成本batch_size默认 8单批处理图片数越大吞吐越高但内存占用越大scale默认 2.0送入视觉模型前的图片缩放倍率picture_area_threshold默认 0.05图片占页面面积的最小比例0.0-1.0小于该阈值的图片会被跳过classification_allow/classification_deny基于图片分类标签的白/黑名单——可与上一节的图片分类联动只对或排除特定类型如仅描述图表、排除 logo的图片做描述classification_min_confidence默认 0.0分类置信度阈值低于该值的图片被跳过。开发新的富化模型除了参考上文所列所有模型的实现Docling 文档还提供了专门讲解富化模型实现的示例develop_picture_enrichment.py如何开发图片富化模型develop_formula_understanding.py如何开发公式富化模型。这两个示例与内置实现共享同一套基类富化阶段通常继承 base_model.py 中的元素-图片富化模型基类实现is_processable(doc, element)与__call__(doc, element_batch)两个方法再挂入流水线的enrichment_pipe即可。小结开启富化时的检查清单先确认成本每个富化开关都会引入额外模型推理按需开启do_code_enrichment/do_formula_enrichment/do_picture_classification/do_picture_description避免一次全部打开图片类富化需要先生成图块设置generate_picture_images True并按需调整images_scale远程模型必须同时设置pipeline_options.enable_remote_services True并留意数据外发问题需要成本核算时用usage_response_key捕获 API 用量从picture.meta.description.get_custom_part()[docling__usage]读取开启任一富化开关会令流水线保持 backendkeep_backendTrue用于元素图像裁剪属于预期行为。【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考