Accelerator — Derinlemesine başvuru (GPU yardımcı hizmeti, KMS sağlayıcı fabrikası)

Bir bakışta

Bu sayfa, NextPDF\Enterprise\Accelerator genel hızlandırma yüzeyi için derinlemesine referanstır. KMS sağlayıcı yığınını — fabrikayı, sağlayıcı sözleşmesini, yerel sağlayıcıyı ve anahtar-meta verisi sonucunu — ve gömme ile vektör araması için GPU yardımcı hizmeti hizmetlerini kapsar. Parametreleri, varsayılanları, başarısızlık kiplerini ve anahtar-emanet duruşunu belirtir. İş akışı rehberliği için önce Accelerator yetenek sayfasını okuyun. Aynı ad alanındaki diğer simgeler başka yeteneklere aittir ve bu sayfanın kapsamı dışındadır.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Enterprise (nextpdf/enterprise) ile birlikte gelir ve Enterprise katman lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans alın.

KMS sağlayıcısı çalışma zamanında seçilir; çağıran kod, somut sağlayıcıya değil, sağlayıcı sözleşmesine bağımlı olur. Gömme ve vektör-dizini hizmetleri, Core EmbeddingServiceInterface ve VectorIndexInterface sözleşmelerini uygular.

Genel API yüzeyi

composer require nextpdf/enterprise:^3

Simge	Parametreler	Varsayılan davranış	Döndürür	Şununla hata verir veya başarısız olur	Notlar
KmsProviderFactory::fromEnvironment	yok	Seçici değişkenin adlandırdığı sağlayıcıyı oluşturur; ayarlanmamış veya boş ise local seçilir	KmsProviderInterface	Eksik bir ana anahtarda, kullanılamayan bir bulut sağlayıcısında veya bilinmeyen bir adda RuntimeException	Statik giriş noktası
KmsProviderFactory::create	string $providerType, array $config = []	Adlandırılan sağlayıcıyı açık yapılandırmadan oluşturur	KmsProviderInterface	local boş olmayan bir encryption_key içermediğinde veya bilinmeyen bir adda RuntimeException	Bu sürümde oluşturulabilen tek ad local’dir
KmsProviderInterface::getEncryptionKey	string $collectionId	Koleksiyon için geçerli anahtar meta verisini döndürür	EncryptionKeyResult	Sağlayıcıya erişilemediğinde veya yanlış yapılandırıldığında RuntimeException (sözleşme)	Yalnızca meta veri; asla ham anahtar baytı değil
KmsProviderInterface::rotateKey	string $collectionId	Anahtar sürümünü ilerletir	EncryptionKeyResult	Rotasyon başarısız olduğunda RuntimeException (sözleşme)	Rotasyon, çağırana yönelik bir yeniden-şifreleme sinyalidir
KmsProviderInterface::providerName	yok	Kurallı sağlayıcı adını bildirir	string	Bildirilmemiş	local, aws, gcp, azure, vault
LocalKmsProvider::__construct	string $encryptionKey (hassas)	En az 64 hex karakterlik (32 bayt) bir hex ana anahtarı doğrular	LocalKmsProvider	Kısa veya hex olmayan bir değerde InvalidArgumentException	Hızlı-başarısızlık koruması; kendisi hiçbir türetme yapmaz
LocalKmsProvider::getEncryptionKey	string $collectionId	local:{collectionId}:v{version} üretir; sürüm varsayılan olarak 1’dir	EncryptionKeyResult	Bildirilmemiş	Algoritma etiketi AES-256-GCM
LocalKmsProvider::rotateKey	string $collectionId	Süreç içi sürüm sayacını artırır	EncryptionKeyResult	Bildirilmemiş	Sürüm durumu örnek başınadır
EncryptionKeyResult::__construct	string $keyId, int $keyVersion, string $algorithm = 'AES-256-GCM', string $provider = 'local'	Değişmez meta veri değer nesnesi	EncryptionKeyResult	Bildirilmemiş	Asla anahtar malzemesi taşımaz
GpuEmbeddingService::embed	string $text	batchEmbed’e devreder ve sıfırıncı öğeyi döndürür	list<float>	batchEmbed ile aynı	1024 boyutlu vektör
GpuEmbeddingService::batchEmbed	array $texts	Toplu isteği yardımcı hizmette gömer	list<list<float>>	Boş bir toplu istekte InvalidArgumentException; yardımcı hizmete erişilemediğinde SpectrumNotAvailableException; başarısız, bozuk veya sayısı uyuşmayan bir yanıtta SpectrumApiException	Asla kısmi sonuç döndürmez
GpuEmbeddingService::getDimension	yok	1024 döndürür	int	Bildirilmemiş	Sabit
GpuEmbeddingService::getModelName	yok	multilingual-e5-large döndürür	string	Bildirilmemiş	Sabit
GpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Tutamacı tek bir koleksiyona bağlar	GpuVectorIndex	Bildirilmemiş	Koleksiyon tanımlayıcısı başına bir tutamaç
GpuVectorIndex::build	array $vectors, array $ids	Koleksiyon dizinini yardımcı hizmette oluşturur	void	Boş bir toplu istekte veya uzunluk uyuşmazlığında InvalidArgumentException; erişilemediğinde SpectrumNotAvailableException; beklenmeyen bir oluşturma yanıtında SpectrumApiException	Yeniden oluşturma dizini değiştirir
GpuVectorIndex::search	array $queryVector, int $topK = 10	Sıralanmış en yakın komşu araması	list<VectorSearchResult>	Erişilemediğinde SpectrumNotAvailableException; bozuk bir yanıt gövdesinde JsonException	Sonuç meta verisinde isabet başına sıra
GpuVectorIndex::delete	array $ids	Her zaman reddeder	void (bildirilmiş)	Her zaman: SpectrumApiException (uygulanmamış)	Oluşturulan dizin değişmezdir; bunun yerine yeniden oluşturun
GpuVectorIndex::count	yok	Koleksiyon toplamını yardımcı hizmetten okur	int	İstisna atmaz; herhangi bir hata 0 döndürür	0 belirsizdir: boş ya da erişilemez

