Accelerator — Riferimento approfondito

In sintesi

Questa pagina è il riferimento approfondito per la superficie di accelerazione pubblica di NextPDF\Pro\Accelerator. Copre la factory del provider, l’optimizer batch accelerato, il wrapper del differ e i servizi CPU basati su sidecar per l’embedding e la ricerca vettoriale. Indica parametri, valori predefiniti, modalità di errore e semantica di fallback. Consultare prima la pagina della funzionalità Accelerator per indicazioni sul flusso di lavoro.

Disponibilità e licenze

Questa funzionalità è 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 funzionalità. Confronta le edizioni e ottieni una licenza.

Accelerator non ha un flag di licenza per singola funzionalità. Il codice è distribuito con l’edizione Pro; il percorso dell’optimizer accelerato è selezionato a runtime da una sonda di raggiungibilità del sidecar. Il servizio di embedding e l’indice vettoriale non hanno alcun fallback PHP e falliscono fail-closed quando il sidecar è irraggiungibile.

Superficie API pubblica

composer require nextpdf/pro:^3

Il metapacchetto nextpdf/premium installa il codice nextpdf/pro; questo modulo risiede nel namespace NextPDF\Pro\Accelerator.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
ProAcceleratorProvider::__construct	SpectrumClient $client	Vincola il provider a un client di sidecar di Core	ProAcceleratorProvider	Nulla dichiarato	Il chiamante costruisce e fornisce il client
ProAcceleratorProvider::isAvailable	nessuno	Sonda la raggiungibilità del sidecar tramite il client	bool	Nulla dichiarato	Solo raggiungibilità; gli endpoint sono sondati a ogni chiamata
ProAcceleratorProvider::embedding	nessuno	Restituisce il servizio di embedding memoizzato	EmbeddingServiceInterface	Nulla dichiarato	Una istanza di CpuEmbeddingService per provider
ProAcceleratorProvider::vectorIndex	string $collectionId = 'default'	Restituisce un handle di indice nuovo vincolato alla collezione	VectorIndexInterface	Nulla dichiarato	Non memoizzato; un handle per chiamata
ProAcceleratorProvider::optimizer	nessuno	Restituisce l’optimizer accelerato memoizzato	AcceleratedOptimizer	Nulla dichiarato	Costruito con il client del provider
ProAcceleratorProvider::differ	nessuno	Restituisce il wrapper del differ memoizzato	AcceleratedDiffer	Nulla dichiarato	Costruito con il client del provider
AcceleratedOptimizer::__construct	?SpectrumClient $spectrum = null, OptimizationLevel $level = OptimizationLevel::Balanced, ?LoggerInterface $logger = null	Avvolge il PdfOptimizer PHP al livello indicato	AcceleratedOptimizer	Nulla dichiarato	Un client null seleziona il percorso PHP; un logger null seleziona NullLogger
AcceleratedOptimizer::optimizeBatch	array<string, string> $documents	Analizza ciascun documento; trasferisce il lavoro sulle immagini al sidecar quando raggiungibile	BatchResultInterface	SpectrumApiException SPEC-SEC-001 (HTTP 413) per un batch oltre il limite; marcatori di errore per singolo elemento nel risultato di fallback	Gli errori di trasporto dopo l’ammissione degradano al percorso PHP
AcceleratedDiffer::__construct	?SpectrumClient $spectrum = null	Conserva il client opzionale per compatibilità futura	AcceleratedDiffer	Nulla dichiarato	Il client non è utilizzato in questa release
AcceleratedDiffer::compare	string $sourcePdf, string $targetPdf	Confronta due documenti interamente in PHP	DiffResult	Come il PdfDiffer di Pro	In questa release non viene emessa alcuna richiesta al sidecar
AcceleratedDiffer::isSpectrumWired	nessuno	Riporta se è stato iniettato un client di sidecar	bool	Nulla dichiarato	Solo stato di cablaggio; non emette alcuna richiesta
CpuEmbeddingService::embed	string $text	Delega a batchEmbed e restituisce l’elemento zero	list<float>	Come batchEmbed	Vettore a 384 dimensioni
CpuEmbeddingService::batchEmbed	array $texts	Esegue l’embedding del batch sul sidecar	list<list<float>>	InvalidArgumentException per un batch vuoto; SpectrumNotAvailableException quando irraggiungibile; SpectrumApiException per una risposta fallita, malformata o con conteggio non coincidente	Non restituisce mai risultati parziali
CpuEmbeddingService::getDimension	nessuno	Restituisce 384	int	Nulla dichiarato	Costante
CpuEmbeddingService::getModelName	nessuno	Restituisce all-MiniLM-L6-v2	string	Nulla dichiarato	Costante
CpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Vincola l’handle a una sola collezione	CpuVectorIndex	Nulla dichiarato	Un handle per identificatore di collezione
CpuVectorIndex::build	array $vectors, array $ids	Costruisce l’indice della collezione sul sidecar	void	InvalidArgumentException per una lunghezza non coincidente; SpectrumNotAvailableException quando irraggiungibile	Un input vuoto restituisce senza contattare il sidecar
CpuVectorIndex::search	array $queryVector, int $topK = 10	Ricerca dei vicini più prossimi ordinata	list<VectorSearchResult>	SpectrumNotAvailableException quando irraggiungibile; SpectrumApiException per un envelope di errore in banda; JsonException per un corpo malformato	Rank per ciascun hit nei metadati del risultato
CpuVectorIndex::delete	array $ids	Rifiuta sempre	void (dichiarato)	Sempre: SpectrumApiException SPEC-INDEX-004 (HTTP 501)	HNSW non ha cancellazione per singolo vettore; ricostruire invece
CpuVectorIndex::count	nessuno	Legge il totale della collezione tramite una sonda dimensionata	int	SpectrumNotAvailableException quando irraggiungibile; SpectrumApiException per un errore o una risposta di conteggio malformata	Restituisce 0 solo per un indice confermato vuoto
CpuVectorIndex::INDEX_DIMENSION	—	Costante pubblica 384	int	—	Corrisponde alla dimensione dell’embedding

