Enterprise phiên bản

Accelerator — Tài liệu tham chiếu chuyên sâu (GPU sidecar, KMS provider factory)

Tổng quan nhanh

Trang này là tài liệu tham chiếu sâu cho bề mặt tăng tốc công khai của NextPDF\Enterprise\Accelerator. Nó bao quát ngăn xếp KMS provider — factory, contract của provider, provider cục bộ, và key-metadata result — cùng các dịch vụ GPU sidecar cho embedding và vector search. Nó nêu các tham số, giá trị mặc định, các chế độ thất bại, và lập trường về việc giám hộ khóa. Hãy đọc trang khả năng Accelerator trước để có hướng dẫn quy trình. Các ký hiệu khác trong cùng namespace thuộc về các khả năng khác và nằm ngoài phạm vi của trang này.

Tính khả dụng và cấp phép

Khả năng này được phát hành trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt bằng một license envelope bậc Enterprise. Một triển khai không có quyền đó sẽ không nạp các class của khả năng này. So sánh các phiên bản và lấy giấy phép.

KMS provider được chọn tại runtime; mã gọi phụ thuộc vào contract của provider, không phải provider cụ thể. Các dịch vụ embedding và vector-index hiện thực các contract EmbeddingServiceInterface và VectorIndexInterface của Core.

Bề mặt Public API

composer require nextpdf/enterprise:^3

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném ra hoặc thất bại với	Ghi chú
`KmsProviderFactory::fromEnvironment`	không có	Dựng provider được đặt tên bởi biến selector; chưa đặt hoặc rỗng sẽ chọn `local`	`KmsProviderInterface`	`RuntimeException` khi thiếu root key, cloud provider không khả dụng, hoặc tên không xác định	Điểm vào tĩnh
`KmsProviderFactory::create`	`string $providerType`, `array $config = []`	Dựng provider được đặt tên từ cấu hình tường minh	`KmsProviderInterface`	`RuntimeException` khi `local` thiếu `encryption_key` không rỗng, hoặc khi tên không xác định	`local` là tên duy nhất có thể dựng trong bản phát hành này
`KmsProviderInterface::getEncryptionKey`	`string $collectionId`	Trả về key metadata hiện tại cho collection	`EncryptionKeyResult`	`RuntimeException` khi provider không thể tiếp cận hoặc cấu hình sai (contract)	Chỉ metadata; không bao giờ có byte khóa thô
`KmsProviderInterface::rotateKey`	`string $collectionId`	Nâng phiên bản khóa	`EncryptionKeyResult`	`RuntimeException` khi xoay khóa thất bại (contract)	Xoay khóa là một tín hiệu mã hóa lại gửi tới người gọi
`KmsProviderInterface::providerName`	không có	Báo cáo tên provider chuẩn tắc	`string`	Không khai báo gì	`local`, `aws`, `gcp`, `azure`, `vault`
`LocalKmsProvider::__construct`	`string $encryptionKey` (nhạy cảm)	Kiểm định một hex root key có ít nhất 64 ký tự hex (32 byte)	`LocalKmsProvider`	`InvalidArgumentException` khi giá trị quá ngắn hoặc không phải hex	Guard fail-fast; tự nó không thực hiện dẫn xuất
`LocalKmsProvider::getEncryptionKey`	`string $collectionId`	Tạo ra `local:{collectionId}:v{version}`; version mặc định là 1	`EncryptionKeyResult`	Không khai báo gì	Nhãn thuật toán `AES-256-GCM`
`LocalKmsProvider::rotateKey`	`string $collectionId`	Tăng bộ đếm version trong tiến trình	`EncryptionKeyResult`	Không khai báo gì	Trạng thái version theo từng instance
`EncryptionKeyResult::__construct`	`string $keyId`, `int $keyVersion`, `string $algorithm = 'AES-256-GCM'`, `string $provider = 'local'`	Đối tượng giá trị metadata bất biến	`EncryptionKeyResult`	Không khai báo gì	Không bao giờ mang vật liệu khóa
`GpuEmbeddingService::embed`	`string $text`	Ủy thác cho `batchEmbed` và trả về phần tử thứ không	`list<float>`	Như `batchEmbed`	Vector 1024 chiều
`GpuEmbeddingService::batchEmbed`	`array $texts`	Nhúng cả batch trên sidecar	`list<list<float>>`	`InvalidArgumentException` khi batch rỗng; `SpectrumNotAvailableException` khi sidecar không thể tiếp cận; `SpectrumApiException` khi response thất bại, dị dạng, hoặc sai số lượng	Không bao giờ trả về kết quả một phần
`GpuEmbeddingService::getDimension`	không có	Trả về `1024`	`int`	Không khai báo gì	Hằng số
`GpuEmbeddingService::getModelName`	không có	Trả về `multilingual-e5-large`	`string`	Không khai báo gì	Hằng số
`GpuVectorIndex::__construct`	`SpectrumClient $client`, `string $collectionId = 'default'`	Gắn handle với một collection	`GpuVectorIndex`	Không khai báo gì	Một handle cho mỗi định danh collection
`GpuVectorIndex::build`	`array $vectors`, `array $ids`	Dựng chỉ mục collection trên sidecar	`void`	`InvalidArgumentException` khi batch rỗng hoặc độ dài không khớp; `SpectrumNotAvailableException` khi không thể tiếp cận; `SpectrumApiException` khi response build ngoài mong đợi	Một lần dựng lại sẽ thay thế chỉ mục
`GpuVectorIndex::search`	`array $queryVector`, `int $topK = 10`	Tìm kiếm lân cận gần nhất có xếp hạng	`list<VectorSearchResult>`	`SpectrumNotAvailableException` khi không thể tiếp cận; `JsonException` khi thân response dị dạng	Xếp hạng theo từng hit trong metadata kết quả
`GpuVectorIndex::delete`	`array $ids`	Luôn từ chối	`void` (khai báo)	Luôn luôn: `SpectrumApiException` (chưa hiện thực)	Chỉ mục đã dựng là bất biến; hãy dựng lại thay vì xóa
`GpuVectorIndex::count`	không có	Đọc tổng số của collection từ sidecar	`int`	Không ném; mọi thất bại đều trả về `0`	`0` là nhập nhằng: rỗng hoặc không thể tiếp cận

