Enterprise 版本

Accelerator — GPU sidecar 與 KMS 提供者工廠

速覽

NextPDF Enterprise 新增兩項加速功能：用於文字嵌入、並具備 CPU 回退的 GPU sidecar，以及提供集合層級資料加密金鑰中繼資料與輪替的 KMS 提供者工廠。本頁說明行為、邊界，以及金鑰保管立場。

可用性與授權

此功能隨附於 NextPDF Enterprise（nextpdf/enterprise），並在具備 Enterprise 層級授權封套時啟用。缺少該授權權益的部署不會載入此功能的類別。比較各版本並取得授權。

概念總覽

GPU sidecar 會加速文字轉向量的嵌入運算。Enterprise 套件會透過本機 HTTP 請求，將文字送往一個獨立的 sidecar 程序。當有可用的 GPU 時，sidecar 會在 GPU 上執行嵌入模型。當沒有可用的 GPU 時，sidecar 會在 CPU 上執行同一個模型，並回報自己以降級模式執行。兩種情況下產生的向量形狀都相同。嵌入模型在第一次請求時載入，因此第一次請求會比後續請求慢。sidecar 是選用的；系統會公開一個可用性檢查，而缺少 sidecar 時會引發一個具型別的例外，而非默默失敗。

KMS 提供者工廠會依設定選定一個金鑰管理提供者。工廠會讀取一個環境變數來選擇提供者。預設提供者會在本機，以 HKDF-SHA256 從一把設定好的主金鑰，並以集合識別碼作為網域分隔符，推導出該集合專屬的資料加密金鑰。本機提供者不聯絡任何外部服務；該推導是確定性的，且在行程內完成。工廠也接受一種供本機提供者使用的明確設定形式。雲端提供者——AWS KMS、GCP Cloud KMS、Azure Key Vault 與 HashiCorp Vault Transit——是已辨識的提供者名稱；選用其中之一卻未安裝對應整合時，會引發一個具型別的設定錯誤，並指名缺少的相依套件。

提供者回傳的是金鑰中繼資料，而非原始金鑰位元組。中繼資料會記錄金鑰識別碼、一個單調遞增的金鑰版本、加密演算法名稱，以及提供者名稱。一次輪替呼叫會推進金鑰版本並回傳新的中繼資料。輪替後，由呼叫端負責以新的金鑰版本重新加密集合資料。金鑰版本與輪替生命週期遵循 NIST SP 800-57 Part 1 Rev.5 §4。

為何如此設計

嵌入運算是在一個獨立的 GPU sidecar 程序中執行，而非在 PHP 請求內部。GPU 模型載入的成本高昂，因此 sidecar 只載入模型一次，並將該成本分攤到眾多請求上。當沒有 GPU 時，sidecar 會在 CPU 上執行同一個模型，並回報降級模式。吞吐量可能下降，但正確性不會：兩種方式下的向量形狀都完全相同。sidecar 維持選用；一個可用性檢查，以及缺少 sidecar 時的具型別例外，讓加速成為刻意的選擇性啟用，而非隱藏的相依。那樣的分離讓高流量的嵌入運算得以在專用硬體上擴充，同時讓文件管線維持為一個單純的 PHP 呼叫。

設計背景：高流量文件產生。

API 介面

公開介面	型別	用途	穩定度	自
KMS provider factory	class	從環境或明確設定建構一個 KMS 提供者	stable	2.1.0
KMS provider	interface	取得金鑰中繼資料、輪替金鑰，並回報提供者名稱	stable	2.1.0
Local KMS provider	class（實作提供者介面）	本機 HKDF-SHA256 金鑰推導；不聯絡任何外部服務	stable	2.1.0
Encryption-key result	value object	不可變的金鑰中繼資料：金鑰 id、版本、演算法、提供者——不含原始金鑰位元組	stable	2.1.0
GPU embedding service	class（實作 Core 嵌入服務介面）	在 GPU sidecar 上嵌入文字，並具備 CPU 回退	stable	2.1.0

提供者工廠公開一個「from environment」進入點與一個明確的「create」進入點。主金鑰設定值在本機提供者中標記為敏感。具權威性的參數與型別合約是 nextpdf/enterprise 套件的已發布 API 參考；請以該參考——而非本頁——作為合約。

程式碼範例——快速上手

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.

