Accélérateur

En bref

Accelerator décharge la recompression d’images par lot, l’analyse de PDF et l’intégration de texte vers un sidecar CPU colocalisé. Lorsque le sidecar est injoignable, chaque opération se rabat sur le chemin PHP en mémoire (in-process), de sorte que les appelants observent les mêmes résultats dans les deux cas.

Disponibilité et licence

Cette capacité est livrée 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é. Comparer les éditions et obtenir une licence.

Accelerator n’a aucun indicateur distinct par fonctionnalité. Le chemin accéléré est sélectionné à l’exécution par une vérification d’accessibilité du sidecar (ProAcceleratorProvider::isAvailable()) ; lorsque le sidecar est injoignable, le chemin PHP en mémoire (in-process) s’exécute à la place.

Installation

composer require nextpdf/pro:^3

Le paquet Premium installe le code nextpdf/pro sous l’espace de noms NextPDF\Pro\Accelerator. Le métapaquet nextpdf/premium installe également des capacités Enterprise ; Accelerator lui-même est une fonctionnalité du palier Pro.

Vue d’ensemble conceptuelle

ProAcceleratorProvider est le point d’entrée. Il construit paresseusement quatre services :

• Un optimiseur accéléré qui enveloppe le PdfOptimizer de Pro et décharge le travail d’images par lot vers le sidecar.
• Un comparateur (differ) accéléré qui enveloppe le PdfDiffer de Pro ; le sidecar parallélise l’analyse de structure tandis que l’algorithme de diff lui-même s’exécute en PHP.
• Un service d’intégration CPU qui renvoie des vecteurs de 384 dimensions à l’aide d’un modèle ONNX all-MiniLM-L6-v2 hébergé par le sidecar.
• Un index vectoriel CPU qui construit et recherche un index HNSW en mémoire indexé par un identifiant de collection.

La conception garde la logique métier en PHP. Le sidecar effectue le travail parallélisable et lié au CPU (transcodage d’images, analyse multi-documents, inférence ONNX, recherche vectorielle). Chaque chemin accéléré a un repli PHP déterministe qui produit des résultats équivalents.

Pourquoi cela fonctionne ainsi

La décision porteuse est que l’exactitude ne dépend jamais du sidecar. La logique métier reste en PHP ; le sidecar effectue uniquement le travail parallélisable et lié au CPU. L’optimiseur et le comparateur (AcceleratedOptimizer, AcceleratedDiffer) conservent un repli PHP déterministe, de sorte qu’un sidecar absent modifie le temps d’exécution, pas les résultats. Seules les deux opérations sans équivalent PHP — CpuEmbeddingService et CpuVectorIndex — échouent en mode fermé (fail closed) au lieu de se dégrader. Une réponse fausse et silencieuse à cet endroit serait pire qu’une erreur explicite. Cette séparation permet au débit d’évoluer avec les cœurs du sidecar tandis que les appelants conservent un seul chemin de code et une seule frontière de confiance.

Contexte de conception : Génération de documents à haut volume.

Contrat de comportement

• ProAcceleratorProvider::isAvailable() renvoie si le sidecar répond. Les appelants peuvent se brancher dessus, mais n’y sont pas tenus : l’optimiseur et le comparateur se rabattent automatiquement.
• embedding()->embed() renvoie un seul vecteur de 384 éléments ; batchEmbed() renvoie un vecteur par entrée et rejette une liste d’entrées vide avec InvalidArgumentException.
• vectorIndex($collectionId)->build() exige que vectors et ids aient la même longueur et traite une entrée vide comme un no-op.
• vectorIndex()->search($queryVector, $topK) renvoie des résultats classés ; delete() n’est pas pris en charge pour l’index HNSW et rejette l’appel — les appelants reconstruisent l’index à la place.
• Le service d’intégration et l’index vectoriel nécessitent le sidecar ; ils lèvent une erreur « non disponible » plutôt que de se dégrader silencieusement, car il n’existe aucun équivalent PHP pour l’inférence ONNX ou la recherche HNSW.
• L’optimiseur et le comparateur ne lèvent jamais d’erreur sur un échec du sidecar ; ils se dégradent vers le chemin PHP de manière transparente.

Exemple de code — Démarrage rapide

Ce qui suit reflète l’API publique documentée (ProAcceleratorProvider). Le dépôt ne livre pas d’exemple exécutable pour ce module.

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

Exemple de code — Production

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

Câble ProAcceleratorProvider à travers ton conteneur en singleton afin que les instances d’optimiseur et de comparateur soient réutilisées. Traite les appels d’intégration et d’index vectoriel comme nécessitant le sidecar.

Cas limites & pièges

• L’index vectoriel réside dans la mémoire du processus sidecar et est indexé par identifiant de collection. Un redémarrage du sidecar efface tous les index ; reconstruis après un redémarrage.
• count() sur l’index vectoriel renvoie 0 lorsque le sidecar est injoignable plutôt que de lever une erreur.
• L’accélération de l’optimiseur et du comparateur est au mieux (best-effort) ; une erreur du sidecar en milieu de lot provoque un repli silencieux pour cet appel, de sorte que le temps — et non l’exactitude — varie.

Performance

L’accélération cible le travail par lot lié au CPU : transcodage d’images parallèle, analyse multi-documents et recherche vectorielle. NextPDF ne publie pas de multiplicateur de débit fixe ici ; les gains dépendent du mélange de documents, de la densité d’images, du nombre de cœurs du sidecar et de la taille du lot. Mesure dans ton environnement avant de te fier à un chiffre précis. Le repli PHP est mono-thread par conception.

Notes de sécurité

Ce module envoie des documents et des vecteurs au sidecar colocalisé via son transport configuré. Traite le sidecar comme faisant partie de ta frontière de confiance et déploie-le sur le même hôte ou un segment de réseau privé. Le module valide la taille et la forme de l’entrée avant la distribution. Il ne journalise aucun contenu de document.

Conformité

Ce module n’effectue lui-même aucun travail de conformité de format ; il délègue l’optimisation et le diff aux modules Optimizer et Diff de Pro. Voir ces modules pour les références ISO 32000-2. Les preuves de conformité de cette page proviennent des contrats de classes publiques documentés et de leurs tests unitaires ; le corpus RAG était indisponible au moment de la rédaction, donc aucun identifiant de clause externe n’est affirmé ici.

Note sur la frontière Enterprise

Enterprise ne change pas le comportement d’Accelerator. Enterprise ajoute des fonctionnalités de conformité, d’archivage et de cycle de vie de signature de palier supérieur documentées ailleurs ; celles-ci sont hors du périmètre de ce module et ne sont pas requises pour utiliser Accelerator.

Repli sur le Core / alternative

Sans Pro, utilise l’optimisation et le diff en mémoire (in-process) de NextPDF Core. Les chemins accélérés de ce module se réduisent à ce même comportement PHP lorsque le sidecar est absent.

Frontière de publication

Cette page documente uniquement 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 auxiliaires, 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 — Référence approfondie
• Optimizer
• Diff
• Output Pipeline