Pro edycja

Accelerator

W skrócie

Accelerator przenosi wsadową ponowną kompresję obrazów, parsowanie PDF oraz osadzanie tekstu do współlokowanego komponentu CPU typu sidecar. Gdy sidecar jest nieosiągalny, każda operacja przechodzi na ścieżkę PHP działającą w procesie, więc wywołujący obserwują te same wyniki w obu przypadkach.

Dostępność i licencjonowanie

Ta funkcja 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 funkcji. Porównaj edycje i uzyskaj licencję.

Accelerator nie ma osobnej flagi dla poszczególnych funkcji. Przyspieszona ścieżka jest wybierana w czasie wykonywania przez kontrolę osiągalności sidecara (ProAcceleratorProvider::isAvailable()); gdy sidecar jest nieosiągalny, zamiast tego działa ścieżka PHP w procesie.

Instalacja

composer require nextpdf/pro:^3

Pakiet Premium instaluje kod nextpdf/pro pod przestrzenią nazw NextPDF\Pro\Accelerator. Metapakiet nextpdf/premium instaluje również możliwości Enterprise; sam Accelerator to funkcja na poziomie Pro.

Przegląd koncepcyjny

ProAcceleratorProvider to punkt wejścia. Leniwie konstruuje cztery usługi:

Przyspieszony optymalizator, który opakowuje Pro PdfOptimizer i przenosi wsadową pracę nad obrazami do sidecara.
Przyspieszony mechanizm różnic, który opakowuje Pro PdfDiffer; sidecar zrównolegla parsowanie struktury, podczas gdy sam algorytm różnic działa w PHP.
Usługa osadzania CPU, która zwraca 384-wymiarowe wektory przy użyciu modelu ONNX all-MiniLM-L6-v2 hostowanego przez sidecar.
Indeks wektorowy CPU, który buduje i przeszukuje indeks HNSW w pamięci kluczowany identyfikatorem kolekcji.

Projekt utrzymuje logikę domenową w PHP. Sidecar wykonuje zrównoleglaną pracę ograniczoną przez CPU (transkodowanie obrazów, parsowanie wielu dokumentów, wnioskowanie ONNX, wyszukiwanie wektorowe). Każda przyspieszona ścieżka ma deterministyczne rozwiązanie zastępcze PHP, które daje równoważne wyniki.

Dlaczego działa to w ten sposób

Nośną decyzją jest to, że poprawność nigdy nie zależy od sidecara. Logika domenowa pozostaje w PHP; sidecar wykonuje wyłącznie zrównoleglaną pracę ograniczoną przez CPU. Optymalizator i mechanizm różnic (AcceleratedOptimizer, AcceleratedDiffer) utrzymują deterministyczne rozwiązanie zastępcze PHP, więc brakujący sidecar zmienia czas, a nie wyniki. Jedynie dwie operacje bez odpowiednika PHP — CpuEmbeddingService i CpuVectorIndex — zawodzą w sposób zamknięty, zamiast obniżać poziom. Cicha błędna odpowiedź byłaby tam gorsza niż jawny błąd. Ten podział pozwala przepustowości skalować się wraz z rdzeniami sidecara, a wywołujący zachowują jedną ścieżkę kodu i jedną granicę zaufania.

Kontekst projektowy: Generowanie dokumentów o dużej objętości.

Kontrakt zachowania

ProAcceleratorProvider::isAvailable() zwraca informację, czy sidecar odpowiada. Wywołujący mogą się na tym rozgałęziać, lecz nie muszą: optymalizator i mechanizm różnic przechodzą na rozwiązanie zastępcze automatycznie.
embedding()->embed() zwraca pojedynczy 384-elementowy wektor; batchEmbed() zwraca jeden wektor na wejście i odrzuca pustą listę wejść z InvalidArgumentException.
vectorIndex($collectionId)->build() wymaga, aby vectors oraz ids miały tę samą długość, i traktuje puste wejście jako brak działania.
vectorIndex()->search($queryVector, $topK) zwraca uszeregowane wyniki; delete() nie jest obsługiwane dla indeksu HNSW i odrzuca wywołanie — wywołujący zamiast tego odbudowują indeks.
Usługa osadzania oraz indeks wektorowy wymagają sidecara; zgłaszają błąd „niedostępne”, zamiast po cichu obniżać poziom, ponieważ nie ma odpowiednika PHP dla wnioskowania ONNX ani wyszukiwania HNSW.
Optymalizator i mechanizm różnic nigdy nie zgłaszają błędu przy niepowodzeniu sidecara; przechodzą na ścieżkę PHP w sposób przezroczysty.

