Accelerator — Referensi Mendalam (GPU sidecar, KMS provider factory)

Sekilas

Halaman ini adalah referensi mendalam untuk permukaan akselerasi publik dari NextPDF\Enterprise\Accelerator. Halaman ini mencakup tumpukan KMS provider — factory, kontrak provider, provider lokal, dan hasil metadata kunci — serta layanan GPU sidecar untuk embedding dan pencarian vektor. Halaman ini menyatakan parameter, default, mode kegagalan, dan sikap penjagaan kunci (key custody). Baca dulu halaman kapabilitas Accelerator untuk panduan alur kerja. Simbol lain dalam namespace yang sama termasuk kapabilitas lain dan berada di luar cakupan halaman ini.

Ketersediaan & lisensi

Kapabilitas ini hadir dalam NextPDF Enterprise (nextpdf/enterprise) dan aktif dengan envelope lisensi tingkat Enterprise. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

KMS provider dipilih saat runtime; kode pemanggil bergantung pada kontrak provider, bukan pada provider konkretnya. Layanan embedding dan indeks vektor mengimplementasikan kontrak Core EmbeddingServiceInterface dan VectorIndexInterface.

Permukaan Public API

composer require nextpdf/enterprise:^3

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
KmsProviderFactory::fromEnvironment	none	Membangun provider yang dinamai oleh variabel selector; unset atau kosong memilih local	KmsProviderInterface	RuntimeException saat root key hilang, cloud provider tidak tersedia, atau nama tidak dikenal	Titik masuk statis
KmsProviderFactory::create	string $providerType, array $config = []	Membangun provider bernama dari konfigurasi eksplisit	KmsProviderInterface	RuntimeException saat local tidak memiliki encryption_key yang tidak kosong, atau saat nama tidak dikenal	local adalah satu-satunya nama yang dapat dibangun dalam rilis ini
KmsProviderInterface::getEncryptionKey	string $collectionId	Mengembalikan metadata kunci saat ini untuk koleksi	EncryptionKeyResult	RuntimeException saat provider tidak dapat dijangkau atau salah konfigurasi (kontrak)	Hanya metadata; tidak pernah byte kunci mentah
KmsProviderInterface::rotateKey	string $collectionId	Menaikkan versi kunci	EncryptionKeyResult	RuntimeException saat rotasi gagal (kontrak)	Rotasi adalah sinyal enkripsi ulang kepada pemanggil
KmsProviderInterface::providerName	none	Melaporkan nama kanonik provider	string	Tidak ada yang dideklarasikan	local, aws, gcp, azure, vault
LocalKmsProvider::__construct	string $encryptionKey (sensitif)	Memvalidasi root key hex minimal 64 karakter hex (32 byte)	LocalKmsProvider	InvalidArgumentException pada nilai pendek atau non-hex	Penjaga fail-fast; tidak melakukan derivasi apa pun sendiri
LocalKmsProvider::getEncryptionKey	string $collectionId	Mencetak local:{collectionId}:v{version}; versi default 1	EncryptionKeyResult	Tidak ada yang dideklarasikan	Label algoritma AES-256-GCM
LocalKmsProvider::rotateKey	string $collectionId	Menaikkan penghitung versi in-process	EncryptionKeyResult	Tidak ada yang dideklarasikan	State versi bersifat per instance
EncryptionKeyResult::__construct	string $keyId, int $keyVersion, string $algorithm = 'AES-256-GCM', string $provider = 'local'	Value object metadata yang immutable	EncryptionKeyResult	Tidak ada yang dideklarasikan	Tidak pernah membawa material kunci
GpuEmbeddingService::embed	string $text	Mendelegasikan ke batchEmbed dan mengembalikan elemen nol	list<float>	Sebagaimana batchEmbed	Vektor 1024-dimensi
GpuEmbeddingService::batchEmbed	array $texts	Meng-embed batch pada sidecar	list<list<float>>	InvalidArgumentException pada batch kosong; SpectrumNotAvailableException saat sidecar tidak dapat dijangkau; SpectrumApiException pada respons yang gagal, malformed, atau jumlahnya tidak cocok	Tidak pernah mengembalikan hasil parsial
GpuEmbeddingService::getDimension	none	Mengembalikan 1024	int	Tidak ada yang dideklarasikan	Konstan
GpuEmbeddingService::getModelName	none	Mengembalikan multilingual-e5-large	string	Tidak ada yang dideklarasikan	Konstan
GpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Mengikat handle ke satu koleksi	GpuVectorIndex	Tidak ada yang dideklarasikan	Satu handle per pengenal koleksi
GpuVectorIndex::build	array $vectors, array $ids	Membangun indeks koleksi pada sidecar	void	InvalidArgumentException pada batch kosong atau ketidakcocokan panjang; SpectrumNotAvailableException saat tidak dapat dijangkau; SpectrumApiException pada respons build yang tak terduga	Rebuild menggantikan indeks
GpuVectorIndex::search	array $queryVector, int $topK = 10	Pencarian nearest-neighbor terperingkat	list<VectorSearchResult>	SpectrumNotAvailableException saat tidak dapat dijangkau; JsonException pada body respons yang malformed	Peringkat per hit dalam metadata hasil
GpuVectorIndex::delete	array $ids	Selalu menolak	void (dideklarasikan)	Selalu: SpectrumApiException (tidak diimplementasikan)	Indeks yang telah dibangun bersifat immutable; lakukan rebuild sebagai gantinya
GpuVectorIndex::count	none	Membaca total koleksi dari sidecar	int	Tidak melempar; kegagalan apa pun mengembalikan 0	0 bersifat ambigu: kosong atau tidak dapat dijangkau

