Accelerator — Diepe referentie (GPU-sidecar, KMS-providerfactory)

In het kort

Deze pagina is de uitgebreide referentie voor het publieke versnellingsoppervlak van NextPDF\Enterprise\Accelerator. Ze behandelt de KMS-providerstack — de factory, het providercontract, de lokale provider en het sleutelmetadata-resultaat — en de GPU-sidecar-diensten voor embedding en vector-zoeken. Ze vermeldt parameters, standaardwaarden, faalmodi en de houding rond sleutelbewaring. Lees eerst de Accelerator-capabilitypagina voor werkstroomrichtlijnen. Andere symbolen in dezelfde namespace horen bij andere capabilities en vallen buiten de scope van deze pagina.

Beschikbaarheid & licenties

Deze capability wordt geleverd in NextPDF Enterprise (nextpdf/enterprise) en wordt geactiveerd met een licentie-envelop op Enterprise-niveau. Een implementatie zonder die rechten laadt de klassen van de capability niet. Vergelijk edities en verkrijg een licentie.

De KMS-provider wordt tijdens runtime geselecteerd; de aanroepende code hangt af van het providercontract, niet van de concrete provider. De embedding- en vector-index-diensten implementeren de Core-contracten EmbeddingServiceInterface en VectorIndexInterface.

Publiek API-oppervlak

composer require nextpdf/enterprise:^3

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of faalt met	Opmerkingen
KmsProviderFactory::fromEnvironment	geen	Bouwt de provider die door de selectorvariabele wordt genoemd; niet-ingesteld of leeg selecteert local	KmsProviderInterface	RuntimeException bij een ontbrekende mastersleutel, een niet-beschikbare cloudprovider of een onbekende naam	Statisch instappunt
KmsProviderFactory::create	string $providerType, array $config = []	Bouwt de genoemde provider vanuit expliciete configuratie	KmsProviderInterface	RuntimeException wanneer local geen niet-lege encryption_key heeft, of bij een onbekende naam	local is de enige construeerbare naam in deze release
KmsProviderInterface::getEncryptionKey	string $collectionId	Retourneert de huidige sleutelmetadata voor de collectie	EncryptionKeyResult	RuntimeException wanneer de provider onbereikbaar of verkeerd geconfigureerd is (contract)	Alleen metadata; nooit ruwe sleutelbytes
KmsProviderInterface::rotateKey	string $collectionId	Verhoogt de sleutelversie	EncryptionKeyResult	RuntimeException wanneer rotatie mislukt (contract)	Rotatie is een hersleutelingssignaal aan de caller
KmsProviderInterface::providerName	geen	Rapporteert de canonieke providernaam	string	Niets gedeclareerd	local, aws, gcp, azure, vault
LocalKmsProvider::__construct	string $encryptionKey (gevoelig)	Valideert een hex-mastersleutel van ten minste 64 hex-tekens (32 bytes)	LocalKmsProvider	InvalidArgumentException bij een te korte of niet-hex-waarde	Fail-fast-bewaking; voert zelf geen afleiding uit
LocalKmsProvider::getEncryptionKey	string $collectionId	Genereert local:{collectionId}:v{version}; versie is standaard 1	EncryptionKeyResult	Niets gedeclareerd	Algoritmelabel AES-256-GCM
LocalKmsProvider::rotateKey	string $collectionId	Verhoogt de in-process versieteller	EncryptionKeyResult	Niets gedeclareerd	Versiestatus is per instantie
EncryptionKeyResult::__construct	string $keyId, int $keyVersion, string $algorithm = 'AES-256-GCM', string $provider = 'local'	Onveranderlijk metadata value object	EncryptionKeyResult	Niets gedeclareerd	Draagt nooit sleutelmateriaal
GpuEmbeddingService::embed	string $text	Delegeert naar batchEmbed en retourneert element nul	list<float>	Zoals batchEmbed	Vector met 1024 dimensies
GpuEmbeddingService::batchEmbed	array $texts	Embedt de batch op de sidecar	list<list<float>>	InvalidArgumentException bij een lege batch; SpectrumNotAvailableException wanneer de sidecar onbereikbaar is; SpectrumApiException bij een mislukte, misvormde of qua aantal niet-overeenkomende respons	Retourneert nooit gedeeltelijke resultaten
GpuEmbeddingService::getDimension	geen	Retourneert 1024	int	Niets gedeclareerd	Constante
GpuEmbeddingService::getModelName	geen	Retourneert multilingual-e5-large	string	Niets gedeclareerd	Constante
GpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Bindt de handle aan één collectie	GpuVectorIndex	Niets gedeclareerd	Eén handle per collectie-identificatie
GpuVectorIndex::build	array $vectors, array $ids	Bouwt de collectie-index op de sidecar	void	InvalidArgumentException bij een lege batch of een lengteverschil; SpectrumNotAvailableException wanneer onbereikbaar; SpectrumApiException bij een onverwachte build-respons	Een herbouw vervangt de index
GpuVectorIndex::search	array $queryVector, int $topK = 10	Gerangschikte nearest-neighbor-zoekopdracht	list<VectorSearchResult>	SpectrumNotAvailableException wanneer onbereikbaar; JsonException bij een misvormde responsbody	Rang per hit in de resultaatmetadata
GpuVectorIndex::delete	array $ids	Weigert altijd	void (gedeclareerd)	Altijd: SpectrumApiException (niet geïmplementeerd)	De gebouwde index is onveranderlijk; herbouw in plaats daarvan
GpuVectorIndex::count	geen	Leest het collectietotaal van de sidecar	int	Werpt niet; elke fout retourneert 0	0 is dubbelzinnig: leeg of onbereikbaar

