Intelligence

In sintesi

NextPDF Enterprise Intelligence converte dati grezzi chiave-valore e tabellari in strutture tipizzate ed eventualmente validate da schema, e orchestra la generazione di PDF ricercabili pilotando un backend OCR sulle pagine acquisite da scanner. Descrive le strutture che produce; non asserisce l’accuratezza dell’OCR né il recall dell’estrazione.

Disponibilità e licenza

Questa funzionalità è inclusa in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di livello Enterprise. Una distribuzione priva di tale diritto non carica le classi della funzionalità. Una distribuzione priva di un diritto Enterprise attivo non carica queste classi. Confronta le edizioni e ottieni una licenza.

Installazione

composer require nextpdf/enterprise:^3

Panoramica concettuale

L’estrattore strutturato prende coppie chiave-valore grezze — prodotte a monte da un accelerator o da un parser euristico — ed emette oggetti coppia tipizzati. Quando viene fornito uno schema, mantiene soltanto le coppie la cui chiave corrisponde a un campo dello schema e segnala quali campi obbligatori mancano. Una coppia priva di una confidenza esplicita riceve un valore predefinito fisso. Si tratta di un passaggio di tipizzazione e convalida su dati già estratti; non è di per sé un motore di estrazione o di riconoscimento e non assegna alcuna precisione calcolata.

L’estrattore di tabelle prende griglie di righe grezze e costruisce risultati tabellari strutturati con oggetti per ciascuna cella e bounding box uniformi sintetizzati, ricavati suddividendo un’area di pagina normalizzata. Le righe corte vengono completate con riempimento affinché ogni riga abbia il numero di colonne più ampio. Una tabella senza righe o senza colonne viene saltata. I bounding box sono una sintesi a griglia uniforme, non un layout misurato.

L’orchestratore di overlay ricercabili accetta un PDF acquisito da scanner o misto, rileva quali pagine sono prive di un livello di testo utilizzabile, pilota il backend OCR configurato e produce un risultato che descrive i conteggi di parole per pagina e una confidenza media. Il testo invisibile è il meccanismo per una pagina acquisita ricercabile: un operatore di mostra del testo può posizionare i glifi mentre la modalità di rendering del testo è impostata in modo che il testo non sia né riempito né tracciato — ISO 32000-2:2020 §9.3.3 — e gli operatori di mostra del testo posizionano i glifi nel content stream — ISO 32000-2:2020 §9.4. Quando l’origine è taggata, la gerarchia di struttura logica mappa il contenuto su un ordine di lettura — ISO 32000-2:2020 §14.7, la struttura taggata supporta il riutilizzo del contenuto — ISO 32000-2:2020 §14.8 e gli elementi di struttura tabellare descrivono righe e celle — ISO 32000-2:2020 §14.8.

La rasterizzazione vera e propria e l’iniezione del testo invisibile sono eseguite da un processo sidecar separato; la superficie PHP orchestra il flusso di lavoro e produce i metadati del risultato. L’output di un’esecuzione di overlay è un documento derivato: qualsiasi firma esistente viene invalidata e lo stato di compliance richiede una nuova convalida. I valori di confidenza sono passanti o valori predefiniti fissi, non una garanzia di accuratezza.

Perché funziona così

La superficie traccia una linea netta tra strutturazione e riconoscimento. La tipizzazione e la convalida da schema vengono eseguite in-process, perché sono deterministiche ed economiche. Il riconoscimento — rasterizzazione e iniezione del testo invisibile — è delegato a un backend OCR iniettato e a un sidecar separato, perché è oneroso, specifico del backend e conviene tenerlo al di fuori del confine di fiducia PHP. Questa separazione consente a una distribuzione di scegliere dove le immagini del documento e il testo riconosciuto vengono calcolati e archiviati, senza modificare il codice chiamante. Il modulo si rifiuta inoltre di inventare un valore di precisione: una coppia priva di etichetta riceve un valore predefinito fisso e la confidenza riportata è passante anziché calcolata. A un chiamante non viene mai consegnato un numero di accuratezza fabbricato.

