Accelerator

Visão geral

O Accelerator descarrega a recompressão de imagens em lote, a análise de PDF e a incorporação de texto para um sidecar de CPU colocalizado. Quando o sidecar está inacessível, toda operação recorre ao caminho PHP em processo, de modo que os chamadores observam os mesmos resultados de qualquer forma.

Disponibilidade e licenciamento

Este recurso vem no NextPDF Pro (nextpdf/pro) e é ativado com um envelope de licença do nível Pro. Uma implantação sem essa habilitação não carrega as classes do recurso. Compare as edições e obtenha uma licença.

O Accelerator não tem nenhum sinalizador por recurso separado. O caminho acelerado é selecionado em tempo de execução por uma verificação de acessibilidade do sidecar (ProAcceleratorProvider::isAvailable()); quando o sidecar não está acessível, o caminho PHP em processo é executado em vez disso.

Instalação

composer require nextpdf/pro:^3

O pacote Premium instala o código nextpdf/pro sob o namespace NextPDF\Pro\Accelerator. O metapacote nextpdf/premium também instala capacidades do Enterprise; o próprio Accelerator é um recurso do nível Pro.

Visão conceitual

ProAcceleratorProvider é o ponto de entrada. Ele constrói preguiçosamente quatro serviços:

• Um otimizador acelerado que envolve o PdfOptimizer do Pro e descarrega o trabalho de imagem em lote para o sidecar.
• Um differ acelerado que envolve o PdfDiffer do Pro; o sidecar paraleliza a análise de estrutura enquanto o próprio algoritmo de diff é executado em PHP.
• Um serviço de incorporação de CPU que retorna vetores de 384 dimensões usando um modelo ONNX all-MiniLM-L6-v2 hospedado pelo sidecar.
• Um índice vetorial de CPU que constrói e pesquisa um índice HNSW em memória indexado por um identificador de coleção.

O design mantém a lógica de domínio em PHP. O sidecar realiza trabalho paralelizável e limitado por CPU (transcodificação de imagem, análise de múltiplos documentos, inferência ONNX, pesquisa vetorial). Cada caminho acelerado tem um fallback PHP determinístico que produz resultados equivalentes.

Por que funciona assim

A decisão estrutural é que a correção nunca depende do sidecar. A lógica de domínio permanece em PHP; o sidecar apenas realiza trabalho paralelizável e limitado por CPU. O otimizador e o differ (AcceleratedOptimizer, AcceleratedDiffer) mantêm um fallback PHP determinístico, de modo que um sidecar ausente muda o tempo, não os resultados. Apenas as duas operações sem equivalente PHP — CpuEmbeddingService e CpuVectorIndex — falham de forma fechada em vez de rebaixar. Uma resposta errada silenciosa ali seria pior do que um erro explícito. Essa divisão permite que o throughput escale com os núcleos do sidecar enquanto os chamadores mantêm um único caminho de código e um único limite de confiança.

Contexto do design: Geração de documentos em alto volume.

Contrato de comportamento

• ProAcceleratorProvider::isAvailable() retorna se o sidecar responde. Os chamadores podem ramificar com base nisso, mas não precisam: o otimizador e o differ fazem fallback automaticamente.
• embedding()->embed() retorna um único vetor de 384 elementos; batchEmbed() retorna um vetor por entrada e rejeita uma lista de entrada vazia com InvalidArgumentException.
• vectorIndex($collectionId)->build() exige que vectors e ids tenham o mesmo comprimento e trata uma entrada vazia como um no-op.
• vectorIndex()->search($queryVector, $topK) retorna resultados classificados; delete() não é suportado para o índice HNSW e rejeita a chamada — os chamadores reconstroem o índice em vez disso.
• O serviço de incorporação e o índice vetorial exigem o sidecar; eles lançam um erro de “não disponível” em vez de rebaixar silenciosamente, porque não há equivalente PHP para inferência ONNX ou pesquisa HNSW.
• O otimizador e o differ nunca lançam erro em uma falha do sidecar; eles rebaixam para o caminho PHP de forma transparente.

Exemplo de código — Início rápido

O seguinte reflete a API pública documentada (ProAcceleratorProvider). O repositório não fornece um exemplo executável 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.
}

Exemplo de código — Produção

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 pelo seu container como um singleton para que as instâncias de otimizador e differ sejam reutilizadas. Trate as chamadas de incorporação e de índice vetorial como exigindo o sidecar.

Casos extremos e armadilhas

• O índice vetorial vive na memória do processo do sidecar e é indexado por identificador de coleção. Uma reinicialização do sidecar limpa todos os índices; reconstrua após uma reinicialização.
• count() no índice vetorial retorna 0 quando o sidecar está inacessível, em vez de lançar erro.
• A aceleração do otimizador e do differ é best-effort; um erro do sidecar no meio de um lote causa um fallback silencioso para aquela chamada, de modo que o tempo — não a correção — varia.

Desempenho

A aceleração visa o trabalho em lote limitado por CPU: transcodificação paralela de imagens, análise de múltiplos documentos e pesquisa vetorial. O NextPDF não publica um multiplicador de throughput fixo aqui; os ganhos dependem da combinação de documentos, da densidade de imagens, da contagem de núcleos do sidecar e do tamanho do lote. Meça no seu ambiente antes de confiar em um número específico. O fallback PHP é single-threaded por design.

Notas de segurança

Este módulo envia documentos e vetores para o sidecar colocalizado pelo transporte configurado dele. Trate o sidecar como parte do seu limite de confiança e implante-o no mesmo host ou em um segmento de rede privada. O módulo valida o tamanho e o formato da entrada antes do dispatch. Ele não registra nenhum conteúdo de documento.

Conformidade

Este módulo não realiza por si só nenhum trabalho de conformidade de formato; ele delega a otimização e o diffing aos módulos Optimizer e Diff do Pro. Consulte esses módulos para referências ISO 32000-2. A evidência de conformidade desta página vem dos contratos públicos de classe documentados e de seus testes de unidade; o corpus RAG estava indisponível no momento da autoria, então nenhum identificador de cláusula externo é afirmado aqui.

Nota sobre o limite do Enterprise

O Enterprise não altera o comportamento do Accelerator. O Enterprise acrescenta recursos de nível superior de conformidade, arquivamento e ciclo de vida de assinatura documentados em outro lugar; esses estão fora do escopo deste módulo e não são necessários para usar o Accelerator.

Alternativa / fallback do Core

Sem o Pro, use a otimização e o diffing em processo do NextPDF Core. Os caminhos acelerados deste módulo reduzem-se a esse mesmo comportamento PHP quando o sidecar está ausente.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície da API pública suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de ticket estão fora do escopo.

Consulte também

• Accelerator — Referência detalhada
• Optimizer
• Diff
• Output Pipeline