Accelerator — référence détaillée

En bref

Cette page est la référence détaillée de la surface d’accélération publique de NextPDF\Pro\Accelerator. Elle couvre la fabrique de fournisseur, l’optimiseur de lots accéléré, le wrapper de comparaison, ainsi que les services CPU du sidecar pour l’embedding et la recherche vectorielle. Elle précise les paramètres, les valeurs par défaut, les modes de défaillance et la sémantique de repli. Lis d’abord la page de capacité Accelerator pour des conseils de flux de travail.

Disponibilité et licence

Cette capacité est fournie dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de palier Pro. Un déploiement sans ce droit ne charge pas les classes de la capacité. Compare les éditions et obtiens une licence.

Accelerator n’a pas d’indicateur de licence par fonctionnalité. Le code est fourni avec l’édition Pro ; le chemin de l’optimiseur accéléré est sélectionné à l’exécution par une sonde d’accessibilité du sidecar. Le service d’embedding et l’index vectoriel n’ont pas de repli PHP et échouent de manière fermée lorsque le sidecar est inaccessible.

Surface d’API publique

composer require nextpdf/pro:^3

Le métapaquet nextpdf/premium installe le code nextpdf/pro ; ce module réside dans l’espace de noms NextPDF\Pro\Accelerator.

Symbole	Paramètres	Comportement par défaut	Retour	Lève ou échoue avec	Notes
ProAcceleratorProvider::__construct	SpectrumClient $client	Lie le fournisseur à un client sidecar Core	ProAcceleratorProvider	Rien de déclaré	L’appelant construit et fournit le client
ProAcceleratorProvider::isAvailable	aucun	Sonde l’accessibilité du sidecar via le client	bool	Rien de déclaré	Accessibilité uniquement ; les points de terminaison sont sondés à chaque appel
ProAcceleratorProvider::embedding	aucun	Renvoie le service d’embedding mémoïsé	EmbeddingServiceInterface	Rien de déclaré	Une instance CpuEmbeddingService par fournisseur
ProAcceleratorProvider::vectorIndex	string $collectionId = 'default'	Renvoie un nouveau handle d’index lié à la collection	VectorIndexInterface	Rien de déclaré	Non mémoïsé ; un handle par appel
ProAcceleratorProvider::optimizer	aucun	Renvoie l’optimiseur accéléré mémoïsé	AcceleratedOptimizer	Rien de déclaré	Construit avec le client du fournisseur
ProAcceleratorProvider::differ	aucun	Renvoie le wrapper de comparaison mémoïsé	AcceleratedDiffer	Rien de déclaré	Construit avec le client du fournisseur
AcceleratedOptimizer::__construct	?SpectrumClient $spectrum = null, OptimizationLevel $level = OptimizationLevel::Balanced, ?LoggerInterface $logger = null	Enveloppe le PdfOptimizer PHP au niveau indiqué	AcceleratedOptimizer	Rien de déclaré	Un client null sélectionne le chemin PHP ; un logger null sélectionne NullLogger
AcceleratedOptimizer::optimizeBatch	array<string, string> $documents	Analyse chaque document ; délègue le travail sur images au sidecar quand il est accessible	BatchResultInterface	SpectrumApiException SPEC-SEC-001 (HTTP 413) sur un lot hors limite ; marqueurs d’erreur par élément dans le résultat de repli	Les échecs de transport après admission se rabattent sur le chemin PHP
AcceleratedDiffer::__construct	?SpectrumClient $spectrum = null	Conserve le client optionnel pour la compatibilité future	AcceleratedDiffer	Rien de déclaré	Le client n’est pas utilisé dans cette version
AcceleratedDiffer::compare	string $sourcePdf, string $targetPdf	Compare deux documents entièrement en PHP	DiffResult	Comme le PdfDiffer Pro	Aucune requête sidecar n’est émise dans cette version
AcceleratedDiffer::isSpectrumWired	aucun	Indique si un client sidecar a été injecté	bool	Rien de déclaré	État de câblage uniquement ; n’émet aucune requête
CpuEmbeddingService::embed	string $text	Délègue à batchEmbed et renvoie l’élément zéro	list<float>	Comme batchEmbed	Vecteur de dimension 384
CpuEmbeddingService::batchEmbed	array $texts	Calcule l’embedding du lot sur le sidecar	list<list<float>>	InvalidArgumentException sur un lot vide ; SpectrumNotAvailableException en cas d’inaccessibilité ; SpectrumApiException sur une réponse en échec, malformée ou de cardinalité incohérente	Ne renvoie jamais de résultats partiels
CpuEmbeddingService::getDimension	aucun	Renvoie 384	int	Rien de déclaré	Constante
CpuEmbeddingService::getModelName	aucun	Renvoie all-MiniLM-L6-v2	string	Rien de déclaré	Constante
CpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Lie le handle à une seule collection	CpuVectorIndex	Rien de déclaré	Un handle par identifiant de collection
CpuVectorIndex::build	array $vectors, array $ids	Construit l’index de la collection sur le sidecar	void	InvalidArgumentException sur une incohérence de longueur ; SpectrumNotAvailableException en cas d’inaccessibilité	Une entrée vide se termine sans contacter le sidecar
CpuVectorIndex::search	array $queryVector, int $topK = 10	Recherche des plus proches voisins classée	list<VectorSearchResult>	SpectrumNotAvailableException en cas d’inaccessibilité ; SpectrumApiException sur une enveloppe d’erreur en bande ; JsonException sur un corps malformé	Rang par résultat dans les métadonnées
CpuVectorIndex::delete	array $ids	Rejette toujours	void (déclaré)	Toujours : SpectrumApiException SPEC-INDEX-004 (HTTP 501)	HNSW ne permet pas la suppression par vecteur ; reconstruis à la place
CpuVectorIndex::count	aucun	Lit le total de la collection via une sonde dimensionnée	int	SpectrumNotAvailableException en cas d’inaccessibilité ; SpectrumApiException sur une erreur ou une réponse de comptage malformée	Renvoie 0 uniquement pour un index confirmé vide
CpuVectorIndex::INDEX_DIMENSION	—	Constante publique 384	int	—	Correspond à la dimension d’embedding

