Classifier

한눈에 보기

NextPDF\Pro\Classifier는 문서 텍스트와 구조에 대한 결정적 휴리스틱을 사용해 문서 유형(인보이스, 계약서, 보고서 등)과 탐지된 언어를 할당합니다. 이는 머신러닝 모델이 아니라 규칙 기반입니다.

가용성 및 라이선스

이 기능은 NextPDF Pro(nextpdf/pro)로 제공되며 Pro 등급 라이선스 봉투로 활성화됩니다. 해당 권한이 없는 배포에서는 이 기능의 클래스가 로드되지 않습니다. 에디션 비교 및 라이선스 받기.

이 모듈을 게이트하는 런타임 기능 플래그는 없습니다. Classifier 클래스는 nextpdf/pro가 설치되어 있으면 언제나 사용할 수 있습니다.

설치

composer require nextpdf/pro:^3

개념 개요

DocumentClassifier는 세 협력자를 오케스트레이션합니다.

• **StructureAnalyzer**는 PDF에서 페이지 수, 이미지 및 글꼴 수, 양식/서명 필드를 검사하여 StructureAnalysis를 생성합니다.
• HeuristicClassifier(기본 ClassifierInterface)는 유형별 키워드 사전을 기준으로 텍스트에 점수를 매기고 구조적 휴리스틱을 적용하여(예를 들어, 짧은 문서는 “report”에서 멀어지는 편향을 가집니다) DocumentType과 신뢰도를 산출합니다.
• **LanguageDetector**는 열 가지 언어의 문자 트라이그램 빈도 프로필로부터 언어를 식별하며, 신뢰도 임계값 미만에서는 영어로 폴백합니다.

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 표면, 파이프라인 순서, 실패 모드.
• 추출
• 필터
• Diff