Accelerator

Auf einen Blick

Accelerator lagert die Batch-Bildneukomprimierung, das PDF-Parsing und das Texteinbetten an einen mitplatzierten CPU-Sidecar aus. Ist der Sidecar nicht erreichbar, fällt jede Operation auf den In-process-PHP-Pfad zurück, sodass Aufrufer in beiden Fällen dieselben Ergebnisse beobachten.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit ist in NextPDF Pro (nextpdf/pro) enthalten und wird mit einem Lizenz-Envelope der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Editionen vergleichen und Lizenz erwerben.

Accelerator hat kein separates Flag pro Funktion. Der beschleunigte Pfad wird zur Laufzeit durch eine Sidecar-Erreichbarkeitsprüfung ausgewählt (ProAcceleratorProvider::isAvailable()); ist der Sidecar nicht erreichbar, läuft stattdessen der In-process-PHP-Pfad.

Installation

composer require nextpdf/pro:^3

Das Premium-Paket installiert den nextpdf/pro-Code unter dem Namespace NextPDF\Pro\Accelerator. Das nextpdf/premium-Metapaket installiert außerdem Enterprise-Fähigkeiten; Accelerator selbst ist eine Funktion der Pro-Stufe.

Konzeptioneller Überblick

ProAcceleratorProvider ist der Einstiegspunkt. Er konstruiert vier Dienste lazy:

• Einen beschleunigten Optimizer, der den Pro-PdfOptimizer umhüllt und die Batch-Bildarbeit an den Sidecar auslagert.
• Einen beschleunigten Differ, der den Pro-PdfDiffer umhüllt; der Sidecar parallelisiert das Struktur-Parsing, während der Diff-Algorithmus selbst in PHP läuft.
• Einen CPU-Embedding-Dienst, der 384-dimensionale Vektoren mit einem vom Sidecar gehosteten all-MiniLM-L6-v2-ONNX-Modell zurückgibt.
• Einen CPU-Vektorindex, der einen In-Memory-HNSW-Index aufbaut und durchsucht, indiziert über eine Collection-Kennung.

Das Design hält die Domänenlogik in PHP. Der Sidecar führt parallelisierbare, CPU-gebundene Arbeit aus (Bild-Transcoding, Mehrdokument-Parsing, ONNX-Inferenz, Vektorsuche). Jeder beschleunigte Pfad hat einen deterministischen PHP-Fallback, der äquivalente Ergebnisse erzeugt.

Warum es so funktioniert

Die tragende Entscheidung ist, dass die Korrektheit niemals vom Sidecar abhängt. Die Domänenlogik bleibt in PHP; der Sidecar führt nur parallelisierbare, CPU-gebundene Arbeit aus. Der Optimizer und der Differ (AcceleratedOptimizer, AcceleratedDiffer) behalten einen deterministischen PHP-Fallback, sodass ein fehlender Sidecar das Timing ändert, nicht die Ergebnisse. Nur die beiden Operationen ohne PHP-Äquivalent — CpuEmbeddingService und CpuVectorIndex — schlagen fehl (fail closed), statt herabzustufen. Eine stille falsche Antwort wäre dort schlimmer als ein expliziter Fehler. Diese Aufteilung lässt den Durchsatz mit den Sidecar-Kernen skalieren, während Aufrufer einen Codepfad und eine Vertrauensgrenze behalten.

Design-Hintergrund: Hochvolumige Dokumentgenerierung.

Verhaltensvertrag

• ProAcceleratorProvider::isAvailable() gibt zurück, ob der Sidecar antwortet. Aufrufer können danach verzweigen, müssen es aber nicht: Der Optimizer und der Differ fallen automatisch zurück.
• embedding()->embed() gibt einen einzelnen 384-elementigen Vektor zurück; batchEmbed() gibt einen Vektor pro Eingabe zurück und lehnt eine leere Eingabeliste mit InvalidArgumentException ab.
• vectorIndex($collectionId)->build() erfordert, dass vectors und ids dieselbe Länge haben, und behandelt eine leere Eingabe als No-op.
• vectorIndex()->search($queryVector, $topK) gibt gerankte Ergebnisse zurück; delete() wird für den HNSW-Index nicht unterstützt und lehnt den Aufruf ab — Aufrufer bauen stattdessen den Index neu auf.
• Der Embedding-Dienst und der Vektorindex erfordern den Sidecar; sie lösen einen „nicht verfügbar“-Fehler aus, statt stillschweigend herabzustufen, weil es kein PHP-Äquivalent für ONNX-Inferenz oder HNSW-Suche gibt.
• Der Optimizer und der Differ lösen bei einem Sidecar-Fehler niemals aus; sie stufen transparent auf den PHP-Pfad herab.