Instappunt-signaturen

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
}

Configuratie-oppervlak

Instelling	Consument	Betekenis
SPECTRUM_KMS_PROVIDER	fromEnvironment()	Providerselector. Niet-ingesteld of leeg wordt local.
SPECTRUM_ENCRYPTION_KEY	Het local-providerpad	Hex-gecodeerde mastersleutel; ten minste 64 hex-tekens (32 bytes). Gedeeld met de sidecar.
encryption_key	create('local', [...])	Expliciete mastersleutel; zelfde formaat en validatie.

Gedragscontract

Providerselectie

KmsProviderFactory::fromEnvironment leest de selectorvariabele en valt standaard terug op local. De cloudprovidernamen aws, gcp, azure en vault worden herkend maar zijn in deze release niet construeerbaar. aws selecteren werpt een getypeerde fout die het vereiste aws/aws-sdk-php-pakket benoemt; de andere drie rapporteren de integratie als niet-geïmplementeerd. Een onbekende naam werpt een getypeerde fout die de ondersteunde namen opsomt. KmsProviderFactory::create accepteert een expliciete providernaam en een configuratiemap; local is de enige naam die het construeert.

Sleutelmetadata en bewaring

Een provider retourneert onveranderlijke sleutelmetadata: een sleutel-identifier, een monotoon stijgende sleutelversie, het algoritmelabel en de providernaam. Hij retourneert nooit ruwe sleutelbytes, zodat een metadata-lek geen sleutelmateriaal blootstelt. De lokale provider verdeelt de taken met de accelerator-sidecar. De PHP-klasse valideert het root-secret bij constructie en genereert een stabiele, collectiespecifieke sleutelidentiteit van de vorm local:{collectionId}:v{version}. De sidecar voert de HKDF-SHA256-afleiding en de AES-256-GCM-versleuteling uit, en leidt per collectie een aparte data-encryptiesleutel van 32 bytes af met de collectie-identificatie en de versie als domeinscheiding. Beide zijden lezen hetzelfde geconfigureerde root-secret. Er wordt geen externe KMS-service gecontacteerd; sleutelafhandeling blijft binnen de implementatie. De sleutelversie en het levenscyclusmodel volgen NIST SP 800-57 Part 1 Rev.5 §4.

Een rotatie-aanroep verhoogt de sleutelversie en retourneert de nieuwe metadata. De caller versleutelt de collectiegegevens opnieuw met de nieuwe versie; de provider versleutelt zelf niets opnieuw.

Sleutelbeveiliging hangt af van de KMS of het root-secret, van de implementatie en van de operator — niet van NextPDF Enterprise alleen. De operator is eigenaar van de mastersleutel-provisioning, de secret-opslag, de KMS-configuratie en de rotatieplanning. De verantwoordelijkheid voor sleutelbescherming volgt NIST SP 800-57 Part 1 Rev.5 §5.5.2.

GPU-embedding

GpuEmbeddingService implementeert het Core-embedding-contract en delegeert naar de sidecar. De sidecar draait het embeddingmodel op een GPU wanneer er een beschikbaar is en valt anders terug op de CPU, waarbij hij de responsmetadata markeert als gedegradeerd ten opzichte van GPU. De vectorvorm is in beide gevallen identiek. Het model (ongeveer 1,3 GB) wordt bij het eerste request lazy gedownload en geladen. De batchsemantiek is alles-of-niets: een fout per item, een misvormde vector of een niet-overeenkomend aantal werpt een getypeerde fout in plaats van gedeeltelijke resultaten te retourneren.

GPU-vector-zoeken

GpuVectorIndex implementeert het Core-vector-index-contract en bindt één handle aan één collectie-identificatie. build construeert de index op de sidecar; de sidecar gebruikt een GPU-index wanneer er een beschikbaar is en anders een CPU-index. De index is onveranderlijk zodra hij gebouwd is: delete weigert altijd met een getypeerde niet-geïmplementeerd-fout, en verwijderen vereist een herbouw. search retourneert gerangschikte hits met een op één gebaseerde rang in de metadata van elk resultaat. count vraagt de sidecar naar het collectietotaal en rapporteert bij elke fout 0 in plaats van te werpen.

Randgevallen & faalmodi

