Accelerator — Diepe referentie

In het kort

Deze pagina is de diepe referentie voor het publieke versnellingsoppervlak van NextPDF\Pro\Accelerator. Ze behandelt de provider-factory, de versnelde batch-optimizer, de differ-wrapper en de CPU sidecar-services voor embedding en vector search. Ze benoemt parameters, standaardwaarden, faalmodi en fallback-semantiek. Lees eerst de Accelerator-capaciteitspagina voor workflow-begeleiding.

Beschikbaarheid en licentie

Deze capaciteit wordt geleverd in NextPDF Pro (nextpdf/pro) en activeert met een Pro-tier license envelope. Een deployment zonder die entitlement laadt de klassen van de capaciteit niet. Vergelijk edities en vraag een licentie aan.

Accelerator heeft geen per-feature licentie-flag. De code wordt met de Pro-editie geleverd; het versnelde optimizer-pad wordt tijdens runtime geselecteerd door een sidecar-bereikbaarheidsprobe. De embedding-service en de vector-index hebben geen PHP-fallback en falen gesloten wanneer de sidecar onbereikbaar is.

Publiek API-oppervlak

composer require nextpdf/pro:^3

Het nextpdf/premium metapackage installeert de nextpdf/pro-code; deze module bevindt zich onder de NextPDF\Pro\Accelerator-namespace.

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of faalt met	Opmerkingen
ProAcceleratorProvider::__construct	SpectrumClient $client	Bindt de provider aan een Core sidecar-client	ProAcceleratorProvider	Niets gedeclareerd	De caller construeert en levert de client
ProAcceleratorProvider::isAvailable	geen	Probet sidecar-bereikbaarheid via de client	bool	Niets gedeclareerd	Alleen bereikbaarheid; endpoints worden per aanroep geprobet
ProAcceleratorProvider::embedding	geen	Retourneert de gememoïzeerde embedding-service	EmbeddingServiceInterface	Niets gedeclareerd	Eén CpuEmbeddingService-instance per provider
ProAcceleratorProvider::vectorIndex	string $collectionId = 'default'	Retourneert een verse index-handle gebonden aan de collectie	VectorIndexInterface	Niets gedeclareerd	Niet gememoïzeerd; één handle per aanroep
ProAcceleratorProvider::optimizer	geen	Retourneert de gememoïzeerde versnelde optimizer	AcceleratedOptimizer	Niets gedeclareerd	Geconstrueerd met de client van de provider
ProAcceleratorProvider::differ	geen	Retourneert de gememoïzeerde differ-wrapper	AcceleratedDiffer	Niets gedeclareerd	Geconstrueerd met de client van de provider
AcceleratedOptimizer::__construct	?SpectrumClient $spectrum = null, OptimizationLevel $level = OptimizationLevel::Balanced, ?LoggerInterface $logger = null	Wrapt de PHP-PdfOptimizer op het gegeven niveau	AcceleratedOptimizer	Niets gedeclareerd	Een null-client selecteert het PHP-pad; een null-logger selecteert NullLogger
AcceleratedOptimizer::optimizeBatch	array<string, string> $documents	Analyseert elk document; verplaatst afbeeldingswerk naar de sidecar wanneer bereikbaar	BatchResultInterface	SpectrumApiException SPEC-SEC-001 (HTTP 413) bij een batch boven de limiet; per-item foutmarkers in het fallback-resultaat	Transportfouten na toelating degraderen naar het PHP-pad
AcceleratedDiffer::__construct	?SpectrumClient $spectrum = null	Behoudt de optionele client voor voorwaartse compatibiliteit	AcceleratedDiffer	Niets gedeclareerd	De client wordt in deze release niet gebruikt
AcceleratedDiffer::compare	string $sourcePdf, string $targetPdf	Vergelijkt twee documenten volledig in PHP	DiffResult	Zoals de Pro-PdfDiffer	In deze release wordt geen sidecar-verzoek uitgevoerd
AcceleratedDiffer::isSpectrumWired	geen	Rapporteert of er een sidecar-client is geïnjecteerd	bool	Niets gedeclareerd	Alleen bedradingsstatus; voert geen verzoek uit
CpuEmbeddingService::embed	string $text	Delegeert naar batchEmbed en retourneert element nul	list<float>	Zoals batchEmbed	384-dimensionale vector
CpuEmbeddingService::batchEmbed	array $texts	Embed de batch op de sidecar	list<list<float>>	InvalidArgumentException bij een lege batch; SpectrumNotAvailableException bij onbereikbaarheid; SpectrumApiException bij een mislukte, misvormde of in aantal niet-overeenkomende respons	Retourneert nooit gedeeltelijke resultaten
CpuEmbeddingService::getDimension	geen	Retourneert 384	int	Niets gedeclareerd	Constante
CpuEmbeddingService::getModelName	geen	Retourneert all-MiniLM-L6-v2	string	Niets gedeclareerd	Constante
CpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Bindt de handle aan één collectie	CpuVectorIndex	Niets gedeclareerd	Eén handle per collectie-identifier
CpuVectorIndex::build	array $vectors, array $ids	Bouwt de collectie-index op de sidecar	void	InvalidArgumentException bij een lengteverschil; SpectrumNotAvailableException bij onbereikbaarheid	Een lege invoer retourneert zonder de sidecar te contacteren
CpuVectorIndex::search	array $queryVector, int $topK = 10	Gerangschikte nearest-neighbor-zoekopdracht	list<VectorSearchResult>	SpectrumNotAvailableException bij onbereikbaarheid; SpectrumApiException bij een in-band foutenvelop; JsonException bij een misvormde body	Per-hit-rang in de resultaatmetadata
CpuVectorIndex::delete	array $ids	Wijst altijd af	void (gedeclareerd)	Altijd: SpectrumApiException SPEC-INDEX-004 (HTTP 501)	HNSW heeft geen per-vector-verwijdering; herbouw in plaats daarvan
CpuVectorIndex::count	geen	Leest het collectietotaal via een gedimensioneerde probe	int	SpectrumNotAvailableException bij onbereikbaarheid; SpectrumApiException bij een fout of een misvormde count-respons	Retourneert 0 alleen voor een bevestigd-lege index
CpuVectorIndex::INDEX_DIMENSION	—	Publieke constante 384	int	—	Komt overeen met de embedding-dimensie

