Accelerator — Référence approfondie (sidecar GPU, fabrique de fournisseurs KMS)

En bref

Cette page constitue la référence approfondie de la surface d’accélération publique de NextPDF\Enterprise\Accelerator. Elle couvre la pile de fournisseurs KMS — la fabrique, le contrat de fournisseur, le fournisseur local et le résultat de métadonnées de clé — ainsi que les services du sidecar GPU pour l’embedding et la recherche vectorielle. Elle précise les paramètres, les valeurs par défaut, les modes de défaillance et la posture de garde des clés. Lis d’abord la page de capacité Accelerator pour des conseils sur les workflows. Les autres symboles du même namespace relèvent d’autres capacités et sortent du périmètre de cette page.

Disponibilité et licence

Cette capacité est livrée dans NextPDF Enterprise (nextpdf/enterprise) et s’active avec une enveloppe de licence de niveau Enterprise. Un déploiement dépourvu de ce droit ne charge pas les classes de la capacité. Compare les éditions et obtiens une licence.

Le fournisseur KMS est sélectionné à l’exécution ; le code appelant dépend du contrat de fournisseur, non du fournisseur concret. Les services d’embedding et d’index vectoriel implémentent les contrats Core EmbeddingServiceInterface et VectorIndexInterface.

Surface d’API publique

composer require nextpdf/enterprise:^3

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
KmsProviderFactory::fromEnvironment	aucun	Construit le fournisseur nommé par la variable de sélection ; non définie ou vide sélectionne local	KmsProviderInterface	RuntimeException en cas de clé maître manquante, de fournisseur cloud indisponible ou de nom inconnu	Point d’entrée statique
KmsProviderFactory::create	string $providerType, array $config = []	Construit le fournisseur nommé à partir d’une configuration explicite	KmsProviderInterface	RuntimeException lorsque local ne possède pas de encryption_key non vide, ou en cas de nom inconnu	local est le seul nom constructible dans cette version
KmsProviderInterface::getEncryptionKey	string $collectionId	Retourne les métadonnées de clé actuelles de la collection	EncryptionKeyResult	RuntimeException lorsque le fournisseur est inaccessible ou mal configuré (contrat)	Métadonnées uniquement ; jamais les octets bruts de la clé
KmsProviderInterface::rotateKey	string $collectionId	Fait avancer la version de clé	EncryptionKeyResult	RuntimeException lorsque la rotation échoue (contrat)	La rotation est un signal de rechiffrement adressé à l’appelant
KmsProviderInterface::providerName	aucun	Indique le nom canonique du fournisseur	string	Rien de déclaré	local, aws, gcp, azure, vault
LocalKmsProvider::__construct	string $encryptionKey (sensible)	Valide une clé maître hexadécimale d’au moins 64 caractères hexadécimaux (32 octets)	LocalKmsProvider	InvalidArgumentException en cas de valeur trop courte ou non hexadécimale	Garde fail-fast ; n’effectue elle-même aucune dérivation
LocalKmsProvider::getEncryptionKey	string $collectionId	Émet local:{collectionId}:v{version} ; la version vaut 1 par défaut	EncryptionKeyResult	Rien de déclaré	Libellé d’algorithme AES-256-GCM
LocalKmsProvider::rotateKey	string $collectionId	Incrémente le compteur de version en mémoire du processus	EncryptionKeyResult	Rien de déclaré	L’état de version est propre à chaque instance
EncryptionKeyResult::__construct	string $keyId, int $keyVersion, string $algorithm = 'AES-256-GCM', string $provider = 'local'	Objet-valeur de métadonnées immuable	EncryptionKeyResult	Rien de déclaré	Ne transporte jamais de matériel de clé
GpuEmbeddingService::embed	string $text	Délègue à batchEmbed et retourne l’élément zéro	list<float>	Comme batchEmbed	Vecteur à 1024 dimensions
GpuEmbeddingService::batchEmbed	array $texts	Calcule l’embedding du lot sur le sidecar	list<list<float>>	InvalidArgumentException en cas de lot vide ; SpectrumNotAvailableException lorsque le sidecar est inaccessible ; SpectrumApiException en cas de réponse en échec, malformée ou dont le nombre ne correspond pas	Ne retourne jamais de résultats partiels
GpuEmbeddingService::getDimension	aucun	Retourne 1024	int	Rien de déclaré	Constant
GpuEmbeddingService::getModelName	aucun	Retourne multilingual-e5-large	string	Rien de déclaré	Constant
GpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Lie le handle à une seule collection	GpuVectorIndex	Rien de déclaré	Un handle par identifiant de collection
GpuVectorIndex::build	array $vectors, array $ids	Construit l’index de la collection sur le sidecar	void	InvalidArgumentException en cas de lot vide ou de longueurs discordantes ; SpectrumNotAvailableException en cas d’inaccessibilité ; SpectrumApiException en cas de réponse de construction inattendue	Une reconstruction remplace l’index
GpuVectorIndex::search	array $queryVector, int $topK = 10	Recherche des plus proches voisins classée	list<VectorSearchResult>	SpectrumNotAvailableException en cas d’inaccessibilité ; JsonException en cas de corps de réponse malformé	Rang par résultat dans les métadonnées
GpuVectorIndex::delete	array $ids	Rejette toujours	void (déclaré)	Toujours : SpectrumApiException (non implémenté)	L’index construit est immuable ; reconstruis-le à la place
GpuVectorIndex::count	aucun	Lit le total de la collection depuis le sidecar	int	Ne lève rien ; toute défaillance retourne 0	0 est ambigu : vide ou inaccessible