Firme dei punti di ingresso

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
}

Contratto di comportamento

Provider

ProAcceleratorProvider è il punto di ingresso. embedding(), optimizer() e differ() memoizzano le proprie istanze. vectorIndex($collectionId) restituisce un handle nuovo a ogni chiamata, vincolato all’identificatore di collezione fornito. isAvailable() sonda la raggiungibilità del sidecar tramite il SpectrumClient di Core iniettato.

Ottimizzazione batch

optimizeBatch restituisce un risultato batch indicizzato per gli identificatori di documento del chiamante. Quando il sidecar è raggiungibile, il payload aggregato viene validato rispetto al budget del client prima di qualsiasi buffering o upload. Un batch oltre il limite fallisce fail-closed con SpectrumApiException SPEC-SEC-001 (HTTP 413); non degrada mai al percorso PHP. Un batch ammesso viene inviato al sidecar per il lavoro parallelo sulle immagini.

Un errore di trasporto, di autenticazione o di parsing della risposta dopo l’ammissione degrada all’optimizer PHP, che analizza ciascun documento in sequenza. La degradazione è osservabile due volte: i metadati del risultato riportano il motore php_fallback con hardware di riepilogo cpu, e un avviso PSR-3 viene emesso sotto il nome di evento spectrum.optimize.fallback. L’avviso riporta solo la classe dell’eccezione e il conteggio dei documenti; nessun byte di documento viene registrato. Nel risultato di fallback, un errore di analisi per singolo documento produce un elemento con stato di errore e codice SPEC-PARSE-001; gli altri documenti del batch vengono comunque completati.

Il livello di ottimizzazione predefinito è Balanced. I campi del risultato per singolo elemento sono original_bytes, optimized_bytes, objects_removed, images_before, images_after, savings_percent e processing_time_ms.

Diff dei documenti

compare viene eseguito interamente in PHP tramite il PdfDiffer di Pro: parsing della struttura, estrazione del testo e algoritmo di diff. In questa release non viene emessa alcuna richiesta al sidecar. Il contratto del differ accetta solo stringhe PDF grezze, quindi un risultato di parsing del sidecar non può essere consumato; il trasferimento aggiungerebbe costo senza alcun beneficio. Un client iniettato viene conservato per una futura funzionalità di parse-offload. isSpectrumWired() espone lo stato di cablaggio senza emettere una richiesta.

Embedding su CPU

embed delega a batchEmbed([$text]) e restituisce l’elemento zero. batchEmbed([]) solleva InvalidArgumentException prima di contattare il sidecar. Un sidecar irraggiungibile solleva SpectrumNotAvailableException. La semantica del batch è tutto-o-niente: un errore per singolo elemento, un vettore mancante o malformato, o un conteggio non coincidente sollevano SpectrumApiException (gli errori di forma del protocollo riportano SPEC-IO-001) anziché restituire vettori parziali. Un componente non numerico all’interno di un vettore restituito viene forzato a 0.0. getDimension restituisce 384; getModelName restituisce all-MiniLM-L6-v2. Il sidecar scarica e carica il modello ONNX in modalità lazy alla prima richiesta.

Ricerca vettoriale su CPU