Entry-point-signaturen

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
}

Gedragscontract

Provider

ProAcceleratorProvider is het entry-point. embedding(), optimizer() en differ() memoizen hun instances. vectorIndex($collectionId) retourneert per aanroep een verse handle, gebonden aan de gegeven collectie-identifier. isAvailable() probet sidecar-bereikbaarheid via de geïnjecteerde Core-SpectrumClient.

Batch-optimalisatie

optimizeBatch retourneert een batchresultaat met de document-identifiers van de caller als sleutels. Wanneer de sidecar bereikbaar is, wordt de geaggregeerde payload gevalideerd tegen het client-budget vóór enige buffering of upload. Een batch boven de limiet faalt gesloten met SpectrumApiException SPEC-SEC-001 (HTTP 413); het degradeert nooit naar het PHP-pad. Een toegelaten batch wordt naar de sidecar gedispatcht voor parallel afbeeldingswerk.

Een transport-, authenticatie- of respons-parse-fout na toelating degradeert naar de PHP-optimizer, die elk document sequentieel analyseert. De degradatie is tweemaal waarneembaar: de resultaatmetadata rapporteert engine php_fallback met summary-hardware cpu, en er wordt een PSR-3-waarschuwing uitgezonden onder de event-naam spectrum.optimize.fallback. De waarschuwing bevat alleen de exception-klasse en het documentaantal; er worden geen document-bytes gelogd. In het fallback-resultaat levert een per-document-analysefout een item op met foutstatus en code SPEC-PARSE-001; andere documenten in de batch worden nog steeds voltooid.

Het standaard optimalisatieniveau is Balanced. De per-item resultaatvelden zijn original_bytes, optimized_bytes, objects_removed, images_before, images_after, savings_percent en processing_time_ms.

Document-diff

compare draait volledig in PHP via de Pro-PdfDiffer: structuurparsing, tekstextractie en het diff-algoritme. In deze release wordt geen sidecar-verzoek uitgevoerd. Het differ-contract accepteert alleen ruwe PDF-strings, dus een sidecar-parseresultaat kan niet worden geconsumeerd; offloaden zou kosten toevoegen zonder voordeel. Een geïnjecteerde client wordt behouden voor een toekomstige parse-offload-functie. isSpectrumWired() legt de bedradingsstatus bloot zonder een verzoek uit te voeren.

CPU embedding

embed delegeert naar batchEmbed([$text]) en retourneert element nul. batchEmbed([]) werpt InvalidArgumentException vóór het contacteren van de sidecar. Een onbereikbare sidecar werpt SpectrumNotAvailableException. De batch-semantiek is alles-of-niets: een per-item-fout, een ontbrekende of misvormde vector, of een aantalverschil werpt SpectrumApiException (protocol-vormfouten dragen SPEC-IO-001) in plaats van gedeeltelijke vectoren te retourneren. Een niet-numerieke component binnen een geretourneerde vector wordt gecoerceerd naar 0.0. getDimension retourneert 384; getModelName retourneert all-MiniLM-L6-v2. De sidecar downloadt en laadt het ONNX-model lui bij het eerste verzoek.

