Classifier — Referência Profunda

Visão geral

Esta página é a referência em nível de contrato do classificador de documentos do NextPDF Pro. A superfície é um orquestrador, NextPDF\Pro\Classifier\DocumentClassifier, e seus colaboradores: StructureAnalyzer, LanguageDetector e a estratégia ClassifierInterface com seu HeuristicClassifier padrão. Os resultados chegam como um ClassificationResult imutável que carrega um DocumentType, uma confiança em [0.0, 1.0], valores ClassificationFeature detectados e um código de idioma ISO 639-1. A classificação é baseada em regras e determinística: sem inferência de modelo, sem aleatoriedade, sem chamada de rede, sem acesso ao sistema de arquivos. Esta página descreve a API pública, o contrato de comportamento observável e os modos de falha.

Disponibilidade e licenciamento

Esta capacidade é distribuída no NextPDF Pro (nextpdf/pro) e é ativada com um envelope de licença de nível Pro. Uma implantação sem esse direito de uso não carrega as classes da capacidade. Compare as edições e obtenha uma licença.

Nenhum sinalizador de capacidade em tempo de execução restringe este módulo. As classes do classificador estão disponíveis sempre que o nextpdf/pro está instalado.

Superfície pública da API

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
DocumentClassifier	construtor: StructureAnalyzer, LanguageDetector, ClassifierInterface	Orquestra a análise de estrutura, a classificação por estratégia e a detecção de idioma	—	—	final; injete colaboradores apenas para estratégias personalizadas
DocumentClassifier::create()	nenhum	Constrói os colaboradores padrão com HeuristicClassifier como estratégia	self	—	Configuração padrão determinística
DocumentClassifier::classifyFromText()	$text, $pdfData = ''	$pdfData vazio usa uma estrutura vazia; bytes brutos não vazios adicionam sinais estruturais	ClassificationResult	Não lança; entrada esparsa reduz a confiança	A detecção de idioma sempre é executada sobre $text
DocumentClassifier::classifyFromFile()	string $pdfData	Varre os fluxos de conteúdo, recupera o texto da §9.4, analisa a estrutura, classifica	ClassificationResult	Não lança; fluxos ilegíveis reduzem o texto recuperado	Varredura de bytes delimitada, não um parse completo de PDF
ClassifierInterface::classify()	$text, StructureAnalysis $structure	Contrato de estratégia consumido pelo orquestrador	ClassificationResult	Definido pela implementação	Ponto de extensão para estratégias de classificação personalizadas
ClassifierInterface::supports()	string $contentType	Sonda de tipo de conteúdo para classificadores compostos	bool	—	Recebe um tipo MIME ou descritor de conteúdo
HeuristicClassifier	nenhum	Estratégia padrão: dicionários de palavras-chave mais heurísticas estruturais	—	Não lança	final; supports() aceita application/pdf e text/plain
StructureAnalyzer::analyze()	string $pdfData	Varredura por regex dos bytes brutos; sem parse completo de PDF	StructureAnalysis	Não lança	Conta páginas, imagens, fontes; detecta campos de formulário e de assinatura
LanguageDetector::detect()	string $text	Correspondência de perfil de trigramas com verificação prévia de intervalo de script CJK	código ISO 639-1 non-empty-string	Não lança	Recorre a en abaixo do limiar de aceitação
LanguageDetector::detectWithConfidence()	string $text	Como detect(), com a confiança exposta	array{language: non-empty-string, confidence: float}	Não lança	Texto curto retorna en com confiança 0.0
ClassificationResult	construtor: $type, $confidence, $features, $language, $metadata = []	Objeto de valor imutável	—	—	final readonly; metadata carrega scores e method
ClassificationResult::isConfident()	float $threshold = 0.7	Compara a confiança com o limiar	bool	—	Gate documentado para o roteamento de revisão manual
StructureAnalysis	construtor: $pageCount, $imageCount, $fontCount, $hasFormFields, $hasSignatureFields, $imageDensity, $detectedFeatures	Objeto de valor imutável produzido por StructureAnalyzer	—	—	final readonly; imageDensity é imagens por página
DocumentType	enum baseado em string, 12 casos	Casos: Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other	valores de suporte invoice … other	—	label() retorna um nome legível por humanos
ClassificationFeature	enum baseado em string, 7 casos	Casos: HasTables, HasHeaders, HasSignatures, HasLogos, HasBarcodes, HasForms, IsScanned	valores de suporte has_tables … is_scanned	—	Sinais estruturais alimentados na classificação

