Accelerator

Tổng quan nhanh

Accelerator chuyển tải việc nén lại ảnh theo lô, phân tích PDF, và nhúng văn bản sang một CPU sidecar đặt cùng vị trí. Khi sidecar không thể truy cập, mọi thao tác chuyển sang đường PHP trong tiến trình, nên bên gọi quan sát cùng kết quả dù theo cách nào.

Tính 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.

Accelerator không có cờ riêng theo từng tính năng. Đường được tăng tốc được chọn lúc chạy bởi một bước kiểm tra khả năng truy cập sidecar (ProAcceleratorProvider::isAvailable()); khi sidecar không thể truy cập, đường PHP trong tiến trình chạy thay thế.

Cài đặt

composer require nextpdf/pro:^3

Gói Premium cài mã nextpdf/pro dưới namespace NextPDF\Pro\Accelerator. Metapackage nextpdf/premium cũng cài các năng lực Enterprise; bản thân Accelerator là một tính năng bậc Pro.

Tổng quan khái niệm

ProAcceleratorProvider là điểm vào. Nó dựng bốn dịch vụ một cách lười (lazily):

• Một optimizer được tăng tốc bao quanh PdfOptimizer của Pro và chuyển tải việc xử lý ảnh theo lô sang sidecar.
• Một differ được tăng tốc bao quanh PdfDiffer của Pro; sidecar song song hóa việc phân tích cấu trúc trong khi bản thân thuật toán diff chạy trong PHP.
• Một dịch vụ embedding CPU trả về các vector 384 chiều bằng một mô hình ONNX all-MiniLM-L6-v2 được sidecar lưu trữ.
• Một vector index CPU dựng và tìm kiếm một HNSW index trong bộ nhớ được lập khóa theo một mã định danh collection.

Thiết kế giữ logic miền trong PHP. Sidecar thực hiện công việc có thể song song hóa, bị ràng buộc CPU (chuyển mã ảnh, phân tích đa tài liệu, suy luận ONNX, tìm kiếm vector). Mỗi đường được tăng tốc có một phương án dự phòng PHP tất định tạo ra kết quả tương đương.

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

Quyết định cốt lõi là tính đúng đắn không bao giờ phụ thuộc vào sidecar. Logic miền ở lại trong PHP; sidecar chỉ thực hiện công việc có thể song song hóa, bị ràng buộc CPU. Optimizer và differ (AcceleratedOptimizer, AcceleratedDiffer) giữ một phương án dự phòng PHP tất định, nên một sidecar vắng mặt chỉ thay đổi thời gian, không phải kết quả. Chỉ hai thao tác không có tương đương PHP — CpuEmbeddingService và CpuVectorIndex — thất bại đóng (fail closed) thay vì suy giảm. Một câu trả lời sai âm thầm ở đó sẽ tệ hơn một lỗi tường minh. Sự phân tách đó cho phép thông lượng mở rộng theo số lõi sidecar trong khi bên gọi giữ một đường mã và một ranh giới tin cậy.

Bối cảnh thiết kế: Tạo tài liệu khối lượng lớn.

Hợp đồng hành vi

• ProAcceleratorProvider::isAvailable() trả về việc sidecar có phản hồi hay không. Bên gọi có thể rẽ nhánh theo điều này, nhưng không bắt buộc: optimizer và differ tự động chuyển sang phương án dự phòng.
• embedding()->embed() trả về một vector 384 phần tử duy nhất; batchEmbed() trả về một vector cho mỗi đầu vào và từ chối một danh sách đầu vào rỗng với InvalidArgumentException.
• vectorIndex($collectionId)->build() yêu cầu vectors và ids có cùng độ dài và coi một đầu vào rỗng là một no-op.
• vectorIndex()->search($queryVector, $topK) trả về các kết quả đã xếp hạng; delete() không được hỗ trợ cho HNSW index và từ chối lệnh gọi — bên gọi dựng lại index thay vào đó.
• Dịch vụ embedding và vector index yêu cầu sidecar; chúng phát sinh một lỗi “not available” thay vì âm thầm suy giảm, vì không có tương đương PHP nào cho suy luận ONNX hay tìm kiếm HNSW.
• Optimizer và differ không bao giờ phát sinh lỗi khi sidecar thất bại; chúng suy giảm sang đường PHP một cách trong suốt.

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

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

