Pro エディション

Accelerator

概要

Accelerator は、バッチ画像の再圧縮、PDF 解析、テキスト埋め込みを、同じ場所に配置された CPU サイドカーにオフロードします。サイドカーに到達できない場合、すべての操作はインプロセスの PHP パスにフォールバックするため、呼び出し元はどちらの場合も同じ結果を観測します。

提供状況とライセンス

このケイパビリティは NextPDF Pro（nextpdf/pro）に同梱され、Pro ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイメントは、当ケイパビリティのクラスを読み込みません。エディションを比較してライセンスを取得。

Accelerator には機能ごとの独立したフラグはありません。アクセラレートされたパスは、サイドカー到達性チェック（ProAcceleratorProvider::isAvailable()）によって実行時に選択されます。サイドカーに到達できない場合は、代わりにインプロセスの PHP パスが実行されます。

インストール

composer require nextpdf/pro:^3

Premium パッケージは、nextpdf/pro のコードを NextPDF\Pro\Accelerator 名前空間の下にインストールします。nextpdf/premium メタパッケージは Enterprise ケイパビリティもインストールします。Accelerator 自体は Pro ティアの機能です。

概念の概要

ProAcceleratorProvider がエントリーポイントです。4 つのサービスを遅延的に構築します。

アクセラレートされたオプティマイザー — Pro の PdfOptimizer をラップし、バッチ画像処理をサイドカーにオフロードします。
アクセラレートされた差分処理 — Pro の PdfDiffer をラップします。サイドカーが構造解析を並列化し、差分アルゴリズム自体は PHP で実行されます。
CPU 埋め込みサービス — サイドカーがホストする all-MiniLM-L6-v2 ONNX モデルを使用して、384 次元のベクトルを返します。
CPU ベクトルインデックス — コレクション識別子をキーとするインメモリの HNSW インデックスを構築および検索します。

この設計は、ドメインロジックを PHP に保ちます。サイドカーは、並列化可能で CPU バウンドな処理（画像トランスコーディング、複数ドキュメント解析、ONNX 推論、ベクトル検索）を実行します。各アクセラレートされたパスには、同等の結果を生成する決定論的な PHP フォールバックがあります。

なぜこの仕組みなのか

要となる決定は、正確性がサイドカーに依存することは決してない、という点です。ドメインロジックは PHP にとどまり、サイドカーは並列化可能で CPU バウンドな処理のみを実行します。オプティマイザーと差分処理（AcceleratedOptimizer、AcceleratedDiffer）は決定論的な PHP フォールバックを保持するため、サイドカーの欠如はタイミングを変えるだけで、結果は変えません。PHP の同等品を持たない 2 つの操作 — CpuEmbeddingService と CpuVectorIndex — だけが、縮退する代わりにフェイルクローズします。そこでの暗黙的な誤答は、明示的なエラーよりも悪いからです。この分離により、呼び出し元が単一のコードパスと単一のトラスト境界を保ちながら、スループットをサイドカーのコアに応じてスケールさせることができます。

設計背景：大量ドキュメント生成。

挙動コントラクト

ProAcceleratorProvider::isAvailable() は、サイドカーが応答するかどうかを返します。呼び出し元はこれで分岐できますが、その必要はありません。オプティマイザーと差分処理は自動的にフォールバックします。
embedding()->embed() は単一の 384 要素ベクトルを返します。batchEmbed() は入力ごとに 1 つのベクトルを返し、空の入力リストを InvalidArgumentException で拒否します。
vectorIndex($collectionId)->build() は、vectors と ids が同じ長さであることを必要とし、空の入力を no-op として扱います。
vectorIndex()->search($queryVector, $topK) はランク付けされた結果を返します。delete() は HNSW インデックスではサポートされておらず、呼び出しを拒否します。呼び出し元は代わりにインデックスを再構築します。
埋め込みサービスとベクトルインデックスはサイドカーを必要とします。ONNX 推論や HNSW 検索に PHP の同等品がないため、暗黙的に縮退するのではなく、「利用不可」エラーを発生させます。
オプティマイザーと差分処理は、サイドカーの失敗時にエラーを発生させることは決してありません。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 をコンテナ経由でシングルトンとして配線し、オプティマイザーと差分処理のインスタンスが再利用されるようにしてください。埋め込みとベクトルインデックスの呼び出しは、サイドカーを必要とするものとして扱ってください。

エッジケースと注意点

ベクトルインデックスはサイドカープロセスのメモリ内に存在し、コレクション識別子をキーとします。サイドカーの再起動はすべてのインデックスをクリアします。再起動後は再構築してください。
ベクトルインデックスに対する count() は、サイドカーに到達できない場合、エラーを発生させるのではなく 0 を返します。
オプティマイザーと差分処理のアクセラレーションはベストエフォートです。バッチの途中でのサイドカーエラーは、その呼び出しに対して暗黙的なフォールバックを引き起こすため、正確性ではなくタイミングが変動します。

パフォーマンス

アクセラレーションは、CPU バウンドなバッチ処理（並列画像トランスコーディング、複数ドキュメント解析、ベクトル検索）を対象とします。NextPDF はここで固定のスループット倍率を公開しません。ゲインは、ドキュメントの構成、画像密度、サイドカーのコア数、バッチサイズに依存します。特定の数値に頼る前に、お客様の環境で測定してください。PHP フォールバックは、設計上シングルスレッドです。

セキュリティに関する注意

このモジュールは、ドキュメントとベクトルを、構成されたトランスポート経由で、同じ場所に配置されたサイドカーに送信します。サイドカーをお客様のトラスト境界の一部として扱い、同じホストまたはプライベートなネットワークセグメントにデプロイしてください。このモジュールは、ディスパッチ前に入力のサイズと形状を検証します。ドキュメントコンテンツをログに記録しません。

適合性

このモジュールは、それ自体ではフォーマット適合性の処理を行いません。最適化と差分処理を Pro の Optimizer モジュールと Diff モジュールに委譲します。ISO 32000-2 の参照については、それらのモジュールを参照してください。このページの適合性証拠は、文書化されたパブリッククラスコントラクトとその単体テストから得られます。執筆時点で RAG コーパスが利用できなかったため、ここでは外部の条項識別子を一切主張しません。

Enterprise の境界に関する注記

Enterprise は Accelerator の挙動を変更しません。Enterprise は、別の場所で文書化されている、より上位ティアのコンプライアンス、アーカイブ、署名ライフサイクルの機能を追加します。それらはこのモジュールの対象外であり、Accelerator を使用するために必要ではありません。

Core のフォールバック/代替手段

Pro がない場合は、NextPDF Core のインプロセス最適化と差分処理を使用してください。このモジュールのアクセラレートされたパスは、サイドカーが存在しない場合、その同じ PHP の挙動に帰着します。

公開の境界

このページは、外部から観測可能な挙動と、サポートされているパブリック API サーフェスのみを記述しています。内部の名前空間パス、ヘルパークラス、メカニズム表、ランブックのファイル名、チケットのプレフィックスは対象外です。