Accelerator — Referencia detallada

De un vistazo

Esta página es la referencia detallada de la superficie pública de aceleración de NextPDF\Pro\Accelerator. Abarca la fábrica de proveedores, el optimizador de lotes acelerado, el envoltorio del comparador y los servicios del sidecar en CPU para embedding y búsqueda vectorial. Establece parámetros, valores por defecto, modos de fallo y semántica de reserva. Léase primero la página de capacidad de Accelerator para orientación sobre el flujo de trabajo.

Disponibilidad y licencias

Esta capacidad se distribuye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin esa habilitación no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Accelerator no tiene una marca de licencia por función. El código se distribuye con la edición Pro; la ruta del optimizador acelerado se selecciona en tiempo de ejecución mediante una sonda de accesibilidad del sidecar. El servicio de embedding y el índice vectorial no tienen reserva en PHP y fallan de forma cerrada cuando el sidecar es inaccesible.

Superficie de la API pública

composer require nextpdf/pro:^3

El metapaquete nextpdf/premium instala el código de nextpdf/pro; este módulo reside bajo el espacio de nombres NextPDF\Pro\Accelerator.

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
ProAcceleratorProvider::__construct	SpectrumClient $client	Vincula el proveedor a un cliente sidecar de Core	ProAcceleratorProvider	Nada declarado	El invocador construye y suministra el cliente
ProAcceleratorProvider::isAvailable	ninguno	Sondea la accesibilidad del sidecar a través del cliente	bool	Nada declarado	Solo accesibilidad; los endpoints se sondean por llamada
ProAcceleratorProvider::embedding	ninguno	Devuelve el servicio de embedding memoizado	EmbeddingServiceInterface	Nada declarado	Una instancia de CpuEmbeddingService por proveedor
ProAcceleratorProvider::vectorIndex	string $collectionId = 'default'	Devuelve un manejador de índice nuevo vinculado a la colección	VectorIndexInterface	Nada declarado	No memoizado; un manejador por llamada
ProAcceleratorProvider::optimizer	ninguno	Devuelve el optimizador acelerado memoizado	AcceleratedOptimizer	Nada declarado	Construido con el cliente del proveedor
ProAcceleratorProvider::differ	ninguno	Devuelve el envoltorio del comparador memoizado	AcceleratedDiffer	Nada declarado	Construido con el cliente del proveedor
AcceleratedOptimizer::__construct	?SpectrumClient $spectrum = null, OptimizationLevel $level = OptimizationLevel::Balanced, ?LoggerInterface $logger = null	Envuelve el PdfOptimizer de PHP en el nivel dado	AcceleratedOptimizer	Nada declarado	Un cliente nulo selecciona la ruta de PHP; un logger nulo selecciona NullLogger
AcceleratedOptimizer::optimizeBatch	array<string, string> $documents	Analiza cada documento; delega el trabajo de imágenes al sidecar cuando es accesible	BatchResultInterface	SpectrumApiException SPEC-SEC-001 (HTTP 413) en un lote que excede el límite; marcadores de error por elemento en el resultado de reserva	Los fallos de transporte tras la admisión degradan a la ruta de PHP
AcceleratedDiffer::__construct	?SpectrumClient $spectrum = null	Conserva el cliente opcional para compatibilidad futura	AcceleratedDiffer	Nada declarado	El cliente no se usa en esta versión
AcceleratedDiffer::compare	string $sourcePdf, string $targetPdf	Compara dos documentos por completo en PHP	DiffResult	Como el PdfDiffer de Pro	No se emite ninguna petición al sidecar en esta versión
AcceleratedDiffer::isSpectrumWired	ninguno	Informa si se inyectó un cliente sidecar	bool	Nada declarado	Solo estado de cableado; no emite ninguna petición
CpuEmbeddingService::embed	string $text	Delega en batchEmbed y devuelve el elemento cero	list<float>	Como batchEmbed	Vector de 384 dimensiones
CpuEmbeddingService::batchEmbed	array $texts	Incrusta el lote en el sidecar	list<list<float>>	InvalidArgumentException en un lote vacío; SpectrumNotAvailableException cuando es inaccesible; SpectrumApiException en una respuesta fallida, malformada o con recuento discordante	Nunca devuelve resultados parciales
CpuEmbeddingService::getDimension	ninguno	Devuelve 384	int	Nada declarado	Constante
CpuEmbeddingService::getModelName	ninguno	Devuelve all-MiniLM-L6-v2	string	Nada declarado	Constante
CpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Vincula el manejador a una colección	CpuVectorIndex	Nada declarado	Un manejador por identificador de colección
CpuVectorIndex::build	array $vectors, array $ids	Construye el índice de la colección en el sidecar	void	InvalidArgumentException en una discordancia de longitud; SpectrumNotAvailableException cuando es inaccesible	Una entrada vacía retorna sin contactar el sidecar
CpuVectorIndex::search	array $queryVector, int $topK = 10	Búsqueda clasificada del vecino más cercano	list<VectorSearchResult>	SpectrumNotAvailableException cuando es inaccesible; SpectrumApiException en un sobre de error en banda; JsonException en un cuerpo malformado	Rango por acierto en los metadatos del resultado
CpuVectorIndex::delete	array $ids	Siempre rechaza	void (declarado)	Siempre: SpectrumApiException SPEC-INDEX-004 (HTTP 501)	HNSW no tiene eliminación por vector; reconstruir en su lugar
CpuVectorIndex::count	ninguno	Lee el total de la colección mediante una sonda dimensionada	int	SpectrumNotAvailableException cuando es inaccesible; SpectrumApiException en un error o una respuesta de recuento malformada	Devuelve 0 solo para un índice confirmado como vacío
CpuVectorIndex::INDEX_DIMENSION	—	Constante pública 384	int	—	Coincide con la dimensión del embedding

