Executor
実行のポート — 計画を、ブロック・埋め込み・トレースへ。
英語版が原文です。
ポート: encode(request: EncodeRequest) -> EncodeResult。indx.encode() として呼ばれます。拡張点ではなくステージなので、Executor プロトコルは宣言されていません。DocumentExecutor が唯一の実装であり、このワークスペースの外に別の実装はありません。
Executor は、ルート計画を処理済みのドキュメントデータへ変換するための境界です。ソース、出力と埋め込みの指定、制約、省略可能な計画を受け取ります。使用した計画、アドレス可能なブロックツリー、埋め込み空間の記述、実行トレース、集計済みの使用量を返します。
実行は各スコープで選択された機能を呼び出し、計画に宣言された順序付きフォールバックだけを通って進むことができます。実際に何が動いたかを記録し、completed、failed、unreadable の結果を区別します。
エグゼキューターは、高価で失敗しやすい作業を計画から切り離しておきます。プランナーは決定的で検査可能なままでいられ、実行は実際のレイテンシ、コスト、品質、リソース使用、検証結果、フォールバックの振る舞いを報告できます。
計画を実行の境界として扱うことは、呼び出し側の意図も守ります。受け渡された計画は、ソースとスナップショットに適合するか、拒否されるかのどちらかです。新しく選び直したルートに黙って差し替えられることは決してありません。
入力は
EncodeRequest
で、リクエスト ID、ソース、制約、要求された粒度、埋め込み空間 ID、シグネチャ検出フラグ、省略可能な RoutePlan、そして metadata — 呼び出し側自身のラベルで、文書ブロックに載って返り、どこでも強制されません — を運びます。このフィールドは EncodeRequest にあり、意図的に PlanRequest にはありません。plan_id は決定される計画のすべてのフィールドをハッシュするため、テナントラベルがあると、同一の文書二つが、何もルーティングしない値のせいで二つの計画を持つことになります。languages と classification のキーは拒否されます。これらはインストール済みの言語検出器と、リクエストが classification で有効にした分類器 — 尋ねる順に並んだ ID を単位ごとに名指ししたもの — からエグゼキューターが書き込むものです。entities も同じく拒否されます。これはリクエストが extraction で有効にしたエンティティ抽出器からエグゼキューターが書き込みます。注釈が文書のどれだけを見せられるかを定めるものはありません。それぞれが自分の単位の全文を渡され、縛りが必要なら自前のものを適用します。
注釈はソースの取得前に拒否され、実行の途中では拒否されません。インストール済みの何も宣言しない ID は、宣言されている ID を列挙する 422 です。data_residency 制約の下で device が external の実装は、黙って省かれるのではなく 422 です。そして CHUNK 粒度を求めずにチャンク対象の分類器や抽出器を名指しすることも 422 です。注釈すべきチャンクが存在せず、空の回答は意見なしと区別がつかないからです。最後のものは REGION がすでに受けているのと同じ拒否であり、理由も同じです。
出力は
EncodeResult
で、次を運びます。
- リクエスト ID とドキュメント ID、そして実際に使用された計画そのもの。
- アドレス可能なドキュメント、ページ、リージョン、チャンクの各ブロック。
- それらのブロック上のテキスト、メタデータ、来歴、ステータス、埋め込み。文書ブロックの来歴は、由来する計画に加えてメディアタイプとソース URI またはファイル名を名指しします。そのメタデータは呼び出し側のラベルと、検出器がインストールされていればその文書が読まれた言語、リクエストが分類器を有効にしていればラベル付けされたファセット、そしてエンティティ抽出器を有効にしていれば見つかったスパンを、それぞれが見つかったブロックで引ける形で、文書レベルの数とともに運びます。
- ベクトルの解釈に必要な、完全な埋め込み空間ディスクリプタ。
- 計画された機能と実際に動いた機能を特定する、スコープ付きの実行トレース。
- バイト数、ページ数、コスト、レイテンシ、品質、リソース使用の集計。
- リクエストが計画を渡さないときは、機能の実行前に、合成されたエンコードワークフローを通じて計画を取得する。
- 受け渡された計画を、ソースダイジェスト、メディアタイプ、機能スナップショットに対して検証する。
- 計画が明示的に宣言した選択済み機能またはフォールバックだけを実行する。
- 返すブロックツリーで、スコープと親子関係を保持する。
- すべてのベクトルを埋め込み空間 ID と埋め込み器 ID で識別し、宣言されたベクトル次元を守る。
- 各トレースイベントに、実際の機能、デバイス、フォールバックインデックス、検証、レイテンシ、コスト、品質を記録する。
- 読めないスコープと終端の失敗を、黙ってコンテンツを省くのではなく明示的に報告する。
unsatisfied な計画は報告されるものであり、例外にはなりません。何も矛盾しておらず、リクエストは有効でした。呼び出し側の制約が、インストールされているもので満たせないだけです。その結果は、理由を運ぶ failed なドキュメントブロックと、同じことを述べる failed なトレースになります。制約をエラー文字列に平坦化せず、見える状態に保つためです。
機能が生成したものの検証はファーストパーティであり、宣言されたポートではありません。検証は、ラングに渡されたすべてのページについて 3 つの問いを立てます。そのページに対して何かが返ってきたか。機能がそのページを failed と宣言したか。そして、このデプロイが INDX_VALIDATION_MIN_CONFIDENCE に設定した下限を下回る信頼度を報告したか — この値は、運用者が自身の出力に対して測定した値を設定しない限り 0.0（無効）です。3 つのいずれかに該当すると、そのページが、そしてそのページだけが次のラングへ送られ、拒否された出力は置き換えの隣に残されるのではなく破棄されます。unreadable ステータスは意図的にこの 3 つに含まれません。それは試行についてではなく、コンテンツについての判定だからです。
すべての機能が失敗したルートは 503 です。ルーティングラダーは構造上、手動レビュー（manual review）で終わります。したがってラダーを使い果たすということは、終端フォールバックを取り除いたインストールを意味します。それは呼び出し側に伝えるべきデプロイの欠陥であり、ページの欠けたドキュメントを黙って返すべきものではありません。
このプロトコルは、アダプターの内部や、合成サービスが欠けた計画をどう取得するかを規定しません。それらの選択は境界の内側にとどまります。
システム内の位置
Section titled “システム内の位置”公開の indx.encode() ファサードと POST /v1/encode オペレーションは、エンコードワークフローを公開します。エグゼキューターは計画の判断と機能の実装を消費しますが、返すのは公開の indx-interfaces 契約だけです。