Accelerator — Referensi Mendalam

Sekilas

Halaman ini adalah referensi mendalam untuk permukaan akselerasi publik NextPDF\Pro\Accelerator. Halaman ini mencakup provider factory, batch optimizer terakselerasi, wrapper differ, serta layanan CPU sidecar untuk embedding dan vector search. Halaman ini menyatakan parameter, nilai default, mode kegagalan, dan semantik fallback. Baca halaman kapabilitas Accelerator terlebih dahulu untuk panduan alur kerja.

Ketersediaan & lisensi

Kapabilitas ini hadir dalam NextPDF Pro (nextpdf/pro) dan aktif dengan envelope lisensi tingkat Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Accelerator tidak memiliki flag lisensi per-fitur. Kode ini hadir bersama edisi Pro; jalur optimizer terakselerasi dipilih saat runtime melalui probe reachability sidecar. Layanan embedding dan vector index tidak memiliki fallback PHP dan gagal-tertutup ketika sidecar tak dapat dijangkau.

Permukaan Public API

composer require nextpdf/pro:^3

Metapackage nextpdf/premium memasang kode nextpdf/pro; modul ini berada di bawah namespace NextPDF\Pro\Accelerator.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
ProAcceleratorProvider::__construct	SpectrumClient $client	Mengikat provider ke klien sidecar Core	ProAcceleratorProvider	Tidak ada yang dideklarasikan	Pemanggil mengonstruksi dan menyuplai klien
ProAcceleratorProvider::isAvailable	none	Melakukan probe reachability sidecar melalui klien	bool	Tidak ada yang dideklarasikan	Hanya reachability; endpoint diprobe per pemanggilan
ProAcceleratorProvider::embedding	none	Mengembalikan layanan embedding yang dimemoize	EmbeddingServiceInterface	Tidak ada yang dideklarasikan	Satu instance CpuEmbeddingService per provider
ProAcceleratorProvider::vectorIndex	string $collectionId = 'default'	Mengembalikan handle index baru yang terikat ke koleksi	VectorIndexInterface	Tidak ada yang dideklarasikan	Tidak dimemoize; satu handle per pemanggilan
ProAcceleratorProvider::optimizer	none	Mengembalikan optimizer terakselerasi yang dimemoize	AcceleratedOptimizer	Tidak ada yang dideklarasikan	Dikonstruksi dengan klien milik provider
ProAcceleratorProvider::differ	none	Mengembalikan wrapper differ yang dimemoize	AcceleratedDiffer	Tidak ada yang dideklarasikan	Dikonstruksi dengan klien milik provider
AcceleratedOptimizer::__construct	?SpectrumClient $spectrum = null, OptimizationLevel $level = OptimizationLevel::Balanced, ?LoggerInterface $logger = null	Membungkus PdfOptimizer PHP pada level yang diberikan	AcceleratedOptimizer	Tidak ada yang dideklarasikan	Klien null memilih jalur PHP; logger null memilih NullLogger
AcceleratedOptimizer::optimizeBatch	array<string, string> $documents	Menganalisis tiap dokumen; mengalihkan pekerjaan gambar ke sidecar saat dapat dijangkau	BatchResultInterface	SpectrumApiException SPEC-SEC-001 (HTTP 413) pada batch melebihi batas; penanda error per-item dalam hasil fallback	Kegagalan transport setelah admission menurun ke jalur PHP
AcceleratedDiffer::__construct	?SpectrumClient $spectrum = null	Menyimpan klien opsional untuk kompatibilitas ke depan	AcceleratedDiffer	Tidak ada yang dideklarasikan	Klien tidak digunakan pada rilis ini
AcceleratedDiffer::compare	string $sourcePdf, string $targetPdf	Membandingkan dua dokumen sepenuhnya di PHP	DiffResult	Sebagaimana PdfDiffer Pro	Tidak ada request sidecar yang dikirim pada rilis ini
AcceleratedDiffer::isSpectrumWired	none	Melaporkan apakah klien sidecar telah diinjeksikan	bool	Tidak ada yang dideklarasikan	Hanya status wiring; tidak mengirim request
CpuEmbeddingService::embed	string $text	Mendelegasikan ke batchEmbed dan mengembalikan elemen nol	list<float>	Sebagaimana batchEmbed	Vektor 384 dimensi
CpuEmbeddingService::batchEmbed	array $texts	Meng-embed batch di sidecar	list<list<float>>	InvalidArgumentException pada batch kosong; SpectrumNotAvailableException saat tak dapat dijangkau; SpectrumApiException pada respons yang gagal, malformed, atau jumlahnya tak cocok	Tidak pernah mengembalikan hasil parsial
CpuEmbeddingService::getDimension	none	Mengembalikan 384	int	Tidak ada yang dideklarasikan	Konstan
CpuEmbeddingService::getModelName	none	Mengembalikan all-MiniLM-L6-v2	string	Tidak ada yang dideklarasikan	Konstan
CpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Mengikat handle ke satu koleksi	CpuVectorIndex	Tidak ada yang dideklarasikan	Satu handle per pengenal koleksi
CpuVectorIndex::build	array $vectors, array $ids	Membangun index koleksi di sidecar	void	InvalidArgumentException pada ketidakcocokan panjang; SpectrumNotAvailableException saat tak dapat dijangkau	Input kosong kembali tanpa menghubungi sidecar
CpuVectorIndex::search	array $queryVector, int $topK = 10	Pencarian nearest-neighbor yang diperingkat	list<VectorSearchResult>	SpectrumNotAvailableException saat tak dapat dijangkau; SpectrumApiException pada envelope error in-band; JsonException pada body malformed	Peringkat per-hit ada di metadata hasil
CpuVectorIndex::delete	array $ids	Selalu menolak	void (dideklarasikan)	Selalu: SpectrumApiException SPEC-INDEX-004 (HTTP 501)	HNSW tidak punya penghapusan per-vektor; bangun ulang saja
CpuVectorIndex::count	none	Membaca total koleksi lewat probe berdimensi	int	SpectrumNotAvailableException saat tak dapat dijangkau; SpectrumApiException pada error atau respons count yang malformed	Mengembalikan 0 hanya untuk index yang dikonfirmasi kosong
CpuVectorIndex::INDEX_DIMENSION	—	Konstanta publik 384	int	—	Cocok dengan dimensi embedding