Chữ ký các điểm vào

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
}

Bề mặt cấu hình

Thiết lập	Bên tiêu thụ	Ý nghĩa
`SPECTRUM_KMS_PROVIDER`	`fromEnvironment()`	Bộ chọn provider. Chưa đặt hoặc rỗng sẽ phân giải thành `local`.
`SPECTRUM_ENCRYPTION_KEY`	Đường dẫn provider `local`	Root key mã hóa hex; ít nhất 64 ký tự hex (32 byte). Chia sẻ với sidecar.
`encryption_key`	`create('local', [...])`	Root key tường minh; cùng định dạng và kiểm định.

Contract hành vi

Chọn provider

KmsProviderFactory::fromEnvironment đọc biến selector và mặc định là local. Các tên cloud provider aws, gcp, azure, và vault được nhận diện nhưng không thể dựng trong bản phát hành này. Chọn aws sẽ làm phát sinh một lỗi có kiểu nêu tên gói aws/aws-sdk-php cần thiết; ba tên còn lại báo cáo tích hợp là chưa hiện thực. Một tên không xác định sẽ làm phát sinh một lỗi có kiểu liệt kê các tên được hỗ trợ. KmsProviderFactory::create chấp nhận một tên provider tường minh và một configuration map; local là tên duy nhất mà nó dựng.

Key metadata và giám hộ

Một provider trả về key metadata bất biến: một định danh khóa, một phiên bản khóa tăng đơn điệu, nhãn thuật toán, và tên provider. Nó không bao giờ trả về các byte khóa thô, nên một rò rỉ metadata không để lộ vật liệu khóa. Provider cục bộ phân chia nhiệm vụ với accelerator sidecar. Class PHP kiểm định bí mật khóa chủ lúc khởi tạo và tạo ra một danh tính khóa ổn định, theo phạm vi collection, có dạng local:{collectionId}:v{version}. Sidecar thực hiện dẫn xuất HKDF-SHA256 và mã hóa AES-256-GCM, dẫn xuất một khóa mã hóa dữ liệu 32 byte riêng biệt cho mỗi collection với định danh collection và phiên bản làm bộ tách miền. Cả hai bên đều đọc cùng một bí mật khóa chủ đã cấu hình. Không có dịch vụ KMS bên ngoài nào được liên hệ; việc xử lý khóa nằm bên trong triển khai. Phiên bản khóa và mô hình vòng đời tuân theo NIST SP 800-57 Part 1 Rev.5 §4.

