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.0～1.0，越高表示转换质量越好）与一个质量等级（quality grade，取值为poor、fair、good、excellent），供使用者快速判断。

典型使用场景包括：

• 识别转换后需要人工复核的文档；
• 为不同文档类型匹配合适的转换管线；
• 为无人值守批量转换设置置信度阈值（低于阈值即告警或转人工）；
• 在工作流早期提前捕获潜在的转换问题。

官方明确建议：重点看质量等级而非数值

!> 官方提示（原文档中的 note）：使用者可以且应当放心地把注意力放在文档级等级字段——mean_grade与low_grade——上来评估整体转换质量。数值分数仅供内部参考，其计算方式与权重在未来可能发生变化，不应作为跨版本比较的稳定依据。

概念拆解：分数（Scores）与等级（Grades）

一份置信度报告同时包含两类内容：

等级来自枚举类型QualityGrade，定义在 docling/datamodel/base_models.py：

class QualityGrade(str, Enum): POOR = "poor" FAIR = "fair" GOOD = "good" EXCELLENT = "excellent" UNSPECIFIED = "unspecified"

UNSPECIFIED用于"暂无数据"的兜底状态。分数到等级的映射见源码中的PageConfidenceScores._score_to_grade（base_models.py）：

四类组件分数：layout / ocr / parse / table

每份置信度报告包含四个组件分数，它们由转换管线中不同的处理阶段负责写入：

• layout_score：文档元素（标题、段落、图片等）识别的整体质量。在布局后处理阶段，页面级layout_score取各布局聚类置信度cluster.confidence的均值（聚类为空时回退为0.0），实现见 docling/models/stages/layout/layout_postprocessing_model.py。
• ocr_score：OCR 提取内容的文本识别质量。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(..., q=0.10)。
• table_score：表格抽取质量——尚未实现（not yet implemented），在数据模型中默认值为np.nan，见 base_models.py。

parse_score的文本质量评分启发式实现（rate_text_quality，page_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.py）：

• mean_grade：四个组件分数的平均值所对应的等级。实现上通过np.nanmean对ocr_score / table_score / layout_score / parse_score求平均，因此尚未产生数据的组件（如未实现的table_score默认NaN）会被自动忽略，再经阈值映射得到等级；
• low_grade：四个组件分数的第 5 百分位所对应的等级，用于突出表现最差的方向。实现采用np.nanquantile(..., q=0.05)。

两者都以computed_field（计算属性）形式暴露（mean_grade/low_grade源码见 base_models.py），因此无论页面级还是文档级对象上读取到的mean_grade/low_grade都是"实时计算、天然一致"的。

官方口径与实现的细微分野

需要指出：官方概念文档将mean_grade描述为"四个组件分数的平均"，将low_grade描述为"第 5 百分位分数"。从源码实现看，数值层面使用的是np.nanmean（忽略NaN的均值）与np.nanquantile(q=0.05)（忽略NaN的分位数）。两者在文档描述口径上一致，但NaN组件的处理细节属于实现层差异——这也再次印证官方"数值仅供内部参考、计算细节可能调整"的提示。

页面级 vs 文档级：两套层次的对象结构

置信度按两个层级计算：

• 页面级：每页各自的分数与等级，保存在pages字段（dict[int, PageConfidenceScores]）；
• 文档级：整篇文档的整体分数与等级，由各页面等级求平均得到，存放在ConfidenceReport根级同名字段中。

对应到源码，两个 Pydantic 模型定义在 base_models.py：

• PageConfidenceScores：持有四个组件分数 + 四个 computed 属性（mean_score/low_score/mean_grade/low_grade）；字段校验器接受None或字符串"NaN"/"null"/""并统一转换为np.nan，兼容性良好（base_models.py）；
• ConfidenceReport(PageConfidenceScores)：在继承页面字段之外增加pages: dict[int, PageConfidenceScores]，并重写文档级mean_score/low_score的计算逻辑——当存在页面记录时，文档级均值取"各页面mean_score的nanmean"、文档级低分取"各页面low_score的nanmean"（base_models.py），即先逐页求统计量、再做跨页汇总。

上面概念文档配图中的输出（docs/assets/confidence_scores.png）展示的正是这样一个典型对象快照：ConfidenceReport根级包含parse_score = 1.0、layout_score ≈ 0.915、ocr_score与table_score为nan，mean_score ≈ 0.957，mean_grade = EXCELLENT，同时pages中以页号为键存放PageConfidenceScores。

从源码看分数如何被"写"出来：文档级聚合的入口

在标准 PDF 转换管线的收尾阶段，会一次性把各页面的组件分数聚合回文档级ConfidenceReport，见 docling/pipeline/standard_pdf_pipeline.py：

conv_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()], q=0.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(), key=lambda 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