Accelerator — Referência Profunda (sidecar de GPU, fábrica de provedores de KMS)

Visão geral

Esta página é a referência detalhada da superfície pública de aceleração de NextPDF\Enterprise\Accelerator. Ela cobre a pilha de provedores de KMS — a fábrica, o contrato do provedor, o provedor local e o resultado de metadados de chave — e os serviços do sidecar de GPU para embedding e busca vetorial. Ela declara parâmetros, valores padrão, modos de falha e a postura de custódia de chaves. Leia primeiro a página de capacidade do Accelerator para orientação de fluxo de trabalho. Outros símbolos no mesmo namespace pertencem a outras capacidades e estão fora do escopo desta página.

Disponibilidade e licenciamento

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

O provedor de KMS é selecionado em tempo de execução; o código que chama depende do contrato do provedor, não do provedor concreto. Os serviços de embedding e de índice vetorial implementam os contratos EmbeddingServiceInterface e VectorIndexInterface do Core.

Superfície pública de API

composer require nextpdf/enterprise:^3

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
KmsProviderFactory::fromEnvironment	nenhum	Constrói o provedor indicado pela variável seletora; ausente ou vazia seleciona local	KmsProviderInterface	RuntimeException em caso de chave-mestra ausente, provedor de nuvem indisponível ou nome desconhecido	Ponto de entrada estático
KmsProviderFactory::create	string $providerType, array $config = []	Constrói o provedor nomeado a partir de configuração explícita	KmsProviderInterface	RuntimeException quando local não tem um encryption_key não vazio, ou em caso de nome desconhecido	local é o único nome construível nesta versão
KmsProviderInterface::getEncryptionKey	string $collectionId	Retorna os metadados atuais da chave da coleção	EncryptionKeyResult	RuntimeException quando o provedor está inacessível ou mal configurado (contrato)	Somente metadados; nunca os bytes brutos da chave
KmsProviderInterface::rotateKey	string $collectionId	Avança a versão da chave	EncryptionKeyResult	RuntimeException quando a rotação falha (contrato)	A rotação é um sinal de recriptografia para o chamador
KmsProviderInterface::providerName	nenhum	Informa o nome canônico do provedor	string	Nada declarado	local, aws, gcp, azure, vault
LocalKmsProvider::__construct	string $encryptionKey (sensível)	Valida uma chave-mestra hexadecimal de pelo menos 64 caracteres hexadecimais (32 bytes)	LocalKmsProvider	InvalidArgumentException em caso de valor curto ou não-hexadecimal	Guarda fail-fast; não realiza nenhuma derivação por si
LocalKmsProvider::getEncryptionKey	string $collectionId	Cunha local:{collectionId}:v{version}; a versão tem padrão 1	EncryptionKeyResult	Nada declarado	Rótulo de algoritmo AES-256-GCM
LocalKmsProvider::rotateKey	string $collectionId	Incrementa o contador de versão em processo	EncryptionKeyResult	Nada declarado	O estado de versão é por instância
EncryptionKeyResult::__construct	string $keyId, int $keyVersion, string $algorithm = 'AES-256-GCM', string $provider = 'local'	Objeto de valor de metadados imutável	EncryptionKeyResult	Nada declarado	Nunca carrega material de chave
GpuEmbeddingService::embed	string $text	Delega para batchEmbed e retorna o elemento zero	list<float>	Igual a batchEmbed	Vetor de 1024 dimensões
GpuEmbeddingService::batchEmbed	array $texts	Faz o embedding do lote no sidecar	list<list<float>>	InvalidArgumentException em lote vazio; SpectrumNotAvailableException quando o sidecar está inacessível; SpectrumApiException em resposta com falha, malformada ou com contagem divergente	Nunca retorna resultados parciais
GpuEmbeddingService::getDimension	nenhum	Retorna 1024	int	Nada declarado	Constante
GpuEmbeddingService::getModelName	nenhum	Retorna multilingual-e5-large	string	Nada declarado	Constante
GpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Vincula o handle a uma coleção	GpuVectorIndex	Nada declarado	Um handle por identificador de coleção
GpuVectorIndex::build	array $vectors, array $ids	Constrói o índice da coleção no sidecar	void	InvalidArgumentException em lote vazio ou divergência de tamanho; SpectrumNotAvailableException quando inacessível; SpectrumApiException em resposta de construção inesperada	Uma reconstrução substitui o índice
GpuVectorIndex::search	array $queryVector, int $topK = 10	Busca de vizinhos mais próximos com ranqueamento	list<VectorSearchResult>	SpectrumNotAvailableException quando inacessível; JsonException em corpo de resposta malformado	Rank por acerto nos metadados do resultado
GpuVectorIndex::delete	array $ids	Sempre rejeita	void (declarado)	Sempre: SpectrumApiException (não implementado)	O índice construído é imutável; reconstrua em vez disso
GpuVectorIndex::count	nenhum	Lê o total da coleção no sidecar	int	Não lança; qualquer falha retorna 0	0 é ambíguo: vazio ou inacessível

