Enterprise Edition

Accelerator — GPU-Sidecar und KMS-Provider-Factory

Auf einen Blick

NextPDF Enterprise ergänzt zwei Beschleunigungsfunktionen: einen GPU-Sidecar für das Text-Embedding mit CPU-Fallback und eine KMS-Provider-Factory, die Metadaten und Rotation für Datenverschlüsselungsschlüssel auf Sammlungsebene bereitstellt. Diese Seite legt das Verhalten, die Grenzen und die Haltung zur Schlüsselverwahrung dar.

Verfügbarkeit & Lizenzierung

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

Konzeptioneller Überblick

Der GPU-Sidecar beschleunigt das Text-zu-Vektor-Embedding. Das Enterprise-Paket sendet den Text über eine lokale HTTP-Anfrage an einen separaten Sidecar-Prozess. Der Sidecar führt das Embedding-Modell auf einer GPU aus, sofern eine verfügbar ist. Ist keine GPU verfügbar, führt der Sidecar dasselbe Modell auf der CPU aus und meldet, dass er in einem herabgestuften Modus lief. Das Ergebnis hat in beiden Fällen dieselbe Vektorform. Das Embedding-Modell wird bei der ersten Anfrage geladen, sodass die erste Anfrage langsamer ist als spätere. Der Sidecar ist optional; eine Verfügbarkeitsprüfung wird bereitgestellt, und ein fehlender Sidecar löst eine typisierte Ausnahme aus, statt still zu scheitern.

Die KMS-Provider-Factory wählt einen Schlüsselverwaltungs-Provider aus der Konfiguration aus. Die Factory liest eine Umgebungsvariable, um den Provider zu bestimmen. Der Standard-Provider leitet einen sammlungsspezifischen Datenverschlüsselungsschlüssel lokal mit HKDF-SHA256 aus einem konfigurierten Root Key ab, wobei der Sammlungsbezeichner als Domänentrenner dient. Der lokale Provider kontaktiert keinen externen Dienst; die Ableitung ist deterministisch und prozessintern. Die Factory akzeptiert außerdem eine explizite Konfigurationsform für den lokalen Provider. Cloud-Provider — AWS KMS, GCP Cloud KMS, Azure Key Vault und HashiCorp Vault Transit — sind anerkannte Provider-Namen; die Auswahl eines Providers ohne die zugehörige installierte Integration löst einen typisierten Konfigurationsfehler aus, der die fehlende Abhängigkeit benennt.

Ein Provider gibt Schlüssel-Metadaten zurück, keine rohen Schlüsselbytes. Die Metadaten erfassen den Schlüsselbezeichner, eine monoton steigende Schlüsselversion, den Namen des Verschlüsselungsalgorithmus und den Provider-Namen. Ein Rotationsaufruf erhöht die Schlüsselversion und gibt die neuen Metadaten zurück. Der Aufrufer ist dafür verantwortlich, die Sammlungsdaten nach einer Rotation mit der neuen Schlüsselversion neu zu verschlüsseln. Der Lebenszyklus von Schlüsselversion und Rotation folgt NIST SP 800-57 Part 1 Rev.5 §4.

Warum es so funktioniert

Das Embedding läuft in einem separaten GPU-Sidecar-Prozess statt innerhalb der PHP-Anfrage. Das Laden eines GPU-Modells ist teuer, daher lädt der Sidecar das Modell einmal und amortisiert diese Kosten über viele Anfragen. Ist keine GPU vorhanden, führt der Sidecar dasselbe Modell auf der CPU aus und meldet einen herabgestuften Modus. Der Durchsatz kann sinken, die Korrektheit jedoch nicht: Die Vektorform ist in beiden Fällen identisch. Der Sidecar bleibt optional; eine Verfügbarkeitsprüfung und eine typisierte Ausnahme bei einem fehlenden Sidecar machen die Beschleunigung zu einem bewussten Opt-in, nicht zu einer versteckten Abhängigkeit. Diese Trennung erlaubt es, das Embedding mit hohem Volumen auf dedizierter Hardware zu skalieren, während die Dokumenten-Pipeline ein einfacher PHP-Aufruf bleibt.

