Enterprise รุ่น

Accelerator — เอกสารอ้างอิงเชิงลึก (GPU sidecar, โรงงานผู้ให้บริการ KMS)

ภาพรวมโดยสังเขป

หน้านี้คือเอกสารอ้างอิงเชิงลึกสำหรับพื้นผิวการเร่งความเร็วสาธารณะของ NextPDF\Enterprise\Accelerator ครอบคลุมสแตกผู้ให้บริการ KMS ได้แก่ โรงงาน สัญญาของผู้ให้บริการ ผู้ให้บริการในเครื่อง และผลลัพธ์ key-metadata และครอบคลุมบริการ GPU sidecar สำหรับ embedding และการค้นหาเวกเตอร์ โดยระบุพารามิเตอร์ ค่าเริ่มต้น โหมดความล้มเหลว และจุดยืนด้านการเก็บรักษาคีย์ โปรดอ่านหน้าความสามารถ Acceleratorก่อนเพื่อคำแนะนำด้านเวิร์กโฟลว์ สัญลักษณ์อื่นใน namespace เดียวกันเป็นของความสามารถอื่นและอยู่นอกขอบเขตของหน้านี้

ความพร้อมใช้งานและการอนุญาต

ความสามารถนี้มาพร้อมกับ NextPDF Enterprise (nextpdf/enterprise) และเปิดใช้งานด้วย license envelope ระดับ Enterprise การปรับใช้ที่ไม่มีสิทธิ์นั้นจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและรับใบอนุญาต

ผู้ให้บริการ KMS ถูกเลือกในขณะรันไทม์ โค้ดที่เรียกใช้ขึ้นอยู่กับสัญญาของผู้ให้บริการ ไม่ใช่ผู้ให้บริการแบบรูปธรรม บริการ embedding และ vector-index นำสัญญา EmbeddingServiceInterface และ VectorIndexInterface ของ Core ไปใช้

พื้นผิว API สาธารณะ

