Pro phiên bản

Extraction — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Trang này là tài liệu tham chiếu ở cấp hợp đồng cho NextPDF\Pro\Extraction. Module chứa năm ký hiệu công khai: hai bộ trích xuất (CitedTextExtractor, CitedTableExtractor) và ba value object bất biến (CitedTextBlock, CitedTableBlock, CitedTableCell). Cả hai bộ trích xuất đều tiêu thụ một NextPDF\Ast\AstDocument đã được phân tích; không bộ nào đọc byte PDF thô. Việc trích xuất là tất định và mang tính cấu trúc. Không có bước ngữ nghĩa, embedding, hay xếp hạng nào tồn tại ở bất cứ đâu trong module này. Góc nhìn thiên về tác vụ nằm trên trang năng lực.

Tình trạng khả dụng & cấp phép

Năng lực này được cung cấp trong NextPDF Pro (nextpdf/pro) và kích hoạt bằng một license envelope 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. So sánh các phiên bản và lấy giấy phép.

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 luôn khả dụng bất cứ khi nào nextpdf/pro được cài đặt và được cấp phép.

Bề mặt API công khai

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném ra hoặc thất bại với	Ghi chú
`CitedTextExtractor::__construct()`	`?int $maxTokensPerChunk = null`, `int $minChunkLength = 10`	Không có ngân sách token; văn bản đã cắt khoảng trắng dưới 10 byte sẽ bị bỏ	`CitedTextExtractor`	Không ném ngoại lệ	Ngân sách `null` nghĩa là một khối cho mỗi node.
`CitedTextExtractor::extract()`	`AstDocument $document`	Duyệt theo chiều sâu trước; một khối cho mỗi node văn bản đủ điều kiện, tách theo ngân sách token	`list<CitedTextBlock>`	Không ném ngoại lệ	Tất định; `chunkIndex` đặt lại về 0 ở mỗi lần gọi.
`CitedTextBlock`	năm trường readonly	Value object bất biến; không có phương thức tuần tự hóa	—	Không ném ngoại lệ	Các khóa `metadata`: `nodeType`, `pageIndex`, cùng các khóa tùy chọn `structType`, `lang`, `alt`, `untagged`.
`CitedTextBlock::estimatedTokens()`	không có	`ceil(byte length / 4)`	`int`	Không ném ngoại lệ	Heuristic ngân sách; không phải một tokenizer.
`CitedTableExtractor::extract()`	`AstDocument $document`	Thu thập các node `Table` ngoài cùng theo thứ tự tài liệu	`list<CitedTableBlock>`	Không ném ngoại lệ	Không bao giờ đi sâu vào cây con của một bảng.
`CitedTableBlock`	năm trường readonly	Ma trận ô bất biến, hình chữ nhật, theo hàng trước (row-major)	—	Không ném ngoại lệ	Các hàng ngắn được đệm bên phải tại thời điểm trích xuất.
`CitedTableBlock::toArray()`	không có	Tuần tự hóa thành một mảng thuần snake_case	`array<string, mixed>`	Không ném ngoại lệ	Các ô lồng nhau được tuần tự hóa qua `CitedTableCell::toArray()`.
`CitedTableCell`	bảy trường readonly	Bản ghi ô bất biến với tọa độ trích dẫn	—	Không ném ngoại lệ	Các ô đệm mang một `nodeId` rỗng và độ tin cậy 0.0.
`CitedTableCell::toArray()`	không có	Tuần tự hóa thành một mảng thuần snake_case; `bbox` được lồng vào hoặc là `null`	`array<string, mixed>`	Không ném ngoại lệ	—

final class CitedTextExtractor

public function __construct(
    private readonly ?int $maxTokensPerChunk = null,
    private readonly int $minChunkLength = 10,
)

public function extract(AstDocument $document): array

final class CitedTableExtractor

public function extract(AstDocument $document): array

final readonly class CitedTextBlock