Một lời gọi xoay khóa nâng phiên bản khóa và trả về metadata mới. Người gọi mã hóa lại dữ liệu collection bằng phiên bản mới; bản thân provider không mã hóa lại gì cả.

Tính bảo mật của khóa phụ thuộc vào KMS hoặc bí mật khóa chủ, vào triển khai, và vào người vận hành — không phải vào riêng NextPDF Enterprise. Người vận hành sở hữu việc cấp phát khóa chủ, lưu trữ bí mật, cấu hình KMS, và lập lịch xoay khóa. Trách nhiệm bảo vệ khóa tuân theo NIST SP 800-57 Part 1 Rev.5 §5.5.2.

GPU embedding

GpuEmbeddingService hiện thực contract embedding của Core và ủy thác cho sidecar. Sidecar chạy mô hình embedding trên một GPU khi có sẵn và dự phòng về CPU nếu không, đánh dấu metadata của response là suy giảm so với GPU. Hình dạng vector giống nhau trong cả hai trường hợp. Mô hình (khoảng 1.3 GB) được tải xuống và nạp một cách lười biếng ở request đầu tiên. Ngữ nghĩa batch là tất-cả-hoặc-không: một thất bại theo từng phần tử, một vector dị dạng, hoặc một sai số lượng sẽ làm phát sinh một lỗi có kiểu thay vì trả về kết quả một phần.

GPU vector search

GpuVectorIndex hiện thực contract vector-index của Core và gắn một handle với một định danh collection. build dựng chỉ mục trên sidecar; sidecar dùng một chỉ mục GPU khi có sẵn và một chỉ mục CPU nếu không. Chỉ mục là bất biến một khi đã dựng: delete luôn từ chối bằng một lỗi có kiểu chưa-hiện-thực, và việc xóa yêu cầu dựng lại. search trả về các hit có xếp hạng với một thứ hạng bắt đầu từ một trong metadata của mỗi kết quả. count hỏi sidecar về tổng số của collection và báo cáo 0 khi có bất kỳ thất bại nào thay vì ném lỗi.

Trường hợp biên và các chế độ thất bại

Root key phải giải mã từ hex ra ít nhất 32 byte. Một giá trị ngắn hơn hoặc không phải hex sẽ làm phát sinh InvalidArgumentException lúc khởi tạo, trước bất kỳ lời gọi sidecar nào.
Một biến selector chưa đặt hoặc rỗng sẽ phân giải thành local; factory không bao giờ đoán một provider khác.
fromEnvironment trên đường dẫn local mà thiếu biến root-key sẽ làm phát sinh một lỗi có kiểu nêu tên biến còn thiếu.
create('local', [...]) mà thiếu một mục encryption_key không rỗng sẽ làm phát sinh một lỗi có kiểu nêu tên mục còn thiếu.
Trạng thái phiên bản khóa nằm trong tiến trình và theo từng instance provider. Một tiến trình mới quan sát thấy version 1 cho đến khi xoay khóa chạy lại. Hãy lưu bền kết quả xoay khóa bằng cách mã hóa lại dữ liệu, không phải bằng cách tin vào trạng thái của provider.
Một batch embedding rỗng sẽ làm phát sinh InvalidArgumentException; sidecar không được liên hệ.
Tính khả dụng của sidecar được thăm dò theo từng lời gọi. Một sidecar không thể tiếp cận sẽ làm phát sinh SpectrumNotAvailableException; các dịch vụ không bao giờ thất bại âm thầm.
Một thành phần không phải số bên trong một vector embedding trả về sẽ bị ép thành 0.0; một vector thiếu hoặc không phải mảng sẽ làm phát sinh SpectrumApiException.
Request embedding đầu tiên phải trả chi phí tải xuống và nạp mô hình một lần; hãy định cỡ timeout đó riêng.
build và search giải mã response của sidecar một cách nghiêm ngặt; một thân dị dạng sẽ làm phát sinh JsonException. count nuốt mọi thất bại và trả về 0.
Một hit tìm kiếm thiếu định danh hoặc điểm số sẽ mặc định thành một chuỗi rỗng và 0.0 thay vì làm hỏng cả batch.
Các mã lỗi của sidecar và phân cấp exception được liệt kê trong tài liệu tham chiếu lỗi Accelerator.