Przykład kodu — Szybki start

Poniższe odzwierciedla udokumentowane publiczne API (ProAcceleratorProvider). Repozytorium nie dostarcza uruchamialnego przykładu dla tego modułu.

use NextPDF\Pro\Accelerator\ProAcceleratorProvider;

$provider = new ProAcceleratorProvider($spectrumClient);

$result = $provider->optimizer()->optimizeBatch([
    'invoice-1' => $pdfBytesA,
    'invoice-2' => $pdfBytesB,
]);

foreach ($result->getItems() as $item) {
    // Per-document optimization outcome.
}

Przykład kodu — Produkcja

use NextPDF\Pro\Accelerator\ProAcceleratorProvider;

$provider = new ProAcceleratorProvider($spectrumClient);

if ($provider->isAvailable()) {
    $index = $provider->vectorIndex('contracts');
    $index->build($vectors, $ids);
    $hits = $index->search($queryVector, topK: 10);
} else {
    // No PHP equivalent for HNSW search: route to your own retrieval path
    // or surface a degraded-capability message.
}

Połącz ProAcceleratorProvider przez swój kontener jako singleton, aby instancje optymalizatora i mechanizmu różnic były wielokrotnie wykorzystywane. Traktuj wywołania osadzania i indeksu wektorowego jako wymagające sidecara.

Przypadki brzegowe i pułapki

Indeks wektorowy żyje w pamięci procesu sidecara i jest kluczowany identyfikatorem kolekcji. Restart sidecara czyści wszystkie indeksy; odbuduj je po restarcie.
count() na indeksie wektorowym zwraca 0, gdy sidecar jest nieosiągalny, zamiast zgłaszać błąd.
Przyspieszanie optymalizatora i mechanizmu różnic ma charakter najlepszego starania; błąd sidecara w trakcie wsadu powoduje ciche przejście na rozwiązanie zastępcze dla tego wywołania, więc zmienia się czas — a nie poprawność.

Wydajność

Przyspieszanie celuje w pracę wsadową ograniczoną przez CPU: równoległe transkodowanie obrazów, parsowanie wielu dokumentów oraz wyszukiwanie wektorowe. NextPDF nie publikuje tutaj stałego mnożnika przepustowości; zyski zależą od mieszanki dokumentów, gęstości obrazów, liczby rdzeni sidecara oraz rozmiaru wsadu. Zmierz w swoim środowisku, zanim oprzesz się na konkretnej liczbie. Rozwiązanie zastępcze PHP jest z założenia jednowątkowe.

Uwagi dotyczące bezpieczeństwa

Ten moduł wysyła dokumenty i wektory do współlokowanego sidecara po jego skonfigurowanym transporcie. Traktuj sidecar jako część swojej granicy zaufania i wdróż go na tym samym hoście lub w prywatnym segmencie sieci. Moduł waliduje rozmiar i kształt wejścia przed rozesłaniem. Nie loguje żadnej treści dokumentu.

Zgodność

Ten moduł sam nie wykonuje żadnej pracy nad zgodnością formatu; deleguje optymalizację i porównywanie do modułów Pro Optimizer oraz Diff. Odniesienia do ISO 32000-2 znajdziesz w tych modułach. Dowody zgodności dla tej strony pochodzą z udokumentowanych publicznych kontraktów klas oraz ich testów jednostkowych; korpus RAG był niedostępny w czasie tworzenia, więc nie deklaruje się tutaj żadnych zewnętrznych identyfikatorów klauzul.

Uwaga o granicy Enterprise

Enterprise nie zmienia zachowania Accelerator. Enterprise dodaje wyższego poziomu funkcje zgodności, archiwizacji oraz cyklu życia podpisu udokumentowane gdzie indziej; są one poza zakresem tego modułu i nie są wymagane do korzystania z Accelerator.

Rozwiązanie zastępcze Core / alternatywa

Bez Pro skorzystaj z działającej w procesie optymalizacji i porównywania NextPDF Core. Przyspieszone ścieżki w tym module sprowadzają się do tego samego zachowania PHP, gdy sidecar jest nieobecny.

Granica publikacji

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