Pro phiên bản

Accelerator — 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 chuyên sâu cho bề mặt tăng tốc công khai của NextPDF\Pro\Accelerator. Nó bao quát provider factory, accelerated batch optimizer, differ wrapper, và các dịch vụ CPU sidecar cho embedding và vector search. Nó nêu các tham số, giá trị mặc định, các chế độ lỗi, và ngữ nghĩa fallback. Hãy đọc trang khả năng Accelerator trước để có hướng dẫn quy trình.

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

Khả năng này xuất xưởng 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 class của khả năng này. So sánh các phiên bản và lấy giấy phép.

Accelerator không có cờ giấy phép riêng theo từng tính năng. Mã xuất xưởng cùng phiên bản Pro; đường dẫn optimizer được tăng tốc được chọn lúc chạy bằng một phép dò khả năng truy cập sidecar. Dịch vụ embedding và vector index không có fallback PHP nào và fail closed khi sidecar không truy cập được.

Bề mặt Public API

composer require nextpdf/pro:^3

Metapackage nextpdf/premium cài đặt mã nextpdf/pro; module này nằm dưới namespace NextPDF\Pro\Accelerator.

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
`ProAcceleratorProvider::__construct`	`SpectrumClient $client`	Ràng buộc provider với một Core sidecar client	`ProAcceleratorProvider`	Không khai báo gì	Bên gọi khởi tạo và cung cấp client
`ProAcceleratorProvider::isAvailable`	không có	Dò khả năng truy cập sidecar thông qua client	`bool`	Không khai báo gì	Chỉ khả năng truy cập; các endpoint được dò theo từng lời gọi
`ProAcceleratorProvider::embedding`	không có	Trả về dịch vụ embedding đã được ghi nhớ	`EmbeddingServiceInterface`	Không khai báo gì	Một thực thể `CpuEmbeddingService` cho mỗi provider
`ProAcceleratorProvider::vectorIndex`	`string $collectionId = 'default'`	Trả về một index handle mới được ràng buộc với collection	`VectorIndexInterface`	Không khai báo gì	Không ghi nhớ; một handle cho mỗi lời gọi
`ProAcceleratorProvider::optimizer`	không có	Trả về accelerated optimizer đã được ghi nhớ	`AcceleratedOptimizer`	Không khai báo gì	Được khởi tạo với client của provider
`ProAcceleratorProvider::differ`	không có	Trả về differ wrapper đã được ghi nhớ	`AcceleratedDiffer`	Không khai báo gì	Được khởi tạo với client của provider
`AcceleratedOptimizer::__construct`	`?SpectrumClient $spectrum = null`, `OptimizationLevel $level = OptimizationLevel::Balanced`, `?LoggerInterface $logger = null`	Bọc `PdfOptimizer` PHP ở mức đã cho	`AcceleratedOptimizer`	Không khai báo gì	Một client null chọn đường dẫn PHP; một logger null chọn `NullLogger`
`AcceleratedOptimizer::optimizeBatch`	`array<string, string> $documents`	Phân tích từng tài liệu; chuyển công việc ảnh sang sidecar khi truy cập được	`BatchResultInterface`	`SpectrumApiException` `SPEC-SEC-001` (HTTP 413) khi batch vượt giới hạn; các marker lỗi theo từng mục trong kết quả fallback	Các lỗi transport sau khi được nạp vào sẽ suy giảm về đường dẫn PHP
`AcceleratedDiffer::__construct`	`?SpectrumClient $spectrum = null`	Giữ lại client tùy chọn để tương thích về sau	`AcceleratedDiffer`	Không khai báo gì	Client không được dùng trong bản phát hành này
`AcceleratedDiffer::compare`	`string $sourcePdf`, `string $targetPdf`	So sánh hai tài liệu hoàn toàn trong PHP	`DiffResult`	Như `PdfDiffer` của Pro	Không phát ra yêu cầu sidecar nào trong bản phát hành này
`AcceleratedDiffer::isSpectrumWired`	không có	Báo cáo liệu một sidecar client có được tiêm vào hay không	`bool`	Không khai báo gì	Chỉ trạng thái đấu nối; không phát ra yêu cầu nào
`CpuEmbeddingService::embed`	`string $text`	Ủy thác cho `batchEmbed` và trả về phần tử số không	`list<float>`	Như `batchEmbed`	Vector 384 chiều
`CpuEmbeddingService::batchEmbed`	`array $texts`	Embed cả batch trên sidecar	`list<list<float>>`	`InvalidArgumentException` khi batch rỗng; `SpectrumNotAvailableException` khi không truy cập được; `SpectrumApiException` khi phản hồi thất bại, dị dạng, hoặc lệch số đếm	Không bao giờ trả về kết quả một phần
`CpuEmbeddingService::getDimension`	không có	Trả về `384`	`int`	Không khai báo gì	Hằng số
`CpuEmbeddingService::getModelName`	không có	Trả về `all-MiniLM-L6-v2`	`string`	Không khai báo gì	Hằng số
`CpuVectorIndex::__construct`	`SpectrumClient $client`, `string $collectionId = 'default'`	Ràng buộc handle với một collection	`CpuVectorIndex`	Không khai báo gì	Một handle cho mỗi định danh collection
`CpuVectorIndex::build`	`array $vectors`, `array $ids`	Dựng index của collection trên sidecar	`void`	`InvalidArgumentException` khi lệch độ dài; `SpectrumNotAvailableException` khi không truy cập được	Một đầu vào rỗng trả về mà không liên hệ sidecar
`CpuVectorIndex::search`	`array $queryVector`, `int $topK = 10`	Tìm kiếm lân cận gần nhất có xếp hạng	`list<VectorSearchResult>`	`SpectrumNotAvailableException` khi không truy cập được; `SpectrumApiException` khi có error envelope trong luồng; `JsonException` khi thân phản hồi dị dạng	Thứ hạng theo từng hit trong metadata kết quả
`CpuVectorIndex::delete`	`array $ids`	Luôn từ chối	`void` (khai báo)	Luôn: `SpectrumApiException` `SPEC-INDEX-004` (HTTP 501)	HNSW không có xóa theo từng vector; hãy dựng lại
`CpuVectorIndex::count`	không có	Đọc tổng của collection qua một phép dò có chiều	`int`	`SpectrumNotAvailableException` khi không truy cập được; `SpectrumApiException` khi có lỗi hoặc phản hồi đếm dị dạng	Chỉ trả về `0` cho một index đã xác nhận rỗng
`CpuVectorIndex::INDEX_DIMENSION`	—	Hằng số công khai `384`	`int`	—	Khớp với chiều của embedding

