Enterprise edição

Accelerator — sidecar de GPU e fábrica de provedores KMS

Visão geral

O NextPDF Enterprise acrescenta dois recursos de aceleração: um sidecar de GPU para embedding de texto com um fallback de CPU e uma fábrica de provedores KMS que fornece metadados e rotação de chaves de criptografia de dados em nível de coleção. Esta página declara o comportamento, os limites e a postura de custódia de chaves.

Disponibilidade e licenciamento

Este recurso é entregue no NextPDF Enterprise (nextpdf/enterprise) e é ativado com um envelope de licença de nível Enterprise. Uma implantação sem esse direito não carrega as classes do recurso. Compare as edições e obtenha uma licença.

Visão conceitual

O sidecar de GPU acelera o embedding de texto para vetor. O pacote Enterprise envia o texto para um processo sidecar separado por meio de uma requisição HTTP local. O sidecar executa o modelo de embedding em uma GPU quando há uma disponível. Quando não há GPU disponível, o sidecar executa o mesmo modelo na CPU e relata que rodou em um modo degradado. O resultado é o mesmo formato de vetor em ambos os casos. O modelo de embedding é carregado na primeira requisição, então a primeira requisição é mais lenta que as posteriores. O sidecar é opcional; uma verificação de disponibilidade é exposta, e um sidecar ausente lança uma exceção tipada em vez de uma falha silenciosa.

A fábrica de provedores KMS seleciona um provedor de gerenciamento de chaves a partir da configuração. A fábrica lê uma variável de ambiente para escolher o provedor. O provedor padrão deriva localmente uma chave de criptografia de dados específica da coleção usando HKDF-SHA256 a partir de uma chave-mestra configurada, com o identificador da coleção como separador de domínio. O provedor local não contata nenhum serviço externo; a derivação é determinística e em processo. A fábrica também aceita uma forma de configuração explícita para o provedor local. Provedores em nuvem — AWS KMS, GCP Cloud KMS, Azure Key Vault e HashiCorp Vault Transit — são nomes de provedor reconhecidos; selecionar um sem a integração correspondente instalada lança um erro de configuração tipado que nomeia a dependência ausente.

Um provedor retorna metadados de chave, não os bytes brutos da chave. Os metadados registram o identificador da chave, uma versão de chave monotonicamente crescente, o nome do algoritmo de criptografia e o nome do provedor. Uma chamada de rotação avança a versão da chave e retorna os novos metadados. O chamador é responsável por recriptografar os dados da coleção com a nova versão de chave após uma rotação. A versão de chave e o ciclo de vida de rotação seguem a NIST SP 800-57 Part 1 Rev.5 §4.

Por que funciona assim

O embedding é executado em um processo sidecar de GPU separado, e não dentro da requisição PHP. O carregamento do modelo em GPU é custoso, então o sidecar carrega o modelo uma única vez e amortiza esse custo entre muitas requisições. Quando não há GPU presente, o sidecar executa o mesmo modelo na CPU e relata um modo degradado. A vazão pode cair, mas a correção não: o formato do vetor é idêntico de qualquer forma. O sidecar permanece opcional; uma verificação de disponibilidade e uma exceção tipada em um sidecar ausente mantêm a aceleração como uma opção deliberada, não uma dependência oculta. Essa separação permite que o embedding de alto volume escale em hardware dedicado enquanto o pipeline de documentos permanece uma simples chamada PHP.

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

Superfície da API

Superfície pública	Tipo	Finalidade	Estabilidade	Desde
Fábrica de provedores KMS	class	Construir um provedor KMS a partir do ambiente ou de configuração explícita	stable	2.1.0
Provedor KMS	interface	Obter metadados de chave, rotacionar uma chave e relatar o nome do provedor	stable	2.1.0
Provedor KMS local	class (implementa a interface do provedor)	Derivação de chave HKDF-SHA256 local; não contata nenhum serviço externo	stable	2.1.0
Resultado de chave de criptografia	value object	Metadados de chave imutáveis: id da chave, versão, algoritmo, provedor — sem bytes brutos da chave	stable	2.1.0
Serviço de embedding por GPU	class (implementa a interface de serviço de embedding do Core)	Fazer embedding de texto em um sidecar de GPU com um fallback de CPU	stable	2.1.0

