Accelerator — sidecar GPU dan factory penyedia KMS

Sekilas pandang

NextPDF Enterprise menambahkan dua fitur akselerasi: sidecar GPU untuk embedding teks dengan fallback CPU, dan pabrik penyedia KMS yang menyediakan metadata dan rotasi kunci enkripsi data tingkat koleksi. Halaman ini menyatakan perilaku, batasan, dan posisi kustodi kunci.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Enterprise (nextpdf/enterprise) dan diaktifkan dengan envelope lisensi tingkat Enterprise. Sebuah penerapan tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tinjauan konseptual

Sidecar GPU mempercepat embedding teks ke vektor. Paket Enterprise mengirimkan teks ke proses sidecar terpisah melalui permintaan HTTP lokal. Sidecar menjalankan model embedding pada GPU ketika tersedia. Ketika GPU tidak tersedia, sidecar menjalankan model yang sama pada CPU dan melaporkan bahwa ia berjalan dalam mode terdegradasi. Hasilnya berupa bentuk vektor yang sama pada kedua kasus. Model embedding dimuat pada permintaan pertama, sehingga permintaan pertama lebih lambat daripada permintaan berikutnya. Sidecar bersifat opsional; sebuah pemeriksaan ketersediaan dipaparkan, dan sidecar yang hilang memunculkan eksepsi bertipe alih-alih kegagalan diam-diam.

Pabrik penyedia KMS memilih penyedia manajemen kunci dari konfigurasi. Pabrik membaca variabel lingkungan untuk memilih penyedianya. Penyedia baku menurunkan kunci enkripsi data spesifik-koleksi secara lokal menggunakan HKDF-SHA256 dari kunci root yang dikonfigurasi, dengan pengenal koleksi sebagai pemisah domain. Penyedia lokal tidak menghubungi layanan eksternal mana pun; penurunannya bersifat deterministik dan di dalam proses. Pabrik juga menerima bentuk konfigurasi eksplisit untuk penyedia lokal. Penyedia cloud — AWS KMS, GCP Cloud KMS, Azure Key Vault, dan HashiCorp Vault Transit — adalah nama penyedia yang dikenali; memilih salah satunya tanpa integrasi terkait yang terpasang memunculkan galat konfigurasi bertipe yang menyebutkan dependensi yang hilang.

Sebuah penyedia mengembalikan metadata kunci, bukan byte kunci mentah. Metadata mencatat pengenal kunci, versi kunci yang naik secara monoton, nama algoritma enkripsi, dan nama penyedia. Sebuah panggilan rotasi menaikkan versi kunci dan mengembalikan metadata baru. Pemanggil bertanggung jawab untuk mengenkripsi ulang data koleksi dengan versi kunci baru setelah rotasi. Versi kunci dan siklus hidup rotasi mengikuti NIST SP 800-57 Part 1 Rev.5 §4.

Mengapa cara kerjanya begini

Embedding berjalan dalam proses sidecar GPU terpisah alih-alih di dalam permintaan PHP. Pemuatan model GPU mahal, sehingga sidecar memuat model sekali dan mengamortisasi biaya tersebut di banyak permintaan. Ketika tidak ada GPU, sidecar menjalankan model yang sama pada CPU dan melaporkan mode terdegradasi. Throughput dapat menurun, tetapi kebenaran tidak: bentuk vektor identik pada kedua kasus. Sidecar tetap opsional; sebuah pemeriksaan ketersediaan dan eksepsi bertipe pada sidecar yang hilang menjaga akselerasi tetap sebagai opt-in yang disengaja, bukan dependensi tersembunyi. Pemisahan tersebut memungkinkan embedding bervolume tinggi diskalakan pada perangkat keras khusus sementara pipeline dokumen tetap berupa panggilan PHP biasa.

Latar belakang desain: Pembuatan dokumen bervolume tinggi.

Permukaan API

Permukaan publik	Tipe	Tujuan	Stabilitas	Sejak
Pabrik penyedia KMS	class	Membangun penyedia KMS dari lingkungan atau konfigurasi eksplisit	stable	2.1.0
Penyedia KMS	interface	Memperoleh metadata kunci, merotasi kunci, dan melaporkan nama penyedia	stable	2.1.0
Penyedia KMS lokal	class (mengimplementasikan antarmuka penyedia)	Penurunan kunci HKDF-SHA256 lokal; tidak menghubungi layanan eksternal	stable	2.1.0
Hasil kunci enkripsi	value object	Metadata kunci imutabel: id kunci, versi, algoritma, penyedia — tanpa byte kunci mentah	stable	2.1.0
Layanan embedding GPU	class (mengimplementasikan antarmuka layanan-embedding Core)	Melakukan embedding teks pada sidecar GPU dengan fallback CPU	stable	2.1.0

