Accelerator — szczegółowa referencja (sidecar GPU, fabryka dostawców KMS)

W skrócie

Ta strona to szczegółowa referencja publicznej powierzchni akceleracji NextPDF\Enterprise\Accelerator. Obejmuje stos dostawców KMS — fabrykę, kontrakt dostawcy, dostawcę lokalnego oraz wynik z metadanymi klucza — a także usługi sidecara GPU do osadzania i wyszukiwania wektorowego. Podaje parametry, wartości domyślne, tryby awarii oraz stanowisko w sprawie pieczy nad kluczami. W celu uzyskania wskazówek dotyczących przepływu pracy przeczytaj najpierw stronę możliwości Accelerator. Pozostałe symbole w tej samej przestrzeni nazw należą do innych możliwości i są poza zakresem tej strony.

Dostępność i licencjonowanie

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

Dostawca KMS jest wybierany w czasie wykonywania; kod wywołujący zależy od kontraktu dostawcy, a nie od konkretnego dostawcy. Usługi osadzania i indeksu wektorowego implementują kontrakty Core EmbeddingServiceInterface oraz VectorIndexInterface.

Powierzchnia publicznego API

composer require nextpdf/enterprise:^3

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
KmsProviderFactory::fromEnvironment	brak	Buduje dostawcę wskazanego przez zmienną selektora; brak wartości lub pusta wartość wybiera local	KmsProviderInterface	RuntimeException przy braku klucza głównego, niedostępnym dostawcy chmurowym lub nieznanej nazwie	Statyczny punkt wejścia
KmsProviderFactory::create	string $providerType, array $config = []	Buduje wskazanego dostawcę na podstawie jawnej konfiguracji	KmsProviderInterface	RuntimeException, gdy local nie ma niepustego encryption_key, lub przy nieznanej nazwie	local to jedyna konstruowalna nazwa w tym wydaniu
KmsProviderInterface::getEncryptionKey	string $collectionId	Zwraca bieżące metadane klucza dla kolekcji	EncryptionKeyResult	RuntimeException, gdy dostawca jest nieosiągalny lub błędnie skonfigurowany (kontrakt)	Wyłącznie metadane; nigdy surowe bajty klucza
KmsProviderInterface::rotateKey	string $collectionId	Zwiększa wersję klucza	EncryptionKeyResult	RuntimeException, gdy rotacja się nie powiedzie (kontrakt)	Rotacja to sygnał ponownego szyfrowania dla wywołującego
KmsProviderInterface::providerName	brak	Zgłasza kanoniczną nazwę dostawcy	string	Nic nie zadeklarowano	local, aws, gcp, azure, vault
LocalKmsProvider::__construct	string $encryptionKey (wrażliwy)	Waliduje szesnastkowy klucz główny o długości co najmniej 64 znaków szesnastkowych (32 bajty)	LocalKmsProvider	InvalidArgumentException przy zbyt krótkiej lub nieszesnastkowej wartości	Zabezpieczenie fail-fast; samo nie wykonuje wyprowadzania
LocalKmsProvider::getEncryptionKey	string $collectionId	Tworzy local:{collectionId}:v{version}; wersja domyślnie wynosi 1	EncryptionKeyResult	Nic nie zadeklarowano	Etykieta algorytmu AES-256-GCM
LocalKmsProvider::rotateKey	string $collectionId	Zwiększa licznik wersji w procesie	EncryptionKeyResult	Nic nie zadeklarowano	Stan wersji jest właściwy dla instancji
EncryptionKeyResult::__construct	string $keyId, int $keyVersion, string $algorithm = 'AES-256-GCM', string $provider = 'local'	Niezmienny obiekt wartości metadanych	EncryptionKeyResult	Nic nie zadeklarowano	Nigdy nie przenosi materiału klucza
GpuEmbeddingService::embed	string $text	Deleguje do batchEmbed i zwraca element zerowy	list<float>	Jak batchEmbed	Wektor o wymiarze 1024
GpuEmbeddingService::batchEmbed	array $texts	Osadza partię w sidecarze	list<list<float>>	InvalidArgumentException przy pustej partii; SpectrumNotAvailableException, gdy sidecar jest nieosiągalny; SpectrumApiException przy nieudanej, zniekształconej lub niezgodnej co do liczby odpowiedzi	Nigdy nie zwraca wyników częściowych
GpuEmbeddingService::getDimension	brak	Zwraca 1024	int	Nic nie zadeklarowano	Stała
GpuEmbeddingService::getModelName	brak	Zwraca multilingual-e5-large	string	Nic nie zadeklarowano	Stała
GpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Wiąże uchwyt z jedną kolekcją	GpuVectorIndex	Nic nie zadeklarowano	Jeden uchwyt na identyfikator kolekcji
GpuVectorIndex::build	array $vectors, array $ids	Buduje indeks kolekcji w sidecarze	void	InvalidArgumentException przy pustej partii lub niezgodności długości; SpectrumNotAvailableException, gdy nieosiągalny; SpectrumApiException przy nieoczekiwanej odpowiedzi budowania	Przebudowa zastępuje indeks
GpuVectorIndex::search	array $queryVector, int $topK = 10	Rankingowe wyszukiwanie najbliższych sąsiadów	list<VectorSearchResult>	SpectrumNotAvailableException, gdy nieosiągalny; JsonException przy zniekształconym ciele odpowiedzi	Ranking każdego trafienia w metadanych wyniku
GpuVectorIndex::delete	array $ids	Zawsze odrzuca	void (zadeklarowane)	Zawsze: SpectrumApiException (niezaimplementowane)	Zbudowany indeks jest niezmienny; zamiast tego przebuduj
GpuVectorIndex::count	brak	Odczytuje sumę kolekcji z sidecara	int	Nie zgłasza wyjątku; każda awaria zwraca 0	0 jest niejednoznaczne: pusty lub nieosiągalny