Codebeispiel — Schnellstart

Das Folgende spiegelt die dokumentierte öffentliche API wider (ProAcceleratorProvider). Das Repository liefert kein lauffähiges Beispiel für dieses Modul.

use NextPDF\Pro\Accelerator\ProAcceleratorProvider;

$provider = new ProAcceleratorProvider($spectrumClient);

$result = $provider->optimizer()->optimizeBatch([
    'invoice-1' => $pdfBytesA,
    'invoice-2' => $pdfBytesB,
]);

foreach ($result->getItems() as $item) {
    // Per-document optimization outcome.
}

Codebeispiel — Produktion

use NextPDF\Pro\Accelerator\ProAcceleratorProvider;

$provider = new ProAcceleratorProvider($spectrumClient);

if ($provider->isAvailable()) {
    $index = $provider->vectorIndex('contracts');
    $index->build($vectors, $ids);
    $hits = $index->search($queryVector, topK: 10);
} else {
    // No PHP equivalent for HNSW search: route to your own retrieval path
    // or surface a degraded-capability message.
}

Verdrahten Sie ProAcceleratorProvider über Ihren Container als Singleton, sodass die Optimizer- und Differ-Instanzen wiederverwendet werden. Behandeln Sie die Embedding- und Vektorindex-Aufrufe als den Sidecar erfordernd.

Sonderfälle & Fallstricke

• Der Vektorindex lebt im Prozessspeicher des Sidecars und wird über die Collection-Kennung indiziert. Ein Sidecar-Neustart löscht alle Indizes; bauen Sie nach einem Neustart neu auf.
• count() auf dem Vektorindex gibt 0 zurück, wenn der Sidecar nicht erreichbar ist, statt auszulösen.
• Die Optimizer- und Differ-Beschleunigung ist Best-Effort; ein Sidecar-Fehler mitten im Batch verursacht für diesen Aufruf einen stillen Fallback, sodass das Timing — nicht die Korrektheit — variiert.

Performance

Die Beschleunigung zielt auf CPU-gebundene Batch-Arbeit: paralleles Bild-Transcoding, Mehrdokument-Parsing und Vektorsuche. NextPDF veröffentlicht hier keinen festen Durchsatz-Multiplikator; die Gewinne hängen von der Dokumentmischung, der Bilddichte, der Sidecar-Kernzahl und der Batch-Größe ab. Messen Sie in Ihrer Umgebung, bevor Sie sich auf eine bestimmte Zahl verlassen. Der PHP-Fallback ist designbedingt single-threaded.

Sicherheitshinweise

Dieses Modul sendet Dokumente und Vektoren über den konfigurierten Transport an den mitplatzierten Sidecar. Behandeln Sie den Sidecar als Teil Ihrer Vertrauensgrenze und deployen Sie ihn auf demselben Host oder einem privaten Netzwerksegment. Das Modul validiert Eingabegröße und -form vor dem Dispatch. Es protokolliert keinen Dokumentinhalt.

Konformität

Dieses Modul führt selbst keine Formatkonformitätsarbeit aus; es delegiert Optimierung und Diffing an die Pro-Module Optimizer und Diff. Siehe diese Module für ISO 32000-2-Referenzen. Die Konformitätsevidenz für diese Seite stammt aus den dokumentierten öffentlichen Klassenverträgen und deren Unit-Tests; der RAG-Korpus war zur Autorenzeit nicht verfügbar, sodass hier keine externen Klausel-Identifikatoren behauptet werden.

Hinweis zur Enterprise-Grenze

Enterprise ändert das Accelerator-Verhalten nicht. Enterprise ergänzt höherstufige Funktionen für Compliance, Archivierung und den Signatur-Lebenszyklus, die anderswo dokumentiert sind; diese liegen außerhalb des Umfangs dieses Moduls und sind zur Nutzung von Accelerator nicht erforderlich.

Core-Fallback / Alternative

Ohne Pro nutzen Sie die In-process-Optimierung und das Diffing von NextPDF Core. Die beschleunigten Pfade in diesem Modul reduzieren sich auf dasselbe PHP-Verhalten, wenn der Sidecar fehlt.

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 Umfangs.

Siehe auch

• Accelerator — Deep-Referenz
• Optimizer
• Diff
• Output Pipeline