Accelerator — GPU sidecar và KMS provider factory

Tổng quan nhanh

NextPDF Enterprise bổ sung hai tính năng tăng tốc: một sidecar GPU cho việc embedding văn bản kèm phương án dự phòng CPU, và một KMS provider factory cung cấp siêu dữ liệu và việc xoay vòng khóa mã hóa dữ liệu ở cấp collection. Trang này nêu hành vi, các ranh giới, và lập trường về lưu giữ khóa.

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

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

Tổng quan khái niệm

Sidecar GPU tăng tốc việc embedding từ văn bản sang vector. Gói Enterprise gửi văn bản tới một tiến trình sidecar riêng qua một yêu cầu HTTP cục bộ. Sidecar chạy mô hình embedding trên một GPU khi có sẵn. Khi không có GPU, sidecar chạy cùng mô hình đó trên CPU và báo cáo rằng nó đã chạy ở chế độ suy giảm. Kết quả là cùng một hình dạng vector trong cả hai trường hợp. Mô hình embedding được nạp ở yêu cầu đầu tiên, nên yêu cầu đầu tiên chậm hơn các yêu cầu sau. Sidecar là tùy chọn; có một bước kiểm tra tính khả dụng được phơi bày, và một sidecar thiếu sẽ phát sinh một ngoại lệ có kiểu thay vì một lỗi âm thầm.

KMS provider factory chọn một nhà cung cấp quản lý khóa từ cấu hình. Factory đọc một biến môi trường để chọn provider. Provider mặc định suy dẫn một khóa mã hóa dữ liệu riêng cho từng collection ngay tại chỗ bằng HKDF-SHA256 từ một khóa chủ đã cấu hình, với mã định danh collection làm dấu phân tách miền. Provider cục bộ không liên hệ dịch vụ bên ngoài nào; việc suy dẫn là tất định và trong tiến trình. Factory cũng chấp nhận một dạng cấu hình tường minh cho provider cục bộ. Các nhà cung cấp đám mây — AWS KMS, GCP Cloud KMS, Azure Key Vault, và HashiCorp Vault Transit — là những tên provider được nhận diện; việc chọn một nhà cung cấp mà chưa cài tích hợp tương ứng sẽ phát sinh một lỗi cấu hình có kiểu nêu tên phần phụ thuộc còn thiếu.

Một provider trả về siêu dữ liệu khóa, không phải byte khóa thô. Siêu dữ liệu ghi lại mã định danh khóa, một phiên bản khóa tăng đơn điệu, tên thuật toán mã hóa, và tên provider. Một lệnh gọi xoay vòng sẽ nâng phiên bản khóa và trả về siêu dữ liệu mới. Bên gọi chịu trách nhiệm mã hóa lại dữ liệu collection bằng phiên bản khóa mới sau một lần xoay vòng. Phiên bản khóa và vòng đời xoay vòng tuân theo NIST SP 800-57 Part 1 Rev.5 §4.

Vì sao nó hoạt động theo cách này

Việc embedding chạy trong một tiến trình sidecar GPU riêng thay vì bên trong yêu cầu PHP. Việc nạp mô hình GPU tốn kém, nên sidecar nạp mô hình một lần và phân bổ chi phí đó qua nhiều yêu cầu. Khi không có GPU, sidecar chạy cùng mô hình đó trên CPU và báo cáo một chế độ suy giảm. Thông lượng có thể giảm, nhưng tính đúng đắn thì không: hình dạng vector là giống hệt nhau trong cả hai trường hợp. Sidecar vẫn là tùy chọn; một bước kiểm tra tính khả dụng và một ngoại lệ có kiểu khi thiếu sidecar giữ cho việc tăng tốc là một lựa chọn tham gia có chủ ý, không phải một phần phụ thuộc ẩn. Sự tách biệt đó cho phép việc embedding khối lượng lớn mở rộng trên phần cứng chuyên dụng trong khi pipeline tài liệu vẫn chỉ là một lệnh gọi PHP thuần túy.

Bối cảnh thiết kế: Tạo tài liệu khối lượng lớn.

Bề mặt API

Bề mặt công khai	Loại	Mục đích	Độ ổn định	Từ
KMS provider factory	class	Dựng một KMS provider từ môi trường hoặc cấu hình tường minh	ổn định	2.1.0
KMS provider	interface	Lấy siêu dữ liệu khóa, xoay vòng một khóa, và báo cáo tên provider	ổn định	2.1.0
Local KMS provider	class (triển khai provider interface)	Suy dẫn khóa cục bộ HKDF-SHA256; không liên hệ dịch vụ bên ngoài nào	ổn định	2.1.0
Encryption-key result	value object	Siêu dữ liệu khóa bất biến: key id, version, algorithm, provider — không có byte khóa thô	ổn định	2.1.0
GPU embedding service	class (triển khai Core embedding-service interface)	Embedding văn bản trên một sidecar GPU kèm phương án dự phòng CPU	ổn định	2.1.0