Sygnatury punktów wejścia

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
}

Powierzchnia konfiguracji

Ustawienie	Konsument	Znaczenie
SPECTRUM_KMS_PROVIDER	fromEnvironment()	Selektor dostawcy. Brak wartości lub pusta wartość rozwiązuje się do local.
SPECTRUM_ENCRYPTION_KEY	Ścieżka dostawcy local	Klucz główny zakodowany szesnastkowo; co najmniej 64 znaki szesnastkowe (32 bajty). Współdzielony z sidecarem.
encryption_key	create('local', [...])	Jawny klucz główny; ten sam format i walidacja.

Kontrakt zachowania

Wybór dostawcy

KmsProviderFactory::fromEnvironment odczytuje zmienną selektora i domyślnie przyjmuje local. Nazwy dostawców chmurowych aws, gcp, azure oraz vault są rozpoznawane, ale nie są konstruowalne w tym wydaniu. Wybranie aws zgłasza typowany błąd wskazujący wymagany pakiet aws/aws-sdk-php; pozostałe trzy zgłaszają integrację jako niezaimplementowaną. Nieznana nazwa zgłasza typowany błąd wymieniający obsługiwane nazwy. KmsProviderFactory::create przyjmuje jawną nazwę dostawcy oraz mapę konfiguracji; local to jedyna nazwa, którą konstruuje.

Metadane klucza i piecza

Dostawca zwraca niezmienne metadane klucza: identyfikator klucza, monotonicznie rosnącą wersję klucza, etykietę algorytmu oraz nazwę dostawcy. Nigdy nie zwraca surowych bajtów klucza, więc wyciek metadanych nie ujawnia materiału klucza. Dostawca lokalny dzieli obowiązki z sidecarem akceleratora. Klasa PHP waliduje sekret główny przy konstrukcji i tworzy stabilną, właściwą dla kolekcji tożsamość klucza w postaci local:{collectionId}:v{version}. Sidecar wykonuje wyprowadzanie HKDF-SHA256 oraz szyfrowanie AES-256-GCM, wyprowadzając odrębny 32-bajtowy klucz szyfrowania danych dla każdej kolekcji, przy czym identyfikator kolekcji i wersja pełnią rolę separacji domen. Obie strony odczytują ten sam skonfigurowany sekret główny. Nie następuje kontakt z żadną zewnętrzną usługą KMS; obsługa klucza pozostaje wewnątrz wdrożenia. Wersja klucza oraz model cyklu życia są zgodne z NIST SP 800-57 Part 1 Rev.5 §4.