Design-Hintergrund: Dokumentgenerierung mit hohem Volumen.

API-Oberfläche

Public surface	Type	Purpose	Stability	Since
KMS-Provider-Factory	class	Erstellt einen KMS-Provider aus Umgebungs- oder expliziter Konfiguration	stable	2.1.0
KMS-Provider	interface	Schlüsselmetadaten abrufen, einen Schlüssel rotieren und den Provider-Namen melden	stable	2.1.0
Lokaler KMS-Provider	class (implements the provider interface)	Lokale HKDF-SHA256-Schlüsselableitung; kontaktiert keinen externen Dienst	stable	2.1.0
Encryption-key result	value object	Unveränderliche Schlüsselmetadaten: Schlüssel-ID, Version, Algorithmus, Provider — keine rohen Schlüsselbytes	stable	2.1.0
GPU-Embedding-Service	class (implements the Core embedding-service interface)	Text auf einem GPU-Sidecar mit CPU-Fallback einbetten	stable	2.1.0

Die Provider-Factory stellt einen „from environment”-Einstiegspunkt und einen expliziten „create”-Einstiegspunkt bereit. Der Konfigurationswert für den Root Key ist im lokalen Provider als sensibel markiert. Der maßgebliche Parameter- und Typvertrag ist die veröffentlichte API-Referenz für das Paket nextpdf/enterprise; behandeln Sie diese Referenz — nicht diese Seite — als den Vertrag.

Codebeispiel — Schnellstart

composer require nextpdf/core
composer require nextpdf/enterprise:^3

use NextPDF\Enterprise\Accelerator\KmsProviderFactory;

// Selects the provider from environment configuration; defaults to the
// local HKDF-based provider. Supply the root key through your secret
// manager, never from source or logs.
$provider = KmsProviderFactory::fromEnvironment();

$key = $provider->getEncryptionKey('collection-1');
// $key is metadata only: key id, version, algorithm, provider name.

Codebeispiel — Produktion

use NextPDF\Enterprise\Accelerator\KmsProviderFactory;

$provider = KmsProviderFactory::fromEnvironment();

$rotated = $provider->rotateKey('collection-1');
// The version advanced. Re-encrypt the collection's data files with the
// new key version. The provider returns metadata only; it never returns
// raw key bytes.

Die Namen der Umgebungsvariablen, die expliziten Konfigurationsschlüssel und die Ausnahmetypen sind in der Accelerator Deep Reference dokumentiert.

Sonderfälle und Stolperfallen

Der lokale KMS-Provider benötigt einen hex-kodierten Root Key von mindestens 32 Byte. Ein kürzerer oder nicht-hexadezimaler Wert löst beim Erstellen eine typisierte Argumentausnahme aus.
Die Auswahl eines Cloud-Provider-Namens ohne die zugehörige installierte Integration löst einen typisierten Konfigurationsfehler aus, der die fehlende Abhängigkeit benennt.
Ein unbekannter Provider-Name löst einen typisierten Fehler aus, der die unterstützten Namen auflistet.
Der GPU-Sidecar meldet einen herabgestuften Modus, wenn er auf die CPU zurückfällt. Prüfen Sie dieses Feld, wenn Sie auf den GPU-Durchsatz angewiesen sind.
Das Embedding-Modell wird bei der ersten Anfrage geladen; dimensionieren Sie das Timeout der ersten Anfrage entsprechend.

Performance

Die lokale Schlüsselableitung ist eine HKDF-Operation mit konstanten Kosten. Sie kontaktiert keinen externen Dienst. Eine GPU-Embedding-Anfrage fügt einen lokalen Roundtrip zum Sidecar plus die Modell-Inferenzzeit hinzu. Die erste Anfrage zahlt zusätzlich die einmaligen Kosten für das Laden des Modells. Der CPU-Fallback ist korrekt, aber für dieselbe Batch langsamer als der GPU-Pfad.

