API コントラクト
型付きエラーエンベロープを含む、HTTP・CLI・Python の完全な契約。
英語版が原文です。
HTTP API は、Python ファサードが使うのと同じ公開 Pydantic 契約の上の トランスポートです。最初の契約は同期かつステートレスです。
| 操作 | 目的 |
|---|---|
GET /health |
プロセスの死活とパッケージバージョン |
GET /v1/capabilities |
現在のバージョン管理された機能・埋め込み空間スナップショット |
POST /v1/plan |
処理判断を実行せずに確認する |
POST /v1/encode |
受け渡された計画を実行する。なければ先に作成する |
POST /v1/embed |
テキストまたは画像のクエリを、選択した埋め込み空間にエンコードする |
計画とエンコードは次のいずれかを受け付けます。
- URI ソースまたは base64 インラインバイトを含む
application/json。 - バイナリの
fileと JSON のrequestフォームパートからなるmultipart/form-data。 このrequestパートはスキーマ上でPlanRequestPart/EncodeRequestPart/EmbedRequestPartです。アップロードされたファイルがソースそのものなので、 JSON リクエストからそのフィールドだけを除いたものになります。生成された クライアントが組み立てられるよう、不透明な文字列ではなく名前付きスキーマです。
クエリ埋め込みは、インラインテキスト、JSON 内の URI/インライン画像、または 同じマルチパートフォームの画像を受け付けます。どちらのトランスポートも 同じドメインモデルへ検証されます。
GET /v1/capabilities は現在のスナップショットを返します。このインストールが
ルーティングできる機能と埋め込み空間、そしてそれらが属するルーティング
ポリシーのバージョンです。
スナップショット ID はコンテンツアドレス方式です。そのため、同じインベントリは
常に同じ識別子を持ち、呼び出し元は自分の環境が変わったことを検出できます。
任意の snapshot_id クエリパラメータで、現在のものではなく、保持されている
特定のスナップショットを再要求できます。保持されていない ID には、黙って別の
インベントリで答えるのではなく 404 が返ります。
機能の可用性は、インストールされているものに従います。プロバイダーの ディストリビューションはエントリポイントで機能を公開するので、インストール することが、機能をここに現す行為そのものです。ロードに失敗したプロバイダーは、 エンドポイントを落とすのではなく省略されます。スナップショット ID は特定の インストールに対して安定であり、リリースをまたいでは安定しません。
成功した計画には次が含まれます。
- 決定的な
plan_idと呼び出し元/リクエスト ID。 - ソースコンテンツのダイジェスト。
- 機能スナップショットとポリシーのバージョン。
- 観察された公開の判断理由とシグネチャの一致。
- ドキュメント既定、ページ上書き、任意のリージョン上書き。
- 順序付きフォールバックと、コスト/レイテンシ/品質の見積もり。
- 明示的な ready または unsatisfied のステータス。
レスポンスは PlanResult です。その計画が plan に、その隣の components に、それを
生み出したディストリビューション — バイト列を取得したローダー、メディアタイプを名付けた
sniffer、証拠を生成したオブザーバー — が、エンコードのトレースと同じ形で載ります。ハッシュ
され束縛されるのは計画だけで、components は診断情報です。encode に渡し戻す計画は plan
フィールドだけです。
非公開の生の事前観察（preflight）特徴量は、ワイヤ契約の一部ではありません。
signature_detection は、インストールされたパーサーにドキュメントを認識するか
尋ねます。一致は、シグネチャ、カバーするスコープ、一致の根拠となった証拠、
ノミネートする機能を報告します。その機能は該当スコープでルートの先頭に立ち、
汎用ラダーはその後ろにフォールバックとして残ります。そのため、誤った
シグネチャの代償はドキュメントではなく、安価な試行 1 回です。confidence は
一致した独立シグナルの割合であり、シグナルが割合であるときはその分だけ数えます
（工程系統図の記号のうちラベルを持つものの割合）。較正された確率ではありません — このリリースには、
ラベル付きコーパスに対して計測されたものは何もありません。ノミネートされた
機能がインストールされていない一致も、そのまま報告されます。認識したものが
消えていても、ドキュメントが認識されたことを知る権利は呼び出し元にあるからです。
その場合、ルートは変わりません。
パーサーだけが宣言するメディアタイプを、signature_detection 未指定で計画すると、
そのパーサーとフラグを名指しした unsatisfied が返ります。ノミネーションは
パーサーの唯一の扉であり、黙って代替する — 全ページを手動レビューへ
ルーティングする — と、パーサーを 1 つも持たないインストールとまったく同じに
見えてしまいます。
POST /v1/encode は任意の plan を受け付けます。存在する場合、そのソース
ダイジェスト、メディアタイプ、スナップショットはリクエストと一致しなければなりません。
エグゼキューターが使えるのは、選択されたルートと宣言済みフォールバック
だけです。黙って再計画することはできません。
metadata も受け付けます。呼び出し側自身のラベル — 所有者、テナント、機密度の
分類 — を入れる自由形式の JSON オブジェクトです。ソースとともに運ばれ、文書
ブロックに載って返り、indx はそのいずれも強制しません。そのベクトルを誰が読める
かはルーターではなくインデックス側の問いです。このフィールドは EncodeRequest
だけにあります。plan_id は決定される計画のすべてのフィールドのハッシュなので、
PlanRequest にラベルを置くと、同一の文書二つが、何もルーティングしない値の
せいで二つの計画を持つことになります。エグゼキューターが書き込むキーはすべて受理せず
拒否します。languages はインストール済みの言語検出器から、classification と
chunk_classification はリクエストが有効にした分類器から、entities は有効にした
エンティティ抽出器から、enrichment と chunk_enrichment は有効にしたエンリッチャーから
書き込まれるもので、静かに置き換えられたラベルは、呼び出し側が運ばれたと信じて
運ばれなかったラベルだからです。
また classification、extraction、enrichment も受け付けます（いずれも既定では不在）。
いずれもインストール済みの実装を単位ごとに ID で名指しします。classification と
enrichment は document_ids、page_ids、chunk_ids を取り、extraction は page_ids と
chunk_ids を取り、各リストは与えられた順に尋ねられます。実装に文書のどれだけを
見せるかを縛るものはありません。それぞれが自分の単位の全文を渡され、縛りが必要なら
自前のものを適用するので、sample フィールドも、その裏にあるデプロイの既定値も
ありません（ADR-0033）。
拒否は三つ、いずれも 422、いずれもソースの取得前です。インストール済みのどの
プロバイダーも宣言しない ID は、宣言されているものを名指しする
unknown_classifier、unknown_extractor、または unknown_enricher です。テキストを外部サービスに
渡すことになるものは、リクエストがその制約を運ぶとき data_residency です。
そして CHUNK 粒度を求めていないリクエストの chunk_ids の項目は
granularity_required です。注釈すべきチャンクが存在せず、空の回答は意見なしと
区別がつかないからです。呼び出し側が名指しできる ID は、機能スナップショットに
コンテンツハッシュの外で載っており、8 つのポートすべてにまたがる 1 つの名前空間なので、
どの 2 つも同じ文字列を共有できません
（DocumentClassifier、
分類器、
エンティティ抽出器、
エンリッチャー）。
レスポンスは、計画、フラットでアドレス可能なブロックツリー、埋め込み空間の
ディスクリプタ、実行トレース、使用量を返します。ブロックはドキュメント、
ページ、リージョン、チャンクの各スコープを表し、id / parent_id で
つながります。
1 ページが何チャンクになるかはインストール依存です。境界はインストールされた
チャンカーディストリビューション（Chunker）が
引き、ページごとに最初の回答が勝ち、indx-chunker-page が読み取り可能な
ページごとに 1 チャンクを保つ床になります。チャンカーを持たないインストールは、
素のインストールがどの URI も解決しないのと同じように、チャンクブロックも
ドキュメントベクトルも返しません。
チャンクブロックは bbox か bbox_reason のどちらか一方を必ず運び、両方や
どちらも持たないことはありません。bbox_reason は no_geometry（チャンカーが
位置を知らない。ワークシート、Word のセクション、テキスト、メール。認識で読まれた
ページは代わりに認識した行ごとの矩形を得る）、hidden（元の文書が図形を非表示にしている。文字は読まれ、何も描かれ
ない）、unresolved（形式は位置を持つが、この図形の位置を解決できなかった）の
いずれかです。テキストレイヤーで読まれた PDF ページと PowerPoint のスライドは
矩形を持ち、それ以外のチャンクは現在すべて no_geometry です。文書ブロックと
ページブロックはどちらのフィールドも持ちません。
文書ブロックの provenance は、そのソースが何として読まれ、どこから来たかを
名指しします — media_type と、URI ソースなら source_uri、名前を伴うインライン
ソースなら filename — すべてのブロックが運ぶ計画の束縛に加えてです。メタデータ
ではなく来歴なのは、用語集がこの辞書をブロックの出所のために予約し、メタデータを
そこから抽出されたもののために予約しているからです。エクスポートされた行は計画が
傍にない状態で出所を述べられなければならず、ダイジェストは誰かが検索するもの
ではありません。
その metadata は、呼び出し側のラベルと、言語検出器がインストールされていれば
languages を運びます。{"language": "ja", "confidence": 0.98} の項目が確信度の
高い順に、読み取り可能な各ページブロックに載り、各スコアが算出されたテキスト量で
重み付けしてページを平均したものが文書ブロックに載ります。素のインストールは何も
検出せず、キーをまったく持ちません
（LanguageDetector）。
リクエストが分類器を有効にしていれば、文書ブロックの metadata は
classification も運びます。{"document_type": [{"label": "invoice", "confidence": 0.9}]}
のように、キーごとに一つのファセット、ラベルは高い順で、あるファセットについて
意見を持つ最初の有効化済み分類器がそれを取ります。ファセット名は分類器自身の
ものであり、何も読めなかった文書はキーを持ちません。ページ分類器は代わりに各ページ
ブロックへ書き、チャンク分類器は文書ブロックの chunk_classification へチャンクブロック ID
で引ける形で書きます。チャンクブロックはメタデータを持たないからです。
リクエストがエンティティ抽出器を有効にしていれば、文書ブロックの metadata は
entities を運びます。見つかったスパンが、それぞれの見つかったブロックで引ける形で
載り、各項目は表層のテキストと、そのブロック自身の text への [start, end) の
文字範囲と、信頼度を持ちます。その傍らに (ラベル, NFKC 正規化した表層形) ごとの
数が、生の表層形を残したまま載ります。数は同一性ではありません — ここでは共参照
解析を一切行いません
（エンティティ抽出器）。
特化機能が抽出したフィールドは、それを述べたブロックの metadata に載ります —
インボイスの番号、日付、金額は invoice キーの下です。金額は数値ではなく
数字の文字列のままです。float に入れた金額は、丸め事故の予備軍だからです。
日付も、ドキュメントが印字した文字列のままです。5/8/2026 を正規化するには
5 月か 8 月かを決める必要があり、ここには発行者のロケールを知るものが
何もないからです。
process-chart シグネチャが認識したスライドは、同じ形でページブロックに process_chart
を載せます。{"title", "nodes": [{"id", "kind", "symbol", "role", "label", "bbox"}], "edges": [{"id", "kind", "from", "to", "arrow", "path"}]} です。ノードの kind は
symbol（symbol は triangle、ellipse、diamond、double_triangle、role は
material、operation、inspection、assembly）、picture、container、text の
いずれかで、エッジは connection（2 つの記号を結ぶコネクタ。arrow はファイルが矢印を
描いたか、path はその両端）か contains（枠と、その中心を囲むノード）です。ID は
shape: にその図形自身の cNvPr id を付けたもので、ファイル内で安定しています。bbox
と path は Block.bbox と同じ正規化の規約なので、ノードはチャンクと同じ計算で重ねられ
ます。シグネチャはページ単位です。一致はスライドを名指しし、process-chart-parser は
そのページのルートだけを先導します。ノードやエッジにない項目は null ではなく省略されます。
スコープを読めなかったブロックは、省略されるのではなく、理由付きの
unreadable または failed を持ちます。トレースは、試行されたすべての機能を
記録します。失敗した機能と、何がそれを止めたのかも含めてです。それが
フォールバックを可視化します。最終的に成功した機能だけを示すトレースは、
フォールバックが存在する理由そのものを隠してしまいます。
トレースの components は、名指しに使える機能 ID を持たずに関与したものを
名指しします。{"role": "chunker", "distribution": "indx-chunker-pdf", "pages": [1, 2]}
のように。役割は loader、sniffer、chunker、language_detector、classifier で、
distribution はそのコンポーネントを宣言したインストール済みパッケージ、pages は
チャンカーが切った、あるいは検出器が答えたページです。分類器はリクエストが名指した
id を、勝ち取った facets の隣に繰り返します。宣言された型のインライン入力は
ローダーも sniffer も名指ししません。何も取得せず何も認識していないからです。
オブザーバーは構造上存在しません。実行は観察しないからです。それは計画レスポンスが
それを運ぶラッパーを得たときに、そちらに属します。
2 つの結果は、意図的にエラーではありません。インストールされたどの機能でも
制約を満たせない計画は、失敗したドキュメントブロックと失敗したトレースを伴う
200 で返ります。何も矛盾しておらず、リクエストは有効だったからです。
呼び出し元の制約をエラー文字列に平坦化すると、呼び出し元が対処できる部分が
失われます。宣言されたすべての機能が失敗したルートは 503 です。ルーティング
ラダーは構造上、手動レビューで終わります。そのためラダーを使い果たすことは、
終端フォールバックを欠いたインストール、または constraints.fallbacks_allowed
を false にした呼び出し側を意味します。このフラグと constraints.capability_ids
の許可リストを使って、リクエストはリーダーを名指しします (ADR-0063)。許可リストの
せいで読むものがなくなったページや、スナップショットにない ID は、capability_ids:
で始まる行を持つ unsatisfied な計画になります。
各ベクトルは自身の embedding_space_id と embedder_id を記録します。
埋め込み空間は、ベクトル次元、距離メトリック、正規化、互換なドキュメント/
クエリ埋め込み器を宣言します。テキストと画像の埋め込み器が空間 ID を
共有するのは、ベクトルが直接比較可能な場合だけです。
クエリ埋め込み
Section titled “クエリ埋め込み”POST /v1/embed は埋め込み空間 ID を必須とします。入力モダリティに対する
その空間のクエリロール埋め込み器を選び、ベクトルと、使用された埋め込み器の
正確な公開設定を返します。プロバイダーの資格情報や非公開エンドポイントが
ディスクリプタに現れることはありません。
スナップショットにない空間、または入力のモダリティに対するクエリロール
埋め込み器を持たない空間 — テキスト専用空間への画像など — は、
type: invalid_embedding_space と、どちらであるかを示す code を伴う 422
です。公開されているのに実行できない埋め込み器、または失敗した埋め込み器は
503 です。埋め込み器にフォールバックラダーはありません。空間を名指しした
呼び出し元は、まさにその空間を求めたからです。
すべてのインストールは default-text を備えます。256 次元の特徴量ハッシュ化
文字トライグラム空間です。これは字面のベースラインです — 文字グラムを共有する
2 つの文字列は近くに落ち、それ以外は近づきません — モデルなしでベクトルが
存在するために提供されるのであって、検索品質のためではありません。
uv sync --all-packages --extra fastembed は fastembed 経由で
minilm-multilingual（384 次元、テキスト）と clip-vit-b32（512 次元、
テキストと画像のクエリを 1 つの比較可能な空間で）を追加します。
--extra hosted はホスト型テキスト空間 hosted-text を追加します。これは
INDX_EMBED_MODEL（LiteLLM のモデル ID）と INDX_EMBED_DIMENSION で設定し、
任意で INDX_EMBED_API_KEY、INDX_EMBED_API_BASE、
INDX_EMBED_TIMEOUT_SECONDS、INDX_EMBED_RETRIES を設定します。次元が発見
ではなく宣言なのは、ベクトルが 1 本も存在する前に空間が次元を述べなければ
ならず、ホスト型プロバイダーは有料でしか答えないからです。ホスト型埋め込み器の
デバイスはビジョンレーンの規則に従います。LiteLLM がこのマシンにルーティング
するモデルは gpu、ホスト型は external であり、data_residency の下でその
空間を名指しする計画リクエストは、ホスト型ビジョンレーンと同じように拒否
されます。ホスト型埋め込み器が報告する課金額は、トレースと使用量の cost_usd
に加算されます。
ドキュメントベクトルは、POST /v1/encode が embedding_space_ids に名指し
された各空間について生成します。チャンクブロックごとに 1 本で、ページブロックと
ドキュメントブロックは持ちません。
チャンクは通常テキストであり、ときにレンダリングされたページです。 どの機能も
テキストとして読めなかったページには切るべき境界がなく、以前は理由を抱えたページ
ブロックだけが残り、検索できるものは何もありませんでした。indx-chunker-pdf は
代わりにそれを 1 つの画像チャンクへレンダリングします。空間は、テキスト埋め込み器を
名指しすることではなく、実行が生成するものによって選択されます。そして実行が生成
するものが DOCUMENT_EMBEDDING_MODALITIES — (text, image) — であり、この順序が
あるため、読めたページがレンダリングの費用まで払うことはありません。したがって
ドキュメントロールの埋め込み器が画像しか読まない空間もルーティング可能です。
レンダリングされたページにちょうど答え、1 つのドキュメントが 1 つの空間の中に
テキストベクトルと画像ベクトルを併せ持てます。いまも unsatisfied になるのは、
ドキュメントレーンを一つも宣言していない空間で、実際には持っているテキスト
埋め込み器の欠如を報告するのではなく、この実行が生成するドキュメント入力を
埋め込めないと述べます。クエリレーンはこのいずれの制約も受けません。
すべての失敗は、type、code、message、任意の param、任意の request_id
を含む、1 つの型付きエンベロープを使います。操作に到達する前にルーターが
送出するトランスポートレベルの失敗も含まれます。未知のパスは 404、誤った
メソッドは 405 で、どちらも type は http_error、code は not_found
または method_not_allowed です。これらはどの操作にも属さないため、OpenAPI
ドキュメントの操作ごとのレスポンスには列挙されません。
| ステータス | 意味 |
|---|---|
404 |
固定指定された機能スナップショット ID が保持されていない（GET /v1/capabilities） |
409 |
受け渡された計画がソースまたは機能スナップショットと一致しない |
413 |
リクエストがサーバーの公開する入力上限を超えている |
415 |
コンテンツタイプが未対応、インストールされたどのローダーもソース URI スキームを解決しない（unsupported_source）、またはインストールされたどの機能もそのメディアタイプを読まない |
422 |
リクエスト検証の失敗、ソースが期待されたバイト列に解決されない（source_unreadable）、このサーバーに渡されていないパスワードを必要とする（source_encrypted）、ローダーのガードが取得を拒否する宛先を名指ししている（source_forbidden）、インストール済みのどれも生成しないブロック粒度を要求している（unsupported_granularity）、または埋め込み空間が要求どおりにリクエストを処理できない |
500 |
サーバーが型付けしなかったエラー。メッセージは汎用で、X-Request-ID ヘッダーがログ行を特定する |
501 |
契約は存在するが、アプリケーション実装がまだ入っていない |
503 |
宣言された機能が一時的に利用できない |
504 |
リクエストが INDX_REQUEST_TIMEOUT_SECONDS を超えた、または作業完了前に呼び出し元が切断した |
すべてのレスポンスは X-Request-ID ヘッダーを持ちます。値は呼び出し元が
送ったもの、またはサーバーが生成したものです。これは、そのリクエストが生んだ
すべてのログ行の相関 ID であり、エンベロープの request_id とは別物です。
後者はリクエストボディに由来する呼び出し元自身の識別子で、ボディが持って
いた場合は常にエコーされます — 検証失敗のときも含めてです。param は、失敗
したフィールドの、pydantic が報告するドット区切りの位置です。判別共用体の
メンバーは、そのタグをセグメントとして持ちます（{"type": "uri"} ソースの
空の uri は source.uri.uri）。body は、ボディが JSON でなかったことを
意味します。
INDX_REQUEST_TIMEOUT_SECONDS は、リクエストが計画、実行、埋め込みに費やせる
時間を制限します。未設定または 0 は無制限です。期限は、ソースのロード完了時に
1 回、その後は機能の試行と試行の間に確認されます。試行の内部では決して確認
されません。したがって、ソースの取得や実行中の機能呼び出しは、504 が答え
られる前に完了します。タイムアウトと切断は作業を停止します。別のルートへ
フォールバックすることは決してありません。
入力上限は、機能スナップショットの limits.max_input_bytes として公開され、
デプロイごとに INDX_MAX_INPUT_BYTES で設定されます。制限するのはデコード済み
ソースバイトであり、エンコードされたリクエストボディではありません。
スナップショットのコンテンツハッシュから意図的に除外されているため、上限を
引き上げても既存の計画は無効になりません。
resolvable も同じ理由で除外されていますが、同じ種類のものではありません。
これは、このインストールが到達できるもの — resolvable.schemes — と、
観察できるもの — resolvable.observable_media_types — を報告します。どちらも、
設定の変更ではなくディストリビューションのインストールによって増えます。
どちらが増えても、次に計画できるものが広がるだけで、進行中のどの計画の選択も
変わりません。これらをハッシュに含めると、ルーティングと無関係な理由で、進行中の
すべての計画に 409 を返すことになります。
計画の見積もりは、機能 kind ごとの既定値から始まり、デプロイが
INDX_ROUTING_ECONOMICS で補正します。これは機能 ID または kind をキーとする
JSON オブジェクトへのパスで、値は quality、cost_usd_per_page、
latency_ms_per_page を設定できます。ID は kind に勝ちます。quality は 0 から 1 の間、
残る 2 つは 0 以上で、latency_ms_per_page はミリ秒の整数です。この数値は非公開の
ルーティング入力であり、ワイヤ契約の一部ではありませんが、estimates を動かし、
制約付きリクエストが受け取るルートを変え得ます。そのため、不正なファイルは
無視されるのではなく拒否されます。未知のフィールドも、小数の latency も同じです。
この変数が運用者側にあるのは、自分の価格を宣言できる機能は、その価格でルートを
買えてしまうからです。請求を払うデプロイこそが、正直である理由を持つ当事者です。
そのコストは実在し、隠されてもいません。1 ページ $0.05 を課金するホスト型 OCR
も、OCR の既定値 $0.0005 のまま maximum_cost_usd に対して受理され、それを
estimates.cost_usd として公開します — 誰かがこのファイルに実際の数値を書き込む
までは。特定のインストールは機能 ID で、作業のクラス全体は kind で補正します。
認識エンジンは extras の背後で出荷されます。そのためデフォルトのインストールは、
ONNX ランタイムもモデル重みも資格情報も持たない、ルーターとネイティブ抽出
レーンです。uv sync --all-packages --extra ocr は onnxruntime 経由で PP-OCR を
追加します。--extra vlm は LiteLLM 経由のビジョンレーンを追加します。
インストールが持たないものは、理由付きで利用不能として公開されます。ルーティング
ラダーは、リクエストを失敗させるのではなく、それを通り越して降りていきます。
ビジョンレーンは INDX_VLM_MODEL（LiteLLM のモデル ID）、任意の
INDX_VLM_API_KEY と INDX_VLM_API_BASE、そして
INDX_VLM_TIMEOUT_SECONDS / INDX_VLM_RETRIES / INDX_VLM_DPI で設定します。
OCR レーンは INDX_OCR_DPI を受け取り、PP-OCR 自身の行ごとのスコアを、各スコアが
与えられた行の長さで重み付けして、ページの confidence として報告します。これは
認識のスコアであって、再現率のスコアではありません。検出器がボックス化しなかった
テキストは、数値に不利に数えられるのではなく、数値から欠けています。 ラスタの 2 レーンは INDX_OCR_MAX_PIXELS と INDX_VLM_MAX_PIXELS（既定 178956970。Pillow 自身の展開爆弾の上限）も取ります。レーンの DPI でそれより多くのピクセルにラスタライズされるページは、ビットマップができる前に拒否され、未読として返されるので、計画の次のラングがそのページを受け取ります。
INDX_TEXT_ENCODING はテキストレーンのもので、カンマ区切りの順序付きリストです
（既定は utf-8-sig）。各名前は厳密に試され、最初にデコードできたものが採用されます。
どれにも一致しないソースは、最後に試したものへ無理に押し込まれるのではなく失敗し、
Python が知らないエンコーディングは、ソースが悪いと報告するのではなくメッセージで
変数名を示します。これが必要なのは、日本の公的機関の CSV が圧倒的に Shift_JIS だから
です。気象庁も東京都オープンデータも CP932 で配信しており、それらを読む環境は
utf-8-sig,cp932 を設定します。UTF-8 が先頭なのは、それが強い判定だからです。任意の
バイト列が妥当な UTF-8 になることはまれである一方、CP932 はほとんど何でもデコードして
しまうため、UTF-8 のファイルが文字化けとして読まれるのを防いでいるのは順序です。既定が
utf-8 ではなく utf-8-sig なのは、BOM のないファイルには同じコーデックであり、BOM の
あるファイルからはそれを取り除くからです。
INDX_CHUNK_DPI（既定 120）はこれらの 3 つ目で、indx-chunker-pdf に属します。
どの機能もテキストとして読めなかったページを 1 つの画像チャンクにレンダリングし、
そのページがベクトルを持てるようにするためのものです。他の 2 つと同様に呼び出しごとに
読まれます。正の整数でない値は既定値に戻らず raise しますが、その raise はエンコードを
失敗させません。エグゼキューターは警告をログに残してその文書ではこのチャンカーを飛ばし、
代わりにページフロアがチャンクするため、設定ミスはログと粗いチャンクに現れます。
INDX_LANGUAGE_CANDIDATES、INDX_LANGUAGE_MINIMUM_CONFIDENCE（既定 0.05）、
INDX_LANGUAGE_LOW_ACCURACY は lang エクストラの背後にある
indx-language-lingua のものです。候補リストはカンマ区切りの ISO 639-1 コードで、
未設定は 75 言語すべてを意味します。正直ですが高価です。読み込む言語はどれも
メモリを消費し、考慮する言語はどれも短いページについて自信たっぷりに誤る道を
一つ増やすからです。下限は飾りではありません。エンジンは構築時に与えられた
すべての言語について値を返すため、下限がなければページは 75 項目を運び、その
74 項目はノイズです。
INDX_NER_PATTERNS_GAZETTEER は indx-ner-patterns に {label: [surface, ...]} の JSON
オブジェクトを指し示します。同梱のパターンの隣で、文字どおりに、長いものから照合されるので、
デプロイの顧客一覧や製品名が、選んだラベルのスパンとして返ります。未設定はパターンだけです。
INDX_NER_VIBRATO_DICTIONARY と INDX_NER_VIBRATO_CACHE は ja エクストラの背後にある
indx-ner-vibrato のものです。前者はコンパイル済みの vibrato 辞書（system.dic または
system.dic.zst）を名指しし、このレーンがそうでなければ後者（既定 ~/.cache/indx-ner-vibrato）へ
一度だけダウンロードして読むたびにダイジェストで検証する IPADIC リリースを置き換えます。
エクストラがなければ、このディストリビューションは抽出器をまったく公表しません。
INDX_NER_ONNX_MODEL（既定 Xenova/bert-base-multilingual-cased-ner-hrl）、
INDX_NER_ONNX_MODEL_FILE（既定 onnx/model_quantized.onnx）、INDX_NER_ONNX_MAX_TOKENS
（既定 512）、INDX_NER_ONNX_WINDOW_CHARACTERS（既定 400。モデルに一度に見せるテキストの量で、
空白で切ります）、INDX_NER_ONNX_MINIMUM_CONFIDENCE（既定 0.5。スパンに必要なトークンスコアの
平均）は ner エクストラの背後にある indx-ner-onnx のものです。重みは最初の使用時に Hugging Face
のキャッシュへダウンロードされ、検出中には決してダウンロードされません。エクストラがなければ、
このディストリビューションは抽出器をまったく公表しません。
INDX_NER_LLM_MODEL、INDX_NER_LLM_API_KEY、INDX_NER_LLM_API_BASE、
INDX_NER_LLM_TIMEOUT_SECONDS（既定 60）、INDX_NER_LLM_RETRIES（既定 1）、
INDX_NER_LLM_MAX_CHARACTERS（既定 6000）、INDX_NER_LLM_LABELS（既定
person,organization,location,date,money,invoice_number。モデルに尋ねるラベル）は llm
エクストラの背後にある indx-ner-llm のものです。独自の接頭辞なので、デプロイは分類とは別の
モデルで抽出できます。モデルがなければ、このディストリビューションは抽出器をまったく公表しません。
モデルは表層形を答え、レーンがそれぞれをテキスト中で探します。デバイスの規則は LLM 分類器のものです。
INDX_ENRICH_EXTRACTIVE_SENTENCES（既定 3。要約を成す文の数）と
INDX_ENRICH_EXTRACTIVE_MAX_CHARACTERS（既定 600。その上限で、空白の境界で切る）は、既定
インストールが持つエンリッチャー indx-enrich-extractive のものです。折り返された行はつなぎ直され、
文はどちらの言語の終端記号でも終わります。選ばれるのはテキスト自身の語彙を最も多く運ぶ文で、語の頻度に
冗長性のペナルティを加えて選び、そのまま文書の順に返します。順位付けするものがないテキスト、短い
フィールドだけの帳票は、先頭の行を得ます。タグは作りません。
INDX_ENRICH_LLM_MODEL、INDX_ENRICH_LLM_API_KEY、INDX_ENRICH_LLM_API_BASE、
INDX_ENRICH_LLM_TIMEOUT_SECONDS（既定 60）、INDX_ENRICH_LLM_RETRIES（既定 1）、
INDX_ENRICH_LLM_MAX_CHARACTERS（既定 6000）、INDX_ENRICH_LLM_SUMMARY_SENTENCES（既定 2。
モデルに求める要約の長さ）、INDX_ENRICH_LLM_TAGS（既定 5。タグの最大数）は llm エクストラの
背後にある indx-enrich-llm のものです。独自の接頭辞なので、デプロイは分類とは別のモデルで要約できます。
1 回の呼び出しが両方の部分を答えます。モデルがなければ、このディストリビューションはエンリッチャーを
まったく公表しません。デバイスの規則は LLM 分類器のものです。
INDX_CLASSIFIER_WORDS_LABELS は indx-classifier-words に、同梱のものを置き換える
JSON タクソノミーを指し示します。ラベルのファセットで、各ラベルは ja と en の
名前、それに票を投じる単語、しきい値 — 異なる単語の整数個数、またはリストの割合 —
を持ちます。未設定は、日本語と英語のビジネス文書向けに同梱される文書種別・部門・
業種の表を意味します。確信度は一致したリストの割合であり、較正された確率では
ありません。
INDX_CLASSIFIER_ZEROSHOT_MODEL（既定は
MoritzLaurer/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7 の Xenova ONNX ミラー）、
INDX_CLASSIFIER_ZEROSHOT_MODEL_FILE（既定 onnx/model_quantized.onnx）、
INDX_CLASSIFIER_ZEROSHOT_HYPOTHESIS（既定 This document is a {}.）、
INDX_CLASSIFIER_ZEROSHOT_MINIMUM_CONFIDENCE（既定 0.5）、
INDX_CLASSIFIER_ZEROSHOT_MAX_TOKENS（既定 512）、INDX_CLASSIFIER_ZEROSHOT_LABELS は
zeroshot エクストラの背後にある indx-classifier-zeroshot のものです。各ラベルは
テキストに対する一つの仮説になり、含意確率がそのラベルの確信度です。トークン窓は
このレーン自身の縛りなので、モデルは文書の先頭を読みます。重みは最初の使用時に
Hugging Face のキャッシュへダウンロードされ、検出中には決してダウンロードされません。
INDX_CLASSIFIER_LLM_MODEL、INDX_CLASSIFIER_LLM_API_KEY、INDX_CLASSIFIER_LLM_API_BASE、
INDX_CLASSIFIER_LLM_TIMEOUT_SECONDS（既定 60）、INDX_CLASSIFIER_LLM_RETRIES
（既定 1）、INDX_CLASSIFIER_LLM_MAX_CHARACTERS（既定 6000。契約は何も縛らないので、
モデルに見せる文書の先頭の長さ）、INDX_CLASSIFIER_LLM_LABELS は llm エクストラの背後にある
indx-classifier-llm のものです。モデルがなければ、このディストリビューションは
壊れた分類器ではなく分類器をまったく公表しません。ホスト型埋め込みの規則です。
分類器の device は下の規則に従います。LiteLLM がこのマシンにルーティングする
モデルは gpu、ホスト型は external で、data_residency を運ぶリクエストが
有効にできるのは前者だけです。ベンダーが請求した額は usage.cost_usd に届きます。
これらはどれもワイヤに現れませんが、モデル ID はワイヤに現れる 1 つのことを
決めます。LiteLLM がこのマシンにルーティングするモデル（ollama/…、または
localhost の api_base）は gpu デバイスとして、ホスト型は external として
宣言されます。そのため、data_residency を持つリクエストは、ローカルのビジョン
レーンを保持したまま、ホスト型のレーンを正しく拒否されます。したがって、設定
されたモデルの変更は機能スナップショット ID を変えます。それこそが狙いです。
計画が判断の前提としたデータ所在の保証は、もはや同じ保証ではないからです。
INDX_VALIDATION_MIN_CONFIDENCE は、デプロイがそれ未満の出力を拒否する
confidence で、既定値は 0.0 — 無効です。機能がこの床未満のスコアを付けた
ページは、未読として扱われます。計画の次の機能へ降り、その出力は破棄され、
トレースは計測値を床と並べて記録します。床を上げることは、金銭とレイテンシで
精度を 1 段ずつ買うことです。だからこそ、ここでは誰も数値を選んでくれません。
このリポジトリのどの閾値も、ラベル付きコーパスに対して計測されていないからです。
床自体はワイヤに現れませんが、比較対象は現れます。trace.events[].quality は、
そのイベントがカバーするページについて機能が主張した値です — ページスコープの
イベントはそのページ自身のスコアを持ち、ドキュメントスコープのイベントは、
代表するグループの平均を持ちます — そして actuals.quality はドキュメント
全体の平均です。どちらも actuals.cost_usd とまったく同じ立場の自己申告で
あって、正解データに対する計測ではありません。何も報告されなければ null です。
ソースは、常に機能するインラインの base64 か、インストールされたローダーが
スキームを解決する URI で届きます。indx が出荷する 4 つ — file、data、
http、https — は indx-loader-file と indx-loader-http に由来し、他と
同じインストールされたディストリビューションです。したがって、解決可能な集合は
indx の性質ではなくインストールの性質です。GET /v1/capabilities は
resolvable.schemes として報告し、素の pip install indx はどれも解決しません。
ソースのメディアタイプは、宣言された値を信用する前に、そのバイト列から認識
されます — 同じインストール済みオブザーバーによってであり、認識もまたインストール
依存になるのはそのためです。オブザーバーを一つも持たないインストールは、宣言された
Content-Type を、次いでファイル名を信じます。
ここには 3 つの拒否があります。すべてインストール依存で、意図的に区別可能です。
インストールされたどのローダーも解決しないスキームは、コード
unsupported_source の 415 です。これが最初に来ます。バイト列が届くまで、
他には何も起こり得ないからです。インストールされたどの機能も読まないメディア
タイプは、そのコードなしの 415 です。インストールされたどのオブザーバーも見る
ことができないメディアタイプは、事前観察（preflight）からの、コード
source_unreadable の 422 です。したがって、同じソースが、あるインストールでは
拒否され、別のインストールでは計画されることがあります。GET /v1/capabilities
は、読めるものを capabilities に、到達できるものと観察できるものを
resolvable に列挙します。
ローダーは、取得できたはずの宛先を拒否することもあります。コード
source_forbidden の 422 です。indx-loader-http は、
INDX_LOADER_HTTP_ALLOW_PRIVATE_HOSTS が設定されない限り、ループバック、
プライベート、リンクローカル、予約済み、マルチキャストの各アドレスを拒否します。
リダイレクトのホップごとに再確認し、話せないスキームへのリダイレクトを拒否
します。INDX_LOADER_HTTP_TIMEOUT_SECONDS が取得を制限します。
indx-loader-file は、INDX_LOADER_FILE_ROOTS が読み取ってよいディレクトリを
名指しするまで、このプロセスが読めるあらゆるパスを読みます。名指しされた後は、
その外に解決されるものをすべて拒否します。どちらの場合も、メッセージは許可する
変数を名指しし、実際に何へ解決されたかはサーバーログが持ちます — レスポンスは
持ちません。ホスト名がどの内部アドレスに解決されるかを呼び出し元に教えることは、
SSRF プローブが求めているものそのものだからです。
両ローダーの上には INDX_URI_SCHEMES があり、スキームを振り分ける indx-source
が読みます。未設定なら、インストール済みローダーが宣言するすべてのスキームを解決
します。設定されていれば、列挙されたスキームだけを解決します。none は URI ソース
をすべて無効にし、認証のない公開ホストはこれで動きます。インストール済みでも有効
化されていないスキームは、どのローダーも名乗らないスキームと同じ 415
unsupported_source で、メッセージが変数を名指しします。スナップショットの
resolvable.schemes はインストール済みの集合ではなく有効な集合を広告するので、
クライアントは最初のリクエストの前に URI レーンがあるかどうかを知ることができます。
インラインのソースは影響を受けません。手渡されたバイト列は取得されたものではないから
です。ルートはこの下でも第二の層として意味を保ちます — 後から file を有効にした
デプロイでも、名指ししたディレクトリしか読みません。
indx-loader-s3 は s3://bucket/key を URI ごとに 1 オブジェクトとして解決します。
boto3 は s3 エクストラの背後にあり、エクストラなしでもスキームは広告されたまま、
取得は indx-loader-s3[s3] のインストールを求める 422 source_unreadable に
なります。認証情報は INDX_LOADER_S3_ACCESS_KEY_ID と
INDX_LOADER_S3_SECRET_ACCESS_KEY（ロールの一時キーがトークンを伴う場合は
INDX_LOADER_S3_SESSION_TOKEN）から取り、これらが未設定なら boto3 自身の
チェーン — AWS_* 変数、プロファイル、インスタンスロール — が適用されます。
この二層目は意図的です。EC2 や EKS 上のデプロイがシークレットを複製せずに
ロールを使えるようにするためで、INDX_LOADER_S3_BUCKETS が存在する理由でも
あります。カンマ区切りの許可リストで、未設定は INDX_LOADER_FILE_ROOTS と同じく
任意のバケットを意味し、設定後は他のバケットを名指しする URI が 422
source_forbidden になります。メッセージには変数名が、ログには設定された
リストが載ります。INDX_LOADER_S3_ENDPOINT_URL は S3 互換サーバーを指し、
パス形式のアドレッシングを強制します。INDX_LOADER_S3_REGION は設定時に
そのまま渡され、INDX_LOADER_S3_TIMEOUT_SECONDS が接続と読み取りを制限します
（既定 30 秒）。?versionId= クエリは黙って落とされるのではなく拒否されます。