Wywołanie rotacji zwiększa wersję klucza i zwraca nowe metadane. Wywołujący ponownie szyfruje dane kolekcji nową wersją; dostawca sam niczego ponownie nie szyfruje.

Bezpieczeństwo klucza zależy od KMS lub sekretu klucza głównego, od wdrożenia oraz od operatora — a nie wyłącznie od NextPDF Enterprise. Operator odpowiada za udostępnianie klucza głównego, przechowywanie sekretów, konfigurację KMS oraz harmonogram rotacji. Odpowiedzialność za ochronę kluczy jest zgodna z NIST SP 800-57 Part 1 Rev.5 §5.5.2.

Osadzanie GPU

GpuEmbeddingService implementuje kontrakt osadzania Core i deleguje do sidecara. Sidecar uruchamia model osadzania na GPU, gdy jest ono dostępne, a w przeciwnym razie przechodzi na CPU, oznaczając metadane odpowiedzi jako zdegradowane względem GPU. Kształt wektora jest identyczny w obu przypadkach. Model (około 1,3 GB) jest pobierany i wczytywany leniwie przy pierwszym żądaniu. Semantyka partii jest „wszystko albo nic”: awaria pojedynczego elementu, zniekształcony wektor lub niezgodność liczby zgłasza typowany błąd zamiast zwracać wyniki częściowe.

Wyszukiwanie wektorowe GPU

GpuVectorIndex implementuje kontrakt indeksu wektorowego Core i wiąże jeden uchwyt z jednym identyfikatorem kolekcji. build konstruuje indeks w sidecarze; sidecar używa indeksu GPU, gdy jest on dostępny, a w przeciwnym razie indeksu CPU. Po zbudowaniu indeks jest niezmienny: delete zawsze odrzuca typowanym błędem „niezaimplementowane”, a usunięcie wymaga przebudowy. search zwraca trafienia z rankingiem, z rankingiem liczonym od jedynki w metadanych każdego wyniku. count pyta sidecar o sumę kolekcji i przy każdej awarii zgłasza 0 zamiast wyjątku.

Przypadki brzegowe i tryby awarii

• Klucz główny musi dekodować się z postaci szesnastkowej do co najmniej 32 bajtów. Krótsza lub nieszesnastkowa wartość zgłasza InvalidArgumentException przy konstrukcji, przed jakimkolwiek wywołaniem sidecara.
• Brak wartości lub pusta zmienna selektora rozwiązuje się do local; fabryka nigdy nie zgaduje innego dostawcy.
• fromEnvironment na ścieżce local bez zmiennej z kluczem głównym zgłasza typowany błąd wskazujący brakującą zmienną.
• create('local', [...]) bez niepustego wpisu encryption_key zgłasza typowany błąd wskazujący brakujący wpis.
• Stan wersji klucza jest w procesie i właściwy dla instancji dostawcy. Nowy proces obserwuje wersję 1, dopóki rotacja nie zostanie ponownie uruchomiona. Utrwalaj wyniki rotacji przez ponowne szyfrowanie danych, a nie przez zaufanie stanowi dostawcy.
• Pusta partia osadzania zgłasza InvalidArgumentException; nie następuje kontakt z sidecarem.
• Dostępność sidecara jest sprawdzana przy każdym wywołaniu. Nieosiągalny sidecar zgłasza SpectrumNotAvailableException; usługi nigdy nie zawodzą po cichu.
• Nienumeryczny składnik zwróconego wektora osadzania jest wymuszany na 0.0; brakujący lub nietablicowy wektor zgłasza SpectrumApiException.
• Pierwsze żądanie osadzania ponosi jednorazowy koszt pobrania i wczytania modelu; wymiaruj ten limit czasu osobno.
• build i search dekodują odpowiedź sidecara rygorystycznie; zniekształcone ciało zgłasza JsonException. count pochłania każdą awarię i zwraca 0.
• Trafienie wyszukiwania bez identyfikatora lub oceny domyślnie przyjmuje pusty ciąg i 0.0 zamiast zawieść partię.
• Kody błędów sidecara oraz hierarchia wyjątków są skatalogowane w referencji błędów Accelerator.

