Accelerator — Ausführliche Referenz

Auf einen Blick

Diese Seite ist die ausführliche Referenz für die öffentliche Beschleunigungsoberfläche von NextPDF\Pro\Accelerator. Sie behandelt die Provider-Factory, den beschleunigten Batch-Optimierer, den Differ-Wrapper sowie die CPU-Sidecar-Dienste für Embedding und Vektorsuche. Sie benennt Parameter, Standardwerte, Fehlermodi und Fallback-Semantik. Lesen Sie zuerst die Accelerator-Funktionsseite für eine Anleitung zum Arbeitsablauf.

Verfügbarkeit & Lizenzierung

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

Accelerator hat kein funktionsspezifisches Lizenzflag. Der Code wird mit der Pro-Edition ausgeliefert; der beschleunigte Optimiererpfad wird zur Laufzeit durch eine Erreichbarkeitsprüfung des Sidecars ausgewählt. Der Embedding-Dienst und der Vektorindex haben keinen PHP-Fallback und scheitern geschlossen (fail closed), wenn das Sidecar nicht erreichbar ist.

Öffentliche API-Oberfläche

composer require nextpdf/pro:^3

Das nextpdf/premium-Metapaket installiert den nextpdf/pro-Code; dieses Modul liegt im Namespace NextPDF\Pro\Accelerator.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
ProAcceleratorProvider::__construct	SpectrumClient $client	Bindet den Provider an einen Core-Sidecar-Client	ProAcceleratorProvider	Nichts deklariert	Der Aufrufer erzeugt und liefert den Client
ProAcceleratorProvider::isAvailable	keine	Prüft die Sidecar-Erreichbarkeit über den Client	bool	Nichts deklariert	Nur Erreichbarkeit; Endpunkte werden pro Aufruf geprüft
ProAcceleratorProvider::embedding	keine	Gibt den memoisierten Embedding-Dienst zurück	EmbeddingServiceInterface	Nichts deklariert	Eine CpuEmbeddingService-Instanz pro Provider
ProAcceleratorProvider::vectorIndex	string $collectionId = 'default'	Gibt ein frisches, an die Collection gebundenes Index-Handle zurück	VectorIndexInterface	Nichts deklariert	Nicht memoisiert; ein Handle pro Aufruf
ProAcceleratorProvider::optimizer	keine	Gibt den memoisierten beschleunigten Optimierer zurück	AcceleratedOptimizer	Nichts deklariert	Erzeugt mit dem Client des Providers
ProAcceleratorProvider::differ	keine	Gibt den memoisierten Differ-Wrapper zurück	AcceleratedDiffer	Nichts deklariert	Erzeugt mit dem Client des Providers
AcceleratedOptimizer::__construct	?SpectrumClient $spectrum = null, OptimizationLevel $level = OptimizationLevel::Balanced, ?LoggerInterface $logger = null	Umschließt den PHP-PdfOptimizer auf der angegebenen Stufe	AcceleratedOptimizer	Nichts deklariert	Ein Null-Client wählt den PHP-Pfad; ein Null-Logger wählt NullLogger
AcceleratedOptimizer::optimizeBatch	array<string, string> $documents	Analysiert jedes Dokument; lagert die Bildarbeit an das Sidecar aus, wenn erreichbar	BatchResultInterface	SpectrumApiException SPEC-SEC-001 (HTTP 413) bei einem Batch über dem Limit; Fehlermarker pro Element im Fallback-Ergebnis	Transportfehler nach der Aufnahme fallen auf den PHP-Pfad zurück
AcceleratedDiffer::__construct	?SpectrumClient $spectrum = null	Behält den optionalen Client zur Vorwärtskompatibilität	AcceleratedDiffer	Nichts deklariert	Der Client wird in dieser Version nicht verwendet
AcceleratedDiffer::compare	string $sourcePdf, string $targetPdf	Vergleicht zwei Dokumente vollständig in PHP	DiffResult	Wie der Pro-PdfDiffer	In dieser Version wird keine Sidecar-Anfrage ausgelöst
AcceleratedDiffer::isSpectrumWired	keine	Meldet, ob ein Sidecar-Client injiziert wurde	bool	Nichts deklariert	Nur Verdrahtungszustand; löst keine Anfrage aus
CpuEmbeddingService::embed	string $text	Delegiert an batchEmbed und gibt Element null zurück	list<float>	Wie batchEmbed	384-dimensionaler Vektor
CpuEmbeddingService::batchEmbed	array $texts	Bettet den Batch auf dem Sidecar ein	list<list<float>>	InvalidArgumentException bei einem leeren Batch; SpectrumNotAvailableException bei Nichterreichbarkeit; SpectrumApiException bei einer fehlgeschlagenen, fehlerhaften oder anzahlabweichenden Antwort	Gibt niemals Teilergebnisse zurück
CpuEmbeddingService::getDimension	keine	Gibt 384 zurück	int	Nichts deklariert	Konstant
CpuEmbeddingService::getModelName	keine	Gibt all-MiniLM-L6-v2 zurück	string	Nichts deklariert	Konstant
CpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Bindet das Handle an eine Collection	CpuVectorIndex	Nichts deklariert	Ein Handle pro Collection-Identifier
CpuVectorIndex::build	array $vectors, array $ids	Baut den Collection-Index auf dem Sidecar	void	InvalidArgumentException bei einer Längenabweichung; SpectrumNotAvailableException bei Nichterreichbarkeit	Eine leere Eingabe kehrt zurück, ohne das Sidecar zu kontaktieren
CpuVectorIndex::search	array $queryVector, int $topK = 10	Nächste-Nachbarn-Suche mit Rangordnung	list<VectorSearchResult>	SpectrumNotAvailableException bei Nichterreichbarkeit; SpectrumApiException bei einem In-Band-Fehler-Envelope; JsonException bei einem fehlerhaften Body	Rang pro Treffer in den Ergebnismetadaten
CpuVectorIndex::delete	array $ids	Lehnt immer ab	void (deklariert)	Immer: SpectrumApiException SPEC-INDEX-004 (HTTP 501)	HNSW hat keine Löschung pro Vektor; stattdessen neu aufbauen
CpuVectorIndex::count	keine	Liest die Collection-Gesamtzahl über eine dimensionierte Prüfung	int	SpectrumNotAvailableException bei Nichterreichbarkeit; SpectrumApiException bei einem Fehler oder einer fehlerhaften Zählantwort	Gibt 0 nur für einen bestätigt leeren Index zurück
CpuVectorIndex::INDEX_DIMENSION	—	Öffentliche Konstante 384	int	—	Entspricht der Embedding-Dimension

