Pro phiên bản

Trích xuất

Tổng quan nhanh

NextPDF\Pro\Extraction duyệt một AST tài liệu đã phân tích và tạo ra các khối văn bản và bảng, mỗi khối mang theo một neo trích dẫn (chỉ số trang, hộp bao, tham chiếu node). Đây là một bộ trích xuất cấu trúc tất định dành cho các pipeline quy gán nguồn, không phải một engine tìm kiếm hay hiểu nội dung.

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

Năng lực này đi kèm trong NextPDF Pro (nextpdf/pro) và được kích hoạt bằng một phong bì giấy phép hạng Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. Không có cờ năng lực lúc chạy nào kiểm soát module này; các lớp Extraction có sẵn bất cứ khi nào nextpdf/pro được cài đặt. So sánh các phiên bản và nhận giấy phép.

Cài đặt

composer require nextpdf/pro:^3

Tổng quan khái niệm

Cả hai bộ trích xuất đều nhận một NextPDF\Ast\AstDocument — một cây tài liệu đã phân tích do hệ con AST của Core tạo ra. Bản thân chúng không phân tích các byte PDF thô; AST là ranh giới đầu vào.

CitedTextExtractor duyệt cây và phát ra một CitedTextBlock cho mỗi node văn bản có nội dung đáng kể (đoạn văn, tiêu đề, mục danh sách, ô bảng, mã, chú thích) mà văn bản đã cắt khoảng trắng của nó đạt một độ dài tối thiểu. Một ngân sách token tùy chọn sẽ tách văn bản dài tại ranh giới câu. Mỗi khối mang theo một CitationAnchor với id node, chỉ số trang, hộp bao và một độ tin cậy đọc từ node (mặc định 1.0). Các node không có hộp bao sẽ nhận một hộp sentinel có diện tích bằng không để neo luôn hợp lệ.
CitedTableExtractor tìm các node Table, đọc các hàng và ô của chúng, và dựng một ma trận theo hàng-trước hình chữ nhật được đệm tới hàng rộng nhất. Các bảng lồng nhau không được đệ quy vào. Độ tin cậy của ô mặc định là 0.8 trừ khi node mang một giá trị tường minh.

Hệ thống phân cấp cấu trúc mà các bộ trích xuất này duyệt qua tương ứng với mô hình cấu trúc logic của PDF (ISO 32000-2:2020 §14.7) và các phần tử cấu trúc bảng (§14.8) khi tài liệu nguồn được gắn thẻ.

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

Bộ trích xuất nhận một AST đã phân tích làm ranh giới đầu vào của nó, không phải các byte PDF thô, nên rủi ro phân tích được giữ tách biệt khỏi logic trích xuất. Độ tin cậy được đọc thẳng từ node AST và truyền qua nguyên vẹn; module không bao giờ tính toán, xếp hạng hay cải thiện nó. Đầu ra giữ theo thứ tự tài liệu, không phải thứ tự theo độ liên quan, vì việc quy gán nguồn cần một nguồn gốc kiểm chứng được thay vì một phỏng đoán heuristic mà bộ trích xuất không thể bảo vệ. Mỗi khối mang theo một neo trích dẫn — id node, chỉ số trang, hộp bao — để một pipeline hạ nguồn có thể truy vết mỗi trích dẫn về nguồn gốc của nó. Điều này cố ý giữ module là một bộ trích xuất cấu trúc tất định: nó báo cáo những gì AST khẳng định và từ chối bịa ra bất cứ điều gì tài liệu không phát biểu.

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

Hợp đồng hành vi

Đầu vào. Một NextPDF\Ast\AstDocument. Module không nhận các byte PDF thô; hãy tạo AST với hệ con AST của Core trước.
Đầu ra. list<CitedTextBlock> hoặc list<CitedTableBlock> theo thứ tự tài liệu.
Độ tin cậy là passthrough. Nó được đọc từ các thuộc tính node AST (hoặc một giá trị mặc định cố định). Module này không tính toán hay cải thiện độ tin cậy.
Không xử lý ngữ nghĩa. Bộ trích xuất không thực hiện embedding, tương đồng vector, xếp hạng hay hiểu tài liệu. Thứ tự đầu ra là thứ tự tài liệu, không phải thứ tự theo độ liên quan.
Tính tất định. Với một AST giống hệt, các khối, neo và chỉ số chunk được tạo ra là ổn định.

Bề mặt API công khai

Kiểu	Loại	Thành viên chính
`NextPDF\Pro\Extraction\CitedTextExtractor`	`final class`	`__construct(?int $maxTokensPerChunk = null, int $minChunkLength = 10)`, `extract(AstDocument $document): list<CitedTextBlock>`
`NextPDF\Pro\Extraction\CitedTableExtractor`	`final class`	`extract(AstDocument $document): list<CitedTableBlock>`
`NextPDF\Pro\Extraction\CitedTextBlock`	`final readonly class`	`string $text`, `CitationAnchor $anchor`, `float $confidence`, `int $chunkIndex`, `array $metadata`, `estimatedTokens(): int`
`NextPDF\Pro\Extraction\CitedTableBlock`	`final readonly class`	`string $nodeId`, `int $pageIndex`, `int $rowCount`, `int $colCount`, `array $matrix`
`NextPDF\Pro\Extraction\CitedTableCell`	`final readonly class`	`int $row`, `int $col`, `?string $textContent`, `float $confidence`

