Accelerator — pełna dokumentacja referencyjna

W skrócie

Ta strona jest pełną dokumentacją referencyjną publicznej powierzchni akceleracji NextPDF\Pro\Accelerator. Obejmuje fabrykę dostawcy, akcelerowany optymalizator wsadowy, wrapper differa oraz usługi sidecara CPU do osadzania i wyszukiwania wektorowego. Podaje parametry, wartości domyślne, tryby awarii i semantykę fallbacku. Najpierw przeczytaj stronę możliwości Acceleratora, aby uzyskać wskazówki dotyczące przepływu pracy.

Dostępność i licencjonowanie

Ta możliwość jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej możliwości. Porównaj edycje i uzyskaj licencję.

Accelerator nie ma flagi licencyjnej dla poszczególnych funkcji. Kod jest dostarczany wraz z edycją Pro; ścieżka akcelerowanego optymalizatora jest wybierana w czasie wykonania przez sondę osiągalności sidecara. Usługa osadzania i indeks wektorowy nie mają rozwiązania awaryjnego w PHP i zawodzą bezpiecznie (fail closed), gdy sidecar jest nieosiągalny.

Powierzchnia publicznego API

composer require nextpdf/pro:^3

Metapakiet nextpdf/premium instaluje kod nextpdf/pro; ten moduł znajduje się w przestrzeni nazw NextPDF\Pro\Accelerator.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub zawodzi z	Uwagi
ProAcceleratorProvider::__construct	SpectrumClient $client	Wiąże dostawcę z klientem sidecara Core	ProAcceleratorProvider	Nic nie zadeklarowano	Wywołujący konstruuje i dostarcza klienta
ProAcceleratorProvider::isAvailable	brak	Sonduje osiągalność sidecara przez klienta	bool	Nic nie zadeklarowano	Tylko osiągalność; punkty końcowe są sondowane przy każdym wywołaniu
ProAcceleratorProvider::embedding	brak	Zwraca memoizowaną usługę osadzania	EmbeddingServiceInterface	Nic nie zadeklarowano	Jedna instancja CpuEmbeddingService na dostawcę
ProAcceleratorProvider::vectorIndex	string $collectionId = 'default'	Zwraca świeży uchwyt indeksu powiązany z kolekcją	VectorIndexInterface	Nic nie zadeklarowano	Nie memoizowany; jeden uchwyt na wywołanie
ProAcceleratorProvider::optimizer	brak	Zwraca memoizowany akcelerowany optymalizator	AcceleratedOptimizer	Nic nie zadeklarowano	Konstruowany z klientem dostawcy
ProAcceleratorProvider::differ	brak	Zwraca memoizowany wrapper differa	AcceleratedDiffer	Nic nie zadeklarowano	Konstruowany z klientem dostawcy
AcceleratedOptimizer::__construct	?SpectrumClient $spectrum = null, OptimizationLevel $level = OptimizationLevel::Balanced, ?LoggerInterface $logger = null	Opakowuje PHP-owy PdfOptimizer na danym poziomie	AcceleratedOptimizer	Nic nie zadeklarowano	Klient null wybiera ścieżkę PHP; logger null wybiera NullLogger
AcceleratedOptimizer::optimizeBatch	array<string, string> $documents	Analizuje każdy dokument; przenosi pracę nad obrazami do sidecara, gdy jest osiągalny	BatchResultInterface	SpectrumApiException SPEC-SEC-001 (HTTP 413) przy wsadzie przekraczającym limit; znaczniki błędów poszczególnych elementów w wyniku awaryjnym	Awarie transportu po dopuszczeniu degradują do ścieżki PHP
AcceleratedDiffer::__construct	?SpectrumClient $spectrum = null	Zachowuje opcjonalnego klienta dla przyszłej zgodności	AcceleratedDiffer	Nic nie zadeklarowano	Klient nie jest używany w tym wydaniu
AcceleratedDiffer::compare	string $sourcePdf, string $targetPdf	Porównuje dwa dokumenty w całości w PHP	DiffResult	Jak Pro PdfDiffer	W tym wydaniu nie jest wysyłane żadne żądanie do sidecara
AcceleratedDiffer::isSpectrumWired	brak	Raportuje, czy wstrzyknięto klienta sidecara	bool	Nic nie zadeklarowano	Tylko stan powiązania; nie wysyła żądania
CpuEmbeddingService::embed	string $text	Deleguje do batchEmbed i zwraca element zerowy	list<float>	Jak batchEmbed	Wektor o 384 wymiarach
CpuEmbeddingService::batchEmbed	array $texts	Osadza wsad na sidecarze	list<list<float>>	InvalidArgumentException przy pustym wsadzie; SpectrumNotAvailableException przy nieosiągalności; SpectrumApiException przy nieudanej, źle sformułowanej lub niezgodnej liczbowo odpowiedzi	Nigdy nie zwraca częściowych wyników
CpuEmbeddingService::getDimension	brak	Zwraca 384	int	Nic nie zadeklarowano	Stała
CpuEmbeddingService::getModelName	brak	Zwraca all-MiniLM-L6-v2	string	Nic nie zadeklarowano	Stała
CpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Wiąże uchwyt z jedną kolekcją	CpuVectorIndex	Nic nie zadeklarowano	Jeden uchwyt na identyfikator kolekcji
CpuVectorIndex::build	array $vectors, array $ids	Buduje indeks kolekcji na sidecarze	void	InvalidArgumentException przy niezgodności długości; SpectrumNotAvailableException przy nieosiągalności	Puste wejście zwraca bez kontaktu z sidecarem
CpuVectorIndex::search	array $queryVector, int $topK = 10	Uszeregowane wyszukiwanie najbliższych sąsiadów	list<VectorSearchResult>	SpectrumNotAvailableException przy nieosiągalności; SpectrumApiException przy wewnątrzpasmowej kopercie błędu; JsonException przy źle sformułowanym ciele	Ranga każdego trafienia w metadanych wyniku
CpuVectorIndex::delete	array $ids	Zawsze odrzuca	void (zadeklarowane)	Zawsze: SpectrumApiException SPEC-INDEX-004 (HTTP 501)	HNSW nie ma usuwania pojedynczych wektorów; zamiast tego przebuduj
CpuVectorIndex::count	brak	Odczytuje sumę kolekcji przez sondę o zadanym wymiarze	int	SpectrumNotAvailableException przy nieosiągalności; SpectrumApiException przy błędzie lub źle sformułowanej odpowiedzi liczącej	Zwraca 0 tylko dla potwierdzonego pustego indeksu
CpuVectorIndex::INDEX_DIMENSION	—	Publiczna stała 384	int	—	Odpowiada wymiarowi osadzania

