Accelerator — Ausführliche Referenz (GPU-Sidecar, KMS-Provider-Factory)

Auf einen Blick

Diese Seite ist die Detailreferenz für die öffentliche Beschleunigungsoberfläche von NextPDF\Enterprise\Accelerator. Sie behandelt den KMS-Provider-Stack — die Factory, den Provider-Vertrag, den lokalen Provider und das Ergebnis der Schlüsselmetadaten — sowie die GPU-Sidecar-Dienste für Embedding und Vektorsuche. Sie beschreibt Parameter, Standardwerte, Fehlermodi und die Haltung zur Schlüsselverwahrung. Lesen Sie zuerst die Accelerator-Funktionsseite für Anleitungen zum Arbeitsablauf. Andere Symbole im selben Namensraum gehören zu anderen Funktionen und liegen außerhalb des Umfangs dieser Seite.

Verfügbarkeit & Lizenzierung

Diese Funktion ist in NextPDF Enterprise (nextpdf/enterprise) enthalten und wird mit einer Lizenzhülle der Enterprise-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Funktion nicht. Editionen vergleichen und eine Lizenz erwerben.

Der KMS-Provider wird zur Laufzeit ausgewählt; aufrufender Code hängt vom Provider-Vertrag ab, nicht vom konkreten Provider. Die Embedding- und Vektorindex-Dienste implementieren die Core-Verträge EmbeddingServiceInterface und VectorIndexInterface.

Öffentliche API-Oberfläche

composer require nextpdf/enterprise:^3

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
KmsProviderFactory::fromEnvironment	keine	Erstellt den durch die Selektorvariable benannten Provider; nicht gesetzt oder leer wählt local	KmsProviderInterface	RuntimeException bei fehlendem Masterschlüssel, nicht verfügbarem Cloud-Provider oder unbekanntem Namen	Statischer Einstiegspunkt
KmsProviderFactory::create	string $providerType, array $config = []	Erstellt den benannten Provider aus expliziter Konfiguration	KmsProviderInterface	RuntimeException, wenn local kein nicht-leeres encryption_key besitzt, oder bei unbekanntem Namen	local ist der einzige konstruierbare Name in dieser Version
KmsProviderInterface::getEncryptionKey	string $collectionId	Gibt die aktuellen Schlüsselmetadaten für die Sammlung zurück	EncryptionKeyResult	RuntimeException, wenn der Provider nicht erreichbar oder fehlkonfiguriert ist (Vertrag)	Nur Metadaten; niemals rohe Schlüsselbytes
KmsProviderInterface::rotateKey	string $collectionId	Erhöht die Schlüsselversion	EncryptionKeyResult	RuntimeException, wenn die Rotation scheitert (Vertrag)	Rotation ist ein Neuverschlüsselungssignal an den Aufrufer
KmsProviderInterface::providerName	keine	Meldet den kanonischen Provider-Namen	string	Nichts deklariert	local, aws, gcp, azure, vault
LocalKmsProvider::__construct	string $encryptionKey (sensibel)	Validiert einen Hex-Masterschlüssel von mindestens 64 Hex-Zeichen (32 Byte)	LocalKmsProvider	InvalidArgumentException bei einem zu kurzen oder nicht-hexadezimalen Wert	Fail-Fast-Prüfung; führt selbst keine Ableitung durch
LocalKmsProvider::getEncryptionKey	string $collectionId	Prägt local:{collectionId}:v{version}; die Version ist standardmäßig 1	EncryptionKeyResult	Nichts deklariert	Algorithmuskennzeichen AES-256-GCM
LocalKmsProvider::rotateKey	string $collectionId	Erhöht den prozessinternen Versionszähler	EncryptionKeyResult	Nichts deklariert	Der Versionszustand gilt pro Instanz
EncryptionKeyResult::__construct	string $keyId, int $keyVersion, string $algorithm = 'AES-256-GCM', string $provider = 'local'	Unveränderliches Metadaten-Wertobjekt	EncryptionKeyResult	Nichts deklariert	Trägt niemals Schlüsselmaterial
GpuEmbeddingService::embed	string $text	Delegiert an batchEmbed und gibt Element null zurück	list<float>	Wie batchEmbed	1024-dimensionaler Vektor
GpuEmbeddingService::batchEmbed	array $texts	Bettet den Stapel auf dem Sidecar ein	list<list<float>>	InvalidArgumentException bei leerem Stapel; SpectrumNotAvailableException, wenn das Sidecar nicht erreichbar ist; SpectrumApiException bei einer fehlgeschlagenen, fehlerhaften oder in der Anzahl abweichenden Antwort	Gibt niemals Teilergebnisse zurück
GpuEmbeddingService::getDimension	keine	Gibt 1024 zurück	int	Nichts deklariert	Konstante
GpuEmbeddingService::getModelName	keine	Gibt multilingual-e5-large zurück	string	Nichts deklariert	Konstante
GpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Bindet den Handle an eine Sammlung	GpuVectorIndex	Nichts deklariert	Ein Handle pro Sammlungskennung
GpuVectorIndex::build	array $vectors, array $ids	Erstellt den Sammlungsindex auf dem Sidecar	void	InvalidArgumentException bei leerem Stapel oder einer Längenabweichung; SpectrumNotAvailableException, wenn nicht erreichbar; SpectrumApiException bei einer unerwarteten Build-Antwort	Ein Neuaufbau ersetzt den Index
GpuVectorIndex::search	array $queryVector, int $topK = 10	Gerankte Nächste-Nachbarn-Suche	list<VectorSearchResult>	SpectrumNotAvailableException, wenn nicht erreichbar; JsonException bei einem fehlerhaften Antworttext	Rang pro Treffer in den Ergebnismetadaten
GpuVectorIndex::delete	array $ids	Lehnt immer ab	void (deklariert)	Immer: SpectrumApiException (nicht implementiert)	Der erstellte Index ist unveränderlich; stattdessen neu aufbauen
GpuVectorIndex::count	keine	Liest die Sammlungssumme vom Sidecar	int	Wirft nicht; jeder Fehler gibt 0 zurück	0 ist mehrdeutig: leer oder nicht erreichbar

