Classifier — 深度参考

速览

本页是 NextPDF Pro 文档分类器的契约级参考。其接口面是一个编排器 NextPDF\Pro\Classifier\DocumentClassifier 及其协作者：StructureAnalyzer、LanguageDetector，以及带有默认 HeuristicClassifier 的 ClassifierInterface 策略。结果以不可变的 ClassificationResult 返回，其中携带一个 DocumentType、一个位于 [0.0, 1.0] 的置信度、检测到的 ClassificationFeature 值，以及一个 ISO 639-1 语言代码。分类是基于规则且确定性的：没有模型推理、没有随机性、没有网络调用、没有文件系统访问。本页阐明公共 API、可观察的行为契约，以及失败模式。

可用性与授权

本能力随 NextPDF Pro（nextpdf/pro）发布，并通过 Pro 级授权信封激活。没有该权益的部署不会加载本能力的类。比较版本并获取授权。

没有运行时能力标记限制本模块。只要安装了 nextpdf/pro，分类器的类就可用。

公共 API 接口面

符号	参数	默认行为	返回	抛出或失败于	备注
DocumentClassifier	构造函数：StructureAnalyzer、LanguageDetector、ClassifierInterface	编排结构分析、策略分类与语言检测	—	—	final；仅在使用自定义策略时注入协作者
DocumentClassifier::create()	无	以 HeuristicClassifier 作为策略构建默认协作者	self	—	确定性的默认配置
DocumentClassifier::classifyFromText()	$text、$pdfData = ''	空的 $pdfData 使用空结构；非空的原始字节会加入结构性信号	ClassificationResult	不抛出；稀疏输入会降低置信度	语言检测始终在 $text 上运行
DocumentClassifier::classifyFromFile()	string $pdfData	扫描内容流，恢复 §9.4 文本，分析结构，进行分类	ClassificationResult	不抛出；不可读的流会减少恢复出的文本	有界的字节扫描，而非完整的 PDF 解析
ClassifierInterface::classify()	$text、StructureAnalysis $structure	由编排器消费的策略契约	ClassificationResult	由实现定义	自定义分类策略的扩展点
ClassifierInterface::supports()	string $contentType	用于组合式分类器的内容类型探测	bool	—	接收一个 MIME 类型或内容描述符
HeuristicClassifier	无	默认策略：关键词词典加结构性启发式	—	不抛出	final；supports() 接受 application/pdf 与 text/plain
StructureAnalyzer::analyze()	string $pdfData	对原始字节的正则扫描；不做完整 PDF 解析	StructureAnalysis	不抛出	统计页面、图像、字体；检测表单与签名字段
LanguageDetector::detect()	string $text	三元组 profile 匹配，带 CJK 文字范围预检	non-empty-string ISO 639-1 代码	不抛出	低于接受阈值时回退到 en
LanguageDetector::detectWithConfidence()	string $text	同 detect()，但公开置信度	array{language: non-empty-string, confidence: float}	不抛出	短文本返回 en，置信度为 0.0
ClassificationResult	构造函数：$type、$confidence、$features、$language、$metadata = []	不可变值对象	—	—	final readonly；metadata 携带 scores 与 method
ClassificationResult::isConfident()	float $threshold = 0.7	将置信度与阈值比较	bool	—	用于人工复核路由的既定门槛
StructureAnalysis	构造函数：$pageCount、$imageCount、$fontCount、$hasFormFields、$hasSignatureFields、$imageDensity、$detectedFeatures	由 StructureAnalyzer 产出的不可变值对象	—	—	final readonly；imageDensity 为每页图像数
DocumentType	字符串支撑的枚举，12 个 case	case：Invoice、Contract、Form、Report、Letter、Receipt、Legal、Medical、Financial、Technical、Academic、Other	backing values invoice … other	—	label() 返回一个人类可读的名称
ClassificationFeature	字符串支撑的枚举，7 个 case	case：HasTables、HasHeaders、HasSignatures、HasLogos、HasBarcodes、HasForms、IsScanned	backing values has_tables … is_scanned	—	输入到分类的结构性信号

入口点签名

public static function create(): self

public function classifyFromText(string $text, string $pdfData = ''): ClassificationResult

public function classifyFromFile(string $pdfData): ClassificationResult

public function classify(string $text, StructureAnalysis $structure): ClassificationResult;

public function supports(string $contentType): bool;

public function analyze(string $pdfData): StructureAnalysis

public function detect(string $text): string

public function detectWithConfidence(string $text): array

public function __construct(
    public DocumentType $type,
    public float $confidence,
    public array $features,
    public string $language,
    public array $metadata = [],
) {}

public function isConfident(float $threshold = 0.7): bool

行为契约

流水线顺序

DocumentClassifier 先运行结构分析，再做策略分类，然后做语言检测，并组装一个 ClassificationResult。策略提供类型、置信度、特征与元数据；检测器提供语言。不带 PDF 字节的 classifyFromText() 会以空结构替代：零页面、零计数、无特征。classifyFromFile() 从同一批原始字节中同时导出结构与文本。

启发式评分

HeuristicClassifier 将小写化的文本对照逐文档类型的关键词词典进行评分，并按文本长度归一化。具体的词典、权重与阈值属于实现细节，不予公布。随后结构性信号会调整这些评分：匹配的 ClassificationFeature 值会提升其关联的类型；超过某个页数阈值的文档会偏离 Letter 与 Receipt；带有页眉与表格的多页文档会获得一个 Report 加成；检测到的表单特征会加入一个强烈的 Form 信号。最高分胜出并映射到一个 DocumentType。一个有界的归一化将原始分数映射到 [0.0, 1.0]。低于最小值的分数会产出 DocumentType::Other，并带有一个小的非零置信度下限。结果的 metadata 携带逐类型的 scores 映射以及 method: heuristic。单独使用的 HeuristicClassifier 报告语言为 en；DocumentClassifier 会用检测器的输出将其覆盖。

