Accelerator — Referencia detallada (sidecar de GPU, fábrica de proveedores KMS)

De un vistazo

Esta página es la referencia detallada de la superficie pública de aceleración de NextPDF\Enterprise\Accelerator. Cubre la pila de proveedores KMS — la fábrica, el contrato del proveedor, el proveedor local y el resultado de metadatos de clave — y los servicios del sidecar de GPU para incrustación y búsqueda vectorial. Enuncia parámetros, valores predeterminados, modos de fallo y la postura de custodia de claves. Leer primero la página de capacidad de Accelerator para orientación sobre el flujo de trabajo. Otros símbolos del mismo espacio de nombres pertenecen a otras capacidades y quedan fuera del alcance de esta página.

Disponibilidad y licencias

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.

El proveedor KMS se selecciona en tiempo de ejecución; el código llamante depende del contrato del proveedor, no del proveedor concreto. Los servicios de incrustación y de índice vectorial implementan los contratos EmbeddingServiceInterface y VectorIndexInterface de Core.

Superficie de la API pública

composer require nextpdf/enterprise:^3

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
KmsProviderFactory::fromEnvironment	ninguno	Construye el proveedor nombrado por la variable selectora; sin definir o vacía selecciona local	KmsProviderInterface	RuntimeException ante una clave maestra ausente, un proveedor de nube no disponible o un nombre desconocido	Punto de entrada estático
KmsProviderFactory::create	string $providerType, array $config = []	Construye el proveedor nombrado a partir de configuración explícita	KmsProviderInterface	RuntimeException cuando local carece de un encryption_key no vacío, o ante un nombre desconocido	local es el único nombre construible en esta versión
KmsProviderInterface::getEncryptionKey	string $collectionId	Devuelve los metadatos de clave actuales de la colección	EncryptionKeyResult	RuntimeException cuando el proveedor es inaccesible o está mal configurado (contrato)	Solo metadatos; nunca los bytes de la clave en bruto
KmsProviderInterface::rotateKey	string $collectionId	Avanza la versión de la clave	EncryptionKeyResult	RuntimeException cuando la rotación falla (contrato)	La rotación es una señal de recifrado para el llamante
KmsProviderInterface::providerName	ninguno	Informa el nombre canónico del proveedor	string	Nada declarado	local, aws, gcp, azure, vault
LocalKmsProvider::__construct	string $encryptionKey (sensible)	Valida una clave maestra hexadecimal de al menos 64 caracteres hex (32 bytes)	LocalKmsProvider	InvalidArgumentException ante un valor corto o no hexadecimal	Guardia de fallo rápido; no realiza derivación por sí mismo
LocalKmsProvider::getEncryptionKey	string $collectionId	Acuña local:{collectionId}:v{version}; la versión es 1 de forma predeterminada	EncryptionKeyResult	Nada declarado	Etiqueta de algoritmo AES-256-GCM
LocalKmsProvider::rotateKey	string $collectionId	Incrementa el contador de versión en el proceso	EncryptionKeyResult	Nada declarado	El estado de la versión es por instancia
EncryptionKeyResult::__construct	string $keyId, int $keyVersion, string $algorithm = 'AES-256-GCM', string $provider = 'local'	Objeto de valor de metadatos inmutable	EncryptionKeyResult	Nada declarado	Nunca transporta material de clave
GpuEmbeddingService::embed	string $text	Delega en batchEmbed y devuelve el elemento cero	list<float>	Como batchEmbed	Vector de 1024 dimensiones
GpuEmbeddingService::batchEmbed	array $texts	Incrusta el lote en el sidecar	list<list<float>>	InvalidArgumentException ante un lote vacío; SpectrumNotAvailableException cuando el sidecar es inaccesible; SpectrumApiException ante una respuesta fallida, malformada o con recuento no coincidente	Nunca devuelve resultados parciales
GpuEmbeddingService::getDimension	ninguno	Devuelve 1024	int	Nada declarado	Constante
GpuEmbeddingService::getModelName	ninguno	Devuelve multilingual-e5-large	string	Nada declarado	Constante
GpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Vincula el manejador a una colección	GpuVectorIndex	Nada declarado	Un manejador por identificador de colección
GpuVectorIndex::build	array $vectors, array $ids	Construye el índice de la colección en el sidecar	void	InvalidArgumentException ante un lote vacío o un desajuste de longitud; SpectrumNotAvailableException cuando es inaccesible; SpectrumApiException ante una respuesta de construcción inesperada	Una reconstrucción reemplaza el índice
GpuVectorIndex::search	array $queryVector, int $topK = 10	Búsqueda ordenada del vecino más cercano	list<VectorSearchResult>	SpectrumNotAvailableException cuando es inaccesible; JsonException ante un cuerpo de respuesta malformado	Rango por acierto en los metadatos del resultado
GpuVectorIndex::delete	array $ids	Siempre rechaza	void (declarado)	Siempre: SpectrumApiException (no implementado)	El índice construido es inmutable; reconstruir en su lugar
GpuVectorIndex::count	ninguno	Lee el total de la colección desde el sidecar	int	No lanza; cualquier fallo devuelve 0	0 es ambiguo: vacío o inaccesible