Assinaturas dos pontos de entrada

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

Contrato de comportamento

Ordem do pipeline

DocumentClassifier executa a análise de estrutura, depois a classificação por estratégia, depois a detecção de idioma, e monta um ClassificationResult. A estratégia fornece o tipo, a confiança, os recursos e os metadados; o detector fornece o idioma. classifyFromText() sem bytes de PDF substitui por uma estrutura vazia: zero páginas, zero contagens, sem recursos. classifyFromFile() deriva tanto a estrutura quanto o texto dos mesmos bytes brutos.

Pontuação heurística

HeuristicClassifier pontua o texto em minúsculas contra dicionários de palavras-chave por tipo de documento, normalizados pelo comprimento do texto. Os dicionários, pesos e limiares específicos são detalhe de implementação e não são publicados. Sinais estruturais então ajustam as pontuações: valores ClassificationFeature correspondentes reforçam seus tipos associados; documentos acima de um limiar de páginas se afastam de Letter e Receipt; documentos de várias páginas com cabeçalhos e tabelas recebem um reforço de Report; um recurso de formulário detectado adiciona um forte sinal de Form. A maior pontuação vence e é mapeada para um DocumentType. Uma normalização delimitada mapeia a pontuação bruta em [0.0, 1.0]. Uma pontuação abaixo do mínimo produz DocumentType::Other com um pequeno piso de confiança diferente de zero. O metadata do resultado carrega o mapa scores por tipo e method: heuristic. HeuristicClassifier sozinho reporta o idioma en; DocumentClassifier o sobrescreve com a saída do detector.

Detecção de idioma

Uma verificação de intervalo de script para texto CJK é executada antes da pontuação por trigramas. A predominância de Hangul seleciona ko; qualquer kana seleciona ja; caso contrário, uma proporção suficiente de ideogramas seleciona zh. Todo outro texto é pontuado pela frequência de trigramas de caracteres contra dez perfis integrados. Os valores de retorno possíveis são os códigos ISO 639-1 en, zh, ja, ko, de, fr, es, pt, it e nl. Texto abaixo de um comprimento mínimo retorna en com confiança 0.0. Um resultado abaixo do limiar de aceitação com uma margem estreita também retorna en. A confiança reflete a margem entre a melhor e a segunda melhor pontuação de perfil.

Recuperação de texto de arquivo

classifyFromFile() varre os bytes brutos em busca de segmentos stream/endstream. Cada segmento é tentado como dados Flate sob um limite de inflação delimitado; em caso de falha, os bytes brutos do segmento são usados. Quando o dicionário de fluxo adjacente declara um predictor PNG em /DecodeParms, a reversão respeita os parâmetros Predictor, Columns, Colors e BitsPerComponent conforme a ISO 32000-2:2020 §7.4.4.4, usando as classes DecodeParms e PngPredictor do módulo Filter. O texto é então recuperado dos operadores de exibição de texto da §9.4: strings literais exibidas com Tj e strings literais dentro de arrays TJ. O classificador pontua o texto recuperado; ele não depende do layout visual.

Análise de estrutura

StructureAnalyzer::analyze() conta tokens de página, imagem e fonte nos bytes brutos, detecta /AcroForm e campos de assinatura, e deriva a densidade de imagens. A detecção de recursos é heurística: desenho repetido de retângulos sugere tabelas, declarações de tamanho de fonte grande sugerem cabeçalhos, e alta densidade de imagens com poucas fontes sugere um documento digitalizado. As contagens refletem os tokens visíveis nos bytes brutos; estruturas serializadas dentro de fluxos de objetos comprimidos não são contadas.