Provider factory phơi bày một điểm vào “from environment” và một điểm vào “create” tường minh. Giá trị cấu hình khóa chủ được đánh dấu là nhạy cảm trong provider cục bộ. Hợp đồng tham số và kiểu mang tính thẩm quyền là tài liệu tham chiếu API đã xuất bản cho gói nextpdf/enterprise; hãy coi tài liệu tham chiếu đó — không phải trang này — là hợp đồng.

Mẫu mã — Bắt đầu nhanh

composer require nextpdf/core
composer require nextpdf/enterprise:^3

Build the local KMS provider and read key metadata

use NextPDF\Enterprise\Accelerator\KmsProviderFactory;

// Selects the provider from environment configuration; defaults to the
// local HKDF-based provider. Supply the root key through your secret
// manager, never from source or logs.
$provider = KmsProviderFactory::fromEnvironment();

$key = $provider->getEncryptionKey('collection-1');
// $key is metadata only: key id, version, algorithm, provider name.

Mẫu mã — Sản phẩm

Rotate a collection key, then re-encrypt collection data

use NextPDF\Enterprise\Accelerator\KmsProviderFactory;

$provider = KmsProviderFactory::fromEnvironment();

$rotated = $provider->rotateKey('collection-1');
// The version advanced. Re-encrypt the collection's data files with the
// new key version. The provider returns metadata only; it never returns
// raw key bytes.

Tên các biến môi trường, các khóa cấu hình tường minh, và các kiểu ngoại lệ được ghi trong tài liệu tham chiếu chuyên sâu Accelerator.

Trường hợp biên & điều cần lưu ý

• Local KMS provider yêu cầu một khóa chủ mã hóa dạng hex dài ít nhất 32 byte. Một giá trị ngắn hơn hoặc không phải hex sẽ phát sinh một ngoại lệ đối số có kiểu lúc khởi tạo.
• Việc chọn một tên nhà cung cấp đám mây mà chưa cài tích hợp tương ứng sẽ phát sinh một lỗi cấu hình có kiểu nêu tên phần phụ thuộc còn thiếu.
• Một tên provider không xác định sẽ phát sinh một lỗi có kiểu liệt kê các tên được hỗ trợ.
• Sidecar GPU báo cáo một chế độ suy giảm khi nó chuyển sang dùng CPU. Hãy kiểm tra trường đó nếu bạn phụ thuộc vào thông lượng GPU.
• Mô hình embedding được nạp ở yêu cầu đầu tiên; hãy định kích thước thời gian chờ của yêu cầu đầu tiên cho phù hợp.

Hiệu năng

Việc suy dẫn khóa cục bộ là một thao tác HKDF có chi phí không đổi. Nó không liên hệ dịch vụ bên ngoài nào. Một yêu cầu embedding GPU bổ sung một lượt khứ hồi cục bộ tới sidecar cộng với thời gian suy luận của mô hình. Yêu cầu đầu tiên cũng phải trả chi phí nạp mô hình một lần. Phương án dự phòng CPU cho kết quả đúng nhưng chậm hơn đường GPU với cùng một batch.

Lưu ý bảo mật

• Một KMS provider trả về siêu dữ liệu khóa, không phải byte khóa thô. Value object encryption-key result không bao giờ mang theo tài liệu khóa.
• Khóa chủ của provider cục bộ là một tham số khởi tạo nhạy cảm. Nó không được ghi nhật ký và không được tuần tự hóa.
• Provider cục bộ không liên hệ dịch vụ bên ngoài nào. Việc suy dẫn là tất định và trong tiến trì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.

Lưu trú dữ liệu & biện pháp giảm thiểu PII

Local KMS provider chạy trong tiến trình và không liên hệ dịch vụ bên ngoài nào; không có tài liệu khóa và không có nội dung tài liệu nào rời khỏi máy chủ cho việc suy dẫn khóa cục bộ. Sidecar GPU nhận văn bản cần embedding qua một yêu cầu cục bộ; nó không nhận nội dung tài liệu không liên quan. Một cloud KMS provider, khi được cấu hình, sẽ liên hệ nhà cung cấp đám mây mà bạn chọn; hãy rà soát lập trường lưu trú dữ liệu của nhà cung cấp đó cho khu vực pháp lý của bạn.

Đo từ xa an toàn & làm sạch nhật ký

Khóa chủ của provider cục bộ là một tham số khởi tạo nhạy cảm và bị loại khỏi nhật ký lẫn việc tuần tự hóa. Đừng thêm khóa chủ, các khóa được suy dẫn, hay thông tin xác thực provider vào nhật ký ứng dụng của riêng bạn. Hãy coi mọi tài liệu khóa là một bí mật trong chính sách ghi nhật ký và truy vết của bạn.

Mô hình mối đe dọa

Provider trả về siêu dữ liệu, không phải byte khóa, nên một lần rò rỉ siêu dữ liệu không làm lộ tài liệu khóa. Tính bảo mật của provider cục bộ phụ thuộc vào việc giữ bí mật khóa chủ đã cấu hình. Tính bảo mật của một cloud provider phụ thuộc vào nhà cung cấp đó và vào cấu hình của bạn. Việc bảo vệ khóa phụ thuộc vào KMS hoặc bí mật khóa chủ, vào lần triển khai, và vào người vận hành — không chỉ phụ thuộc vào riêng phần mềm này. Xem ranh giới triển khai.