public function __construct(
    public string $text,
    public CitationAnchor $anchor,
    public float $confidence,
    public int $chunkIndex,
    public array $metadata,
)

public function estimatedTokens(): int

final readonly class CitedTableBlock

public function __construct(
    public readonly string $nodeId,
    public readonly int    $pageIndex,
    public readonly int    $rowCount,
    public readonly int    $colCount,
    public readonly array  $matrix,
)

public function toArray(): array

final readonly class CitedTableCell

public function __construct(
    public readonly string       $nodeId,
    public readonly int          $row,
    public readonly int          $col,
    public readonly ?string      $textContent,
    public readonly ?BoundingBox $bbox,
    public readonly int          $pageIndex,
    public readonly float        $confidence,
)

public function toArray(): array

Hợp đồng hành vi

Lựa chọn node. CitedTextExtractor phát ra các khối cho những node có loại là Paragraph, Heading, ListItem, TableCell, Code, hoặc Annotation. Một node có văn bản null sẽ bị bỏ qua. Một node chỉ được phát ra khi độ dài văn bản đã cắt khoảng trắng của nó tối thiểu bằng minChunkLength (mặc định 10). Mọi độ dài đều là độ dài theo byte.
Thứ tự duyệt. Lượt duyệt theo chiều sâu trước, bắt đầu từ gốc tài liệu. Một node đủ điều kiện được phát ra trước khi các con của nó được thăm. chunkIndex tăng dần xuyên suốt toàn bộ lượt duyệt tài liệu và đặt lại về 0 ở mỗi lần gọi extract().
Phân khối. Khi maxTokensPerChunk không được đặt, mỗi node cho ra một khối. Khi được đặt, văn bản dài hơn maxTokensPerChunk * 4 byte sẽ được tách. Bộ tách ưu tiên một ranh giới câu — một ký tự xuống dòng, hoặc một dấu chấm theo sau là một khoảng trắng — tìm được bằng cách quét lùi nhiều nhất 200 byte từ điểm cắt ưu tiên. Nếu không, nó cắt cứng tại mức ngân sách. Các khoảng trắng sau một điểm cắt sẽ bị bỏ qua; các khối rỗng bị loại bỏ.
Neo trích dẫn. CitationAnchor của mỗi khối mang theo node id, page index, một hộp bao, một độ tin cậy, và một content hash null. Các node không có hộp bao sẽ nhận một sentinel diện-tích-bằng-không dùng chung, BoundingBox(0, 0, 0, 0), nên neo luôn hợp lệ về mặt cấu trúc.
Độ tin cậy văn bản. Độ tin cậy đọc từ thuộc tính confidence của node khi nó là int hoặc float; mặc định là 1.0. Các giá trị thuộc tính không phải số sẽ quay về mặc định.
Metadata của khối. metadata luôn mang theo nodeType và pageIndex. structType, lang, và alt được sao chép khi hiện diện trên node. untagged được đặt thành true khi node mang một thuộc tính untagged.
Lựa chọn bảng. CitedTableExtractor chỉ thu thập các node Table ngoài cùng, theo thứ tự tài liệu. Một khi một node Table được xử lý, cây con của nó không được xem xét lại; các bảng lồng nhau không được hỗ trợ.
Hình dạng ma trận. Các hàng đến từ các con TableRow; các ô đến từ các con TableCell của chúng. Các loại con khác bị bỏ qua. colCount là số ô lớn nhất trên tất cả các hàng. Các hàng ngắn được đệm bên phải cho bằng colCount bằng các ô tổng hợp: nodeId rỗng, văn bản null, bbox null, page index của bảng, độ tin cậy 0.0. Một bảng không có hàng hoặc không có cột sẽ không cho ra khối nào.
Độ tin cậy ô. Độ tin cậy của một ô thực đọc từ thuộc tính confidence của nó khi đó là int hoặc float; mặc định là 0.8. Các khối văn bản mặc định 1.0; các ô bảng mặc định 0.8.
Ánh xạ cấu trúc. Hệ phân cấp được duyệt ánh xạ vào mô hình cấu trúc logic của PDF (ISO 32000-2:2020 §14.7). Các hàng bảng ánh xạ vào phần tử cấu trúc TR (§14.8) khi nguồn được gắn thẻ.

