未翻訳のページは英語で開き、英語と表示されます。
このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 Machine-translated from the English page, which is authoritative.
プロバイダーの再構成
Loom は、ダッシュボードのモデル設定を、暗号化されたバージョン管理付きの行として loom.provider_configuration に保存します。1 つの設定には、コミット済みの先行バージョンが 1 つあります。古いバージョンに基づく保存は拒否されます。ダッシュボードでの上書きは、サーバーの起動時の環境設定よりも優先されます。環境設定へのリセットでは、起動時のスナップショットが復元されます。新しく編集した dotenv ファイルの内容は反映されません。
アクティベーションとアドミッション
キーのローテーションと LLM のみの変更は、ベクトルを再構築せずにアクティベートできます。埋め込みプロバイダー、エンドポイント、モデル、次元数のいずれかを変更すると、キューに入ったトランジションが作成されます。このトランジションは、以前のベクトル空間のベクトルに対してアクティベートしてはなりません。
ランタイムは、失敗したトランジションを含め、未完了のトランジションを検出すると、ローカルのモデル処理用アドミッションゲートを閉じます。すでに受け付けた処理は完了できます。新しいデータプレーンのリクエストには再試行可能なメンテナンス応答が返され、ワーカーのパスは実行期限を消費せずに待機します。ヘルス、モデル設定、ダッシュボードの制御ルートには引き続き到達できます。コミット済みの一致するトランジションがあれば、再キャリブレーションとアドミッションの再開が可能になります。後続のキーのみのリビジョンは、コミット済みの先行チェーンを通じてこの確認を満たせます。
このゲートがカウントするのは 1 つのプロセス内の処理です。分散ライターバリアではなく、遅延書き込みや他のレプリカがドレイン済みであることも保証しません。
リフレッシュループは、このゲートの外でコーディネーターを実行します。すべてのサーバープロセスとネイティブのデータプレーン CLI コマンドは、コミット済みの設定を読み込む前、または処理を受け付ける前に、loom._provider_participants に登録します。トランジションでは、リクエスト、ワーカーのパス、登録済みの有限な子タスク、バッファされた書き込みがドレインされた後に、既存のすべての参加者が同じ設定 ID を承認する必要があります。新しく起動したプロセスは、サービスを開始する前に、保留中の閉じたゲートかコミット済みの置き換え後の設定のいずれかを読み込みます。
各参加者は、専用のスレッドから 10 s ごとに自身の行を書き込み、開くすべての ClickHouse クライアントは User-Agent に自身の ID を含めます。参加者が停止したとみなされるのは、自分で退役した場合(正常なシャットダウン)、同じホスト上の後続プロセスがその消失を証明した場合、またはオペレーターが退役させた場合に限られます。ハートビートの期限切れは証明になりません。一時停止したプロセスは ClickHouse の外でアドミッション済みの処理を保持しており、再開後に古い設定でそれを書き込む可能性があります。そのため、トランジションはその参加者が再びハートビートを送り、ドレインするまで待ちます。各行には、ホスト名、カーネルのブート、コンテナ ID(Docker のもの、または Kubernetes のポッドとコンテナ名)、pid 名前空間、pid、開始時刻が記録されます。10 s ごとに、各プロセスは、同じホストかつ同じブートの参加者のうち、その pid がもはやそのプロセスを実行していないもの、またはコンテナが新しい pid 名前空間で再起動する前に自身のコンテナで動いていたものを、そのクエリが実行されていなければ退役させます。これは、コンテナやワーカーがその場で再起動した、強制終了されたプロセスを対象とします。ホスト名を共有する 2 つのコンテナ(ホストネットワーク、1 つのポッド内の 2 つのコンテナ)が互いを退役させることはありません。プロセスが消失したことを確認したオペレーターは、loom participant retire --participant <id> --yes で退役させます。ハートビートが新しい参加者や、クエリがまだ実行中の参加者は拒否されます。workers リーダーの /v1/health は、トランジションが待機することになるすべての参加者を provider_participants_stale(heartbeat_expired または queries_running)として一覧表示します。system.processes は clusterAllReplicas(LOOM_CH_CLUSTER) 越しに読み取られます。そのクラスターがないサーバーは自身の分だけを返し、読み取りのその他の失敗は、その参加者を実行中として扱います。
境界のある各再構築ステップは、共有の設定 Keeper キーを保持し、20 s ごとに更新されます(TTL 60 s)。競合する側が期限切れのキーを引き継げるのは、その保持者の参加者が停止したとみなされる場合のみです。TTL の経過だけでは証明になりません。loom provider-lock clear --holder <holder> は、保持者に参加者行がないキーを解放し、保持者が更新中、ハートビート送信中、またはクエリ実行中の間は拒否します。ブート時のマイグレーションはこのキーの下では実行されません。ブートは、登録後に未完了の再構築がないことを確認するためだけにこれを保持するため、マイグレーション中に開始された再設定はそのブートを待ちます。60 s を超えて停止した参加者は、停止したとみなされることがあります。その参加者は次のハートビートで再登録し、次のリフレッシュでゲートを閉じます。
最初のコーディネーターのチェックポイントで、エンドポイントとモデルの識別情報、および有効な設定済みのプレフィックス幅が固定されます。再起動しても、変更されたプレフィックス設定は採用されません。再構築クライアントは、明示的な認証情報を使う生のプロバイダーリクエストを使い、プロセスキャッシュと共有のサービングキャッシュの両方を迂回します。失敗したバッチが所有権を解放する前に、兄弟リクエストはキャンセルを完了します。アクティベーションでは、サービングのキャリブレーションを再構築する前に、プロセスキャッシュのベクトルと以前にプローブした幅をクリアします。
リビルドのステージング
リビルドのインベントリは、既知のすべてのライブベクトル列を対象とします。履歴ベクトルは保持されます。キャッシュと派生コードプレフィックスには、それぞれ別のアクションがあります。未知のベクトルサーフェスは、黙って除外されることなく、プリフライトで失敗します。
実装済みのステージングプリミティブは、排他的なコーディネーターリースと、書き込みが完全に停止した状態(drained writers)を必要とします。
- スナップショットフェーズのプリフライトは、書き込みの前に、レシート、ソーススキーマ、UUID によって部分的なコピーを突き合わせます。未完了のソースコピーはインベントリに計上されることがありますが、完了とは見なされず、再構築されます。完了済みの対応するソースを持たないターゲットや、想定外のプライベートテーブルがある場合は、リカバリーが停止します。
- ソースコピーは書き込み可能なすべての列を保持し、安定したページング用の序数を割り当てます。完了レシートは、成功したコピーをそのソースの UUID とスキーマフィンガープリントに結び付けます。確認できていないコピーは、行数によって受け入れられることなく、再構築されます。
- モデルをキーとする置換テーブルは、古い埋め込みラベルをまたいで、論理キーごとに最も高いリビジョンを選択します。リビジョンが同じ場合は、トゥームストーンが優先され、次に古いモデルラベルによって決定的にタイブレークされます。後のアクティブなリビジョンは、明示的なリストアを保持します。選択では、個別に集約したフィールドを混ぜることなく、選ばれた行全体が保持されます。ソースポリシーのバージョンはスナップショットフィンガープリントに含まれるため、古いレシートが変更されたレシピを黙って引き継ぐことはありません。
- スナップショットのクリーンアップでは、所有権、UUID、ローカルのクエリステータスを確認します。クエリの検査は、作成時と同じ固定された ClickHouse ノードで行う必要があります。これはクラスター全体の確認応答ではありません。リカバリーの前に、古いコーディネーターをフェンスする必要があります。
- ターゲットテーブルは、ソースの序数をキーとするプライベートな
ReplacingMergeTreeテーブルです。繰り返されたバッチは、FINALの下では論理的に 1 行になります。所有権マーカーは、テーブルをソーススナップショットと埋め込み空間のフィンガープリントに結び付けます。 - ベクトルの生成には、明示的に指定されたターゲット埋め込み器を使用します。書き込みの前にバッチ全体を検証し、プロセス全体のプロバイダーは変更しません。
- キャッシュアクションは、所有しているプライベートなキャッシュターゲットだけを無効化し、それが空であることを確認します。埋め込みプロバイダーは呼び出しません。これにより、モデルラベルが変わらない場合でも、古いエンドポイント固有のエントリが無効化されます。提供中のキャッシュは、置き換え分が公開されるまで変更されません。
- トラッカーページは、名前空間の既存のソースゲートと通常のインデックス作成レシピを通して、タイトルと本文のテキストをハイドレートします。照合には、テナント、種別、アイテム番号、リポジトリのソース ID、保存済みのテキストダイジェストが含まれます。トゥームストーンではソースの読み取りは不要です。ソースが存在してテキストが変更されている場合、ステージング済みのテキストダイジェストは、ターゲットプロバイダーに送信される、認可済みの正確なテキストで更新されます。所有権とその他のメタデータはすべて凍結されたままで、スナップショットの行は変更されません。ソースが見つからない場合やアクセスできない場合は、プロバイダーの呼び出しやステージングの書き込みの前にページが停止します。スナップショットのトゥームストーンが、ソースの読み取りやプロバイダーの呼び出しを引き起こすことはありません。
- プレフィックスの導出には、検証済みの再構築されたフルコードベクトルを使用し、そのメタデータを ClickHouse 内で保持したまま、通常のプレフィックス正規化ルールを適用します。安定した序数によって、設定された射影が分離されます。検証では、行数だけでなく、各ラベルの行の完全なマルチセットを比較します。凍結されたプレフィックスポリシーが空の場合は、不要になったツインがクリアされます。マニフェストはポリシーを永続化し、それと食い違うリクエストは、ステージングを変更する前に失敗します。ランタイムのアクティベーションでは、後のキーローテーションを経ても、完了したレシピからコード検索のラベルとテーブルルートが再構築されます。プロバイダーやエンドポイントのフィンガープリントが一致しない場合、受け入れは閉じたままになります。有効なプレフィックスのデフォルトは、その幅が再構築されている場合はその幅を保持し、存在しない幅は無効になります。ベクトル機能のキャッシュは、受け入れが再開される前に更新されます。
- ステージングの挿入では、変更のないメタデータを ClickHouse 内でソースコピーから直接選択します。Python が転送するのは埋め込み関連の更新だけなので、メタデータの往復時に起こるタイムゾーンの再解釈やタイムスタンプ精度の損失を避けられます。
- 検証では、行のカバレッジ、null セーフなメタデータの等価性、モデルの同一性、ベクトルの次元数、有限で非ゼロのベクトル、トゥームストーン上のベクトルがクリアされていることを確認します。検証結果が存在しない、または不正な形式の場合は、成功とは見なされません。
- 検証では、最終的なライブのソートキーも確認します。古いモデルの行を 1 つのモデルに書き換えて、置換エンジンまたは集約エンジンに公開する際に、異なるステージング序数が黙って 1 つにまとめられてはなりません。正規の入力選択の後にも衝突が残る場合は、検証が失敗します。
ステップランナーは、エフェクトが完了した後にのみ進捗を永続化します。データベースへの書き込みの後、チェックポイントが保存される前にプロセスが停止する可能性があるため、エフェクトは冪等でなければなりません。失敗時には最後のカーソルが保持され、固定のエラーコードが公開されます。管理者のリトライアクションは、その同じ遷移を再度キューに入れます。
進捗チェックポイントには、バージョン付きのリカバリーマニフェストも含まれます。マニフェストには、設定 ID、埋め込み空間のフィンガープリント、凍結されたプレフィックスの次元数、順序付きの完全なテーブルインベントリが含まれます。プレフィックスポリシーが存在しない場合は、空のポリシーとは解釈されません。古いバージョンのマニフェストは、ランタイムのデフォルトを採用することなく、フェイルクローズします。各エントリには、元のスキーマと UUID に加えて、スナップショットとターゲットの UUID が記録されます。検証では、これらの凍結された識別情報を変更せずに、準備済みの UUID と検証済みの行数が追加されます。ランナーは公開の前にこのマニフェストを永続化し、公開とクリーンアップに渡します。マニフェストがない場合、未知のバージョン、不完全なインベントリ、再利用された UUID はフェイルクローズします。リカバリーが名前からテーブルの識別情報を推測することはありません。マニフェストにはメタデータのみが含まれ、認証情報、ベクトル、ソースコンテンツは含まれません。
リカバリーのインベントリがプライベートコピーを除外するのは、その正確な名前と物理 UUID がマニフェストと一致する場合に限られます。未知のベクトルテーブル、別のジョブのコピー、同名の置き換えは、引き続きプリフライトで失敗します。ジャーナルに記録されていないコピーは、このチェックの前にレシートの突き合わせが必要です。ステージングのプレフィックスだけでは、インベントリを回避できません。このインベントリチェックは、ジャーナルに記録されたすべてのコピーがまだ存在することを証明するものではありません。
ベクトルのパッチは、単一の HTTP パラメーターフィールドではなく、型付きの JSONEachRow マルチパートファイルデータとして送信されます。SQL 自体が小さくても、フルサイズのページは ClickHouse のフォームフィールドの上限を超えることがあります。この書き込みパスを通るのは、序数と埋め込み関連のフィールドだけです。変更のないメタデータは、DateTime64 の精度を保ったまま、ClickHouse 内でスナップショットから結合されます。アップロードによって永続的なパッチテーブルは作成されず、同期書き込みでは通常のリトライと重複排除の設定が維持されます。
公開プリミティブ
候補の準備では、ライブスキーマを非公開テーブルにクローンし、検証済みのステージングから書き込み可能なカラムだけをコピーします。完了を記録する前に、ClickHouse 内で論理行数と、NULL や重複数を含む全行のマルチセット等価性の両方を検査します。完了済みの候補を再開した場合も、これらの検査を繰り返します。行数が一致するだけでは、コピーが損なわれていないことの証明にはなりません。このヘルパーが現在受け付けるのは、ローカルの MergeTree エンジンのみです。レプリケートエンジンと共有エンジンには、別途レプリケーション経路の計画が必要です。
コード化されたテーブルでは、準備時に正規の DDL と既存の Quantized メソッドおよびコーデックチェーンを保持し、テーブルの識別子、所有権コメント、ベクトル幅だけを置き換えます。候補は、サーバーがコーデック設定を受け付ける状態に従って作成されます(ゲート付き設定)。コーデックを有効にできない場合は CREATE の前に拒否され(所有している古い候補は先に削除されます)、allow_suspicious_codecs を有効にできない場合はチェーンなしで作成されます。クリアされたステージングのベクトルは、これらの物理カラムでは固定幅のゼロのプレースホルダーになります。次元フラグ、トゥームストーン、その他のメタデータは変更されません。全行の検証では、行数の一致だけでなく、この明示的な物理射影を比較します。Rabitq と TurboQuant の幅は 8 の倍数でなければなりません。未知のコーデック引数、およびオペレーターが作成したベクトルインデックスや制約には、別途次元の計画が必要です。準備はフェイルクローズで失敗し、コーデックを削除したり、互換性のないレイアウトを公開したりすることはありません。
公開ヘルパーは、永続化された元テーブルと準備済みテーブルの UUID を受け取ります。まずライブテーブルを所有するバックアップ名に移動し、次に準備済みテーブルをライブ名に移動します。再試行時には、UUID によって、移動前、中間、完了の各状態を識別します。EXCHANGE は使用しません。共有クライアントの自動ネットワーク再試行により、応答が失われた後で exchange が繰り返され、意図せず古いテーブルが復元される可能性があるためです。
固定されたレシピは、依存する明示的 TO のマテリアライズドビューと、その置き換え用 UUID もジャーナルに記録します。オペレーターが記述した定義にはシークレットが含まれうるため、ビューの DDL は暗号化されます。すべての置き換えテーブルがライブになった後、公開処理はこれらのビューを再作成し、以降の挿入がバックアップ UUID ではなく置き換え後のソースにバインドされるようにします。DROP/CREATE の応答が失われた場合は、ジャーナルに記録された ID に対して再開します。未知の ID がある場合は、プリフライト全体が停止します。暗黙の内部データを持つビューはサポートされません。削除するとデータが失われるためです。明示的 TO ビューの宛先は保持され、ビューの再バインドはバックアップのクリーンアップより前に完了します。探索は、ソーステーブルの dependencies_database と dependencies_table の配列をたどり、非同期ロードの依存関係はたどりません。ビューのメタデータが欠けている場合やデータベースをまたぐ依存関係がある場合は、フェイルクローズで失敗します。
これらの一方向のリネームにより、ライブ名に一時的な空白が生じます。すべてのテーブルが公開され検証されるまで、すべてのリーダーとライターを停止したままにする必要があります。準備済みテーブルは、意図したライブのスキーマ、インデックス、制約をあらかじめ備えていなければなりません。序数をキーとするステージングのターゲット自体は、公開可能な置き換えテーブルではありません。バックアップのクリーンアップとプロバイダーの有効化は、コーディネーターの別個のステップです。
クリーンアップでは、非公開コピーを削除する前に、すべてのライブテーブルをジャーナルに記録された置き換え UUID と照合して検証します。未知のコピーや置き換え済みのコピーは拒否され、ローカルのクエリと未完了のミューテーションも確認されます。ジャーナルに記録された正確なスナップショット、ターゲット、バックアップは、再試行しても安全な削除で除去されます。コピーが存在しない場合は、中断されたクリーンアップを再開できます。最後の ID 全数調査で、このジョブに属するコピーが残っていないことを確認する必要があります。呼び出し側は引き続き分散フェンスを所有し、その間ずっとアドミッションを閉じたままにします。
復旧と消去
ローカルランタイムのアクティベーションは、埋め込みクライアントを変更して受け入れ処理を再開する前に、受理済みのリクエストと登録済みの TaskSet の処理が完了するのを待ちます。この確認は、遅延書き込みをキャンセルしません。また、分散環境での確認応答ではありません。未登録のタスク、バッファリングされた書き込み、サーバー側のクエリについては、別途ドレーンの確認が必要です。完了したことだけでは、書き込みが成功したことは証明されません。
具体的なストレージバックエンドは、スナップショットのマニフェスト、テーブルごとの再構築、検証、置き換えの準備、公開、クリーンアップを、永続的なステップランナーに接続します。バックエンドは、明示的な埋め込み器、固定されたポリシー、バリアコールバックを受け取ります。コーディネーターのリースを作成することも、分散環境での静止状態を自ら証明することもありません。
ブートマイグレーションは、プロバイダー設定フェンスのテーブルが存在する時点から、そのフェンスを共有します。スキーマが同一の再起動では、移行が保留中の間はマイグレーション DDL をスキップします。保留中のマイグレーションを伴うアップグレードは、その移行が完了するまで待つ必要があります。保持期間の DDL は、モデル処理のゲートを通して受け入れられ、メンテナンス再起動時にはスキップされます。変更した保持期間の環境設定は、再構築の後にもう一度再起動して適用してください。MCP のアイドル実行スイープは、メンテナンス中に新しい要約処理を開始しません。
Docker 検証
scripts/gates/docker_quickstart_smoke.py は、生成されたリリースバンドルを、使い捨ての新規 Compose プロジェクトにインストールします。デフォルトの本番エントリポイントを通して、ダッシュボードの読み込み、メモリ、同梱のコンパイラツールチェーン、永続化されたコンパイラの結果、再起動、およびドキュメントに記載された環境更新と再作成の手順を確認します。
プロバイダーフェーズでは、Chromium を使って実際の Models & keys フォームを送信し、キーのローテーション、埋め込み次元の変更、失敗したリビルドの再試行、確認 UI による環境設定の復元を行います。あわせて、空でないメモリ/コードのベクトルとメタデータの保持、2 つの Web ワーカーの協調動作、メンテナンス応答、クラッシュからの復旧、コンテナの再作成、プライベートなリビルド用コピーの削除を確認します。プロバイダーフェーズでは、テスト専用の Compose エントリポイントで上流の LLM HTTP エンドポイントだけをリダイレクトします。埋め込みリクエストには、ネットワークのみの互換プロバイダーフィクスチャを使います。サーバー側の検証、認可、暗号化、コーディネーター、ClickHouse のストレージは実物のままです。フィクスチャの認証情報と出力は、有料プロバイダーへのアクセス、モデルの品質、本番クラスターの動作を証明するものではありません。CI ではこのゲートを amd64 と arm64 で実行します。
ローカルで実行するには、まずフロントエンドの依存関係と Chromium をインストールし(cd frontend && npm ci && npx playwright install chromium)、本番イメージをビルドしてから、--image <repository:tag> を指定してゲートを実行します。削除されるのは、生成されたプロジェクトのコンテナとボリュームだけです。ユニットテストは、モック化したストレージの副作用でこのオーケストレーションを検証しますが、Docker でのプロバイダー変更フロー全体は検証しません。
コーディネーターは、キューに入ったジョブをスナップショット、リビルド、検証、公開、クリーンアップ、有効化の順に進めます。失敗したジョブは、明示的に再試行するまで閉じたままです。再試行すると、永続化されたカーソルから再開します。ダッシュボードの進捗には、フェーズ、テーブル、カウンターが表示されます。プライベートな復旧マニフェストやレシピは表示されません。
移行中に届いた消去リクエストには、他のデータプレーンの書き込みと同じく、再試行可能なメンテナンス応答が返されます。それ以前に開始されたデタッチ状態の消去サーガは、登録済みの有限タスクであり、スナップショットの前に完了する必要があります。残存データの調査では、リビルドのソース、ターゲット、準備済みコピー、バックアップもすべて検査します。調査では、古い置換バージョンやトゥームストーンを含む物理行を数えます。利用可能なスコープ列を持たないコピーは、すべてのスコープにまたがるものとして保守的に数えます。不明なコピーや読み取れない件数は、0 と解釈されず、検証の失敗として扱われます。コピーはリビルドのクリーンアップで削除され、固定されたレシピの裏で編集されることはありません。そのため、中断されたリビルドが、消去の管理対象外のスナップショットを残すことはなく、対象者のデータを復活させうるコピーが残っているのに削除済みと報告することもありません。
現在の実装の境界
現在、パブリケーションがサポートするのは、固定された 1 つの ClickHouse ノード上のローカル MergeTree エンジンのみです。レプリケーション/共有エンジンの準備とクラスタ全体の残存クエリの検査には、それぞれ専用のサポート計画がまだ必要です。そのため、埋め込み空間を変更する保存またはリセットは、いずれかの再構築テーブルが別のエンジンを使用しており、かつ、いずれかの再埋め込みテーブルに行が残っている間、遷移がキューに入る前、かつ受け付けが閉じられる前に 409 で拒否されます。ステータスレスポンスには、同じ理由が embedding_change_blocked として含まれます。保存済みのベクトルがなければ、どのストレージでも再構築するものはありません。その場合、変更は active としてコミットされ、各プロセスは構成のリフレッシュを通じてドレインしたのち切り替わります。プロセスが切り替わる前に書き込んだ行には、以前のモデルのベクトルが残ります。Loom に登録されたサーバー/CLI の経路以外から直接データベースに書き込むものは、オペレーターが停止する必要があります。Loom プロセスの調査では、外部の任意の SQL クライアントを遮断することはできません。死亡証明のない失われたリモート参加者は、明示的なリカバリ上の境界であり、無視してよいという許可ではありません。Docker 上でのプロバイダー変更とクラッシュリカバリを通した E2E の完全な検証は、引き続きマージの前提条件です。ユニットのオーケストレーションテストとストレージレベルのテストは、そのフローの代わりにはなりません。