Determinismo

Todo o pipeline é uma função pura de seus bytes de entrada. Uma entrada idêntica produz um ClassificationResult idêntico. Não há inferência de modelo, nem aleatoriedade, nem chamada de rede, nem acesso ao sistema de arquivos.

Casos extremos e modos de falha

• Texto vazio ou quase vazio produz um DocumentType::Other de baixa confiança por design. Ramifique com base em isConfident() em vez de apenas no tipo.
• Nenhum método público deste módulo lança. Fluxos que falham na descompressão são varridos brutos; parâmetros de predictor malformados ou não suportados recorrem aos bytes não filtrados.
• A recuperação de texto corresponde apenas às formas de string literal Tj e TJ. Strings hexadecimais, texto dentro de conteúdo criptografado e operadores divididos entre fluxos não são recuperados, o que reduz o texto disponível para pontuar.
• O limite de descompressão delimita a memória durante a inflação de fluxo e resiste a entradas de bomba de descompressão. Conteúdo além do limite não é inflado.
• PDFs somente de imagem ou fortemente comprimidos recuperam pouco texto; espere resultados de baixa confiança e roteie-os para revisão manual.
• A detecção de idioma abaixo do comprimento mínimo de texto retorna en com confiança 0.0; strings muito curtas nunca produzem um resultado diferente do inglês.
• Os doze tipos de documento e os dez perfis de idioma são fixos para esta versão. A extensão se dá via uma implementação personalizada de ClassifierInterface, não pela edição dos dados integrados.
• Nenhuma operação criptográfica ocorre neste módulo, então não há comportamento específico de modo FIPS.

Conformidade

Alegação	Padrão	Cláusula
A classificação de arquivo recupera o texto exibido com o operador Tj.	ISO 32000-2:2020	§9.4
A classificação de arquivo recupera strings literais dentro de operadores de array TJ.	ISO 32000-2:2020	§9.4
A reversão do predictor PNG respeita os parâmetros de filtro Predictor, Columns, Colors e BitsPerComponent.	ISO 32000-2:2020	§7.4.4.4

Os códigos de idioma seguem a ISO 639-1; esta é uma declaração fundamentada no produto sobre o formato de saída, não uma alegação de conformidade citada. Todas as cláusulas são parafraseadas; o NextPDF não reproduz texto normativo. Estas são declarações de capacidade, não certificações. O NextPDF não detém nenhuma certificação e não concede nenhuma. A classificação é heurística e de melhor esforço: o módulo assegura determinismo, não acurácia, e os chamadores são donos do limiar de decisão.

Notas de desenvolvimento

• Disponível desde o nextpdf/pro 2.2.0; atual no nextpdf/pro 3.1.0.
• Use DocumentClassifier::create() para o pipeline padrão. Injete colaboradores apenas para fornecer uma estratégia ClassifierInterface personalizada.
• Trate resultados abaixo do limiar como incertos e roteie-os para revisão manual; isConfident() com seu padrão 0.7 é o gate documentado.
• O módulo não armazena nada, não emite telemetria e não registra a entrada. Se os chamadores persistirem metadata, revise-o primeiro em relação à própria política de tratamento de dados.
• A pontuação por palavras-chave e a contagem de trigramas são lineares no comprimento do texto. A análise de estrutura é linear no comprimento de bytes do PDF sob o limite de descompressão delimitado. O orçamento da página é 1000 ms de tempo de parede e 64 MB de pico de memória.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície pública da API suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de tíquetes estão fora do escopo.

Veja também

• Classifier (capacidade) — instalação, início rápido e amostras de roteamento em produção.
• Extraction — Referência Profunda — a superfície completa de extração de texto para uma entrada de texto mais rica.
• Filter — Referência Profunda — DecodeParms e PngPredictor, usados durante a classificação de arquivo.
• Diff — Referência Profunda — a superfície irmã de comparação de documentos em nível de bytes.