Pabrik penyedia memaparkan titik masuk “from environment” dan titik masuk “create” eksplisit. Nilai konfigurasi kunci root ditandai sensitif di penyedia lokal. Kontrak parameter dan tipe yang otoritatif adalah referensi API terbitan untuk paket nextpdf/enterprise; perlakukan referensi tersebut — bukan halaman ini — sebagai kontrak.

Contoh kode — Mulai cepat

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.

Contoh kode — Produksi

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.

Nama variabel lingkungan, kunci konfigurasi eksplisit, dan tipe eksepsi didokumentasikan dalam referensi mendalam Accelerator.

Kasus tepi & jebakan

• Penyedia KMS lokal memerlukan kunci root ter-encode-hex sepanjang minimal 32 byte. Nilai yang lebih pendek atau non-hex memunculkan eksepsi argumen bertipe saat konstruksi.
• Memilih nama penyedia cloud tanpa integrasi terkait yang terpasang memunculkan galat konfigurasi bertipe yang menyebutkan dependensi yang hilang.
• Nama penyedia yang tidak dikenal memunculkan galat bertipe yang mencantumkan nama-nama yang didukung.
• Sidecar GPU melaporkan mode terdegradasi ketika ia jatuh ke CPU. Periksa bidang tersebut jika Anda bergantung pada throughput GPU.
• Model embedding dimuat pada permintaan pertama; sesuaikan batas waktu permintaan-pertama dengan tepat.

Kinerja

Penurunan kunci lokal adalah operasi HKDF berbiaya konstan. Operasi ini tidak menghubungi layanan eksternal mana pun. Sebuah permintaan embedding GPU menambahkan satu putaran lokal ke sidecar ditambah waktu inferensi model. Permintaan pertama juga membayar biaya pemuatan-model satu kali. Fallback CPU benar tetapi lebih lambat daripada jalur GPU untuk batch yang sama.

Catatan keamanan

• Penyedia KMS mengembalikan metadata kunci, bukan byte kunci mentah. Value object hasil kunci enkripsi tidak pernah membawa material kunci.
• Kunci root penyedia lokal adalah parameter konstruktor yang sensitif. Kunci ini tidak dicatat dan tidak diserialkan.
• Penyedia lokal tidak menghubungi layanan eksternal mana pun. Penurunan bersifat deterministik dan di dalam proses.
• Penggunaan AES-GCM memerlukan initialization vector yang unik per kunci, sesuai NIST SP 800-38D §5.

Residensi Data & Mitigasi PII

Penyedia KMS lokal berjalan di dalam proses dan tidak menghubungi layanan eksternal mana pun; tidak ada material kunci dan tidak ada konten dokumen yang meninggalkan host untuk penurunan kunci lokal. Sidecar GPU menerima teks untuk di-embed melalui permintaan lokal; ia tidak menerima konten dokumen yang tidak terkait. Penyedia KMS cloud, ketika dikonfigurasi, menghubungi penyedia cloud yang Anda pilih; tinjau posisi residensi data penyedia tersebut untuk yurisdiksi Anda.

Telemetri Aman & Pembersihan Log

Kunci root penyedia lokal adalah parameter konstruktor yang sensitif dan dikecualikan dari log serta serialisasi. Jangan menambahkan kunci root, kunci turunan, atau kredensial penyedia ke log aplikasi Anda sendiri. Perlakukan semua material kunci sebagai rahasia dalam kebijakan pencatatan dan penjejakan Anda.

Model ancaman

Penyedia mengembalikan metadata, bukan byte kunci, sehingga kebocoran metadata tidak mengekspos material kunci. Keamanan penyedia lokal bergantung pada kerahasiaan kunci root yang dikonfigurasi. Keamanan penyedia cloud bergantung pada penyedia tersebut dan konfigurasi Anda. Perlindungan kunci bergantung pada KMS atau rahasia kunci-root, penerapan, dan operator — bukan pada perangkat lunak ini saja. Lihat batas penerapan.

Kesesuaian

• Versi dan siklus hidup rotasi kunci enkripsi data selaras dengan NIST SP 800-57 Part 1 Rev.5 §4.
• Tanggung jawab perlindungan kunci selaras dengan NIST SP 800-57 Part 1 Rev.5 §5.5.2.
• Keunikan initialization vector AES-GCM selaras dengan NIST SP 800-38D §5.

