Intelligence

Tổng quan nhanh

NextPDF Enterprise Intelligence chuyển dữ liệu key-value và bảng thô thành các cấu trúc có kiểu, được xác thực theo schema một cách tùy chọn, và điều phối việc tạo PDF có thể tìm kiếm bằng cách điều khiển một backend OCR trên các trang đã quét. Nó mô tả các cấu trúc mà nó tạo ra; nó không khẳng định độ chính xác OCR hay độ phủ trích xuất.

Tính khả dụng và cấp phép

Năng lực này được phát hành trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt bằng một license envelope bậc Enterprise. Một triển khai không có entitlement đó sẽ không nạp các class của năng lực này. Một triển khai không có entitlement Enterprise đang hoạt động sẽ không nạp các class này. So sánh các phiên bản và lấy giấy phép.

Cài đặt

composer require nextpdf/enterprise:^3

Tổng quan khái niệm

Bộ trích xuất có cấu trúc nhận các cặp key-value thô — được tạo ở upstream bởi một accelerator hoặc một parser heuristic — và phát ra các đối tượng cặp có kiểu. Khi một schema được cung cấp, nó chỉ giữ lại các cặp có key khớp với một trường schema và báo cáo những trường bắt buộc nào còn thiếu. Một cặp không có độ tin cậy tường minh sẽ nhận một giá trị mặc định cố định. Đây là một bước gán kiểu và xác thực trên dữ liệu đã được trích xuất; bản thân nó không phải là một engine trích xuất hay nhận dạng và không gán độ chính xác được tính toán nào.

Bộ trích xuất bảng nhận các lưới hàng thô và dựng các kết quả bảng có cấu trúc với các đối tượng từng ô và các bounding box được tổng hợp đều nhau, dẫn xuất bằng cách chia nhỏ một vùng trang đã chuẩn hóa. Các hàng ngắn được đệm thêm để mọi hàng có số cột rộng nhất. Một bảng không có hàng hoặc không có cột sẽ bị bỏ qua. Các bounding box là một tổng hợp lưới đều, không phải một bố cục được đo đạc.

Bộ điều phối searchable-overlay nhận một PDF đã quét hoặc hỗn hợp, phát hiện những trang nào thiếu một lớp văn bản dùng được, điều khiển backend OCR đã cấu hình, và tạo một kết quả mô tả số lượng từ của từng trang và một độ tin cậy trung bình. Văn bản vô hình là cơ chế cho một trang quét có thể tìm kiếm: một text-showing operator có thể đặt glyph trong khi text rendering mode được đặt sao cho văn bản không được tô (fill) cũng không được vẽ viền (stroke) — ISO 32000-2:2020 §9.3.3 — và các text-showing operator đặt glyph trong content stream — ISO 32000-2:2020 §9.4. Khi nguồn được gắn thẻ (tagged), phân cấp cấu trúc logic ánh xạ nội dung tới một thứ tự đọc — ISO 32000-2:2020 §14.7, cấu trúc tagged hỗ trợ tái sử dụng nội dung — ISO 32000-2:2020 §14.8, và các phần tử cấu trúc bảng mô tả các hàng và ô — ISO 32000-2:2020 §14.8.

Việc rasterization thực tế và việc tiêm văn bản vô hình được thực hiện bởi một tiến trình sidecar riêng biệt; bề mặt PHP điều phối quy trình và tạo metadata kết quả. Đầu ra của một lần overlay là một tài liệu dẫn xuất: bất kỳ chữ ký hiện có nào đều bị vô hiệu hóa và trạng thái tuân thủ cần được xác thực lại. Các giá trị độ tin cậy là passthrough hoặc các giá trị mặc định cố định, không phải một con số độ chính xác được bảo đảm.

Vì sao nó hoạt động theo cách này