Sygnatury punktów wejścia

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
}

Kontrakt zachowania

Dostawca

ProAcceleratorProvider jest punktem wejścia. embedding(), optimizer() i differ() memoizują swoje instancje. vectorIndex($collectionId) zwraca świeży uchwyt na każde wywołanie, powiązany z podanym identyfikatorem kolekcji. isAvailable() sonduje osiągalność sidecara przez wstrzykniętego klienta Core SpectrumClient.

Optymalizacja wsadowa

optimizeBatch zwraca wynik wsadowy kluczowany identyfikatorami dokumentów wywołującego. Gdy sidecar jest osiągalny, zagregowany ładunek jest walidowany względem budżetu klienta przed jakimkolwiek buforowaniem lub przesłaniem. Wsad przekraczający limit zawodzi bezpiecznie (fail closed) z SpectrumApiException SPEC-SEC-001 (HTTP 413); nigdy nie degraduje do ścieżki PHP. Dopuszczony wsad jest wysyłany do sidecara w celu równoległej pracy nad obrazami.

Awaria transportu, uwierzytelniania lub parsowania odpowiedzi po dopuszczeniu degraduje do optymalizatora PHP, który analizuje każdy dokument sekwencyjnie. Degradacja jest obserwowalna dwukrotnie: metadane wyniku raportują silnik php_fallback ze sprzętem podsumowania cpu, a ostrzeżenie PSR-3 jest emitowane pod nazwą zdarzenia spectrum.optimize.fallback. Ostrzeżenie niesie wyłącznie klasę wyjątku i liczbę dokumentów; żadne bajty dokumentów nie są logowane. W wyniku awaryjnym awaria analizy poszczególnego dokumentu daje element ze statusem błędu i kodem SPEC-PARSE-001; pozostałe dokumenty we wsadzie nadal się kończą.