Tanda tangan entry-point

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
}

Kontrak perilaku

Provider

ProAcceleratorProvider adalah entry point. embedding(), optimizer(), dan differ() mememoize instance-nya. vectorIndex($collectionId) mengembalikan handle baru per pemanggilan, terikat ke pengenal koleksi yang diberikan. isAvailable() melakukan probe reachability sidecar melalui SpectrumClient Core yang diinjeksikan.

Optimasi batch

optimizeBatch mengembalikan hasil batch yang di-key berdasarkan pengenal dokumen milik pemanggil. Ketika sidecar dapat dijangkau, payload agregat divalidasi terhadap budget klien sebelum buffering atau upload apa pun. Batch melebihi batas gagal-tertutup dengan SpectrumApiException SPEC-SEC-001 (HTTP 413); ia tidak pernah menurun ke jalur PHP. Batch yang diterima dikirim ke sidecar untuk pekerjaan gambar paralel.

Kegagalan transport, autentikasi, atau parse-respons setelah admission menurun ke optimizer PHP, yang menganalisis tiap dokumen secara berurutan. Penurunan ini teramati dua kali: metadata hasil melaporkan engine php_fallback dengan ringkasan hardware cpu, dan peringatan PSR-3 dipancarkan di bawah nama event spectrum.optimize.fallback. Peringatan itu membawa kelas exception dan jumlah dokumen saja; tidak ada byte dokumen yang dicatat. Dalam hasil fallback, kegagalan analisis per-dokumen menghasilkan item berstatus error dengan kode SPEC-PARSE-001; dokumen lain dalam batch tetap selesai.

Level optimasi default adalah Balanced. Field hasil per-item adalah original_bytes, optimized_bytes, objects_removed, images_before, images_after, savings_percent, dan processing_time_ms.

Diff dokumen

compare berjalan sepenuhnya di PHP melalui PdfDiffer Pro: parsing struktur, ekstraksi teks, dan algoritma diff. Tidak ada request sidecar yang dikirim pada rilis ini. Kontrak differ hanya menerima string PDF mentah, sehingga hasil parse sidecar tidak dapat dikonsumsi; pengalihan hanya akan menambah biaya tanpa manfaat. Klien yang diinjeksikan disimpan untuk fitur parse-offload di masa depan. isSpectrumWired() mengekspos status wiring tanpa mengirim request.

CPU embedding

embed mendelegasikan ke batchEmbed([$text]) dan mengembalikan elemen nol. batchEmbed([]) memunculkan InvalidArgumentException sebelum menghubungi sidecar. Sidecar yang tak dapat dijangkau memunculkan SpectrumNotAvailableException. Semantik batch bersifat all-or-nothing: kegagalan per-item, vektor yang hilang atau malformed, atau ketidakcocokan jumlah memunculkan SpectrumApiException (kegagalan bentuk-protokol membawa SPEC-IO-001) alih-alih mengembalikan vektor parsial. Komponen non-numerik di dalam vektor yang dikembalikan dipaksa menjadi 0.0. getDimension mengembalikan 384; getModelName mengembalikan all-MiniLM-L6-v2. Sidecar mengunduh dan memuat model ONNX secara lazy pada request pertama.

