Enterprise エディション

Accelerator — 詳細リファレンス（GPU サイドカー、KMS プロバイダーファクトリー）

概要

このページは、NextPDF\Enterprise\Accelerator のパブリックなアクセラレーションサーフェスの詳細リファレンスです。KMS プロバイダースタック（ファクトリー、プロバイダーコントラクト、ローカルプロバイダー、鍵メタデータの結果）と、埋め込みおよびベクトル検索のための GPU サイドカーサービスを扱います。パラメーター、デフォルト、失敗モード、鍵の保管方針を記載します。ワークフローのガイダンスについては、まず 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 桁の 16 進文字（32 バイト）の 16 進マスターキーを検証	`LocalKmsProvider`	短いまたは 16 進でない値で `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` に委譲し、要素 0 を返す	`list<float>`	`batchEmbed` に準じる	1024 次元ベクトル
`GpuEmbeddingService::batchEmbed`	`array $texts`	バッチをサイドカーで埋め込む	`list<list<float>>`	空のバッチで `InvalidArgumentException`。サイドカーに到達不能な場合 `SpectrumNotAvailableException`。失敗・不正形式・件数不一致の応答で `SpectrumApiException`	部分的な結果は返さない
`GpuEmbeddingService::getDimension`	なし	`1024` を返す	`int`	宣言なし	定数
`GpuEmbeddingService::getModelName`	なし	`multilingual-e5-large` を返す	`string`	宣言なし	定数
`GpuVectorIndex::__construct`	`SpectrumClient $client`、`string $collectionId = 'default'`	ハンドルを 1 つのコレクションにバインド	`GpuVectorIndex`	宣言なし	コレクション識別子ごとに 1 つのハンドル
`GpuVectorIndex::build`	`array $vectors`、`array $ids`	コレクションインデックスをサイドカーで構築	`void`	空のバッチまたは長さの不一致で `InvalidArgumentException`。到達不能な場合 `SpectrumNotAvailableException`。想定外の構築応答で `SpectrumApiException`	再構築はインデックスを置き換える
`GpuVectorIndex::search`	`array $queryVector`、`int $topK = 10`	ランク付き最近傍検索	`list<VectorSearchResult>`	到達不能な場合 `SpectrumNotAvailableException`。不正形式の応答本文で `JsonException`	ヒットごとのランクは結果メタデータ内
`GpuVectorIndex::delete`	`array $ids`	常に拒否	`void`（宣言上）	常に `SpectrumApiException`（未実装）	構築済みインデックスは不変。代わりに再構築
`GpuVectorIndex::count`	なし	コレクションの総数をサイドカーから読み取る	`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` プロバイダーパス	16 進エンコードされたマスターキー。少なくとも 64 桁の 16 進文字（32 バイト）。サイドカーと共有。
`encryption_key`	`create('local', [...])`	明示的なマスターキー。同じ形式と検証。

挙動コントラクト

プロバイダーの選択

KmsProviderFactory::fromEnvironment はセレクター変数を読み取り、デフォルトは local です。クラウドプロバイダー名 aws、gcp、azure、vault は認識されますが、このリリースでは構築できません。aws を選択すると、必要な aws/aws-sdk-php パッケージを名指しする型付きエラーが発生します。他の 3 つは統合が未実装であると報告します。不明な名前は、サポートされる名前を列挙する型付きエラーを発生させます。KmsProviderFactory::create は明示的なプロバイダー名と構成マップを受け取ります。構築する名前は local のみです。

鍵メタデータと保管

