Accelerator — глубокий справочник (GPU sidecar, фабрика провайдеров KMS)

Краткий обзор

Эта страница — подробный справочник по публичной поверхности ускорения NextPDF\Enterprise\Accelerator. Она охватывает стек провайдеров KMS — фабрику, контракт провайдера, локальный провайдер и результат с метаданными ключа — а также службы GPU sidecar для эмбеддингов и векторного поиска. Она описывает параметры, значения по умолчанию, режимы сбоя и позицию по хранению ключей. Сначала прочитайте страницу возможности Accelerator для руководства по рабочим процессам. Другие символы в том же пространстве имён относятся к иным возможностям и находятся вне области охвата этой страницы.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Enterprise (nextpdf/enterprise) и активируется лицензионным конвертом уровня Enterprise. Развёртывание без этого права доступа не загружает классы возможности. Сравните редакции и получите лицензию.

Провайдер KMS выбирается во время выполнения; вызывающий код зависит от контракта провайдера, а не от конкретного провайдера. Службы эмбеддингов и векторного индекса реализуют контракты Core EmbeddingServiceInterface и VectorIndexInterface.

Публичная поверхность API

composer require nextpdf/enterprise:^3

Символ	Параметры	Поведение по умолчанию	Возвращает	Бросает или завершается с	Примечания
KmsProviderFactory::fromEnvironment	нет	Создаёт провайдер, названный переменной-селектором; отсутствие или пустое значение выбирает local	KmsProviderInterface	RuntimeException при отсутствии мастер-ключа, недоступном облачном провайдере или неизвестном имени	Статическая точка входа
KmsProviderFactory::create	string $providerType, array $config = []	Создаёт названный провайдер из явной конфигурации	KmsProviderInterface	RuntimeException, когда у local нет непустого encryption_key, или при неизвестном имени	local — единственное создаваемое имя в этом выпуске
KmsProviderInterface::getEncryptionKey	string $collectionId	Возвращает текущие метаданные ключа для коллекции	EncryptionKeyResult	RuntimeException, когда провайдер недоступен или неправильно настроен (контракт)	Только метаданные; никогда не сырые байты ключа
KmsProviderInterface::rotateKey	string $collectionId	Продвигает версию ключа	EncryptionKeyResult	RuntimeException, когда ротация не удаётся (контракт)	Ротация — сигнал повторного шифрования для вызывающего кода
KmsProviderInterface::providerName	нет	Сообщает каноническое имя провайдера	string	Ничего не объявлено	local, aws, gcp, azure, vault
LocalKmsProvider::__construct	string $encryptionKey (чувствительный)	Проверяет hex-мастер-ключ длиной не менее 64 hex-символов (32 байта)	LocalKmsProvider	InvalidArgumentException при коротком или не-hex значении	Проверка с быстрым отказом; сам деривацию не выполняет
LocalKmsProvider::getEncryptionKey	string $collectionId	Формирует local:{collectionId}:v{version}; версия по умолчанию 1	EncryptionKeyResult	Ничего не объявлено	Метка алгоритма AES-256-GCM
LocalKmsProvider::rotateKey	string $collectionId	Увеличивает внутрипроцессный счётчик версий	EncryptionKeyResult	Ничего не объявлено	Состояние версии — на экземпляр
EncryptionKeyResult::__construct	string $keyId, int $keyVersion, string $algorithm = 'AES-256-GCM', string $provider = 'local'	Неизменяемый объект-значение с метаданными	EncryptionKeyResult	Ничего не объявлено	Никогда не несёт ключевой материал
GpuEmbeddingService::embed	string $text	Делегирует batchEmbed и возвращает нулевой элемент	list<float>	Как batchEmbed	Вектор размерности 1024
GpuEmbeddingService::batchEmbed	array $texts	Вычисляет эмбеддинги пакета на sidecar	list<list<float>>	InvalidArgumentException при пустом пакете; SpectrumNotAvailableException, когда sidecar недоступен; SpectrumApiException при неуспешном, некорректном или несовпадающем по количеству ответе	Никогда не возвращает частичные результаты
GpuEmbeddingService::getDimension	нет	Возвращает 1024	int	Ничего не объявлено	Константа
GpuEmbeddingService::getModelName	нет	Возвращает multilingual-e5-large	string	Ничего не объявлено	Константа
GpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Привязывает дескриптор к одной коллекции	GpuVectorIndex	Ничего не объявлено	Один дескриптор на идентификатор коллекции
GpuVectorIndex::build	array $vectors, array $ids	Строит индекс коллекции на sidecar	void	InvalidArgumentException при пустом пакете или несовпадении длины; SpectrumNotAvailableException, когда недоступен; SpectrumApiException при неожиданном ответе на построение	Повторное построение заменяет индекс
GpuVectorIndex::search	array $queryVector, int $topK = 10	Ранжированный поиск ближайших соседей	list<VectorSearchResult>	SpectrumNotAvailableException, когда недоступен; JsonException при некорректном теле ответа	Ранг каждого попадания в метаданных результата
GpuVectorIndex::delete	array $ids	Всегда отклоняет	void (объявлено)	Всегда: SpectrumApiException (не реализовано)	Построенный индекс неизменяем; выполните повторное построение
GpuVectorIndex::count	нет	Читает общее число коллекции с sidecar	int	Не бросает; любой сбой возвращает 0	0 неоднозначен: пусто или недоступен

