Accelerator — 深入參考

速覽

本頁是 NextPDF\Pro\Accelerator 公開加速介面的深度參考。內容涵蓋 provider factory、加速批次 optimizer、differ 包裝器，以及用於嵌入與向量搜尋的 CPU 側車服務。它會說明參數、預設值、失敗模式與回退語意。請先閱讀 Accelerator 能力頁面以取得工作流程指引。

可用性與授權

此能力隨 NextPDF Pro（nextpdf/pro）出貨，並以 Pro 層級的授權封套啟用。缺少該權利的部署不會載入此能力的類別。比較版本並取得授權。

Accelerator 沒有逐功能授權旗標。程式碼隨 Pro 版本出貨；加速 optimizer 路徑由一個側車可連線性探測在執行階段選定。嵌入服務與向量索引沒有 PHP 回退，並在側車無法連線時 fail closed。

公開 API 介面

composer require nextpdf/pro:^3

nextpdf/premium 元套件會安裝 nextpdf/pro 程式碼；此模組位於 NextPDF\Pro\Accelerator 命名空間之下。

符號	參數	預設行為	回傳	拋出或失敗於	備註
ProAcceleratorProvider::__construct	SpectrumClient $client	將 provider 綁定到一個 Core 側車用戶端	ProAcceleratorProvider	未宣告	由呼叫端建構並提供該用戶端
ProAcceleratorProvider::isAvailable	無	透過用戶端探測側車可連線性	bool	未宣告	僅為可連線性；端點於每次呼叫時探測
ProAcceleratorProvider::embedding	無	回傳被記憶（memoized）的嵌入服務	EmbeddingServiceInterface	未宣告	每個 provider 一個 CpuEmbeddingService 實例
ProAcceleratorProvider::vectorIndex	string $collectionId = 'default'	回傳一個綁定到該集合的全新索引控點	VectorIndexInterface	未宣告	不記憶；每次呼叫一個控點
ProAcceleratorProvider::optimizer	無	回傳被記憶的加速 optimizer	AcceleratedOptimizer	未宣告	以 provider 的用戶端建構
ProAcceleratorProvider::differ	無	回傳被記憶的 differ 包裝器	AcceleratedDiffer	未宣告	以 provider 的用戶端建構
AcceleratedOptimizer::__construct	?SpectrumClient $spectrum = null, OptimizationLevel $level = OptimizationLevel::Balanced, ?LoggerInterface $logger = null	以給定層級包裝 PHP PdfOptimizer	AcceleratedOptimizer	未宣告	null 用戶端選定 PHP 路徑；null logger 選定 NullLogger
AcceleratedOptimizer::optimizeBatch	array<string, string> $documents	分析每份文件；可連線時將影像工作卸載到側車	BatchResultInterface	批次超限時拋出 SpectrumApiException SPEC-SEC-001（HTTP 413）；回退結果中帶有逐項錯誤標記	准入後的傳輸失敗會降級為 PHP 路徑
AcceleratedDiffer::__construct	?SpectrumClient $spectrum = null	保留可選用戶端以利向前相容	AcceleratedDiffer	未宣告	此版本未使用該用戶端
AcceleratedDiffer::compare	string $sourcePdf, string $targetPdf	完全在 PHP 中比較兩份文件	DiffResult	同 Pro PdfDiffer	此版本不發出側車請求
AcceleratedDiffer::isSpectrumWired	無	回報是否注入了側車用戶端	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'	將控點綁定到單一集合	CpuVectorIndex	未宣告	每個集合識別碼一個控點
CpuVectorIndex::build	array $vectors, array $ids	在側車上建構該集合索引	void	長度不符時拋出 InvalidArgumentException；無法連線時拋出 SpectrumNotAvailableException	空輸入直接回傳，不聯絡側車
CpuVectorIndex::search	array $queryVector, int $topK = 10	排名最近鄰搜尋	list<VectorSearchResult>	無法連線時拋出 SpectrumNotAvailableException；帶內錯誤封套時拋出 SpectrumApiException；主體格式錯誤時拋出 JsonException	結果中繼資料中帶有逐筆命中排名
CpuVectorIndex::delete	array $ids	一律拒絕	void（宣告）	一律：SpectrumApiException SPEC-INDEX-004（HTTP 501）	HNSW 沒有逐向量刪除；請改為重建
CpuVectorIndex::count	無	透過一個帶維度的探測讀取集合總數	int	無法連線時拋出 SpectrumNotAvailableException；發生錯誤或 count 回應格式錯誤時拋出 SpectrumApiException	僅在確認為空的索引時回傳 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) 每次呼叫都會回傳一個綁定到所給集合識別碼的全新控點。isAvailable() 透過注入的 Core SpectrumClient 探測側車可連線性。