Chữ ký điểm vào

final class ProAcceleratorProvider
{
    public function __construct(
        private readonly SpectrumClient $client,
    )

    public function isAvailable(): bool

    public function embedding(): EmbeddingServiceInterface

    public function vectorIndex(string $collectionId = 'default'): VectorIndexInterface

    public function optimizer(): AcceleratedOptimizer

    public function differ(): AcceleratedDiffer
}

final class AcceleratedOptimizer
{
    public function __construct(
        private readonly ?SpectrumClient $spectrum = null,
        private readonly OptimizationLevel $level = OptimizationLevel::Balanced,
        ?LoggerInterface $logger = null,
    )

    public function optimizeBatch(array $documents): BatchResultInterface
}

final class AcceleratedDiffer
{
    public function __construct(
        private readonly ?SpectrumClient $spectrum = null,
    )

    public function compare(string $sourcePdf, string $targetPdf): DiffResult

    public function isSpectrumWired(): bool
}

final class CpuEmbeddingService implements EmbeddingServiceInterface
{
    public function __construct(
        private readonly SpectrumClient $client,
    )

    public function embed(string $text): array

    public function batchEmbed(array $texts): array

    public function getDimension(): int

    public function getModelName(): string
}

final class CpuVectorIndex implements VectorIndexInterface
{
    public const int INDEX_DIMENSION = 384;

    public function __construct(
        private readonly SpectrumClient $client,
        private readonly string $collectionId = 'default',
    )

    public function build(array $vectors, array $ids): void

    public function search(array $queryVector, int $topK = 10): array

    public function delete(array $ids): void

    public function count(): int
}

Hợp đồng hành vi

Provider

ProAcceleratorProvider là điểm vào. embedding(), optimizer(), và differ() ghi nhớ (memoize) các thực thể của chúng. vectorIndex($collectionId) trả về một handle mới cho mỗi lời gọi, được ràng buộc với định danh collection đã cho. isAvailable() dò khả năng truy cập sidecar thông qua SpectrumClient của Core được tiêm vào.