Сигнатуры точек входа

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
}

Поверхность конфигурации

Настройка	Потребитель	Значение
SPECTRUM_KMS_PROVIDER	fromEnvironment()	Селектор провайдера. Отсутствие или пустое значение разрешается в local.
SPECTRUM_ENCRYPTION_KEY	Путь провайдера local	Мастер-ключ в hex-кодировке; не менее 64 hex-символов (32 байта). Разделяется с sidecar.
encryption_key	create('local', [...])	Явный мастер-ключ; тот же формат и проверка.

Контракт поведения

Выбор провайдера

KmsProviderFactory::fromEnvironment читает переменную-селектор и по умолчанию использует local. Имена облачных провайдеров aws, gcp, azure и vault распознаются, но не создаются в этом выпуске. Выбор aws вызывает типизированную ошибку с указанием требуемого пакета aws/aws-sdk-php; остальные три сообщают, что интеграция не реализована. Неизвестное имя вызывает типизированную ошибку с перечислением поддерживаемых имён. KmsProviderFactory::create принимает явное имя провайдера и карту конфигурации; local — единственное имя, которое он создаёт.

Метаданные и хранение ключей

Провайдер возвращает неизменяемые метаданные ключа: идентификатор ключа, монотонно возрастающую версию ключа, метку алгоритма и имя провайдера. Он никогда не возвращает сырые байты ключа, поэтому утечка метаданных не раскрывает ключевой материал. Локальный провайдер разделяет обязанности с sidecar ускорителя. PHP-класс проверяет мастер-секрет при создании и формирует стабильную, привязанную к коллекции идентичность ключа вида local:{collectionId}:v{version}. Sidecar выполняет деривацию HKDF-SHA256 и шифрование AES-256-GCM, выводя отдельный 32-байтовый ключ шифрования данных на каждую коллекцию, используя идентификатор коллекции и версию как разделение домена. Обе стороны читают один и тот же настроенный мастер-секрет. Ни к какой внешней службе KMS обращения нет; обработка ключей остаётся внутри развёртывания. Версия ключа и модель жизненного цикла следуют NIST SP 800-57 Part 1 Rev.5 §4.

Вызов ротации продвигает версию ключа и возвращает новые метаданные. Вызывающий код повторно шифрует данные коллекции новой версией; сам провайдер ничего не перешифровывает.

Безопасность ключа зависит от KMS или секрета мастер-ключа, от развёртывания и от оператора — а не только от NextPDF Enterprise. Оператор владеет подготовкой мастер-ключа, хранением секретов, конфигурацией KMS и планированием ротации. Ответственность за защиту ключа следует NIST SP 800-57 Part 1 Rev.5 §5.5.2.

Эмбеддинги на GPU

GpuEmbeddingService реализует контракт эмбеддингов Core и делегирует sidecar. Sidecar запускает модель эмбеддингов на GPU, когда он доступен, и иначе переходит на CPU, помечая метаданные ответа как деградировавшие с GPU. Форма вектора идентична в обоих случаях. Модель (около 1,3 ГБ) загружается и подгружается лениво при первом запросе. Семантика пакета — «всё или ничего»: сбой отдельного элемента, некорректный вектор или несовпадение количества вызывает типизированную ошибку вместо возврата частичных результатов.

Векторный поиск на GPU

GpuVectorIndex реализует контракт векторного индекса Core и привязывает один дескриптор к одному идентификатору коллекции. build строит индекс на sidecar; sidecar использует GPU-индекс, когда он доступен, и иначе CPU-индекс. После построения индекс неизменяем: delete всегда отклоняет с типизированной ошибкой «не реализовано», а удаление требует повторного построения. search возвращает ранжированные попадания с рангом от единицы в метаданных каждого результата. count запрашивает у sidecar общее число коллекции и при любом сбое сообщает 0, а не бросает исключение.

Граничные случаи и режимы сбоя