• De mastersleutel moet van hex naar ten minste 32 bytes decoderen. Een kortere of niet-hex-waarde werpt bij constructie InvalidArgumentException, vóór enige sidecar-aanroep.
• Een niet-ingestelde of lege selectorvariabele wordt local; de factory raadt nooit een andere provider.
• fromEnvironment op het local-pad zonder de mastersleutelvariabele werpt een getypeerde fout die de ontbrekende variabele benoemt.
• create('local', [...]) zonder een niet-lege encryption_key-vermelding werpt een getypeerde fout die de ontbrekende vermelding benoemt.
• De sleutelversiestatus is in-process en per providerinstantie. Een nieuw proces ziet versie 1 totdat rotatie opnieuw draait. Bewaar rotatie-uitkomsten door gegevens opnieuw te versleutelen, niet door op de providerstatus te vertrouwen.
• Een lege embedding-batch werpt InvalidArgumentException; de sidecar wordt niet gecontacteerd.
• De beschikbaarheid van de sidecar wordt per aanroep gecontroleerd. Een onbereikbare sidecar werpt SpectrumNotAvailableException; de diensten falen nooit stilzwijgend.
• Een niet-numerieke component in een geretourneerde embedding-vector wordt naar 0.0 omgezet; een ontbrekende of niet-array-vector werpt SpectrumApiException.
• Het eerste embedding-request betaalt de eenmalige kosten voor het downloaden en laden van het model; dimensioneer die timeout afzonderlijk.
• build en search decoderen de sidecar-respons strikt; een misvormde body werpt JsonException. count slikt elke fout en retourneert 0.
• Een zoekhit zonder identifier of score krijgt standaard een lege string en 0.0 in plaats van de batch te laten falen.
• Sidecar-foutcodes en de exceptiehiërarchie zijn gecatalogiseerd in de Accelerator-foutreferentie.

FIPS-modusgedrag

Het lokale sleutelpad gebruikt HKDF-SHA256 voor afleiding en AES-256-GCM voor versleuteling; de sidecar voert beide uit. Het algoritmelabel dat in de sleutelmetadata wordt vastgelegd is AES-256-GCM. Wanneer de implementatie tegen een FIPS-gevalideerde cryptografische provider draait, draaien die primitieven binnen die gevalideerde grens. AES-GCM-gebruik vereist een unieke initialisatievector per sleutel, volgens NIST SP 800-38D §5.

NextPDF Enterprise is geen FIPS-gevalideerde cryptografische module en maakt geen FIPS-certificeringsclaim. Het werkt uitsluitend in een FIPS-compatibele modus wanneer het is geconfigureerd met een FIPS-gevalideerde cryptografische provider of een FIPS-gevalideerde KMS. In deze repository bestaat geen FIPS-certificeringsartefact.

Conformiteit

Claim	Standaard	Clausule
De sleutelversie en het levenscyclusmodel volgen de richtlijn voor sleutelstatussen.	NIST SP 800-57 Part 1 Rev.5	§4
De verantwoordelijkheid voor sleutelbescherming en -bewaring ligt bij de sleuteleigenaar en de operator.	NIST SP 800-57 Part 1 Rev.5	§5.5.2
AES-GCM vereist een unieke initialisatievector per sleutel.	NIST SP 800-38D	§5

Alle clausules zijn geparafraseerd; NextPDF reproduceert geen normatieve tekst. NextPDF maakt geen certificeringsclaim. Afstemming op de geciteerde clausules is een capability-verklaring, geen certificering. Deze pagina betreft sleutelbeheer; de FIPS-modusverklaring is een compatibiliteitsverklaring, geen juridisch advies. Raadpleeg je eigen compliance- en juridische adviseurs.

Ontwikkelnotities

• De modulebroncode draagt @since 2.1.0; deze referentie documenteert het oppervlak zoals geleverd in nextpdf/enterprise 3.1.0.
• Alle klassen zijn final; EncryptionKeyResult is final readonly. Construeer nieuwe instanties in plaats van te muteren.
• De mastersleutel is een gevoelige constructorparameter (#[SensitiveParameter]); PHP verwijdert hem uit stacktraces. Houd hem uit applicatielogs en configuratiedumps.
• SpectrumClient, VectorSearchResult en de contracten EmbeddingServiceInterface en VectorIndexInterface komen van NextPDF Core; de caller construeert en levert de sidecar-client.
• De namespace NextPDF\Enterprise\Accelerator bevat ook batch-offload-engines en de retrieval-collection- en OCR-extractiestacks; die oppervlakken vallen buiten de scope van deze pagina.
• Interne mechanismedetails blijven in de interne documentatie van de bronrepository en vallen buiten de scope van deze handleiding.

Publicatiegrens

Deze pagina documenteert uitsluitend extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.

Zie ook

• Accelerator — GPU-sidecar en KMS-providerfactory — de capabilitypagina voor werkstroom- en bewaringsrichtlijnen.
• Accelerator-foutreferentie — sidecar-exceptiehiërarchie en foutcodes.
• Security — Uitgebreide referentie
• Accelerator — NextPDF Pro Uitgebreide referentie