Giriş noktası imzaları

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
}

Yapılandırma yüzeyi

Ayar	Tüketici	Anlam
SPECTRUM_KMS_PROVIDER	fromEnvironment()	Sağlayıcı seçici. Ayarlanmamış veya boş ise local’e çözümlenir.
SPECTRUM_ENCRYPTION_KEY	local sağlayıcı yolu	Hex ile kodlanmış ana anahtar; en az 64 hex karakter (32 bayt). Yardımcı hizmetle paylaşılır.
encryption_key	create('local', [...])	Açık ana anahtar; aynı biçim ve doğrulama.

Davranış sözleşmesi

Sağlayıcı seçimi

KmsProviderFactory::fromEnvironment, seçici değişkeni okur ve varsayılan olarak local’i kullanır. Bulut sağlayıcı adları aws, gcp, azure ve vault tanınır ancak bu sürümde oluşturulamaz. aws seçmek, gereken aws/aws-sdk-php paketini adlandıran türlenmiş bir hata yükseltir; diğer üçü tümleştirmeyi uygulanmamış olarak bildirir. Bilinmeyen bir ad, desteklenen adları listeleyen türlenmiş bir hata yükseltir. KmsProviderFactory::create, açık bir sağlayıcı adını ve bir yapılandırma haritasını kabul eder; oluşturduğu tek ad local’dir.

Anahtar meta verisi ve emaneti

Bir sağlayıcı değişmez anahtar meta verisi döndürür: bir anahtar tanımlayıcısı, monoton olarak artan bir anahtar sürümü, algoritma etiketi ve sağlayıcı adı. Asla ham anahtar baytları döndürmez, bu yüzden bir meta veri sızıntısı anahtar malzemesini açığa çıkarmaz. Yerel sağlayıcı, görevleri accelerator yardımcı hizmetiyle paylaşır. PHP sınıfı, oluşturma sırasında ana gizi doğrular ve local:{collectionId}:v{version} biçiminde kararlı, koleksiyon kapsamlı bir anahtar kimliği üretir. Yardımcı hizmet, HKDF-SHA256 türetmesini ve AES-256-GCM şifrelemesini gerçekleştirir; koleksiyon tanımlayıcısı ve sürümü alan ayırıcı olarak kullanarak koleksiyon başına ayrı bir 32 baytlık veri-şifreleme anahtarı türetir. Her iki taraf da yapılandırılmış aynı ana gizi okur. Hiçbir harici KMS hizmetiyle iletişim kurulmaz; anahtar işleme dağıtımın içinde kalır. Anahtar sürümü ve yaşam döngüsü modeli NIST SP 800-57 Part 1 Rev.5 §4’ü izler.