Sicherheitshinweise

Ein KMS-Provider gibt Schlüssel-Metadaten zurück, keine rohen Schlüsselbytes. Das Encryption-key-result-Value-Object trägt niemals das Schlüsselmaterial.
Der Root Key des lokalen Providers ist ein sensibler Konstruktorparameter. Er wird nicht protokolliert und nicht serialisiert.
Der lokale Provider kontaktiert keinen externen Dienst. Die Ableitung ist deterministisch und prozessintern.
Die Nutzung von AES-GCM erfordert einen pro Schlüssel eindeutigen Initialisierungsvektor, gemäß NIST SP 800-38D §5.

Datenresidenz & PII-Minderungen

Der lokale KMS-Provider läuft prozessintern und kontaktiert keinen externen Dienst; bei der lokalen Schlüsselableitung verlässt kein Schlüsselmaterial und kein Dokumenteninhalt den Host. Der GPU-Sidecar erhält den einzubettenden Text über eine lokale Anfrage; er erhält keinen unzusammenhängenden Dokumenteninhalt. Ein Cloud-KMS-Provider kontaktiert, wenn konfiguriert, den von Ihnen ausgewählten Cloud-Provider; prüfen Sie dessen Haltung zur Datenresidenz für Ihre Rechtsordnung.

Sichere Telemetrie & Log-Bereinigung

Der Root Key des lokalen Providers ist ein sensibler Konstruktorparameter und von Protokollen und Serialisierung ausgenommen. Fügen Sie den Root Key, abgeleitete Schlüssel oder Provider-Zugangsdaten nicht in Ihre eigenen Anwendungsprotokolle ein. Behandeln Sie sämtliches Schlüsselmaterial in Ihrer Protokollierungs- und Tracing-Richtlinie als Geheimnis.

Bedrohungsmodell

Der Provider gibt Metadaten zurück, keine Schlüsselbytes, sodass ein Metadatenleck kein Schlüsselmaterial offenlegt. Die Sicherheit des lokalen Providers hängt von der Geheimhaltung des konfigurierten Root Keys ab. Die Sicherheit eines Cloud-Providers hängt von diesem Provider und Ihrer Konfiguration ab. Der Schlüsselschutz hängt vom KMS oder dem Root-Key-Geheimnis, von der Bereitstellung und vom Betreiber ab — nicht von dieser Software allein. Siehe die Bereitstellungsgrenze.

Konformität

Der Lebenszyklus von Version und Rotation des Datenverschlüsselungsschlüssels ist auf NIST SP 800-57 Part 1 Rev.5 §4 abgestimmt.
Die Verantwortung für den Schlüsselschutz ist auf NIST SP 800-57 Part 1 Rev.5 §5.5.2 abgestimmt.
Die Eindeutigkeit des AES-GCM-Initialisierungsvektors ist auf NIST SP 800-38D §5 abgestimmt.

Jede normative Quelle ist paraphrasiert. Auf dieser Seite wird kein normativer Text wiedergegeben. Diese Seite betrifft das Schlüsselmanagement.

FIPS-mode-Verhalten

Die HKDF-Ableitung des lokalen Providers verwendet SHA-256. Der in den Schlüsselmetadaten erfasste Verschlüsselungsalgorithmus ist AES-256-GCM. Wenn die Anwendung gegen einen FIPS-validierten kryptografischen Provider läuft, laufen diese Primitive in dieser validierten Grenze. Die Provider-Factory selbst wählt und erstellt den Provider; sie zertifiziert die kryptografische Grenze nicht.

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.

Edition-Grenze