Signature titik masuk

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
}

Permukaan konfigurasi

Setting	Consumer	Meaning
SPECTRUM_KMS_PROVIDER	fromEnvironment()	Selector provider. Unset atau kosong diselesaikan menjadi local.
SPECTRUM_ENCRYPTION_KEY	Jalur provider local	Root key ter-encode hex; minimal 64 karakter hex (32 byte). Dibagikan dengan sidecar.
encryption_key	create('local', [...])	Root key eksplisit; format dan validasi yang sama.

Kontrak perilaku

Pemilihan provider

KmsProviderFactory::fromEnvironment membaca variabel selector dan default ke local. Nama cloud provider aws, gcp, azure, dan vault dikenali tetapi tidak dapat dibangun dalam rilis ini. Memilih aws memunculkan error bertipe yang menyebutkan paket aws/aws-sdk-php yang diperlukan; tiga lainnya melaporkan integrasi sebagai belum diimplementasikan. Nama yang tidak dikenal memunculkan error bertipe yang mendaftar nama-nama yang didukung. KmsProviderFactory::create menerima nama provider eksplisit dan map konfigurasi; local adalah satu-satunya nama yang dibangunnya.

Metadata dan penjagaan kunci

Sebuah provider mengembalikan metadata kunci yang immutable: pengenal kunci, versi kunci yang naik monoton, label algoritma, dan nama provider. Provider tidak pernah mengembalikan byte kunci mentah, sehingga kebocoran metadata tidak mengekspos material kunci. Provider lokal membagi tugas dengan accelerator sidecar. Kelas PHP memvalidasi root secret saat konstruksi dan mencetak identitas kunci yang stabil dan ber-scope koleksi berbentuk local:{collectionId}:v{version}. Sidecar melakukan derivasi HKDF-SHA256 dan enkripsi AES-256-GCM, menurunkan data-encryption key 32-byte yang berbeda per koleksi dengan pengenal koleksi dan versi sebagai pemisah domain. Kedua sisi membaca root secret yang sama yang dikonfigurasi. Tidak ada layanan KMS eksternal yang dihubungi; penanganan kunci tetap di dalam deployment. Model versi dan siklus hidup kunci mengikuti NIST SP 800-57 Part 1 Rev.5 §4.

Panggilan rotasi menaikkan versi kunci dan mengembalikan metadata baru. Pemanggil meng-enkripsi ulang data koleksi dengan versi baru; provider tidak meng-enkripsi ulang apa pun sendiri.

Keamanan kunci bergantung pada KMS atau root-key secret, pada deployment, dan pada operator — bukan pada NextPDF Enterprise saja. Operator memiliki penyediaan root-key, penyimpanan secret, konfigurasi KMS, dan penjadwalan rotasi. Tanggung jawab perlindungan kunci mengikuti NIST SP 800-57 Part 1 Rev.5 §5.5.2.

Embedding GPU

GpuEmbeddingService mengimplementasikan kontrak embedding Core dan mendelegasikan ke sidecar. Sidecar menjalankan model embedding pada GPU bila tersedia dan jatuh ke CPU jika tidak, menandai metadata respons sebagai terdegradasi dari GPU. Bentuk vektor identik dalam kedua kasus. Model (sekitar 1,3 GB) diunduh dan dimuat secara lazy pada permintaan pertama. Semantik batch bersifat all-or-nothing: kegagalan per-item, vektor yang malformed, atau ketidakcocokan jumlah memunculkan error bertipe alih-alih mengembalikan hasil parsial.

Pencarian vektor GPU

GpuVectorIndex mengimplementasikan kontrak indeks vektor Core dan mengikat satu handle ke satu pengenal koleksi. build membangun indeks pada sidecar; sidecar menggunakan indeks GPU bila tersedia dan indeks CPU jika tidak. Indeks bersifat immutable setelah dibangun: delete selalu menolak dengan error bertipe not-implemented, dan penghapusan memerlukan rebuild. search mengembalikan hit terperingkat dengan peringkat berbasis-satu di metadata setiap hasil. count menanyakan total koleksi ke sidecar dan melaporkan 0 pada kegagalan apa pun alih-alih memunculkan error.

Kasus tepi & mode kegagalan