Bir rotasyon çağrısı anahtar sürümünü ilerletir ve yeni meta veriyi döndürür. Çağıran, koleksiyon verisini yeni sürümle yeniden şifreler; sağlayıcı kendisi hiçbir şeyi yeniden şifrelemez.

Anahtar güvenliği; KMS’ye veya ana-anahtar gizine, dağıtıma ve operatöre bağlıdır — yalnızca NextPDF Enterprise’a değil. Operatör; ana-anahtar sağlamaya, giz depolamaya, KMS yapılandırmasına ve rotasyon zamanlamasına sahiptir. Anahtar-koruması sorumluluğu NIST SP 800-57 Part 1 Rev.5 §5.5.2’yi izler.

GPU gömme

GpuEmbeddingService, Core gömme sözleşmesini uygular ve yardımcı hizmete devreder. Yardımcı hizmet, kullanılabilir olduğunda gömme modelini bir GPU üzerinde çalıştırır ve aksi takdirde CPU’ya geri döner; yanıt meta verisini GPU’dan bozulmuş olarak işaretler. Vektör biçimi her iki durumda da aynıdır. Model (yaklaşık 1.3 GB) ilk istekte tembel biçimde indirilir ve yüklenir. Toplu istek semantiği ya hep ya hiçtir: öğe başına bir hata, bozuk bir vektör veya sayı uyuşmazlığı, kısmi sonuç döndürmek yerine türlenmiş bir hata yükseltir.

GPU vektör araması

GpuVectorIndex, Core vektör-dizini sözleşmesini uygular ve bir tutamacı tek bir koleksiyon tanımlayıcısına bağlar. build, dizini yardımcı hizmette oluşturur; yardımcı hizmet, kullanılabilir olduğunda bir GPU dizini, aksi takdirde bir CPU dizini kullanır. Dizin bir kez oluşturulduktan sonra değişmezdir: delete her zaman türlenmiş bir uygulanmamış hatasıyla reddeder ve kaldırma bir yeniden oluşturma gerektirir. search, her sonucun meta verisinde bir tabanlı sıra ile sıralanmış isabetler döndürür. count, koleksiyon toplamını yardımcı hizmetten ister ve herhangi bir hatada istisna yükseltmek yerine 0 bildirir.

Uç durumlar ve başarısızlık kipleri

• Ana anahtar, hex’ten en az 32 bayta çözümlenmelidir. Daha kısa veya hex olmayan bir değer, herhangi bir yardımcı hizmet çağrısından önce, oluşturma sırasında InvalidArgumentException yükseltir.
• Ayarlanmamış veya boş bir seçici değişken local’e çözümlenir; fabrika asla başka bir sağlayıcı tahmin etmez.
• local yolunda ana-anahtar değişkeni olmadan fromEnvironment, eksik değişkeni adlandıran türlenmiş bir hata yükseltir.
• Boş olmayan bir encryption_key girdisi olmadan create('local', [...]), eksik girdiyi adlandıran türlenmiş bir hata yükseltir.
• Anahtar-sürümü durumu süreç içidir ve sağlayıcı örneği başınadır. Yeni bir süreç, rotasyon yeniden çalışana kadar sürüm 1’i gözlemler. Rotasyon sonuçlarını, sağlayıcı durumuna güvenerek değil, veriyi yeniden şifreleyerek kalıcılaştırın.
• Boş bir gömme toplu isteği InvalidArgumentException yükseltir; yardımcı hizmetle iletişim kurulmaz.
• Yardımcı hizmet kullanılabilirliği çağrı başına yoklanır. Erişilemeyen bir yardımcı hizmet SpectrumNotAvailableException yükseltir; hizmetler asla sessizce başarısız olmaz.
• Döndürülen bir gömme vektörünün içindeki sayısal olmayan bir bileşen 0.0’a zorlanır; eksik veya dizi olmayan bir vektör SpectrumApiException yükseltir.
• İlk gömme isteği, tek seferlik model indirme ve yükleme maliyetini öder; o zaman aşımını ayrı boyutlandırın.
• build ve search, yardımcı hizmet yanıtını katı biçimde çözer; bozuk bir gövde JsonException yükseltir. count her hatayı yutar ve 0 döndürür.
• Tanımlayıcısı veya puanı eksik bir arama isabeti, toplu isteği başarısız kılmak yerine boş bir dizeye ve 0.0’a varsayılır.
• Yardımcı hizmet hata kodları ve istisna hiyerarşisi Accelerator hata referansında kataloglanmıştır.