Ogni handle è vincolato a un identificatore di collezione; ogni collezione corrisponde a un indice HNSW in memoria separato nel sidecar. build richiede liste di vettori e identificatori di uguale lunghezza e in caso contrario solleva InvalidArgumentException; un input vuoto restituisce senza una chiamata al sidecar. search restituisce hit ordinati con un rank a base uno nei metadati di ciascun risultato. Un envelope di errore in banda solleva SpectrumApiException; un envelope privo di codice viene mappato a SPEC-INDEX-003. delete rifiuta sempre con SpectrumApiException SPEC-INDEX-004 (HTTP 501, non ripetibile) perché HNSW non supporta la cancellazione per singolo vettore; ricostruire invece l’indice.

count è fail-closed e non ambiguo. Un sidecar irraggiungibile solleva SpectrumNotAvailableException; gli errori di trasporto e del sidecar si propagano inalterati. In una risposta altrimenti riuscita, un corpo non JSON solleva SPEC-INDEX-005, un metadata.total_vectors mancante solleva SPEC-INDEX-006, e un totale non intero o negativo solleva SPEC-INDEX-007. count restituisce 0 solo per un indice confermato vuoto. La sonda di dimensione invia un vettore nullo di esattamente INDEX_DIMENSION (384) dimensioni con un top_k di 0, così un sidecar che valida la dimensione lo accetta.

Casi limite e modalità di errore

• La memoria del sidecar è volatile: un riavvio cancella tutte le collezioni HNSW. Trattare la costruzione dell’indice come idempotente e rieseguirla dopo un riavvio.
• La disponibilità mista all’interno di un singolo processo è supportata: l’optimizer degrada per chiamata; i servizi di embedding e vettoriale falliscono fail-closed per chiamata.
• Un batch dell’optimizer oltre il limite fallisce fail-closed prima di qualsiasi upload; non ripiega sul percorso PHP.
• Il fallback dell’optimizer non fallisce mai in silenzio: verificare il marcatore di motore nei metadati del risultato e monitorare l’evento di avviso.
• count non riporta mai un sidecar irraggiungibile o un errore di protocollo come 0; questi sollevano eccezioni tipizzate.
• Un hit di ricerca privo del proprio identificatore o punteggio assume come predefiniti una stringa vuota e 0.0 anziché far fallire il batch.
• Un top_k di 0 è usato internamente solo per la sonda di conteggio; passare un topK positivo per ricerche reali.
• La prima richiesta di embedding paga il costo una tantum di download e caricamento del modello; dimensionare tale timeout separatamente.
• La gerarchia delle eccezioni del sidecar e le famiglie di codici di errore sono catalogate nel riferimento agli errori di Accelerator.
• Questo modulo non esegue alcuna operazione crittografica e non definisce alcun comportamento specifico per FIPS. La postura in modalità FIPS è governata dai moduli di firma e compliance, non qui.

Conformità

Accelerator delega il lavoro che incide sul formato ai moduli Optimizer e Diff e non asserisce alcuna conformità di formato indipendente. La conformità per il lavoro delegato è documentata nelle pagine di riferimento di Optimizer e Diff. Questa pagina non dichiara alcun identificatore di clausola esterno; ogni affermazione è fondata sul codice sorgente del prodotto. NextPDF non avanza alcuna dichiarazione di certificazione.

Note di sviluppo

• Il codice sorgente del modulo riporta @since 2.1.0; questo riferimento documenta la superficie come distribuita in nextpdf/pro 3.1.0.
• Tutte le classi sono final e usano l’iniezione tramite costruttore; costruire nuove istanze anziché mutare.
• SpectrumClient, VectorSearchResult, BatchResultInterface e i contratti EmbeddingServiceInterface e VectorIndexInterface provengono da NextPDF Core; il chiamante costruisce e fornisce il client di sidecar.
• OptimizationLevel, PdfOptimizer e PdfDiffer provengono dai moduli Optimizer e Diff di Pro; la loro semantica è documentata in quelle pagine di riferimento.
• Il servizio di embedding e l’indice vettoriale condividono la dimensione 384. Costruire i vettori dell’indice alla stessa dimensione degli embedding che li interrogano.
• I dettagli di meccanismo interni restano nella documentazione interna del repository sorgente e sono fuori ambito per questo manuale.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile esternamente e la superficie API pubblica supportata. I percorsi di namespace interni, le classi di supporto, le tabelle dei meccanismi, i nomi dei file dei runbook e i prefissi dei ticket sono fuori ambito.

Vedere anche

• Accelerator — la pagina della funzionalità per indicazioni sul flusso di lavoro.
• Riferimento agli errori di Accelerator — gerarchia delle eccezioni del sidecar e codici di errore.
• Optimizer — Riferimento approfondito
• Diff — Riferimento approfondito
• Accelerator — Riferimento approfondito NextPDF Enterprise