Setiap sumber normatif diparafrasakan. Tidak ada teks normatif yang direproduksi pada halaman ini. Halaman ini berkaitan dengan manajemen kunci.

Perilaku mode-FIPS

Penurunan HKDF penyedia lokal menggunakan SHA-256. Algoritma enkripsi yang dicatat dalam metadata kunci adalah AES-256-GCM. Ketika aplikasi berjalan terhadap penyedia kriptografi tervalidasi FIPS, primitif tersebut berjalan dalam batas tervalidasi itu. Pabrik penyedia itu sendiri memilih dan membangun penyedia; ia tidak mensertifikasi batas kriptografi.

NextPDF Enterprise bukan modul kriptografi tervalidasi FIPS dan tidak membuat klaim sertifikasi FIPS apa pun. NextPDF Enterprise beroperasi dalam mode yang kompatibel dengan FIPS hanya ketika dikonfigurasi dengan penyedia kriptografi tervalidasi FIPS atau KMS tervalidasi FIPS.

Batas edisi

Sidecar embedding GPU dan pabrik penyedia KMS disertakan hanya dalam paket nextpdf/enterprise. NextPDF Pro menyediakan integrasi KMS untuk strategi penandatanganan (AWS KMS, GCP Cloud KMS, Azure Key Vault) tetapi tidak menyediakan pabrik penyedia KMS Enterprise atau sidecar embedding GPU. Transport sidecar internal dan kelas pipeline-embedding internal berada di luar cakupan permukaan publik dan tidak direproduksi di sini.

Fallback Pro

NextPDF Pro menyediakan strategi penandatanganan cloud-KMS — KMS menyimpan kunci penandatangan, dan Pro mengirimkan digest atribut-tertanda ke penyedia. Itu adalah integrasi penandatanganan. Itu bukan pabrik penyedia kunci enkripsi data tingkat koleksi Enterprise dan bukan sidecar embedding GPU. Lihat Accelerator — NextPDF Pro untuk permukaan akselerasi Pro.

Fallback Core

NextPDF Core tidak memiliki sidecar embedding GPU dan tidak memiliki pabrik penyedia KMS. Embedding dan manajemen kunci tingkat koleksi adalah fitur khusus Enterprise.

Catatan batas Enterprise

Transport sidecar GPU, pengenal model embedding, dan kelas pipeline internal dijelaskan hanya pada tingkat perilaku. Klien transport internal, token cakupan internal, dan komposisi pipeline internal berada di luar cakupan permukaan publik dan tidak direproduksi di sini.

Batas penerapan

NextPDF Enterprise terintegrasi dengan KMS atau menurunkan kunci dari rahasia kunci-root yang dikonfigurasi. NextPDF Enterprise itu sendiri tidak menyimpan atau menjamin keamanan rahasia kunci-root tersebut atau kunci KMS cloud. Keamanan kunci bergantung pada KMS atau rahasia kunci-root, pada penerapan, dan pada operator — bukan pada NextPDF Enterprise saja. Operator bertanggung jawab atas penyediaan kunci root, penyimpanan rahasia, konfigurasi KMS, dan penjadwalan rotasi. Tanggung jawab perlindungan kunci mengikuti NIST SP 800-57 Part 1 Rev.5 §5.5.2. NextPDF Enterprise tidak memaparkan alur kredensial KMS atau internal penanganan kunci-root dalam dokumentasi ini.

Batas kepatuhan hukum

Halaman ini berkaitan dengan manajemen kunci. Pernyataan mode-FIPS adalah pernyataan kompatibilitas, bukan sertifikasi dan bukan opini hukum. Konsultasikan kewajiban regulasi Anda dengan penasihat kepatuhan dan hukum Anda sendiri.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Path namespace internal, kelas pembantu, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Kontrak perilaku

• Pabrik penyedia memilih penyedia dari konfigurasi dan mengembalikan penyedia yang memenuhi kontrak penyedia.
• Sebuah penyedia mengembalikan metadata kunci imutabel dan tidak pernah mengembalikan byte kunci mentah.
• Sebuah panggilan rotasi menaikkan versi kunci dan mengembalikan metadata baru; pemanggil mengenkripsi ulang data koleksi.
• Sidecar GPU melaporkan mode terdegradasi saat fallback CPU dan memunculkan eksepsi bertipe ketika tidak tersedia.

Lihat juga

• Referensi Accelerator — NextPDF Enterprise
• Security — NextPDF Enterprise
• Intelligence — NextPDF Enterprise
• Accelerator — NextPDF Pro
• KMS · DEK · HKDF — istilah glosarium.