Các trường hợp biên & chế độ lỗi

Không có gì trên bề mặt này ném ngoại lệ. Cả hai phương thức extract() đều trả về một danh sách rỗng đối với tài liệu không có node đủ điều kiện.
Hộp bao diện-tích-bằng-không là một sentinel singleton dùng chung. Bên gọi nào cần một vùng thực phải phát hiện nó một cách tường minh: width === 0.0 && height === 0.0.
Mọi phép kiểm tra độ dài và phép tách đều dựa trên byte. Khi không tồn tại ranh giới câu nào trong cửa sổ 200 byte, một điểm cắt cứng có thể rơi vào giữa một chuỗi UTF-8 nhiều byte.
Con số 4-byte-mỗi-token chỉ là một heuristic để tính ngân sách. Nó không phải một tokenizer và không khớp với cách tokenization của bất kỳ mô hình cụ thể nào. estimatedTokens() dùng cùng heuristic đó.
Một chuỗi số trong thuộc tính confidence sẽ không được ép kiểu; mặc định được áp dụng. Chỉ các giá trị int và float được tôn trọng.
Việc bỏ qua khoảng trắng sau một điểm cắt chỉ loại bỏ các khoảng trắng thường. Các ký tự tab và xuống dòng ở đầu một khối được giữ lại.
Văn bản TableCell được trích xuất hai lần theo thiết kế: dưới dạng các khối văn bản bởi CitedTextExtractor, và bên trong các ma trận bởi CitedTableExtractor. Hãy khử trùng lặp ở phía sau khi chạy cả hai bộ trích xuất trên cùng một tài liệu.
Các ô đệm có thể nhận biết qua một nodeId rỗng và độ tin cậy 0.0. Một ô thực nhưng rỗng vẫn giữ nodeId không rỗng của nó.
Không có thao tác mã hóa nào xảy ra trong module này, nên không có hành vi đặc thù chế độ FIPS.

Tính phù hợp

Khi tài liệu nguồn được gắn thẻ, AST phản chiếu hệ phân cấp cấu trúc logic của ISO 32000-2:2020 §14.7, và các node Table/TableRow tương ứng với các phần tử cấu trúc Table/TR của §14.8. Chất lượng trích xuất bị giới hạn bởi chất lượng gắn thẻ; nội dung chưa gắn thẻ tạo ra ít node hơn hoặc node thô hơn.

Đây là các phát biểu về căn chỉnh cấu trúc, không phải kết quả kiểm thử tính phù hợp. NextPDF không nắm giữ chứng nhận nào và cũng không cấp chứng nhận nào. Module này không tự đưa ra tuyên bố phù hợp nào; nó tiêu thụ bất kỳ cấu trúc nào mà hệ thống con Core AST tạo ra.

Ghi chú phát triển

Tái sử dụng một instance CitedTextExtractor trên nhiều tài liệu là an toàn khi thực hiện tuần tự; extract() đặt lại chunkIndex trước mỗi lượt duyệt.
Điều chỉnh minChunkLength để lọc các node nhiễu (số trang, các chuỗi glyph rời rạc) trước khi phân khối, chứ không phải sau.
Với CJK và các hệ chữ nhiều byte khác, heuristic dựa trên byte đếm quá nhiều token; hãy định cỡ maxTokensPerChunk cho phù hợp.
CitedTableBlock::toArray() và CitedTableCell::toArray() phát ra các khóa snake_case cho các pipeline JSON. CitedTextBlock không có bộ tuần tự hóa; hãy tự mã hóa các trường của nó.
Trường contentHash của CitationAnchor luôn là null trên bề mặt này. Hãy tính các content hash ở phía sau khi pipeline cần chúng.

Ranh giới công bố

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