composer require nextpdf/enterprise:^3

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	ยก exception หรือความล้มเหลว	หมายเหตุ
`KmsProviderFactory::fromEnvironment`	ไม่มี	สร้างผู้ให้บริการตามชื่อในตัวแปรตัวเลือก หากไม่ตั้งค่าหรือว่างจะเลือก `local`	`KmsProviderInterface`	`RuntimeException` เมื่อไม่มีคีย์หลัก ผู้ให้บริการคลาวด์ไม่พร้อมใช้งาน หรือชื่อไม่รู้จัก	จุดเข้าแบบ static
`KmsProviderFactory::create`	`string $providerType`, `array $config = []`	สร้างผู้ให้บริการตามชื่อจากการกำหนดค่าอย่างชัดเจน	`KmsProviderInterface`	`RuntimeException` เมื่อ `local` ไม่มี `encryption_key` ที่ไม่ว่าง หรือเมื่อชื่อไม่รู้จัก	`local` เป็นชื่อเดียวที่สร้างได้ในรุ่นนี้
`KmsProviderInterface::getEncryptionKey`	`string $collectionId`	คืนข้อมูลเมตาคีย์ปัจจุบันของ collection	`EncryptionKeyResult`	`RuntimeException` เมื่อผู้ให้บริการเข้าถึงไม่ได้หรือกำหนดค่าผิด (สัญญา)	ข้อมูลเมตาเท่านั้น ไม่มีไบต์คีย์แบบดิบ
`KmsProviderInterface::rotateKey`	`string $collectionId`	เลื่อนเวอร์ชันคีย์	`EncryptionKeyResult`	`RuntimeException` เมื่อการหมุนล้มเหลว (สัญญา)	การหมุนเป็นสัญญาณให้ผู้เรียก re-encrypt
`KmsProviderInterface::providerName`	ไม่มี	รายงานชื่อผู้ให้บริการตามรูปแบบมาตรฐาน	`string`	ไม่ได้ประกาศไว้	`local`, `aws`, `gcp`, `azure`, `vault`
`LocalKmsProvider::__construct`	`string $encryptionKey` (อ่อนไหว)	ตรวจสอบคีย์หลัก hex อย่างน้อย 64 อักขระ hex (32 ไบต์)	`LocalKmsProvider`	`InvalidArgumentException` เมื่อค่าสั้นเกินไปหรือไม่ใช่ hex	การป้องกันแบบ fail-fast ไม่ได้ทำการได้มาซึ่งคีย์เอง
`LocalKmsProvider::getEncryptionKey`	`string $collectionId`	สร้าง `local:{collectionId}:v{version}` เวอร์ชันเริ่มต้นเป็น 1	`EncryptionKeyResult`	ไม่ได้ประกาศไว้	ป้ายอัลกอริทึม `AES-256-GCM`
`LocalKmsProvider::rotateKey`	`string $collectionId`	เพิ่มตัวนับเวอร์ชันในกระบวนการ	`EncryptionKeyResult`	ไม่ได้ประกาศไว้	สถานะเวอร์ชันเป็นราย instance
`EncryptionKeyResult::__construct`	`string $keyId`, `int $keyVersion`, `string $algorithm = 'AES-256-GCM'`, `string $provider = 'local'`	อ็อบเจกต์ค่าข้อมูลเมตาที่ไม่เปลี่ยนแปลงได้	`EncryptionKeyResult`	ไม่ได้ประกาศไว้	ไม่เคยพกพาวัสดุคีย์
`GpuEmbeddingService::embed`	`string $text`	มอบหมายให้ `batchEmbed` และคืนสมาชิกลำดับศูนย์	`list<float>`	เช่นเดียวกับ `batchEmbed`	เวกเตอร์ขนาด 1024 มิติ
`GpuEmbeddingService::batchEmbed`	`array $texts`	ฝังชุดข้อมูลบน sidecar	`list<list<float>>`	`InvalidArgumentException` เมื่อชุดข้อมูลว่าง `SpectrumNotAvailableException` เมื่อเข้าถึง sidecar ไม่ได้ `SpectrumApiException` เมื่อการตอบสนองล้มเหลว รูปแบบผิด หรือจำนวนไม่ตรงกัน	ไม่เคยคืนผลลัพธ์บางส่วน
`GpuEmbeddingService::getDimension`	ไม่มี	คืนค่า `1024`	`int`	ไม่ได้ประกาศไว้	ค่าคงที่
`GpuEmbeddingService::getModelName`	ไม่มี	คืนค่า `multilingual-e5-large`	`string`	ไม่ได้ประกาศไว้	ค่าคงที่
`GpuVectorIndex::__construct`	`SpectrumClient $client`, `string $collectionId = 'default'`	ผูก handle เข้ากับ collection เดียว	`GpuVectorIndex`	ไม่ได้ประกาศไว้	หนึ่ง handle ต่อหนึ่งตัวระบุ collection
`GpuVectorIndex::build`	`array $vectors`, `array $ids`	สร้างดัชนี collection บน sidecar	`void`	`InvalidArgumentException` เมื่อชุดข้อมูลว่างหรือความยาวไม่ตรงกัน `SpectrumNotAvailableException` เมื่อเข้าถึงไม่ได้ `SpectrumApiException` เมื่อการตอบสนองการสร้างไม่คาดคิด	การสร้างใหม่จะแทนที่ดัชนี
`GpuVectorIndex::search`	`array $queryVector`, `int $topK = 10`	ค้นหาเพื่อนบ้านใกล้สุดแบบจัดอันดับ	`list<VectorSearchResult>`	`SpectrumNotAvailableException` เมื่อเข้าถึงไม่ได้ `JsonException` เมื่อเนื้อหาการตอบสนองรูปแบบผิด	อันดับต่อรายการอยู่ในข้อมูลเมตาผลลัพธ์
`GpuVectorIndex::delete`	`array $ids`	ปฏิเสธเสมอ	`void` (ตามที่ประกาศ)	เสมอ: `SpectrumApiException` (ยังไม่ได้ทำ)	ดัชนีที่สร้างแล้วไม่เปลี่ยนแปลง ให้สร้างใหม่แทน
`GpuVectorIndex::count`	ไม่มี	อ่านยอดรวม collection จาก sidecar	`int`	ไม่ยก exception ความล้มเหลวใด ๆ คืนค่า `0`	`0` กำกวม: ว่างหรือเข้าถึงไม่ได้

ลายเซ็นจุดเข้า

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
}

พื้นผิวการกำหนดค่า

การตั้งค่า	ผู้บริโภค	ความหมาย
`SPECTRUM_KMS_PROVIDER`	`fromEnvironment()`	ตัวเลือกผู้ให้บริการ หากไม่ตั้งค่าหรือว่างจะปรับเป็น `local`
`SPECTRUM_ENCRYPTION_KEY`	เส้นทางผู้ให้บริการ `local`	คีย์หลักเข้ารหัสแบบ hex อย่างน้อย 64 อักขระ hex (32 ไบต์) แชร์กับ sidecar
`encryption_key`	`create('local', [...])`	คีย์หลักแบบชัดเจน รูปแบบและการตรวจสอบเดียวกัน

