Intelligence

Em resumo

O NextPDF Enterprise Intelligence converte dados brutos de chave-valor e de tabela em estruturas tipadas e, opcionalmente, validadas por esquema, e orquestra a geração de PDFs pesquisáveis acionando um backend de OCR sobre páginas digitalizadas. Ele descreve as estruturas que produz; não afirma a precisão do OCR nem a abrangência da extração.

Disponibilidade e licenciamento

Este recurso é entregue no NextPDF Enterprise (nextpdf/enterprise) e é ativado com um envelope de licença de nível Enterprise. Uma implantação sem esse direito de uso não carrega as classes do recurso. Uma implantação sem um direito de uso ativo do Enterprise não carrega essas classes. Compare edições e obtenha uma licença.

Instalação

composer require nextpdf/enterprise:^3

Visão conceitual

O extrator estruturado recebe pares brutos de chave-valor — produzidos a montante por um accelerator ou por um analisador heurístico — e emite objetos de pares tipados. Quando um esquema é fornecido, ele mantém apenas os pares cuja chave corresponde a um campo do esquema e relata quais campos obrigatórios estão ausentes. Um par sem confiança explícita recebe um valor padrão fixo. Esta é uma etapa de tipagem e validação sobre dados que já foram extraídos; ela não é, por si só, um motor de extração ou de reconhecimento e não atribui nenhuma precisão calculada.

O extrator de tabelas recebe grades brutas de linhas e constrói resultados de tabela estruturados, com objetos por célula e bounding boxes uniformes sintetizadas, derivadas pela subdivisão de uma área de página normalizada. Linhas curtas são preenchidas para que cada linha tenha a maior contagem de colunas. Uma tabela sem linhas ou sem colunas é ignorada. As bounding boxes são uma síntese de grade uniforme, não um layout medido.

O orquestrador de sobreposição pesquisável aceita um PDF digitalizado ou misto, detecta quais páginas não têm uma camada de texto utilizável, aciona o backend de OCR configurado e produz um resultado que descreve a contagem de palavras por página e uma confiança média. O texto invisível é o mecanismo de uma página digitalizada pesquisável: um operador de exibição de texto pode posicionar glifos enquanto o modo de renderização de texto está configurado de forma que o texto não seja nem preenchido nem traçado — ISO 32000-2:2020 §9.3.3 — e os operadores de exibição de texto posicionam glifos no content stream — ISO 32000-2:2020 §9.4. Quando a origem é marcada (tagged), a hierarquia de estrutura lógica mapeia o conteúdo para uma ordem de leitura — ISO 32000-2:2020 §14.7, a estrutura marcada dá suporte à reutilização de conteúdo — ISO 32000-2:2020 §14.8, e os elementos de estrutura de tabela descrevem linhas e células — ISO 32000-2:2020 §14.8.

A rasterização propriamente dita e a injeção de texto invisível são realizadas por um processo sidecar separado; a superfície PHP orquestra o fluxo de trabalho e produz os metadados de resultado. A saída de uma execução de sobreposição é um documento derivado: qualquer assinatura existente é invalidada e o status de conformidade exige nova validação. Os valores de confiança são repassados (passthrough) ou são valores padrão fixos, não um número de precisão garantido.

Por que funciona assim

A superfície traça uma linha rígida entre estruturação e reconhecimento. A tipagem e a validação por esquema rodam em processo, porque são determinísticas e baratas. O reconhecimento — rasterização e injeção de texto invisível — é delegado a um backend de OCR injetado e a um sidecar separado, porque é pesado, específico do backend e melhor mantido fora do limite de confiança do PHP. Essa divisão permite que uma implantação escolha onde as imagens do documento e o texto reconhecido são computados e armazenados, sem alterar o código chamador. O módulo também se recusa a inventar um número de precisão: um par sem rótulo recebe um valor padrão fixo, e a confiança relatada é repassada em vez de calculada. Um chamador nunca recebe um número de precisão fabricado.

Contexto de design: Uma API que se recusa a adivinhar.

Superfície de API