A fábrica de provedores expõe um ponto de entrada “a partir do ambiente” e um ponto de entrada explícito de “criação”. O valor de configuração da chave-mestra é marcado como sensível no provedor local. O contrato autoritativo de parâmetros e tipos é a referência de API publicada do pacote nextpdf/enterprise; trate essa referência — não esta página — como o contrato.

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

composer require nextpdf/core
composer require nextpdf/enterprise:^3

use NextPDF\Enterprise\Accelerator\KmsProviderFactory;

// Selects the provider from environment configuration; defaults to the
// local HKDF-based provider. Supply the root key through your secret
// manager, never from source or logs.
$provider = KmsProviderFactory::fromEnvironment();

$key = $provider->getEncryptionKey('collection-1');
// $key is metadata only: key id, version, algorithm, provider name.

Exemplo de código — Produção

use NextPDF\Enterprise\Accelerator\KmsProviderFactory;

$provider = KmsProviderFactory::fromEnvironment();

$rotated = $provider->rotateKey('collection-1');
// The version advanced. Re-encrypt the collection's data files with the
// new key version. The provider returns metadata only; it never returns
// raw key bytes.

Os nomes das variáveis de ambiente, as chaves de configuração explícita e os tipos de exceção estão documentados na referência aprofundada do Accelerator.

Casos extremos e armadilhas

O provedor KMS local exige uma chave-mestra codificada em hexadecimal de pelo menos 32 bytes. Um valor mais curto ou não hexadecimal lança uma exceção de argumento tipada na construção.
Selecionar um nome de provedor em nuvem sem a integração correspondente instalada lança um erro de configuração tipado que nomeia a dependência ausente.
Um nome de provedor desconhecido lança um erro tipado que lista os nomes suportados.
O sidecar de GPU relata um modo degradado quando recorre à CPU. Verifique esse campo se você depende da vazão da GPU.
O modelo de embedding é carregado na primeira requisição; dimensione o tempo limite da primeira requisição de acordo.

Desempenho

A derivação de chave local é uma operação HKDF de custo constante. Ela não contata nenhum serviço externo. Uma requisição de embedding por GPU acrescenta uma ida e volta local ao sidecar mais o tempo de inferência do modelo. A primeira requisição também paga o custo único de carregamento do modelo. O fallback de CPU está correto, mas é mais lento que o caminho de GPU para o mesmo lote.

Notas de segurança

Um provedor KMS retorna metadados de chave, não os bytes brutos da chave. O value object de resultado de chave de criptografia nunca carrega o material de chave.
A chave-mestra do provedor local é um parâmetro de construtor sensível. Ela não é registrada em log nem serializada.
O provedor local não contata nenhum serviço externo. A derivação é determinística e em processo.
O uso de AES-GCM exige um vetor de inicialização único por chave, conforme a NIST SP 800-38D §5.

Residência de dados e mitigações de PII

O provedor KMS local é executado em processo e não contata nenhum serviço externo; nenhum material de chave e nenhum conteúdo de documento sai do host na derivação de chave local. O sidecar de GPU recebe o texto a ser submetido a embedding por meio de uma requisição local; ele não recebe conteúdo de documento não relacionado. Um provedor KMS em nuvem, quando configurado, contata o provedor de nuvem que você selecionar; revise a postura de residência de dados desse provedor para a sua jurisdição.

Telemetria segura e limpeza de logs

A chave-mestra do provedor local é um parâmetro de construtor sensível e é excluída dos logs e da serialização. Não adicione a chave-mestra, as chaves derivadas nem as credenciais do provedor aos logs da sua própria aplicação. Trate todo material de chave como um segredo na sua política de logging e tracing.

Modelo de ameaças

O provedor retorna metadados, não bytes de chave, então um vazamento de metadados não expõe material de chave. A segurança do provedor local depende do sigilo da chave-mestra configurada. A segurança de um provedor em nuvem depende desse provedor e da sua configuração. A proteção de chaves depende do KMS ou do segredo da chave-mestra, da implantação e do operador — não apenas deste software. Consulte o limite de implantação.

Conformidade

A versão da chave de criptografia de dados e o ciclo de vida de rotação alinham-se à NIST SP 800-57 Part 1 Rev.5 §4.
A responsabilidade de proteção de chaves alinha-se à NIST SP 800-57 Part 1 Rev.5 §5.5.2.
A unicidade do vetor de inicialização do AES-GCM alinha-se à NIST SP 800-38D §5.

