Accelerator — GPU 旁车与 KMS 提供方工厂

概览

NextPDF Enterprise 增加了两项加速功能：一个用于文本嵌入、带 CPU 回退的 GPU 旁车，以及一个为集合级数据加密密钥提供元数据与轮换的 KMS 提供方工厂。本页说明其行为、边界，以及密钥保管立场。

可用性与授权

此能力随 NextPDF Enterprise（nextpdf/enterprise）发行，并在具备 Enterprise 层级授权信封时激活。缺少该权益的部署不会加载此能力的相关类。比较各版本并获取授权。

概念总览

GPU 旁车用于加速文本到向量的嵌入。Enterprise 包会通过一次本地 HTTP 请求，把文本发送给一个独立的旁车进程。当有 GPU 可用时，旁车会在 GPU 上运行嵌入模型。当 GPU 不可用时，旁车会在 CPU 上运行同一个模型，并报告它以降级模式运行。两种情况下得到的向量形状相同。嵌入模型在首次请求时加载，因此首次请求比后续请求更慢。旁车是可选的；系统对外暴露了一个可用性检查，旁车缺失时会抛出一个有类型的异常，而不是静默失败。

KMS 提供方工厂会根据配置选择一个密钥管理提供方。工厂读取一个环境变量来选择提供方。默认提供方会以配置好的主密钥为基础，使用 HKDF-SHA256 在本地派生出集合专属的数据加密密钥，并以集合标识符作为域分隔符。本地提供方不联系任何外部服务；派生过程是确定性的，且在进程内完成。工厂也接受本地提供方的显式配置形式。云提供方——AWS KMS、GCP Cloud KMS、Azure Key Vault 与 HashiCorp Vault Transit——是受识别的提供方名称；在未安装对应集成的情况下选择其中之一，会抛出一个有类型的配置错误，并指明缺失的依赖。

提供方返回的是密钥元数据，而非原始密钥字节。元数据记录密钥标识符、单调递增的密钥版本、加密算法名称，以及提供方名称。一次轮换调用会推进密钥版本，并返回新的元数据。轮换之后，调用方负责用新的密钥版本重新加密集合数据。密钥版本与轮换生命周期遵循 NIST SP 800-57 Part 1 Rev.5 §4。

为何如此设计

嵌入运行在一个独立的 GPU 旁车进程中，而非 PHP 请求内部。GPU 模型加载成本高昂，因此旁车只加载一次模型，并把该成本摊薄到许多请求上。当没有 GPU 时，旁车会在 CPU 上运行同一个模型，并报告降级模式。吞吐可能下降，但正确性不会：向量形状两种方式都完全一致。旁车保持可选；一个可用性检查以及旁车缺失时的有类型异常，让加速成为一次有意的显式选择，而非隐藏的依赖。这种分离让高流量嵌入得以在专用硬件上扩展，同时让文档管线保持为一次普通的 PHP 调用。

设计背景：高流量文档生成。

API 接口

公开接口	类型	用途	稳定性	起始版本
KMS 提供方工厂	class	从环境或显式配置构建一个 KMS 提供方	stable	2.1.0
KMS 提供方	interface	获取密钥元数据、轮换密钥，并报告提供方名称	stable	2.1.0
本地 KMS 提供方	class（实现提供方接口）	本地 HKDF-SHA256 密钥派生；不联系任何外部服务	stable	2.1.0
加密密钥结果	value object	不可变的密钥元数据：key id、版本、算法、提供方——不含原始密钥字节	stable	2.1.0
GPU 嵌入服务	class（实现 Core 嵌入服务接口）	在 GPU 旁车上嵌入文本，带 CPU 回退	stable	2.1.0

提供方工厂暴露一个“from environment”入口点与一个显式的“create”入口点。主密钥配置值在本地提供方中被标记为敏感。参数与类型契约的权威来源是 nextpdf/enterprise 包的已发布 API 参考；请把该参考——而非本页——视为契约。

代码示例 — 快速开始

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

Build the local KMS provider and read key metadata

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.

代码示例 — 生产

Rotate a collection key, then re-encrypt collection data

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.

环境变量名称、显式配置键，以及异常类型，都记录在 Accelerator 深度参考 中。

边界情况与注意事项

• 本地 KMS 提供方要求一个至少 32 字节、以十六进制编码的主密钥。更短或非十六进制的值会在构造时抛出一个有类型的参数异常。
• 在未安装对应集成的情况下选择某个云提供方名称，会抛出一个有类型的配置错误，并指明缺失的依赖。
• 未知的提供方名称会抛出一个有类型的错误，并列出受支持的名称。
• GPU 旁车在回退到 CPU 时会报告降级模式。如果你依赖 GPU 吞吐，请检查该字段。
• 嵌入模型在首次请求时加载；请据此设置首次请求的超时时间。

性能

本地密钥派生是一次成本恒定的 HKDF 运算。它不联系任何外部服务。一次 GPU 嵌入请求会增加一次到旁车的本地往返，外加模型推理时间。首次请求还会额外承担一次性的模型加载成本。CPU 回退结果正确，但对同一批次而言，比 GPU 路径更慢。

安全说明

