Accelerator — การอ้างอิงเชิงลึก

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

หน้านี้เป็นการอ้างอิงเชิงลึกสำหรับพื้นผิวการเร่งความเร็วสาธารณะของ NextPDF\Pro\Accelerator ครอบคลุม provider factory ตัวเพิ่มประสิทธิภาพแบบกลุ่มที่เร่งความเร็ว differ wrapper และบริการไซด์คาร์ CPU สำหรับการฝังเวกเตอร์และการค้นหาเวกเตอร์ โดยระบุพารามิเตอร์ ค่าเริ่มต้น โหมดความล้มเหลว และความหมายของการถอยกลับ อ่าน หน้าความสามารถ Accelerator ก่อนเพื่อคำแนะนำเวิร์กโฟลว์

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

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

Accelerator ไม่มีแฟล็กสิทธิ์ใช้งานรายฟีเจอร์ โค้ดมาพร้อมกับรุ่น Pro เส้นทางตัวเพิ่มประสิทธิภาพที่เร่งความเร็วถูกเลือกในขณะรันไทม์ด้วยการตรวจการเข้าถึงไซด์คาร์ บริการฝังเวกเตอร์และดัชนีเวกเตอร์ไม่มีทางเลือกสำรอง PHP และจะ fail closed เมื่อไซด์คาร์ไม่สามารถเข้าถึงได้

พื้นผิว public API

composer require nextpdf/pro:^3