Der GPU-Embedding-Sidecar und die KMS-Provider-Factory werden ausschließlich im Paket nextpdf/enterprise ausgeliefert. NextPDF Pro bietet KMS-Integration für Signierstrategien (AWS KMS, GCP Cloud KMS, Azure Key Vault), stellt jedoch nicht die Enterprise-KMS-Provider-Factory oder den GPU-Embedding-Sidecar bereit. Der interne Sidecar-Transport und die internen Embedding-Pipeline-Klassen liegen außerhalb des Geltungsbereichs der öffentlichen Oberfläche und werden hier nicht wiedergegeben.

Pro-Fallback

NextPDF Pro stellt Cloud-KMS-Signierstrategien bereit — das KMS hält den Signierschlüssel, und Pro sendet den Digest der signierten Attribute an den Provider. Das ist eine Signierintegration. Es ist nicht die Enterprise-Provider-Factory für Datenverschlüsselungsschlüssel auf Sammlungsebene und nicht der GPU-Embedding-Sidecar. Siehe Accelerator — NextPDF Pro für die Pro-Beschleunigungsoberfläche.

Core-Fallback

NextPDF Core hat keinen GPU-Embedding-Sidecar und keine KMS-Provider-Factory. Embedding und Schlüsselverwaltung auf Sammlungsebene sind Enterprise-exklusive Funktionen.

Hinweis zur Enterprise-Grenze

Der GPU-Sidecar-Transport, der Bezeichner des Embedding-Modells und die internen Pipeline-Klassen werden nur auf Verhaltensebene beschrieben. Der interne Transport-Client, die internen Scope-Token und die interne Pipeline-Komposition liegen außerhalb des Geltungsbereichs der öffentlichen Oberfläche und werden hier nicht wiedergegeben.

Bereitstellungsgrenze

NextPDF Enterprise integriert sich mit einem KMS oder leitet Schlüssel aus einem konfigurierten Root-Key-Geheimnis ab. Es speichert dieses Root-Key-Geheimnis oder den Cloud-KMS-Schlüssel selbst nicht und garantiert deren Sicherheit nicht. Die Schlüsselsicherheit hängt vom KMS oder dem Root-Key-Geheimnis, von der Bereitstellung und vom Betreiber ab — nicht von NextPDF Enterprise allein. Der Betreiber ist für die Root-Key-Bereitstellung, die Geheimnisspeicherung, die KMS-Konfiguration und die Rotationsplanung verantwortlich. Die Verantwortung für den Schlüsselschutz folgt NIST SP 800-57 Part 1 Rev.5 §5.5.2. NextPDF Enterprise legt in dieser Dokumentation keine KMS-Anmeldedatenflüsse oder Root-Key-Handhabungsinterna offen.

Rechtliche Compliance-Grenze

Sie betrifft das Schlüsselmanagement. Die FIPS-mode-Aussage ist eine Kompatibilitätsaussage, keine Zertifizierung und kein Rechtsgutachten. Konsultieren Sie für Ihre regulatorischen Pflichten Ihre eigenen Compliance- und Rechtsberater.

Veröffentlichungsgrenze

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

Verhaltensvertrag

Die Provider-Factory wählt den Provider aus der Konfiguration aus und gibt einen Provider zurück, der den Provider-Vertrag erfüllt.
Ein Provider gibt unveränderliche Schlüsselmetadaten zurück und niemals rohe Schlüsselbytes.
Ein Rotationsaufruf erhöht die Schlüsselversion und gibt die neuen Metadaten zurück; der Aufrufer verschlüsselt die Sammlungsdaten neu.
Der GPU-Sidecar meldet bei einem CPU-Fallback einen herabgestuften Modus und löst eine typisierte Ausnahme aus, wenn er nicht verfügbar ist.

Siehe auch

Accelerator-Referenz — NextPDF Enterprise
Security — NextPDF Enterprise
Intelligence — NextPDF Enterprise
Accelerator — NextPDF Pro
KMS · DEK · HKDF — Glossarbegriffe.