Bề mặt vẽ một ranh giới rõ ràng giữa việc cấu trúc hóa và việc nhận dạng. Việc gán kiểu và xác thực schema chạy trong tiến trình, vì chúng có tính tất định và rẻ. Việc nhận dạng — rasterization và tiêm văn bản vô hình — được ủy thác cho một backend OCR được tiêm vào và một sidecar riêng biệt, vì nó nặng, phụ thuộc backend, và tốt nhất là giữ ngoài ranh giới tin cậy của PHP. Sự phân tách đó cho phép một triển khai chọn nơi hình ảnh tài liệu và văn bản được nhận dạng được tính toán và lưu trữ, mà không thay đổi mã gọi. Module cũng từ chối bịa ra một con số độ chính xác: một cặp không có nhãn nhận một giá trị mặc định cố định, và độ tin cậy được báo cáo là được truyền qua (passthrough) chứ không phải được tính toán. Một người gọi không bao giờ được đưa cho một con số độ chính xác bịa đặt.

Bối cảnh thiết kế: Một API từ chối đoán mò.

Bề mặt API

Kiểu	Loại	Vai trò	Độ ổn định	Từ
StructuredExtractor	class	Gán kiểu cho các cặp key-value thô; lọc theo schema và kiểm tra trường bắt buộc	stable	2.2.0
ExtractionSchema / SchemaField	classes	Định nghĩa trường và tập trường bắt buộc	stable	2.2.0
KeyValuePair	class	Một cặp key-value có kiểu kèm độ tin cậy	stable	2.2.0
TableExtractor	class	Dựng các bảng có cấu trúc từ các lưới hàng thô	stable	2.2.0
TableResult / TableCell	classes	Hình dạng bảng với văn bản, độ tin cậy và bounding box của từng ô	stable	2.2.0
SearchableOverlay	class	Điều phối việc tạo PDF có thể tìm kiếm dựa trên OCR	stable	2.2.0
OverlayConfig / OverlayQuality	classes	Gợi ý ngôn ngữ, DPI, preset chất lượng, bỏ qua trang gốc	stable	2.2.0
SearchableOverlayResult / PageOverlayInfo	classes	Số lượng từ của từng trang và độ tin cậy trung bình	stable	2.2.0
ExtractionConfig / ExtractionStrategy	classes	Chiến lược heuristic so với hỗ trợ OCR và các gợi ý OCR	stable	2.2.0

Backend OCR là một contract được tiêm vào. Bộ điều phối không nhúng một mô hình OCR; một triển khai cung cấp backend và chịu trách nhiệm về nơi OCR được tính toán.

Mẫu mã — Bắt đầu nhanh

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

Bộ trích xuất gán kiểu và lọc dữ liệu mà một bước upstream đã tạo ra. Bản thân nó không thực hiện việc nhận dạng nào.

Mẫu mã — Production

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

Nhật ký chỉ mang theo số lượng trang và từ. Nó không mang theo văn bản được nhận dạng hay các byte tài liệu. Khối catch ném lại; nó không nuốt lỗi.

Trường hợp biên và lưu ý

• Bộ trích xuất có cấu trúc và bộ trích xuất bảng tiêu thụ dữ liệu đã được trích xuất. Chúng không phân tích cú pháp một PDF, không chạy một mô hình, hay đo độ chính xác. Độ tin cậy là passthrough hoặc một giá trị mặc định cố định.
• Các bounding box bảng được tổng hợp là một sự chia nhỏ lưới đều, không phải một bố cục được đo đạc. Một người gọi cần hình học thực phải lấy nó ở nơi khác.
• Searchable overlay là một tài liệu dẫn xuất. Bất kỳ chữ ký số hiện có nào đều bị vô hiệu hóa; trạng thái tuân thủ phải được xác thực lại sau khi overlay.
• Khi backend OCR không khả dụng, các trang bị ảnh hưởng đóng góp không từ nào thay vì làm cả lần chạy thất bại âm thầm — hãy kiểm tra kết quả của từng trang.
• Một trang đã có sẵn một lớp văn bản gốc dùng được sẽ bị bỏ qua theo mặc định. Hãy tắt việc bỏ qua trong cấu hình nếu bạn cần OCR lại.
• Độ chính xác OCR phụ thuộc hoàn toàn vào backend được cung cấp, chất lượng đầu vào, và gợi ý ngôn ngữ. NextPDF không khẳng định độ chính xác nhận dạng hay độ phủ trích xuất.