Signaturen der Einstiegspunkte

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
}

Konfigurationsoberfläche

Einstellung	Konsument	Bedeutung
SPECTRUM_KMS_PROVIDER	fromEnvironment()	Provider-Selektor. Nicht gesetzt oder leer wird zu local aufgelöst.
SPECTRUM_ENCRYPTION_KEY	Der local-Provider-Pfad	Hex-kodierter Masterschlüssel; mindestens 64 Hex-Zeichen (32 Byte). Mit dem Sidecar geteilt.
encryption_key	create('local', [...])	Expliziter Masterschlüssel; gleiches Format und gleiche Validierung.

Verhaltensvertrag

Provider-Auswahl

KmsProviderFactory::fromEnvironment liest die Selektorvariable und verwendet standardmäßig local. Die Cloud-Provider-Namen aws, gcp, azure und vault werden erkannt, sind aber in dieser Version nicht konstruierbar. Die Auswahl von aws löst einen typisierten Fehler aus, der das erforderliche Paket aws/aws-sdk-php benennt; die anderen drei melden die Integration als nicht implementiert. Ein unbekannter Name löst einen typisierten Fehler aus, der die unterstützten Namen auflistet. KmsProviderFactory::create akzeptiert einen expliziten Provider-Namen und eine Konfigurationszuordnung; local ist der einzige Name, den es konstruiert.

Schlüsselmetadaten und -verwahrung

Ein Provider gibt unveränderliche Schlüsselmetadaten zurück: eine Schlüsselkennung, eine monoton steigende Schlüsselversion, das Algorithmuskennzeichen und den Provider-Namen. Er gibt niemals rohe Schlüsselbytes zurück, sodass ein Metadatenleck kein Schlüsselmaterial preisgibt. Der lokale Provider teilt die Aufgaben mit dem Accelerator-Sidecar. Die PHP-Klasse validiert das Mastergeheimnis bei der Konstruktion und prägt eine stabile, sammlungsbezogene Schlüsselidentität in der Form local:{collectionId}:v{version}. Das Sidecar führt die HKDF-SHA256-Ableitung und die AES-256-GCM-Verschlüsselung durch und leitet mit Sammlungskennung und Version als Domänentrennung pro Sammlung einen eigenen 32-Byte-Datenverschlüsselungsschlüssel ab. Beide Seiten lesen dasselbe konfigurierte Mastergeheimnis. Es wird kein externer KMS-Dienst kontaktiert; die Schlüsselverarbeitung bleibt innerhalb der Bereitstellung. Das Schlüsselversions- und Lebenszyklusmodell folgt NIST SP 800-57 Part 1 Rev.5 §4.