Signatures des points d’entrée

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
}

Contrat de comportement

Fournisseur

ProAcceleratorProvider est le point d’entrée. embedding(), optimizer() et differ() mémoïsent leurs instances. vectorIndex($collectionId) renvoie un nouveau handle à chaque appel, lié à l’identifiant de collection fourni. isAvailable() sonde l’accessibilité du sidecar via le SpectrumClient Core injecté.

Optimisation par lots

optimizeBatch renvoie un résultat de lot indexé par les identifiants de document de l’appelant. Lorsque le sidecar est accessible, la charge utile agrégée est validée par rapport au budget du client avant toute mise en tampon ou tout envoi. Un lot hors limite échoue de manière fermée avec SpectrumApiException SPEC-SEC-001 (HTTP 413) ; il ne se rabat jamais sur le chemin PHP. Un lot admis est expédié au sidecar pour un travail d’images en parallèle.

Un échec de transport, d’authentification ou d’analyse de réponse après admission se rabat sur l’optimiseur PHP, qui analyse chaque document de manière séquentielle. La dégradation est observable deux fois : les métadonnées du résultat signalent le moteur php_fallback avec le matériel de synthèse cpu, et un avertissement PSR-3 est émis sous le nom d’événement spectrum.optimize.fallback. L’avertissement ne porte que la classe d’exception et le nombre de documents ; aucun octet de document n’est journalisé. Dans le résultat de repli, un échec d’analyse par document produit un élément au statut d’erreur avec le code SPEC-PARSE-001 ; les autres documents du lot se terminent quand même.

Le niveau d’optimisation par défaut est Balanced. Les champs de résultat par élément sont original_bytes, optimized_bytes, objects_removed, images_before, images_after, savings_percent et processing_time_ms.

Comparaison de documents

compare s’exécute entièrement en PHP via le PdfDiffer Pro : analyse de structure, extraction de texte et algorithme de comparaison. Aucune requête sidecar n’est émise dans cette version. Le contrat de comparaison n’accepte que des chaînes PDF brutes, si bien qu’un résultat d’analyse du sidecar ne peut pas être consommé ; la délégation ajouterait un coût sans bénéfice. Un client injecté est conservé pour une future fonctionnalité de délégation de l’analyse. isSpectrumWired() expose l’état de câblage sans émettre de requête.

Embedding CPU

embed délègue à batchEmbed([$text]) et renvoie l’élément zéro. batchEmbed([]) lève InvalidArgumentException avant de contacter le sidecar. Un sidecar inaccessible lève SpectrumNotAvailableException. La sémantique de lot est du tout ou rien : un échec par élément, un vecteur manquant ou malformé, ou une cardinalité incohérente lève SpectrumApiException (les échecs de forme de protocole portent SPEC-IO-001) au lieu de renvoyer des vecteurs partiels. Un composant non numérique à l’intérieur d’un vecteur renvoyé est converti en 0.0. getDimension renvoie 384 ; getModelName renvoie all-MiniLM-L6-v2. Le sidecar télécharge et charge le modèle ONNX de manière paresseuse à la première requête.

