Classifier

速览

NextPDF\Pro\Classifier 通过对文档文本与结构应用确定性的启发式方法，为文档分配一个文档类型（发票、合同、报告等）和一种检测到的语言。它基于规则，而不是机器学习模型。

可用性与授权

此能力包含在 NextPDF Pro（nextpdf/pro）中，并通过 Pro 层级的授权信封激活。缺少该授权的部署不会加载此能力的类。比较各版本并获取授权。

没有任何运行时能力标志对该模块进行门控。只要安装了 nextpdf/pro，Classifier 类即可用。

安装

composer require nextpdf/pro:^3

概念概述

DocumentClassifier 编排三个协作者：

• StructureAnalyzer 检查 PDF 的页数、图像与字体数量，以及表单/签名字段，产出一个 StructureAnalysis。
• HeuristicClassifier（默认的 ClassifierInterface）依据按类型组织的关键词词典为文本评分，并应用结构性启发式方法（例如，短文档会偏向远离“report”），从而得出一个 DocumentType 和一个置信度。
• LanguageDetector 根据十种语言的字符三元组（trigram）频率特征识别语言，当置信度低于阈值时回退到英语。

classifyFromText() 接受已提取的文本（可选地附带用于结构分析的原始 PDF 字节）；classifyFromFile() 接受原始 PDF 字节，并通过直接解析 §9.4 的文本显示运算符来提取文本。

为何如此设计

关键的承重决策是使用确定性启发式方法进行分类，而不是机器学习模型。基于规则的流水线是其输入的纯函数：相同的字节始终产生相同的类型、置信度和语言，没有模型漂移，也没有网络调用。这种确定性让结果得以暴露一个明确的置信度、一个 isConfident() 门控，以及一个按类型划分的 scores 映射，从而使该模块展示它如何做出判断，而不是把选择隐藏在模型背后。因此，调用方可按约定将低置信度文档路由到人工审核，而过短以至无法评分的文本则在同一固定规则下回退为 en。这是一种有意的取舍：准确率受固定的关键词与三元组特征所限，以此换取可复现性、可检视性，以及一个完全在进程内运行的分类器。

设计背景：一个拒绝猜测的 API。

行为契约

• 输入。 已提取的文本（classifyFromText）或原始 PDF 字节（classifyFromFile）。空输入是有效的，会产生一个低置信度结果，通常为 DocumentType::Other。
• 输出。 一个 ClassificationResult，包含 DocumentType、一个位于 [0.0, 1.0] 的置信度、检测到的结构特征、一个 ISO 639-1 语言代码，以及元数据。isConfident(0.7) 是有文档记录的阈值辅助方法。
• 确定性。 分类与语言检测都是输入的纯函数 —— 相同输入、相同结果，无随机性、无网络。
• 范围。 十二种文档类型和十种语言特征，两者在本版本中均为固定。自定义策略可通过 ClassifierInterface 提供。

公共 API 接口

类型	种类	关键成员
NextPDF\Pro\Classifier\DocumentClassifier	final class	static create(): self, classifyFromText(string $text, string $pdfData = ''): ClassificationResult, classifyFromFile(string $pdfData): ClassificationResult
NextPDF\Pro\Classifier\ClassifierInterface	interface	classify(string $text, StructureAnalysis $structure): ClassificationResult, supports(string $contentType): bool
NextPDF\Pro\Classifier\HeuristicClassifier	final class	implements ClassifierInterface
NextPDF\Pro\Classifier\StructureAnalyzer	final class	analyze(string $pdfData): StructureAnalysis
NextPDF\Pro\Classifier\LanguageDetector	final class	detect(string $text): string
NextPDF\Pro\Classifier\ClassificationResult	final readonly class	DocumentType $type, float $confidence, array $features, string $language, isConfident(float $threshold = 0.7): bool
NextPDF\Pro\Classifier\DocumentType	enum	12 个枚举项（Invoice、Contract、Form、Report、Letter、Receipt、Legal、Medical、Financial、Technical、Academic、Other）；label(): string

代码示例 —— 快速上手

<?php

declare(strict_types=1);

use NextPDF\Pro\Classifier\DocumentClassifier;

$result = DocumentClassifier::create()
    ->classifyFromText('Invoice #4471 — Amount due: $1,200.00');

printf(
    "%s (%.0f%% confidence), lang=%s\n",
    $result->type->label(),
    $result->confidence * 100,
    $result->language,
);

代码示例 —— 生产环境

<?php

declare(strict_types=1);

use NextPDF\Pro\Classifier\DocumentClassifier;
use NextPDF\Pro\Classifier\DocumentType;

function routeDocument(string $pdfBytes): string
{
    $result = DocumentClassifier::create()->classifyFromFile($pdfBytes);

    if (! $result->isConfident(0.7)) {
        return 'manual-review';
    }

    return match ($result->type) {
        DocumentType::Invoice, DocumentType::Receipt => 'accounts-payable',
        DocumentType::Contract, DocumentType::Legal   => 'legal-intake',
        default                                       => 'general-inbox',
    };
}

边界情况与注意事项

• 置信度是启发式的。请将低于阈值的结果视为“不确定”，并按生产示例那样路由到人工审核。
• 语言检测需要足够的文本；非常短的字符串按设计会回退到英语。
• classifyFromFile() 使用有界的字节级文本提取；高度压缩或仅含图像的 PDF 会减少可供评分的文本。
• 文档类型集合和语言集合在本版本中是固定的；请通过实现 ClassifierInterface 来扩展分类，而不是改动内置词典。

数据驻留与 PII 缓解措施

分类在进程内运行，没有网络调用，也不存储输入。结果包含一个 DocumentType 和语言代码，而不包含源文本。如果调用方持久化 metadata，请在存储前审查其中是否有偶然的 PII。

安全遥测与日志清洗

该模块不发出任何遥测数据，也不记录任何输入。添加日志记录的调用方应只记录所得到的 DocumentType 和语言代码，绝不记录被分类的文本。

性能

关键词评分和三元组计数随文本长度呈线性。结构分析随 PDF 字节长度呈线性，并设有解压上限。参见 performance_budget。

安全说明

classifyFromFile() 以有界扫描和解压尺寸上限来解析不受信任的 PDF 字节，以抵御解压炸弹式输入。不会执行任何嵌入脚本。

一致性

主张	规范条款	状态
通过 Tj 恢复文本以进行文件分类	ISO 32000-2:2020 §9.4	已验证（单元测试套件）
通过 TJ 恢复文本以进行文件分类	ISO 32000-2:2020 §9.4	已验证（单元测试套件）
基于机器学习/模型的分类	—	不支持（仅启发式）

Core 回退/替代方案

文档分类或语言检测没有 Core 等价物。

Enterprise 边界说明

此分类器基于规则且具确定性。它不执行任何嵌入、向量相似度、模型推理或语义理解。这些能力不属于本模块，也不为本模块所暗示。

发布边界

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

另请参阅

• Classifier —— 深度参考 —— 完整的公共 API 接口、流水线顺序和失败模式。
• Extraction
• Filter
• Diff