CPU vector search

Elke handle bindt één collectie-identifier; elke collectie mapt naar een aparte in-memory HNSW-index in de sidecar. build vereist vector- en identifier-lijsten van gelijke lengte en werpt anders InvalidArgumentException; een lege invoer retourneert zonder een sidecar-aanroep. search retourneert gerangschikte hits met een op-één-gebaseerde rang in de metadata van elk resultaat. Een in-band foutenvelop werpt SpectrumApiException; een envelop zonder code mapt naar SPEC-INDEX-003. delete wijst altijd af met SpectrumApiException SPEC-INDEX-004 (HTTP 501, niet herhaalbaar) omdat HNSW geen per-vector-verwijdering ondersteunt; herbouw in plaats daarvan de index.

count is fail-closed en ondubbelzinnig. Een onbereikbare sidecar werpt SpectrumNotAvailableException; transport- en sidecar-fouten propageren ongewijzigd. Bij een verder succesvolle respons werpt een niet-JSON-body SPEC-INDEX-005, een ontbrekende metadata.total_vectors werpt SPEC-INDEX-006, en een niet-geheel of negatief totaal werpt SPEC-INDEX-007. count retourneert 0 alleen voor een bevestigd-lege index. De grootteprobe stuurt een nulvector van precies INDEX_DIMENSION (384) dimensies met een top_k van 0, zodat een dimensie-valideerende sidecar hem accepteert.

Randgevallen en faalmodi

• Sidecar-geheugen is volatiel: een herstart wist alle HNSW-collecties. Behandel de index-build als idempotent en draai opnieuw na een herstart.
• Gemengde beschikbaarheid binnen één proces wordt ondersteund: de optimizer degradeert per aanroep; de embedding- en vectorservices falen gesloten per aanroep.
• Een optimizer-batch boven de limiet faalt gesloten vóór enige upload; het valt niet terug op het PHP-pad.
• De optimizer-fallback faalt nooit stilzwijgend: controleer de engine-marker in de resultaatmetadata en monitor het waarschuwingsevent.
• count rapporteert een onbereikbare sidecar of een protocolfout nooit als 0; die werpen getypeerde excepties.
• Een zoekhit zonder identifier of score valt terug op een lege string en 0.0 in plaats van de batch te laten falen.
• Een top_k van 0 wordt intern alleen gebruikt voor de count-probe; geef een positieve topK door voor echte zoekopdrachten.
• Het eerste embedding-verzoek betaalt de eenmalige kosten voor het downloaden en laden van het model; dimensioneer die timeout apart.
• De sidecar-exceptiehiërarchie en de error-code-families zijn gecatalogiseerd in de Accelerator-foutreferentie.
• Deze module voert geen cryptografische bewerkingen uit en definieert geen FIPS-specifiek gedrag. De FIPS-moduspositie wordt geregeld door de signing- en compliance-modules, niet hier.

Conformiteit

Accelerator delegeert formaatbeïnvloedend werk naar de Optimizer- en Diff-modules en doet geen onafhankelijke formaatconformiteitsbewering. Conformiteit voor het gedelegeerde werk is gedocumenteerd op de referentiepagina’s van Optimizer en Diff. Deze pagina claimt geen externe clausule-identifiers; elke uitspraak is gefundeerd in de productbron. NextPDF doet geen certificeringsbewering.

Ontwikkelnotities

• De modulebron draagt @since 2.1.0; deze referentie documenteert het oppervlak zoals geleverd in nextpdf/pro 3.1.0.
• Alle klassen zijn final en gebruiken constructor-injectie; construeer nieuwe instances in plaats van te muteren.
• SpectrumClient, VectorSearchResult, BatchResultInterface en de EmbeddingServiceInterface- en VectorIndexInterface-contracten komen uit NextPDF Core; de caller construeert en levert de sidecar-client.
• OptimizationLevel, PdfOptimizer en PdfDiffer komen uit de Pro Optimizer- en Diff-modules; hun semantiek is gedocumenteerd op die referentiepagina’s.
• De embedding-service en de vector-index delen de 384-dimensie. Bouw index-vectoren op dezelfde dimensie als de embeddings die ze bevragen.
• Interne mechanismedetails blijven in de interne documentatie van de bronrepository en vallen buiten de scope van deze handleiding.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-klassen, mechanismetabellen, runbook-bestandsnamen en ticket-prefixen vallen buiten de scope.

Zie ook

• Accelerator — de capaciteitspagina voor workflow-begeleiding.
• Accelerator-foutreferentie — sidecar-exceptiehiërarchie en error-codes.
• Optimizer — Diepe referentie
• Diff — Diepe referentie
• Accelerator — NextPDF Enterprise Diepe referentie