Classifier — 심층 참조

한눈에 보기

이 페이지는 NextPDF Pro 문서 classifier의 계약 수준 레퍼런스입니다. 표면은 하나의 오케스트레이터 NextPDF\Pro\Classifier\DocumentClassifier와 그 협력자들, 즉 StructureAnalyzer, LanguageDetector, 그리고 기본 구현 HeuristicClassifier를 갖춘 ClassifierInterface 전략으로 구성됩니다. 결과는 불변 ClassificationResult로 도착하며, 여기에는 DocumentType, [0.0, 1.0] 범위의 신뢰도, 감지된 ClassificationFeature 값, 그리고 ISO 639-1 언어 코드가 담깁니다. 분류는 규칙 기반이며 결정적입니다: 모델 추론 없음, 무작위성 없음, 네트워크 호출 없음, 파일시스템 접근 없음. 이 페이지는 공개 API, 관찰 가능한 동작 계약, 그리고 실패 모드를 명시합니다.

가용성 및 라이선싱

이 기능은 NextPDF Pro(nextpdf/pro)에 포함되어 있으며 Pro 등급 라이선스 엔벌로프로 활성화됩니다. 해당 권한이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 받기.

이 모듈을 게이트하는 런타임 기능 플래그는 없습니다. classifier 클래스는 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	복합 classifier를 위한 콘텐츠 유형 프로브	bool	—	MIME 유형 또는 콘텐츠 디스크립터를 받습니다
HeuristicClassifier	없음	기본 전략: 키워드 딕셔너리와 구조적 휴리스틱	—	예외를 던지지 않음	final; supports()는 application/pdf와 text/plain을 허용합니다
StructureAnalyzer::analyze()	string $pdfData	원시 바이트의 정규식 스캔; 전체 PDF 파싱 없음	StructureAnalysis	예외를 던지지 않음	페이지, 이미지, 폰트를 계수하고; 폼 및 서명 필드를 감지합니다
LanguageDetector::detect()	string $text	CJK 스크립트 범위 사전 검사를 포함한 트라이그램 프로필 매칭	non-empty-string ISO 639-1 코드	예외를 던지지 않음	수용 임계값 미만에서는 en으로 폴백합니다
LanguageDetector::detectWithConfidence()	string $text	detect()와 동일하며, 신뢰도를 노출합니다	array{language: non-empty-string, confidence: float}	예외를 던지지 않음	짧은 텍스트는 신뢰도 0.0으로 en을 반환합니다
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	문자열 기반 enum, 12개 케이스	케이스: Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other	백킹 값 invoice … other	—	label()은 사람이 읽을 수 있는 이름을 반환합니다
ClassificationFeature	문자열 기반 enum, 7개 케이스	케이스: HasTables, HasHeaders, HasSignatures, HasLogos, HasBarcodes, HasForms, IsScanned	백킹 값 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()는 빈 구조를 대체합니다: 페이지 0개, 카운트 0, 특징 없음. classifyFromFile()은 동일한 원시 바이트에서 구조와 텍스트를 모두 파생합니다.

휴리스틱 점수화

HeuristicClassifier는 소문자화된 텍스트를 문서 유형별 키워드 딕셔너리에 대조하여 점수화하고, 텍스트 길이로 정규화합니다. 구체적인 딕셔너리, 가중치, 임계값은 구현 세부 사항이며 발행되지 않습니다. 그다음 구조적 신호가 점수를 조정합니다: 일치하는 ClassificationFeature 값은 연관된 유형을 부스트하고; 페이지 임계값을 초과하는 문서는 Letter와 Receipt에서 멀어지도록 편향되며; 헤더와 표를 가진 여러 페이지 문서는 Report 부스트를 받고; 감지된 폼 특징은 강한 Form 신호를 추가합니다. 가장 높은 점수가 이기고 DocumentType으로 매핑됩니다. 제한된 정규화가 원시 점수를 [0.0, 1.0]으로 매핑합니다. 최소 미만 점수는 작은 0이 아닌 신뢰도 하한과 함께 DocumentType::Other를 산출합니다. 결과 metadata는 유형별 scores 맵과 method: heuristic을 담습니다. HeuristicClassifier 단독으로는 언어를 en으로 보고하며, DocumentClassifier가 감지기 출력으로 이를 재정의합니다.

언어 감지