Firmas de los puntos de entrada

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
}

Contrato de comportamiento

Proveedor

ProAcceleratorProvider es el punto de entrada. embedding(), optimizer() y differ() memoizan sus instancias. vectorIndex($collectionId) devuelve un manejador nuevo por llamada, vinculado al identificador de colección dado. isAvailable() sondea la accesibilidad del sidecar a través del SpectrumClient de Core inyectado.

Optimización por lotes

optimizeBatch devuelve un resultado de lote indexado por los identificadores de documento del invocador. Cuando el sidecar es accesible, la carga útil agregada se valida contra el presupuesto del cliente antes de cualquier almacenamiento en búfer o subida. Un lote que excede el límite falla de forma cerrada con SpectrumApiException SPEC-SEC-001 (HTTP 413); nunca degrada a la ruta de PHP. Un lote admitido se despacha al sidecar para el trabajo paralelo de imágenes.

Un fallo de transporte, autenticación o análisis de respuesta tras la admisión degrada al optimizador de PHP, que analiza cada documento secuencialmente. La degradación es observable dos veces: los metadatos del resultado informan del motor php_fallback con hardware de resumen cpu, y se emite una advertencia PSR-3 bajo el nombre de evento spectrum.optimize.fallback. La advertencia lleva únicamente la clase de excepción y el recuento de documentos; no se registran bytes de documento. En el resultado de reserva, un fallo de análisis por documento produce un elemento con estado de error y código SPEC-PARSE-001; los demás documentos del lote se completan igualmente.

El nivel de optimización por defecto es Balanced. Los campos de resultado por elemento son original_bytes, optimized_bytes, objects_removed, images_before, images_after, savings_percent y processing_time_ms.

Comparación de documentos

compare se ejecuta por completo en PHP mediante el PdfDiffer de Pro: análisis de estructura, extracción de texto y el algoritmo de comparación. No se emite ninguna petición al sidecar en esta versión. El contrato del comparador acepta únicamente cadenas PDF sin procesar, de modo que no puede consumirse un resultado de análisis del sidecar; delegar añadiría coste sin beneficio. Un cliente inyectado se conserva para una futura función de delegación del análisis. isSpectrumWired() expone el estado de cableado sin emitir una petición.

Embedding en CPU

embed delega en batchEmbed([$text]) y devuelve el elemento cero. batchEmbed([]) lanza InvalidArgumentException antes de contactar el sidecar. Un sidecar inaccesible lanza SpectrumNotAvailableException. La semántica de lote es de todo o nada: un fallo por elemento, un vector ausente o malformado, o un recuento discordante lanza SpectrumApiException (los fallos de forma del protocolo llevan SPEC-IO-001) en lugar de devolver vectores parciales. Un componente no numérico dentro de un vector devuelto se coacciona a 0.0. getDimension devuelve 384; getModelName devuelve all-MiniLM-L6-v2. El sidecar descarga y carga el modelo ONNX de forma perezosa en la primera petición.

Búsqueda vectorial en CPU

