AST

Tổng quan nhanh

Module AST biến một PDF thành một cây tài liệu bất biến, có thể điều hướng. Nó dùng cây cấu trúc được gắn thẻ khi có và chuyển sang dùng một bộ dựng heuristic cho các tài liệu không gắn thẻ, đính kèm các bounding box và văn bản cho mỗi node.

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

Năng lực này có trong NextPDF Pro (nextpdf/pro) và kích hoạt với một license envelope bậc 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 tồn tại cờ giấy phép riêng theo từng tính năng. Mã đi kèm phiên bản Pro; hành vi dựng được điều phối hoàn toàn bởi AstBuildOptions (các giới hạn tài nguyên và khoảng trang), không phải bởi một công tắc giấy phép.

Cài đặt

composer require nextpdf/pro:^3

Mã nằm dưới namespace NextPDF\Pro\Ast.

Tổng quan khái niệm

AstBuilder điều phối pipeline PDF-sang-cây: kiểm tra bộ nhớ đệm, từ chối sớm đầu vào đã mã hóa, đọc cây cấu trúc cho các PDF được gắn thẻ, chuyển sang một đường không-gắn-thẻ nếu khác, đính kèm các bounding box từ việc phân tích content-stream, rồi lưu kết quả vào bộ nhớ đệm. Đầu ra là một AstDocument có các node bất biến; các cập nhật dựng lại cây con bị ảnh hưởng từ dưới lên thay vì thay đổi tại chỗ.

Tồn tại hai chiến lược dự phòng cho các PDF không gắn thẻ: một phương án dự phòng trần và một bộ dựng heuristic tùy chọn (AstBuildOptions::$useHeuristic). Module cũng cung cấp một đường emitter có thể ghi một AST trở lại một PDF và xác minh kết quả, cộng với một mutation log để theo dõi các thay đổi được áp dụng cho cây.

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

Cây là bất biến theo thiết kế. Mỗi lần chỉnh sửa chỉ dựng lại đường từ gốc-đến-node bị ảnh hưởng và chia sẻ các cây con không bị đụng tới theo danh tính, nên một AstDocument đã dựng có thể được giữ, lưu vào bộ nhớ đệm, và trao cho các bên đọc đồng thời một cách an toàn mà không cần bản sao phòng thủ. Điều này phản chiếu cách một PDF tự thay đổi trên đĩa: đường ghi-trở-lại nối thêm một cập nhật tăng dần thông qua AstWriter thay vì viết lại tệp, để nguyên các byte gốc — và mọi chữ ký hiện có. Một phiên bản chỉ-nối-thêm cũng rẻ để xác minh về mặt cấu trúc, đó là lý do AstWriter có thể kiểm tra chính đầu ra của mình trước khi trả về. Việc dựng lại các cây con thay vì thay đổi tại chỗ là quyết định duy nhất khiến module vừa có thể điều hướng vừa có thể chỉnh sửa an toàn.

Bối cảnh thiết kế: Cập nhật tăng dần và vì sao chúng quan trọng.

Hợp đồng hành vi

• AstBuilder::build($sourceHash) chấp nhận toàn bộ SHA-256 hex của PDF nguồn và trả về một AstDocument.
• Các PDF đã mã hóa bị từ chối với một lỗi unsupported-encryption chuyên dụng; hãy giải mã trước khi dựng.
• Khi không có cây cấu trúc nào, bộ dựng tự động dùng đường không-gắn-thẻ — heuristic nếu được bật, phương án dự phòng trần nếu khác.
• Các giới hạn tài nguyên trong AstBuildOptions (số node tối đa, độ sâu tối đa, bộ nhớ tối đa, timeout wall-clock) gây ra một lỗi build-limit hoặc build-timeout thay vì công việc không giới hạn.
• Khóa bộ nhớ đệm tích hợp bản băm nguồn và bản băm các tùy chọn, nên hai lần dựng với đầu vào và tùy chọn giống hệt nhau trả về cùng một cây.
• AstNode là bất biến; người tiêu thụ nhận các thể hiện node mới khi cây thay đổi.

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

Phần sau phản ánh API công khai đã được ghi tài liệu. Kho mã không đi kèm một ví dụ chạy được cho module này.

use NextPDF\Pro\Ast\AstBuilder;
use NextPDF\Pro\Ast\AstBuildOptions;

$builder = new AstBuilder($pdfReader, new AstBuildOptions());
$document = $builder->build($sha256OfPdf);

Mẫu mã — Sản phẩm

use NextPDF\Pro\Ast\AstBuilder;
use NextPDF\Pro\Ast\AstBuildOptions;

$options = new AstBuildOptions(
    maxNodes: 100_000,
    maxDepth: 200,
    maxMemoryBytes: 256 * 1024 * 1024,
    timeoutSeconds: 30.0,
    useHeuristic: true,
);

$builder = new AstBuilder($pdfReader, $options, $astCache);

try {
    $document = $builder->build($sha256OfPdf);
} catch (\NextPDF\Pro\Ast\Exception\AstUnsupportedEncryptionException $e) {
    // Decrypt the source first, then retry.
}

Trường hợp ngoại lệ & lưu ý

• Các trang có content stream không thể phân tích được sẽ bị bỏ qua trong khi đính kèm bounding-box; cây vẫn được trả về, chỉ là không có box cho các trang đó.
• Bộ dựng heuristic là tùy chọn bật. Khi nó bị tắt, các PDF không gắn thẻ tạo ra một cây thô hơn từ phương án dự phòng trần.
• Khoảng trang trong AstBuildOptions dùng các chỉ số dựa-trên-0, bao gồm cả hai đầu; để cả hai biên là null sẽ xử lý mọi trang.

Hiệu năng

Chi phí dựng tỷ lệ với số node và số trang; AstBuildOptions giới hạn cả hai. Bộ nhớ đệm đoản mạch các lần dựng lặp lại của cùng đầu vào với cùng tùy chọn. NextPDF không công bố một thời gian cố định theo từng tài liệu ở đây; timeout wall-clock (mặc định 30 s) và trần số node (mặc định 100,000) giới hạn công việc trường hợp xấu nhất. Hãy đo với các tài liệu đại diện.

Lưu ý bảo mật

Hãy coi đầu vào là không tin cậy. Bộ dựng từ chối các PDF đã mã hóa thay vì xử lý chúng một phần. Các trần tài nguyên (node, độ sâu, bộ nhớ, thời gian) bảo vệ chống lại các tài liệu bệnh lý hoặc thù địch. Module này không ghi nhật ký nội dung tài liệu nào.

Tính phù hợp

Đường cây cấu trúc đọc các cấu trúc PDF được gắn thẻ được định nghĩa bởi ISO 32000-2; mã nguồn của module chú thích các điều khoản content-stream và cấu trúc liên quan. Vì kho RAG không khả dụng ở thời điểm soạn thảo, trang này không khẳng định mã định danh điều khoản bên ngoài nào và giới hạn các phát biểu về sự phù hợp vào hành vi đã được xác minh bởi các test của module.

Lưu ý về ranh giới Enterprise

Enterprise không thay đổi hành vi của AST. Enterprise bổ sung các năng lực tuân thủ và lưu trữ ở bậc cao hơn được ghi tài liệu riêng; chúng không cần thiết để dựng hay tiêu thụ một AST.

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

Khi không có Pro, không có cây tài liệu tương đương nào; bên gọi phân tích các content stream trực tiếp bằng các nguyên hàm của NextPDF Core. Xem /modules/ast/.

Ranh giới công bố

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

Xem thêm

• AST — Tham chiếu chuyên sâu
• Projection
• Diff
• Output Pipeline