Toda fonte normativa é parafraseada. Nenhum texto normativo é reproduzido nesta página. Esta página trata de gerenciamento de chaves.

Comportamento em modo FIPS

A derivação HKDF do provedor local usa SHA-256. O algoritmo de criptografia registrado nos metadados da chave é AES-256-GCM. Quando a aplicação é executada com um provedor criptográfico validado pelo FIPS, essas primitivas são executadas dentro desse limite validado. A própria fábrica de provedores seleciona e constrói o provedor; ela não certifica o limite criptográfico.

O NextPDF Enterprise não é um módulo criptográfico validado pelo FIPS e não faz nenhuma declaração de certificação FIPS. Ele opera em modo compatível com FIPS apenas quando configurado com um provedor criptográfico validado pelo FIPS ou um KMS validado pelo FIPS.

Limite de edição

O sidecar de embedding por GPU e a fábrica de provedores KMS são entregues apenas no pacote nextpdf/enterprise. O NextPDF Pro fornece integração KMS para estratégias de assinatura (AWS KMS, GCP Cloud KMS, Azure Key Vault), mas não fornece a fábrica de provedores KMS do Enterprise nem o sidecar de embedding por GPU. O transporte interno do sidecar e as classes internas do pipeline de embedding estão fora do escopo da superfície pública e não são reproduzidos aqui.

Fallback do Pro

O NextPDF Pro fornece estratégias de assinatura com KMS em nuvem — o KMS mantém a chave de assinatura, e o Pro envia o resumo dos atributos assinados ao provedor. Isso é uma integração de assinatura. Não é a fábrica de provedores de chaves de criptografia de dados em nível de coleção do Enterprise nem o sidecar de embedding por GPU. Consulte Accelerator — NextPDF Pro para a superfície de aceleração do Pro.

Fallback do Core

O NextPDF Core não tem sidecar de embedding por GPU nem fábrica de provedores KMS. Embedding e gerenciamento de chaves em nível de coleção são recursos exclusivos do Enterprise.

Nota sobre o limite do Enterprise

O transporte do sidecar de GPU, o identificador do modelo de embedding e as classes internas do pipeline são descritos apenas no nível de comportamento. O cliente de transporte interno, os tokens de escopo internos e a composição interna do pipeline estão fora do escopo da superfície pública e não são reproduzidos aqui.

Limite de implantação

O NextPDF Enterprise integra-se a um KMS ou deriva chaves a partir de um segredo de chave-mestra configurado. Ele próprio não armazena nem garante a segurança desse segredo de chave-mestra ou da chave do KMS em nuvem. A segurança das chaves depende do KMS ou do segredo da chave-mestra, da implantação e do operador — não apenas do NextPDF Enterprise. O operador é responsável pelo provisionamento da chave-mestra, pelo armazenamento de segredos, pela configuração do KMS e pelo agendamento de rotação. A responsabilidade de proteção de chaves segue a NIST SP 800-57 Part 1 Rev.5 §5.5.2. O NextPDF Enterprise não expõe os fluxos de credenciais do KMS nem os detalhes internos de manuseio da chave-mestra nesta documentação.

Limite de conformidade legal

Ela trata de gerenciamento de chaves. A declaração do modo FIPS é uma declaração de compatibilidade, não uma certificação nem um parecer jurídico. Consulte sua própria assessoria de conformidade e jurídica para conhecer suas obrigações regulatórias.

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 mecanismos, nomes de arquivo de runbook e prefixos de tíquete estão fora do escopo.

Contrato de comportamento

A fábrica de provedores seleciona o provedor a partir da configuração e retorna um provedor que satisfaz o contrato do provedor.
Um provedor retorna metadados de chave imutáveis e nunca retorna os bytes brutos da chave.
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.
O sidecar de GPU relata um modo degradado no fallback de CPU e lança uma exceção tipada quando está indisponível.

Consulte também

Referência do Accelerator — NextPDF Enterprise
Segurança — NextPDF Enterprise
Inteligência — NextPDF Enterprise
Accelerator — NextPDF Pro
KMS · DEK · HKDF — termos do glossário.