Accelerator — Riferimento approfondito (sidecar GPU, factory di provider KMS)

In sintesi

Questa pagina è il riferimento approfondito per la superficie di accelerazione pubblica di NextPDF\Enterprise\Accelerator. Copre lo stack dei provider KMS — la factory, il contratto del provider, il provider locale e il risultato dei metadati della chiave — e i servizi sidecar GPU per l’embedding e la ricerca vettoriale. Indica parametri, valori predefiniti, modalità di errore e la posizione sulla custodia delle chiavi. Leggere prima la pagina della funzionalità Accelerator per le indicazioni sul flusso di lavoro. Gli altri simboli nello stesso namespace appartengono ad altre funzionalità e sono fuori dall’ambito di questa pagina.

Disponibilità e licenze

Questa funzionalità è inclusa in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di tier Enterprise. Una distribuzione priva di tale entitlement non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Il provider KMS viene selezionato in fase di esecuzione; il codice chiamante dipende dal contratto del provider, non dal provider concreto. I servizi di embedding e di indice vettoriale implementano i contratti Core EmbeddingServiceInterface e VectorIndexInterface.

Superficie API pubblica

composer require nextpdf/enterprise:^3

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
KmsProviderFactory::fromEnvironment	nessuno	Costruisce il provider indicato dalla variabile selettore; se non impostata o vuota seleziona local	KmsProviderInterface	RuntimeException in caso di chiave root mancante, provider cloud non disponibile o nome sconosciuto	Punto di ingresso statico
KmsProviderFactory::create	string $providerType, array $config = []	Costruisce il provider indicato dalla configurazione esplicita	KmsProviderInterface	RuntimeException quando local non ha un encryption_key non vuoto, o in caso di nome sconosciuto	local è l’unico nome costruibile in questa release
KmsProviderInterface::getEncryptionKey	string $collectionId	Restituisce i metadati correnti della chiave per la collezione	EncryptionKeyResult	RuntimeException quando il provider non è raggiungibile o è configurato male (contratto)	Solo metadati; mai i byte grezzi della chiave
KmsProviderInterface::rotateKey	string $collectionId	Fa avanzare la versione della chiave	EncryptionKeyResult	RuntimeException quando la rotazione fallisce (contratto)	La rotazione è un segnale di ri-cifratura per il chiamante
KmsProviderInterface::providerName	nessuno	Riporta il nome canonico del provider	string	Nulla dichiarato	local, aws, gcp, azure, vault
LocalKmsProvider::__construct	string $encryptionKey (sensibile)	Convalida una chiave root esadecimale di almeno 64 caratteri esadecimali (32 byte)	LocalKmsProvider	InvalidArgumentException in caso di valore corto o non esadecimale	Guardia fail-fast; non esegue essa stessa alcuna derivazione
LocalKmsProvider::getEncryptionKey	string $collectionId	Genera local:{collectionId}:v{version}; la versione predefinita è 1	EncryptionKeyResult	Nulla dichiarato	Etichetta dell’algoritmo AES-256-GCM
LocalKmsProvider::rotateKey	string $collectionId	Incrementa il contatore di versione in-process	EncryptionKeyResult	Nulla dichiarato	Lo stato della versione è per istanza
EncryptionKeyResult::__construct	string $keyId, int $keyVersion, string $algorithm = 'AES-256-GCM', string $provider = 'local'	Value object di metadati immutabile	EncryptionKeyResult	Nulla dichiarato	Non trasporta mai materiale di chiave
GpuEmbeddingService::embed	string $text	Delega a batchEmbed e restituisce l’elemento zero	list<float>	Come batchEmbed	Vettore a 1024 dimensioni
GpuEmbeddingService::batchEmbed	array $texts	Esegue l’embedding del batch sul sidecar	list<list<float>>	InvalidArgumentException in caso di batch vuoto; SpectrumNotAvailableException quando il sidecar non è raggiungibile; SpectrumApiException in caso di risposta fallita, malformata o con conteggio non corrispondente	Non restituisce mai risultati parziali
GpuEmbeddingService::getDimension	nessuno	Restituisce 1024	int	Nulla dichiarato	Costante
GpuEmbeddingService::getModelName	nessuno	Restituisce multilingual-e5-large	string	Nulla dichiarato	Costante
GpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Associa l’handle a una sola collezione	GpuVectorIndex	Nulla dichiarato	Un handle per identificatore di collezione
GpuVectorIndex::build	array $vectors, array $ids	Costruisce l’indice della collezione sul sidecar	void	InvalidArgumentException in caso di batch vuoto o lunghezza non corrispondente; SpectrumNotAvailableException quando non è raggiungibile; SpectrumApiException in caso di risposta di build inattesa	Una ricostruzione sostituisce l’indice
GpuVectorIndex::search	array $queryVector, int $topK = 10	Ricerca dei vicini più prossimi con classificazione	list<VectorSearchResult>	SpectrumNotAvailableException quando non è raggiungibile; JsonException in caso di corpo della risposta malformato	Rango per singolo hit nei metadati del risultato
GpuVectorIndex::delete	array $ids	Rifiuta sempre	void (dichiarato)	Sempre: SpectrumApiException (non implementato)	L’indice costruito è immutabile; ricostruire invece
GpuVectorIndex::count	nessuno	Legge il totale della collezione dal sidecar	int	Non solleva eccezioni; qualsiasi fallimento restituisce 0	0 è ambiguo: vuoto o non raggiungibile