Hiệu năng

Việc trích xuất có cấu trúc và trích xuất bảng tuyến tính theo kích thước đầu vào. Chi phí searchable-overlay bị chi phối bởi backend OCR và việc rasterization của sidecar ở DPI được cấu hình; chi phí điều phối là nhỏ. Các đầu vào về trang và kích thước bị giới hạn và fail closed khi tràn. Hồ sơ tái lập là structural: trích xuất có tính tất định cho đầu vào cố định, trong khi đầu ra overlay phụ thuộc vào backend OCR và có thể thay đổi giữa các backend hoặc phiên bản.

Ghi chú bảo mật

Các bộ trích xuất là các bước cấu trúc hóa chỉ đọc. Bề mặt overlay tạo ra một tài liệu dẫn xuất và giới hạn kích thước đầu vào và số trang, fail closed khi tràn. Backend OCR là một điểm tích hợp, không phải một phần của ranh giới tin cậy; một triển khai chọn và vận hành nó. Không có thao tác mật mã nào xảy ra trong module này, nên nó không đưa ra tuyên bố FIPS nào.

Cư trú dữ liệu và biện pháp giảm thiểu PII

Việc trích xuất có cấu trúc và trích xuất bảng chạy trong tiến trình trên host. Việc điều phối searchable-overlay điều khiển một backend OCR được tiêm vào: nơi backend đó chạy — trong tiến trình, một sidecar cục bộ, hay một dịch vụ từ xa — và do đó nơi hình ảnh tài liệu và văn bản được nhận dạng được tính toán và lưu trữ, là một trách nhiệm triển khai nằm ngoài ranh giới của thư viện. Nếu đầu vào chứa dữ liệu cá nhân, lớp văn bản được nhận dạng cũng sẽ chứa; hãy đối xử với tài liệu dẫn xuất cho phù hợp.

Telemetry an toàn và làm sạch nhật ký

Thư viện làm phát sinh các exception có kiểu với thông điệp mang tính cấu trúc và không đặt các byte tài liệu hay văn bản được nhận dạng vào nội dung exception. Một triển khai ghi nhật ký quanh bề mặt này nên ghi số lượng và cấu hình — như được trình bày trong mẫu production — và không được ghi payload PDF thô hay văn bản được nhận dạng vào nhật ký hoặc một backend APM.

Hành vi ở FIPS-mode

Không có thao tác mật mã nào xảy ra trong module này, nên không có hành vi riêng cho FIPS-mode.

Phù hợp tiêu chuẩn

Tuyên bố	Tiêu chuẩn	Điều khoản
Text rendering mode kiểm soát việc glyph được tô, vẽ viền, hay không cái nào (cơ sở cho văn bản OCR vô hình).	ISO 32000-2:2020	§9.3.3
Các text-showing operator đặt glyph trong content stream.	ISO 32000-2:2020	§9.4
Phân cấp cấu trúc logic ánh xạ nội dung tới một thứ tự đọc.	ISO 32000-2:2020	§14.7
Cấu trúc tagged hỗ trợ tái sử dụng nội dung.	ISO 32000-2:2020	§14.8
Các phần tử cấu trúc bảng mô tả các hàng và ô.	ISO 32000-2:2020	§14.8
Cây cấu trúc ánh xạ nội dung tới một thứ tự đọc.	ISO 32000-2:2020	§14.7

Mọi điều khoản đều được diễn giải lại. NextPDF không tái hiện văn bản quy phạm. Hãy tham khảo tiêu chuẩn đã xuất bản để có nội dung có thẩm quyền. NextPDF không đưa ra tuyên bố nào về độ chính xác OCR hay độ phủ trích xuất; trang này nêu các cấu trúc được tạo ra và ranh giới điều phối, không phải một bảo đảm chất lượng.

Hợp đồng hành vi

