Accelerator — Referência Profunda

Visão geral

Esta página é a referência profunda da superfície pública de aceleração de NextPDF\Pro\Accelerator. Ela cobre a fábrica de providers, o otimizador de lote acelerado, o wrapper do differ e os serviços de sidecar em CPU para embedding e busca vetorial. Descreve parâmetros, padrões, modos de falha e a semântica de fallback. Leia primeiro a página de capacidade do Accelerator para orientação de fluxo de trabalho.

Disponibilidade e licenciamento

Esta capacidade é distribuída no NextPDF Pro (nextpdf/pro) e é ativada com um envelope de licença de nível Pro. Uma implantação sem esse direito não carrega as classes da capacidade. Compare edições e obtenha uma licença.

O Accelerator não tem um sinalizador de licença por recurso. O código é distribuído com a edição Pro; o caminho do otimizador acelerado é selecionado em tempo de execução por uma sonda de acessibilidade do sidecar. O serviço de embedding e o índice de vetores não têm fallback em PHP e falham de forma segura (fail-closed) quando o sidecar está inacessível.

Superfície pública da API

composer require nextpdf/pro:^3

O metapacote nextpdf/premium instala o código de nextpdf/pro; este módulo reside no namespace NextPDF\Pro\Accelerator.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
ProAcceleratorProvider::__construct	SpectrumClient $client	Vincula o provider a um cliente de sidecar do Core	ProAcceleratorProvider	Nada declarado	O chamador constrói e fornece o cliente
ProAcceleratorProvider::isAvailable	nenhum	Sonda a acessibilidade do sidecar através do cliente	bool	Nada declarado	Apenas acessibilidade; os endpoints são sondados por chamada
ProAcceleratorProvider::embedding	nenhum	Retorna o serviço de embedding memoizado	EmbeddingServiceInterface	Nada declarado	Uma instância de CpuEmbeddingService por provider
ProAcceleratorProvider::vectorIndex	string $collectionId = 'default'	Retorna um handle de índice novo vinculado à coleção	VectorIndexInterface	Nada declarado	Não memoizado; um handle por chamada
ProAcceleratorProvider::optimizer	nenhum	Retorna o otimizador acelerado memoizado	AcceleratedOptimizer	Nada declarado	Construído com o cliente do provider
ProAcceleratorProvider::differ	nenhum	Retorna o wrapper de differ memoizado	AcceleratedDiffer	Nada declarado	Construído com o cliente do provider
AcceleratedOptimizer::__construct	?SpectrumClient $spectrum = null, OptimizationLevel $level = OptimizationLevel::Balanced, ?LoggerInterface $logger = null	Envolve o PdfOptimizer em PHP no nível fornecido	AcceleratedOptimizer	Nada declarado	Um cliente nulo seleciona o caminho em PHP; um logger nulo seleciona NullLogger
AcceleratedOptimizer::optimizeBatch	array<string, string> $documents	Analisa cada documento; transfere o trabalho de imagens para o sidecar quando acessível	BatchResultInterface	SpectrumApiException SPEC-SEC-001 (HTTP 413) em um lote acima do limite; marcadores de erro por item no resultado de fallback	Falhas de transporte após a admissão degradam para o caminho em PHP
AcceleratedDiffer::__construct	?SpectrumClient $spectrum = null	Retém o cliente opcional para compatibilidade futura	AcceleratedDiffer	Nada declarado	O cliente não é usado nesta versão
AcceleratedDiffer::compare	string $sourcePdf, string $targetPdf	Compara dois documentos inteiramente em PHP	DiffResult	Como o PdfDiffer do Pro	Nenhuma requisição ao sidecar é emitida nesta versão
AcceleratedDiffer::isSpectrumWired	nenhum	Informa se um cliente de sidecar foi injetado	bool	Nada declarado	Apenas estado de conexão; não emite requisição
CpuEmbeddingService::embed	string $text	Delega para batchEmbed e retorna o elemento zero	list<float>	Como batchEmbed	Vetor de 384 dimensões
CpuEmbeddingService::batchEmbed	array $texts	Faz o embedding do lote no sidecar	list<list<float>>	InvalidArgumentException em um lote vazio; SpectrumNotAvailableException quando inacessível; SpectrumApiException em uma resposta com falha, malformada ou com contagem incompatível	Nunca retorna resultados parciais
CpuEmbeddingService::getDimension	nenhum	Retorna 384	int	Nada declarado	Constante
CpuEmbeddingService::getModelName	nenhum	Retorna all-MiniLM-L6-v2	string	Nada declarado	Constante
CpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Vincula o handle a uma coleção	CpuVectorIndex	Nada declarado	Um handle por identificador de coleção
CpuVectorIndex::build	array $vectors, array $ids	Constrói o índice da coleção no sidecar	void	InvalidArgumentException em uma incompatibilidade de comprimento; SpectrumNotAvailableException quando inacessível	Uma entrada vazia retorna sem contatar o sidecar
CpuVectorIndex::search	array $queryVector, int $topK = 10	Busca ranqueada de vizinhos mais próximos	list<VectorSearchResult>	SpectrumNotAvailableException quando inacessível; SpectrumApiException em um envelope de erro in-band; JsonException em um corpo malformado	Rank por acerto nos metadados do resultado
CpuVectorIndex::delete	array $ids	Sempre rejeita	void (declarado)	Sempre: SpectrumApiException SPEC-INDEX-004 (HTTP 501)	O HNSW não tem exclusão por vetor; reconstrua
CpuVectorIndex::count	nenhum	Lê o total da coleção via uma sonda dimensionada	int	SpectrumNotAvailableException quando inacessível; SpectrumApiException em um erro ou uma resposta de contagem malformada	Retorna 0 apenas para um índice comprovadamente vazio
CpuVectorIndex::INDEX_DIMENSION	—	Constante pública 384	int	—	Corresponde à dimensão do embedding