• Мастер-ключ должен декодироваться из hex не менее чем в 32 байта. Более короткое или не-hex значение вызывает InvalidArgumentException при создании, до любого вызова sidecar.
• Отсутствующая или пустая переменная-селектор разрешается в local; фабрика никогда не угадывает другой провайдер.
• fromEnvironment на пути local без переменной мастер-ключа вызывает типизированную ошибку с указанием отсутствующей переменной.
• create('local', [...]) без непустой записи encryption_key вызывает типизированную ошибку с указанием отсутствующей записи.
• Состояние версии ключа — внутрипроцессное и на экземпляр провайдера. Новый процесс наблюдает версию 1, пока ротация не выполнится снова. Сохраняйте результаты ротации, повторно шифруя данные, а не полагаясь на состояние провайдера.
• Пустой пакет эмбеддингов вызывает InvalidArgumentException; к sidecar обращения нет.
• Доступность sidecar проверяется при каждом вызове. Недоступный sidecar вызывает SpectrumNotAvailableException; службы никогда не завершаются молча.
• Нечисловой компонент внутри возвращённого вектора эмбеддинга приводится к 0.0; отсутствующий или не-массивный вектор вызывает SpectrumApiException.
• Первый запрос эмбеддинга оплачивает разовую загрузку и подгрузку модели; задавайте этот таймаут отдельно.
• build и search строго декодируют ответ sidecar; некорректное тело вызывает JsonException. count поглощает любой сбой и возвращает 0.
• Попадание поиска без идентификатора или оценки по умолчанию получает пустую строку и 0.0, а не срывает пакет.
• Коды ошибок sidecar и иерархия исключений каталогизированы в справочнике ошибок Accelerator.

Поведение в режиме FIPS

Локальный путь ключа использует HKDF-SHA256 для деривации и AES-256-GCM для шифрования; sidecar выполняет оба. Метка алгоритма, записанная в метаданных ключа, — AES-256-GCM. Когда развёртывание работает с провайдером криптографии, валидированным по FIPS, эти примитивы выполняются в этой валидированной границе. Использование AES-GCM требует уникального вектора инициализации на каждый ключ, согласно NIST SP 800-38D §5.

NextPDF Enterprise не является валидированным по FIPS криптографическим модулем и не делает заявлений о сертификации FIPS. Он работает в режиме, совместимом с FIPS, только при настройке с провайдером криптографии, валидированным по FIPS, или с KMS, валидированным по FIPS. В этом репозитории нет артефакта сертификации FIPS.

Соответствие

Заявление	Стандарт	Пункт
Версия ключа и модель жизненного цикла следуют руководству по состояниям ключей.	NIST SP 800-57 Part 1 Rev.5	§4
Ответственность за защиту и хранение ключа лежит на владельце ключа и операторе.	NIST SP 800-57 Part 1 Rev.5	§5.5.2
AES-GCM требует уникального вектора инициализации на каждый ключ.	NIST SP 800-38D	§5

Все пункты изложены в пересказе; NextPDF не воспроизводит нормативный текст. NextPDF не делает заявлений о сертификации. Соответствие цитируемым пунктам — это заявление о возможностях, а не сертификация. Эта страница касается управления ключами; заявление о режиме FIPS — это заявление о совместимости, а не юридическое заключение. Обращайтесь к собственным консультантам по комплаенсу и праву.

Заметки для разработчиков

• Исходный код модуля содержит @since 2.1.0; этот справочник документирует поверхность в том виде, как она поставлена в nextpdf/enterprise 3.1.0.
• Все классы final; EncryptionKeyResult — final readonly. Создавайте новые экземпляры вместо изменения.
• Мастер-ключ — чувствительный параметр конструктора (#[SensitiveParameter]); PHP скрывает его из трассировок стека. Держите его вне журналов приложения и дампов конфигурации.
• SpectrumClient, VectorSearchResult, а также контракты EmbeddingServiceInterface и VectorIndexInterface происходят из NextPDF Core; вызывающий код создаёт и предоставляет клиент sidecar.
• Пространство имён NextPDF\Enterprise\Accelerator также содержит движки пакетной разгрузки, а также стеки коллекций извлечения и OCR-извлечения; эти поверхности находятся вне области охвата этой страницы.
• Детали внутреннего механизма остаются во внутренней документации исходного репозитория и находятся вне области охвата этого руководства.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы заявок находятся вне области охвата.

См. также

• Accelerator — GPU sidecar и фабрика провайдеров KMS — страница возможности для руководства по рабочим процессам и хранению.
• Справочник ошибок Accelerator — иерархия исключений sidecar и коды ошибок.
• Security — подробный справочник
• Accelerator — подробный справочник NextPDF Pro