Signaturen der Einstiegspunkte

final class ProAcceleratorProvider
{
    public function __construct(
        private readonly SpectrumClient $client,
    )

    public function isAvailable(): bool

    public function embedding(): EmbeddingServiceInterface

    public function vectorIndex(string $collectionId = 'default'): VectorIndexInterface

    public function optimizer(): AcceleratedOptimizer

    public function differ(): AcceleratedDiffer
}

final class AcceleratedOptimizer
{
    public function __construct(
        private readonly ?SpectrumClient $spectrum = null,
        private readonly OptimizationLevel $level = OptimizationLevel::Balanced,
        ?LoggerInterface $logger = null,
    )

    public function optimizeBatch(array $documents): BatchResultInterface
}

final class AcceleratedDiffer
{
    public function __construct(
        private readonly ?SpectrumClient $spectrum = null,
    )

    public function compare(string $sourcePdf, string $targetPdf): DiffResult

    public function isSpectrumWired(): bool
}

final class CpuEmbeddingService 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 CpuVectorIndex implements VectorIndexInterface
{
    public const int INDEX_DIMENSION = 384;

    public function __construct(
        private readonly SpectrumClient $client,
        private readonly 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
}

Verhaltensvertrag

Provider

ProAcceleratorProvider ist der Einstiegspunkt. embedding(), optimizer() und differ() memoisieren ihre Instanzen. vectorIndex($collectionId) gibt pro Aufruf ein frisches, an den angegebenen Collection-Identifier gebundenes Handle zurück. isAvailable() prüft die Sidecar-Erreichbarkeit über den injizierten Core-SpectrumClient.

Batch-Optimierung

optimizeBatch gibt ein Batch-Ergebnis zurück, das nach den Dokumentkennungen des Aufrufers verschlüsselt ist. Wenn das Sidecar erreichbar ist, wird die aggregierte Nutzlast vor jeder Pufferung oder jedem Upload gegen das Client-Budget validiert. Ein Batch über dem Limit scheitert geschlossen mit SpectrumApiException SPEC-SEC-001 (HTTP 413); er fällt niemals auf den PHP-Pfad zurück. Ein aufgenommener Batch wird zur parallelen Bildarbeit an das Sidecar versandt.

Ein Transport-, Authentifizierungs- oder Antwortparsefehler nach der Aufnahme fällt auf den PHP-Optimierer zurück, der jedes Dokument sequenziell analysiert. Die Herabstufung ist zweifach beobachtbar: Die Ergebnismetadaten melden die Engine php_fallback mit der Zusammenfassungshardware cpu, und eine PSR-3-Warnung wird unter dem Ereignisnamen spectrum.optimize.fallback ausgegeben. Die Warnung trägt nur die Ausnahmeklasse und die Dokumentanzahl; es werden keine Dokumentbytes protokolliert. Im Fallback-Ergebnis liefert ein Analysefehler pro Dokument ein Element mit Fehlerstatus und Code SPEC-PARSE-001; andere Dokumente im Batch werden dennoch abgeschlossen.

Die Standard-Optimierungsstufe ist Balanced. Die Ergebnisfelder pro Element sind original_bytes, optimized_bytes, objects_removed, images_before, images_after, savings_percent und processing_time_ms.

Dokumentvergleich

compare läuft vollständig in PHP über den Pro-PdfDiffer: Strukturparsen, Textextraktion und der Diff-Algorithmus. In dieser Version wird keine Sidecar-Anfrage ausgelöst. Der Differ-Vertrag akzeptiert nur rohe PDF-Strings, sodass ein Sidecar-Parseergebnis nicht konsumiert werden kann; ein Auslagern würde Kosten ohne Nutzen verursachen. Ein injizierter Client wird für eine künftige Parse-Auslagerungsfunktion behalten. isSpectrumWired() legt den Verdrahtungszustand offen, ohne eine Anfrage auszulösen.

CPU-Embedding

embed delegiert an batchEmbed([$text]) und gibt Element null zurück. batchEmbed([]) wirft InvalidArgumentException, bevor das Sidecar kontaktiert wird. Ein nicht erreichbares Sidecar wirft SpectrumNotAvailableException. Die Batch-Semantik ist Alles-oder-nichts: ein Fehler pro Element, ein fehlender oder fehlerhafter Vektor oder eine Anzahlabweichung wirft SpectrumApiException (Protokoll-Form-Fehler tragen SPEC-IO-001), anstatt Teilvektoren zurückzugeben. Eine nicht numerische Komponente in einem zurückgegebenen Vektor wird zu 0.0 gecastet. getDimension gibt 384 zurück; getModelName gibt all-MiniLM-L6-v2 zurück. Das Sidecar lädt das ONNX-Modell verzögert bei der ersten Anfrage herunter und lädt es.

CPU-Vektorsuche

Jedes Handle bindet einen Collection-Identifier; jede Collection wird auf einen separaten In-Memory-HNSW-Index im Sidecar abgebildet. build erfordert gleich lange Vektor- und Identifierlisten und wirft andernfalls InvalidArgumentException; eine leere Eingabe kehrt ohne Sidecar-Aufruf zurück. search gibt geordnete Treffer mit einem einsbasierten Rang in den Metadaten jedes Ergebnisses zurück. Ein In-Band-Fehler-Envelope wirft SpectrumApiException; ein Envelope ohne Code wird auf SPEC-INDEX-003 abgebildet. delete lehnt stets mit SpectrumApiException SPEC-INDEX-004 (HTTP 501, nicht wiederholbar) ab, weil HNSW keine Löschung pro Vektor unterstützt; bauen Sie den Index stattdessen neu auf.

count ist fail-closed und eindeutig. Ein nicht erreichbares Sidecar wirft SpectrumNotAvailableException; Transport- und Sidecar-Fehler werden unverändert weitergereicht. Bei einer ansonsten erfolgreichen Antwort wirft ein Nicht-JSON-Body SPEC-INDEX-005, ein fehlendes metadata.total_vectors wirft SPEC-INDEX-006, und eine nicht ganzzahlige oder negative Gesamtzahl wirft SPEC-INDEX-007. count gibt 0 nur für einen bestätigt leeren Index zurück. Die Größenprüfung übermittelt einen Nullvektor mit genau INDEX_DIMENSION (384) Dimensionen und einem top_k von 0, sodass ein dimensionsvalidierendes Sidecar ihn akzeptiert.

Grenzfälle & Fehlermodi

• Der Sidecar-Speicher ist flüchtig: Ein Neustart löscht alle HNSW-Collections. Behandeln Sie den Indexaufbau als idempotent und führen Sie ihn nach einem Neustart erneut aus.
• Gemischte Verfügbarkeit innerhalb eines einzelnen Prozesses wird unterstützt: Der Optimierer stuft pro Aufruf herab; die Embedding- und Vektordienste scheitern geschlossen pro Aufruf.
• Ein Optimiererbatch über dem Limit scheitert geschlossen vor jedem Upload; er fällt nicht auf den PHP-Pfad zurück.
• Der Optimierer-Fallback scheitert niemals stillschweigend: Prüfen Sie den Engine-Marker in den Ergebnismetadaten und überwachen Sie das Warnereignis.
• count meldet ein nicht erreichbares Sidecar oder einen Protokollfehler niemals als 0; diese werfen typisierte Ausnahmen.
• Ein Suchtreffer ohne Identifier oder Score wird auf einen leeren String und 0.0 gesetzt, anstatt den Batch scheitern zu lassen.
• Ein top_k von 0 wird intern nur für die Zählprüfung verwendet; übergeben Sie für echte Suchen ein positives topK.
• Die erste Embedding-Anfrage trägt die einmaligen Kosten für Download und Laden des Modells; bemessen Sie dieses Timeout separat.
• Die Sidecar-Ausnahmehierarchie und die Fehlercodefamilien sind in der Accelerator-Fehlerreferenz katalogisiert.
• Dieses Modul führt keine kryptografischen Operationen durch und definiert kein FIPS-spezifisches Verhalten. Die FIPS-Modus-Haltung wird von den Signatur- und Compliance-Modulen bestimmt, nicht hier.

Konformität

Accelerator delegiert formatbeeinflussende Arbeit an die Optimizer- und Diff-Module und behauptet keine eigenständige Formatkonformität. Die Konformität für die delegierte Arbeit ist auf den Referenzseiten von Optimizer und Diff dokumentiert. Diese Seite beansprucht keine externen Klausel-Identifier; jede Aussage ist im Produktquellcode verankert. NextPDF erhebt keinen Zertifizierungsanspruch.

Entwicklungshinweise

• Der Modulquellcode trägt @since 2.1.0; diese Referenz dokumentiert die Oberfläche, wie sie in nextpdf/pro 3.1.0 ausgeliefert wird.
• Alle Klassen sind final und verwenden Constructor Injection; erzeugen Sie neue Instanzen, anstatt zu mutieren.
• SpectrumClient, VectorSearchResult, BatchResultInterface sowie die Verträge EmbeddingServiceInterface und VectorIndexInterface stammen aus NextPDF Core; der Aufrufer erzeugt und liefert den Sidecar-Client.
• OptimizationLevel, PdfOptimizer und PdfDiffer stammen aus den Pro-Modulen Optimizer und Diff; ihre Semantik ist auf jenen Referenzseiten dokumentiert.
• Der Embedding-Dienst und der Vektorindex teilen sich die Dimension 384. Bauen Sie Indexvektoren mit derselben Dimension wie die Embeddings, die sie abfragen.
• Interne Mechanismusdetails verbleiben in der internen Dokumentation des Quellrepositorys und liegen außerhalb des Umfangs dieses Handbuchs.

Publikationsgrenze

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

Siehe auch

• Accelerator — die Funktionsseite für die Anleitung zum Arbeitsablauf.
• Accelerator-Fehlerreferenz — Sidecar-Ausnahmehierarchie und Fehlercodes.
• Optimizer — Ausführliche Referenz
• Diff — Ausführliche Referenz
• Accelerator — NextPDF Enterprise Ausführliche Referenz