สัญญาพฤติกรรม

การเลือกผู้ให้บริการ

KmsProviderFactory::fromEnvironment อ่านตัวแปรตัวเลือกและใช้ค่าเริ่มต้นเป็น local ชื่อผู้ให้บริการคลาวด์ aws, gcp, azure และ vault ถูกจดจำแต่สร้างไม่ได้ในรุ่นนี้ การเลือก aws จะยกข้อผิดพลาดที่มีชนิดซึ่งระบุชื่อแพ็กเกจ aws/aws-sdk-php ที่ต้องใช้ อีกสามรายการรายงานว่ายังไม่ได้ทำการผสานการทำงาน ชื่อที่ไม่รู้จักจะยกข้อผิดพลาดที่มีชนิดซึ่งแสดงรายชื่อที่รองรับ KmsProviderFactory::create รับชื่อผู้ให้บริการแบบชัดเจนและแมปการกำหนดค่า local เป็นชื่อเดียวที่มันสร้าง

ข้อมูลเมตาคีย์และการเก็บรักษา

ผู้ให้บริการคืนข้อมูลเมตาคีย์ที่ไม่เปลี่ยนแปลงได้ ได้แก่ ตัวระบุคีย์ เวอร์ชันคีย์ที่เพิ่มขึ้นแบบ monotonic ป้ายอัลกอริทึม และชื่อผู้ให้บริการ มันไม่เคยคืนไบต์คีย์แบบดิบ ดังนั้นการรั่วไหลของข้อมูลเมตาจึงไม่เปิดเผยวัสดุคีย์ ผู้ให้บริการในเครื่องแบ่งหน้าที่กับ accelerator sidecar คลาส PHP ตรวจสอบ secret คีย์หลักในขณะการสร้างและสร้างอัตลักษณ์คีย์ที่เสถียรและจำกัดขอบเขตตาม collection ในรูปแบบ local:{collectionId}:v{version} sidecar ทำการได้มาแบบ HKDF-SHA256 และการเข้ารหัส AES-256-GCM โดยได้มาซึ่งคีย์เข้ารหัสข้อมูลขนาด 32 ไบต์ที่แตกต่างกันต่อ collection โดยใช้ตัวระบุ collection และเวอร์ชันเป็นตัวแยกโดเมน ทั้งสองฝ่ายอ่าน secret คีย์หลักที่กำหนดค่าไว้เดียวกัน ไม่มีการติดต่อบริการ KMS ภายนอก การจัดการคีย์อยู่ภายในการปรับใช้ เวอร์ชันคีย์และโมเดลวงจรชีวิตเป็นไปตาม NIST SP 800-57 Part 1 Rev.5 §4

การเรียกหมุนจะเลื่อนเวอร์ชันคีย์และคืนข้อมูลเมตาใหม่ ผู้เรียก re-encrypt ข้อมูล collection ด้วยเวอร์ชันใหม่ ผู้ให้บริการไม่ได้ re-encrypt สิ่งใดเอง

ความปลอดภัยของคีย์ขึ้นอยู่กับ KMS หรือ secret คีย์หลัก ขึ้นอยู่กับการปรับใช้ และขึ้นอยู่กับผู้ดำเนินการ — ไม่ได้ขึ้นอยู่กับ NextPDF Enterprise เพียงลำพัง ผู้ดำเนินการเป็นเจ้าของการจัดเตรียมคีย์หลัก การจัดเก็บ secret การกำหนดค่า KMS และการจัดกำหนดการการหมุน ความรับผิดชอบในการปกป้องคีย์เป็นไปตาม NIST SP 800-57 Part 1 Rev.5 §5.5.2

GPU embedding

GpuEmbeddingService นำสัญญา embedding ของ Core ไปใช้และมอบหมายให้ sidecar sidecar รันโมเดล embedding บน GPU เมื่อมี GPU พร้อมใช้งานและถอยกลับไปใช้ CPU มิฉะนั้น โดยทำเครื่องหมายข้อมูลเมตาการตอบสนองว่า degraded จาก GPU รูปทรงเวกเตอร์เหมือนกันในทั้งสองกรณี โมเดล (ประมาณ 1.3 GB) ถูกดาวน์โหลดและโหลดแบบ lazy ในคำขอแรก ความหมายของชุดข้อมูลเป็นแบบทั้งหมดหรือไม่มีเลย ความล้มเหลวรายรายการ เวกเตอร์รูปแบบผิด หรือจำนวนไม่ตรงกันจะยกข้อผิดพลาดที่มีชนิดแทนที่จะคืนผลลัพธ์บางส่วน