Tối ưu hóa theo batch

optimizeBatch trả về một kết quả batch được khóa theo các định danh tài liệu của bên gọi. Khi sidecar truy cập được, payload tổng hợp được kiểm định theo ngân sách client trước bất kỳ thao tác đệm hay tải lên nào. Một batch vượt giới hạn fail closed với SpectrumApiException SPEC-SEC-001 (HTTP 413); nó không bao giờ suy giảm về đường dẫn PHP. Một batch đã được nạp vào sẽ được phân phối tới sidecar để chạy công việc ảnh song song.

Một lỗi transport, xác thực, hoặc phân tích phản hồi sau khi được nạp vào sẽ suy giảm về optimizer PHP, vốn phân tích từng tài liệu một cách tuần tự. Sự suy giảm quan sát được ở hai nơi: metadata kết quả báo cáo engine php_fallback với phần cứng tóm tắt cpu, và một cảnh báo PSR-3 được phát ra dưới tên sự kiện spectrum.optimize.fallback. Cảnh báo chỉ mang theo lớp ngoại lệ và số lượng tài liệu; không có byte tài liệu nào được ghi log. Trong kết quả fallback, một lỗi phân tích theo từng tài liệu tạo ra một mục có trạng thái lỗi và mã SPEC-PARSE-001; các tài liệu khác trong batch vẫn hoàn tất.

Mức tối ưu hóa mặc định là Balanced. Các trường kết quả theo từng mục là original_bytes, optimized_bytes, objects_removed, images_before, images_after, savings_percent, và processing_time_ms.

Diff tài liệu

compare chạy hoàn toàn trong PHP qua PdfDiffer của Pro: phân tích cấu trúc, trích xuất văn bản, và thuật toán diff. Không phát ra yêu cầu sidecar nào trong bản phát hành này. Hợp đồng differ chỉ chấp nhận các chuỗi PDF thô, nên một kết quả phân tích từ sidecar không thể được tiêu thụ; việc chuyển tải sẽ thêm chi phí mà không có lợi ích. Một client được tiêm vào được giữ lại cho một tính năng chuyển-tải-phân-tích trong tương lai. isSpectrumWired() phơi bày trạng thái đấu nối mà không phát ra yêu cầu nào.

CPU embedding

embed ủy thác cho batchEmbed([$text]) và trả về phần tử số không. batchEmbed([]) phát sinh InvalidArgumentException trước khi liên hệ sidecar. Một sidecar không truy cập được phát sinh SpectrumNotAvailableException. Ngữ nghĩa batch là tất-cả-hoặc-không-gì: một lỗi theo từng mục, một vector thiếu hoặc dị dạng, hoặc một lệch số đếm sẽ phát sinh SpectrumApiException (các lỗi hình-dạng-giao-thức mang mã SPEC-IO-001) thay vì trả về các vector một phần. Một thành phần không phải số bên trong một vector trả về sẽ bị ép về 0.0. getDimension trả về 384; getModelName trả về all-MiniLM-L6-v2. Sidecar tải xuống và nạp model ONNX một cách lười biếng ở yêu cầu đầu tiên.

CPU vector search

Mỗi handle ràng buộc một định danh collection; mỗi collection ánh xạ tới một index HNSW trong-bộ-nhớ riêng biệt trong sidecar. build yêu cầu các danh sách vector và định danh có độ dài bằng nhau và phát sinh InvalidArgumentException nếu không; một đầu vào rỗng trả về mà không có lời gọi sidecar. search trả về các hit đã xếp hạng với một thứ hạng bắt-đầu-từ-một trong metadata của mỗi kết quả. Một error envelope trong luồng phát sinh SpectrumApiException; một envelope không có mã ánh xạ tới SPEC-INDEX-003. delete luôn từ chối với SpectrumApiException SPEC-INDEX-004 (HTTP 501, không thể thử lại) vì HNSW không hỗ trợ xóa theo từng vector; hãy dựng lại index.