Firme dei punti di ingresso

final class KmsProviderFactory
{
    public static function fromEnvironment(): KmsProviderInterface

    public static function create(string $providerType, array $config = []): KmsProviderInterface
}

interface KmsProviderInterface
{
    public function getEncryptionKey(string $collectionId): EncryptionKeyResult;

    public function rotateKey(string $collectionId): EncryptionKeyResult;

    public function providerName(): string;
}

final class LocalKmsProvider implements KmsProviderInterface
{
    public function __construct(
        #[SensitiveParameter]
        private readonly string $encryptionKey,
    )
}

final readonly class EncryptionKeyResult
{
    public function __construct(
        public string $keyId,
        public int $keyVersion,
        public string $algorithm = 'AES-256-GCM',
        public string $provider = 'local',
    )
}

final class GpuEmbeddingService 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 GpuVectorIndex implements VectorIndexInterface
{
    public function __construct(
        private readonly SpectrumClient $client,
        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
}

Superficie di configurazione

Impostazione	Consumatore	Significato
SPECTRUM_KMS_PROVIDER	fromEnvironment()	Selettore del provider. Se non impostata o vuota si risolve in local.
SPECTRUM_ENCRYPTION_KEY	Il percorso del provider local	Chiave root codificata in esadecimale; almeno 64 caratteri esadecimali (32 byte). Condivisa con il sidecar.
encryption_key	create('local', [...])	Chiave root esplicita; stesso formato e stessa convalida.

Contratto di comportamento

Selezione del provider

KmsProviderFactory::fromEnvironment legge la variabile selettore e per impostazione predefinita usa local. I nomi dei provider cloud aws, gcp, azure e vault sono riconosciuti ma non costruibili in questa release. Selezionare aws solleva un errore tipizzato che nomina il pacchetto aws/aws-sdk-php richiesto; gli altri tre segnalano l’integrazione come non implementata. Un nome sconosciuto solleva un errore tipizzato che elenca i nomi supportati. KmsProviderFactory::create accetta un nome di provider esplicito e una mappa di configurazione; local è l’unico nome che costruisce.

Metadati e custodia delle chiavi

Un provider restituisce metadati immutabili della chiave: un identificatore della chiave, una versione della chiave monotonicamente crescente, l’etichetta dell’algoritmo e il nome del provider. Non restituisce mai i byte grezzi della chiave, perciò una fuga di metadati non espone il materiale di chiave. Il provider locale divide i compiti con il sidecar dell’accelerator. La classe PHP convalida il segreto root in fase di costruzione e genera un’identità di chiave stabile e con ambito di collezione nella forma local:{collectionId}:v{version}. Il sidecar esegue la derivazione HKDF-SHA256 e la cifratura AES-256-GCM, derivando una distinta chiave di cifratura dei dati di 32 byte per ciascuna collezione, usando l’identificatore della collezione e la versione come separazione di dominio. Entrambi i lati leggono lo stesso segreto root configurato. Non viene contattato alcun servizio KMS esterno; la gestione delle chiavi resta all’interno della distribuzione. Il modello di versione e ciclo di vita delle chiavi segue NIST SP 800-57 Part 1 Rev.5 §4.

Una chiamata di rotazione fa avanzare la versione della chiave e restituisce i nuovi metadati. Il chiamante ri-cifra i dati della collezione con la nuova versione; il provider non ri-cifra nulla da sé.

La sicurezza delle chiavi dipende dal KMS o dal segreto della chiave root, dalla distribuzione e dall’operatore — non da NextPDF Enterprise da solo. L’operatore possiede il provisioning della chiave root, l’archiviazione dei segreti, la configurazione del KMS e la pianificazione della rotazione. La responsabilità di protezione delle chiavi segue NIST SP 800-57 Part 1 Rev.5 §5.5.2.

Embedding su GPU

GpuEmbeddingService implementa il contratto di embedding di Core e delega al sidecar. Il sidecar esegue il modello di embedding su una GPU quando disponibile e altrimenti ricorre alla CPU, segnalando nei metadati della risposta una modalità degradata rispetto alla GPU. La forma del vettore è identica in entrambi i casi. Il modello (circa 1,3 GB) viene scaricato e caricato in modo lazy alla prima richiesta. La semantica del batch è tutto-o-niente: un fallimento su un singolo elemento, un vettore malformato o un conteggio non corrispondente solleva un errore tipizzato anziché restituire risultati parziali.

Ricerca vettoriale su GPU

GpuVectorIndex implementa il contratto di indice vettoriale di Core e associa un handle a un solo identificatore di collezione. build costruisce l’indice sul sidecar; il sidecar usa un indice GPU quando disponibile e altrimenti un indice CPU. L’indice è immutabile una volta costruito: delete rifiuta sempre con un errore tipizzato di non implementato e la rimozione richiede una ricostruzione. search restituisce hit classificati con un rango a base uno nei metadati di ciascun risultato. count chiede al sidecar il totale della collezione e in caso di qualsiasi fallimento riporta 0 anziché sollevare un’eccezione.

Casi limite e modalità di errore

• La chiave root deve decodificarsi da esadecimale ad almeno 32 byte. Un valore più corto o non esadecimale solleva InvalidArgumentException in fase di costruzione, prima di qualsiasi chiamata al sidecar.
• Una variabile selettore non impostata o vuota si risolve in local; la factory non indovina mai un altro provider.
• fromEnvironment sul percorso local senza la variabile della chiave root solleva un errore tipizzato che nomina la variabile mancante.
• create('local', [...]) senza una voce encryption_key non vuota solleva un errore tipizzato che nomina la voce mancante.
• Lo stato della versione della chiave è in-process e per istanza del provider. Un nuovo processo osserva la versione 1 finché la rotazione non viene eseguita di nuovo. Rendere persistenti gli esiti della rotazione ri-cifrando i dati, non affidandosi allo stato del provider.
• Un batch di embedding vuoto solleva InvalidArgumentException; il sidecar non viene contattato.
• La disponibilità del sidecar viene verificata a ogni chiamata. Un sidecar non raggiungibile solleva SpectrumNotAvailableException; i servizi non falliscono mai silenziosamente.
• Una componente non numerica all’interno di un vettore di embedding restituito viene forzata a 0.0; un vettore mancante o non di tipo array solleva SpectrumApiException.
• La prima richiesta di embedding paga il costo una tantum di download e caricamento del modello; dimensionare tale timeout separatamente.
• build e search decodificano la risposta del sidecar in modo rigoroso; un corpo malformato solleva JsonException. count assorbe ogni fallimento e restituisce 0.
• Un hit di ricerca privo del proprio identificatore o punteggio assume come predefinito una stringa vuota e 0.0 anziché far fallire il batch.
• I codici di errore del sidecar e la gerarchia delle eccezioni sono catalogati nel riferimento agli errori di Accelerator.

Comportamento in modalità FIPS

Il percorso della chiave locale usa HKDF-SHA256 per la derivazione e AES-256-GCM per la cifratura; il sidecar esegue entrambi. L’etichetta dell’algoritmo registrata nei metadati della chiave è AES-256-GCM. Quando la distribuzione viene eseguita rispetto a un provider crittografico convalidato FIPS, tali primitive vengono eseguite all’interno di quel confine convalidato. L’uso di AES-GCM richiede un vettore di inizializzazione univoco per ciascuna chiave, secondo NIST SP 800-38D §5.

NextPDF Enterprise non è un modulo crittografico convalidato FIPS e non avanza alcuna rivendicazione di certificazione FIPS. Opera in una modalità compatibile con FIPS solo quando è configurato con un provider crittografico convalidato FIPS o con un KMS convalidato FIPS. In questo repository non esiste alcun artefatto di certificazione FIPS.

Conformità

Dichiarazione	Standard	Clausola
Il modello di versione e ciclo di vita delle chiavi segue le indicazioni sullo stato delle chiavi.	NIST SP 800-57 Part 1 Rev.5	§4
La responsabilità di protezione e custodia delle chiavi spetta al proprietario delle chiavi e all’operatore.	NIST SP 800-57 Part 1 Rev.5	§5.5.2
AES-GCM richiede un vettore di inizializzazione univoco per ciascuna chiave.	NIST SP 800-38D	§5

Tutte le clausole sono parafrasate; NextPDF non riproduce il testo normativo. NextPDF non avanza alcuna rivendicazione di certificazione. L’allineamento con le clausole citate è una dichiarazione di capacità, non una certificazione. Questa pagina riguarda la gestione delle chiavi; la dichiarazione sulla modalità FIPS è una dichiarazione di compatibilità, non un parere legale. Consultare i propri consulenti di conformità e legali.

Note di sviluppo

• Il sorgente del modulo riporta @since 2.1.0; questo riferimento documenta la superficie così come rilasciata in nextpdf/enterprise 3.1.0.
• Tutte le classi sono final; EncryptionKeyResult è final readonly. Costruire nuove istanze anziché mutare.
• La chiave root è un parametro del costruttore sensibile (#[SensitiveParameter]); PHP la oscura dagli stack trace. Tenerla fuori dai log dell’applicazione e dai dump di configurazione.
• SpectrumClient, VectorSearchResult e i contratti EmbeddingServiceInterface e VectorIndexInterface provengono da NextPDF Core; il chiamante costruisce e fornisce il client del sidecar.
• Il namespace NextPDF\Enterprise\Accelerator include anche motori di offload in batch e gli stack di collezione di retrieval e di estrazione OCR; tali superfici sono fuori dall’ambito di questa pagina.
• I dettagli sui meccanismi interni rimangono nella documentazione interna del repository sorgente e sono fuori ambito per questo manuale.

Confine di pubblicazione

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

Vedere anche

• Accelerator — sidecar GPU e factory di provider KMS — la pagina della funzionalità per le indicazioni su flusso di lavoro e custodia.
• Riferimento agli errori di Accelerator — gerarchia delle eccezioni del sidecar e codici di errore.
• Security — Riferimento approfondito
• Accelerator — Riferimento approfondito NextPDF Pro