Contesto di progettazione: Un’API che si rifiuta di indovinare.

Superficie API

Tipo	Genere	Ruolo	Stabilità	Da
StructuredExtractor	class	Tipizza coppie chiave-valore grezze; filtro per schema e controllo dei campi obbligatori	stable	2.2.0
ExtractionSchema / SchemaField	classes	Definizioni dei campi e insieme dei campi obbligatori	stable	2.2.0
KeyValuePair	class	Una coppia chiave-valore tipizzata con confidenza	stable	2.2.0
TableExtractor	class	Costruisce tabelle strutturate da griglie di righe grezze	stable	2.2.0
TableResult / TableCell	classes	Forma della tabella con testo, confidenza e bounding box per ciascuna cella	stable	2.2.0
SearchableOverlay	class	Orchestra la generazione di PDF ricercabili basata su OCR	stable	2.2.0
OverlayConfig / OverlayQuality	classes	Suggerimento di lingua, DPI, preset di qualità, salto delle pagine native	stable	2.2.0
SearchableOverlayResult / PageOverlayInfo	classes	Conteggi di parole per pagina e confidenza media	stable	2.2.0
ExtractionConfig / ExtractionStrategy	classes	Strategia euristica vs. assistita da OCR e suggerimenti OCR	stable	2.2.0

Il backend OCR è un contratto iniettato. L’orchestratore non incorpora un modello OCR; la distribuzione fornisce il backend ed è responsabile di dove l’OCR viene calcolato.

Esempio di codice — Avvio rapido

Type and schema-validate raw key-value pairs

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Enterprise\Intelligence\StructuredExtractor;
use NextPDF\Enterprise\Intelligence\ExtractionSchema;

/**
 * Type raw pairs against a schema and list any missing required fields.
 *
 * @param list<array{key: string, value: string, confidence?: float}> $rawPairs Upstream key-value data.
 *
 * @return list<string> Missing required field names (empty when compliant).
 */
function validate(array $rawPairs, ExtractionSchema $schema): array
{
    $extractor = new StructuredExtractor();
    $pairs = $extractor->extract($rawPairs, $schema);

    return $extractor->validateSchema($schema, $pairs);
}

L’estrattore tipizza e filtra dati che un passaggio a monte ha già prodotto. Non esegue di per sé alcun riconoscimento.

Esempio di codice — Produzione

Searchable-overlay orchestration with safe logging

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Enterprise\Accelerator\OcrStrategyInterface;
use NextPDF\Enterprise\Intelligence\OverlayConfig;
use NextPDF\Enterprise\Intelligence\SearchableOverlay;
use Psr\Log\LoggerInterface;

final readonly class OverlayJob
{
    public function __construct(
        private OcrStrategyInterface $ocr,
        private LoggerInterface $logger,
    ) {}

    /**
     * Generate a searchable PDF from a scanned input.
     *
     * @param string $pdfData Scanned or mixed PDF bytes.
     *
     * @return string The derived searchable PDF bytes.
     */
    public function run(string $pdfData): string
    {
        try {
            $result = (new SearchableOverlay($this->ocr))
                ->generate($pdfData, new OverlayConfig(language: 'eng'));

            $this->logger->info('Overlay complete', [
                'pages' => $result->pageCount,
                'words' => $result->wordCount,
            ]);

            return $result->pdfData;
        } catch (\Throwable $e) {
            $this->logger->error('Overlay failed', ['error' => $e->getMessage()]);

            throw $e;
        }
    }
}

Il log riporta soltanto i conteggi di pagine e parole. Non riporta il testo riconosciuto né i byte del documento. Il blocco catch ri-solleva l’eccezione; non assorbe il fallimento.

Casi limite e insidie