Ein Rotationsaufruf erhöht die Schlüsselversion und gibt die neuen Metadaten zurück. Der Aufrufer verschlüsselt die Sammlungsdaten mit der neuen Version neu; der Provider selbst verschlüsselt nichts neu.

Die Schlüsselsicherheit hängt vom KMS oder dem Mastergeheimnis, von der Bereitstellung und vom Betreiber ab — nicht von NextPDF Enterprise allein. Der Betreiber ist verantwortlich für die Bereitstellung des Masterschlüssels, die Aufbewahrung des Geheimnisses, die KMS-Konfiguration und die Rotationsplanung. Die Verantwortung für den Schlüsselschutz folgt NIST SP 800-57 Part 1 Rev.5 §5.5.2.

GPU-Embedding

GpuEmbeddingService implementiert den Core-Embedding-Vertrag und delegiert an das Sidecar. Das Sidecar führt das Embedding-Modell auf einer GPU aus, wenn eine verfügbar ist, und weicht andernfalls auf die CPU aus, wobei es die Antwortmetadaten als von GPU herabgestuft kennzeichnet. Die Vektorform ist in beiden Fällen identisch. Das Modell (etwa 1,3 GB) wird beim ersten Aufruf verzögert heruntergeladen und geladen. Die Stapelsemantik ist Alles-oder-Nichts: ein Fehler pro Element, ein fehlerhafter Vektor oder eine abweichende Anzahl löst einen typisierten Fehler aus, statt Teilergebnisse zurückzugeben.

GPU-Vektorsuche

GpuVectorIndex implementiert den Core-Vektorindex-Vertrag und bindet einen Handle an eine Sammlungskennung. build erstellt den Index auf dem Sidecar; das Sidecar verwendet einen GPU-Index, wenn einer verfügbar ist, andernfalls einen CPU-Index. Der Index ist nach dem Erstellen unveränderlich: delete lehnt immer mit einem typisierten Nicht-implementiert-Fehler ab, und das Entfernen erfordert einen Neuaufbau. search gibt gerankte Treffer mit einem eins-basierten Rang in den Metadaten jedes Ergebnisses zurück. count fragt das Sidecar nach der Sammlungssumme und meldet bei jedem Fehler 0, statt eine Ausnahme auszulösen.

Grenzfälle & Fehlermodi

• Der Masterschlüssel muss aus Hex zu mindestens 32 Byte dekodieren. Ein zu kurzer oder nicht-hexadezimaler Wert löst bei der Konstruktion InvalidArgumentException aus, noch vor jedem Sidecar-Aufruf.
• Eine nicht gesetzte oder leere Selektorvariable wird zu local aufgelöst; die Factory rät niemals einen anderen Provider.
• fromEnvironment auf dem local-Pfad ohne die Masterschlüssel-Variable löst einen typisierten Fehler aus, der die fehlende Variable benennt.
• create('local', [...]) ohne einen nicht-leeren encryption_key-Eintrag löst einen typisierten Fehler aus, der den fehlenden Eintrag benennt.
• Der Schlüsselversionszustand ist prozessintern und pro Provider-Instanz. Ein neuer Prozess beobachtet Version 1, bis erneut eine Rotation ausgeführt wird. Persistieren Sie Rotationsergebnisse durch Neuverschlüsseln der Daten, nicht durch Vertrauen in den Provider-Zustand.
• Ein leerer Embedding-Stapel löst InvalidArgumentException aus; das Sidecar wird nicht kontaktiert.
• Die Sidecar-Verfügbarkeit wird pro Aufruf geprüft. Ein nicht erreichbares Sidecar löst SpectrumNotAvailableException aus; die Dienste scheitern niemals stillschweigend.
• Eine nicht-numerische Komponente in einem zurückgegebenen Embedding-Vektor wird zu 0.0 umgewandelt; ein fehlender oder nicht als Array vorliegender Vektor löst SpectrumApiException aus.
• Der erste Embedding-Aufruf trägt die einmaligen Kosten für das Herunterladen und Laden des Modells; bemessen Sie dieses Timeout separat.
• build und search dekodieren die Sidecar-Antwort strikt; ein fehlerhafter Text löst JsonException aus. count verschluckt jeden Fehler und gibt 0 zurück.
• Ein Suchtreffer ohne Kennung oder Wert wird standardmäßig auf eine leere Zeichenkette und 0.0 gesetzt, statt den Stapel scheitern zu lassen.
• Sidecar-Fehlercodes und die Ausnahmehierarchie sind in der Accelerator-Fehlerreferenz katalogisiert.