Firmas de los puntos 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
}

Superficie de configuración

Ajuste	Consumidor	Significado
SPECTRUM_KMS_PROVIDER	fromEnvironment()	Selector de proveedor. Sin definir o vacío se resuelve a local.
SPECTRUM_ENCRYPTION_KEY	La ruta del proveedor local	Clave maestra codificada en hex; al menos 64 caracteres hex (32 bytes). Compartida con el sidecar.
encryption_key	create('local', [...])	Clave maestra explícita; mismo formato y validación.

Contrato de comportamiento

Selección de proveedor

KmsProviderFactory::fromEnvironment lee la variable selectora y toma local de forma predeterminada. Los nombres de proveedor de nube aws, gcp, azure y vault se reconocen pero no son construibles en esta versión. Seleccionar aws genera un error tipado que nombra el paquete requerido aws/aws-sdk-php; los otros tres informan que la integración no está implementada. Un nombre desconocido genera un error tipado que enumera los nombres admitidos. KmsProviderFactory::create acepta un nombre de proveedor explícito y un mapa de configuración; local es el único nombre que construye.

Metadatos y custodia de claves

Un proveedor devuelve metadatos de clave inmutables: un identificador de clave, una versión de clave monótonamente creciente, la etiqueta del algoritmo y el nombre del proveedor. Nunca devuelve los bytes de la clave en bruto, de modo que una fuga de metadatos no expone material de clave. El proveedor local reparte funciones con el sidecar del acelerador. La clase PHP valida el secreto maestro en la construcción y acuña una identidad de clave estable, con alcance de colección, de la forma local:{collectionId}:v{version}. El sidecar realiza la derivación HKDF-SHA256 y el cifrado AES-256-GCM, derivando una clave de cifrado de datos distinta de 32 bytes por colección, con el identificador de colección y la versión como separación de dominio. Ambos lados leen el mismo secreto maestro configurado. No se contacta ningún servicio KMS externo; el manejo de claves permanece dentro del despliegue. La versión de clave y el modelo de ciclo de vida siguen NIST SP 800-57 Part 1 Rev.5 §4.

Una llamada de rotación avanza la versión de la clave y devuelve los nuevos metadatos. El llamante recifra los datos de la colección con la nueva versión; el proveedor no recifra nada por sí mismo.

La seguridad de las claves depende del KMS o del secreto de 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 del secreto, de la configuración del KMS y de la programación de la rotación. La responsabilidad de la protección de claves sigue NIST SP 800-57 Part 1 Rev.5 §5.5.2.

Incrustación en GPU

GpuEmbeddingService implementa el contrato de incrustación de Core y delega en el sidecar. El sidecar ejecuta el modelo de incrustación en una GPU cuando hay una disponible y, en caso contrario, repliega a la CPU, marcando los metadatos de la respuesta como degradados respecto de la GPU. La forma del vector es idéntica en ambos casos. El modelo (alrededor de 1,3 GB) se descarga y se carga de forma diferida en la primera solicitud. La semántica de lote es de todo o nada: un fallo por elemento, un vector malformado o un recuento no coincidente genera un error tipado en lugar de devolver resultados parciales.

Búsqueda vectorial en GPU

GpuVectorIndex implementa el contrato de índice vectorial de Core y vincula un manejador a un identificador de colección. build construye el índice en el sidecar; el sidecar usa un índice en GPU cuando hay una disponible y un índice en CPU en caso contrario. El índice es inmutable una vez construido: delete siempre rechaza con un error tipado de no implementado, y la eliminación requiere una reconstrucción. search devuelve aciertos ordenados con un rango basado en uno en los metadatos de cada resultado. count pide al sidecar el total de la colección e informa 0 ante cualquier fallo en lugar de generar una excepción.

Casos límite y modos de fallo