Signatures des points d’entrée

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
}

Surface de configuration

Réglage	Consommateur	Signification
SPECTRUM_KMS_PROVIDER	fromEnvironment()	Sélecteur de fournisseur. Non défini ou vide se résout en local.
SPECTRUM_ENCRYPTION_KEY	Le chemin du fournisseur local	Clé maître encodée en hexadécimal ; au moins 64 caractères hexadécimaux (32 octets). Partagée avec le sidecar.
encryption_key	create('local', [...])	Clé maître explicite ; même format et même validation.

Contrat de comportement

Sélection du fournisseur

KmsProviderFactory::fromEnvironment lit la variable de sélection et retombe par défaut sur local. Les noms de fournisseurs cloud aws, gcp, azure et vault sont reconnus mais non constructibles dans cette version. Sélectionner aws lève une erreur typée nommant le paquet requis aws/aws-sdk-php ; les trois autres signalent l’intégration comme non implémentée. Un nom inconnu lève une erreur typée énumérant les noms pris en charge. KmsProviderFactory::create accepte un nom de fournisseur explicite et une carte de configuration ; local est le seul nom qu’elle construit.

Métadonnées et garde des clés

Un fournisseur retourne des métadonnées de clé immuables : un identifiant de clé, une version de clé croissant de façon monotone, le libellé d’algorithme et le nom du fournisseur. Il ne retourne jamais les octets bruts de la clé, de sorte qu’une fuite de métadonnées n’expose aucun matériel de clé. Le fournisseur local partage les responsabilités avec le sidecar de l’accélérateur. La classe PHP valide le secret maître à la construction et émet une identité de clé stable et propre à la collection, de la forme local:{collectionId}:v{version}. Le sidecar effectue la dérivation HKDF-SHA256 et le chiffrement AES-256-GCM, en dérivant une clé de chiffrement de données distincte de 32 octets par collection, avec l’identifiant de collection et la version comme séparation de domaine. Les deux côtés lisent le même secret maître configuré. Aucun service KMS externe n’est contacté ; la gestion des clés reste à l’intérieur du déploiement. Le modèle de version et de cycle de vie des clés suit NIST SP 800-57 Part 1 Rev.5 §4.

Un appel de rotation fait avancer la version de clé et retourne les nouvelles métadonnées. L’appelant rechiffre les données de la collection avec la nouvelle version ; le fournisseur ne rechiffre rien lui-même.

La sécurité des clés dépend du KMS ou du secret de clé maître, du déploiement et de l’opérateur — et non de NextPDF Enterprise seul. L’opérateur est responsable du provisionnement de la clé maître, du stockage des secrets, de la configuration du KMS et de la planification des rotations. La responsabilité de protection des clés suit NIST SP 800-57 Part 1 Rev.5 §5.5.2.

Embedding GPU

GpuEmbeddingService implémente le contrat d’embedding Core et délègue au sidecar. Le sidecar exécute le modèle d’embedding sur un GPU lorsqu’il en existe un et retombe sinon sur le CPU, en marquant les métadonnées de réponse comme dégradées par rapport au GPU. La forme du vecteur est identique dans les deux cas. Le modèle (environ 1.3 GB) est téléchargé et chargé de façon paresseuse à la première requête. La sémantique de lot est du tout-ou-rien : une défaillance sur un élément, un vecteur malformé ou un nombre discordant lève une erreur typée au lieu de retourner des résultats partiels.

Recherche vectorielle GPU

GpuVectorIndex implémente le contrat d’index vectoriel Core et lie un handle à un unique identifiant de collection. build construit l’index sur le sidecar ; le sidecar utilise un index GPU lorsqu’il en existe un et un index CPU sinon. L’index est immuable une fois construit : delete rejette toujours avec une erreur typée « non implémenté », et toute suppression nécessite une reconstruction. search retourne des résultats classés avec un rang commençant à un dans les métadonnées de chaque résultat. count demande au sidecar le total de la collection et signale 0 en cas de défaillance plutôt que de lever une erreur.

Cas limites et modes de défaillance