FIPS modu davranışı

Yerel anahtar yolu, türetme için HKDF-SHA256 ve şifreleme için AES-256-GCM kullanır; yardımcı hizmet her ikisini de yürütür. Anahtar meta verisinde kaydedilen algoritma etiketi AES-256-GCM’dir. Dağıtım FIPS-doğrulamalı bir kriptografik sağlayıcıya karşı çalıştığında, bu ilkeller o doğrulanmış sınırda çalışır. AES-GCM kullanımı, NIST SP 800-38D §5 uyarınca anahtar başına benzersiz bir başlatma vektörü gerektirir.

NextPDF Enterprise, FIPS-doğrulamalı bir kriptografik modül değildir ve hiçbir FIPS sertifikasyon iddiasında bulunmaz. Yalnızca FIPS-doğrulamalı bir kriptografik sağlayıcı veya FIPS-doğrulamalı bir KMS ile yapılandırıldığında FIPS-uyumlu bir kipte çalışır. Bu depoda hiçbir FIPS sertifikasyon yapıtı yoktur.

Uygunluk

İddia	Standart	Madde
Anahtar sürümü ve yaşam döngüsü modeli, anahtar-durumu rehberliğini izler.	NIST SP 800-57 Part 1 Rev.5	§4
Anahtar-koruması ve emanet sorumluluğu, anahtar sahibine ve operatöre aittir.	NIST SP 800-57 Part 1 Rev.5	§5.5.2
AES-GCM, anahtar başına benzersiz bir başlatma vektörü gerektirir.	NIST SP 800-38D	§5

Tüm maddeler başka sözcüklerle anlatılmıştır; NextPDF normatif metni yeniden üretmez. NextPDF hiçbir sertifikasyon iddiasında bulunmaz. Anılan maddelerle uyum, bir sertifikasyon değil, bir yetenek beyanıdır. Bu sayfa anahtar yönetimini ilgilendirir; FIPS-modu beyanı, bir hukuki görüş değil, bir uyumluluk beyanıdır. Kendi uygunluk ve hukuk danışmanlarınıza başvurun.

Geliştirme notları

• Modül kaynağı @since 2.1.0 taşır; bu referans, yüzeyi nextpdf/enterprise 3.1.0’da yayımlandığı şekliyle belgeler.
• Tüm sınıflar final’dir; EncryptionKeyResult final readonly’dir. Değiştirmek yerine yeni örnekler oluşturun.
• Ana anahtar, hassas bir oluşturucu parametresidir (#[SensitiveParameter]); PHP onu yığın izlerinden çıkarır. Onu uygulama günlüklerinden ve yapılandırma dökümlerinden uzak tutun.
• SpectrumClient, VectorSearchResult ve EmbeddingServiceInterface ile VectorIndexInterface sözleşmeleri NextPDF Core’dan gelir; çağıran, yardımcı hizmet istemcisini oluşturur ve sağlar.
• NextPDF\Enterprise\Accelerator ad alanı ayrıca toplu boşaltma motorlarını ve getirme-koleksiyonu ile OCR çıkarma yığınlarını da taşır; bu yüzeyler bu sayfanın kapsamı dışındadır.
• Dahilî mekanizma ayrıntısı, kaynak deposunun dahilî belgelerinde kalır ve bu kılavuzun kapsamı dışındadır.

Yayımlama sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahilî ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bakınız

• Accelerator — GPU yardımcı hizmeti ve KMS sağlayıcı fabrikası — iş akışı ve emanet rehberliği için yetenek sayfası.
• Accelerator hata referansı — yardımcı hizmet istisna hiyerarşisi ve hata kodları.
• Security — derinlemesine referans
• Accelerator — NextPDF Pro derinlemesine referansı