プロバイダーは不変の鍵メタデータ（鍵識別子、単調増加する鍵バージョン、アルゴリズム名、プロバイダー名）を返します。生の鍵バイトを返すことは決してないため、メタデータの漏洩によって鍵素材が露出することはありません。ローカルプロバイダーは、アクセラレーターサイドカーと役割を分担します。PHP クラスは構築時にマスターシークレットを検証し、local:{collectionId}:v{version} という形式の安定したコレクションスコープの鍵アイデンティティを生成します。サイドカーは 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 の埋め込みコントラクトを実装し、サイドカーに委譲します。サイドカーは、GPU が利用可能な場合は GPU 上で埋め込みモデルを実行し、そうでない場合は CPU にフォールバックして、応答メタデータを GPU からの劣化として印付けします。ベクトルの形状は両方の場合で同一です。モデル（約 1.3 GB）は、最初のリクエスト時に遅延ダウンロードおよびロードされます。バッチのセマンティクスはオールオアナッシングです。項目ごとの失敗、不正形式のベクトル、件数の不一致は、部分的な結果を返すのではなく、型付きエラーを発生させます。

GPU ベクトル検索

GpuVectorIndex は Core のベクトルインデックスコントラクトを実装し、1 つのハンドルを 1 つのコレクション識別子にバインドします。build はサイドカー上にインデックスを構築します。サイドカーは、GPU が利用可能な場合は GPU インデックスを使用し、そうでない場合は CPU インデックスを使用します。インデックスは一度構築されると不変です。delete は常に型付きの未実装エラーで拒否し、削除には再構築が必要です。search は、各結果のメタデータに 1 始まりのランクを付けたランク付きヒットを返します。count はサイドカーにコレクションの総数を問い合わせ、失敗時には例外を発生させるのではなく 0 を報告します。

エッジケースと失敗モード

マスターキーは 16 進から少なくとも 32 バイトにデコードできなければなりません。より短いまたは 16 進でない値は、いずれのサイドカー呼び出しよりも前に、構築時に InvalidArgumentException を発生させます。
未設定または空のセレクター変数は local に解決されます。ファクトリーが他のプロバイダーを推測することはありません。
マスターキー変数がないまま local パスで fromEnvironment を呼び出すと、欠落している変数を名指しする型付きエラーが発生します。
空でない encryption_key エントリーがないまま create('local', [...]) を呼び出すと、欠落しているエントリーを名指しする型付きエラーが発生します。
鍵バージョンの状態はインプロセスであり、プロバイダーインスタンスごとです。新しいプロセスは、ローテーションが再度実行されるまでバージョン 1 を観測します。ローテーションの結果は、プロバイダーの状態を信頼するのではなく、データを再暗号化して永続化してください。
空の埋め込みバッチは InvalidArgumentException を発生させます。サイドカーには接続されません。
サイドカーの可用性は呼び出しごとにプローブされます。到達不能なサイドカーは SpectrumNotAvailableException を発生させます。サービスが黙って失敗することはありません。
返された埋め込みベクトル内の非数値の成分は 0.0 に強制変換されます。欠落しているまたは配列でないベクトルは SpectrumApiException を発生させます。
最初の埋め込みリクエストは、一度限りのモデルダウンロードおよびロードのコストを負担します。そのタイムアウトは別途見積もってください。
build と search はサイドカーの応答を厳格にデコードします。不正形式の本文は JsonException を発生させます。count はあらゆる失敗を飲み込み、0 を返します。
識別子またはスコアを欠く検索ヒットは、バッチを失敗させるのではなく、空文字列と 0.0 にデフォルトします。
サイドカーのエラーコードと例外階層は、Accelerator エラーリファレンスにカタログ化されています。

FIPS モードの挙動

ローカル鍵パスは、導出に HKDF-SHA256、暗号化に AES-256-GCM を使用します。サイドカーが両方を実行します。鍵メタデータに記録されるアルゴリズム名は 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 から提供されます。呼び出し元がサイドカークライアントを構築して提供します。
NextPDF\Enterprise\Accelerator 名前空間には、バッチオフロードエンジンや、検索コレクションおよび OCR 抽出スタックも含まれますが、それらのサーフェスはこのページの対象外です。
内部メカニズムの詳細はソースリポジトリの内部ドキュメントにとどまり、このマニュアルの対象外です。

公開境界

このページは、外部から観測可能な挙動と、サポートされるパブリック API サーフェスのみを文書化します。内部の名前空間パス、ヘルパークラス、メカニズムテーブル、ランブックのファイル名、チケットプレフィックスは対象外です。