Type	Kind	Role	Stability	Since
StructuredExtractor	class	Types raw key-value pairs; schema filter and required-field check	stable	2.2.0
ExtractionSchema / SchemaField	classes	Field definitions and required-field set	stable	2.2.0
KeyValuePair	class	One typed key-value pair with confidence	stable	2.2.0
TableExtractor	class	Builds structured tables from raw row grids	stable	2.2.0
TableResult / TableCell	classes	Table shape with per-cell text, confidence, and bounding box	stable	2.2.0
SearchableOverlay	class	Orchestrates OCR-backed searchable-PDF generation	stable	2.2.0
OverlayConfig / OverlayQuality	classes	Language hint, DPI, quality preset, native-page skip	stable	2.2.0
SearchableOverlayResult / PageOverlayInfo	classes	Per-page word counts and average confidence	stable	2.2.0
ExtractionConfig / ExtractionStrategy	classes	Heuristic vs OCR-assisted strategy and OCR hints	stable	2.2.0

O backend de OCR é um contrato injetado. O orquestrador não incorpora um modelo de OCR; uma implantação fornece o backend e é responsável por onde o OCR é computado.

Exemplo de código — Início rápido

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);
}

O extrator tipa e filtra dados que uma etapa a montante já produziu. Ele próprio não realiza nenhum reconhecimento.

Exemplo de código — Produção

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;
        }
    }
}

O log carrega apenas a contagem de páginas e de palavras. Ele não carrega o texto reconhecido nem os bytes do documento. O catch relança a exceção; ele não engole a falha.

Casos extremos e pegadinhas

• Os extratores estruturado e de tabelas consomem dados já extraídos. Eles não analisam um PDF, não executam um modelo nem medem precisão. A confiança é repassada (passthrough) ou um valor padrão fixo.
• As bounding boxes de tabela sintetizadas são uma subdivisão de grade uniforme, não um layout medido. Um chamador que precise de geometria real deve obtê-la em outro lugar.
• A sobreposição pesquisável é um documento derivado. Qualquer assinatura digital existente é invalidada; o status de conformidade deve ser revalidado após a sobreposição.
• Quando o backend de OCR está indisponível, as páginas afetadas contribuem com zero palavras em vez de falhar toda a execução silenciosamente — verifique o resultado por página.
• Uma página que já tem uma camada de texto nativa utilizável é ignorada por padrão. Desative essa exclusão na configuração se você precisar refazer o OCR.
• A precisão do OCR depende inteiramente do backend fornecido, da qualidade da entrada e da dica de idioma. O NextPDF não afirma a precisão do reconhecimento nem a abrangência da extração.

Desempenho

A extração estruturada e de tabelas é linear em relação ao tamanho da entrada. O custo da sobreposição pesquisável é dominado pelo backend de OCR e pela rasterização do sidecar no DPI configurado; a sobrecarga de orquestração é pequena. As entradas de páginas e de tamanho são limitadas e falham de forma fechada (fail closed) em caso de estouro. O perfil de reprodutibilidade é structural: a extração é determinística para uma entrada fixa, ao passo que a saída de sobreposição depende do backend de OCR e pode variar entre backends ou versões.

Notas de segurança

Os extratores são etapas de estruturação somente leitura. A superfície de sobreposição produz um documento derivado e limita o tamanho da entrada e a contagem de páginas, falhando de forma fechada em caso de estouro. O backend de OCR é um ponto de integração, não parte do limite de confiança; uma implantação o escolhe e o opera. Nenhuma operação criptográfica ocorre neste módulo, então ele não faz nenhuma afirmação de FIPS.

Residência de dados e mitigações de PII

A extração estruturada e de tabelas é executada em processo no host. A orquestração de sobreposição pesquisável aciona um backend de OCR injetado: onde esse backend é executado — em processo, em um sidecar local ou em um serviço remoto — e, portanto, onde as imagens do documento e o texto reconhecido são computados e armazenados, é uma responsabilidade da implantação, fora do limite da biblioteca. Se a entrada contiver dados pessoais, a camada de texto reconhecido também os conterá; trate o documento derivado de acordo.

Telemetria segura e limpeza de logs

A biblioteca lança exceções tipadas com mensagens estruturais e não coloca bytes do documento nem texto reconhecido no texto da exceção. Uma implantação que registre logs em torno desta superfície deve registrar contagens e configuração — como mostrado no exemplo de produção — e não deve registrar o payload bruto do PDF nem o texto reconhecido em logs ou em um backend de APM.

Comportamento em modo FIPS

Nenhuma operação criptográfica ocorre neste módulo, então não há comportamento específico de modo FIPS.

Conformidade