Assinaturas dos pontos 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 comportamento

Provider

ProAcceleratorProvider é o ponto de entrada. embedding(), optimizer() e differ() memoizam suas instâncias. vectorIndex($collectionId) retorna um handle novo por chamada, vinculado ao identificador de coleção fornecido. isAvailable() sonda a acessibilidade do sidecar através do SpectrumClient do Core injetado.

Otimização em lote

optimizeBatch retorna um resultado de lote indexado pelos identificadores de documento do chamador. Quando o sidecar está acessível, o payload agregado é validado contra o orçamento do cliente antes de qualquer buffering ou upload. Um lote acima do limite falha de forma segura (fail-closed) com SpectrumApiException SPEC-SEC-001 (HTTP 413); ele nunca degrada para o caminho em PHP. Um lote admitido é despachado para o sidecar para o trabalho paralelo de imagens.

Uma falha de transporte, autenticação ou análise de resposta após a admissão degrada para o otimizador em PHP, que analisa cada documento sequencialmente. A degradação é observável duas vezes: os metadados do resultado informam o motor php_fallback com o hardware de resumo cpu, e um aviso PSR-3 é emitido sob o nome de evento spectrum.optimize.fallback. O aviso carrega apenas a classe da exceção e a contagem de documentos; nenhum byte de documento é registrado. No resultado de fallback, uma falha de análise por documento produz um item com status de erro e código SPEC-PARSE-001; os demais documentos do lote ainda são concluídos.

O nível de otimização padrão é Balanced. Os campos de resultado por item são original_bytes, optimized_bytes, objects_removed, images_before, images_after, savings_percent e processing_time_ms.

Diff de documentos

compare é executado inteiramente em PHP via o PdfDiffer do Pro: análise de estrutura, extração de texto e o algoritmo de diff. Nenhuma requisição ao sidecar é emitida nesta versão. O contrato do differ aceita apenas strings de PDF brutas, então um resultado de análise do sidecar não pode ser consumido; a transferência adicionaria custo sem benefício. Um cliente injetado é retido para um futuro recurso de transferência de análise. isSpectrumWired() expõe o estado de conexão sem emitir uma requisição.

Embedding em CPU

embed delega para batchEmbed([$text]) e retorna o elemento zero. batchEmbed([]) levanta InvalidArgumentException antes de contatar o sidecar. Um sidecar inacessível levanta SpectrumNotAvailableException. A semântica do lote é tudo ou nada: uma falha por item, um vetor ausente ou malformado, ou uma contagem incompatível levanta SpectrumApiException (falhas de formato de protocolo carregam SPEC-IO-001) em vez de retornar vetores parciais. Um componente não numérico dentro de um vetor retornado é convertido para 0.0. getDimension retorna 384; getModelName retorna all-MiniLM-L6-v2. O sidecar baixa e carrega o modelo ONNX de forma preguiçosa na primeira requisição.

