Pro editie

Accelerator

In het kort

Accelerator offloadt batch-hercompressie van afbeeldingen, PDF-parsing en text-embedding naar een co-located CPU-sidecar. Wanneer de sidecar onbereikbaar is, valt elke bewerking terug op het in-process PHP-pad, zodat aanroepers in beide gevallen dezelfde resultaten waarnemen.

Beschikbaarheid en licenties

Deze mogelijkheid wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een Pro-tier licentie-envelope. Een deployment zonder die entitlement laadt de classes van de mogelijkheid niet. Vergelijk edities en verkrijg een licentie.

Accelerator heeft geen aparte vlag per functie. Het versnelde pad wordt tijdens runtime geselecteerd door een sidecar-bereikbaarheidscheck (ProAcceleratorProvider::isAvailable()); wanneer de sidecar onbereikbaar is, draait in plaats daarvan het in-process PHP-pad.

Installeren

composer require nextpdf/pro:^3

Het Premium-pakket installeert de nextpdf/pro-code onder de NextPDF\Pro\Accelerator-namespace. Het nextpdf/premium-metapakket installeert ook Enterprise-mogelijkheden; Accelerator zelf is een Pro-tier-functie.

Conceptueel overzicht

ProAcceleratorProvider is het toegangspunt. Het construeert lazy vier services:

Een accelerated optimizer die de Pro PdfOptimizer omhult en batch-beeldwerk offloadt naar de sidecar.
Een accelerated differ die de Pro PdfDiffer omhult; de sidecar parallelliseert structuurparsing terwijl het diff-algoritme zelf in PHP draait.
Een CPU embedding service die 384-dimensionale vectoren retourneert met behulp van een all-MiniLM-L6-v2 ONNX-model dat door de sidecar wordt gehost.
Een CPU vector index die een in-memory HNSW-index bouwt en doorzoekt, gekeyd met een collectie-identificator.

Het ontwerp houdt domeinlogica in PHP. De sidecar voert parallelliseerbaar, CPU-gebonden werk uit (beeldtranscodering, multi-document-parsing, ONNX-inferentie, vectorzoeken). Elk versneld pad heeft een deterministische PHP-terugval die equivalente resultaten produceert.

Waarom het zo werkt

De dragende beslissing is dat correctheid nooit afhangt van de sidecar. Domeinlogica blijft in PHP; de sidecar voert alleen parallelliseerbaar, CPU-gebonden werk uit. De optimizer en differ (AcceleratedOptimizer, AcceleratedDiffer) behouden een deterministische PHP-terugval, dus een ontbrekende sidecar verandert de timing, niet de resultaten. Alleen de twee bewerkingen zonder PHP-equivalent — CpuEmbeddingService en CpuVectorIndex — falen dicht in plaats van te degraderen. Een stilzwijgend fout antwoord daar zou erger zijn dan een expliciete fout. Die splitsing laat de doorvoer schalen met sidecar-cores terwijl aanroepers één codepad en één trust boundary behouden.

Ontwerpachtergrond: High-volume documentgeneratie.

Gedragscontract

ProAcceleratorProvider::isAvailable() retourneert of de sidecar reageert. Aanroepers kunnen hierop vertakken, maar hoeven dat niet: de optimizer en differ vallen automatisch terug.
embedding()->embed() retourneert één vector van 384 elementen; batchEmbed() retourneert één vector per invoer en wijst een lege invoerlijst af met InvalidArgumentException.
vectorIndex($collectionId)->build() vereist dat vectors en ids dezelfde lengte hebben en behandelt een lege invoer als een no-op.
vectorIndex()->search($queryVector, $topK) retourneert gerangschikte resultaten; delete() wordt niet ondersteund voor de HNSW-index en wijst de aanroep af — aanroepers herbouwen in plaats daarvan de index.
De embedding service en vector index vereisen de sidecar; ze werpen een “not available”-fout in plaats van stilzwijgend te degraderen, omdat er geen PHP-equivalent is voor ONNX-inferentie of HNSW-zoeken.
De optimizer en differ werpen nooit bij een sidecar-fout; ze degraderen transparant naar het PHP-pad.

Codevoorbeeld — Snelstart

Het volgende weerspiegelt de gedocumenteerde publieke API (ProAcceleratorProvider). De repository levert geen uitvoerbaar voorbeeld voor deze module.

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

Codevoorbeeld — Productie

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

Bedraad ProAcceleratorProvider via je container als een singleton zodat de optimizer- en differ-instances worden hergebruikt. Behandel de embedding- en vector-index-aanroepen als vereisend voor de sidecar.

Randgevallen en valkuilen

De vector index leeft in het procesgeheugen van de sidecar en is gekeyd met de collectie-identificator. Een sidecar-herstart wist alle indexen; herbouw na een herstart.
count() op de vector index retourneert 0 wanneer de sidecar onbereikbaar is in plaats van te werpen.
Optimizer- en differ-versnelling is best-effort; een sidecar-fout middenin een batch veroorzaakt een stilzwijgende terugval voor die aanroep, dus de timing — niet de correctheid — varieert.

Prestaties

Versnelling richt zich op CPU-gebonden batchwerk: parallelle beeldtranscodering, multi-document-parsing en vectorzoeken. NextPDF publiceert hier geen vaste doorvoervermenigvuldiger; de winst hangt af van documentmix, beelddichtheid, sidecar-kernaantal en batchgrootte. Meet in je eigen omgeving voordat je op een specifiek getal vertrouwt. De PHP-terugval is van ontwerp single-threaded.

Beveiligingsnotities

Deze module verzendt documenten en vectoren naar de co-located sidecar over zijn geconfigureerde transport. Behandel de sidecar als onderdeel van je trust boundary en implementeer die op dezelfde host of een privaat netwerksegment. De module valideert invoergrootte en -vorm vóór dispatch. Hij logt geen documentinhoud.

Conformiteit

Deze module voert zelf geen format-conformiteitswerk uit; het delegeert optimalisatie en diffing aan de Pro Optimizer- en Diff-modules. Zie die modules voor ISO 32000-2-referenties. Conformiteitsbewijs voor deze pagina is afkomstig van de gedocumenteerde publieke class-contracten en hun unittests; het RAG-corpus was tijdens het auteuren niet beschikbaar, dus hier worden geen externe clausule-identifiers beweerd.

Opmerking over de Enterprise-grens

Enterprise wijzigt het Accelerator-gedrag niet. Enterprise voegt hogere-tier compliance-, archiverings- en handtekeninglevenscyclusfuncties toe die elders zijn gedocumenteerd; die vallen buiten de scope van deze module en zijn niet vereist om Accelerator te gebruiken.

Core-terugval / alternatief

Zonder Pro gebruik je de in-process optimalisatie en diffing van NextPDF Core. De versnelde paden in deze module reduceren tot datzelfde PHP-gedrag wanneer de sidecar afwezig is.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-classes, mechanismetabellen, runbook-bestandsnamen en ticket-prefixen vallen buiten de scope.