count là fail-closed và không mơ hồ. Một sidecar không truy cập được phát sinh SpectrumNotAvailableException; các lỗi transport và sidecar lan truyền nguyên vẹn. Trên một phản hồi lẽ-ra-thành-công, một thân không phải JSON phát sinh SPEC-INDEX-005, một metadata.total_vectors bị thiếu phát sinh SPEC-INDEX-006, và một tổng không phải số nguyên hoặc âm phát sinh SPEC-INDEX-007. count chỉ trả về 0 cho một index đã xác nhận rỗng. Phép dò kích thước gửi một vector toàn số không với đúng INDEX_DIMENSION (384) chiều với một top_k bằng 0, nên một sidecar có kiểm định chiều sẽ chấp nhận nó.

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

Bộ nhớ sidecar là dễ bay hơi: một lần khởi động lại sẽ xóa mọi collection HNSW. Hãy coi việc dựng index là lũy đẳng và chạy lại sau khi khởi động lại.
Tình trạng khả dụng hỗn hợp trong một tiến trình đơn lẻ được hỗ trợ: optimizer suy giảm theo từng lời gọi; các dịch vụ embedding và vector fail closed theo từng lời gọi.
Một batch optimizer vượt giới hạn fail closed trước bất kỳ thao tác tải lên nào; nó không quay về đường dẫn PHP.
Fallback của optimizer không bao giờ thất bại âm thầm: hãy kiểm tra engine marker trong metadata kết quả và theo dõi sự kiện cảnh báo.
count không bao giờ báo cáo một sidecar không truy cập được hoặc một lỗi giao thức là 0; những trường hợp đó phát sinh các ngoại lệ có kiểu.
Một search hit thiếu định danh hoặc điểm số của nó mặc định về một chuỗi rỗng và 0.0 thay vì làm thất bại cả batch.
Một top_k bằng 0 chỉ được dùng nội bộ cho phép dò count; hãy truyền một topK dương cho các tìm kiếm thực.
Yêu cầu embedding đầu tiên gánh chi phí tải xuống và nạp model một lần; hãy định cỡ timeout đó riêng.
Cây phân cấp ngoại lệ sidecar và các họ mã lỗi được lập danh mục trong tài liệu tham chiếu lỗi Accelerator.
Module này không thực hiện thao tác mật mã nào và không định nghĩa hành vi riêng cho FIPS nào. Tư thế chế độ FIPS được điều chỉnh bởi các module ký và tuân thủ, không phải ở đây.

Tính phù hợp

Accelerator ủy thác công việc ảnh hưởng đến định dạng cho các module Optimizer và Diff và không khẳng định sự phù hợp định dạng độc lập nào. Sự phù hợp cho công việc được ủy thác được ghi tài liệu trên các trang tham chiếu Optimizer và Diff. Trang này không tuyên bố định danh điều khoản bên ngoài nào; mọi phát biểu đều dựa trên mã nguồn sản phẩm. NextPDF không đưa ra tuyên bố chứng nhận nào.

Ghi chú phát triển

Mã nguồn module mang @since 2.1.0; tài liệu tham chiếu này ghi bề mặt như đã xuất xưởng trong nextpdf/pro 3.1.0.
Tất cả các class đều là final và dùng constructor injection; hãy khởi tạo các thực thể mới thay vì biến đổi.
SpectrumClient, VectorSearchResult, BatchResultInterface, và các hợp đồng EmbeddingServiceInterface và VectorIndexInterface đến từ NextPDF Core; bên gọi khởi tạo và cung cấp sidecar client.
OptimizationLevel, PdfOptimizer, và PdfDiffer đến từ các module Optimizer và Diff của Pro; ngữ nghĩa của chúng được ghi tài liệu trên các trang tham chiếu đó.
Dịch vụ embedding và vector index dùng chung chiều 384. Hãy dựng các vector index cùng chiều với các embedding truy vấn chúng.
Chi tiết cơ chế nội bộ nằm trong tài liệu nội bộ của repository nguồn và nằm ngoài phạm vi của sổ tay này.

Ranh giới xuất bản

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

Xem thêm

Accelerator — trang khả năng để có hướng dẫn quy trình.
Tài liệu tham chiếu lỗi Accelerator — cây phân cấp ngoại lệ sidecar và các mã lỗi.
Optimizer — Tài liệu tham chiếu chuyên sâu
Diff — Tài liệu tham chiếu chuyên sâu
Accelerator — Tài liệu tham chiếu chuyên sâu NextPDF Enterprise