Busca vetorial em CPU

Cada handle vincula um identificador de coleção; cada coleção mapeia para um índice HNSW em memória separado no sidecar. build requer listas de vetores e identificadores de igual comprimento e levanta InvalidArgumentException caso contrário; uma entrada vazia retorna sem uma chamada ao sidecar. search retorna acertos ranqueados com um rank de base um nos metadados de cada resultado. Um envelope de erro in-band levanta SpectrumApiException; um envelope sem um código mapeia para SPEC-INDEX-003. delete sempre rejeita com SpectrumApiException SPEC-INDEX-004 (HTTP 501, não repetível) porque o HNSW não suporta exclusão por vetor; reconstrua o índice.

count é fail-closed e inequívoco. Um sidecar inacessível levanta SpectrumNotAvailableException; erros de transporte e do sidecar se propagam inalterados. Em uma resposta bem-sucedida no restante, um corpo não JSON levanta SPEC-INDEX-005, um metadata.total_vectors ausente levanta SPEC-INDEX-006 e um total não inteiro ou negativo levanta SPEC-INDEX-007. count retorna 0 apenas para um índice comprovadamente vazio. A sonda de tamanho envia um vetor zero de exatamente INDEX_DIMENSION (384) dimensões com um top_k de 0, de modo que um sidecar que valida dimensão o aceita.

Casos extremos e modos de falha

• A memória do sidecar é volátil: um reinício limpa todas as coleções HNSW. Trate a construção do índice como idempotente e execute-a novamente após um reinício.
• A disponibilidade mista dentro de um único processo é suportada: o otimizador degrada por chamada; os serviços de embedding e de vetores falham de forma segura (fail-closed) por chamada.
• Um lote do otimizador acima do limite falha de forma segura (fail-closed) antes de qualquer upload; ele não recorre ao caminho em PHP.
• O fallback do otimizador nunca falha silenciosamente: verifique o marcador de motor nos metadados do resultado e monitore o evento de aviso.
• count nunca reporta um sidecar inacessível ou um erro de protocolo como 0; esses levantam exceções tipadas.
• Um acerto de busca sem seu identificador ou pontuação assume por padrão uma string vazia e 0.0 em vez de falhar o lote.
• Um top_k de 0 é usado internamente apenas para a sonda de contagem; passe um topK positivo para buscas reais.
• A primeira requisição de embedding paga o custo único de download e carregamento do modelo; dimensione esse timeout separadamente.
• A hierarquia de exceções do sidecar e as famílias de códigos de erro estão catalogadas na referência de erros do Accelerator.
• Este módulo não realiza nenhuma operação criptográfica e não define nenhum comportamento específico de FIPS. A postura em modo FIPS é governada pelos módulos de assinatura e conformidade, não aqui.

Conformidade

O Accelerator delega o trabalho que afeta o formato aos módulos Optimizer e Diff e não afirma nenhuma conformidade de formato independente. A conformidade para o trabalho delegado está documentada nas páginas de referência do Optimizer e do Diff. Esta página não declara nenhum identificador de cláusula externo; cada afirmação está fundamentada na fonte do produto. A NextPDF não faz nenhuma alegação de certificação.

Notas de desenvolvimento

• A fonte do módulo carrega @since 2.1.0; esta referência documenta a superfície conforme distribuída em nextpdf/pro 3.1.0.
• Todas as classes são final e usam injeção via construtor; construa novas instâncias em vez de mutar.
• SpectrumClient, VectorSearchResult, BatchResultInterface e os contratos EmbeddingServiceInterface e VectorIndexInterface vêm do NextPDF Core; o chamador constrói e fornece o cliente de sidecar.
• OptimizationLevel, PdfOptimizer e PdfDiffer vêm dos módulos Optimizer e Diff do Pro; sua semântica está documentada nessas páginas de referência.
• O serviço de embedding e o índice de vetores compartilham a dimensão 384. Construa os vetores de índice com a mesma dimensão dos embeddings que os consultam.
• Os detalhes internos do mecanismo permanecem na documentação interna do repositório de origem e estão fora do escopo deste manual.

Limite de publicação

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

Veja também

• Accelerator — a página de capacidade para orientação de fluxo de trabalho.
• Referência de erros do Accelerator — hierarquia de exceções do sidecar e códigos de erro.
• Optimizer — Referência profunda
• Diff — Referência profunda
• Accelerator — Referência profunda do NextPDF Enterprise