Cada manejador vincula un identificador de colección; cada colección se asigna a un índice HNSW en memoria independiente dentro del sidecar. build requiere listas de vectores e identificadores de igual longitud y lanza InvalidArgumentException en caso contrario; una entrada vacía retorna sin una llamada al sidecar. search devuelve aciertos clasificados con un rango de base uno en los metadatos de cada resultado. Un sobre de error en banda lanza SpectrumApiException; un sobre sin código se asigna a SPEC-INDEX-003. delete siempre rechaza con SpectrumApiException SPEC-INDEX-004 (HTTP 501, no reintentable) porque HNSW no admite la eliminación por vector; reconstruir el índice en su lugar.

count es de fallo cerrado e inequívoco. Un sidecar inaccesible lanza SpectrumNotAvailableException; los errores de transporte y del sidecar se propagan sin cambios. En una respuesta por lo demás exitosa, un cuerpo no JSON lanza SPEC-INDEX-005, una ausencia de metadata.total_vectors lanza SPEC-INDEX-006, y un total no entero o negativo lanza SPEC-INDEX-007. count devuelve 0 solo para un índice confirmado como vacío. La sonda de tamaño envía un vector cero de exactamente INDEX_DIMENSION (384) dimensiones con un top_k de 0, de modo que un sidecar que valida la dimensión lo acepta.

Casos límite y modos de fallo

• La memoria del sidecar es volátil: un reinicio borra todas las colecciones HNSW. Tratar la construcción del índice como idempotente y volver a ejecutarla tras un reinicio.
• Se admite la disponibilidad mixta dentro de un solo proceso: el optimizador degrada por llamada; los servicios de embedding y vectorial fallan de forma cerrada por llamada.
• Un lote del optimizador que excede el límite falla de forma cerrada antes de cualquier subida; no recurre a la ruta de PHP.
• La reserva del optimizador nunca falla en silencio: comprobar el marcador de motor en los metadatos del resultado y monitorizar el evento de advertencia.
• count nunca informa de un sidecar inaccesible o de un error de protocolo como 0; esos lanzan excepciones tipadas.
• Un acierto de búsqueda sin su identificador o puntuación adopta por defecto una cadena vacía y 0.0 en lugar de hacer fallar el lote.
• Un top_k de 0 se usa internamente solo para la sonda de recuento; pasar un topK positivo para búsquedas reales.
• La primera petición de embedding paga el coste único de descarga y carga del modelo; dimensionar ese tiempo de espera por separado.
• La jerarquía de excepciones del sidecar y las familias de códigos de error se catalogan en la referencia de errores de Accelerator.
• Este módulo no realiza operaciones criptográficas y no define comportamiento específico de FIPS. La postura de modo FIPS la gobiernan los módulos de firma y cumplimiento, no este.

Conformidad

Accelerator delega el trabajo que afecta al formato en los módulos Optimizer y Diff y no afirma ninguna conformidad de formato independiente. La conformidad del trabajo delegado se documenta en las páginas de referencia de Optimizer y Diff. Esta página no reclama identificadores de cláusula externos; cada afirmación se fundamenta en la fuente del producto. NextPDF no formula ninguna reclamación de certificación.

Notas de desarrollo

• La fuente del módulo lleva @since 2.1.0; esta referencia documenta la superficie tal como se distribuye en nextpdf/pro 3.1.0.
• Todas las clases son final y usan inyección por constructor; construir nuevas instancias en lugar de mutar.
• SpectrumClient, VectorSearchResult, BatchResultInterface y los contratos EmbeddingServiceInterface y VectorIndexInterface provienen de NextPDF Core; el invocador construye y suministra el cliente sidecar.
• OptimizationLevel, PdfOptimizer y PdfDiffer provienen de los módulos Optimizer y Diff de Pro; su semántica se documenta en esas páginas de referencia.
• El servicio de embedding y el índice vectorial comparten la dimensión 384. Construir los vectores del índice a la misma dimensión que los embeddings que los consultan.
• El detalle interno del mecanismo permanece en la documentación interna del repositorio de fuentes y queda fuera del alcance de este manual.

Límite de publicación

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

Véase también

• Accelerator — la página de capacidad para orientación sobre el flujo de trabajo.
• Referencia de errores de Accelerator — jerarquía de excepciones del sidecar y códigos de error.
• Optimizer — Referencia detallada
• Diff — Referencia detallada
• Accelerator — Referencia detallada de NextPDF Enterprise