Mẫu mã — Khởi đầu nhanh

<?php

declare(strict_types=1);

use NextPDF\Pro\Extraction\CitedTextExtractor;

/** @var \NextPDF\Ast\AstDocument $ast */
$blocks = (new CitedTextExtractor())->extract($ast);

foreach ($blocks as $block) {
    printf(
        "p%d chunk#%d (%d tokens): %s\n",
        $block->anchor->pageIndex,
        $block->chunkIndex,
        $block->estimatedTokens(),
        $block->text,
    );
}

Mẫu mã — Production

<?php

declare(strict_types=1);

use NextPDF\Pro\Extraction\CitedTextExtractor;

function chunkForCitation(\NextPDF\Ast\AstDocument $ast): array
{
    // Token-bounded chunks for downstream citation storage.
    $extractor = new CitedTextExtractor(
        maxTokensPerChunk: 400,
        minChunkLength: 16,
    );

    $rows = [];
    foreach ($extractor->extract($ast) as $block) {
        $rows[] = [
            'text'      => $block->text,
            'page'      => $block->anchor->pageIndex,
            'node_id'   => $block->anchor->nodeId,
            'chunk'     => $block->chunkIndex,
        ];
    }

    return $rows;
}

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

Các tài liệu không gắn thẻ hoặc gắn thẻ kém sẽ cho ra ít node văn bản hơn; chất lượng AST là giới hạn trên của chất lượng trích xuất.
Các node không có hộp bao sẽ nhận một hộp sentinel diện tích bằng không BoundingBox(0,0,0,0) — hãy phát hiện nó qua width === 0.0 && height === 0.0 nếu cần một vùng thực.
Các bảng lồng nhau không được đệ quy; chỉ node Table ngoài cùng được phát ra.
Các hàng ngắn được đệm với các ô tổng hợp có độ tin cậy bằng không để mọi hàng có cùng số cột.

Lưu trú dữ liệu & giảm thiểu PII

Module này xử lý bất kỳ văn bản nào mà AST được cung cấp chứa và trả nó lại nguyên vẹn bên trong các khối. Nó không thực hiện lời gọi mạng, không lưu trữ ngoài và không ghi log nội dung đã trích xuất. Việc xử lý PII, che và kiểm soát lưu trú là trách nhiệm của bên gọi trên các khối được tạo ra. Xem hướng dẫn xử lý PII của Core.

Telemetry an toàn & làm sạch log

Bộ trích xuất không phát ra telemetry và không ghi log văn bản đã trích xuất. Nếu một bên gọi bọc nó với việc ghi log, hãy làm sạch text, metadata và mọi nội dung ô trước khi phát ra log.

Hiệu năng

Việc trích xuất là một lượt duyệt cây duy nhất, tuyến tính theo số node. Việc tách chunk thêm công việc tỷ lệ với độ dài văn bản. Xem performance_budget.

Ghi chú về bảo mật

Đầu vào là một AST đã phân tích sẵn, nên bản thân module này không phân tích các byte PDF thù địch. Hãy xem văn bản đã trích xuất là không tin cậy và escape nó cho đích đến của nó.

Sự phù hợp tiêu chuẩn

Tuyên bố	Điều khoản tiêu chuẩn	Trạng thái
Duyệt node cấu trúc logic	ISO 32000-2:2020 §14.7	Đã xác minh (bộ kiểm thử đơn vị, AST gắn thẻ)
Trích xuất hàng/ô bảng	ISO 32000-2:2020 §14.8	Đã xác minh (bộ kiểm thử đơn vị)
Tìm kiếm ngữ nghĩa / embedding	—	Không hỗ trợ (ngoài phạm vi)

Phương án dự phòng / thay thế trong Core

Hệ con AST của Core tạo ra AstDocument được tiêu thụ ở đây; không có tương đương trong Core cho chính việc trích xuất khối trích dẫn. Xem /modules/core/ast/.

Ghi chú ranh giới Enterprise

Module này chỉ là một bộ trích xuất cấu trúc. Nó không thực hiện tìm kiếm ngữ nghĩa, embedding vector, xếp hạng tương đồng hay trí tuệ tài liệu. Những năng lực đó không thuộc về module này và không được ngụ ý bởi nó.

Ranh giới xuất bản

Trang này chỉ ghi lại hành vi có thể quan sát 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ộ, lớp trợ giúp, bảng cơ chế, tên tệp runbook và tiền tố ticket đều ngoài phạm vi.