• Gli estrattori strutturato e tabellare consumano dati già estratti. Non analizzano un PDF, non eseguono un modello e non misurano la precisione. La confidenza è passante o un valore predefinito fisso.
• I bounding box di tabella sintetizzati sono una suddivisione a griglia uniforme, non un layout misurato. Un chiamante che ha bisogno della geometria reale deve ottenerla altrove.
• L’overlay ricercabile è un documento derivato. Qualsiasi firma digitale esistente viene invalidata; lo stato di compliance deve essere riconvalidato dopo l’overlay.
• Quando il backend OCR non è disponibile, le pagine interessate contribuiscono con zero parole anziché far fallire silenziosamente l’intera esecuzione — verificare il risultato per pagina.
• Una pagina che dispone già di un livello di testo nativo utilizzabile viene saltata per impostazione predefinita. Disabilitare il salto nella configurazione se occorre ri-eseguire l’OCR.
• L’accuratezza dell’OCR dipende interamente dal backend fornito, dalla qualità dell’input e dal suggerimento di lingua. NextPDF non asserisce l’accuratezza del riconoscimento né il recall dell’estrazione.

Prestazioni

L’estrazione strutturata e tabellare è lineare rispetto alla dimensione dell’input. Il costo dell’overlay ricercabile è dominato dal backend OCR e dalla rasterizzazione del sidecar al DPI configurato; l’overhead di orchestrazione è ridotto. Gli input di pagine e dimensioni sono limitati e falliscono in modo chiuso in caso di overflow. Il profilo di riproducibilità è structural: l’estrazione è deterministica per un input fisso, mentre l’output dell’overlay dipende dal backend OCR e può variare tra backend o versioni.

Note di sicurezza

Gli estrattori sono passaggi di strutturazione in sola lettura. La superficie di overlay produce un documento derivato e limita la dimensione dell’input e il numero di pagine, fallendo in modo chiuso in caso di overflow. Il backend OCR è un punto di integrazione, non parte del confine di fiducia; una distribuzione lo sceglie e lo gestisce. In questo modulo non avviene alcuna operazione crittografica, perciò non avanza alcuna rivendicazione FIPS.

Residenza dei dati e mitigazioni dei dati personali (PII)

L’estrazione strutturata e tabellare viene eseguita in-process sull’host. L’orchestrazione di overlay ricercabili pilota un backend OCR iniettato: dove tale backend viene eseguito — in-process, in un sidecar locale o in un servizio remoto — e quindi dove le immagini del documento e il testo riconosciuto vengono calcolati e archiviati, è una responsabilità della distribuzione esterna al confine della libreria. Se l’input contiene dati personali, anche il livello di testo riconosciuto li conterrà; trattare il documento derivato di conseguenza.

Telemetria sicura e sanificazione dei log

La libreria solleva eccezioni tipizzate con messaggi strutturali e non inserisce i byte del documento o il testo riconosciuto nel testo dell’eccezione. Una distribuzione che effettua il logging attorno a questa superficie dovrebbe registrare conteggi e configurazione — come mostrato nell’esempio di produzione — e non deve registrare il payload PDF grezzo né il testo riconosciuto nei log o in un backend APM.

Comportamento in modalità FIPS

In questo modulo non avviene alcuna operazione crittografica, perciò non esiste alcun comportamento specifico della modalità FIPS.

Conformità

Asserzione	Standard	Clausola
La modalità di rendering del testo controlla se i glifi sono riempiti, tracciati o nessuno dei due (la base del testo OCR invisibile).	ISO 32000-2:2020	§9.3.3
Gli operatori di mostra del testo posizionano i glifi nel content stream.	ISO 32000-2:2020	§9.4
La gerarchia di struttura logica mappa il contenuto su un ordine di lettura.	ISO 32000-2:2020	§14.7
La struttura taggata supporta il riutilizzo del contenuto.	ISO 32000-2:2020	§14.8
Gli elementi di struttura tabellare descrivono righe e celle.	ISO 32000-2:2020	§14.8
L’albero di struttura mappa il contenuto su un ordine di lettura.	ISO 32000-2:2020	§14.7

