Accelerator

De un vistazo

Accelerator descarga la recompresión de imágenes por lotes, el análisis de PDF y la incrustación de texto a un sidecar de CPU colocado junto a la aplicación. Cuando el sidecar no es alcanzable, cada operación recurre a la ruta de PHP en proceso, de modo que los llamantes observan los mismos resultados en cualquier caso.

Disponibilidad y licencias

Esta capacidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia del nivel Pro. Un despliegue sin ese derecho no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Accelerator no tiene ningún indicador por función independiente. La ruta acelerada se selecciona en tiempo de ejecución mediante una comprobación de accesibilidad del sidecar (ProAcceleratorProvider::isAvailable()); cuando el sidecar no es alcanzable, se ejecuta en su lugar la ruta de PHP en proceso.

Instalación

composer require nextpdf/pro:^3

El paquete Premium instala el código de nextpdf/pro bajo el espacio de nombres NextPDF\Pro\Accelerator. El metapaquete nextpdf/premium también instala las capacidades de Enterprise; Accelerator en sí es una función del nivel Pro.

Descripción conceptual

ProAcceleratorProvider es el punto de entrada. Construye de forma diferida (lazy) cuatro servicios:

• Un optimizador acelerado que envuelve el PdfOptimizer de Pro y descarga el trabajo de imágenes por lotes al sidecar.
• Un comparador acelerado que envuelve el PdfDiffer de Pro; el sidecar paraleliza el análisis de estructura mientras que el propio algoritmo de comparación se ejecuta en PHP.
• Un servicio de incrustación de CPU que devuelve vectores de 384 dimensiones usando un modelo ONNX all-MiniLM-L6-v2 alojado por el sidecar.
• Un índice vectorial de CPU que construye y busca un índice HNSW en memoria indexado por un identificador de colección.

El diseño mantiene la lógica de dominio en PHP. El sidecar realiza el trabajo paralelizable, limitado por CPU (transcodificación de imágenes, análisis multidocumento, inferencia ONNX, búsqueda vectorial). Cada ruta acelerada tiene una alternativa de PHP determinista que produce resultados equivalentes.

Por qué funciona así

La decisión de mayor peso es que la corrección nunca depende del sidecar. La lógica de dominio permanece en PHP; el sidecar solo realiza el trabajo paralelizable, limitado por CPU. El optimizador y el comparador (AcceleratedOptimizer, AcceleratedDiffer) mantienen una alternativa de PHP determinista, de modo que la ausencia de sidecar cambia el tiempo, no los resultados. Solo las dos operaciones sin equivalente en PHP — CpuEmbeddingService y CpuVectorIndex — fallan de forma cerrada en lugar de degradarse. Una respuesta silenciosamente incorrecta ahí sería peor que un error explícito. Esa separación permite que el rendimiento escale con los núcleos del sidecar mientras que los llamantes conservan una sola ruta de código y una sola frontera de confianza.

Contexto de diseño: Generación de documentos de alto volumen.

Contrato de comportamiento

• ProAcceleratorProvider::isAvailable() devuelve si el sidecar responde. Los llamantes pueden ramificar en función de esto, pero no es obligatorio: el optimizador y el comparador recurren a la alternativa automáticamente.
• embedding()->embed() devuelve un único vector de 384 elementos; batchEmbed() devuelve un vector por entrada y rechaza una lista de entrada vacía con InvalidArgumentException.
• vectorIndex($collectionId)->build() requiere que vectors e ids tengan la misma longitud y trata una entrada vacía como una operación nula (no-op).
• vectorIndex()->search($queryVector, $topK) devuelve resultados clasificados; delete() no es compatible con el índice HNSW y rechaza la llamada — en su lugar, los llamantes reconstruyen el índice.
• El servicio de incrustación y el índice vectorial requieren el sidecar; generan un error de «no disponible» en lugar de degradarse silenciosamente, porque no hay equivalente en PHP para la inferencia ONNX ni la búsqueda HNSW.
• El optimizador y el comparador nunca generan un error ante un fallo del sidecar; se degradan a la ruta de PHP de forma transparente.

Ejemplo de código — Inicio rápido

Lo siguiente refleja la API pública documentada (ProAcceleratorProvider). El repositorio no incluye ningún ejemplo ejecutable para este módulo.

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

Ejemplo de código — Producción

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

Conecte ProAcceleratorProvider a través de su contenedor como un singleton para que se reutilicen las instancias del optimizador y del comparador. Trate las llamadas de incrustación y de índice vectorial como dependientes del sidecar.

Casos límite y trampas

• El índice vectorial vive en la memoria del proceso del sidecar y está indexado por identificador de colección. Un reinicio del sidecar borra todos los índices; reconstruya tras un reinicio.
• count() en el índice vectorial devuelve 0 cuando el sidecar no es alcanzable en lugar de generar un error.
• La aceleración del optimizador y del comparador es de mejor esfuerzo; un error del sidecar a mitad de lote provoca una alternativa silenciosa para esa llamada, de modo que varía el tiempo — no la corrección.

Rendimiento

La aceleración se dirige al trabajo por lotes limitado por CPU: transcodificación de imágenes en paralelo, análisis multidocumento y búsqueda vectorial. NextPDF no publica aquí un multiplicador de rendimiento fijo; las ganancias dependen de la mezcla de documentos, la densidad de imágenes, el número de núcleos del sidecar y el tamaño del lote. Mida en su entorno antes de confiar en una cifra específica. La alternativa de PHP es de un solo hilo por diseño.

Notas de seguridad

Este módulo envía documentos y vectores al sidecar colocado junto a la aplicación a través de su transporte configurado. Trate el sidecar como parte de su frontera de confianza y despliéguelo en el mismo host o en un segmento de red privado. El módulo valida el tamaño y la forma de la entrada antes del despacho. No registra ningún contenido del documento.

Conformidad

Este módulo no realiza por sí mismo ningún trabajo de conformidad de formato; delega la optimización y la comparación en los módulos Optimizer y Diff de Pro. Consulte esos módulos para conocer las referencias a ISO 32000-2. La evidencia de conformidad de esta página procede de los contratos de clase pública documentados y de sus pruebas unitarias; el corpus de RAG no estaba disponible en el momento de la redacción, por lo que aquí no se afirman identificadores de cláusula externos.

Nota sobre la frontera de Enterprise

Enterprise no cambia el comportamiento de Accelerator. Enterprise añade funciones de cumplimiento, archivado y ciclo de vida de firma de nivel superior documentadas en otro lugar; estas quedan fuera del alcance de este módulo y no son necesarias para usar Accelerator.

Alternativa / recurso de Core

Sin Pro, use la optimización y la comparación en proceso de NextPDF Core. Las rutas aceleradas de este módulo se reducen a ese mismo comportamiento de PHP cuando el sidecar está ausente.

Frontera de publicación

Esta página documenta únicamente el comportamiento observable desde fuera y la superficie de API pública admitida. Las rutas de espacios de nombres internos, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de tickets quedan fuera del alcance.

Véase también

• Accelerator — Referencia detallada
• Optimizer
• Diff
• Output Pipeline