<a id="cost-budgets"></a>

# コスト予算

<!-- i18n: source=docs/architecture/cost-budgets.md blob=932ba3cd2049b60a49294a5dd87fa51b9401b693 model=claude-sonnet-5-5 -->
> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/architecture/cost-budgets.md)の機械翻訳です。内容は英語の原文が優先されます。
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/architecture/cost-budgets.md), which is authoritative.


名前空間とネームドユーザーの上限は、`agent_events` のローリング 24 時間コスト台帳を使用します。正の値を持つ名前空間ポリシーは、対応するサーバーのデフォルト値を上書きします。0 は継承を意味し、両方のティアで 0 の場合はその上限が無効になります。ネームドユーザーの上限は、名前空間の上限とは独立しています。どちらかに達すると、アドミッションは有料の合成を拒否し、モデルルーティングはより大きい支出割合を使用します。`memory.ask`（ドキュメント全体のルートを含む）、`code.ask`、`knowledge.synthesize`、`code.search` のクエリ拡張は、台帳に記録される論理ユーザーを供給します。名前空間全体のワーカーは名前空間のアカウンティングを維持し、トークンのサブジェクトが帰属先のないユーザーの代わりに使われることはありません。これらのソフトコントロールは、支出を予約せず、課金 ID も確立しません。