Tutte le clausole sono parafrasate. NextPDF non riproduce il testo normativo. Consultare lo standard pubblicato per il testo autorevole. NextPDF non avanza alcuna rivendicazione sull’accuratezza dell’OCR o sul recall dell’estrazione; questa pagina indica le strutture prodotte e il confine di orchestrazione, non una garanzia di qualità.

Contratto di comportamento

• Gli estrattori strutturato e tabellare consumano dati già estratti; non analizzano un PDF, non eseguono un modello e non misurano la precisione. La confidenza è passante o un valore predefinito fisso.
• Un filtro per schema mantiene soltanto le coppie la cui chiave corrisponde a un campo dello schema e segnala i campi obbligatori mancanti; i bounding box di tabella sintetizzati sono una suddivisione a griglia uniforme, non un layout misurato.
• L’overlay ricercabile è un documento derivato: qualsiasi firma digitale esistente viene invalidata e lo stato di compliance deve essere riconvalidato.
• Quando il backend OCR non è disponibile, le pagine interessate contribuiscono con zero parole anziché far fallire silenziosamente l’intera esecuzione; una pagina con un livello di testo nativo utilizzabile viene saltata per impostazione predefinita.
• Gli input di pagine e dimensioni sono limitati e falliscono in modo chiuso in caso di overflow. L’estrazione è deterministica per un input fisso; l’output dell’overlay dipende dal backend OCR fornito.

Confine di pubblicazione

Questa pagina documenta soltanto il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi di file di runbook e i prefissi di ticket sono fuori ambito.

Fallback di Core

NextPDF Core (Apache-2.0) non dispone di alcuna orchestrazione di overlay ricercabili né di alcuna superficie di strutturazione validata da schema — nessuna; questa funzionalità non ha un equivalente di livello Core. Il modello AST di Core è la base del documento analizzato, non una superficie di estrazione o OCR.

Fallback di Pro

NextPDF Pro include l’estrazione strutturale guidata dall’AST su un documento già analizzato; non fornisce la strutturazione chiave-valore validata da schema, la ricostruzione delle tabelle a partire da griglie grezze né l’orchestrazione di overlay ricercabili basata su OCR. Queste sono incluse esclusivamente nel pacchetto nextpdf/enterprise.

Nota sul confine Enterprise

Gli estrattori strutturato/tabellare e l’orchestratore di overlay sono descritti a livello di comportamento. La rasterizzazione vera e propria e l’iniezione del testo invisibile vengono eseguite in un processo sidecar separato; le componenti interne del sidecar, il modello OCR e qualsiasi dettaglio interno di orchestrazione sono fuori ambito per la superficie pubblica. Il backend OCR è un contratto iniettato fornito dalla distribuzione.

Confine di distribuzione

La distribuzione fornisce e gestisce il backend OCR e sceglie dove l’OCR viene calcolato (in-process, in un sidecar locale o in un servizio remoto) — e quindi dove le immagini del documento e il testo riconosciuto vengono calcolati e archiviati. NextPDF Enterprise orchestra il flusso di lavoro e produce i metadati del risultato; non incorpora un modello OCR e non garantisce l’accuratezza del riconoscimento né il recall dell’estrazione.

Confine di conformità legale

Alla superficie Intelligence non si applica alcuna restrizione di controllo delle esportazioni. La libreria non asserisce alcuna garanzia sull’accuratezza dell’OCR o sul recall dell’estrazione e nessuno stato di conformità normativa. Questa documentazione non è un parere legale; consultare i propri consulenti di conformità e legali.

Vedere anche

• Riferimento Intelligence — il riferimento API approfondito per questa funzionalità.
• Estrazione Pro — blocchi di citazione strutturali guidati dall’AST.
• Privacy — rilevamento dei dati personali (PII) sul testo estratto.
• NextPDF Enterprise — l’intera superficie di funzionalità Enterprise.
• AST di Core — il modello del documento analizzato.
• Tagged PDF · OCR · PDF ricercabile — termini del glossario.