Enterprise edición

Accelerator: sidecar de GPU y fábrica de proveedores KMS

De un vistazo

NextPDF Enterprise añade dos funciones de aceleración: un sidecar de GPU para el embedding de texto con un repliegue a CPU, y una fábrica de proveedores KMS que suministra metadatos y rotación de claves de cifrado de datos a nivel de colección. Esta página expone el comportamiento, los límites y la postura de custodia de claves.

Disponibilidad y licencia

Esta capacidad se distribuye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Un despliegue sin ese derecho no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Descripción conceptual

El sidecar de GPU acelera el embedding de texto a vector. El paquete Enterprise envía el texto a un proceso sidecar independiente a través de una solicitud HTTP local. El sidecar ejecuta el modelo de embedding en una GPU cuando hay una disponible. Cuando no hay GPU disponible, el sidecar ejecuta el mismo modelo en la CPU e informa de que se ejecutó en modo degradado. El resultado es la misma forma de vector en ambos casos. El modelo de embedding se carga en la primera solicitud, por lo que la primera solicitud es más lenta que las posteriores. El sidecar es opcional; se expone una comprobación de disponibilidad, y un sidecar ausente genera una excepción tipada en lugar de un fallo silencioso.

La fábrica de proveedores KMS selecciona un proveedor de gestión de claves a partir de la configuración. La fábrica lee una variable de entorno para elegir el proveedor. El proveedor predeterminado deriva localmente una clave de cifrado de datos específica de la colección mediante HKDF-SHA256 a partir de una clave maestra configurada, con el identificador de la colección como separador de dominio. El proveedor local no contacta con ningún servicio externo; la derivación es determinista y en proceso. La fábrica también acepta una forma de configuración explícita para el proveedor local. Los proveedores en la nube —AWS KMS, GCP Cloud KMS, Azure Key Vault y HashiCorp Vault Transit— son nombres de proveedor reconocidos; seleccionar uno sin la integración correspondiente instalada genera un error de configuración tipado que nombra la dependencia ausente.

Un proveedor devuelve metadatos de la clave, no los bytes en bruto de la clave. Los metadatos registran el identificador de la clave, una versión de clave monótonamente creciente, el nombre del algoritmo de cifrado y el nombre del proveedor. Una llamada de rotación avanza la versión de la clave y devuelve los nuevos metadatos. El llamante es responsable de volver a cifrar los datos de la colección con la nueva versión de clave después de una rotación. La versión de clave y el ciclo de vida de la rotación siguen NIST SP 800-57 Part 1 Rev.5 §4.

Por qué funciona así

El embedding se ejecuta en un proceso sidecar de GPU independiente en lugar de dentro de la solicitud PHP. La carga del modelo en la GPU es costosa, por lo que el sidecar carga el modelo una vez y amortiza ese costo entre muchas solicitudes. Cuando no hay GPU presente, el sidecar ejecuta el mismo modelo en la CPU e informa de un modo degradado. El rendimiento puede caer, pero la corrección no: la forma del vector es idéntica en cualquier caso. El sidecar permanece opcional; una comprobación de disponibilidad y una excepción tipada ante un sidecar ausente mantienen la aceleración como una opción deliberada, no como una dependencia oculta. Esa separación permite que el embedding de alto volumen escale en hardware dedicado mientras el pipeline de documentos sigue siendo una simple llamada PHP.

Contexto de diseño: Generación de documentos de alto volumen.

Superficie de la API

Superficie pública	Tipo	Propósito	Estabilidad	Desde
Fábrica de proveedores KMS	clase	Construir un proveedor KMS a partir del entorno o de una configuración explícita	estable	2.1.0
Proveedor KMS	interfaz	Obtener metadatos de clave, rotar una clave e informar del nombre del proveedor	estable	2.1.0
Proveedor KMS local	clase (implementa la interfaz del proveedor)	Derivación local de claves con HKDF-SHA256; no contacta con ningún servicio externo	estable	2.1.0
Resultado de clave de cifrado	objeto de valor	Metadatos de clave inmutables: id de clave, versión, algoritmo, proveedor — sin bytes de clave en bruto	estable	2.1.0
Servicio de embedding por GPU	clase (implementa la interfaz de servicio de embedding de Core)	Hacer el embedding de texto en un sidecar de GPU con un repliegue a CPU	estable	2.1.0