• KMS 提供方返回的是密钥元数据，而非原始密钥字节。加密密钥结果值对象绝不携带密钥素材。
• 本地提供方主密钥是一个敏感的构造参数。它不会被记录，也不会被序列化。
• 本地提供方不联系任何外部服务。派生过程是确定性的，且在进程内完成。
• 依据 NIST SP 800-38D §5，使用 AES-GCM 要求每个密钥都使用唯一的初始化向量。

数据驻留与个人信息缓解

本地 KMS 提供方在进程内运行，不联系任何外部服务；本地密钥派生过程中，没有任何密钥素材、也没有任何文档内容离开主机。GPU 旁车通过一次本地请求接收待嵌入的文本；它不会接收无关的文档内容。当配置了云 KMS 提供方时，它会联系你所选择的云提供方；请针对你的司法管辖区，审查该提供方的数据驻留立场。

安全遥测与日志清洗

本地提供方主密钥是一个敏感的构造参数，会被排除在日志与序列化之外。请不要把主密钥、派生密钥或提供方凭据加入你自己的应用程序日志。在你的日志与追踪策略中，请把所有密钥素材都当作机密对待。

威胁模型

提供方返回的是元数据，而非密钥字节，因此一次元数据泄露并不会暴露密钥素材。本地提供方的安全性取决于所配置主密钥的保密性。云提供方的安全性取决于该提供方与你的配置。密钥保护取决于 KMS 或主密钥机密、取决于部署，并取决于操作方——而不仅仅取决于本软件。参见部署边界。

符合性

• 数据加密密钥的版本与轮换生命周期对齐 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。

每一项规范性来源都以转述方式呈现。本页不复现任何规范性原文。本页涉及密钥管理。

FIPS 模式行为

本地提供方的 HKDF 派生使用 SHA-256。密钥元数据中记录的加密算法为 AES-256-GCM。当应用程序运行在通过 FIPS 验证的密码学提供方之上时，这些原语会在该已验证边界内运行。提供方工厂本身只负责选择并构造提供方；它并不为密码学边界做认证。

NextPDF Enterprise 不是通过 FIPS 验证的密码学模块，也不作出任何 FIPS 认证声明。 只有在配置了通过 FIPS 验证的密码学提供方或通过 FIPS 验证的 KMS 时，它才以 FIPS 兼容模式运行。

版本边界

GPU 嵌入旁车与 KMS 提供方工厂仅随 nextpdf/enterprise 包发行。NextPDF Pro 为签名策略提供 KMS 集成（AWS KMS、GCP Cloud KMS、Azure Key Vault），但不提供 Enterprise 的 KMS 提供方工厂或 GPU 嵌入旁车。内部旁车传输与内部嵌入管线类不属于公开接口范围，此处不予复现。

Pro 回退

NextPDF Pro 提供云 KMS 签名策略——由 KMS 保管签名密钥，Pro 把签名属性摘要发送给提供方。那是一种签名集成。它既不是 Enterprise 的集合级数据加密密钥提供方工厂，也不是 GPU 嵌入旁车。Pro 的加速接口请参见 Accelerator — NextPDF Pro。

Core 回退

NextPDF Core 没有 GPU 嵌入旁车，也没有 KMS 提供方工厂。嵌入与集合级密钥管理都是仅限 Enterprise 的功能。

Enterprise 边界说明

GPU 旁车传输、嵌入模型标识符，以及内部管线类，仅在行为层面进行描述。内部传输客户端、内部范围令牌，以及内部管线组合，不属于公开接口范围，此处不予复现。

部署边界

NextPDF Enterprise 与某个 KMS 集成，或从配置好的主密钥机密派生密钥。它本身并不存储该主密钥机密或云 KMS 密钥，也不保证其安全性。密钥安全取决于 KMS 或主密钥机密、取决于部署，并取决于操作方——而不仅仅取决于 NextPDF Enterprise。 操作方负责主密钥的预置、机密存储、KMS 配置，以及轮换排程。密钥保护责任遵循 NIST SP 800-57 Part 1 Rev.5 §5.5.2。NextPDF Enterprise 不会在本文档中暴露 KMS 凭据流程或主密钥处理的内部机制。

法务合规边界

本页涉及密钥管理。FIPS 模式声明是一项兼容性声明，既不是认证，也不是法律意见。请就你所负有的监管义务咨询你自己的合规与法务顾问。

发布边界

本页仅记录外部可观察的行为，以及受支持的公开 API 接口。内部命名空间路径、辅助类、机制表、运维手册文件名，以及工单前缀，均不在范围之内。

行为契约

• 提供方工厂根据配置选择提供方，并返回一个满足提供方契约的提供方。
• 提供方返回不可变的密钥元数据，绝不返回原始密钥字节。
• 一次轮换调用会推进密钥版本并返回新的元数据；由调用方重新加密集合数据。
• GPU 旁车在 CPU 回退时报告降级模式，并在其不可用时抛出一个有类型的异常。

另请参阅

• Accelerator 参考 — NextPDF Enterprise
• Security — NextPDF Enterprise
• Intelligence — NextPDF Enterprise
• Accelerator — NextPDF Pro
• KMS · DEK · HKDF — 术语表条目。