CPU vector search

Setiap handle mengikat satu pengenal koleksi; setiap koleksi memetakan ke index HNSW in-memory terpisah di sidecar. build mensyaratkan daftar vektor dan pengenal berpanjang sama dan memunculkan InvalidArgumentException jika tidak; input kosong kembali tanpa pemanggilan sidecar. search mengembalikan hit terperingkat dengan rank berbasis-satu di metadata tiap hasil. Envelope error in-band memunculkan SpectrumApiException; envelope tanpa kode dipetakan ke SPEC-INDEX-003. delete selalu menolak dengan SpectrumApiException SPEC-INDEX-004 (HTTP 501, tidak dapat diulang) karena HNSW tidak mendukung penghapusan per-vektor; bangun ulang index saja.

count bersifat fail-closed dan tanpa ambiguitas. Sidecar yang tak dapat dijangkau memunculkan SpectrumNotAvailableException; error transport dan sidecar merambat tanpa perubahan. Pada respons yang sebaliknya sukses, body non-JSON memunculkan SPEC-INDEX-005, metadata.total_vectors yang hilang memunculkan SPEC-INDEX-006, dan total non-integer atau negatif memunculkan SPEC-INDEX-007. count mengembalikan 0 hanya untuk index yang dikonfirmasi kosong. Probe ukuran mengirimkan vektor nol berdimensi tepat INDEX_DIMENSION (384) dengan top_k sebesar 0, sehingga sidecar yang memvalidasi dimensi menerimanya.

Kasus tepi & mode kegagalan

• Memori sidecar bersifat volatil: restart menghapus semua koleksi HNSW. Perlakukan build index sebagai idempoten dan jalankan ulang setelah restart.
• Ketersediaan campuran dalam satu proses didukung: optimizer menurun per pemanggilan; layanan embedding dan vector gagal-tertutup per pemanggilan.
• Batch optimizer melebihi batas gagal-tertutup sebelum upload apa pun; ia tidak fallback ke jalur PHP.
• Fallback optimizer tidak pernah gagal secara diam-diam: periksa penanda engine di metadata hasil dan pantau event peringatan.
• count tidak pernah melaporkan sidecar yang tak dapat dijangkau atau error protokol sebagai 0; hal itu memunculkan exception bertipe.
• Hit pencarian yang kehilangan pengenal atau skornya mengambil default string kosong dan 0.0 alih-alih menggagalkan batch.
• top_k sebesar 0 digunakan secara internal hanya untuk probe count; gunakan topK positif untuk pencarian nyata.
• Request embedding pertama membayar biaya unduh dan muat model satu kali; ukur timeout itu secara terpisah.
• Hierarki exception sidecar dan famili kode error dikatalogkan di referensi error Accelerator.
• Modul ini tidak melakukan operasi kriptografis dan tidak mendefinisikan perilaku spesifik-FIPS. Postur mode FIPS diatur oleh modul signing dan compliance, bukan di sini.

Konformitas

Accelerator mendelegasikan pekerjaan yang memengaruhi format ke modul Optimizer dan Diff dan tidak menegaskan konformitas format independen. Konformitas untuk pekerjaan yang didelegasikan didokumentasikan di halaman referensi Optimizer dan Diff. Halaman ini tidak mengklaim pengenal klausa eksternal apa pun; setiap pernyataan berdasar pada source produk. NextPDF tidak membuat klaim sertifikasi.

Catatan pengembangan

• Source modul membawa @since 2.1.0; referensi ini mendokumentasikan permukaan sebagaimana dirilis dalam nextpdf/pro 3.1.0.
• Semua kelas bersifat final dan menggunakan constructor injection; konstruksi instance baru alih-alih memutasi.
• SpectrumClient, VectorSearchResult, BatchResultInterface, serta kontrak EmbeddingServiceInterface dan VectorIndexInterface berasal dari NextPDF Core; pemanggil mengonstruksi dan menyuplai klien sidecar.
• OptimizationLevel, PdfOptimizer, dan PdfDiffer berasal dari modul Optimizer dan Diff Pro; semantiknya didokumentasikan di halaman referensi tersebut.
• Layanan embedding dan vector index berbagi dimensi 384. Bangun vektor index ke dimensi yang sama dengan embedding yang menge-query-nya.
• Detail mekanisme internal tetap berada di dokumentasi internal repositori source dan berada di luar cakupan manual ini.

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang teramati secara eksternal dan permukaan public API yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama file runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Accelerator — halaman kapabilitas untuk panduan alur kerja.
• Referensi error Accelerator — hierarki exception sidecar dan kode error.
• Optimizer — Referensi Mendalam
• Diff — Referensi Mendalam
• Accelerator — Referensi Mendalam NextPDF Enterprise