加速器 — 深度参考（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	当 local 缺少非空的 encryption_key，或名称未知时抛出 RuntimeException	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（敏感）	校验一个至少 64 个十六进制字符（32 字节）的十六进制主密钥	LocalKmsProvider	值过短或非十六进制时抛出 InvalidArgumentException	快速失败守卫；自身不执行任何派生
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；sidecar 不可达时抛出 SpectrumNotAvailableException；响应失败、格式错误或数量不匹配时抛出 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 提供方路径	十六进制编码的主密钥；至少 64 个十六进制字符（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 可用时于 GPU 上运行嵌入模型，否则回退到 CPU，并将响应元数据标记为已从 GPU 降级。两种情况下向量形状相同。模型（约 1.3 GB）在首次请求时惰性下载并加载。批处理语义是全有或全无：单项失败、格式错误的向量或数量不匹配都会抛出一个带类型的错误，而不是返回部分结果。

GPU 向量搜索

GpuVectorIndex 实现 Core 的向量索引契约，并将一个句柄绑定到一个集合标识符。build 在 sidecar 上构建索引；sidecar 在有 GPU 可用时使用 GPU 索引，否则使用 CPU 索引。索引一经构建即不可变：delete 总是以一个带类型的未实现错误拒绝，移除需要重建。search 返回带排名的命中，每个结果的元数据中带有从 1 开始的排名。count 向 sidecar 查询集合总数，并在任何失败时报告 0 而不抛出。

边界情况与失败模式

• 主密钥必须能从十六进制解码为至少 32 字节。更短或非十六进制的值会在构造时、任何 sidecar 调用之前抛出 InvalidArgumentException。
• 未设置或为空的选择器变量解析为 local；工厂绝不猜测其他提供方。
• 在 local 路径上调用 fromEnvironment 而缺少主密钥变量时，会抛出一个带类型的错误，指出缺失的变量。
• 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 表面。内部命名空间路径、辅助类、机制表、运行手册文件名，以及工单前缀不在范围内。

另请参阅

• Accelerator — GPU sidecar 与 KMS 提供方工厂 — 用于工作流与保管指引的能力页。
• Accelerator 错误参考 — sidecar 异常层次结构与错误码。
• Security — 深度参考
• Accelerator — NextPDF Pro 深度参考