การค้นหาเวกเตอร์ GPU

GpuVectorIndex นำสัญญา vector-index ของ Core ไปใช้และผูก handle หนึ่งเข้ากับตัวระบุ collection หนึ่ง build สร้างดัชนีบน sidecar sidecar ใช้ดัชนี GPU เมื่อมี GPU พร้อมใช้งานและใช้ดัชนี CPU มิฉะนั้น ดัชนีไม่เปลี่ยนแปลงเมื่อสร้างแล้ว delete ปฏิเสธเสมอด้วยข้อผิดพลาดที่มีชนิดว่ายังไม่ได้ทำ และการลบต้องสร้างใหม่ search คืนผลลัพธ์ที่จัดอันดับพร้อมอันดับเริ่มจากหนึ่งในข้อมูลเมตาของแต่ละผลลัพธ์ count ถาม sidecar สำหรับยอดรวม collection และรายงาน 0 เมื่อเกิดความล้มเหลวใด ๆ แทนที่จะยก exception

กรณีขอบและโหมดความล้มเหลว

คีย์หลักต้องถอดรหัสจาก hex เป็นอย่างน้อย 32 ไบต์ ค่าที่สั้นกว่าหรือไม่ใช่ hex จะยก InvalidArgumentException ในขณะการสร้าง ก่อนการเรียก sidecar ใด ๆ
ตัวแปรตัวเลือกที่ไม่ตั้งค่าหรือว่างจะปรับเป็น local โรงงานไม่เคยเดาผู้ให้บริการอื่น
fromEnvironment บนเส้นทาง local โดยไม่มีตัวแปรคีย์หลักจะยกข้อผิดพลาดที่มีชนิดซึ่งระบุชื่อตัวแปรที่ขาดหายไป
create('local', [...]) โดยไม่มีรายการ encryption_key ที่ไม่ว่างจะยกข้อผิดพลาดที่มีชนิดซึ่งระบุชื่อรายการที่ขาดหายไป
สถานะเวอร์ชันคีย์อยู่ในกระบวนการและเป็นราย instance ผู้ให้บริการ กระบวนการใหม่จะเห็นเวอร์ชัน 1 จนกว่าจะมีการหมุนอีกครั้ง จงคงผลลัพธ์การหมุนไว้ด้วยการ re-encrypt ข้อมูล ไม่ใช่ด้วยการเชื่อสถานะของผู้ให้บริการ
ชุดข้อมูล embedding ที่ว่างจะยก InvalidArgumentException โดยไม่มีการติดต่อ sidecar
ความพร้อมใช้งานของ sidecar ถูกตรวจสอบต่อการเรียกแต่ละครั้ง sidecar ที่เข้าถึงไม่ได้จะยก SpectrumNotAvailableException บริการไม่เคยล้มเหลวอย่างเงียบ ๆ
องค์ประกอบที่ไม่ใช่ตัวเลขภายในเวกเตอร์ embedding ที่คืนมาจะถูกบังคับเป็น 0.0 เวกเตอร์ที่ขาดหายไปหรือไม่ใช่อาเรย์จะยก SpectrumApiException
คำขอ embedding แรกจะรับภาระค่าดาวน์โหลดและโหลดโมเดลครั้งเดียว จงกำหนดขนาด timeout นั้นแยกต่างหาก
build และ search ถอดรหัสการตอบสนองของ sidecar อย่างเข้มงวด เนื้อหาที่รูปแบบผิดจะยก JsonException count กลืนทุกความล้มเหลวและคืนค่า 0
ผลการค้นหาที่ขาดตัวระบุหรือคะแนนจะใช้ค่าเริ่มต้นเป็นสตริงว่างและ 0.0 แทนที่จะทำให้ชุดข้อมูลล้มเหลว
รหัสข้อผิดพลาดของ sidecar และลำดับชั้น exception ถูกจัดทำแคตตาล็อกในเอกสารอ้างอิงข้อผิดพลาด Accelerator

พฤติกรรมในโหมด FIPS

