Accelerator — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF\Pro\Accelerator’ın genel hızlandırma yüzeyi için derinlemesine başvurudur. Sağlayıcı fabrikasını, hızlandırılmış toplu optimize ediciyi, differ sarmalayıcısını ve gömme ile vektör araması için CPU sidecar hizmetlerini kapsar. Parametreleri, varsayılanları, arıza modlarını ve geri dönüş semantiğini belirtir. İş akışı rehberliği için önce Accelerator yetenek sayfasını okuyun.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile birlikte gelir ve bir Pro 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 lisans edinin.

Accelerator’ın özellik başına lisans bayrağı yoktur. Kod, Pro sürümüyle birlikte gelir; hızlandırılmış optimize edici yolu, çalışma zamanında bir sidecar erişilebilirliği yoklamasıyla seçilir. Gömme hizmeti ve vektör dizininin PHP geri dönüşü yoktur ve sidecar’a erişilemediğinde kapalı arıza verir.

Genel API yüzeyi

composer require nextpdf/pro:^3

nextpdf/premium meta paketi, nextpdf/pro kodunu yükler; bu modül, NextPDF\Pro\Accelerator ad alanı altında yer alır.

Simge	Parametreler	Varsayılan davranış	Döndürür	Şununla oluşturur veya arızalanır	Notlar
ProAcceleratorProvider::__construct	SpectrumClient $client	Sağlayıcıyı bir Core sidecar istemcisine bağlar	ProAcceleratorProvider	Bildirilen yok	Çağıran, istemciyi oluşturur ve sağlar
ProAcceleratorProvider::isAvailable	yok	Sidecar erişilebilirliğini istemci aracılığıyla yoklar	bool	Bildirilen yok	Yalnızca erişilebilirlik; uç noktalar çağrı başına yoklanır
ProAcceleratorProvider::embedding	yok	Bellekte tutulan gömme hizmetini döndürür	EmbeddingServiceInterface	Bildirilen yok	Sağlayıcı başına bir CpuEmbeddingService örneği
ProAcceleratorProvider::vectorIndex	string $collectionId = 'default'	Koleksiyona bağlı yeni bir dizin tanıtıcısı döndürür	VectorIndexInterface	Bildirilen yok	Bellekte tutulmaz; çağrı başına bir tanıtıcı
ProAcceleratorProvider::optimizer	yok	Bellekte tutulan hızlandırılmış optimize ediciyi döndürür	AcceleratedOptimizer	Bildirilen yok	Sağlayıcının istemcisiyle oluşturulur
ProAcceleratorProvider::differ	yok	Bellekte tutulan differ sarmalayıcısını döndürür	AcceleratedDiffer	Bildirilen yok	Sağlayıcının istemcisiyle oluşturulur
AcceleratedOptimizer::__construct	?SpectrumClient $spectrum = null, OptimizationLevel $level = OptimizationLevel::Balanced, ?LoggerInterface $logger = null	PHP PdfOptimizer’ı verilen düzeyde sarmalar	AcceleratedOptimizer	Bildirilen yok	Null istemci PHP yolunu seçer; null günlükçü NullLogger’ı seçer
AcceleratedOptimizer::optimizeBatch	array<string, string> $documents	Her belgeyi analiz eder; erişilebilir olduğunda görüntü işini sidecar’a devreder	BatchResultInterface	Sınır aşan bir toplu işte SpectrumApiException SPEC-SEC-001 (HTTP 413); geri dönüş sonucunda öğe başına hata işaretçileri	Kabulden sonraki taşıma hataları PHP yoluna geriler
AcceleratedDiffer::__construct	?SpectrumClient $spectrum = null	İleriye dönük uyumluluk için isteğe bağlı istemciyi saklar	AcceleratedDiffer	Bildirilen yok	İstemci bu sürümde kullanılmaz
AcceleratedDiffer::compare	string $sourcePdf, string $targetPdf	İki belgeyi tamamen PHP’de karşılaştırır	DiffResult	Pro PdfDiffer gibi	Bu sürümde sidecar isteği gönderilmez
AcceleratedDiffer::isSpectrumWired	yok	Bir sidecar istemcisinin enjekte edilip edilmediğini raporlar	bool	Bildirilen yok	Yalnızca bağlantı durumu; istek göndermez
CpuEmbeddingService::embed	string $text	batchEmbed’e devreder ve sıfırıncı öğeyi döndürür	list<float>	batchEmbed gibi	384 boyutlu vektör
CpuEmbeddingService::batchEmbed	array $texts	Toplu işi sidecar’da gömer	list<list<float>>	Boş toplu işte InvalidArgumentException; erişilemediğinde SpectrumNotAvailableException; başarısız, hatalı biçimlendirilmiş veya sayısı uyuşmayan yanıtta SpectrumApiException	Asla kısmi sonuç döndürmez
CpuEmbeddingService::getDimension	yok	384 döndürür	int	Bildirilen yok	Sabit
CpuEmbeddingService::getModelName	yok	all-MiniLM-L6-v2 döndürür	string	Bildirilen yok	Sabit
CpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Tanıtıcıyı tek bir koleksiyona bağlar	CpuVectorIndex	Bildirilen yok	Koleksiyon tanımlayıcısı başına bir tanıtıcı
CpuVectorIndex::build	array $vectors, array $ids	Koleksiyon dizinini sidecar’da oluşturur	void	Uzunluk uyuşmazlığında InvalidArgumentException; erişilemediğinde SpectrumNotAvailableException	Boş bir girdi, sidecar’a başvurmadan döner
CpuVectorIndex::search	array $queryVector, int $topK = 10	Sıralanmış en yakın komşu araması	list<VectorSearchResult>	Erişilemediğinde SpectrumNotAvailableException; bant içi hata zarfında SpectrumApiException; hatalı biçimlendirilmiş gövdede JsonException	Sonuç üst verisinde isabet başına sıralama
CpuVectorIndex::delete	array $ids	Her zaman reddeder	void (bildirilen)	Her zaman: SpectrumApiException SPEC-INDEX-004 (HTTP 501)	HNSW’de vektör başına silme yoktur; bunun yerine yeniden oluşturun
CpuVectorIndex::count	yok	Boyutlandırılmış bir yoklama aracılığıyla koleksiyon toplamını okur	int	Erişilemediğinde SpectrumNotAvailableException; bir hatada veya hatalı biçimlendirilmiş sayım yanıtında SpectrumApiException	Yalnızca doğrulanmış boş bir dizin için 0 döndürür
CpuVectorIndex::INDEX_DIMENSION	—	Genel sabit 384	int	—	Gömme boyutuyla eşleşir

