API コントラクト
型付きエラーエンベロープを含む、HTTP・CLI・Python の完全な契約。
英語版が原文です。
HTTP API は、Python ファサードが使うのと同じ公開 Pydantic 契約の上の トランスポートです。契約は同期で、デプロイが保存を選んだ文書を除けばステートレスです （保存した文書）。
| 操作 | 目的 |
|---|---|
GET /health |
プロセスの死活とパッケージバージョン |
GET /v1/capabilities |
現在のバージョン管理された機能・埋め込み空間スナップショット |
POST /v1/plan |
処理判断を実行せずに確認する |
POST /v1/encode |
受け渡された計画を実行する。なければ先に作成する |
POST /v1/embed |
テキストまたは画像のクエリを、選択した埋め込み空間にエンコードする |
POST /v1/documents |
文書をエンコードし、失効まで呼び出し元のために保存する |
GET /v1/documents |
呼び出し元が保存した文書を一覧する |
GET /v1/documents/{digest} |
保存した文書を結果全体とともに読む |
GET /v1/documents/{digest}/source |
保存した文書を読んだ元のファイルをダウンロードする |
DELETE /v1/documents/{digest} |
保存した文書を今すぐ忘れる |
POST /v1/search |
呼び出し元が保存したチャンクを語と意味で検索する |
計画とエンコードは次のいずれかを受け付けます。
- 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 は有効にしたエンリッチャーから、lanes はその 3 つすべてから
書き込まれるもので、静かに置き換えられたラベルは、呼び出し側が運ばれたと信じて
運ばれなかったラベルだからです。
また 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、
分類器、
エンティティ抽出器、
エンリッチャー）。
chunking は最初に尋ねるチャンカーを名指します。{"chunkers": [{"id": "pdf", "version": 2}]} で、
バージョンは任意です。これは置き換えではなく優先です
（ADR-0068）。
名指しされたチャンカーが順に先頭に立ち、それらが主張しなかったページにはインストールの順序が
そのまま応えるので、PDF のチャンカーを名指してもスライドには何の代価もありません。バージョンのない
ID は、このインストールが既定で尋ねるバージョン（スナップショットが chunkers で default と
示すもの）を、それがなければ最新を意味します。default でないバージョンは、それを名指す
リクエストでだけ走ります。拒否は 422 invalid_chunker で、ほかと同じく取得の前です。
unknown_chunker と unknown_chunker_version はそれぞれインストール済みのものを名指し、
granularity_required はチャンカーを名指しながらチャンクを求めなかったリクエストです。
トレースのチャンカーのコンポーネントが、どのバージョンが各ページを切ったかを示します。
公表される各組は default の隣に media_types（チャンカーが切るタイプ。空なら任意）と
summary（そのバージョンでチャンクが何であるかを言う 1 句）を運びます。どちらも文書に対して
バージョンを選ぶ呼び出し側のためのもので、リクエストをゲートしません。
レスポンスは、計画、フラットでアドレス可能なブロックツリー、埋め込み空間の
ディスクリプタ、実行トレース、使用量を返します。ブロックはドキュメント、
ページ、リージョン、チャンクの各スコープを表し、id / parent_id で
つながります。
1 ページが何チャンクになるかはインストール依存です。境界はインストールされた
チャンカーディストリビューション（Chunker）が
引き、ページごとに最初の回答が勝ち、indx-chunker-page が読み取り可能な
ページごとに 1 チャンクを保つ床になります。チャンカーを持たないインストールは、
素のインストールがどの URI も解決しないのと同じように、チャンクブロックも
ドキュメントベクトルも返しません。
チャンクブロックは bbox か bbox_reason のどちらか一方を必ず運び、両方や
どちらも持たないことはありません。bbox_reason は no_geometry（チャンカーが
位置を知らない。ワークシート、Word のセクション、テキスト、メール。認識で読まれた
ページは代わりに認識した行ごとの矩形を得る）、hidden（元の文書が図形を非表示にしている。文字は読まれ、何も描かれ
ない）、unresolved（形式は位置を持つが、この図形の位置を解決できなかった）の
いずれかです。テキストレイヤーで読まれた PDF ページと PowerPoint のスライドは
矩形を持ち、それ以外のチャンクは現在すべて no_geometry です。文書ブロックと
ページブロックはどちらのフィールドも持ちません。
チャンカーがチャンクの正体を判別できるとき、チャンクブロックは layout も運びます
（ADR-0070）。
paragraph か table の role と、表ならその rows、columns、header_rows、cells です。各セルは
1 始まりの row と column、結合の幅、text、形式が位置を持つ場合の bbox を述べます。チャンクの
text は素のレンダリング（表の行は 1 行ずつ、セルはタブ区切り）のままなので、text だけを読むものは
何も変わりません。無いときは、チャンカーが述べなかったということです。
文書ブロックの 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 正規化した表層形) ごとの
数が、生の表層形を残したまま載ります。数は同一性ではありません — ここでは共参照
解析を一切行いません
（エンティティ抽出器）。
これらのキーが持つのはマージ、つまり各レーンが勝ち取ったものです。負けた答えも含めた
各レーンの答え全体は、その隣の lanes に載ります。{レーン ID: {...}} の形で、{...} は
そのレーンが答えた上のキーを同じ形で持ち、entities の数はそのレーンのスパンだけから
数えます。文書ブロックに載り、ページ分類器とページエンリッチャーの分は各ページブロックに
載ります。意見のないレーンには項目がなく、どのレーンも答えなかったブロックには lanes
キーがありません。リクエストが名指すレーンは、先のレーンがすべてのファセットを取っていても
すべて尋ねられ、課金されます
（ADR-0079）。
特化機能が抽出したフィールドは、それを述べたブロックの 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", "id": "pdf", "version": 1, "pages": [1, 2]}
のように。チャンカーは id と version を述べます。スナップショットがコンテンツハッシュの外の
chunkers に公表する組です。ほかの役割は version を持ちません。役割は 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 になるのは、
ドキュメントレーンを一つも宣言していない空間で、実際には持っているテキスト
埋め込み器の欠如を報告するのではなく、この実行が生成するドキュメント入力を
埋め込めないと述べます。クエリレーンはこのいずれの制約も受けません。
保存した文書
Section titled “保存した文書”レコードストアとベクトルインデックスを名指すデプロイは、呼び出し元がエンコードしたものを、呼び出し元
ごとに分けて、TTL が尽きるまで保存します（ADR-0071）。どちらも名指さない
デプロイは何も保存せず、以下のすべてのルートは 404 store_disabled を返します。
POST /v1/documents は POST /v1/encode と同じ本文（JSON またはマルチパート）を受け取って実行し、
201 と StoredDocument を返します。これはサマリー（ダイジェスト、名前、メディアタイプ、ページ数と
チャンク数、ベクトルが属する空間、作成・更新・失効の時刻）と EncodeResult 全体を並べたものです。
name はクエリパラメーターで、既定はアップロードしたファイルの名前です。呼び出し元の中で文書は
ソースダイジェストなので、同じバイト列を再び保存すると置き換わり、TTL が再び始まります。
ソースストアも名指すデプロイは、文書を読んだ元のソースを、同じ呼び出し元の下で同じ失効時刻まで保存します。 データセットに集めた文書を読み直せるようにするためです （ADR-0081）。 未設定なら、これまでどおりソースは読んだあと捨てます。
GET /v1/documents/{digest}/source は、保存した呼び出し元に元のバイトを、保存したときのメディアタイプで
返します（ADR-0084）。
応答は常に Content-Disposition: attachment（ファイル名は filename*）と X-Content-Type-Options: nosniff
を持ち、ブラウザーはアップロードされたファイルを保存するだけで描画しません。保存した文書のサマリーは
source_kept を持ち、デプロイがバイトを保存したときに真です。URI から保存した文書では偽です。別の
呼び出し元の文書、保存されたことのない文書、URI のソース、ソースを保持しないデプロイは、どれも
404 source_not_kept です。
呼び出し元は indx_owner Cookie です。最初の保存で設定され、保存のたびに更新され、HttpOnly、
SameSite=Lax、/v1 に限定され、INDX_STORE_COOKIE_SECURE=false でない限り Secure です。
ランダムなベアラートークンで、サーバーはその SHA-256 だけを保持します。Cookie のない呼び出し元は何も
保存していません。別の呼び出し元の文書は、保存されたことのない文書と同じく 404 document_not_found
で、DELETE はどちらでも 204 を返すので、他人が何を保存したかは何も伝わりません。
POST /v1/search は、呼び出し元が保存したすべてのチャンクを、含まれる語で検索します。埋め込みなしで
保存したチャンクも対象です。embedding_space_id を名指すと 2 本目の脚が加わり、クエリがその空間で
埋め込まれ、その空間のベクトルを持つチャンクと比較されます。語で見つかったチャンクがすべて先に来て、
意味だけで見つかったチャンクがその後に続きます。空間は共有する文字や意味で似ているものを見つけますが、
似ていることは、尋ねたことを述べているチャンクほど良い答えではないからです。各グループの中では脚が
逆順位で融合されるので、ヒットの score は応答の順序を決めるだけで、単独では意味を持ちません。
句読点だけのチャンクが、似ているというだけで返されることはありません。text_score（BM25）と
vector_score（空間のメトリック、近いほど高い）はそれぞれの脚のスコアで、lanes はどの脚が見つけた
かを示します。テキストのクエリ埋め込み器を持たない空間は、POST /v1/embed と同じ 422 です。
| 変数 | 既定 | 意味 |
|---|---|---|
INDX_DOCUMENT_STORE |
未設定 | レコードを保存する indx.document_stores のエントリポイント（memory、sqlite または postgres） |
INDX_VECTOR_INDEX |
未設定 | チャンクを保存する indx.vector_indexes のエントリポイント。上と一緒に設定するか、どちらも設定しない |
INDX_SOURCE_STORE |
未設定 | 保存した文書のソースを保存する indx.source_stores のエントリポイント（memory、sqlite または postgres）。未設定ならソースは保持しない |
INDX_STORE_TTL_SECONDS |
86400 |
最後の保存から文書を保存しておく時間 |
INDX_STORE_MAX_DOCUMENTS_PER_OWNER |
20 |
呼び出し元ごとの上限。もう 1 つ保存すると最も古いものが消える |
INDX_STORE_COOKIE_SECURE |
true |
オーナー Cookie を Secure にするか。サーバーに平文の HTTP で届く場合だけ false |
INDX_STORE_MEMORY_MAX_DOCUMENTS |
512 |
indx-store-memory: すべての呼び出し元をまたいでプロセスごとに保存する文書数。最も前に保存したものから消える |
INDX_STORE_MEMORY_MAX_BYTES |
268435456 |
indx-store-memory: 各バックエンドが保持する量を JSON の長さで数えたもの。最も前に保存したものから消える。1 文書だけでこれを超えると 413 input_too_large。Python はこの 3〜6 倍を保持する |
INDX_STORE_MEMORY_PRESSURE |
0.8 |
indx-store-memory: メモリ上限（cgroup のもの、なければマシンのもの）に対する使用の割合。これに達すると、保存のたびに最も古い 1 割の文書を消す。0 で無効 |
INDX_STORE_SQLITE_PATH |
未設定 | indx-store-sqlite: 両方のポートがテーブルを置くファイル。保存したものが再起動を越えて残る。これなしに sqlite を名指すと、起動時に store_not_configured で失敗する |
INDX_STORE_POSTGRES_URL |
未設定 | indx-store-postgres: すべてのポートがテーブルを置くデータベースの libpq 接続文字列。前に立つすべてのインスタンスが共有する。これなしに postgres を名指すと、起動時に store_not_configured で失敗する |
INDX_STORE_POSTGRES_SCHEMA_NAME |
indx |
indx-store-postgres: テーブルを置く Postgres のスキーマ。なければ作る。1 つのデータベースに複数のインストールを置ける |
2 つのバックエンドはサーバーの起動時に読まれます。バックエンドは保存したものを保持するからです。残りは
リクエストごとに読まれます。indx-store-memory はすべてをサーバープロセスに保存するので、再起動で
失われ、2 つのインスタンスの間で共有されません。インスタンスを 1 つだけ動かすデプロイに向いています。
スキーマストアを名指すデプロイは、インストールの文書タイプを保存します
（ADR-0075）。
名指さないデプロイは、下のどのルートにも 404 store_disabled を返します。タイプは呼び出し元ではなく
インストールのもので、どの呼び出し元も同じものを読み、失効しません。
GET /v1/types はタイプをキー順に並べ、writable（このデプロイが書き込みを受けるかどうか）を返します。
GET /v1/types/{id} は 1 つを読み、保持していないキーは 404 type_not_found です。PUT /v1/types/{id} は
DocumentTypeSpec（label、fields、signature）から作成または置き換えをし、最初に作った時刻を保ちます。
DELETE /v1/types/{id} は、タイプがあってもなくても 204 を返します。
書き込みには Authorization: Bearer <INDX_WORKSPACE_TOKEN> が要ります。トークンがない、または違えば
401 unauthorized で、トークンを設定していないデプロイは読み取り専用です: 403 workspace_read_only。
signature は、そのタイプを認識する形式シグネチャを持つインストール済みのパーサー（invoice-parser など）を
名指します。ほかの機能なら 422 invalid_type です。
| 変数 | 既定値 | 意味 |
|---|---|---|
INDX_SCHEMA_STORE |
未設定 | 文書タイプを保存する indx.schema_stores のエントリポイント（memory、sqlite または postgres） |
INDX_WORKSPACE_TOKEN |
未設定 | タイプとラベルへのすべての書き込みに要る運用者のベアラートークン。未設定なら読み取り専用 |
ラベルストアも名指すデプロイは、レーンが答えたものへのレビュー担当者の判定を保存します
（ADR-0076）。
名指さないデプロイは、下のどのルートにも 404 store_disabled を返します。タイプと同じく、ラベルは
インストールのもので失効せず、判定した答えを写し取るので、読んだ元の保存された文書より長く残ります。
GET /v1/labels はラベルをダイジェスト、ID の順に並べ、digest と type_id があれば絞り込み、writable
を返します。PUT /v1/labels は LabelSpec を保存します。文書の digest と document_name、target
（ブロック、ページ、枠、ラベル、範囲、表記を持つ entity、または単位、ブロック、ページ、ファセット、ラベルを
持つ facet）、verdict（approved、corrected、rejected）、corrected の判定に要る correction、
そして任意で type_id、field、reviewer です。ラベルの ID はダイジェストと判定した答えから導くので、
同じ答えへの 2 つ目の判定は 1 つ目を置き換えます。ワークスペースが保持しない type_id や field は
422 invalid_label です。DELETE /v1/labels/{id} は、ラベルがあってもなくても 204 を返します。
書き込みにはタイプと同じトークンが要ります。
| 変数 | 既定値 | 意味 |
|---|---|---|
INDX_LABEL_STORE |
未設定 | ラベルを保存する indx.label_stores のエントリポイント（memory、sqlite または postgres） |
データセット
Section titled “データセット”データセットストアを名指すデプロイは、レビュー済みの文書を、目的（training または evaluation）を 1 つ
持つデータセットにまとめます（ADR-0077）。名指さないデプロイは、下のどのルートにも
404 store_disabled を返します。データセットのメンバーは文書で、各文書はダイジェストと写し取った名前です。
例はその文書が今持つラベルなので、データセットはライブのビューです。
GET /v1/datasets はデータセットをキー順に並べ、それぞれに examples（文書が持つラベルの数）と
readable（インストールがソースを保持している文書の数）を添え、writable を返します。GET /v1/datasets/{id} は 1 つを読み、保持していないキーは 404 dataset_not_found
です。GET /v1/datasets/{id}/labels はその例を並べます。PUT /v1/datasets/{id} は DatasetSpec
（label、purpose、type_id、documents）から作成または置き換えをし、最初に作った時刻を保ちます。
ワークスペースが保持しない type_id、または同じタイプのもう一方の目的のデータセットにすでにある文書は
422 invalid_dataset です。DELETE /v1/datasets/{id} は 204 を返し、文書のラベルは残します。
書き込みにはタイプと同じトークンが要ります。
PUT は、加えた各文書のソースを、呼び出し元が保存したもの（リクエストと一緒に送られる indx_owner
Cookie）からインストールへ写します。写しは失効しません。呼び出し元が保存していない文書、またはソース
ストアを名指さないデプロイで保存した文書は、読めないまま加わります。どのデータセットも名指さなくなった
ソースは消えます。
| 変数 | 既定値 | 意味 |
|---|---|---|
INDX_DATASET_STORE |
未設定 | データセットを保存する indx.dataset_stores のエントリポイント（memory、sqlite または postgres） |
ルーターストアを名指すデプロイは、インストールのルーターを保存します（ADR-0078）。各バージョンは、
文書タイプごとの分岐、既定の分岐、任意で認識器です。名指さないデプロイは、下のどのルートにも
404 store_disabled を返します。公開したバージョンは変わりません。
GET /v1/routers は各ルーターの最新のバージョンを並べ、writable を返します。
GET /v1/routers/{id}/versions は 1 つのルーターのバージョンを古い順に並べ、
GET /v1/routers/{id}/versions/{version} は 1 つを読みます。ワークスペースが保持しないルーターやバージョンは
404 router_not_found です。PUT /v1/routers/{id} は RouterSpec（label、branches、default、
recognizer）を次のバージョンとして公開します。古いバージョンの復元は、その仕様をもう一度公開することです。
ワークスペースが保持しないタイプの分岐、またはこのインストールにないリーダー、レーン、チャンカー、空間、
認識器を名指す分岐は 422 invalid_router です。DELETE /v1/routers/{id} はすべてのバージョンを消し、
204 を返します。書き込みにはタイプと同じトークンが要ります。
/v1/plan、/v1/encode、/v1/documents は router: {id, version?} を取り、バージョンがなければ最新です。
サーバーは計画の前にそれを解決し、各タイプのパーサーと、認識器のファセットで人がタイプに承認したダイジェストを
加えます。計画はバージョン（router）を名指し、branches、typed_pages、recognizer を並べます。
トレースは各ページの分岐を branches に並べます。ルーターを名指すリクエストは自分のチャンカー、レーン、空間を
名指しません（422）。別のバージョンで作られた計画は 409 plan_conflict（param="plan.router"）です。
| 変数 | 既定値 | 意味 |
|---|---|---|
INDX_ROUTER_STORE |
未設定 | ルーターを保存する indx.router_stores のエントリポイント（memory、sqlite または postgres） |
昇格が公開したバージョンは origin（元になった実験と候補）を持ちます。それ以外のバージョンの origin は、
復元したものも含めて null です。
ワークスペースに加えて実験ストアを名指すデプロイは、評価データセットで候補ルートを採点し、その 1 つを
昇格させます（ADR-0082、
ADR-0083）。
名指さないデプロイは、以下のすべてのルートで 404 store_disabled を返します。
PUT /v1/experiments/{id} は ExperimentSpec（label、dataset_id、router_id、candidates）から
実験を作ります。候補は key、label、そしてタイプを名指さないルーターの branch です。サーバーは
データセットのタイプと文書、それらの文書がいま持つラベル、ルーターの最新バージョンを凍結し、
production（ルーターがそのタイプに持つブランチ）を最初に置きます。実験は変わらないので、すでにある
キーは 409 experiment_exists です。1 つのタイプの評価の組でないデータセット、保存されたソースのない
文書、採点する判定のないデータセット、インストールされていないものを名指す候補は
422 invalid_experiment です。
PUT /v1/experiments/{id}/run は実行をバックグラウンドで開始または再開し、すぐに応答します。ジョブの
ランナーを名指さないデプロイでは 404 store_disabled です。同じパスの
DELETE は次の文書の前で止めます。各候補は各文書を、それがなるはずのルーターのバージョンとして読み、
文書には読む前にタイプが付きます。GET /v1/experiments/{id} は ExperimentReport を返します。
stateはrunning、stopped、completeのいずれかで、保存されたセルから導出し、保存はしません。cellsとdoneがセルを数えます。candidatesは各候補の保存されたセルを合計します。採点したdocumentsとfailed、expectedとright、pagesとneeds_person、結果が報告したcost_usdとlatency_ms、そしてrowsです。rowsはフィールド（assigned）、または未割り当てのエンティティのラベルやファセットごとに 1 行です。resultsはすべてのセルを並べ、失敗したセルはerrorを持ちます。promotionは、候補が公開されたあと、そのルーターのバージョンを名指します。
エンティティへの判定は、そのページのマージしたエンティティが、NFKC で畳んだあと同じ表層のラベルを持てば 正解です。ファセットへの判定は、最上位のラベルが一致すれば正解です。承認は答えを、訂正は訂正後の値を、 却下はその答えがないことを期待します。オフセットとボックスは比べません。
PUT /v1/experiments/{id}/promotion に {"candidate": key} を送ると、そのタイプのブランチを置き換えた
ルーターの次のバージョンを公開し、それを返します。候補がすべての文書を採点していなければ
409 experiment_incomplete、実行が測ったバージョンより先にルーターが進んでいれば 409 experiment_stale
です。GET /v1/experiments は実験をキー順に状態とともに並べ、DELETE /v1/experiments/{id} は実行を止め、
セルを消して 204 を返します。書き込みにはタイプと同じトークンが要ります。
| 変数 | 既定値 | 意味 |
|---|---|---|
INDX_EXPERIMENT_STORE |
未設定 | 実験とそのセルを保存する indx.experiment_stores のエントリポイント（memory、sqlite または postgres） |
INDX_JOB_RUNNER |
未設定 | 実験をバックグラウンドで走らせる indx.job_runners のエントリポイント。memory はサーバーのプロセスの中の 1 本のワーカースレッドで、実行はプロセスより長く生きません。未設定なら、実験は保存して読めますが、走らせられません |
すべての失敗は、type、code、message、任意の param、任意の request_id
を含む、1 つの型付きエンベロープを使います。操作に到達する前にルーターが
送出するトランスポートレベルの失敗も含まれます。未知のパスは 404、誤った
メソッドは 405 で、どちらも type は http_error、code は not_found
または method_not_allowed です。これらはどの操作にも属さないため、OpenAPI
ドキュメントの操作ごとのレスポンスには列挙されません。
| ステータス | 意味 |
|---|---|
401 |
運用者のベアラートークンなしの文書タイプへの書き込み（unauthorized） |
403 |
トークンを設定していないデプロイでの文書タイプへの書き込み（workspace_read_only） |
404 |
固定指定された機能スナップショット ID が保持されていない（GET /v1/capabilities）、呼び出し元がそのダイジェストの文書を保存していない（document_not_found）、ワークスペースがそのキーのタイプを保持していない（type_not_found）、ワークスペースがそのキーのデータセット、そのルーター・バージョン、そのキーの実験を保持していない（dataset_not_found、router_not_found、experiment_not_found）、またはデプロイが文書、タイプ、ラベル、データセット、ルーター、実験を保存しない（store_disabled） |
409 |
受け渡された計画がソースまたは機能スナップショットと一致しない。または、実験のキーがすでにある（experiment_exists）、候補がすべての文書を採点していない（experiment_incomplete）、ルーターが先に進んでいる（experiment_stale） |
413 |
リクエストがサーバーの公開する入力上限を超えている |
415 |
コンテンツタイプが未対応、インストールされたどのローダーもソース URI スキームを解決しない（unsupported_source）、またはインストールされたどの機能もそのメディアタイプを読まない |
422 |
リクエスト検証の失敗、ソースが期待されたバイト列に解決されない（source_unreadable）、このサーバーに渡されていないパスワードを必要とする（source_encrypted）、ローダーのガードが取得を拒否する宛先を名指ししている（source_forbidden）、インストール済みのどれも生成しないブロック粒度を要求している（unsupported_granularity）、埋め込み空間が要求どおりにリクエストを処理できない、文書タイプがインストール済みのどのパーサーも持たないシグネチャを名指している（invalid_type）、ラベルがワークスペースの保持しないタイプやフィールドを名指している（invalid_label）、データセットが未知のタイプや、同じタイプを教えて採点することになる文書を名指している（invalid_dataset）、またはルーターがこのインストールにないタイプや ID を名指している（invalid_router） |
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_CHUNK_LAYOUT_MAX_CHARS（既定 2000）は pdf チャンカーのバージョン 2 である
indx-chunker-layout に属します。それを超えそうな段落は次の改行で閉じられます。目標ではなく
上限で、INDX_CHUNK_DPI と同様、正の整数でない値は raise し、エグゼキューターはその文書では
このチャンカーを飛ばして、代わりにバージョン 1 が切ります。
INDX_CHUNK_GRID_MAX_ROWS（既定 50）は indx-chunker-grid に属します。1 つの表チャンクが運ぶ本体の
行数で、それを超えた表は見出し行を繰り返して次のチャンクに続きます。正の整数でない値は raise し、
エグゼキューターはその文書ではこのチャンカーを飛ばします。
INDX_CHUNKERS はデプロイ自身の優先で、CLI と同じ綴りです。pdf@2,page。リクエストの
chunking と同じ意味を持ち、その後ろに位置します。リクエストが名指したものが先に尋ねられ、
次にこれら、次にインストールの順序です。だからデプロイは、新しいチャンカーのバージョンが全員の
既定になるのを待たずに、それへ移れます。未設定なら何も変わりません。インストール済みの何も
応えられない項目は、呼び出し元ではなく運用者の誤りです。ファサードは変数を名指して構築を
拒否するので、サーバーは起動に失敗し、CLI は開始に失敗します。変数はチャンクを含むエンコードの
たびに再び読まれるので、調整に再起動は要りません。どちらの経路も、何も名指さなかったリクエストに
422 を返すことはしません。
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= クエリは黙って落とされるのではなく拒否されます。
indx-loader-gs は gs://bucket/object を同じ方法で解決します。
google-cloud-storage は gs エクストラの背後にあり、エクストラなしの取得は
indx-loader-gs[gs] を名指しする同じ 422 になります。
INDX_LOADER_GS_CREDENTIALS_JSON はサービスアカウントキーの JSON そのもので、
パスではありません。設定されていればそれが優先され、未設定なら
アプリケーションのデフォルト認証情報（ADC）が適用されるので、Cloud Run や GKE 上の
デプロイはキーを複製せずにサービスアカウントを使えます（ADR-0066）。
INDX_LOADER_GS_BUCKETS はその二層目が必要とする許可リストで、規則は
INDX_LOADER_S3_BUCKETS と同じです。INDX_LOADER_GS_ENDPOINT_URL はローダーを
エミュレーターに向け、キーが未設定なら匿名にします。プロセスのアイデンティティの
トークンを、エンドポイントが名指しする先へ送らないためです。
INDX_LOADER_GS_TIMEOUT_SECONDS が各リクエストとその再試行を制限します
（既定 30 秒）。?generation= クエリは黙って落とされるのではなく拒否されます。
indx-loader-az は az://container/blob を、az エクストラの背後にある
azure-storage-blob を通じて解決し、エクストラなしの取得は indx-loader-az[az] を
名指しする同じ 422 になります。ストレージアカウントは設定であって URI の一部では
ないので、1 つのデプロイが読むのは 1 つのアカウントです（ADR-0066）。
INDX_LOADER_AZ_CONNECTION_STRING は設定されていれば優先され、それがすべてです。
アカウント、そのキーまたは SAS、エミュレーターならエンドポイントを運びます。未設定なら
INDX_LOADER_AZ_ACCOUNT がアカウントを名指しし、DefaultAzureCredential が
適用されるので、Container Apps や AKS 上のデプロイはキーを複製せずにマネージド ID を
使えます。どちらも未設定なら、取得は両方の変数を名指しする 422 になります。
INDX_LOADER_AZ_CONTAINERS はその二層目が必要とする許可リストで、規則は
INDX_LOADER_S3_BUCKETS と同じです。INDX_LOADER_AZ_TIMEOUT_SECONDS が接続と
読み取りを制限し（既定 30 秒）、そのために SDK の再試行は切ってあります。
?snapshot= や ?versionid= クエリは黙って落とされるのではなく拒否されます。