Pro エディション

Accelerator — 詳細リファレンス

概要

このページは、NextPDF\Pro\Accelerator の公開高速化サーフェスの詳細リファレンスです。プロバイダーファクトリー、高速化バッチオプティマイザー、differ ラッパー、そして埋め込みとベクトル検索のための CPU サイドカーサービスを扱います。パラメーター、既定値、失敗モード、フォールバックのセマンティクスを記載します。ワークフローの指針については、まず Accelerator 機能ページをお読みください。

提供状況とライセンス

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

Accelerator には機能ごとのライセンスフラグはありません。コードは Pro エディションに同梱され、高速化されたオプティマイザー経路は、サイドカーの到達可能性プローブによってランタイムで選択されます。埋め込みサービスとベクトルインデックスには PHP フォールバックがなく、サイドカーに到達できない場合はフェイルクローズドになります。

公開 API サーフェス

composer require nextpdf/pro:^3

nextpdf/premium メタパッケージは nextpdf/pro コードをインストールします。このモジュールは NextPDF\Pro\Accelerator 名前空間の下に存在します。

シンボル	パラメーター	既定の挙動	戻り値	スローまたは失敗	備考
`ProAcceleratorProvider::__construct`	`SpectrumClient $client`	プロバイダーを Core サイドカークライアントにバインド	`ProAcceleratorProvider`	宣言なし	呼び出し元がクライアントを構築して供給
`ProAcceleratorProvider::isAvailable`	なし	クライアント経由でサイドカーの到達可能性をプローブ	`bool`	宣言なし	到達可能性のみ。エンドポイントは呼び出しごとにプローブ
`ProAcceleratorProvider::embedding`	なし	メモ化された埋め込みサービスを返す	`EmbeddingServiceInterface`	宣言なし	プロバイダーごとに `CpuEmbeddingService` 1 インスタンス
`ProAcceleratorProvider::vectorIndex`	`string $collectionId = 'default'`	コレクションにバインドされた新しいインデックスハンドルを返す	`VectorIndexInterface`	宣言なし	メモ化なし。呼び出しごとに 1 ハンドル
`ProAcceleratorProvider::optimizer`	なし	メモ化された高速化オプティマイザーを返す	`AcceleratedOptimizer`	宣言なし	プロバイダーのクライアントで構築
`ProAcceleratorProvider::differ`	なし	メモ化された differ ラッパーを返す	`AcceleratedDiffer`	宣言なし	プロバイダーのクライアントで構築
`AcceleratedOptimizer::__construct`	`?SpectrumClient $spectrum = null`, `OptimizationLevel $level = OptimizationLevel::Balanced`, `?LoggerInterface $logger = null`	指定レベルで PHP `PdfOptimizer` をラップ	`AcceleratedOptimizer`	宣言なし	null クライアントは PHP 経路を選択。null ロガーは `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`	2 つのドキュメントを完全に 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'`	ハンドルを 1 コレクションにバインド	`CpuVectorIndex`	宣言なし	コレクション識別子ごとに 1 ハンドル
`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`。エラーまたは不正形式のカウント応答で `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() はそれぞれのインスタンスをメモ化します。vectorIndex($collectionId) は、与えられたコレクション識別子にバインドされた新しいハンドルを呼び出しごとに返します。isAvailable() は、注入された Core の SpectrumClient を介してサイドカーの到達可能性をプローブします。

バッチ最適化

optimizeBatch は、呼び出し元のドキュメント識別子をキーとするバッチ結果を返します。サイドカーに到達可能な場合、集約ペイロードは、バッファリングやアップロードの前にクライアントバジェットに対して検証されます。上限超過バッチは SpectrumApiException SPEC-SEC-001（HTTP 413）でフェイルクローズドになり、PHP 経路へは決して縮退しません。受理されたバッチは、並列の画像処理のためにサイドカーへディスパッチされます。

受理後のトランスポート、認証、または応答解析の失敗は、各ドキュメントを順次解析する PHP オプティマイザーへ縮退します。縮退は 2 通りで観測可能です。結果メタデータがエンジン 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 でのベクトル検索

各ハンドルは 1 つのコレクション識別子にバインドされ、各コレクションはサイドカー内の個別のインメモリ HNSW インデックスにマッピングされます。build は等長のベクトルと識別子のリストを必要とし、そうでない場合は InvalidArgumentException を発生させます。空入力はサイドカー呼び出しなしに戻ります。search は、各結果のメタデータに 1 始まりの順位を伴うランク付きヒットを返します。インバンドエラーエンベロープは SpectrumApiException を発生させ、コードのないエンベロープは SPEC-INDEX-003 にマッピングされます。delete は、HNSW がベクトルごとの削除をサポートしないため、常に SpectrumApiException SPEC-INDEX-004（HTTP 501、再試行不可）で拒否します。代わりにインデックスを再構築してください。

count はフェイルクローズドかつ曖昧さがありません。到達不能なサイドカーは SpectrumNotAvailableException を発生させ、トランスポートおよびサイドカーのエラーはそのまま伝播します。それ以外は成功した応答において、非 JSON ボディは SPEC-INDEX-005 を、metadata.total_vectors の欠落は SPEC-INDEX-006 を、非整数または負の総数は SPEC-INDEX-007 を発生させます。count は、確認済みの空インデックスに対してのみ 0 を返します。サイズプローブは、ちょうど INDEX_DIMENSION（384）次元のゼロベクトルを top_k 0 で送信するため、次元を検証するサイドカーはこれを受理します。

エッジケースと失敗モード

サイドカーのメモリは揮発性です。再起動するとすべての HNSW コレクションがクリアされます。インデックスの構築は冪等として扱い、再起動後に再実行してください。
単一プロセス内での可用性の混在がサポートされます。オプティマイザーは呼び出しごとに縮退し、埋め込みおよびベクトルのサービスは呼び出しごとにフェイルクローズドになります。
上限超過のオプティマイザーバッチは、いかなるアップロードよりも前にフェイルクローズドになり、PHP 経路へはフォールバックしません。
オプティマイザーのフォールバックは決して静かに失敗しません。結果メタデータのエンジンマーカーを確認し、警告イベントを監視してください。
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 サーフェスのみを文書化します。内部の名前空間パス、ヘルパークラス、メカニズムテーブル、ランブックのファイル名、チケットのプレフィックスは範囲外です。