`cost.budget_status` は、ガードとポリシーおよび支出の読み取りを共有します。ユーザーモードでは名前空間が必須で、ユーザーの上限と判定に加えて `namespace_over_cap` を返します。ユーザーの正確な支出額とその割合は、呼び出し元が名前空間ロールの制限を受けない検証済みのプラットフォーム管理者でない限り `null` になります。これはすべてのイベントが通常のものである場合でも同じです。数値の有無を変えると、マークされたアクティビティが明らかになってしまうためです。認証がない場合、非公開の支出へのアクセスは許可されません。内部のアカウンティング、アドミッション、予算プレッシャーには、マークされたリクエストを含むすべての支出が含まれます。名前空間と組織の合計は数値のままです。トランスポートのアドミッションは、トークンに固定されたユーザーを強制します。名前空間モードと組織モードは、既存の読み取りスコープを維持します。[コストガイド](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/cost-and-usage.md#daily-spend-caps)に、設定と警告のタイミングが記載されています。

オプションの `budget_alert_inbox` には、同じ組織内で、その予算の名前空間が所有する既存の inbox を指定する必要があります。登録時に検証され、配信時に所有権が再確認されます。ポイントチェックとステータスポーリングは、既存のタスクイベントストリームを通じて、上限付きのバックグラウンド警告をスケジュールします。保留中の配信は 1 プロセスあたり最大 32 件です。1 つの組織への配信はプロセス内で直列に実行されるため、名前空間の警告とユーザーの警告が競合しません。ディスカバリーワーカーはありません。イベント ID には、組織、名前空間、inbox、選択されたユーザー、上限、警告の割合、UTC の日付が含まれます。分散クレームと強い整合性を持つイベント読み取りがチェックと挿入を直列化し、重複排除トークンと読み戻しが不確実なリトライを処理します。通知の失敗が上限の判定を変えることはありません。

ユーザー警告のペイロードには、選択されたユーザー、上限、警告の割合が含まれ、`spent_24h_usd: null` となります。これは、オペレーターのチェックが配信を引き起こした場合でも、inbox、ポーリング、ストリーム、webhook のすべてに当てはまります。開始者の権限が受信者の権限を確立するわけではないためです。名前空間の警告は、名前空間の支出合計を保持します。ユーザー上限の判定と警告しきい値の超過は、支出の範囲を明らかにします。上限を変更する管理者は、より狭い範囲を推測できます。これは、[マークされた支出の合計の例外](https://github.com/ClickHouse/loom/blob/main/docs/architecture/document-sources.md)と並んで許容されるポリシーシグナルであり、完全な非干渉ではありません。マークされた作業、モデル、結果へのアクセスは許可されません。

タスク更新とウォッチストリームは、ページネーションの前に、呼び出し元のユーザーとセッションのスコープを警告に適用します。スコープが不完全な場合、警告は受信されません。通常のタスクイベントは inbox 内で共有されたままです。登録された inbox の webhook は、その名前空間のストリームを受信します。

すべての配信とタスクイベントの消去は、同じ組織全体の warning-writer リースを取得します。挿入には、既存のサーバー側の開始期限と実行上限が使われ、リースの TTL は作業ウィンドウと送信上限全体の合計を超えます。不確実な挿入やキャンセルが発生した場合、そのリースは期限切れになるまで残るため、起こりうるすべての送信が完了するまで消去はリースを取得できません。消去は、タグ付きミューテーション、ポーリング、再開のプロトコルを維持します。公開の前後に行う台帳チェックは、消去と競合した観測を無効にします。書き込み後のクリーンアップは、その配信の正確なイベントとシーケンスのみを対象とします。台帳が読み取れない場合、公開は拒否されます。

警告行には、完全な ID タプル、プロセスアクター、導出されたソースクラスが含まれます。ユーザーの消去はそのタスクイベントを削除し、残存データの調査で削除が検証されます。名前空間の消去はタスクとイベントの両方を対象とします。追加された列には、古いライターのためのデフォルト値があります。警告の生成は、稼働中のすべてのレプリカがマイグレーションをサポートするまで待機するため、ローリングアップグレード中に古い消去実装がユーザーを含む警告行を見逃すことはありません。フリートの状態が不明な場合、公開は後のチェックまで延期されます。

<a id="activation-and-rollback"></a>

## 有効化とロールバック

ユーザー上限と予算警告には、稼働中のすべてのビルドがマイグレーション 107 をサポートしている必要があります。ストアを共有するいずれかのデプロイメントが古いビルドを実行している間、またはそのバージョンが不明な間は、`LOOM_DEFAULT_DAILY_USER_COST_CAP_USD` とすべての名前空間の `daily_user_cost_cap_usd` を 0 のままにし、`budget_alert_inbox` を空にしてください。この期間中はユーザー上限に依存しないでください。これらのポリシーを設定する前に、マイグレーションを適用し、稼働中のすべてのプロセスをアップグレードしてください。警告のフリートチェックは、古いフリートや不明なフリートでは生成を延期しますが、すでに保存されている警告は削除しません。

ロールバックの前に、グローバルなユーザー上限のデフォルト値と、各名前空間のユーザー上限および警告 inbox を保存してください。ロールバックにはメンテナンス期間が必要です。

1. ストアを共有するすべてのデプロイメントにわたり、予算をチェックしたり警告をスケジュールしたりできる、リクエストを処理するプロセスとバックグラウンドプロセスをすべて停止します。ステータスポーリングも停止します。バックグラウンドワーカーをオフにしたり inbox ポリシーをクリアしたりするだけでは、その inbox ですでにスケジュールされた配信は止まりません。
2. クリーンアップの前に、スケジュールされた配信をドレインし、実行中または不確実な書き込みをすべて確定させます。warning-writer リースが解放されるか期限切れになるのを待ち、その遅延開始とサーバー実行の上限ウィンドウが終了するまで待ってください。ドレインの中断や実行中クエリの一覧が空であることは、遅延した送信がまだ到達しえないことの証明にはなりません。
3. `event` が `budget.warning` である `loom.task_events` の行のみを消去します。最初の古いプロセスを起動する前に、すべてのストレージレプリカで削除が完了するのを待ち、どのレプリカにも警告行が残っていないことを確認してください。読み取れないレプリカや確定していない書き込みがある場合、ロールバックはブロックされます。名前空間やユーザーの消去は代わりになりません。無関係なデータも削除されるためです。
4. 古いビルドが稼働している間は、ユーザー上限と警告を無効のままにします。稼働中のすべてのプロセスが再びマイグレーション 107 をサポートしたら、保存したグローバルのデフォルト値を復元し、`namespace.register` で名前空間のユーザー上限と警告 inbox を再適用します。警告の生成を再開する前に、名前空間のポリシーを読み取り、有効な上限を確認してください。

これにより、バージョン混在運用中の有効化が制限され、ロールバック中はプライバシーのために可用性が犠牲になります。古いタスクリーダーは非公開の警告をフィルタリングせず、古いユーザー消去はそれらを削除しません。また、古い名前空間登録はユーザー上限と警告 inbox の列も省略するため、置き換え後の行ではこれらのポリシーがデフォルト値にリセットされます。名前空間レジストリは、古い書き込みを通じてこれらの列を引き継ぎません。そのため、オペレーターはロールバック後もポリシーが残ることに頼らず、ポリシーを保存して復元する必要があります。

<a id="source-entry-points"></a>

## ソースのエントリポイント

- `server/observability/budget.py`: `budget_snapshot` は、ガードとステータスのためにポリシーとローリング支出を読み取ります。
- `server/tasks/app/budget_notifications.py`: `deliver` は警告のクレームと消去フェンスを管理します。
- `server/tasks/store/repo.py`: `events_since` は、カーソルによるページネーションの前に警告スコープを適用します。
- `server/tasks/app/reads.py` と `server/tasks/app/watch_routes.py`: ポーリングとストリーミングのリーダーがそのスコープをバインドします。
- `server/erasure/store/steps_ledgers.py`: warning-writer リースがタスクイベントの削除を保護します。

<a id="invariants"></a>

## 不変条件

- ネームドユーザーの許容額が名前空間の上限を引き上げることはなく、帰属の際にトークンのサブジェクトが推測されることもありません。
- 絞り込まれたリーダーは、そのユーザーとセッションのスコープ外の警告を受信しません。
- 不確実な警告の書き込みがあると、起こりうる送信が完了するまで消去はフェンスされたままになります。
- 通知の失敗が上限の判定を変えることはありません。