เมทาแพ็กเกจ nextpdf/premium ติดตั้งโค้ด nextpdf/pro โมดูลนี้อยู่ภายใต้เนมสเปซ NextPDF\Pro\Accelerator

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
ProAcceleratorProvider::__construct	SpectrumClient $client	ผูก provider เข้ากับ sidecar client ของ Core	ProAcceleratorProvider	ไม่ได้ประกาศไว้	ผู้เรียกใช้สร้างและจัดหา client
ProAcceleratorProvider::isAvailable	ไม่มี	ตรวจการเข้าถึงไซด์คาร์ผ่าน client	bool	ไม่ได้ประกาศไว้	เฉพาะการเข้าถึงเท่านั้น endpoint ถูกตรวจต่อการเรียก
ProAcceleratorProvider::embedding	ไม่มี	คืนบริการฝังเวกเตอร์ที่ memoize ไว้	EmbeddingServiceInterface	ไม่ได้ประกาศไว้	หนึ่งอินสแตนซ์ CpuEmbeddingService ต่อ provider
ProAcceleratorProvider::vectorIndex	string $collectionId = 'default'	คืน handle ดัชนีใหม่ที่ผูกกับคอลเลกชัน	VectorIndexInterface	ไม่ได้ประกาศไว้	ไม่ memoize หนึ่ง handle ต่อการเรียก
ProAcceleratorProvider::optimizer	ไม่มี	คืนตัวเพิ่มประสิทธิภาพที่เร่งความเร็วที่ memoize ไว้	AcceleratedOptimizer	ไม่ได้ประกาศไว้	สร้างด้วย client ของ provider
ProAcceleratorProvider::differ	ไม่มี	คืน differ wrapper ที่ memoize ไว้	AcceleratedDiffer	ไม่ได้ประกาศไว้	สร้างด้วย client ของ provider
AcceleratedOptimizer::__construct	?SpectrumClient $spectrum = null, OptimizationLevel $level = OptimizationLevel::Balanced, ?LoggerInterface $logger = null	ห่อ PHP PdfOptimizer ที่ระดับที่กำหนด	AcceleratedOptimizer	ไม่ได้ประกาศไว้	client ที่เป็น null เลือกเส้นทาง PHP logger ที่เป็น null เลือก NullLogger
AcceleratedOptimizer::optimizeBatch	array<string, string> $documents	วิเคราะห์แต่ละเอกสาร ถ่ายงานภาพไปยังไซด์คาร์เมื่อเข้าถึงได้	BatchResultInterface	SpectrumApiException SPEC-SEC-001 (HTTP 413) เมื่อกลุ่มเกินขีดจำกัด เครื่องหมายข้อผิดพลาดรายรายการในผลลัพธ์สำรอง	ความล้มเหลวของการขนส่งหลังการรับเข้าจะลดทอนไปเป็นเส้นทาง PHP
AcceleratedDiffer::__construct	?SpectrumClient $spectrum = null	เก็บ client ที่เป็นทางเลือกไว้เพื่อความเข้ากันได้ในอนาคต	AcceleratedDiffer	ไม่ได้ประกาศไว้	client ไม่ถูกใช้ในรุ่นนี้
AcceleratedDiffer::compare	string $sourcePdf, string $targetPdf	เปรียบเทียบเอกสารสองฉบับทั้งหมดใน PHP	DiffResult	ตาม PdfDiffer ของ Pro	ไม่มีการส่งคำขอไปยังไซด์คาร์ในรุ่นนี้
AcceleratedDiffer::isSpectrumWired	ไม่มี	รายงานว่ามีการฉีด sidecar client หรือไม่	bool	ไม่ได้ประกาศไว้	เฉพาะสถานะการเชื่อมต่อ ไม่ส่งคำขอ
CpuEmbeddingService::embed	string $text	มอบหมายให้ batchEmbed และคืนองค์ประกอบที่ศูนย์	list<float>	ตาม batchEmbed	เวกเตอร์ 384 มิติ
CpuEmbeddingService::batchEmbed	array $texts	ฝังเวกเตอร์กลุ่มบนไซด์คาร์	list<list<float>>	InvalidArgumentException เมื่อกลุ่มว่าง SpectrumNotAvailableException เมื่อเข้าถึงไม่ได้ SpectrumApiException เมื่อการตอบสนองล้มเหลว ผิดรูปแบบ หรือจำนวนไม่ตรงกัน	ไม่คืนผลลัพธ์บางส่วนเลย
CpuEmbeddingService::getDimension	ไม่มี	คืนค่า 384	int	ไม่ได้ประกาศไว้	ค่าคงที่
CpuEmbeddingService::getModelName	ไม่มี	คืนค่า all-MiniLM-L6-v2	string	ไม่ได้ประกาศไว้	ค่าคงที่
CpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	ผูก handle เข้ากับหนึ่งคอลเลกชัน	CpuVectorIndex	ไม่ได้ประกาศไว้	หนึ่ง handle ต่อตัวระบุคอลเลกชัน
CpuVectorIndex::build	array $vectors, array $ids	สร้างดัชนีคอลเลกชันบนไซด์คาร์	void	InvalidArgumentException เมื่อความยาวไม่ตรงกัน SpectrumNotAvailableException เมื่อเข้าถึงไม่ได้	อินพุตว่างจะคืนค่าโดยไม่ติดต่อไซด์คาร์
CpuVectorIndex::search	array $queryVector, int $topK = 10	การค้นหาเพื่อนบ้านใกล้สุดแบบจัดอันดับ	list<VectorSearchResult>	SpectrumNotAvailableException เมื่อเข้าถึงไม่ได้ SpectrumApiException เมื่อมีซองข้อผิดพลาดแบบ in-band JsonException เมื่อเนื้อหาผิดรูปแบบ	อันดับต่อ hit ในเมทาดาทาของผลลัพธ์
CpuVectorIndex::delete	array $ids	ปฏิเสธเสมอ	void (ที่ประกาศ)	เสมอ: SpectrumApiException SPEC-INDEX-004 (HTTP 501)	HNSW ไม่มีการลบต่อเวกเตอร์ ให้สร้างใหม่แทน
CpuVectorIndex::count	ไม่มี	อ่านยอดรวมของคอลเลกชันผ่านการตรวจที่มีมิติ	int	SpectrumNotAvailableException เมื่อเข้าถึงไม่ได้ SpectrumApiException เมื่อเกิดข้อผิดพลาดหรือการตอบสนอง count ผิดรูปแบบ	คืนค่า 0 เฉพาะดัชนีที่ยืนยันว่าว่างเปล่าเท่านั้น
CpuVectorIndex::INDEX_DIMENSION	—	ค่าคงที่สาธารณะ 384	int	—	ตรงกับมิติของการฝังเวกเตอร์

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

final class ProAcceleratorProvider
{
    public function __construct(
        private readonly SpectrumClient $client,
    )

    public function isAvailable(): bool

    public function embedding(): EmbeddingServiceInterface

