定義ドラフト
定義ドラフト
このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 Machine-translated from the English page, which is authoritative.
ギャップドラフトには knowledge_gaps_enabled が、クエリ履歴には knowledge_query_history_enabled が必要です。どちらの経路でも、モデルが書いた定義は管理者のレビューキューに入ります。モデルが定義を公開することはありません。このページでは、根拠、非公開の候補、レビューについて説明します。検索の記録とグルーピングについては、ナレッジギャップを参照してください。
根拠とアクセス
ライブラリの Draft definition アクションは knowledge.gaps.draft を呼び出します。このアクションは、現在の 7 日間のミスウィンドウでギャップの質問を再読み込みし、各質問について少なくとも knowledge_gaps_min_askers 人の異なる質問者を要求します。モデルには、正規化されたそれらの質問だけを送ります。キャプチャの同意はキャッシュなしで読み取られ、同意を確認できない場合はドラフトを拒否します。作業中にしきい値が変更された場合やユーザーの消去があった場合は、根拠が無効になり、その試行の候補バージョンが削除されます。
knowledge.query_history.add、.list、.remove には名前空間管理者のアクセス権が必要です。ライブラリでは、Query history からソース一覧と接続フォームを開きます。登録には、名前、ホスト、ポート、TLS の選択、読み取り専用アカウント、データベースの許可リスト、任意のクラスターがあります。パスワードは保存時に封印され、返されることはありません。接続は、トラッカーのホストチェック、固定されたアドレス、読み取り専用の権限レビューを再利用します。クラスターには REMOTE も必要です。登録を削除すると以後のターンは停止しますが、既存のドラフトや定義は削除されません。オペレーターがクエリ履歴を無効にしても、切断は引き続き可能です。
ワーカーは、完了した最初の SELECT クエリのうち、空でないデータベース一覧がすべて登録の許可リストに含まれるものを読み取ります。クラスターを指定した場合は clusterAllReplicas を使い、指定しない場合は接続したノードだけを読み取ります。グループ化には normalized_query_hash と normalizedQueryHashKeepNames を使い、異なる initial_user アカウントの数と新しさで並べます。2 つ目のハッシュは、番号付きの異なるテーブル名を区別したまま、空白やリテラルの違いでは分割しません。normalizeQueryKeepNames は、コメントを削除しリテラルを置き換えますが、識別子は保持します。モデルに渡るのは、この正規化された SQL だけです。
グループを裏付けるアカウントは少なくとも knowledge_query_history_min_users 個必要で、3 個を下回ることはありません。アカウントは人ではありません。共有アカウント 1 つは 1 と数えられ、1 人が複数のアカウントを持てばそれぞれ別に数えられます。この下限は匿名性を保証するものではありません。しきい値をライブで引き上げたり履歴ウィンドウを変更したりすると、処理中の結果は無効になります。ソースの削除、ソース UUID の変更、機能の無効化、名前空間の消去も結果を無効にします。
候補は source_kind = knowledge_gap または query_history を使います。モデルが書いたテキストとクエリ履歴の SQL は、learnings.list、品質カウント、明示的および推論されたリネージのいずれでも、名前空間管理者だけが読み取れます。フィルタリングはページネーションと集計の前に行われ、組織全体の品質読み取りも同様です。読み取りに絞られたトークンは、どちらのオペレーションのプレフィックスも呼び出せません。
モデルの 1 回の試行
候補 ID は、組織、名前空間、種別、根拠リソースから導出されます。ギャップではギャップ ID を、クエリ履歴では登録 UUID と 2 つのクエリハッシュを使います。短い候補リースにより、モデル呼び出しのためにリースを解放する前に、保留中のクレームが永続化されます。同時のリクエストも後続のリクエストも、決定、モデルエラー、無効な結果、クラッシュの後であっても、その候補 ID を返します。こうした失敗では、管理者に却下して明示的に書くよう促す理由を添えた保留中のクレームが残ります。生成前のポリシー保留では、未使用のクレームのバージョンだけが削除され、許可された時点で再試行できます。
組織のモデル呼び出しスイッチと名前空間の 1 日あたり上限は、作業をクレームする前に確認されます。上限を読み取れない場合は、作業を拒否します。各試行で許可されるのは、上限付きの JSON 補完 1 回です。結果は、用語、別名、本文、テーブル/カラム一覧のサイズについて検証されます。rests_on のギャップの来歴には、ギャップ ID とモデルのテーブル/カラム一覧が入ります。対象の質問はモデルの入力にだけ渡され、アプリケーションが候補にコピーすることはありません。モデルが、作成したテキストの中で質問を繰り返すことはあります。生成後は、元の質問のユーザー消去があっても、ドラフトとギャップ ID が残ることがあります。クエリ履歴の来歴には、正規化された SQL とモデルのテーブル/カラム一覧が残ります。最後の候補リースでステータスを再読み込みするため、完了処理が却下を上書きしたり、スクラブ済みのテキストを復元したりすることはありません。根拠のフェンスは、モデル処理の前後と挿入の後に実行されます。
ワーカーは、ソース、グループ、試行、クエリのバイト数、行数、メモリ、実行時間に上限を設けています。パスの予算の半分が過ぎると以降のグループは開始せず、ターンの前に最後のソースの UUID を保存するため、失敗するソースがあってもローテーションは妨げられません。固定サイズの UUID なので、ソース名が永続化されるカーソルに入ることもありません。接続の失敗には、ソースごとの上限付きサーキットブレーカーを使います。ワーカーのコストイベントには、名前空間の帰属が保持されます。
レビューと公開
learnings.review がこれらの候補を受け付けるのは、宛先が memory の場合だけです。書き込みの前に、フリートの機能、機微性、共有定義の上限、名前の衝突を確認します。ドラフトは、大文字小文字などを正規化した用語または別名がその用語と一致する、現行の共有定義を改訂します。一致が曖昧な場合は拒否します。新しい用語には、クレームとともに永続化されたランダムな definition/ キーを使います。書き込みの前に共有行を再読み込みするため、同時のリネームによって書き込みが別の用語にリダイレクトされることはありません。
レビューは memory.set を通じて、名前空間全体に適用される派生定義を書き込み、有効期限と有効範囲の境界を解除します。完全に一致する、有効で期限内のヘッドには書き込みが不要で、ピン留めやロックがあっても同様です。値が変わる場合は、ピン留めまたはロックされたヘッドを拒否します。改訂では、現在のソーステキストが共有コピーと一致している必要があり、その間に他の書き手が編集していれば拒否します。保持された期限切れのヘッドは、そのハッシュを使って条件付きで書き換え、ヘッドがない場合は if_match_sha256="absent" を使います。条件付きの呼び出し元はキー上で直列化され、通常の同時 ClickHouse 書き込みはバージョンで解決されます。これらのチェックによって、書き込みと昇格がアトミックになるわけではありません。
レビューは、承認された正規値のハッシュを付けて memory.promote を呼び出します。サーバーが内部で候補の来歴を渡し、認証されたアクターを記録します。クライアントが信頼される来歴を指定したり、approver で決定するアクターを選んだりすることはできません。昇格では、正規化された SQL を含む定義全体が名前空間の読者に公開されるため、管理者はそのテキストを全員向けに承認することになります。
書き込みがコミットされた後に公開または昇格が失敗すると、通常の名前空間全体の定義と保留中の候補が残ります。通常の取得では、その行を読み取れます。再試行では、変更のない完全一致のヘッドを書き換えずに昇格します。候補を却下しても、元の行はそのまま残ります。自動的な取り消しはありません。取り消すと、後から書いた人の同一テキストのメタデータ改訂を上書きしかねないためです。管理者は、メモリの履歴と書き込みオペレーションで意図したテキストを復元するか、特定のバージョンを明示的に削除できます。
消去、監査、アップグレード
名前空間の消去では、query_history_sources.delete によって loom.query_history_sources が削除されます。登録には設定と封印された認証情報が含まれるため、メモリ内容の census 行なしで、このステップに分類されます。候補は、learnings キューの消去の対象範囲に従います。過去の定義の redact では、正規テキストのハッシュ、または redact されたバージョンの候補タグに一致する非公開候補も、すべての候補バージョンにわたってスクラブされます。この処理はレビューリースを使い、空白のテキストを後からレビューすることを拒否し、redact されたテキストをまだ保持している現行のヘッドは保持します。
レビューの監査では、認証された決定アクターと候補が特定されます。内部の memory.set と memory.promote はそれぞれ独自の監査イベントを出し、昇格イベントは memory.lineage がたどる監査リクエスト ID にもなります。ソースの変更では、スコープ付きの登録名が監査されますが、パスワードは監査されません。
非公開種別の生成と昇格では、稼働中のすべてのサーバーとワーカーのハートビートが、登録のマイグレーションに対応していると通知している必要があります。フリートの状態がない場合や読み取れない場合は、フェイルクローズします。どちらのドラフト経路を有効にする前にも、マイグレーションを適用し、すべてのサーバーとワーカーをアップグレードしてください。提供中のビルドに古いものや不明なものがある間は、両方の経路を無効にしておいてください。古いビルドは、非公開候補をフィルタリングせず、登録を消去しません。フリートチェックだけではロールバックを保護できません。古いハートビートが現れる前にチェックを通過するリクエストがあり得るためです。
ロールバックでは、古いリーダーを起動する前にメンテナンスウィンドウが必要です。
knowledge_gaps_enabledとknowledge_query_history_enabledの両方を無効にします。新しい非公開ドラフト、レビュー、ソース登録のリクエストと、クエリ履歴ワーカーのターンを停止します。キューにある作業と、受け付け済みのすべてのモデル呼び出し、レビュー、登録、削除を静止させます。フラグを無効にしても、既存のリクエストやレビューはキャンセルされません。- それらのオペレーションが完了または終了するのを待ってから、不確実なサーバー送信と保持された書き手リースを、それぞれの上限の範囲で解消させます。受け付け済みのオペレーションが候補、決定、登録を書き込める間は、テーブルをクリーンアップしないでください。
- メンテナンスのため対応ビルドだけを実行した状態で、
loom.learnings_queueからknowledge_gapとquery_historyの候補のすべてのバージョンと、loom.query_history_sourcesのすべての登録を削除します。削除が完了するのを待ち、リーダーが使える全ストレージレプリカで、どちらも存在しないことを確認します。通常の候補と公開済みの定義は残してください。その後で初めて、古いリーダーを起動します。
ダウングレードの間は、非公開の生成を無効にしたままにしてください。再び有効にするのは、すべての提供プロセスが登録のマイグレーションに対応してからです。ガバナンス対象のメモリと共有行には、既存のアップグレードルールが引き続き適用されます。
ソースのエントリポイント
server/memory/app/definition_drafts.py: 永続的なクレームと、上限付きの生成。server/memory/app/definition_review.py: フリートのゲート、昇格、候補の redact。server/knowledge/app/gap_drafts.py: 現在のギャップの適格性と同意。server/knowledge/app/query_history_sources.py: 登録と認証情報のチェック。server/knowledge/store/query_history_remote.py: 読み取り専用のグループ化されたクエリログの読み取り。server/knowledge/workers/query_history.py: 上限付きのソースローテーション。
不変条件
- 管理者だけが、非公開候補を読み取ったり、レビューを通じて公開したりできます。
- モデルの補完が、候補の決定を置き換えたり、消去された根拠を復活させたりすることはありません。
- ソースの登録が名前空間の消去後も残り、ドラフトを生成し続けることはありません。
- 拒否または中断された昇格が、書き手の行を元に戻すことはありません。