Assinaturas dos pontos de entrada

final class KmsProviderFactory
{
    public static function fromEnvironment(): KmsProviderInterface

    public static function create(string $providerType, array $config = []): KmsProviderInterface
}

interface KmsProviderInterface
{
    public function getEncryptionKey(string $collectionId): EncryptionKeyResult;

    public function rotateKey(string $collectionId): EncryptionKeyResult;

    public function providerName(): string;
}

final class LocalKmsProvider implements KmsProviderInterface
{
    public function __construct(
        #[SensitiveParameter]
        private readonly string $encryptionKey,
    )
}

final readonly class EncryptionKeyResult
{
    public function __construct(
        public string $keyId,
        public int $keyVersion,
        public string $algorithm = 'AES-256-GCM',
        public string $provider = 'local',
    )
}

final class GpuEmbeddingService 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 GpuVectorIndex implements VectorIndexInterface
{
    public function __construct(
        private readonly SpectrumClient $client,
        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
}

Superfície de configuração

Configuração	Consumidor	Significado
SPECTRUM_KMS_PROVIDER	fromEnvironment()	Seletor de provedor. Ausente ou vazia resolve para local.
SPECTRUM_ENCRYPTION_KEY	O caminho do provedor local	Chave-mestra codificada em hexadecimal; pelo menos 64 caracteres hexadecimais (32 bytes). Compartilhada com o sidecar.
encryption_key	create('local', [...])	Chave-mestra explícita; mesmo formato e validação.

Contrato de comportamento

Seleção de provedor

KmsProviderFactory::fromEnvironment lê a variável seletora e assume local por padrão. Os nomes de provedores de nuvem aws, gcp, azure e vault são reconhecidos, mas não são construíveis nesta versão. Selecionar aws gera um erro tipado que nomeia o pacote aws/aws-sdk-php exigido; os outros três relatam a integração como não implementada. Um nome desconhecido gera um erro tipado que lista os nomes suportados. KmsProviderFactory::create aceita um nome de provedor explícito e um mapa de configuração; local é o único nome que ele constrói.

Metadados e custódia de chaves

Um provedor retorna metadados de chave imutáveis: um identificador de chave, uma versão de chave monotonicamente crescente, o rótulo do algoritmo e o nome do provedor. Ele nunca retorna os bytes brutos da chave, então um vazamento de metadados não expõe o material de chave. O provedor local divide as responsabilidades com o sidecar do accelerator. A classe PHP valida o segredo-mestre na construção e cunha uma identidade de chave estável, com escopo de coleção, na forma local:{collectionId}:v{version}. O sidecar realiza a derivação HKDF-SHA256 e a criptografia AES-256-GCM, derivando uma chave de criptografia de dados distinta de 32 bytes por coleção, usando o identificador da coleção e a versão como separação de domínio. Ambos os lados leem o mesmo segredo-mestre configurado. Nenhum serviço de KMS externo é contatado; o manuseio de chaves permanece dentro da implantação. A versão da chave e o modelo de ciclo de vida seguem a NIST SP 800-57 Part 1 Rev.5 §4.

Uma chamada de rotação avança a versão da chave e retorna os novos metadados. O chamador recriptografa os dados da coleção com a nova versão; o provedor não recriptografa nada por si.

A segurança da chave depende do KMS ou do segredo de chave-mestra, da implantação e do operador — não apenas do NextPDF Enterprise. O operador é dono do provisionamento da chave-mestra, do armazenamento do segredo, da configuração do KMS e do agendamento da rotação. A responsabilidade de proteção de chaves segue a NIST SP 800-57 Part 1 Rev.5 §5.5.2.

Embedding de GPU

GpuEmbeddingService implementa o contrato de embedding do Core e delega ao sidecar. O sidecar executa o modelo de embedding em uma GPU quando há uma disponível e recorre à CPU caso contrário, sinalizando os metadados da resposta como degradados em relação à GPU. A forma do vetor é idêntica em ambos os casos. O modelo (cerca de 1,3 GB) é baixado e carregado de forma preguiçosa na primeira requisição. A semântica de lote é tudo-ou-nada: uma falha por item, um vetor malformado ou uma contagem divergente gera um erro tipado em vez de retornar resultados parciais.

Busca vetorial de GPU

GpuVectorIndex implementa o contrato de índice vetorial do Core e vincula um handle a um identificador de coleção. build constrói o índice no sidecar; o sidecar usa um índice de GPU quando há uma disponível e um índice de CPU caso contrário. O índice é imutável depois de construído: delete sempre rejeita com um erro tipado de não implementado, e a remoção exige uma reconstrução. search retorna acertos ranqueados com um rank baseado em 1 nos metadados de cada resultado. count pede ao sidecar o total da coleção e relata 0 em qualquer falha em vez de gerar exceção.

Casos extremos e modos de falha

• A chave-mestra deve decodificar de hexadecimal para pelo menos 32 bytes. Um valor mais curto ou não-hexadecimal gera InvalidArgumentException na construção, antes de qualquer chamada ao sidecar.
• Uma variável seletora ausente ou vazia resolve para local; a fábrica nunca adivinha outro provedor.
• fromEnvironment no caminho local sem a variável de chave-mestra gera um erro tipado que nomeia a variável ausente.
• create('local', [...]) sem uma entrada encryption_key não vazia gera um erro tipado que nomeia a entrada ausente.
• O estado de versão da chave é em processo e por instância de provedor. Um novo processo observa a versão 1 até que a rotação seja executada novamente. Persista os resultados da rotação recriptografando os dados, não confiando no estado do provedor.
• Um lote de embedding vazio gera InvalidArgumentException; o sidecar não é contatado.
• A disponibilidade do sidecar é verificada a cada chamada. Um sidecar inacessível gera SpectrumNotAvailableException; os serviços nunca falham silenciosamente.
• Um componente não numérico dentro de um vetor de embedding retornado é convertido para 0.0; um vetor ausente ou que não seja array gera SpectrumApiException.
• A primeira requisição de embedding paga o custo único de download e carregamento do modelo; dimensione esse timeout separadamente.
• build e search decodificam a resposta do sidecar de forma estrita; um corpo malformado gera JsonException. count engole todas as falhas e retorna 0.
• Um acerto de busca sem seu identificador ou pontuação assume uma string vazia e 0.0 por padrão, em vez de fazer o lote falhar.
• Os códigos de erro do sidecar e a hierarquia de exceções estão catalogados na referência de erros do Accelerator.

Comportamento em modo FIPS

O caminho de chave local usa HKDF-SHA256 para derivação e AES-256-GCM para criptografia; o sidecar executa ambos. O rótulo de algoritmo registrado nos metadados de chave é AES-256-GCM. Quando a implantação é executada contra um provedor de criptografia validado por FIPS, essas primitivas são executadas nesse limite validado. O uso de AES-GCM requer um vetor de inicialização único por chave, conforme a NIST SP 800-38D §5.

O NextPDF Enterprise não é um módulo criptográfico validado por FIPS e não faz nenhuma afirmação de certificação FIPS. Ele opera em um modo compatível com FIPS apenas quando configurado com um provedor de criptografia validado por FIPS ou um KMS validado por FIPS. Nenhum artefato de certificação FIPS existe neste repositório.

Conformidade

Afirmação	Padrão	Cláusula
A versão da chave e o modelo de ciclo de vida seguem a orientação de estados de chave.	NIST SP 800-57 Part 1 Rev.5	§4
A responsabilidade de proteção e custódia de chaves cabe ao dono da chave e ao operador.	NIST SP 800-57 Part 1 Rev.5	§5.5.2
O AES-GCM requer um vetor de inicialização único por chave.	NIST SP 800-38D	§5

Todas as cláusulas são parafraseadas; o NextPDF não reproduz texto normativo. O NextPDF não faz nenhuma afirmação de certificação. O alinhamento com as cláusulas citadas é uma declaração de capacidade, não uma certificação. Esta página trata de gerenciamento de chaves; a declaração de modo FIPS é uma declaração de compatibilidade, não uma opinião jurídica. Consulte seus próprios assessores de conformidade e jurídicos.

Notas de desenvolvimento

• O código-fonte do módulo carrega @since 2.1.0; esta referência documenta a superfície tal como distribuída no nextpdf/enterprise 3.1.0.
• Todas as classes são final; EncryptionKeyResult é final readonly. Construa novas instâncias em vez de mutar.
• A chave-mestra é um parâmetro de construtor sensível (#[SensitiveParameter]); o PHP a oculta dos stack traces. Mantenha-a fora dos logs da aplicação e dos dumps de configuração.
• SpectrumClient, VectorSearchResult e os contratos EmbeddingServiceInterface e VectorIndexInterface vêm do NextPDF Core; o chamador constrói e fornece o cliente do sidecar.
• O namespace NextPDF\Enterprise\Accelerator também carrega motores de offload em lote e as pilhas de coleção de recuperação e de extração por OCR; essas superfícies estão fora do escopo desta página.
• O detalhe de mecanismo interno permanece na documentação interna do repositório de origem e está 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 de API suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismo, nomes de arquivos de runbook e prefixos de tickets estão fora do escopo.

Veja também

• Accelerator — sidecar de GPU e fábrica de provedores de KMS — a página de capacidade para orientação de fluxo de trabalho e custódia.
• Referência de erros do Accelerator — hierarquia de exceções e códigos de erro do sidecar.
• Security — Referência detalhada
• Accelerator — Referência detalhada do NextPDF Pro