批次最佳化

optimizeBatch 會回傳一個以呼叫端文件識別碼為鍵的批次結果。當側車可連線時，聚合負載會在任何緩衝或上傳之前，先對用戶端預算進行驗證。批次超限時會以 SpectrumApiException SPEC-SEC-001（HTTP 413）fail closed；它絕不降級為 PHP 路徑。獲准入的批次會被分派到側車進行平行影像工作。

准入後的傳輸、驗證或回應剖析失敗會降級為 PHP optimizer，它會依序逐一分析每份文件。此降級可被觀察到兩次：結果中繼資料回報引擎 php_fallback，摘要硬體為 cpu，並在事件名稱 spectrum.optimize.fallback 下發出一則 PSR-3 警告。該警告僅帶有例外類別與文件數量；不會記錄任何文件位元組。在回退結果中，逐份文件的分析失敗會產生一個具有錯誤狀態與代碼 SPEC-PARSE-001 的項目；批次中的其他文件仍會完成。

預設最佳化層級為 Balanced。逐項結果欄位為 original_bytes、optimized_bytes、objects_removed、images_before、images_after、savings_percent 與 processing_time_ms。

文件差異

compare 完全透過 Pro PdfDiffer 在 PHP 中執行：結構剖析、文字擷取與差異演算法。此版本不發出側車請求。differ 合約僅接受原始 PDF 字串，因此無法消費側車剖析結果；卸載只會增加成本而無益處。注入的用戶端會被保留，以供未來的剖析卸載功能使用。isSpectrumWired() 會揭露接線狀態而不發出請求。

CPU 嵌入

embed 會委派給 batchEmbed([$text]) 並回傳第零個元素。batchEmbed([]) 會在聯絡側車之前引發 InvalidArgumentException。無法連線的側車會引發 SpectrumNotAvailableException。批次語意為全有或全無：逐項失敗、缺漏或格式錯誤的向量，或數量不符，都會引發 SpectrumApiException（協定形狀失敗帶有 SPEC-IO-001），而非回傳部分向量。回傳向量內的非數值分量會被強制轉為 0.0。getDimension 回傳 384；getModelName 回傳 all-MiniLM-L6-v2。側車會在第一個請求時延遲下載並載入 ONNX 模型。

CPU 向量搜尋

每個控點綁定一個集合識別碼；每個集合在側車中對應到一個獨立的記憶體內 HNSW 索引。build 需要等長的向量與識別碼清單，否則會引發 InvalidArgumentException；空輸入會直接回傳，不呼叫側車。search 會回傳排名命中，並在每筆結果的中繼資料中附上以一為起始的排名。帶內錯誤封套會引發 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，因此驗證維度的側車會接受它。

邊界案例與失敗模式

• 側車記憶體是揮發性的：重啟會清除所有 HNSW 集合。請將索引建構視為冪等，並在重啟後重新執行。
• 支援單一行程內的混合可用性：optimizer 會逐次呼叫降級；嵌入與向量服務會逐次呼叫 fail closed。
• 超限的 optimizer 批次會在任何上傳之前 fail closed；它不會回退到 PHP 路徑。
• optimizer 回退絕不會靜默失敗：請檢查結果中繼資料的引擎標記，並監控警告事件。
• count 絕不會把無法連線的側車或協定錯誤回報為 0；那些會引發具型別的例外。
• 缺少識別碼或分數的搜尋命中會預設為空字串與 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；由呼叫端建構並提供側車用戶端。
• OptimizationLevel、PdfOptimizer 與 PdfDiffer 來自 Pro Optimizer 與 Diff 模組；其語意記載於那些參考頁面上。
• 嵌入服務與向量索引共用 384 維。請將索引向量建構為與查詢它們的嵌入相同的維度。
• 內部機制細節保留在原始碼儲存庫的內部文件中，不在本手冊範圍內。

發佈邊界

本頁僅記載外部可觀察的行為與受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表格、runbook 檔名與工單前綴皆不在範圍內。

另請參閱

• Accelerator — 工作流程指引的能力頁面。
• Accelerator 錯誤參考 — 側車例外階層與錯誤代碼。
• Optimizer — 深度參考
• Diff — 深度參考
• Accelerator — NextPDF Enterprise 深度參考