Verhalten im FIPS-Modus

Der lokale Schlüsselpfad verwendet HKDF-SHA256 zur Ableitung und AES-256-GCM zur Verschlüsselung; das Sidecar führt beides aus. Das in den Schlüsselmetadaten erfasste Algorithmuskennzeichen ist AES-256-GCM. Wenn die Bereitstellung gegen einen FIPS-validierten kryptografischen Provider läuft, werden diese Primitive innerhalb dieser validierten Grenze ausgeführt. Die Verwendung von AES-GCM erfordert einen eindeutigen Initialisierungsvektor pro Schlüssel, gemäß NIST SP 800-38D §5.

NextPDF Enterprise ist kein FIPS-validiertes kryptografisches Modul und erhebt keinen FIPS-Zertifizierungsanspruch. Es arbeitet nur dann in einem FIPS-kompatiblen Modus, wenn es mit einem FIPS-validierten kryptografischen Provider oder einem FIPS-validierten KMS konfiguriert ist. In diesem Repository existiert kein FIPS-Zertifizierungsartefakt.

Konformität

Anspruch	Standard	Klausel
Das Schlüsselversions- und Lebenszyklusmodell folgt den Vorgaben zu Schlüsselzuständen.	NIST SP 800-57 Part 1 Rev.5	§4
Die Verantwortung für Schlüsselschutz und -verwahrung liegt beim Schlüsseleigentümer und Betreiber.	NIST SP 800-57 Part 1 Rev.5	§5.5.2
AES-GCM erfordert einen eindeutigen Initialisierungsvektor pro Schlüssel.	NIST SP 800-38D	§5

Alle Klauseln sind paraphrasiert; NextPDF gibt keinen normativen Text wieder. NextPDF erhebt keinen Zertifizierungsanspruch. Die Übereinstimmung mit den zitierten Klauseln ist eine Funktionsaussage, keine Zertifizierung. Diese Seite betrifft die Schlüsselverwaltung; die Aussage zum FIPS-Modus ist eine Kompatibilitätsaussage, kein Rechtsgutachten. Ziehen Sie Ihre eigenen Compliance- und Rechtsberater hinzu.

Entwicklungshinweise

• Der Modulquellcode trägt @since 2.1.0; diese Referenz dokumentiert die Oberfläche, wie sie in nextpdf/enterprise 3.1.0 ausgeliefert wird.
• Alle Klassen sind final; EncryptionKeyResult ist final readonly. Konstruieren Sie neue Instanzen, statt zu mutieren.
• Der Masterschlüssel ist ein sensibler Konstruktorparameter (#[SensitiveParameter]); PHP redigiert ihn aus Stack-Traces. Halten Sie ihn aus Anwendungsprotokollen und Konfigurationsdumps heraus.
• SpectrumClient, VectorSearchResult sowie die Verträge EmbeddingServiceInterface und VectorIndexInterface stammen aus NextPDF Core; der Aufrufer konstruiert und liefert den Sidecar-Client.
• Der Namensraum NextPDF\Enterprise\Accelerator trägt außerdem Batch-Offload-Engines sowie die Retrieval-Sammlungs- und OCR-Extraktions-Stacks; diese Oberflächen liegen außerhalb des Umfangs dieser Seite.
• Interne Mechanismusdetails verbleiben in der internen Dokumentation des Quell-Repositorys und liegen außerhalb des Umfangs dieses Handbuchs.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namensraumpfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.

Siehe auch

• Accelerator — GPU-Sidecar und KMS-Provider-Factory — die Funktionsseite für Arbeitsablauf- und Verwahrungsanleitungen.
• Accelerator-Fehlerreferenz — Sidecar-Ausnahmehierarchie und Fehlercodes.
• Sicherheit — Detailreferenz
• Accelerator — NextPDF Pro Detailreferenz