    public function vectorIndex(string $collectionId = 'default'): VectorIndexInterface

    public function optimizer(): AcceleratedOptimizer

    public function differ(): AcceleratedDiffer
}

final class AcceleratedOptimizer
{
    public function __construct(
        private readonly ?SpectrumClient $spectrum = null,
        private readonly OptimizationLevel $level = OptimizationLevel::Balanced,
        ?LoggerInterface $logger = null,
    )

    public function optimizeBatch(array $documents): BatchResultInterface
}

final class AcceleratedDiffer
{
    public function __construct(
        private readonly ?SpectrumClient $spectrum = null,
    )

    public function compare(string $sourcePdf, string $targetPdf): DiffResult

    public function isSpectrumWired(): bool
}

final class CpuEmbeddingService 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 CpuVectorIndex implements VectorIndexInterface
{
    public const int INDEX_DIMENSION = 384;

    public function __construct(
        private readonly SpectrumClient $client,
        private readonly 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
}

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

ผู้ให้บริการ

ProAcceleratorProvider คือจุดเข้าใช้งาน embedding(), optimizer() และ differ() จะ memoize อินสแตนซ์ของตน vectorIndex($collectionId) คืน handle ใหม่ต่อการเรียก ผูกกับตัวระบุคอลเลกชันที่กำหนด isAvailable() ตรวจการเข้าถึงไซด์คาร์ผ่าน SpectrumClient ของ Core ที่ถูกฉีดเข้ามา

การเพิ่มประสิทธิภาพแบบกลุ่ม

optimizeBatch คืนผลลัพธ์แบบกลุ่มที่ keyed ด้วยตัวระบุเอกสารของผู้เรียกใช้ เมื่อไซด์คาร์เข้าถึงได้ เพย์โหลดรวมจะถูกตรวจสอบกับงบประมาณของ client ก่อนการบัฟเฟอร์หรืออัปโหลดใด ๆ กลุ่มที่เกินขีดจำกัดจะ fail closed ด้วย SpectrumApiException SPEC-SEC-001 (HTTP 413) และจะไม่ลดทอนไปเป็นเส้นทาง PHP เลย กลุ่มที่ได้รับการรับเข้าจะถูกส่งไปยังไซด์คาร์เพื่อทำงานภาพแบบขนาน

ความล้มเหลวของการขนส่ง การยืนยันตัวตน หรือการแจงการตอบสนองหลังการรับเข้าจะลดทอนไปเป็น PHP optimizer ซึ่งวิเคราะห์แต่ละเอกสารตามลำดับ การลดทอนสังเกตได้สองทาง คือเมทาดาทาของผลลัพธ์รายงานเอนจิน php_fallback พร้อมฮาร์ดแวร์สรุป cpu และมีการปล่อยคำเตือน PSR-3 ภายใต้ชื่อเหตุการณ์ spectrum.optimize.fallback คำเตือนมีเพียงคลาสข้อยกเว้นและจำนวนเอกสารเท่านั้น ไม่มีการบันทึกไบต์ของเอกสาร ในผลลัพธ์สำรอง ความล้มเหลวของการวิเคราะห์รายเอกสารจะให้รายการที่มีสถานะข้อผิดพลาดและรหัส SPEC-PARSE-001 เอกสารอื่นในกลุ่มยังคงเสร็จสมบูรณ์

ระดับการเพิ่มประสิทธิภาพเริ่มต้นคือ Balanced ฟิลด์ผลลัพธ์รายรายการคือ original_bytes, optimized_bytes, objects_removed, images_before, images_after, savings_percent และ processing_time_ms

การเปรียบเทียบเอกสาร

compare รันทั้งหมดใน PHP ผ่าน PdfDiffer ของ Pro ได้แก่ การแจงโครงสร้าง การสกัดข้อความ และอัลกอริทึม diff ไม่มีการส่งคำขอไปยังไซด์คาร์ในรุ่นนี้ สัญญาของ differ รับเฉพาะสตริง PDF ดิบเท่านั้น จึงไม่สามารถใช้ผลการแจงจากไซด์คาร์ได้ การถ่ายงานออกไปจะเพิ่มต้นทุนโดยไม่มีประโยชน์ client ที่ถูกฉีดเข้ามาถูกเก็บไว้สำหรับฟีเจอร์การถ่ายงานแจงในอนาคต isSpectrumWired() เปิดเผยสถานะการเชื่อมต่อโดยไม่ส่งคำขอ

การฝังเวกเตอร์ CPU

embed มอบหมายให้ batchEmbed([$text]) และคืนองค์ประกอบที่ศูนย์ batchEmbed([]) ยก InvalidArgumentException ก่อนติดต่อไซด์คาร์ ไซด์คาร์ที่เข้าถึงไม่ได้ยก SpectrumNotAvailableException ความหมายของกลุ่มเป็นแบบทั้งหมดหรือไม่มีเลย คือ ความล้มเหลวรายรายการ เวกเตอร์ที่หายไปหรือผิดรูปแบบ หรือจำนวนไม่ตรงกันจะยก SpectrumApiException (ความล้มเหลวของรูปร่างโปรโตคอลมีรหัส SPEC-IO-001) แทนที่จะคืนเวกเตอร์บางส่วน องค์ประกอบที่ไม่ใช่ตัวเลขภายในเวกเตอร์ที่คืนมาจะถูกแปลงเป็น 0.0 getDimension คืนค่า 384 getModelName คืนค่า all-MiniLM-L6-v2 ไซด์คาร์ดาวน์โหลดและโหลดโมเดล ONNX แบบ lazy ในคำขอแรก

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

แต่ละ handle ผูกกับหนึ่งตัวระบุคอลเลกชัน แต่ละคอลเลกชันจับคู่กับดัชนี HNSW ในหน่วยความจำแยกกันในไซด์คาร์ build ต้องการรายการเวกเตอร์และตัวระบุที่มีความยาวเท่ากันและยก InvalidArgumentException มิฉะนั้น อินพุตว่างจะคืนค่าโดยไม่เรียกไซด์คาร์ search คืน hit ที่จัดอันดับพร้อมอันดับเริ่มที่หนึ่งในเมทาดาทาของแต่ละผลลัพธ์ ซองข้อผิดพลาดแบบ in-band ยก SpectrumApiException ซองที่ไม่มีรหัสจะจับคู่กับ SPEC-INDEX-003 delete ปฏิเสธเสมอด้วย SpectrumApiException SPEC-INDEX-004 (HTTP 501 ลองใหม่ไม่ได้) เพราะ HNSW ไม่รองรับการลบต่อเวกเตอร์ ให้สร้างดัชนีใหม่แทน

count เป็นแบบ fail-closed และไม่กำกวม ไซด์คาร์ที่เข้าถึงไม่ได้ยก SpectrumNotAvailableException ข้อผิดพลาดของการขนส่งและไซด์คาร์ส่งต่อโดยไม่เปลี่ยนแปลง ในการตอบสนองที่สำเร็จ เนื้อหาที่ไม่ใช่ JSON ยก SPEC-INDEX-005 การขาด metadata.total_vectors ยก SPEC-INDEX-006 และยอดรวมที่ไม่ใช่จำนวนเต็มหรือติดลบยก SPEC-INDEX-007 count คืนค่า 0 เฉพาะดัชนีที่ยืนยันว่าว่างเปล่าเท่านั้น การตรวจขนาดส่งเวกเตอร์ศูนย์ที่มี INDEX_DIMENSION (384) มิติพอดี พร้อม top_k เป็น 0 ไซด์คาร์ที่ตรวจสอบมิติจึงยอมรับ

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

• หน่วยความจำของไซด์คาร์เป็นแบบ volatile การรีสตาร์ตจะล้างคอลเลกชัน HNSW ทั้งหมด ให้ถือว่าการสร้างดัชนีเป็น idempotent และรันใหม่หลังการรีสตาร์ต
• รองรับความพร้อมใช้งานแบบผสมภายในกระบวนการเดียว คือ optimizer ลดทอนต่อการเรียก ส่วนบริการ embedding และ vector จะ fail closed ต่อการเรียก
• กลุ่ม optimizer ที่เกินขีดจำกัดจะ fail closed ก่อนการอัปโหลดใด ๆ และจะไม่ถอยกลับไปใช้เส้นทาง PHP
• การถอยกลับของ optimizer จะไม่ล้มเหลวเงียบ ๆ เลย ให้ตรวจเครื่องหมายเอนจินในเมทาดาทาของผลลัพธ์และเฝ้าติดตามเหตุการณ์คำเตือน
• count จะไม่รายงานไซด์คาร์ที่เข้าถึงไม่ได้หรือข้อผิดพลาดโปรโตคอลเป็น 0 เลย กรณีเหล่านั้นยกข้อยกเว้นแบบมีชนิด
• hit การค้นหาที่ขาดตัวระบุหรือคะแนนจะใช้ค่าเริ่มต้นเป็นสตริงว่างและ 0.0 แทนที่จะทำให้กลุ่มล้มเหลว
• top_k ที่เป็น 0 ถูกใช้ภายในเฉพาะการตรวจ count เท่านั้น ให้ส่ง topK ที่เป็นบวกสำหรับการค้นหาจริง
• คำขอฝังเวกเตอร์แรกจ่ายต้นทุนการดาวน์โหลดและโหลดโมเดลครั้งเดียว ให้กำหนดขนาดไทม์เอาต์นั้นแยกต่างหาก
• ลำดับชั้นข้อยกเว้นของไซด์คาร์และตระกูลรหัสข้อผิดพลาดถูกจัดทำรายการไว้ใน การอ้างอิงข้อผิดพลาด Accelerator
• โมดูลนี้ไม่ดำเนินการเข้ารหัสลับใด ๆ และไม่กำหนดพฤติกรรมเฉพาะ FIPS จุดยืนโหมด FIPS ถูกควบคุมโดยโมดูลการลงนามและการปฏิบัติตามข้อกำหนด ไม่ใช่ที่นี่

การเป็นไปตามข้อกำหนด

Accelerator มอบหมายงานที่มีผลต่อรูปแบบให้โมดูล Optimizer และ Diff และไม่ยืนยันความสอดคล้องของรูปแบบอย่างเป็นอิสระ ความสอดคล้องสำหรับงานที่มอบหมายถูกจัดทำเอกสารไว้ในหน้าอ้างอิงของ Optimizer และ Diff หน้านี้ไม่อ้างตัวระบุข้อกำหนดภายนอกใด ๆ ทุกข้อความมีพื้นฐานจากซอร์สของผลิตภัณฑ์ NextPDF ไม่กล่าวอ้างการรับรองใด ๆ

บันทึกการพัฒนา

• ซอร์สของโมดูลมี @since 2.1.0 การอ้างอิงนี้จัดทำเอกสารพื้นผิวตามที่จัดส่งใน nextpdf/pro 3.1.0
• คลาสทั้งหมดเป็น final และใช้การฉีดผ่านคอนสตรัคเตอร์ ให้สร้างอินสแตนซ์ใหม่แทนการเปลี่ยนแปลงค่า
• SpectrumClient, VectorSearchResult, BatchResultInterface และสัญญา EmbeddingServiceInterface กับ VectorIndexInterface มาจาก NextPDF Core ผู้เรียกใช้สร้างและจัดหา sidecar client
• OptimizationLevel, PdfOptimizer และ PdfDiffer มาจากโมดูล Optimizer และ Diff ของ Pro ความหมายของสิ่งเหล่านี้ถูกจัดทำเอกสารไว้ในหน้าอ้างอิงเหล่านั้น
• บริการฝังเวกเตอร์และดัชนีเวกเตอร์ใช้มิติ 384 ร่วมกัน ให้สร้างเวกเตอร์ดัชนีให้มีมิติเดียวกับการฝังเวกเตอร์ที่ใช้ค้นหา
• รายละเอียดกลไกภายในอยู่ในเอกสารภายในของที่เก็บซอร์สและอยู่นอกขอบเขตของคู่มือนี้

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

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

ดูเพิ่มเติม

• Accelerator — หน้าความสามารถสำหรับคำแนะนำเวิร์กโฟลว์
• การอ้างอิงข้อผิดพลาด Accelerator — ลำดับชั้นข้อยกเว้นของไซด์คาร์และรหัสข้อผิดพลาด
• Optimizer — การอ้างอิงเชิงลึก
• Diff — การอ้างอิงเชิงลึก
• Accelerator — การอ้างอิงเชิงลึก NextPDF Enterprise