程式碼範例——正式環境

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 sidecar 在回退到 CPU 時會回報降級模式。若你的吞吐量取決於 GPU，請檢查該欄位。
嵌入模型在第一次請求時載入；請據此設定第一次請求的逾時值。

效能

本機金鑰推導是一次成本固定的 HKDF 運算。它不聯絡任何外部服務。一次 GPU 嵌入請求會額外增加一次往返 sidecar 的本機來回，加上模型推論時間。第一次請求還會付出一次性的模型載入成本。CPU 回退結果正確，但對同一批次而言比 GPU 路徑慢。

安全注意事項

KMS 提供者回傳的是金鑰中繼資料，而非原始金鑰位元組。encryption-key result 這個 value object 永不承載金鑰素材。
本機提供者的主金鑰是一個敏感的建構子參數。它不會被記錄，也不會被序列化。
本機提供者不聯絡任何外部服務。推導是確定性的，且在行程內完成。
使用 AES-GCM 時，每把金鑰都需要一個唯一的初始向量，依 NIST SP 800-38D §5。

資料落地與 PII 緩解措施

本機 KMS 提供者在行程內執行，且不聯絡任何外部服務；本機金鑰推導不會讓任何金鑰素材或任何文件內容離開主機。GPU sidecar 透過一次本機請求接收要嵌入的文字；它不會接收無關的文件內容。當設定使用雲端 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 嵌入 sidecar 與 KMS 提供者工廠僅隨附於 nextpdf/enterprise 套件。NextPDF Pro 為簽署策略提供 KMS 整合（AWS KMS、GCP Cloud KMS、Azure Key Vault），但不提供 Enterprise KMS 提供者工廠或 GPU 嵌入 sidecar。內部 sidecar 傳輸與內部嵌入管線類別不在公開介面範圍內，此處不予重現。

Pro 回退

NextPDF Pro 提供雲端 KMS 簽署策略——KMS 保管簽署金鑰，而 Pro 將已簽署屬性的摘要送往提供者。那是一種簽署整合。它不是 Enterprise 的集合層級資料加密金鑰提供者工廠，也不是 GPU 嵌入 sidecar。Pro 的加速介面請參閱 Accelerator — NextPDF Pro。

Core 回退

NextPDF Core 沒有 GPU 嵌入 sidecar，也沒有 KMS 提供者工廠。嵌入運算與集合層級金鑰管理是 Enterprise 專屬功能。

Enterprise 邊界註記

GPU sidecar 傳輸、嵌入模型識別碼，以及內部管線類別僅以行為層級描述。內部傳輸用戶端、內部範圍符記，以及內部管線組合不在公開介面範圍內，此處不予重現。

部署邊界

NextPDF Enterprise 會整合 KMS，或從一把設定好的主金鑰機密推導金鑰。它本身不會儲存或保證該主金鑰機密或雲端 KMS 金鑰的安全。金鑰安全取決於 KMS 或主金鑰機密、部署環境，以及操作者——而非單靠 NextPDF Enterprise。 操作者負責主金鑰供裝、機密儲存、KMS 設定，以及輪替排程。金鑰保護責任遵循 NIST SP 800-57 Part 1 Rev.5 §5.5.2。NextPDF Enterprise 不在本文件中公開 KMS 憑證流程或主金鑰處理的內部實作。

法律合規邊界

本頁涉及金鑰管理。FIPS 模式陳述是一項相容性陳述，並非認證，也不是法律意見。關於你的法規義務，請諮詢你自己的合規與法律顧問。

發布邊界

本頁僅記載外部可觀察的行為，以及受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表格、runbook 檔名，以及工單前綴，皆不在範圍內。

行為合約

提供者工廠會依設定選定提供者，並回傳一個滿足提供者合約的提供者。
提供者回傳不可變的金鑰中繼資料，且永不回傳原始金鑰位元組。
一次輪替呼叫會推進金鑰版本並回傳新的中繼資料；由呼叫端重新加密集合資料。
GPU sidecar 在回退到 CPU 時會回報降級模式，並在不可用時引發一個具型別的例外。

另請參閱

Accelerator reference — NextPDF Enterprise
Security — NextPDF Enterprise
Intelligence — NextPDF Enterprise
Accelerator — NextPDF Pro
KMS · DEK · HKDF — 詞彙表條目。