Docling 转换置信度评分Confidence Scores权威指南看懂 QualityGrade、四类分数与质量门槛【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling本指南以 Docling 官方概念文档 docs/concepts/confidence_scores.md 为核心结合仓库源码 docling/datamodel/base_models.py、docling/pipeline/standard_pdf_pipeline.py 等实现系统讲解 Docling 从 v2.34.0 引入的置信度评分体系分数如何计算、等级如何映射、在何处写入、以及如何用它驱动人工复核 / 管道调优 / 批量阈值截断等后处理决策。读完后你将能准确解读ConversionResult.confidence中的每一个字段并基于mean_grade、low_grade落地质量门控策略。为什么需要置信度评分把转换质量变成可量化信号复杂版式、劣质扫描件、棘手的排版问题都可能导致文档转换结果不理想进而需要人工关注或切换备用转换管线。Docling 的置信度评分正是一种对文档转换质量的数量化评估每个置信度报告都包含一个数值分数范围 0.01.0越高表示转换质量越好与一个质量等级quality grade取值为poor、fair、good、excellent供使用者快速判断。典型使用场景包括识别转换后需要人工复核的文档为不同文档类型匹配合适的转换管线为无人值守批量转换设置置信度阈值低于阈值即告警或转人工在工作流早期提前捕获潜在的转换问题。官方明确建议重点看质量等级而非数值! 官方提示原文档中的 note使用者可以且应当放心地把注意力放在文档级等级字段——mean_grade与low_grade——上来评估整体转换质量。数值分数仅供内部参考其计算方式与权重在未来可能发生变化不应作为跨版本比较的稳定依据。概念拆解分数Scores与等级Grades一份置信度报告同时包含两类内容类型含义用途Scores分数0.01.0 的数值越高代表转换质量越好内部计算与信息参考Grades等级基于分数阈值得到的分档质量评估面向使用者的整体质量判定等级来自枚举类型QualityGrade定义在 docling/datamodel/base_models.pyclass QualityGrade(str, Enum): POOR poor FAIR fair GOOD good EXCELLENT excellent UNSPECIFIED unspecifiedUNSPECIFIED用于暂无数据的兜底状态。分数到等级的映射见源码中的PageConfidenceScores._score_to_gradebase_models.py数值区间等级score 0.5POOR0.5 score 0.8FAIR0.8 score 0.9GOODscore 0.9EXCELLENT其余如全为NaN尚无数据UNSPECIFIED四类组件分数layout / ocr / parse / table每份置信度报告包含四个组件分数它们由转换管线中不同的处理阶段负责写入layout_score文档元素标题、段落、图片等识别的整体质量。在布局后处理阶段页面级layout_score取各布局聚类置信度cluster.confidence的均值聚类为空时回退为0.0实现见 docling/models/stages/layout/layout_postprocessing_model.py。ocr_scoreOCR 提取内容的文本识别质量。OCR 阶段结束后取该页所有来自 OCR 的文本单元confidence的均值写入pages[page].ocr_score见 docling/models/base_ocr_model.py。纯文本型 PDF不触发 OCR通常不会产生该分数。parse_score数字文本单元质量的第 10 百分位分数专门用于突出薄弱区域PDF 原生文本提取的质量评分。其页面级计算在 docling/models/stages/page_preprocessing/page_preprocessing_model.py先对页内每个文本 cell 调用rate_text_quality打分再对这些分数取np.nanquantile(..., q0.10)。table_score表格抽取质量——尚未实现not yet implemented在数据模型中默认值为np.nan见 base_models.py。parse_score的文本质量评分启发式实现rate_text_qualitypage_preprocessing_model.py包含几条易读的实现细节命中黑名单字符如替换符、疑似字形垃圾/斜杠数字模式等正则时直接返回 0.0碎片化单词模式FRAG_RE累计出现 3 次以上时每个命中施加 0.1 的惩罚最终max(1.0 - penalty, 0.0)。这解释了为什么乱码页的parse_score会显著偏低。汇总等级mean_grade 与 low_grade在PageConfidenceScores中四个组件分数进一步被聚合为两个汇总指标base_models.pymean_grade四个组件分数的平均值所对应的等级。实现上通过np.nanmean对ocr_score / table_score / layout_score / parse_score求平均因此尚未产生数据的组件如未实现的table_score默认NaN会被自动忽略再经阈值映射得到等级low_grade四个组件分数的第 5 百分位所对应的等级用于突出表现最差的方向。实现采用np.nanquantile(..., q0.05)。两者都以computed_field计算属性形式暴露mean_grade/low_grade源码见 base_models.py因此无论页面级还是文档级对象上读取到的mean_grade/low_grade都是实时计算、天然一致的。官方口径与实现的细微分野需要指出官方概念文档将mean_grade描述为四个组件分数的平均将low_grade描述为第 5 百分位分数。从源码实现看数值层面使用的是np.nanmean忽略NaN的均值与np.nanquantile(q0.05)忽略NaN的分位数。两者在文档描述口径上一致但NaN组件的处理细节属于实现层差异——这也再次印证官方数值仅供内部参考、计算细节可能调整的提示。页面级 vs 文档级两套层次的对象结构置信度按两个层级计算页面级每页各自的分数与等级保存在pages字段dict[int, PageConfidenceScores]文档级整篇文档的整体分数与等级由各页面等级求平均得到存放在ConfidenceReport根级同名字段中。对应到源码两个 Pydantic 模型定义在 base_models.pyPageConfidenceScores持有四个组件分数 四个 computed 属性mean_score/low_score/mean_grade/low_grade字段校验器接受None或字符串NaN/null/并统一转换为np.nan兼容性良好base_models.pyConfidenceReport(PageConfidenceScores)在继承页面字段之外增加pages: dict[int, PageConfidenceScores]并重写文档级mean_score/low_score的计算逻辑——当存在页面记录时文档级均值取各页面mean_score的nanmean、文档级低分取各页面low_score的nanmeanbase_models.py即先逐页求统计量、再做跨页汇总。上面概念文档配图中的输出docs/assets/confidence_scores.png展示的正是这样一个典型对象快照ConfidenceReport根级包含parse_score 1.0、layout_score ≈ 0.915、ocr_score与table_score为nanmean_score ≈ 0.957mean_grade EXCELLENT同时pages中以页号为键存放PageConfidenceScores。从源码看分数如何被写出来文档级聚合的入口在标准 PDF 转换管线的收尾阶段会一次性把各页面的组件分数聚合回文档级ConfidenceReport见 docling/pipeline/standard_pdf_pipeline.pyconv_res.confidence.layout_score float(np.nanmean([c.layout_score for c in conv_res.confidence.pages.values()])) conv_res.confidence.parse_score float(np.nanquantile([c.parse_score for c in conv_res.confidence.pages.values()], q0.1)) conv_res.confidence.table_score float(np.nanmean([c.table_score for c in conv_res.confidence.pages.values()])) conv_res.confidence.ocr_score float(np.nanmean([c.ocr_score for c in conv_res.confidence.pages.values()]))注意其中parse_score的文档级聚合并不用均值而是跨页取10% 分位源码注释明确写着 parse score should relate to worst 10% of pages使其持续对准问题最严重的页面其余三者在文档级采用跨页nanmean。由此可梳理出完整的数据流parse_score在页面预处理阶段写入 →layout_score在布局后处理阶段写入 →ocr_score在 OCR 模型阶段写入若触发 OCR→ 各页面分数在 standard_pdf_pipeline.py 统一聚合成文档级数值 → 文档级的mean_grade/low_grade由ConfidenceReport的计算属性按页面均值实时得出。在代码中读取并使用置信度置信度报告挂在DocumentConverter.convert()返回的ConversionResult.confidence字段上类型为ConfidenceReport字段说明见 参考文档使用方式示意如下from docling.document_converter import DocumentConverter result DocumentConverter().convert(input.pdf) report result.confidence print(report.mean_grade) # 如 QualityGrade.EXCELLENT print(report.low_grade) # 整篇最差方向对应的等级 # 页面级查看哪一页最需要人工复核 worst_page min(report.pages.items(), keylambda kv: kv[1].mean_score) print(worst_page[0], worst_page[1].layout_score, worst_page[1].parse_score)配合置信度做质量门控时推荐策略把mean_grade用于整体是否达标的判断把low_grade用于是否存在局部烂页/烂区域的筛查——例如low_grade达到POOR即转人工复核或改用其他转换管线完全贴合官方只看两个 grade 字段的指引。序列化与服务端传输的配套处理在导出/打包场景中ConfidenceReport也被纳入序列化docling 的打包输出流程会为转换资产单独写出confidence.json相关代码位于 docling/datamodel/document.py并在恢复时以ConfidenceReport.model_validate读回document.py。面向网络传输如 docling 服务时ConfidenceReport会被转换为 JSON 安全的ConfidenceScores快照——源码位于 docling/datamodel/service/responses.py其中NaN一律映射为None、mean_grade/low_grade序列化为字符串枚举服务结果类中对应confidence可选字段见 responses.py 等。这意味着同一份置信度体系在本地 SDK 使用与远端服务响应两条路径上的语义完全一致。小结Docling 的置信度评分是一套分层、可审计的质量信号四个组件分数layout_score/ocr_score/parse_score/table_score刻画具体处理环节的质量两个汇总指标mean_score→mean_grade的平均口径、low_score→low_grade的第 5 百分位口径给出页面级与文档级的整体结论且实现分布在转换管线的页面预处理、布局后处理、OCR 与最终聚合等真实阶段中可以从源码逐项追溯。实际使用时请遵循官方建议将决策锚定在mean_grade与low_grade上把数值分数当作诊断参考而非长期契约即可在批量转换、人工复核分流与管线选择等场景中获得稳定的质量观测。【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Docling 转换置信度评分（Confidence Scores）权威指南：看懂 QualityGrade、四类分数与质量门槛
Docling 转换置信度评分Confidence Scores权威指南看懂 QualityGrade、四类分数与质量门槛【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling本指南以 Docling 官方概念文档 docs/concepts/confidence_scores.md 为核心结合仓库源码 docling/datamodel/base_models.py、docling/pipeline/standard_pdf_pipeline.py 等实现系统讲解 Docling 从 v2.34.0 引入的置信度评分体系分数如何计算、等级如何映射、在何处写入、以及如何用它驱动人工复核 / 管道调优 / 批量阈值截断等后处理决策。读完后你将能准确解读ConversionResult.confidence中的每一个字段并基于mean_grade、low_grade落地质量门控策略。为什么需要置信度评分把转换质量变成可量化信号复杂版式、劣质扫描件、棘手的排版问题都可能导致文档转换结果不理想进而需要人工关注或切换备用转换管线。Docling 的置信度评分正是一种对文档转换质量的数量化评估每个置信度报告都包含一个数值分数范围 0.01.0越高表示转换质量越好与一个质量等级quality grade取值为poor、fair、good、excellent供使用者快速判断。典型使用场景包括识别转换后需要人工复核的文档为不同文档类型匹配合适的转换管线为无人值守批量转换设置置信度阈值低于阈值即告警或转人工在工作流早期提前捕获潜在的转换问题。官方明确建议重点看质量等级而非数值! 官方提示原文档中的 note使用者可以且应当放心地把注意力放在文档级等级字段——mean_grade与low_grade——上来评估整体转换质量。数值分数仅供内部参考其计算方式与权重在未来可能发生变化不应作为跨版本比较的稳定依据。概念拆解分数Scores与等级Grades一份置信度报告同时包含两类内容类型含义用途Scores分数0.01.0 的数值越高代表转换质量越好内部计算与信息参考Grades等级基于分数阈值得到的分档质量评估面向使用者的整体质量判定等级来自枚举类型QualityGrade定义在 docling/datamodel/base_models.pyclass QualityGrade(str, Enum): POOR poor FAIR fair GOOD good EXCELLENT excellent UNSPECIFIED unspecifiedUNSPECIFIED用于暂无数据的兜底状态。分数到等级的映射见源码中的PageConfidenceScores._score_to_gradebase_models.py数值区间等级score 0.5POOR0.5 score 0.8FAIR0.8 score 0.9GOODscore 0.9EXCELLENT其余如全为NaN尚无数据UNSPECIFIED四类组件分数layout / ocr / parse / table每份置信度报告包含四个组件分数它们由转换管线中不同的处理阶段负责写入layout_score文档元素标题、段落、图片等识别的整体质量。在布局后处理阶段页面级layout_score取各布局聚类置信度cluster.confidence的均值聚类为空时回退为0.0实现见 docling/models/stages/layout/layout_postprocessing_model.py。ocr_scoreOCR 提取内容的文本识别质量。OCR 阶段结束后取该页所有来自 OCR 的文本单元confidence的均值写入pages[page].ocr_score见 docling/models/base_ocr_model.py。纯文本型 PDF不触发 OCR通常不会产生该分数。parse_score数字文本单元质量的第 10 百分位分数专门用于突出薄弱区域PDF 原生文本提取的质量评分。其页面级计算在 docling/models/stages/page_preprocessing/page_preprocessing_model.py先对页内每个文本 cell 调用rate_text_quality打分再对这些分数取np.nanquantile(..., q0.10)。table_score表格抽取质量——尚未实现not yet implemented在数据模型中默认值为np.nan见 base_models.py。parse_score的文本质量评分启发式实现rate_text_qualitypage_preprocessing_model.py包含几条易读的实现细节命中黑名单字符如替换符、疑似字形垃圾/斜杠数字模式等正则时直接返回 0.0碎片化单词模式FRAG_RE累计出现 3 次以上时每个命中施加 0.1 的惩罚最终max(1.0 - penalty, 0.0)。这解释了为什么乱码页的parse_score会显著偏低。汇总等级mean_grade 与 low_grade在PageConfidenceScores中四个组件分数进一步被聚合为两个汇总指标base_models.pymean_grade四个组件分数的平均值所对应的等级。实现上通过np.nanmean对ocr_score / table_score / layout_score / parse_score求平均因此尚未产生数据的组件如未实现的table_score默认NaN会被自动忽略再经阈值映射得到等级low_grade四个组件分数的第 5 百分位所对应的等级用于突出表现最差的方向。实现采用np.nanquantile(..., q0.05)。两者都以computed_field计算属性形式暴露mean_grade/low_grade源码见 base_models.py因此无论页面级还是文档级对象上读取到的mean_grade/low_grade都是实时计算、天然一致的。官方口径与实现的细微分野需要指出官方概念文档将mean_grade描述为四个组件分数的平均将low_grade描述为第 5 百分位分数。从源码实现看数值层面使用的是np.nanmean忽略NaN的均值与np.nanquantile(q0.05)忽略NaN的分位数。两者在文档描述口径上一致但NaN组件的处理细节属于实现层差异——这也再次印证官方数值仅供内部参考、计算细节可能调整的提示。页面级 vs 文档级两套层次的对象结构置信度按两个层级计算页面级每页各自的分数与等级保存在pages字段dict[int, PageConfidenceScores]文档级整篇文档的整体分数与等级由各页面等级求平均得到存放在ConfidenceReport根级同名字段中。对应到源码两个 Pydantic 模型定义在 base_models.pyPageConfidenceScores持有四个组件分数 四个 computed 属性mean_score/low_score/mean_grade/low_grade字段校验器接受None或字符串NaN/null/并统一转换为np.nan兼容性良好base_models.pyConfidenceReport(PageConfidenceScores)在继承页面字段之外增加pages: dict[int, PageConfidenceScores]并重写文档级mean_score/low_score的计算逻辑——当存在页面记录时文档级均值取各页面mean_score的nanmean、文档级低分取各页面low_score的nanmeanbase_models.py即先逐页求统计量、再做跨页汇总。上面概念文档配图中的输出docs/assets/confidence_scores.png展示的正是这样一个典型对象快照ConfidenceReport根级包含parse_score 1.0、layout_score ≈ 0.915、ocr_score与table_score为nanmean_score ≈ 0.957mean_grade EXCELLENT同时pages中以页号为键存放PageConfidenceScores。从源码看分数如何被写出来文档级聚合的入口在标准 PDF 转换管线的收尾阶段会一次性把各页面的组件分数聚合回文档级ConfidenceReport见 docling/pipeline/standard_pdf_pipeline.pyconv_res.confidence.layout_score float(np.nanmean([c.layout_score for c in conv_res.confidence.pages.values()])) conv_res.confidence.parse_score float(np.nanquantile([c.parse_score for c in conv_res.confidence.pages.values()], q0.1)) conv_res.confidence.table_score float(np.nanmean([c.table_score for c in conv_res.confidence.pages.values()])) conv_res.confidence.ocr_score float(np.nanmean([c.ocr_score for c in conv_res.confidence.pages.values()]))注意其中parse_score的文档级聚合并不用均值而是跨页取10% 分位源码注释明确写着 parse score should relate to worst 10% of pages使其持续对准问题最严重的页面其余三者在文档级采用跨页nanmean。由此可梳理出完整的数据流parse_score在页面预处理阶段写入 →layout_score在布局后处理阶段写入 →ocr_score在 OCR 模型阶段写入若触发 OCR→ 各页面分数在 standard_pdf_pipeline.py 统一聚合成文档级数值 → 文档级的mean_grade/low_grade由ConfidenceReport的计算属性按页面均值实时得出。在代码中读取并使用置信度置信度报告挂在DocumentConverter.convert()返回的ConversionResult.confidence字段上类型为ConfidenceReport字段说明见 参考文档使用方式示意如下from docling.document_converter import DocumentConverter result DocumentConverter().convert(input.pdf) report result.confidence print(report.mean_grade) # 如 QualityGrade.EXCELLENT print(report.low_grade) # 整篇最差方向对应的等级 # 页面级查看哪一页最需要人工复核 worst_page min(report.pages.items(), keylambda kv: kv[1].mean_score) print(worst_page[0], worst_page[1].layout_score, worst_page[1].parse_score)配合置信度做质量门控时推荐策略把mean_grade用于整体是否达标的判断把low_grade用于是否存在局部烂页/烂区域的筛查——例如low_grade达到POOR即转人工复核或改用其他转换管线完全贴合官方只看两个 grade 字段的指引。序列化与服务端传输的配套处理在导出/打包场景中ConfidenceReport也被纳入序列化docling 的打包输出流程会为转换资产单独写出confidence.json相关代码位于 docling/datamodel/document.py并在恢复时以ConfidenceReport.model_validate读回document.py。面向网络传输如 docling 服务时ConfidenceReport会被转换为 JSON 安全的ConfidenceScores快照——源码位于 docling/datamodel/service/responses.py其中NaN一律映射为None、mean_grade/low_grade序列化为字符串枚举服务结果类中对应confidence可选字段见 responses.py 等。这意味着同一份置信度体系在本地 SDK 使用与远端服务响应两条路径上的语义完全一致。小结Docling 的置信度评分是一套分层、可审计的质量信号四个组件分数layout_score/ocr_score/parse_score/table_score刻画具体处理环节的质量两个汇总指标mean_score→mean_grade的平均口径、low_score→low_grade的第 5 百分位口径给出页面级与文档级的整体结论且实现分布在转换管线的页面预处理、布局后处理、OCR 与最终聚合等真实阶段中可以从源码逐项追溯。实际使用时请遵循官方建议将决策锚定在mean_grade与low_grade上把数值分数当作诊断参考而非长期契约即可在批量转换、人工复核分流与管线选择等场景中获得稳定的质量观测。【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考