Tính phù hợp

• Phiên bản khóa mã hóa dữ liệu và vòng đời xoay vòng căn chỉnh theo NIST SP 800-57 Part 1 Rev.5 §4.
• Trách nhiệm bảo vệ khóa căn chỉnh theo NIST SP 800-57 Part 1 Rev.5 §5.5.2.
• Tính duy nhất của initialization vector AES-GCM căn chỉnh theo NIST SP 800-38D §5.

Mọi nguồn quy phạm đều được diễn giải lại. Không có văn bản quy phạm nào được sao chép nguyên văn trên trang này. Trang này liên quan đến quản lý khóa.

Hành vi ở chế độ FIPS

Việc suy dẫn HKDF của provider cục bộ dùng SHA-256. Thuật toán mã hóa được ghi trong siêu dữ liệu khóa là AES-256-GCM. Khi ứng dụng chạy với một nhà cung cấp mã hóa được thẩm định theo FIPS, các nguyên hàm đó chạy trong ranh giới đã thẩm định ấy. Bản thân provider factory chỉ chọn và dựng provider; nó không chứng nhận ranh giới mã hóa.

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

Ranh giới phiên bản

Sidecar embedding GPU và KMS provider factory chỉ đi kèm trong gói nextpdf/enterprise. NextPDF Pro cung cấp tích hợp KMS cho các chiến lược ký (AWS KMS, GCP Cloud KMS, Azure Key Vault) nhưng không cung cấp KMS provider factory của Enterprise hay sidecar embedding GPU. Lớp truyền tải sidecar nội bộ và các lớp pipeline embedding nội bộ nằm ngoài phạm vi của bề mặt công khai và không được tái hiện ở đây.

Phương án dự phòng Pro

NextPDF Pro cung cấp các chiến lược ký bằng cloud-KMS — KMS giữ khóa ký, còn Pro gửi digest của các thuộc tính đã ký tới provider. Đó là một tích hợp ký. Nó không phải là KMS provider factory cho khóa mã hóa dữ liệu ở cấp collection của Enterprise và cũng không phải sidecar embedding GPU. Xem Accelerator — NextPDF Pro để biết bề mặt tăng tốc của Pro.

Phương án dự phòng Core

NextPDF Core không có sidecar embedding GPU và không có KMS provider factory. Embedding và quản lý khóa ở cấp collection là các tính năng chỉ dành cho Enterprise.

Lưu ý về ranh giới Enterprise

Lớp truyền tải sidecar GPU, mã định danh mô hình embedding, và các lớp pipeline nội bộ chỉ được mô tả ở mức hành vi. Client truyền tải nội bộ, các scope token nội bộ, và cách kết hợp pipeline nội bộ nằm ngoài phạm vi của bề mặt công khai và không được tái hiện ở đây.

Ranh giới triển khai

NextPDF Enterprise tích hợp với một KMS hoặc suy dẫn khóa từ một bí mật khóa chủ đã cấu hình. Bản thân nó không lưu trữ hay bảo đảm tính bảo mật của bí mật khóa chủ đó hay khóa cloud KMS. 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 lần triển khai, và vào người vận hành — không chỉ phụ thuộc vào riêng NextPDF Enterprise. Người vận hành chịu trách nhiệm cấp phát khóa chủ, lưu trữ bí mật, cấu hình KMS, và lập lịch xoay vòng. Trách nhiệm bảo vệ khóa tuân theo NIST SP 800-57 Part 1 Rev.5 §5.5.2. NextPDF Enterprise không phơi bày các luồng thông tin xác thực KMS hay chi tiết nội bộ về xử lý khóa chủ trong tài liệu này.

Ranh giới tuân thủ pháp lý

Trang này liên quan đến quản lý khóa. Phát biểu về chế độ FIPS là một phát biểu tương thích, không phải một chứng nhận và cũng 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 về các nghĩa vụ quy định của bạn.

Ranh giới xuất bản

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

Hợp đồng hành vi

• Provider factory chọn provider từ cấu hình và trả về một provider thỏa mãn hợp đồng provider.
• Một provider trả về siêu dữ liệu khóa bất biến và không bao giờ trả về byte khóa thô.
• Một lệnh gọi xoay vòng nâng phiên bản khóa và trả về siêu dữ liệu mới; bên gọi mã hóa lại dữ liệu collection.
• Sidecar GPU báo cáo một chế độ suy giảm khi chuyển sang dùng CPU và phát sinh một ngoại lệ có kiểu khi nó không khả dụng.

Xem thêm

• Tài liệu tham chiếu Accelerator — NextPDF Enterprise
• Security — NextPDF Enterprise
• Intelligence — NextPDF Enterprise
• Accelerator — NextPDF Pro
• KMS · DEK · HKDF — các thuật ngữ bảng chú giải.