Claim	Standard	Clause
O modo de renderização de texto controla se os glifos são preenchidos, traçados ou nenhum dos dois (a base do texto invisível de OCR).	ISO 32000-2:2020	§9.3.3
Os operadores de exibição de texto posicionam glifos no content stream.	ISO 32000-2:2020	§9.4
A hierarquia de estrutura lógica mapeia o conteúdo para uma ordem de leitura.	ISO 32000-2:2020	§14.7
A estrutura marcada dá suporte à reutilização de conteúdo.	ISO 32000-2:2020	§14.8
Os elementos de estrutura de tabela descrevem linhas e células.	ISO 32000-2:2020	§14.8
A árvore de estrutura mapeia o conteúdo para uma ordem de leitura.	ISO 32000-2:2020	§14.7

Todas as cláusulas são parafraseadas. O NextPDF não reproduz texto normativo. Consulte o padrão publicado para obter a redação autoritativa. O NextPDF não faz nenhuma afirmação de precisão de OCR ou de abrangência de extração; esta página declara as estruturas produzidas e o limite de orquestração, não uma garantia de qualidade.

Contrato de comportamento

• Os extratores estruturado e de tabelas consomem dados já extraídos; eles não analisam um PDF, não executam um modelo nem medem precisão. A confiança é repassada (passthrough) ou um valor padrão fixo.
• Um filtro de esquema mantém apenas os pares cuja chave corresponde a um campo do esquema e relata os campos obrigatórios ausentes; as bounding boxes de tabela sintetizadas são uma subdivisão de grade uniforme, não um layout medido.
• A sobreposição pesquisável é um documento derivado: qualquer assinatura digital existente é invalidada e o status de conformidade deve ser revalidado.
• Quando o backend de OCR está indisponível, as páginas afetadas contribuem com zero palavras em vez de falhar toda a execução silenciosamente; uma página com uma camada de texto nativa utilizável é ignorada por padrão.
• As entradas de páginas e de tamanho são limitadas e falham de forma fechada em caso de estouro. A extração é determinística para uma entrada fixa; a saída de sobreposição depende do backend de OCR fornecido.

Limite de publicação

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

Fallback no Core

O NextPDF Core (Apache-2.0) não tem orquestração de sobreposição pesquisável nem superfície de estruturação validada por esquema — nenhuma; essa capacidade não tem equivalente no nível Core. O modelo de AST do Core é a base do documento analisado, não uma superfície de extração ou de OCR.

Fallback no Pro

O NextPDF Pro traz extração estrutural baseada em AST sobre um documento já analisado; ele não fornece estruturação de chave-valor validada por esquema, reconstrução de tabelas a partir de grades brutas nem orquestração de sobreposição pesquisável baseada em OCR. Esses recursos são entregues apenas no pacote nextpdf/enterprise.

Nota sobre o limite do Enterprise

Os extratores estruturado/de tabelas e o orquestrador de sobreposição são descritos no nível de comportamento. A rasterização propriamente dita e a injeção de texto invisível são executadas em um processo sidecar separado; os detalhes internos do sidecar, o modelo de OCR e qualquer detalhe interno de orquestração estão fora do escopo da superfície pública. O backend de OCR é um contrato injetado, fornecido pela implantação.

Limite de implantação

A implantação fornece e opera o backend de OCR e escolhe onde o OCR é computado (em processo, em um sidecar local ou em um serviço remoto) — e, portanto, onde as imagens do documento e o texto reconhecido são computados e armazenados. O NextPDF Enterprise orquestra o fluxo de trabalho e produz os metadados de resultado; ele não incorpora um modelo de OCR nem garante a precisão do reconhecimento ou a abrangência da extração.

Limite legal e de conformidade

Nenhuma restrição de controle de exportação se aplica à superfície do Intelligence. A biblioteca não afirma nenhuma garantia de precisão de OCR ou de abrangência de extração e nenhum status de conformidade regulatória. Esta documentação não é uma opinião jurídica; consulte seus próprios assessores de conformidade e jurídicos.

Veja também

• Referência do Intelligence — a referência aprofundada de API deste recurso.
• Extração no Pro — blocos de citação estruturais baseados em AST.
• Privacidade — detecção de PII sobre texto extraído.
• NextPDF Enterprise — a superfície completa de recursos do Enterprise.
• Core AST — o modelo do documento analisado.
• Tagged PDF · OCR · Searchable PDF — termos do glossário.