Zachowanie w trybie FIPS

Lokalna ścieżka klucza używa HKDF-SHA256 do wyprowadzania oraz AES-256-GCM do szyfrowania; sidecar wykonuje oba. Etykieta algorytmu zapisana w metadanych klucza to AES-256-GCM. Gdy wdrożenie działa z dostawcą kryptograficznym zwalidowanym zgodnie z FIPS, te prymitywy działają w tej zwalidowanej granicy. Użycie AES-GCM wymaga unikatowego wektora inicjującego dla każdego klucza, zgodnie z NIST SP 800-38D §5.

NextPDF Enterprise nie jest modułem kryptograficznym zwalidowanym zgodnie z FIPS i nie wysuwa żadnej deklaracji certyfikacji FIPS. Działa w trybie zgodnym z FIPS wyłącznie wtedy, gdy jest skonfigurowany z dostawcą kryptograficznym zwalidowanym zgodnie z FIPS lub z KMS zwalidowanym zgodnie z FIPS. W tym repozytorium nie istnieje żaden artefakt certyfikacji FIPS.

Zgodność

Deklaracja	Standard	Klauzula
Wersja klucza oraz model cyklu życia są zgodne z wytycznymi dotyczącymi stanów klucza.	NIST SP 800-57 Part 1 Rev.5	§4
Odpowiedzialność za ochronę klucza oraz pieczę spoczywa na właścicielu klucza i operatorze.	NIST SP 800-57 Part 1 Rev.5	§5.5.2
AES-GCM wymaga unikatowego wektora inicjującego dla każdego klucza.	NIST SP 800-38D	§5

Wszystkie klauzule są parafrazowane; NextPDF nie odtwarza tekstu normatywnego. NextPDF nie wysuwa żadnej deklaracji certyfikacji. Zgodność z przywołanymi klauzulami jest deklaracją możliwości, a nie certyfikacją. Ta strona dotyczy zarządzania kluczami; stwierdzenie o trybie FIPS jest stwierdzeniem o zgodności, a nie opinią prawną. Skonsultuj się z własnymi doradcami ds. zgodności i prawnymi.

Uwagi programistyczne

• Źródło modułu zawiera @since 2.1.0; ta referencja dokumentuje powierzchnię w postaci dostarczonej w nextpdf/enterprise 3.1.0.
• Wszystkie klasy są final; EncryptionKeyResult jest final readonly. Konstruuj nowe instancje zamiast mutować.
• Klucz główny to wrażliwy parametr konstruktora (#[SensitiveParameter]); PHP redaguje go w śladach stosu. Trzymaj go z dala od dzienników aplikacji i zrzutów konfiguracji.
• SpectrumClient, VectorSearchResult oraz kontrakty EmbeddingServiceInterface i VectorIndexInterface pochodzą z NextPDF Core; wywołujący konstruuje i dostarcza klienta sidecara.
• Przestrzeń nazw NextPDF\Enterprise\Accelerator zawiera również silniki odciążania wsadowego oraz stosy kolekcji wyszukiwania i ekstrakcji OCR; te powierzchnie są poza zakresem tej strony.
• 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 oraz obsługiwaną 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 też

• Accelerator — sidecar GPU i fabryka dostawców KMS — strona możliwości z wskazówkami dotyczącymi przepływu pracy i pieczy.
• Referencja błędów Accelerator — hierarchia wyjątków sidecara i kody błędów.
• Security — szczegółowa referencja
• Accelerator — szczegółowa referencja NextPDF Pro