• La clé maître doit se décoder depuis l’hexadécimal en au moins 32 octets. Une valeur plus courte ou non hexadécimale lève InvalidArgumentException à la construction, avant tout appel au sidecar.
• Une variable de sélection non définie ou vide se résout en local ; la fabrique ne devine jamais un autre fournisseur.
• fromEnvironment sur le chemin local sans la variable de clé maître lève une erreur typée nommant la variable manquante.
• create('local', [...]) sans entrée encryption_key non vide lève une erreur typée nommant l’entrée manquante.
• L’état de version de clé est en mémoire du processus et propre à chaque instance de fournisseur. Un nouveau processus observe la version 1 jusqu’à ce qu’une rotation soit de nouveau exécutée. Rends persistants les résultats de rotation en rechiffrant les données, non en te fiant à l’état du fournisseur.
• Un lot d’embedding vide lève InvalidArgumentException ; le sidecar n’est pas contacté.
• La disponibilité du sidecar est sondée à chaque appel. Un sidecar inaccessible lève SpectrumNotAvailableException ; les services n’échouent jamais en silence.
• Un composant non numérique à l’intérieur d’un vecteur d’embedding retourné est converti en 0.0 ; un vecteur manquant ou n’étant pas un tableau lève SpectrumApiException.
• La première requête d’embedding paie le coût unique de téléchargement et de chargement du modèle ; dimensionne ce délai d’expiration séparément.
• build et search décodent strictement la réponse du sidecar ; un corps malformé lève JsonException. count absorbe toute défaillance et retourne 0.
• Un résultat de recherche dépourvu de son identifiant ou de son score prend par défaut une chaîne vide et 0.0 plutôt que de faire échouer le lot.
• Les codes d’erreur du sidecar et la hiérarchie d’exceptions sont catalogués dans la référence des erreurs Accelerator.

Comportement en mode FIPS

Le chemin de clé local utilise HKDF-SHA256 pour la dérivation et AES-256-GCM pour le chiffrement ; le sidecar exécute les deux. Le libellé d’algorithme enregistré dans les métadonnées de clé est AES-256-GCM. Lorsque le déploiement s’appuie sur un fournisseur cryptographique validé FIPS, ces primitives s’exécutent dans cette frontière validée. L’usage d’AES-GCM requiert un vecteur d’initialisation unique par clé, conformément à NIST SP 800-38D §5.

NextPDF Enterprise n’est pas un module cryptographique validé FIPS et ne revendique aucune certification FIPS. Il fonctionne dans un mode compatible FIPS uniquement lorsqu’il est configuré avec un fournisseur cryptographique validé FIPS ou un KMS validé FIPS. Aucun artefact de certification FIPS n’existe dans ce dépôt.

Conformité

Affirmation	Norme	Clause
Le modèle de version et de cycle de vie des clés suit les recommandations sur les états de clé.	NIST SP 800-57 Part 1 Rev.5	§4
La responsabilité de protection et de garde des clés incombe au propriétaire de la clé et à l’opérateur.	NIST SP 800-57 Part 1 Rev.5	§5.5.2
AES-GCM requiert un vecteur d’initialisation unique par clé.	NIST SP 800-38D	§5

Toutes les clauses sont paraphrasées ; NextPDF ne reproduit aucun texte normatif. NextPDF ne revendique aucune certification. L’alignement sur les clauses citées est une déclaration de capacité, non une certification. Cette page concerne la gestion des clés ; la déclaration sur le mode FIPS est une déclaration de compatibilité, non un avis juridique. Consulte tes propres conseillers en conformité et en droit.

Notes de développement

• Le code source du module porte @since 2.1.0 ; cette référence documente la surface telle qu’elle est livrée dans nextpdf/enterprise 3.1.0.
• Toutes les classes sont final ; EncryptionKeyResult est final readonly. Construis de nouvelles instances au lieu de muter.
• La clé maître est un paramètre de constructeur sensible (#[SensitiveParameter]) ; PHP la masque dans les traces de pile. Tiens-la à l’écart des journaux applicatifs et des vidages de configuration.
• SpectrumClient, VectorSearchResult, ainsi que les contrats EmbeddingServiceInterface et VectorIndexInterface proviennent de NextPDF Core ; l’appelant construit et fournit le client du sidecar.
• Le namespace NextPDF\Enterprise\Accelerator porte également des moteurs de délestage par lot ainsi que les piles de collections de récupération et d’extraction OCR ; ces surfaces sortent du périmètre de cette page.
• Les détails de mécanisme interne restent dans la documentation interne du dépôt source et sortent du périmètre de ce manuel.

Limite de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins de namespace internes, les classes utilitaires, les tables de mécanisme, les noms de fichiers de runbook et les préfixes de ticket sortent du périmètre.

Voir aussi

• Accelerator — sidecar GPU et fabrique de fournisseurs KMS — la page de capacité pour les conseils sur les workflows et la garde des clés.
• Référence des erreurs Accelerator — hiérarchie d’exceptions du sidecar et codes d’erreur.
• Security — Référence approfondie
• Accelerator — Référence approfondie NextPDF Pro