เส้นทางคีย์ในเครื่องใช้ HKDF-SHA256 สำหรับการได้มาและ AES-256-GCM สำหรับการเข้ารหัส sidecar ดำเนินการทั้งสอง ป้ายอัลกอริทึมที่บันทึกในข้อมูลเมตาคีย์คือ AES-256-GCM เมื่อการปรับใช้รันกับผู้ให้บริการการเข้ารหัสที่ผ่านการตรวจรับรอง FIPS ไพรมิทีฟเหล่านั้นจะรันในขอบเขตที่ได้รับการรับรองนั้น การใช้ AES-GCM ต้องการ initialization vector ที่ไม่ซ้ำกันต่อคีย์ ตาม NIST SP 800-38D §5

NextPDF Enterprise ไม่ใช่โมดูลการเข้ารหัสที่ผ่านการตรวจรับรอง FIPS และไม่ได้อ้างการรับรอง FIPS มันทำงานในโหมดที่เข้ากันได้กับ FIPS เท่านั้นเมื่อกำหนดค่าด้วยผู้ให้บริการการเข้ารหัสที่ผ่านการตรวจรับรอง FIPS หรือ KMS ที่ผ่านการตรวจรับรอง FIPS ไม่มีอาร์ทิแฟกต์การรับรอง FIPS อยู่ใน repository นี้

ความสอดคล้อง

ข้อกล่าวอ้าง	มาตรฐาน	ข้อ
เวอร์ชันคีย์และโมเดลวงจรชีวิตเป็นไปตามคำแนะนำสถานะคีย์	NIST SP 800-57 Part 1 Rev.5	§4
ความรับผิดชอบในการปกป้องและเก็บรักษาคีย์อยู่กับเจ้าของคีย์และผู้ดำเนินการ	NIST SP 800-57 Part 1 Rev.5	§5.5.2
AES-GCM ต้องการ initialization vector ที่ไม่ซ้ำกันต่อคีย์	NIST SP 800-38D	§5

ทุกข้อถูกถอดความ NextPDF ไม่ได้ทำซ้ำข้อความเชิงบรรทัดฐาน NextPDF ไม่ได้อ้างการรับรองใด ๆ ความสอดคล้องกับข้อที่อ้างอิงเป็นคำแถลงความสามารถ ไม่ใช่การรับรอง หน้านี้เกี่ยวกับการจัดการคีย์ คำแถลงโหมด FIPS เป็นคำแถลงความเข้ากันได้ ไม่ใช่ความเห็นทางกฎหมาย โปรดปรึกษาที่ปรึกษาด้านการปฏิบัติตามกฎและด้านกฎหมายของคุณเอง

หมายเหตุการพัฒนา

ซอร์สของโมดูลระบุ @since 2.1.0 เอกสารอ้างอิงนี้บันทึกพื้นผิวตามที่จัดส่งใน nextpdf/enterprise 3.1.0
คลาสทั้งหมดเป็น final EncryptionKeyResult เป็น final readonly จงสร้าง instance ใหม่แทนที่จะเปลี่ยนแปลง
คีย์หลักเป็นพารามิเตอร์ตัวสร้างที่อ่อนไหว (#[SensitiveParameter]) PHP ซ่อนมันจาก stack trace จงเก็บมันให้พ้นจาก log ของแอปพลิเคชันและการ dump การกำหนดค่า
SpectrumClient, VectorSearchResult และสัญญา EmbeddingServiceInterface กับ VectorIndexInterface มาจาก NextPDF Core ผู้เรียกเป็นผู้สร้างและจัดหาไคลเอนต์ sidecar
namespace NextPDF\Enterprise\Accelerator ยังมีเอนจินการ offload แบบชุด และสแตกการดึง collection และการสกัด OCR ด้วย พื้นผิวเหล่านั้นอยู่นอกขอบเขตของหน้านี้
รายละเอียดกลไกภายในอยู่ในเอกสารภายในของ repository ต้นทางและอยู่นอกขอบเขตของคู่มือนี้

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว public API ที่รองรับเท่านั้น เส้นทาง namespace ภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้า ticket อยู่นอกขอบเขต

ดูเพิ่มเติม

Accelerator — GPU sidecar และแฟกทอรีผู้ให้บริการ KMS — หน้าความสามารถสำหรับคำแนะนำด้านเวิร์กโฟลว์และการเก็บรักษา
เอกสารอ้างอิงข้อผิดพลาด Accelerator — ลำดับชั้น exception ของ sidecar และรหัสข้อผิดพลาด
Security — เอกสารอ้างอิงเชิงลึก
Accelerator — เอกสารอ้างอิงเชิงลึก NextPDF Pro