Accelerator

Sekilas

Accelerator memindahkan re-kompresi gambar batch, penguraian PDF, dan penyematan teks ke sidecar CPU yang berlokasi sama. Ketika sidecar tidak dapat dijangkau, setiap operasi kembali (fallback) ke jalur PHP in-process, sehingga pemanggil mengamati hasil yang sama di kedua kasus.

Ketersediaan & lisensi

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

Accelerator tidak memiliki flag per-fitur tersendiri. Jalur terakselerasi dipilih saat runtime oleh pemeriksaan ketercapaian sidecar (ProAcceleratorProvider::isAvailable()); ketika sidecar tidak dapat dijangkau, jalur PHP in-process berjalan sebagai gantinya.

Pemasangan

composer require nextpdf/pro:^3

Paket Premium memasang kode nextpdf/pro di bawah namespace NextPDF\Pro\Accelerator. Metapackage nextpdf/premium juga memasang kapabilitas Enterprise; Accelerator itu sendiri adalah fitur tier Pro.

Ikhtisar konseptual

ProAcceleratorProvider adalah titik masuknya. Ia mengonstruksi empat layanan secara lazy:

• Sebuah optimizer terakselerasi yang membungkus PdfOptimizer Pro dan memindahkan pekerjaan gambar batch ke sidecar.
• Sebuah differ terakselerasi yang membungkus PdfDiffer Pro; sidecar memparalelkan penguraian struktur sementara algoritma diff itu sendiri berjalan di PHP.
• Sebuah layanan embedding CPU yang mengembalikan vektor 384-dimensi menggunakan model ONNX all-MiniLM-L6-v2 yang di-host oleh sidecar.
• Sebuah vector index CPU yang membangun dan mencari index HNSW in-memory yang dikunci oleh pengenal koleksi.

Desain menjaga logika domain tetap di PHP. Sidecar melakukan pekerjaan yang dapat diparalelkan dan terikat-CPU (transcoding gambar, penguraian multi-dokumen, inferensi ONNX, pencarian vektor). Setiap jalur terakselerasi memiliki fallback PHP deterministik yang menghasilkan hasil yang setara.

Mengapa cara kerjanya seperti ini

Keputusan penyangga utamanya adalah bahwa kebenaran tidak pernah bergantung pada sidecar. Logika domain tetap di PHP; sidecar hanya melakukan pekerjaan yang dapat diparalelkan dan terikat-CPU. Optimizer dan differ (AcceleratedOptimizer, AcceleratedDiffer) mempertahankan fallback PHP deterministik, sehingga sidecar yang hilang mengubah timing, bukan hasil. Hanya dua operasi yang tidak memiliki padanan PHP — CpuEmbeddingService dan CpuVectorIndex — yang gagal-tertutup (fail closed) alih-alih menurun. Jawaban salah yang diam-diam di sana akan lebih buruk daripada error eksplisit. Pemisahan itu memungkinkan throughput menskala dengan core sidecar sementara pemanggil mempertahankan satu jalur kode dan satu batas trust.

Latar belakang desain: Pembuatan dokumen volume-tinggi.

Kontrak perilaku

• ProAcceleratorProvider::isAvailable() mengembalikan apakah sidecar merespons. Pemanggil dapat bercabang berdasarkan ini, tetapi tidak harus: optimizer dan differ melakukan fallback secara otomatis.
• embedding()->embed() mengembalikan satu vektor 384-elemen; batchEmbed() mengembalikan satu vektor per input dan menolak daftar input kosong dengan InvalidArgumentException.
• vectorIndex($collectionId)->build() mensyaratkan vectors dan ids memiliki panjang yang sama dan memperlakukan input kosong sebagai no-op.
• vectorIndex()->search($queryVector, $topK) mengembalikan hasil berperingkat; delete() tidak didukung untuk index HNSW dan menolak panggilan — pemanggil membangun ulang index sebagai gantinya.
• Layanan embedding dan vector index membutuhkan sidecar; keduanya memunculkan error “not available” alih-alih menurun secara diam-diam, karena tidak ada padanan PHP untuk inferensi ONNX atau pencarian HNSW.
• Optimizer dan differ tidak pernah memunculkan error pada kegagalan sidecar; keduanya menurun ke jalur PHP secara transparan.

Contoh kode — Mulai cepat

Berikut mencerminkan API publik yang didokumentasikan (ProAcceleratorProvider). Repositori tidak mengapalkan contoh yang dapat dijalankan untuk modul ini.

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.
}

Contoh kode — Produksi

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.
}

Sambungkan ProAcceleratorProvider melalui container Anda sebagai singleton sehingga instance optimizer dan differ digunakan ulang. Perlakukan panggilan embedding dan vector-index sebagai membutuhkan sidecar.

Kasus tepi & jebakan

• Vector index tinggal di memori proses sidecar dan dikunci oleh pengenal koleksi. Restart sidecar membersihkan semua index; bangun ulang setelah restart.
• count() pada vector index mengembalikan 0 ketika sidecar tidak dapat dijangkau alih-alih memunculkan error.
• Akselerasi optimizer dan differ bersifat best-effort; error sidecar di tengah-batch menyebabkan fallback diam-diam untuk panggilan itu, sehingga timing — bukan kebenaran — yang bervariasi.

Performa

Akselerasi menargetkan pekerjaan batch terikat-CPU: transcoding gambar paralel, penguraian multi-dokumen, dan pencarian vektor. NextPDF tidak menerbitkan pengali throughput tetap di sini; perolehan bergantung pada campuran dokumen, densitas gambar, jumlah core sidecar, dan ukuran batch. Ukur di lingkungan Anda sebelum mengandalkan angka tertentu. Fallback PHP bersifat single-threaded secara desain.

Catatan keamanan

Modul ini mengirim dokumen dan vektor ke sidecar yang berlokasi sama melalui transport yang dikonfigurasinya. Perlakukan sidecar sebagai bagian dari batas trust Anda dan terapkan pada host yang sama atau segmen jaringan privat. Modul memvalidasi ukuran dan bentuk input sebelum dispatch. Ia tidak mencatat konten dokumen apa pun.

Konformansi

Modul ini tidak melakukan pekerjaan konformansi format sendiri; ia mendelegasikan optimisasi dan diffing ke modul Optimizer dan Diff Pro. Lihat modul tersebut untuk rujukan ISO 32000-2. Bukti konformansi untuk halaman ini bersumber dari kontrak kelas publik yang didokumentasikan dan unit test-nya; korpus RAG tidak tersedia saat penulisan, sehingga tidak ada pengenal klausa eksternal yang ditegaskan di sini.

Catatan batas Enterprise

Enterprise tidak mengubah perilaku Accelerator. Enterprise menambahkan fitur kepatuhan, archival, dan siklus-hidup tanda tangan tier-lebih-tinggi yang didokumentasikan di tempat lain; itu berada di luar cakupan modul ini dan tidak diperlukan untuk menggunakan Accelerator.

Fallback / alternatif Core

Tanpa Pro, gunakan optimisasi dan diffing in-process NextPDF Core. Jalur terakselerasi dalam modul ini menyusut ke perilaku PHP yang sama ketika sidecar tidak ada.

Batas publikasi

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

Lihat juga

• Accelerator — Referensi Mendalam
• Optimizer
• Diff
• Output Pipeline