Hành vi ở FIPS-mode

Đường dẫn khóa cục bộ dùng HKDF-SHA256 cho dẫn xuất và AES-256-GCM cho mã hóa; sidecar thực thi cả hai. Nhãn thuật toán được ghi trong key metadata là AES-256-GCM. Khi triển khai chạy với một provider mật mã được thẩm định FIPS, các primitive đó chạy trong ranh giới đã thẩm định đó. Việc dùng AES-GCM yêu cầu một initialization vector duy nhất cho mỗi khóa, theo NIST SP 800-38D §5.

NextPDF Enterprise không phải là một module mật mã được thẩm định FIPS và không đưa ra tuyên bố chứng nhận FIPS nào. Nó chỉ hoạt động ở một chế độ tương thích FIPS khi được cấu hình với một provider mật mã được thẩm định FIPS hoặc một KMS được thẩm định FIPS. Không có artifact chứng nhận FIPS nào tồn tại trong repository này.

Sự phù hợp

Tuyên bố	Tiêu chuẩn	Điều khoản
Phiên bản khóa và mô hình vòng đời tuân theo hướng dẫn về trạng thái khóa.	NIST SP 800-57 Part 1 Rev.5	§4
Trách nhiệm bảo vệ và giám hộ khóa thuộc về chủ sở hữu khóa và người vận hành.	NIST SP 800-57 Part 1 Rev.5	§5.5.2
AES-GCM yêu cầu một initialization vector duy nhất cho mỗi khóa.	NIST SP 800-38D	§5

Tất cả các điều khoản đều được diễn giải lại; NextPDF không tái hiện văn bản quy phạm. NextPDF không đưa ra tuyên bố chứng nhận nào. Sự tương thích với các điều khoản được trích dẫn là một tuyên bố về khả năng, không phải một chứng nhận. Trang này liên quan đến quản lý khóa; tuyên bố về FIPS-mode là một tuyên bố về tính tương thích, không phải một ý kiến pháp lý. Hãy tham vấn các cố vấn tuân thủ và pháp lý của riêng bạn.

Ghi chú phát triển

Mã nguồn module mang @since 2.1.0; tài liệu tham chiếu này mô tả bề mặt như được phát hành trong nextpdf/enterprise 3.1.0.
Tất cả các class đều là final; EncryptionKeyResult là final readonly. Hãy dựng các instance mới thay vì biến đổi tại chỗ.
Root key là một tham số khởi tạo nhạy cảm (#[SensitiveParameter]); PHP che nó khỏi các stack trace. Hãy giữ nó ngoài các log ứng dụng và các bản đổ cấu hình.
SpectrumClient, VectorSearchResult, cùng các contract EmbeddingServiceInterface và VectorIndexInterface đến từ NextPDF Core; người gọi dựng và cung cấp client sidecar.
Namespace NextPDF\Enterprise\Accelerator cũng mang các engine batch offload cùng các ngăn xếp retrieval-collection và trích xuất OCR; các bề mặt đó nằm ngoài phạm vi của trang này.
Chi tiết cơ chế nội bộ nằm trong tài liệu nội bộ của source repository và nằm ngoài phạm vi của cẩm nang này.

Ranh giới xuất bản

Trang này chỉ ghi lại hành vi có thể quan sát từ bên ngoài và bề mặt public API được hỗ trợ. Các đường dẫn namespace nội bộ, các class trợ giúp, các bảng cơ chế, tên tệp runbook, và tiền tố ticket nằm ngoài phạm vi.

Xem thêm

Accelerator — GPU sidecar và KMS provider factory — trang khả năng cho hướng dẫn quy trình và giám hộ.
Tài liệu tham chiếu lỗi Accelerator — phân cấp exception của sidecar và các mã lỗi.
Security — Tài liệu tham chiếu sâu
Accelerator — NextPDF Pro Tài liệu tham chiếu sâu