La fábrica de proveedores expone un punto de entrada «desde el entorno» y un punto de entrada explícito de «creación». El valor de configuración de la clave maestra se marca como sensible en el proveedor local. El contrato autorizado de parámetros y tipos es la referencia de API publicada del paquete nextpdf/enterprise; trate esa referencia —no esta página— como el contrato.

Ejemplo de código — Inicio 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.

Ejemplo de código — Producción

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.

Los nombres de las variables de entorno, las claves de configuración explícitas y los tipos de excepción se documentan en la referencia profunda de Accelerator.

Casos límite y trampas

El proveedor KMS local requiere una clave maestra codificada en hexadecimal de al menos 32 bytes. Un valor más corto o no hexadecimal genera una excepción de argumento tipada en la construcción.
Seleccionar el nombre de un proveedor en la nube sin la integración correspondiente instalada genera un error de configuración tipado que nombra la dependencia ausente.
Un nombre de proveedor desconocido genera un error tipado que enumera los nombres admitidos.
El sidecar de GPU informa de un modo degradado cuando recurre a la CPU. Compruebe ese campo si depende del rendimiento de la GPU.
El modelo de embedding se carga en la primera solicitud; dimensione el tiempo de espera de la primera solicitud en consecuencia.

Rendimiento

La derivación local de claves es una operación HKDF de costo constante. No contacta con ningún servicio externo. Una solicitud de embedding por GPU añade un ciclo de ida y vuelta local al sidecar más el tiempo de inferencia del modelo. La primera solicitud también paga el costo único de carga del modelo. El repliegue a CPU es correcto, pero más lento que la ruta de GPU para el mismo lote.

Notas de seguridad

Un proveedor KMS devuelve metadatos de la clave, no los bytes en bruto de la clave. El objeto de valor de resultado de clave de cifrado nunca transporta el material de clave.
La clave maestra del proveedor local es un parámetro sensible del constructor. No se registra ni se serializa.
El proveedor local no contacta con ningún servicio externo. La derivación es determinista y en proceso.
El uso de AES-GCM requiere un vector de inicialización único por clave, según NIST SP 800-38D §5.

Residencia de datos y mitigaciones de PII

El proveedor KMS local se ejecuta en proceso y no contacta con ningún servicio externo; ningún material de clave ni contenido de documento sale del host para la derivación local de claves. El sidecar de GPU recibe el texto a procesar a través de una solicitud local; no recibe contenido de documento no relacionado. Un proveedor KMS en la nube, cuando está configurado, contacta con el proveedor en la nube que seleccione; revise la postura de residencia de datos de ese proveedor para su jurisdicción.

Telemetría segura y depuración de registros

La clave maestra del proveedor local es un parámetro sensible del constructor y se excluye de los registros y de la serialización. No añada la clave maestra, las claves derivadas ni las credenciales del proveedor a los registros de su propia aplicación. Trate todo el material de clave como un secreto en su política de registro y trazado.

Modelo de amenazas

El proveedor devuelve metadatos, no bytes de clave, por lo que una fuga de metadatos no expone el material de clave. La seguridad del proveedor local depende del secreto de la clave maestra configurada. La seguridad de un proveedor en la nube depende de ese proveedor y de su configuración. La protección de claves depende del KMS o del secreto de la clave maestra, del despliegue y del operador — no de este software por sí solo. Consulte el límite de despliegue.

Conformidad

La versión y el ciclo de vida de rotación de la clave de cifrado de datos se alinean con NIST SP 800-57 Part 1 Rev.5 §4.
La responsabilidad de protección de claves se alinea con NIST SP 800-57 Part 1 Rev.5 §5.5.2.
La unicidad del vector de inicialización de AES-GCM se alinea con NIST SP 800-38D §5.

Toda fuente normativa está parafraseada. No se reproduce ningún texto normativo en esta página. Esta página trata sobre gestión de claves.

Comportamiento en modo FIPS

