Intelligence

速覽

NextPDF Enterprise Intelligence 會將原始的鍵值與表格資料轉換為具型別、可選擇性經結構描述驗證的結構，並透過驅動 OCR 後端處理掃描頁面，來協調可搜尋 PDF 的產生。它描述自己所產出的結構；它不主張 OCR 準確度或擷取召回率。

供應與授權

此能力隨附於 NextPDF Enterprise（nextpdf/enterprise），並以 Enterprise 層級的授權封套啟用。未具該權益的部署不會載入此能力的類別。未具有效 Enterprise 權益的部署不會載入這些類別。比較各版本並取得授權。

安裝

composer require nextpdf/enterprise:^3

概念總覽

結構化擷取器接收原始鍵值對——由上游的 accelerator 或啟發式剖析器產生——並輸出具型別的鍵值對物件。當提供了結構描述時，它只會保留鍵與某個結構描述欄位相符的鍵值對，並回報哪些必填欄位缺漏。沒有明確信賴度的鍵值對會獲得一個固定的預設值。這是針對「已擷取完成的資料」進行的型別化與驗證步驟；它本身並不是擷取或辨識引擎，也不指派任何計算出的精確度。

表格擷取器接收原始的列網格，並建構出帶有逐格物件的結構化表格結果，其邊界框則由將正規化頁面區域細分後合成、且尺寸一致。較短的列會被填補，使每一列都具有最寬的欄數。沒有任何列或沒有任何欄的表格會被跳過。這些邊界框是均勻網格合成的結果，而非實際量測的版面。

可搜尋覆疊協調器會接收掃描或混合型 PDF，偵測哪些頁面缺少可用的文字層，驅動設定好的 OCR 後端，並產出一份描述每頁字數與平均信賴度的結果。隱形文字是可搜尋掃描頁面背後的機制：文字顯示運算子可以放置字符，同時將文字繪製模式設定為文字既不填色也不描邊——ISO 32000-2:2020 §9.3.3——而文字顯示運算子會在內容串流中放置字符——ISO 32000-2:2020 §9.4。當來源帶有標記時，邏輯結構階層會將內容對應到一個閱讀順序——ISO 32000-2:2020 §14.7、帶標記結構支援內容再利用——ISO 32000-2:2020 §14.8，而表格結構元素則描述列與儲存格——ISO 32000-2:2020 §14.8。

實際的點陣化與隱形文字注入由一個獨立的 sidecar 程序執行；PHP 介面負責協調整個工作流程，並產出結果中繼資料。覆疊執行的輸出是一份衍生文件：任何既有的簽章都會失效，而合規狀態則需要重新驗證。信賴度值是直接傳遞的數值或固定的預設值，並非保證的準確度數字。

為何採用這種方式

此介面在結構化與辨識之間劃下一條明確界線。型別化與結構描述驗證在行程內執行，因為它們是決定性且廉價的。辨識——點陣化與隱形文字注入——則委派給注入的 OCR 後端與獨立的 sidecar，因為它沉重、特定於後端，且最好置於 PHP 信任邊界之外。這樣的切分讓部署能自行選擇文件影像與辨識文字在何處計算與儲存，而無須變更呼叫端程式碼。此模組也拒絕捏造精確度數字：未標記的鍵值對會獲得固定的預設值，而回報的信賴度是直接傳遞而非計算得出。呼叫端絕不會拿到一個虛構的準確度數字。

設計背景：一個拒絕臆測的 API。

API 介面

型別	種類	角色	穩定度	自
StructuredExtractor	class	為原始鍵值對指派型別；結構描述過濾與必填欄位檢查	stable	2.2.0
ExtractionSchema / SchemaField	classes	欄位定義與必填欄位集合	stable	2.2.0
KeyValuePair	class	一個帶有信賴度、具型別的鍵值對	stable	2.2.0
TableExtractor	class	從原始列網格建構結構化表格	stable	2.2.0
TableResult / TableCell	classes	帶有逐格文字、信賴度與邊界框的表格形狀	stable	2.2.0
SearchableOverlay	class	協調由 OCR 支撐的可搜尋 PDF 產生	stable	2.2.0
OverlayConfig / OverlayQuality	classes	語言提示、DPI、品質預設值、原生頁面跳過	stable	2.2.0
SearchableOverlayResult / PageOverlayInfo	classes	每頁字數與平均信賴度	stable	2.2.0
ExtractionConfig / ExtractionStrategy	classes	啟發式 vs OCR 輔助策略與 OCR 提示	stable	2.2.0

OCR 後端是一個注入的合約。協調器並不內嵌 OCR 模型；由部署提供後端，並負責 OCR 在何處計算。

程式碼範例——快速上手

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

此擷取器會為上游步驟已產出的資料指派型別並加以過濾。它本身不執行任何辨識。

程式碼範例——正式環境

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

日誌只承載頁數與字數。它不承載辨識出的文字或文件位元組。catch 會重新拋出例外；它不會吞掉這個失敗。

邊界案例與陷阱

• 結構化與表格擷取器消耗的是「已擷取完成的資料」。它們不會剖析 PDF、不執行模型，也不量測精確度。信賴度是直接傳遞的數值或固定的預設值。
• 合成出的表格邊界框是均勻網格的細分結果，而非實際量測的版面。需要真實幾何資訊的呼叫端必須另行取得。
• 可搜尋覆疊是一份衍生文件。任何既有的數位簽章都會失效；覆疊後必須重新驗證合規狀態。
• 當 OCR 後端無法使用時，受影響的頁面會貢獻零個字，而不會默默地使整次執行失敗——請檢查每頁的結果。
• 已具備可用原生文字層的頁面預設會被跳過。若你必須重新 OCR，請在設定中停用該跳過行為。
• OCR 準確度完全取決於所提供的後端、輸入品質與語言提示。NextPDF 不主張辨識準確度或擷取召回率。