语言检测

针对 CJK 文本的文字范围检查在三元组评分之前运行。谚文占主导会选择 ko；出现任意假名会选择 ja；否则足够的表意文字比例会选择 zh。所有其他文本按字符三元组频率对照十个内置 profile 进行评分。可能的返回值是 ISO 639-1 代码 en、zh、ja、ko、de、fr、es、pt、it 与 nl。低于最小长度的文本返回 en，置信度为 0.0。低于接受阈值且差距狭窄的结果同样返回 en。置信度反映最佳与次佳 profile 分数之间的差距。

文件文本恢复

classifyFromFile() 扫描原始字节以查找 stream/endstream 段。每一段都会在一个有界的膨胀上限下按 Flate 数据尝试；失败时则使用该段的原始字节。当相邻的流字典在 /DecodeParms 中声明了 PNG 预测器时，逆转会依据 ISO 32000-2:2020 §7.4.4.4 遵循 Predictor、Columns、Colors 与 BitsPerComponent 参数，使用 Filter 模块的 DecodeParms 与 PngPredictor 类。随后从 §9.4 文本显示运算符中恢复文本：以 Tj 显示的字面字符串，以及 TJ 数组内部的字面字符串。分类器对恢复出的文本评分；它不依赖于视觉版面。

结构分析

StructureAnalyzer::analyze() 统计原始字节中的页面、图像与字体标记，检测 /AcroForm 与签名字段，并导出图像密度。特征检测是启发式的：重复的矩形绘制暗示表格，大字号声明暗示页眉，高图像密度加少量字体暗示扫描文档。计数反映原始字节中可见的标记；序列化在压缩对象流内部的结构不计入。

确定性

整条流水线是其输入字节的纯函数。相同的输入产出相同的 ClassificationResult。没有模型推理、没有随机性、没有网络调用，也没有文件系统访问。

边界情形与失败模式

• 空或近乎空的文本在设计上会产出一个低置信度的 DocumentType::Other。请基于 isConfident() 分支处理，而非仅依据类型。
• 本模块没有任何公共方法会抛出异常。解压失败的流会按原始字节扫描；畸形或不受支持的预测器参数会回退到未过滤的字节。
• 文本恢复仅匹配字面字符串的 Tj 与 TJ 形式。十六进制字符串、加密内容内部的文本，以及跨流拆分的运算符不会被恢复，这会减少可供评分的文本。
• 解压上限在流膨胀期间限制内存，并抵御解压炸弹输入。超出上限的内容不会被膨胀。
• 纯图像或高度压缩的 PDF 恢复出的文本很少；应预期低置信度结果，并将它们路由到人工复核。
• 低于最小文本长度的语言检测返回 en，置信度为 0.0；非常短的字符串永远不会产出非英语的结果。
• 这十二种文档类型与十个语言 profile 在本发行版中是固定的。扩展通过一个自定义的 ClassifierInterface 实现进行，而非通过编辑内置数据。
• 本模块中不发生任何密码学操作，因此没有 FIPS 模式专属行为。

符合性

声明	标准	条款
文件分类会恢复以 Tj 运算符显示的文本。	ISO 32000-2:2020	§9.4
文件分类会恢复 TJ 数组运算符内部的字面字符串。	ISO 32000-2:2020	§9.4
PNG 预测器逆转遵循 Predictor、Columns、Colors 与 BitsPerComponent 过滤器参数。	ISO 32000-2:2020	§7.4.4.4

语言代码遵循 ISO 639-1；这是关于输出格式的、基于产品的陈述，而非引用性的符合性声明。所有条款均为转述；NextPDF 不复制规范性文本。这些是能力陈述，而非认证。NextPDF 不持有任何认证，也不授予任何认证。分类是启发式的、尽力而为的：本模块断言的是确定性，而非准确性，且决策阈值由调用方自行掌握。

开发说明

• 自 nextpdf/pro 2.2.0 起可用；当前为 nextpdf/pro 3.1.0。
• 对于默认流水线使用 DocumentClassifier::create()。仅在提供自定义 ClassifierInterface 策略时才注入协作者。
• 将低于阈值的结果视为不确定，并将其路由到人工复核；带有 0.7 默认值的 isConfident() 即既定的门槛。
• 本模块不存储任何内容、不发出遥测，也不记录任何输入。如果调用方持久化 metadata，请先依据其自身的数据处理策略审查它。
• 关键词评分与三元组计数在文本长度上是线性的。在有界解压上限下，结构分析在 PDF 字节长度上是线性的。本页的预算为 1000 ms 墙钟时间与 64 MB 峰值内存。

发布边界

本页仅记录外部可观察的行为以及受支持的公共 API 接口面。内部命名空间路径、辅助类、机制表、运行手册文件名以及工单前缀均不在范围之内。

另请参阅

• Classifier（能力） — 安装、快速开始与生产路由示例。
• Extraction — 深度参考 — 用于更丰富输入文本的完整文本提取接口面。
• Filter — 深度参考 — 文件分类期间使用的 DecodeParms 与 PngPredictor。
• Diff — 深度参考 — 同级的字节级文档比较接口面。