Acceleratore

In sintesi

Accelerator scarica su un sidecar CPU co-localizzato la ri-compressione batch delle immagini, il parsing dei PDF e l’embedding del testo. Quando il sidecar è irraggiungibile, ogni operazione ricade sul percorso PHP in-process, così che i chiamanti osservino gli stessi risultati in entrambi i casi.

Disponibilità e licenza

Questa capacità è distribuita in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di tale entitlement non carica le classi della capacità. Confronta le edizioni e ottieni una licenza.

Accelerator non ha un flag per-funzionalità separato. Il percorso accelerato viene selezionato in fase di esecuzione da un controllo di raggiungibilità del sidecar (ProAcceleratorProvider::isAvailable()); quando il sidecar è irraggiungibile, viene eseguito invece il percorso PHP in-process.

Installazione

composer require nextpdf/pro:^3

Il pacchetto Premium installa il codice nextpdf/pro sotto il namespace NextPDF\Pro\Accelerator. Il metapacchetto nextpdf/premium installa anche le capacità Enterprise; Accelerator in sé è una funzionalità di livello Pro.

Panoramica concettuale

ProAcceleratorProvider è il punto di ingresso. Costruisce in modo pigro (lazy) quattro servizi:

• Un optimizer accelerato che avvolge il PdfOptimizer di Pro e scarica il lavoro batch sulle immagini al sidecar.
• Un differ accelerato che avvolge il PdfDiffer di Pro; il sidecar parallelizza il parsing della struttura mentre l’algoritmo di diff stesso viene eseguito in PHP.
• Un servizio di embedding CPU che restituisce vettori a 384 dimensioni usando un modello ONNX all-MiniLM-L6-v2 ospitato dal sidecar.
• Un indice vettoriale CPU che costruisce e ricerca un indice HNSW in memoria indicizzato da un identificatore di collezione.

Il design mantiene la logica di dominio in PHP. Il sidecar esegue il lavoro parallelizzabile e CPU-bound (transcodifica delle immagini, parsing multi-documento, inferenza ONNX, ricerca vettoriale). Ogni percorso accelerato ha un fallback PHP deterministico che produce risultati equivalenti.

Perché funziona così

La decisione portante è che la correttezza non dipende mai dal sidecar. La logica di dominio resta in PHP; il sidecar esegue soltanto lavoro parallelizzabile e CPU-bound. L’optimizer e il differ (AcceleratedOptimizer, AcceleratedDiffer) mantengono un fallback PHP deterministico, così un sidecar mancante cambia la tempistica, non i risultati. Solo le due operazioni prive di un equivalente PHP — CpuEmbeddingService e CpuVectorIndex — falliscono in modo chiuso anziché degradare. Una risposta silenziosamente errata in quel punto sarebbe peggiore di un errore esplicito. Questa separazione consente al throughput di scalare con i core del sidecar mentre i chiamanti mantengono un solo percorso di codice e un solo confine di fiducia.

Contesto di progettazione: Generazione di documenti ad alto volume.

Contratto di comportamento

• ProAcceleratorProvider::isAvailable() restituisce se il sidecar risponde. I chiamanti possono ramificarsi su questo, ma non devono: l’optimizer e il differ ricadono automaticamente.
• embedding()->embed() restituisce un singolo vettore di 384 elementi; batchEmbed() restituisce un vettore per input e rifiuta un elenco di input vuoto con InvalidArgumentException.
• vectorIndex($collectionId)->build() richiede che vectors e ids abbiano la stessa lunghezza e tratta un input vuoto come un no-op.
• vectorIndex()->search($queryVector, $topK) restituisce risultati ordinati; delete() non è supportato per l’indice HNSW e rifiuta la chiamata — i chiamanti ricostruiscono invece l’indice.
• Il servizio di embedding e l’indice vettoriale richiedono il sidecar; sollevano un errore «non disponibile» anziché degradare silenziosamente, perché non c’è alcun equivalente PHP per l’inferenza ONNX o la ricerca HNSW.
• L’optimizer e il differ non sollevano mai in caso di fallimento del sidecar; degradano al percorso PHP in modo trasparente.

Esempio di codice — Avvio rapido

Quanto segue riflette l’API pubblica documentata (ProAcceleratorProvider). Il repository non include un esempio eseguibile per questo modulo.

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

Esempio di codice — Produzione

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

Cablare ProAcceleratorProvider tramite il proprio container come singleton, così che le istanze dell’optimizer e del differ siano riutilizzate. Trattare le chiamate di embedding e di indice vettoriale come richiedenti il sidecar.

Casi limite e insidie

• L’indice vettoriale risiede nella memoria del processo sidecar ed è indicizzato dall’identificatore di collezione. Un riavvio del sidecar svuota tutti gli indici; ricostruire dopo un riavvio.
• count() sull’indice vettoriale restituisce 0 quando il sidecar è irraggiungibile anziché sollevare.
• L’accelerazione dell’optimizer e del differ è best-effort; un errore del sidecar a metà batch causa un fallback silenzioso per quella chiamata, quindi varia la tempistica — non la correttezza.

Prestazioni

L’accelerazione mira al lavoro batch CPU-bound: transcodifica parallela delle immagini, parsing multi-documento e ricerca vettoriale. NextPDF non pubblica qui un moltiplicatore di throughput fisso; i guadagni dipendono dal mix di documenti, dalla densità delle immagini, dal numero di core del sidecar e dalla dimensione del batch. Misurare nel proprio ambiente prima di fare affidamento su un numero specifico. Il fallback PHP è single-threaded per progettazione.

Note di sicurezza

Questo modulo invia documenti e vettori al sidecar co-localizzato sul suo trasporto configurato. Trattare il sidecar come parte del proprio confine di fiducia e distribuirlo sullo stesso host o su un segmento di rete privato. Il modulo valida la dimensione e la forma dell’input prima del dispatch. Non registra alcun contenuto del documento.

Conformità

Questo modulo non esegue di per sé alcun lavoro di conformità di formato; delega l’ottimizzazione e il diffing ai moduli Optimizer e Diff di Pro. Vedere quei moduli per i riferimenti ISO 32000-2. Le prove di conformità per questa pagina provengono dai contratti di classe pubblici documentati e dai loro unit test; il corpus RAG non era disponibile al momento della redazione, quindi qui non si asserisce alcun identificatore di clausola esterno.

Nota sul confine Enterprise

Enterprise non modifica il comportamento di Accelerator. Enterprise aggiunge funzionalità di livello superiore di compliance, archiviazione e ciclo di vita della firma documentate altrove; queste sono fuori ambito per questo modulo e non sono richieste per usare Accelerator.

Fallback / alternativa Core

Senza Pro, usare l’ottimizzazione e il diffing in-process di NextPDF Core. I percorsi accelerati in questo modulo si riducono a quello stesso comportamento PHP quando il sidecar è assente.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie dell’API pubblica supportata. Percorsi di namespace interni, classi helper, tabelle di meccanismi, nomi di file di runbook e prefissi di ticket sono fuori ambito.

Vedere anche

• Accelerator — Riferimento approfondito
• Optimizer
• Diff
• Output Pipeline