• La clave maestra debe decodificarse de hex a al menos 32 bytes. Un valor más corto o no hexadecimal genera InvalidArgumentException en la construcción, antes de cualquier llamada al sidecar.
• Una variable selectora sin definir o vacía se resuelve a local; la fábrica nunca adivina otro proveedor.
• fromEnvironment en la ruta local sin la variable de clave maestra genera un error tipado que nombra la variable ausente.
• create('local', [...]) sin una entrada encryption_key no vacía genera un error tipado que nombra la entrada ausente.
• El estado de la versión de clave es interno al proceso y por instancia de proveedor. Un nuevo proceso observa la versión 1 hasta que la rotación se ejecute de nuevo. Persistir los resultados de la rotación recifrando los datos, no confiando en el estado del proveedor.
• Un lote de incrustación vacío genera InvalidArgumentException; no se contacta el sidecar.
• La disponibilidad del sidecar se comprueba en cada llamada. Un sidecar inaccesible genera SpectrumNotAvailableException; los servicios nunca fallan de forma silenciosa.
• Un componente no numérico dentro de un vector de incrustación devuelto se fuerza a 0.0; un vector ausente o que no sea un array genera SpectrumApiException.
• La primera solicitud de incrustación paga el coste único de descarga y carga del modelo; dimensionar ese tiempo de espera por separado.
• build y search decodifican la respuesta del sidecar de forma estricta; un cuerpo malformado genera JsonException. count absorbe cualquier fallo y devuelve 0.
• Un acierto de búsqueda al que le falta su identificador o su puntuación toma de forma predeterminada una cadena vacía y 0.0 en lugar de hacer fallar el lote.
• Los códigos de error del sidecar y la jerarquía de excepciones se catalogan en la referencia de errores de Accelerator.

Comportamiento en modo FIPS

La ruta de clave local usa HKDF-SHA256 para la derivación y AES-256-GCM para el cifrado; el sidecar ejecuta ambos. La etiqueta de algoritmo registrada en los metadatos de clave es AES-256-GCM. Cuando el despliegue se ejecuta contra un proveedor criptográfico validado por FIPS, esas primitivas se ejecutan dentro de ese límite validado. El uso de AES-GCM requiere un vector de inicialización único por clave, según NIST SP 800-38D §5.

NextPDF Enterprise no es un módulo criptográfico validado por FIPS y no realiza ninguna afirmación de certificación FIPS. Opera en un modo compatible con FIPS solo cuando se configura con un proveedor criptográfico validado por FIPS o un KMS validado por FIPS. No existe ningún artefacto de certificación FIPS en este repositorio.

Conformidad

Afirmación	Estándar	Cláusula
La versión de clave y el modelo de ciclo de vida siguen la guía de estados de clave.	NIST SP 800-57 Part 1 Rev.5	§4
La responsabilidad de protección y custodia de claves recae en el propietario de la clave y en el operador.	NIST SP 800-57 Part 1 Rev.5	§5.5.2
AES-GCM requiere un vector de inicialización único por clave.	NIST SP 800-38D	§5

Todas las cláusulas están parafraseadas; NextPDF no reproduce texto normativo. NextPDF no realiza ninguna afirmación de certificación. La alineación con las cláusulas citadas es una declaración de capacidad, no una certificación. Esta página trata sobre la gestión de claves; la declaración de modo FIPS es una declaración de compatibilidad, no una opinión legal. Consultar a los propios asesores de cumplimiento y legales.

Notas de desarrollo

• El código fuente del módulo lleva @since 2.1.0; esta referencia documenta la superficie tal como se distribuye en nextpdf/enterprise 3.1.0.
• Todas las clases son final; EncryptionKeyResult es final readonly. Construir nuevas instancias en lugar de mutar.
• La clave maestra es un parámetro de constructor sensible (#[SensitiveParameter]); PHP la redacta de los rastros de pila. Mantenerla fuera de los registros de la aplicación y de los volcados de configuración.
• SpectrumClient, VectorSearchResult y los contratos EmbeddingServiceInterface y VectorIndexInterface provienen de NextPDF Core; el llamante construye y suministra el cliente del sidecar.
• El espacio de nombres NextPDF\Enterprise\Accelerator también contiene motores de descarga por lotes y las pilas de colección de recuperación y de extracción por OCR; esas superficies quedan fuera del alcance de esta página.
• El detalle del mecanismo interno permanece en la documentación interna del repositorio de origen y queda fuera del alcance de este manual.

Límite de publicación

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

Véase también

• Accelerator — sidecar de GPU y fábrica de proveedores KMS — la página de capacidad para orientación sobre flujo de trabajo y custodia.
• Referencia de errores de Accelerator — jerarquía de excepciones del sidecar y códigos de error.
• Seguridad — Referencia detallada
• Accelerator — Referencia detallada de NextPDF Pro