use NextPDF\Pro\Accelerator\ProAcceleratorProvider;

$provider = new ProAcceleratorProvider($spectrumClient);

$result = $provider->optimizer()->optimizeBatch([
    'invoice-1' => $pdfBytesA,
    'invoice-2' => $pdfBytesB,
]);

foreach ($result->getItems() as $item) {
    // Per-document optimization outcome.
}

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

use NextPDF\Pro\Accelerator\ProAcceleratorProvider;

$provider = new ProAcceleratorProvider($spectrumClient);

if ($provider->isAvailable()) {
    $index = $provider->vectorIndex('contracts');
    $index->build($vectors, $ids);
    $hits = $index->search($queryVector, topK: 10);
} else {
    // No PHP equivalent for HNSW search: route to your own retrieval path
    // or surface a degraded-capability message.
}

Hãy nối ProAcceleratorProvider qua container của bạn dưới dạng một singleton để các thể hiện optimizer và differ được tái sử dụng. Hãy coi các lệnh gọi embedding và vector-index là cần sidecar.

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

• Vector index nằm trong bộ nhớ tiến trình sidecar và được lập khóa theo mã định danh collection. Một lần khởi động lại sidecar xóa mọi index; hãy dựng lại sau một lần khởi động lại.
• count() trên vector index trả về 0 khi sidecar không thể truy cập thay vì phát sinh lỗi.
• Việc tăng tốc optimizer và differ là nỗ lực tốt nhất (best-effort); một lỗi sidecar giữa chừng một lô gây ra một phương án dự phòng âm thầm cho lệnh gọi đó, nên thời gian — không phải tính đúng đắn — thay đổi.

Hiệu năng

Việc tăng tốc nhắm vào công việc theo lô bị ràng buộc CPU: chuyển mã ảnh song song, phân tích đa tài liệu, và tìm kiếm vector. NextPDF không công bố một hệ số nhân thông lượng cố định ở đây; mức tăng phụ thuộc vào hỗn hợp tài liệu, mật độ ảnh, số lõi sidecar, và kích thước lô. Hãy đo trong môi trường của bạn trước khi dựa vào một con số cụ thể. Phương án dự phòng PHP là đơn luồng theo thiết kế.

Lưu ý bảo mật

Module này gửi các tài liệu và vector tới sidecar đặt cùng vị trí qua kênh truyền tải đã cấu hình của nó. Hãy coi sidecar là một phần của ranh giới tin cậy của bạn và triển khai nó trên cùng host hoặc một phân đoạn mạng riêng. Module xác thực kích thước và hình dạng đầu vào trước khi gửi. Nó không ghi nhật ký nội dung tài liệu nào.

Tính phù hợp

Module này tự nó không thực hiện công việc phù hợp định dạng nào; nó ủy thác việc tối ưu hóa và so sánh cho các module Optimizer và Diff của Pro. Xem các module đó để biết các tài liệu tham chiếu ISO 32000-2. Bằng chứng phù hợp cho trang này được lấy từ các hợp đồng lớp công khai đã được ghi tài liệu và các unit test của chúng; kho RAG không khả dụng ở thời điểm soạn thảo, nên không có mã định danh điều khoản bên ngoài nào được khẳng định ở đây.

Lưu ý về ranh giới Enterprise

Enterprise không thay đổi hành vi của Accelerator. Enterprise bổ sung các tính năng tuân thủ, lưu trữ, và vòng đời chữ ký ở bậc cao hơn được ghi tài liệu ở nơi khác; những thứ đó nằm ngoài phạm vi của module này và không cần thiết để dùng Accelerator.

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

Khi không có Pro, hãy dùng việc tối ưu hóa và so sánh trong tiến trình của NextPDF Core. Các đường được tăng tốc trong module này thu về cùng hành vi PHP đó khi sidecar vắng mặt.

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ộ, lớp trợ giúp, bảng cơ chế, tên tệp runbook, và tiền tố phiếu (ticket) nằm ngoài phạm vi.

Xem thêm

• Accelerator — Tham chiếu chuyên sâu
• Optimizer
• Diff
• Output Pipeline