Recherche vectorielle CPU

Chaque handle lie un identifiant de collection ; chaque collection correspond à un index HNSW en mémoire distinct dans le sidecar. build exige des listes de vecteurs et d’identifiants de même longueur et lève InvalidArgumentException sinon ; une entrée vide se termine sans appel au sidecar. search renvoie des résultats classés avec un rang commençant à un dans les métadonnées de chaque résultat. Une enveloppe d’erreur en bande lève SpectrumApiException ; une enveloppe sans code correspond à SPEC-INDEX-003. delete rejette toujours avec SpectrumApiException SPEC-INDEX-004 (HTTP 501, non réessayable) car HNSW ne prend pas en charge la suppression par vecteur ; reconstruis plutôt l’index.

count échoue de manière fermée et sans ambiguïté. Un sidecar inaccessible lève SpectrumNotAvailableException ; les erreurs de transport et du sidecar se propagent inchangées. Sur une réponse par ailleurs réussie, un corps non JSON lève SPEC-INDEX-005, un metadata.total_vectors manquant lève SPEC-INDEX-006, et un total non entier ou négatif lève SPEC-INDEX-007. count renvoie 0 uniquement pour un index confirmé vide. La sonde de taille soumet un vecteur nul d’exactement INDEX_DIMENSION (384) dimensions avec un top_k de 0, de sorte qu’un sidecar validant la dimension l’accepte.

Cas limites et modes de défaillance

• La mémoire du sidecar est volatile : un redémarrage efface toutes les collections HNSW. Traite la construction d’index comme idempotente et relance-la après un redémarrage.
• La disponibilité mixte au sein d’un même processus est prise en charge : l’optimiseur se dégrade à chaque appel ; les services d’embedding et vectoriel échouent de manière fermée à chaque appel.
• Un lot d’optimiseur hors limite échoue de manière fermée avant tout envoi ; il ne se rabat pas sur le chemin PHP.
• Le repli de l’optimiseur n’échoue jamais en silence : vérifie le marqueur de moteur dans les métadonnées du résultat et surveille l’événement d’avertissement.
• count ne signale jamais un sidecar inaccessible ou une erreur de protocole comme 0 ; ceux-ci lèvent des exceptions typées.
• Un résultat de recherche dépourvu de son identifiant ou de son score prend par défaut une chaîne vide et 0.0 au lieu de faire échouer le lot.
• Un top_k de 0 n’est utilisé en interne que pour la sonde de comptage ; passe un topK positif pour les recherches réelles.
• La première requête d’embedding paie le coût unique de téléchargement et de chargement du modèle ; dimensionne ce délai d’attente séparément.
• La hiérarchie d’exceptions du sidecar et les familles de codes d’erreur sont cataloguées dans la référence des erreurs Accelerator.
• Ce module n’effectue aucune opération cryptographique et ne définit aucun comportement propre à FIPS. La posture en mode FIPS est régie par les modules de signature et de conformité, pas ici.

Conformité

Accelerator délègue le travail affectant le format aux modules Optimizer et Diff et n’affirme aucune conformité de format indépendante. La conformité du travail délégué est documentée sur les pages de référence Optimizer et Diff. Cette page ne revendique aucun identifiant de clause externe ; chaque affirmation est fondée sur le code source du produit. NextPDF ne formule aucune revendication de certification.

Notes de développement

• Le code source du module porte @since 2.1.0 ; cette référence documente la surface telle que livrée dans nextpdf/pro 3.1.0.
• Toutes les classes sont final et utilisent l’injection par constructeur ; construis de nouvelles instances plutôt que de muter.
• SpectrumClient, VectorSearchResult, BatchResultInterface, ainsi que les contrats EmbeddingServiceInterface et VectorIndexInterface proviennent de NextPDF Core ; l’appelant construit et fournit le client sidecar.
• OptimizationLevel, PdfOptimizer et PdfDiffer proviennent des modules Optimizer et Diff Pro ; leur sémantique est documentée sur ces pages de référence.
• Le service d’embedding et l’index vectoriel partagent la dimension 384. Construis les vecteurs d’index à la même dimension que les embeddings qui les interrogent.
• Le détail des mécanismes internes reste dans la documentation interne du dépôt source et est hors du périmètre de ce manuel.

Périmètre de publication

Cette page ne documente que le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espaces de noms internes, les classes utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.

Voir aussi

• Accelerator — la page de capacité pour des conseils de flux de travail.
• Référence des erreurs Accelerator — hiérarchie d’exceptions du sidecar et codes d’erreur.
• Optimizer — référence détaillée
• Diff — référence détaillée
• Accelerator — référence détaillée NextPDF Enterprise