Pro 版本

Accelerator

速覽

Accelerator 將批次影像重新壓縮、PDF 剖析與文字嵌入卸載到一個同位的 CPU sidecar。當 sidecar 無法連線時，每個操作都會回退到行程內的 PHP 路徑，因此呼叫端無論哪種方式都會觀察到相同的結果。

可用性與授權

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

Accelerator 沒有獨立的逐功能旗標。加速路徑由執行階段的一個 sidecar 連線性檢查（ProAcceleratorProvider::isAvailable()）選定；當 sidecar 無法連線時，改為執行行程內的 PHP 路徑。

安裝

composer require nextpdf/pro:^3

Premium 套件會將 nextpdf/pro 程式碼安裝在 NextPDF\Pro\Accelerator 命名空間之下。nextpdf/premium metapackage 也會安裝 Enterprise 能力；Accelerator 本身是一項 Pro 層級功能。

概念總覽

ProAcceleratorProvider 是進入點。它惰性地建構四個服務：

一個加速的 optimizer，它包覆 Pro 的 PdfOptimizer，並將批次影像工作卸載到 sidecar。
一個加速的 differ，它包覆 Pro 的 PdfDiffer；sidecar 將結構剖析平行化，而 diff 演算法本身在 PHP 中執行。
一個 CPU 嵌入服務，它使用一個由 sidecar 託管的 all-MiniLM-L6-v2 ONNX 模型回傳 384 維向量。
一個 CPU 向量索引，它建立並搜尋一個以集合識別碼為鍵的記憶體內 HNSW 索引。

此設計將領域邏輯保留在 PHP 中。sidecar 執行可平行化、受 CPU 限制的工作（影像轉碼、多文件剖析、ONNX 推論、向量搜尋）。每條加速路徑都有一個會產生等效結果的確定性 PHP 回退。

為何如此設計

承載性的決策是：正確性絕不依賴 sidecar。領域邏輯留在 PHP 中；sidecar 僅執行可平行化、受 CPU 限制的工作。optimizer 與 differ（AcceleratedOptimizer、AcceleratedDiffer）保留一個確定性的 PHP 回退，因此缺少 sidecar 改變的是時間，而非結果。只有那兩個沒有 PHP 對應的操作——CpuEmbeddingService 與 CpuVectorIndex——會失敗關閉，而非降級。在那裡給出一個無聲的錯誤答案會比一個明確的錯誤更糟。這樣的切分讓吞吐量得以隨 sidecar 核心數擴展，同時呼叫端維持單一程式碼路徑與單一信任邊界。

設計背景：大量文件產生。

行為合約

ProAcceleratorProvider::isAvailable() 回傳 sidecar 是否回應。呼叫端可以據此分支，但不必這麼做：optimizer 與 differ 會自動回退。
embedding()->embed() 回傳單一的 384 元素向量；batchEmbed() 為每個輸入回傳一個向量，並以 InvalidArgumentException 拒絕空的輸入清單。
vectorIndex($collectionId)->build() 要求 vectors 與 ids 長度相同，並將空輸入視為無操作。
vectorIndex()->search($queryVector, $topK) 回傳排名結果；HNSW 索引不支援 delete()，並會拒絕該呼叫——呼叫端改為重建索引。
嵌入服務與向量索引需要 sidecar；它們會引發一個「不可用」錯誤，而非默默降級，因為 ONNX 推論或 HNSW 搜尋沒有 PHP 對應。
optimizer 與 differ 絕不會在 sidecar 失敗時引發錯誤；它們會透明地降級到 PHP 路徑。

程式碼範例 — 快速上手

以下反映已記載的公開 API（ProAcceleratorProvider）。本儲存庫不為此模組隨附任何可執行的範例。

use NextPDF\Pro\Accelerator\ProAcceleratorProvider;

$provider = new ProAcceleratorProvider($spectrumClient);

$result = $provider->optimizer()->optimizeBatch([
    'invoice-1' => $pdfBytesA,
    'invoice-2' => $pdfBytesB,
]);

foreach ($result->getItems() as $item) {
    // Per-document optimization outcome.
}

程式碼範例 — 正式環境

use NextPDF\Pro\Accelerator\ProAcceleratorProvider;

$provider = new ProAcceleratorProvider($spectrumClient);

if ($provider->isAvailable()) {
    $index = $provider->vectorIndex('contracts');
    $index->build($vectors, $ids);
    $hits = $index->search($queryVector, topK: 10);
} else {
    // No PHP equivalent for HNSW search: route to your own retrieval path
    // or surface a degraded-capability message.
}

請將 ProAcceleratorProvider 透過你的容器以單例接線，讓 optimizer 與 differ 實例得以重複使用。請將嵌入與向量索引呼叫視為需要 sidecar。

邊界案例與陷阱

向量索引存在於 sidecar 程序記憶體中，並以集合識別碼為鍵。一次 sidecar 重啟會清除所有索引；請在重啟後重建。
當 sidecar 無法連線時，向量索引上的 count() 回傳 0，而非引發錯誤。
optimizer 與 differ 加速是盡力而為的；批次途中發生 sidecar 錯誤會導致該次呼叫無聲回退，因此變動的是時間——而非正確性。

效能

加速針對受 CPU 限制的批次工作：平行影像轉碼、多文件剖析，以及向量搜尋。NextPDF 在此不公布一個固定的吞吐量倍率；增益取決於文件組合、影像密度、sidecar 核心數，以及批次大小。在仰賴某個特定數字之前，請在你的環境中量測。PHP 回退在設計上是單執行緒的。

安全注意事項

本模組透過其所設定的傳輸，將文件與向量送往同位的 sidecar。請將 sidecar 視為你信任邊界的一部分，並將它部署在同一台主機或一個私有網路區段上。本模組會在派送之前驗證輸入的大小與形態。它不記錄任何文件內容。

一致性

本模組本身不執行任何格式一致性工作；它將最佳化與比對委派給 Pro Optimizer 與 Diff 模組。ISO 32000-2 參考請見那些模組。本頁的一致性佐證來自已記載的公開類別合約及其單元測試；撰寫時 RAG 語料庫無法使用，因此此處不主張任何外部條款識別碼。

Enterprise 邊界註記

Enterprise 不會改變 Accelerator 行為。Enterprise 新增記載於別處的更高層級合規、封存與簽章生命週期功能；那些不在本模組的範圍內，且使用 Accelerator 並不需要它們。

Core 回退/替代方案

沒有 Pro 時，請使用 NextPDF Core 行程內的最佳化與比對。本模組中的加速路徑在 sidecar 缺席時會退化為同樣的 PHP 行為。

發布邊界

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