Giriş noktası imzaları

final class ProAcceleratorProvider
{
    public function __construct(
        private readonly SpectrumClient $client,
    )

    public function isAvailable(): bool

    public function embedding(): EmbeddingServiceInterface

    public function vectorIndex(string $collectionId = 'default'): VectorIndexInterface

    public function optimizer(): AcceleratedOptimizer

    public function differ(): AcceleratedDiffer
}

final class AcceleratedOptimizer
{
    public function __construct(
        private readonly ?SpectrumClient $spectrum = null,
        private readonly OptimizationLevel $level = OptimizationLevel::Balanced,
        ?LoggerInterface $logger = null,
    )

    public function optimizeBatch(array $documents): BatchResultInterface
}

final class AcceleratedDiffer
{
    public function __construct(
        private readonly ?SpectrumClient $spectrum = null,
    )

    public function compare(string $sourcePdf, string $targetPdf): DiffResult

    public function isSpectrumWired(): bool
}

final class CpuEmbeddingService 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 CpuVectorIndex implements VectorIndexInterface
{
    public const int INDEX_DIMENSION = 384;

    public function __construct(
        private readonly SpectrumClient $client,
        private readonly 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
}

Davranış sözleşmesi

Sağlayıcı

ProAcceleratorProvider, giriş noktasıdır. embedding(), optimizer() ve differ(), örneklerini bellekte tutar. vectorIndex($collectionId), verilen koleksiyon tanımlayıcısına bağlı olarak çağrı başına yeni bir tanıtıcı döndürür. isAvailable(), enjekte edilen Core SpectrumClient aracılığıyla sidecar erişilebilirliğini yoklar.

Toplu optimizasyon

optimizeBatch, çağıranın belge tanımlayıcılarına göre anahtarlanmış bir toplu sonuç döndürür. Sidecar erişilebilir olduğunda, toplam yük herhangi bir arabelleğe alma veya yüklemeden önce istemci bütçesine göre doğrulanır. Sınır aşan bir toplu iş, SpectrumApiException SPEC-SEC-001 (HTTP 413) ile kapalı arıza verir; asla PHP yoluna gerilemez. Kabul edilen bir toplu iş, paralel görüntü işi için sidecar’a gönderilir.

Kabulden sonraki bir taşıma, kimlik doğrulama veya yanıt ayrıştırma hatası, her belgeyi sırayla analiz eden PHP optimize edicisine geriler. Gerileme iki kez gözlemlenebilir: sonuç üst verisi, özet donanım cpu ile php_fallback motorunu raporlar ve spectrum.optimize.fallback olay adı altında bir PSR-3 uyarısı yayılır. Uyarı, yalnızca istisna sınıfını ve belge sayısını taşır; hiçbir belge baytı günlüğe kaydedilmez. Geri dönüş sonucunda, belge başına bir analiz hatası, hata durumu ve SPEC-PARSE-001 koduna sahip bir öğe verir; toplu işteki diğer belgeler yine de tamamlanır.

Varsayılan optimizasyon düzeyi Balanced’dır. Öğe başına sonuç alanları original_bytes, optimized_bytes, objects_removed, images_before, images_after, savings_percent ve processing_time_ms’dir.

Belge farkı

compare, Pro PdfDiffer aracılığıyla tamamen PHP’de çalışır: yapı ayrıştırma, metin çıkarma ve fark algoritması. Bu sürümde sidecar isteği gönderilmez. Differ sözleşmesi yalnızca ham PDF dizeleri kabul eder, bu nedenle bir sidecar ayrıştırma sonucu tüketilemez; devretme, fayda sağlamadan maliyet ekler. Enjekte edilen bir istemci, gelecekteki bir ayrıştırma devretme özelliği için saklanır. isSpectrumWired(), istek göndermeden bağlantı durumunu açığa çıkarır.

CPU gömme

embed, batchEmbed([$text])’e devreder ve sıfırıncı öğeyi döndürür. batchEmbed([]), sidecar’a başvurmadan önce InvalidArgumentException oluşturur. Erişilemeyen bir sidecar, SpectrumNotAvailableException oluşturur. Toplu iş semantiği ya hep ya hiçtir: öğe başına bir hata, eksik veya hatalı biçimlendirilmiş bir vektör ya da bir sayım uyuşmazlığı, kısmi vektörler döndürmek yerine SpectrumApiException oluşturur (protokol biçimi hataları SPEC-IO-001 taşır). Döndürülen bir vektörün içindeki sayısal olmayan bir bileşen 0.0’a zorlanır. getDimension, 384 döndürür; getModelName, all-MiniLM-L6-v2 döndürür. Sidecar, ONNX modelini ilk istekte tembel olarak indirir ve yükler.

CPU vektör araması

Her tanıtıcı, tek bir koleksiyon tanımlayıcısına bağlanır; her koleksiyon, sidecar’da ayrı bir bellek içi HNSW dizinine eşlenir. build, eşit uzunlukta vektör ve tanımlayıcı listeleri gerektirir ve aksi takdirde InvalidArgumentException oluşturur; boş bir girdi, sidecar çağrısı olmadan döner. search, her sonucun üst verisinde bir tabanlı bir sıralama ile sıralanmış isabetler döndürür. Bant içi bir hata zarfı, SpectrumApiException oluşturur; kodu olmayan bir zarf, SPEC-INDEX-003’e eşlenir. HNSW vektör başına silmeyi desteklemediğinden delete, her zaman SpectrumApiException SPEC-INDEX-004 (HTTP 501, yeniden denenemez) ile reddeder; bunun yerine dizini yeniden oluşturun.

count, kapalı arıza verir ve nettir. Erişilemeyen bir sidecar, SpectrumNotAvailableException oluşturur; taşıma ve sidecar hataları değişmeden yayılır. Aksi halde başarılı bir yanıtta, JSON olmayan bir gövde SPEC-INDEX-005, eksik bir metadata.total_vectors SPEC-INDEX-006 ve tamsayı olmayan veya negatif bir toplam SPEC-INDEX-007 oluşturur. count, yalnızca doğrulanmış boş bir dizin için 0 döndürür. Boyut yoklaması, tam olarak INDEX_DIMENSION (384) boyutlu ve top_k değeri 0 olan bir sıfır vektör gönderir, böylece boyut doğrulayan bir sidecar bunu kabul eder.

Uç durumlar ve arıza modları

• Sidecar belleği uçucudur: bir yeniden başlatma, tüm HNSW koleksiyonlarını temizler. Dizin oluşturmayı etkisiz olarak değerlendirin ve yeniden başlatmadan sonra yeniden çalıştırın.
• Tek bir süreç içinde karışık kullanılabilirlik desteklenir: optimize edici çağrı başına geriler; gömme ve vektör hizmetleri çağrı başına kapalı arıza verir.
• Sınır aşan bir optimize edici toplu işi, herhangi bir yüklemeden önce kapalı arıza verir; PHP yoluna geri dönmez.
• Optimize edici geri dönüşü asla sessizce arızalanmaz: sonuç üst verisi motor işaretçisini kontrol edin ve uyarı olayını izleyin.
• count, erişilemeyen bir sidecar’ı veya bir protokol hatasını asla 0 olarak raporlamaz; bunlar türlü istisnalar oluşturur.
• Tanımlayıcısı veya puanı eksik olan bir arama isabeti, toplu işi başarısız kılmak yerine boş bir dizeye ve 0.0’a varsayılan olur.
• 0 top_k değeri, dahili olarak yalnızca sayım yoklaması için kullanılır; gerçek aramalar için pozitif bir topK geçirin.
• İlk gömme isteği, tek seferlik model indirme ve yükleme maliyetini öder; bu zaman aşımını ayrı olarak boyutlandırın.
• Sidecar istisna hiyerarşisi ve hata kodu aileleri, Accelerator hata başvurusunda kataloglanmıştır.
• Bu modül hiçbir kriptografik işlem yapmaz ve hiçbir FIPS’e özgü davranış tanımlamaz. FIPS modu duruşu burada değil, imzalama ve uyumluluk modülleri tarafından yönetilir.

Uygunluk

Accelerator, biçimi etkileyen işi Optimizer ve Diff modüllerine devreder ve bağımsız bir biçim uygunluğu öne sürmez. Devredilen iş için uygunluk, Optimizer ve Diff başvuru sayfalarında belgelenir. Bu sayfa hiçbir harici kural tanımlayıcısı iddia etmez; her ifade, ürün kaynağına dayanır. NextPDF hiçbir sertifikasyon iddiasında bulunmaz.

Geliştirme notları

• Modül kaynağı @since 2.1.0 taşır; bu başvuru, yüzeyi nextpdf/pro 3.1.0’da sunulduğu şekliyle belgeler.
• Tüm sınıflar final’dır ve yapıcı enjeksiyonu kullanır; değiştirmek yerine yeni örnekler oluşturun.
• SpectrumClient, VectorSearchResult, BatchResultInterface ve EmbeddingServiceInterface ile VectorIndexInterface sözleşmeleri NextPDF Core’dan gelir; çağıran, sidecar istemcisini oluşturur ve sağlar.
• OptimizationLevel, PdfOptimizer ve PdfDiffer, Pro Optimizer ve Diff modüllerinden gelir; semantikleri bu başvuru sayfalarında belgelenir.
• Gömme hizmeti ve vektör dizini, 384 boyutunu paylaşır. Dizin vektörlerini, onları sorgulayan gömmelerle aynı boyuta oluşturun.
• Dahili mekanizma ayrıntısı, kaynak deposunun dahili belgelerinde kalır ve bu kılavuzun kapsamı dışındadır.

Yayın sınırı

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

Ayrıca bkz.

• Accelerator — iş akışı rehberliği için yetenek sayfası.
• Accelerator hata başvurusu — sidecar istisna hiyerarşisi ve hata kodları.
• Optimizer — Derinlemesine başvuru
• Diff — Derinlemesine başvuru
• Accelerator — NextPDF Enterprise derinlemesine başvurusu