Domyślny poziom optymalizacji to Balanced. Pola wyniku poszczególnego elementu to original_bytes, optimized_bytes, objects_removed, images_before, images_after, savings_percent oraz processing_time_ms.

Różnica dokumentów

compare działa w całości w PHP za pośrednictwem Pro PdfDiffer: parsowanie struktury, ekstrakcja tekstu i algorytm różnicy. W tym wydaniu nie jest wysyłane żadne żądanie do sidecara. Kontrakt differa akceptuje wyłącznie surowe ciągi PDF, więc wynik parsowania sidecara nie może zostać wykorzystany; przeniesienie dodałoby koszt bez korzyści. Wstrzyknięty klient jest zachowany na potrzeby przyszłej funkcji przenoszenia parsowania. isSpectrumWired() ujawnia stan powiązania bez wysyłania żądania.

Osadzanie CPU

embed deleguje do batchEmbed([$text]) i zwraca element zerowy. batchEmbed([]) zgłasza InvalidArgumentException przed skontaktowaniem się z sidecarem. Nieosiągalny sidecar zgłasza SpectrumNotAvailableException. Semantyka wsadu jest typu wszystko albo nic: awaria poszczególnego elementu, brakujący lub źle sformułowany wektor bądź niezgodność liczby zgłasza SpectrumApiException (awarie kształtu protokołu niosą SPEC-IO-001) zamiast zwracać częściowe wektory. Nienumeryczny składnik wewnątrz zwróconego wektora jest sprowadzany do 0.0. getDimension zwraca 384; getModelName zwraca all-MiniLM-L6-v2. Sidecar pobiera i ładuje model ONNX leniwie przy pierwszym żądaniu.

Wyszukiwanie wektorowe CPU

Każdy uchwyt wiąże jeden identyfikator kolekcji; każda kolekcja mapuje się na osobny indeks HNSW w pamięci sidecara. build wymaga list wektorów i identyfikatorów o równej długości i w przeciwnym razie zgłasza InvalidArgumentException; puste wejście zwraca bez wywołania sidecara. search zwraca uszeregowane trafienia z rangą liczoną od jeden w metadanych każdego wyniku. Wewnątrzpasmowa koperta błędu zgłasza SpectrumApiException; koperta bez kodu mapuje się na SPEC-INDEX-003. delete zawsze odrzuca z SpectrumApiException SPEC-INDEX-004 (HTTP 501, nie do ponowienia), ponieważ HNSW nie obsługuje usuwania pojedynczych wektorów; zamiast tego przebuduj indeks.

count jest fail-closed i jednoznaczny. Nieosiągalny sidecar zgłasza SpectrumNotAvailableException; błędy transportu i sidecara propagują się bez zmian. Przy poza tym udanej odpowiedzi ciało inne niż JSON zgłasza SPEC-INDEX-005, brakujące metadata.total_vectors zgłasza SPEC-INDEX-006, a suma niecałkowita lub ujemna zgłasza SPEC-INDEX-007. count zwraca 0 tylko dla potwierdzonego pustego indeksu. Sonda rozmiaru przesyła zerowy wektor o dokładnie INDEX_DIMENSION (384) wymiarach z top_k równym 0, więc sidecar walidujący wymiar go akceptuje.