效能

結構化與表格擷取的成本與輸入大小呈線性關係。可搜尋覆疊的成本主要由 OCR 後端與 sidecar 在設定 DPI 下的點陣化所主導；協調本身的額外開銷很小。頁數與大小輸入皆有上界，溢位時 fail closed。可重現性設定檔為 structural：對固定輸入而言擷取是決定性的，而覆疊輸出取決於 OCR 後端，並可能因後端或版本不同而有所差異。

安全注意事項

這些擷取器是唯讀的結構化步驟。覆疊介面會產出衍生文件，並對輸入大小與頁數設下界限，溢位時 fail closed。OCR 後端是整合點，而非信任邊界的一部分；由部署來選擇與營運它。本模組不進行任何加密運算，因此不做任何 FIPS 聲明。

資料落地與 PII 緩解措施

結構化與表格擷取會在主機上於行程內執行。可搜尋覆疊協調會驅動一個注入的 OCR 後端：該後端在何處運行——行程內、本機 sidecar 或遠端服務——以及因此文件影像與辨識出的文字在何處計算與儲存，皆屬於部署責任，落在函式庫的邊界之外。若輸入含有個人資料，辨識出的文字層也會含有；請以對待衍生文件的方式對待它。

安全遙測與日誌清洗

函式庫會丟出帶有結構性訊息的具型別例外，且不會將文件位元組或辨識出的文字放入例外文字中。在此介面周圍進行日誌記錄的部署，應記錄計數與設定——如正式環境範例所示——且絕不可將原始 PDF 酬載或辨識出的文字記錄到日誌或 APM 後端。

FIPS 模式行為

本模組不進行任何加密運算，因此沒有任何 FIPS 模式專屬行為。

一致性

聲明	標準	條款
文字繪製模式控制字符是填色、描邊還是兩者皆非（隱形 OCR 文字的基礎）。	ISO 32000-2:2020	§9.3.3
文字顯示運算子在內容串流中放置字符。	ISO 32000-2:2020	§9.4
邏輯結構階層將內容對應到一個閱讀順序。	ISO 32000-2:2020	§14.7
帶標記結構支援內容再利用。	ISO 32000-2:2020	§14.8
表格結構元素描述列與儲存格。	ISO 32000-2:2020	§14.8
結構樹將內容對應到一個閱讀順序。	ISO 32000-2:2020	§14.7

所有條款皆為改寫。NextPDF 不重製規範性文字。請查閱已發布的標準以取得權威用語。NextPDF 不做任何 OCR 準確度或擷取召回率的聲明；本頁陳述的是所產出的結構與協調邊界，而非品質保證。

行為合約

• 結構化與表格擷取器消耗的是「已擷取完成的資料」；它們不會剖析 PDF、不執行模型，也不量測精確度。信賴度是直接傳遞的數值或固定的預設值。
• 結構描述過濾只保留鍵與某個結構描述欄位相符的鍵值對，並回報缺漏的必填欄位；合成出的表格邊界框是均勻網格的細分結果，而非實際量測的版面。
• 可搜尋覆疊是一份衍生文件：任何既有的數位簽章都會失效，且合規狀態必須重新驗證。
• 當 OCR 後端無法使用時，受影響的頁面會貢獻零個字，而不會默默地使整次執行失敗；已具可用原生文字層的頁面預設會被跳過。
• 頁數與大小輸入皆有上界，溢位時 fail closed。對固定輸入而言擷取是決定性的；覆疊輸出取決於所提供的 OCR 後端。

發布邊界

本頁僅記載外部可觀察的行為與所支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表格、runbook 檔名與工單前綴皆不在範圍內。

Core 回退

NextPDF Core（Apache-2.0）沒有可搜尋覆疊協調，也沒有經結構描述驗證的結構化介面——一概沒有；此能力沒有任何 Core 層級的等價物。Core AST 模型是已剖析文件的基底，而非擷取或 OCR 介面。

Pro 回退

NextPDF Pro 隨附針對已剖析文件、由 AST 驅動的結構性擷取；它不提供經結構描述驗證的鍵值結構化、從原始網格重建表格，或由 OCR 支撐的可搜尋覆疊協調。那些僅隨 nextpdf/enterprise 套件提供。

Enterprise 邊界註記

結構化/表格擷取器與覆疊協調器皆以行為層級描述。實際的點陣化與隱形文字注入會在獨立的 sidecar 程序中執行；sidecar 內部實作、OCR 模型，以及任何內部協調細節，皆不在公開介面範圍內。OCR 後端是由部署提供的注入合約。

部署邊界

由部署提供並營運 OCR 後端，並選擇 OCR 在何處計算（行程內、本機 sidecar 或遠端服務）——因此也決定了文件影像與辨識出的文字在何處計算與儲存。NextPDF Enterprise 協調工作流程並產出結果中繼資料；它不內嵌 OCR 模型，也不保證辨識準確度或擷取召回率。

法律合規邊界

Intelligence 介面不適用任何出口管制限制。函式庫不主張任何 OCR 準確度或擷取召回率的保證，也不主張任何法規合規狀態。本文件不是法律意見；請諮詢你自己的合規與法律顧問。

另請參閱

• Intelligence 參考 — 此能力的深入 API 參考。
• Pro 擷取 — 結構性、由 AST 驅動的引用區塊。
• Privacy — 針對擷取文字進行 PII 偵測。
• NextPDF Enterprise — 完整的 Enterprise 功能介面。
• Core AST — 已剖析文件的模型。
• Tagged PDF · OCR · Searchable PDF — 詞彙表條目。