CJK 텍스트에 대한 스크립트 범위 검사가 트라이그램 점수화 전에 실행됩니다. 한글 우세는 ko를 선택하고; 가나가 있으면 ja를 선택하며; 그렇지 않으면 충분한 표의문자 비율이 zh를 선택합니다. 그 밖의 모든 텍스트는 열 개의 내장 프로필에 대조하여 문자 트라이그램 빈도로 점수화됩니다. 가능한 반환값은 ISO 639-1 코드 en, zh, ja, ko, de, fr, es, pt, it, nl입니다. 최소 길이 미만의 텍스트는 신뢰도 0.0으로 en을 반환합니다. 좁은 마진으로 수용 임계값 미만인 결과도 en을 반환합니다. 신뢰도는 최고 프로필 점수와 두 번째 프로필 점수 사이의 마진을 반영합니다.

파일 텍스트 복구

classifyFromFile()은 원시 바이트에서 stream/endstream 세그먼트를 스캔합니다. 각 세그먼트는 제한된 인플레이션 상한 아래에서 Flate 데이터로 시도되며, 실패 시 원시 세그먼트 바이트가 사용됩니다. 인접한 스트림 딕셔너리가 /DecodeParms에 PNG 예측기를 선언하면, 역변환은 Filter 모듈의 DecodeParms 및 PngPredictor 클래스를 사용하여 ISO 32000-2:2020 §7.4.4.4에 따라 Predictor, Columns, Colors, BitsPerComponent 매개변수를 준수합니다. 그다음 텍스트는 §9.4 텍스트 표시 연산자에서 복구됩니다: Tj로 표시된 리터럴 문자열과 TJ 배열 내부의 리터럴 문자열. classifier는 복구된 텍스트를 점수화하며; 시각적 레이아웃에 의존하지 않습니다.

구조 분석

StructureAnalyzer::analyze()는 원시 바이트에서 페이지, 이미지, 폰트 토큰을 계수하고, /AcroForm과 서명 필드를 감지하며, 이미지 밀도를 파생합니다. 특징 감지는 휴리스틱입니다: 반복된 사각형 그리기는 표를 시사하고, 큰 폰트 크기 선언은 헤더를 시사하며, 폰트가 적은 높은 이미지 밀도는 스캔된 문서를 시사합니다. 카운트는 원시 바이트에 보이는 토큰을 반영하며; 압축된 객체 스트림 내부에 직렬화된 구조는 계수되지 않습니다.

결정성

전체 파이프라인은 입력 바이트의 순수 함수입니다. 동일한 입력은 동일한 ClassificationResult를 생성합니다. 모델 추론, 무작위성, 네트워크 호출, 파일시스템 접근이 없습니다.

엣지 케이스 및 실패 모드

• 비어 있거나 거의 비어 있는 텍스트는 설계상 낮은 신뢰도의 DocumentType::Other를 산출합니다. 유형만이 아니라 isConfident()로 분기하십시오.
• 이 모듈의 어떤 공개 메서드도 예외를 던지지 않습니다. 압축 해제에 실패한 스트림은 원시로 스캔되며; 잘못되거나 지원되지 않는 예측기 매개변수는 필터링되지 않은 바이트로 폴백합니다.
• 텍스트 복구는 리터럴 문자열 Tj와 TJ 형식만 일치시킵니다. 16진수 문자열, 암호화된 콘텐츠 내부의 텍스트, 스트림에 걸쳐 분할된 연산자는 복구되지 않으며, 이는 점수화에 사용 가능한 텍스트를 줄입니다.
• 압축 해제 상한은 스트림 인플레이션 중 메모리를 제한하고 압축 폭탄 입력에 저항합니다. 상한을 넘는 콘텐츠는 인플레이션되지 않습니다.
• 이미지 전용이거나 크게 압축된 PDF는 텍스트를 거의 복구하지 못하며; 낮은 신뢰도 결과를 예상하고 이를 수동 검토로 라우팅하십시오.
• 최소 텍스트 길이 미만의 언어 감지는 신뢰도 0.0으로 en을 반환하며; 매우 짧은 문자열은 결코 비영어 결과를 산출하지 않습니다.
• 열두 개의 문서 유형과 열 개의 언어 프로필은 이번 릴리스에 대해 고정되어 있습니다. 확장은 내장 데이터를 편집하는 것이 아니라 사용자 정의 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 — 심층 레퍼런스 — 형제 격인 바이트 수준 문서 비교 표면.