Accelerator — 深入參考（GPU sidecar、KMS provider factory）

速覽

本頁是 NextPDF\Enterprise\Accelerator 公開加速介面的深入參考。它涵蓋 KMS provider 堆疊——factory、provider 合約、本機 provider，以及金鑰中繼資料 result——以及用於 embedding 與向量搜尋的 GPU sidecar 服務。它陳述參數、預設值、失敗模式，以及金鑰保管立場。請先閱讀 Accelerator 能力頁面 以取得工作流程指引。同一命名空間中的其他符號屬於其他能力，不在本頁範圍內。

可用性與授權

此能力隨 NextPDF Enterprise（nextpdf/enterprise）出貨，並以 Enterprise 層級的授權封套啟用。未持有該授權的部署不會載入此能力的類別。比較版本並取得授權。

KMS provider 在執行階段選定；呼叫端程式碼依賴的是 provider 合約，而非具體的 provider。embedding 與 vector-index 服務實作了 Core 的 EmbeddingServiceInterface 與 VectorIndexInterface 合約。

公開 API 介面

composer require nextpdf/enterprise:^3

符號	參數	預設行為	回傳	拋出或失敗於	備註
KmsProviderFactory::fromEnvironment	無	建構由選擇器變數指名的 provider；未設定或空值時選定 local	KmsProviderInterface	主金鑰缺失、雲端 provider 不可用，或名稱未知時拋出 RuntimeException	靜態進入點
KmsProviderFactory::create	string $providerType、array $config = []	從明確設定建構指名的 provider	KmsProviderInterface	當 local 缺少非空的 encryption_key，或名稱未知時拋出 RuntimeException	local 是此版本中唯一可建構的名稱
KmsProviderInterface::getEncryptionKey	string $collectionId	回傳該集合當前的金鑰中繼資料	EncryptionKeyResult	當 provider 不可連線或設定錯誤時拋出 RuntimeException（合約）	僅中繼資料；絕不含原始金鑰位元組
KmsProviderInterface::rotateKey	string $collectionId	推進金鑰版本	EncryptionKeyResult	當輪替失敗時拋出 RuntimeException（合約）	輪替是給呼叫端的重新加密訊號
KmsProviderInterface::providerName	無	回報標準的 provider 名稱	string	未宣告任何拋出	local、aws、gcp、azure、vault
LocalKmsProvider::__construct	string $encryptionKey（敏感）	驗證一把至少 64 個十六進位字元（32 bytes）的十六進位主金鑰	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 上為整批進行 embedding	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()	provider 選擇器。未設定或空值時解析為 local。
SPECTRUM_ENCRYPTION_KEY	local provider 路徑	十六進位編碼的主金鑰；至少 64 個十六進位字元（32 bytes）。與 sidecar 共用。
encryption_key	create('local', [...])	明確的主金鑰；相同格式與驗證。

行為合約

provider 選定

KmsProviderFactory::fromEnvironment 會讀取選擇器變數並預設為 local。雲端 provider 名稱 aws、gcp、azure 與 vault 會被辨識，但在此版本中無法建構。選定 aws 會引發一個具型別的錯誤，並指名所需的 aws/aws-sdk-php 套件；其餘三者會回報整合尚未實作。未知的名稱會引發一個具型別的錯誤，並列出受支援的名稱。KmsProviderFactory::create 接受一個明確的 provider 名稱與一個設定映射；local 是它唯一會建構的名稱。

金鑰中繼資料與保管

provider 會回傳不可變的金鑰中繼資料：一個金鑰識別碼、一個單調遞增的金鑰版本、演算法標籤，以及 provider 名稱。它絕不回傳原始金鑰位元組，因此中繼資料外洩不會暴露金鑰材料。本機 provider 會與 accelerator sidecar 分工。PHP 類別會在建構時驗證主秘密，並產生一個穩定、集合範圍的金鑰身分，其形式為 local:{collectionId}:v{version}。sidecar 會執行 HKDF-SHA256 衍生與 AES-256-GCM 加密，並以集合識別碼與版本作為網域分隔，為每個集合衍生出一把獨立的 32 bytes 資料加密金鑰。兩端讀取的是同一把設定好的主秘密。不聯絡任何外部 KMS 服務；金鑰處理保持在部署內部。金鑰版本與生命週期模型遵循 NIST SP 800-57 Part 1 Rev.5 §4。

一次輪替呼叫會推進金鑰版本並回傳新的中繼資料。呼叫端會以新版本重新加密集合資料；provider 本身不重新加密任何東西。

**金鑰安全性取決於 KMS 或主金鑰秘密、取決於部署，以及取決於運維人員——而非單靠 NextPDF Enterprise。**運維人員擁有主金鑰佈建、秘密儲存、KMS 設定，以及輪替排程。金鑰保護責任遵循 NIST SP 800-57 Part 1 Rev.5 §5.5.2。

GPU 嵌入

GpuEmbeddingService 實作了 Core embedding 合約並委派給 sidecar。sidecar 會在有 GPU 可用時於 GPU 上執行 embedding 模型，否則回退到 CPU，並將回應中繼資料標記為自 GPU 降級。兩種情況下向量形狀相同。模型（約 1.3 GB）會在第一個請求時延遲下載並載入。批次語意為全有或全無：單一項目失敗、向量格式錯誤或數量不符，都會引發一個具型別的錯誤，而非回傳部分結果。

GPU 向量搜尋

GpuVectorIndex 實作了 Core vector-index 合約，並將單一把手繫結至單一集合識別碼。build 會在 sidecar 上建構索引；sidecar 會在有 GPU 可用時使用 GPU 索引，否則使用 CPU 索引。索引一旦建構即不可變：delete 一律以一個具型別的未實作錯誤拒絕，移除需要重新建構。search 會回傳依排名的命中，每筆結果的中繼資料中帶有以 1 為起始的排名。count 會向 sidecar 詢問集合總數，並在任何失敗時回報 0 而非引發例外。

邊界案例與失敗模式

• 主金鑰必須能從十六進位解碼為至少 32 bytes。較短或非十六進位的值會在建構時、任何 sidecar 呼叫之前引發 InvalidArgumentException。
• 未設定或空值的選擇器變數會解析為 local；factory 絕不猜測其他 provider。
• 在 local 路徑上呼叫 fromEnvironment 卻缺少主金鑰變數時，會引發一個具型別的錯誤，並指名缺少的變數。
• create('local', [...]) 缺少非空的 encryption_key 項目時，會引發一個具型別的錯誤，並指名缺少的項目。
• 金鑰版本狀態是行程內且以每個 provider 實例為單位的。新的行程在再次執行輪替之前會看到版本 1。請以重新加密資料的方式保存輪替結果，而非仰賴 provider 狀態。
• 空的 embedding 批次會引發 InvalidArgumentException；不會聯絡 sidecar。
• sidecar 的可用性會在每次呼叫時探測。不可連線的 sidecar 會引發 SpectrumNotAvailableException；這些服務絕不默默失敗。
• 回傳的 embedding 向量中若有非數值的分量，會被強制轉為 0.0；缺失或非陣列的向量會引發 SpectrumApiException。
• 第一個 embedding 請求會付出一次性的模型下載與載入成本；請為該逾時另行估算。
• 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 provider factory — 提供工作流程與保管指引的能力頁面。
• Accelerator 錯誤參考 — sidecar 例外階層與錯誤碼。
• Security — 深入參考
• Accelerator — NextPDF Pro 深入參考