• Bộ trích xuất có cấu trúc và bộ trích xuất bảng tiêu thụ dữ liệu đã được trích xuất; chúng không phân tích cú pháp một PDF, không chạy một mô hình, hay đo độ chính xác. Độ tin cậy là passthrough hoặc một giá trị mặc định cố định.
• Một bộ lọc schema chỉ giữ các cặp có key khớp với một trường schema và báo cáo các trường bắt buộc còn thiếu; các bounding box bảng được tổng hợp là một sự chia nhỏ lưới đều, không phải một bố cục được đo đạc.
• Searchable overlay là một tài liệu dẫn xuất: bất kỳ chữ ký số hiện có nào đều bị vô hiệu hóa và trạng thái tuân thủ phải được xác thực lại.
• Khi backend OCR không khả dụng, các trang bị ảnh hưởng đóng góp không từ nào thay vì làm cả lần chạy thất bại âm thầm; một trang có một lớp văn bản gốc dùng được sẽ bị bỏ qua theo mặc định.
• Các đầu vào về trang và kích thước bị giới hạn và fail closed khi tràn. Trích xuất có tính tất định cho đầu vào cố định; đầu ra overlay phụ thuộc vào backend OCR được cung cấp.

Ranh giới xuất bản

Trang này chỉ ghi lại hành vi quan sát được từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, class trợ giúp, bảng cơ chế, tên tệp runbook, và tiền tố ticket nằm ngoài phạm vi.

Phương án dự phòng Core

NextPDF Core (Apache-2.0) không có việc điều phối searchable-overlay và không có bề mặt cấu trúc hóa được xác thực theo schema — không hề có; năng lực này không có bản tương đương ở bậc Core. Mô hình AST của Core là nền tài liệu đã phân tích cú pháp, không phải một bề mặt trích xuất hay OCR.

Phương án dự phòng Pro

NextPDF Pro cung cấp việc trích xuất cấu trúc dựa trên AST trên một tài liệu đã được phân tích cú pháp; nó không cung cấp việc cấu trúc hóa key-value được xác thực theo schema, dựng lại bảng từ các lưới thô, hay điều phối searchable-overlay dựa trên OCR. Những thứ đó chỉ được phát hành trong gói nextpdf/enterprise.

Ghi chú ranh giới Enterprise

Các bộ trích xuất có cấu trúc/bảng và bộ điều phối overlay được mô tả ở mức hành vi. Việc rasterization thực tế và việc tiêm văn bản vô hình chạy trong một tiến trình sidecar riêng biệt; các chi tiết nội bộ của sidecar, mô hình OCR, và bất kỳ chi tiết điều phối nội bộ nào nằm ngoài phạm vi của bề mặt công khai. Backend OCR là một contract được tiêm vào do triển khai cung cấp.

Ranh giới triển khai

Triển khai cung cấp và vận hành backend OCR và chọn nơi OCR được tính toán (trong tiến trình, một sidecar cục bộ, hay một dịch vụ từ xa) — và do đó nơi hình ảnh tài liệu và văn bản được nhận dạng được tính toán và lưu trữ. NextPDF Enterprise điều phối quy trình và tạo metadata kết quả; nó không nhúng một mô hình OCR hay bảo đảm độ chính xác nhận dạng hay độ phủ trích xuất.

Ranh giới tuân thủ pháp lý

Không có hạn chế kiểm soát xuất khẩu nào áp dụng cho bề mặt Intelligence. Thư viện không khẳng định bảo đảm nào về độ chính xác OCR hay độ phủ trích xuất và không có trạng thái tuân thủ quy định nào. Tài liệu này không phải là một ý kiến pháp lý; hãy tham vấn các cố vấn tuân thủ và pháp lý của riêng bạn.

Xem thêm

• Intelligence reference — tài liệu tham chiếu API chuyên sâu cho năng lực này.
• Pro extraction — các khối trích dẫn cấu trúc dựa trên AST.
• Privacy — phát hiện PII trên văn bản đã trích xuất.
• NextPDF Enterprise — toàn bộ bề mặt tính năng Enterprise.
• Core AST — mô hình tài liệu đã phân tích cú pháp.
• Tagged PDF · OCR · Searchable PDF — thuật ngữ trong bảng chú giải.