La derivación HKDF del proveedor local utiliza SHA-256. El algoritmo de cifrado registrado en los metadatos de la clave es AES-256-GCM. Cuando la aplicación se ejecuta sobre un proveedor criptográfico validado con FIPS, esas primitivas se ejecutan dentro de ese límite validado. La fábrica de proveedores en sí selecciona y construye el proveedor; no certifica el límite criptográfico.

NextPDF Enterprise no es un módulo criptográfico validado con FIPS y no hace ninguna declaración de certificación FIPS. Opera en modo compatible con FIPS únicamente cuando se configura con un proveedor criptográfico validado con FIPS o un KMS validado con FIPS.

Límite de edición

El sidecar de embedding por GPU y la fábrica de proveedores KMS se distribuyen únicamente en el paquete nextpdf/enterprise. NextPDF Pro proporciona la integración de KMS para estrategias de firma (AWS KMS, GCP Cloud KMS, Azure Key Vault), pero no proporciona la fábrica de proveedores KMS de Enterprise ni el sidecar de embedding por GPU. El transporte interno del sidecar y las clases internas del pipeline de embedding quedan fuera del alcance de la superficie pública y no se reproducen aquí.

Alternativa de Pro

NextPDF Pro proporciona estrategias de firma con KMS en la nube — el KMS retiene la clave de firma, y Pro envía el resumen de atributos firmados al proveedor. Esa es una integración de firma. No es la fábrica de proveedores de claves de cifrado de datos a nivel de colección de Enterprise ni el sidecar de embedding por GPU. Consulte Accelerator — NextPDF Pro para la superficie de aceleración de Pro.

Alternativa de Core

NextPDF Core no tiene sidecar de embedding por GPU ni fábrica de proveedores KMS. El embedding y la gestión de claves a nivel de colección son funciones exclusivas de Enterprise.

Nota sobre el límite de Enterprise

El transporte del sidecar de GPU, el identificador del modelo de embedding y las clases internas del pipeline se describen únicamente a nivel de comportamiento. El cliente de transporte interno, los tokens de alcance internos y la composición interna del pipeline quedan fuera del alcance de la superficie pública y no se reproducen aquí.

Límite de despliegue

NextPDF Enterprise se integra con un KMS o deriva claves a partir de un secreto de clave maestra configurado. No almacena ni garantiza por sí mismo la seguridad de ese secreto de clave maestra ni de la clave del KMS en la nube. La seguridad de las claves depende del KMS o del secreto de la clave maestra, del despliegue y del operador — no de NextPDF Enterprise por sí solo. El operador es responsable del aprovisionamiento de la clave maestra, del almacenamiento de secretos, de la configuración del KMS y de la programación de la rotación. La responsabilidad de protección de claves sigue NIST SP 800-57 Part 1 Rev.5 §5.5.2. NextPDF Enterprise no expone en esta documentación los flujos de credenciales del KMS ni los detalles internos de manejo de la clave maestra.

Límite de cumplimiento legal

Trata sobre gestión de claves. La declaración de modo FIPS es una declaración de compatibilidad, no una certificación ni una opinión legal. Consulte a sus propios asesores de cumplimiento y legales sobre sus obligaciones regulatorias.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública de API admitida. Las rutas internas de espacio de nombres, las clases auxiliares, las tablas de mecanismos, los nombres de archivos de runbook y los prefijos de tickets quedan fuera del alcance.

Contrato de comportamiento

La fábrica de proveedores selecciona el proveedor a partir de la configuración y devuelve un proveedor que satisface el contrato del proveedor.
Un proveedor devuelve metadatos de clave inmutables y nunca devuelve bytes de clave en bruto.
Una llamada de rotación avanza la versión de la clave y devuelve los nuevos metadatos; el llamante vuelve a cifrar los datos de la colección.
El sidecar de GPU informa de un modo degradado en el repliegue a CPU y genera una excepción tipada cuando no está disponible.

Consulte también

Referencia de Accelerator — NextPDF Enterprise
Seguridad — NextPDF Enterprise
Inteligencia — NextPDF Enterprise
Accelerator — NextPDF Pro
KMS · DEK · HKDF — términos del glosario.