Przypadki brzegowe i tryby awarii

• Pamięć sidecara jest ulotna: restart czyści wszystkie kolekcje HNSW. Traktuj budowę indeksu jako idempotentną i uruchom ją ponownie po restarcie.
• Mieszana dostępność w obrębie jednego procesu jest obsługiwana: optymalizator degraduje się przy każdym wywołaniu; usługi osadzania i wektorowa zawodzą bezpiecznie (fail closed) przy każdym wywołaniu.
• Wsad optymalizatora przekraczający limit zawodzi bezpiecznie (fail closed) przed jakimkolwiek przesłaniem; nie przechodzi awaryjnie na ścieżkę PHP.
• Fallback optymalizatora nigdy nie zawodzi po cichu: sprawdź znacznik silnika w metadanych wyniku i monitoruj zdarzenie ostrzeżenia.
• count nigdy nie raportuje nieosiągalnego sidecara ani błędu protokołu jako 0; te zgłaszają typowane wyjątki.
• Trafienie wyszukiwania bez identyfikatora lub wyniku domyślnie przyjmuje pusty ciąg i 0.0 zamiast powodować awarię wsadu.
• top_k równe 0 jest używane wewnętrznie wyłącznie dla sondy count; przekazuj dodatnie topK dla rzeczywistych wyszukiwań.
• Pierwsze żądanie osadzania ponosi jednorazowy koszt pobrania i załadowania modelu; wymiaruj ten limit czasu osobno.
• Hierarchia wyjątków sidecara i rodziny kodów błędów są skatalogowane w dokumentacji błędów Acceleratora.
• Ten moduł nie wykonuje żadnych operacji kryptograficznych i nie definiuje żadnego zachowania specyficznego dla FIPS. Postawa trybu FIPS jest regulowana przez moduły podpisywania i zgodności, a nie tutaj.

Zgodność

Accelerator deleguje pracę wpływającą na format do modułów Optimizer i Diff i nie deklaruje niezależnej zgodności formatu. Zgodność dla delegowanej pracy jest udokumentowana na stronach referencyjnych Optimizer i Diff. Ta strona nie deklaruje żadnych zewnętrznych identyfikatorów klauzul; każde stwierdzenie jest oparte na źródle produktu. NextPDF nie zgłasza żadnych roszczeń certyfikacyjnych.

Uwagi deweloperskie

• Źródło modułu nosi @since 2.1.0; ta dokumentacja opisuje powierzchnię w postaci dostarczonej w nextpdf/pro 3.1.0.
• Wszystkie klasy są final i używają wstrzykiwania przez konstruktor; konstruuj nowe instancje zamiast mutować.
• SpectrumClient, VectorSearchResult, BatchResultInterface oraz kontrakty EmbeddingServiceInterface i VectorIndexInterface pochodzą z NextPDF Core; wywołujący konstruuje i dostarcza klienta sidecara.
• OptimizationLevel, PdfOptimizer i PdfDiffer pochodzą z modułów Optimizer i Diff edycji Pro; ich semantyka jest udokumentowana na tych stronach referencyjnych.
• Usługa osadzania i indeks wektorowy współdzielą wymiar 384. Buduj wektory indeksu w tym samym wymiarze co osadzenia, które je odpytują.
• Szczegóły wewnętrznego mechanizmu pozostają w wewnętrznej dokumentacji repozytorium źródłowego i są poza zakresem tego podręcznika.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie i wspieraną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Zobacz także

• Accelerator — strona możliwości ze wskazówkami dotyczącymi przepływu pracy.
• Dokumentacja błędów Acceleratora — hierarchia wyjątków sidecara i kody błędów.
• Optimizer — pełna dokumentacja referencyjna
• Diff — pełna dokumentacja referencyjna
• Accelerator — pełna dokumentacja referencyjna NextPDF Enterprise