• Root key harus terdekode dari hex menjadi minimal 32 byte. Nilai yang lebih pendek atau non-hex memunculkan InvalidArgumentException saat konstruksi, sebelum panggilan sidecar apa pun.
• Variabel selector yang unset atau kosong diselesaikan menjadi local; factory tidak pernah menebak provider lain.
• fromEnvironment pada jalur local tanpa variabel root-key memunculkan error bertipe yang menyebutkan variabel yang hilang.
• create('local', [...]) tanpa entri encryption_key yang tidak kosong memunculkan error bertipe yang menyebutkan entri yang hilang.
• State versi kunci bersifat in-process dan per instance provider. Proses baru mengamati versi 1 hingga rotasi berjalan lagi. Persistenkan hasil rotasi dengan meng-enkripsi ulang data, bukan dengan mempercayai state provider.
• Batch embedding kosong memunculkan InvalidArgumentException; sidecar tidak dihubungi.
• Ketersediaan sidecar diperiksa per panggilan. Sidecar yang tidak dapat dijangkau memunculkan SpectrumNotAvailableException; layanan tidak pernah gagal secara diam-diam.
• Komponen non-numerik di dalam vektor embedding yang dikembalikan dikoersi menjadi 0.0; vektor yang hilang atau bukan array memunculkan SpectrumApiException.
• Permintaan embedding pertama membayar biaya unduh dan muat model satu kali; ukur timeout tersebut secara terpisah.
• build dan search mendekode respons sidecar secara ketat; body yang malformed memunculkan JsonException. count menelan setiap kegagalan dan mengembalikan 0.
• Hit pencarian yang kehilangan pengenal atau skornya default ke string kosong dan 0.0 alih-alih menggagalkan batch.
• Kode error sidecar dan hierarki exception dikatalogkan di referensi error Accelerator.

Perilaku mode FIPS

Jalur kunci lokal menggunakan HKDF-SHA256 untuk derivasi dan AES-256-GCM untuk enkripsi; sidecar menjalankan keduanya. Label algoritma yang direkam dalam metadata kunci adalah AES-256-GCM. Ketika deployment berjalan terhadap provider kriptografi yang tervalidasi FIPS, primitif tersebut berjalan dalam batas tervalidasi itu. Penggunaan AES-GCM memerlukan initialization vector yang unik per kunci, sesuai NIST SP 800-38D §5.

NextPDF Enterprise bukan modul kriptografi yang tervalidasi FIPS dan tidak membuat klaim sertifikasi FIPS. Ia beroperasi dalam mode kompatibel-FIPS hanya bila dikonfigurasi dengan provider kriptografi yang tervalidasi FIPS atau KMS yang tervalidasi FIPS. Tidak ada artefak sertifikasi FIPS dalam repositori ini.

Konformansi

Claim	Standard	Clause
Model versi dan siklus hidup kunci mengikuti panduan key-state.	NIST SP 800-57 Part 1 Rev.5	§4
Tanggung jawab perlindungan dan penjagaan kunci berada pada pemilik kunci dan operator.	NIST SP 800-57 Part 1 Rev.5	§5.5.2
AES-GCM memerlukan initialization vector yang unik per kunci.	NIST SP 800-38D	§5

Semua klausa diparafrasekan; NextPDF tidak mereproduksi teks normatif. NextPDF tidak membuat klaim sertifikasi. Keselarasan dengan klausa yang dikutip adalah pernyataan kapabilitas, bukan sertifikasi. Halaman ini berkenaan dengan manajemen kunci; pernyataan mode FIPS adalah pernyataan kompatibilitas, bukan opini hukum. Konsultasikan penasihat kepatuhan dan hukum Anda sendiri.

Catatan pengembangan

• Sumber modul membawa @since 2.1.0; referensi ini mendokumentasikan permukaan sebagaimana dikirim dalam nextpdf/enterprise 3.1.0.
• Semua kelas bersifat final; EncryptionKeyResult bersifat final readonly. Bangun instance baru alih-alih memutasi.
• Root key adalah parameter konstruktor yang sensitif (#[SensitiveParameter]); PHP menyunting (redact) nilainya dari stack trace. Jauhkan dari log aplikasi dan dump konfigurasi.
• SpectrumClient, VectorSearchResult, serta kontrak EmbeddingServiceInterface dan VectorIndexInterface berasal dari NextPDF Core; pemanggil membangun dan menyediakan klien sidecar.
• Namespace NextPDF\Enterprise\Accelerator juga membawa mesin batch offload serta tumpukan retrieval-collection dan ekstraksi OCR; permukaan tersebut berada di luar cakupan halaman ini.
• Detail mekanisme internal tetap di dokumentasi internal repositori sumber dan berada di luar cakupan manual ini.

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang dapat diamati secara eksternal dan permukaan Public API yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama file runbook, dan prefix tiket berada di luar cakupan.

Lihat juga

• Accelerator — GPU sidecar dan KMS provider factory — halaman kapabilitas untuk panduan alur kerja dan penjagaan kunci.
• Referensi error Accelerator — hierarki exception sidecar dan kode error.
• Security — Referensi Mendalam
• Accelerator — Referensi Mendalam NextPDF Pro