Yabanin — シャドウモード (v9)
シャドウモードは、シミュレーションではなく実際の本番データで経路の問いに答えます。すでに処理済みの実際のリクエストのうち、サンプリングされた一部を候補のモデル/プロバイダへ静かに再送し、候補の実際のコストとレイテンシを、プライマリリクエストの行の隣に記録します。比較は見積もりではなくなります。
これはゲートウェイの機能です。デフォルトではオフであり、オンのあいだは実際の費用がかかり、クライアントのレスポンスに影響することは決してないように作られています。
三つの不変条件
- 必須のパススルー。 クライアントのレスポンスは、シャドウ呼び出しが発火する前に、ワイヤへ完全に書き込まれます。シャドウのエラー、タイムアウト、パニック、そして完全に死んだシャドウプロバイダは、クライアントからはバイト単位で見えません。テストスイートがこれを証明します(シャドウのエラー/タイムアウト/パニックの各ケースは、いずれもプライマリのレスポンスが変わらないことをアサートします)。
- フェイルセーフなデフォルト。 デフォルトではオ フです。レジデンシーが固定された組織をスキップし、すでにシャドウモデルへ向かっているリクエストをスキップします。サンプリングされ、同時実行数に上限があり、タイムアウトで区切られ、任意で予算に上限があります。ランタイムのキルスイッチがあります。(ストリーミングのプライマリはミラーされます — ストリーミングの立場 を参照してください。)
- 正直な会計。 シャドウのコストは、シャドウプロバイダでの実際の支出です。独自の
request_logs行(ab_group='shadow'、プライマリと同じrequest_id)として保存され、クライアントに見えるすべての支出集計から除外され、クライアントのクレジットから決して差し引かれません。
動作の仕組み
client ──POST /v1/chat/completions──▶ gateway
│
├─ primary upstream call ──▶ response ──▶ client (always)
│
└─ AFTER the response is written:
eligible? (see gates) ──▶ goroutine:
shadow upstream call
usage → cost
event: request.shadow_completed
│
loggerd ──▶ request_logs
(ab_group='shadow',
same request_id)
リクエストごとのゲート(最初の失敗が優先され、それぞれ独自のスキップメトリクスを持ちます):
| ゲート | スキッ プ理由 | 備考 |
|---|---|---|
| 機能が有効(ランタイム状態) | disabled | 環境設定、または管理トグル |
| プライマリモデル ≠ シャドウモデル | same_model | 自分自身へのミラーは無駄です |
サンプル抽選 < sample_rate | sampling | デフォルト 10% |
| 組織がレジデンシー固定されていない | residency | 固定された組織のデータは、リージョンの外へ出てはならない場合があります |
| 日次予算に余裕がある | budget_exhausted | インメモリ、UTC 日、助言的 |
| 同時実行スロットが猶予内 | semaphore | デフォルトはインフライト 4、猶予 250 ms |
ストリーミングのゲートはありません。プライマリリクエストがストリームするかどうかは、ミラーの判断に含まれません。シャドウ呼び出しは、常に候補への通常の非ストリーミングリクエストです(ゲートウェイはシャドウのボディで "stream": false を強制します)。そのため、ストリーミングのプライマリは非ストリーミングのものと同じようにミラーされます。
設定
すべての変数は任意です。未設定のものは、機能をオフのままにするか、安全なデフォルトに保ちます。
| 変数 | デフォルト | 意味 |
|---|---|---|
YABANIN_SHADOW_ENABLED | false | マスタースイッチ(環境レベル。ランタイムのトグルが実行時に上書きします) |
YABANIN_SHADOW_MODEL | — | ミラー先の候補モデル(有効化時は必須) |
YABANIN_SHADOW_UPSTREAM_URL | プライマリのアップストリーム | シャドウプロバイダのベース URL(同じプールを通ります → SSRF の許可リストが適用されます) |
YABANIN_SHADOW_API_KEY | ゲートウェイのキー | シャドウプロバイダへ提示するキー |
YABANIN_SHADOW_SAMPLE_RATE | 0.10 | 対象となるリクエストのうちミラーする割合(0..1、クランプされます) |
YABANIN_SHADOW_TIMEOUT | 30s | シャドウ呼び出しごとの期限 |
YABANIN_SHADOW_MAX_CONCURRENT | 4 | インフライトのシャドウ呼び出しの上限 |
YABANIN_SHADOW_DAILY_BUDGET_USD | 0(無制限) | 日次の実支出上限。UTC 日、助言的 |
config.yaml の gateway.shadow.* 配下にある YAML 相当です。
無効な設定(例: モデルなしで有効化)は、警告ログとともに無効へ劣化します — シャドウは可観測性であり、リクエスト経路の依存ではありません。タイプミスでゲートウェイを停止させてはなりません。
ランタイムのキルスイッチ
ゲートウェイの管理リスナー(デフォルト :9090。/metrics を提供するのと同じもの)上で:
# current state (never includes the API key)
curl -H "Authorization: Bearer $YABANIN_METRICS_BEARER_KEY" \
http://gateway:9090/admin/shadow/status
# flip at runtime (no restart)
curl -X POST -H "Authorization: Bearer $YABANIN_METRICS_BEARER_KEY" \
-d '{"enabled": false}' http://gateway:9090/admin/shadow/toggle
- フェイルクローズドな認証。
/metricsとは異なり(キーが未設定のときはネットワーク制限のみへフォールバックします)、トグルはYABANIN_METRICS_BEARER_KEYを必須とします。キーが未設定 ⇒403です。費用のかかる制御は、デフォルトで開いてはなりません。定数時間の比較です。 - セマンティクス: インフライトのシャドウ呼び出しは完了します。無効のあいだ、新しい呼び出しは開始しません。
- トグルはプロセスローカルです。再起動すると、状態は環境設定へリセットされます。複数レプリカの導入では、各レプリカをトグルしてください(共有状態は設計上 v9 の範囲外です。マイグレーションか新しいプロトコルが必要になり、どちらも凍結されています)。
- シャドウがまったく設定されていないときは
409です。
コストへの影響(有効化する前に読んでください)
シャドウ呼び出しはシャドウプロバイダへの実際のリクエストであり、実際の費用がかかります。 忙しい組織での 10% サンプルは 10% の追加支出であり、シャドウプロバイダ自身の課金周期で請求されます。
意味のある量がある組織では、YABANIN_SHADOW_DAILY_BUDGET_USD を設定してください。台帳はプロセスごとのインメモリです(再起動でリセットされ、UTC の深夜に繰り上がります)。助言的であり、請求グレードではありません。
yabanin_shadow_cost_usd_total(Prometheus)と yabanin_shadow_budget_exhausted_total を監視してください。
比較エンドポイントは、経路の判断に必要な、リクエストごとの答えを伝えます。
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
"https://admin/api/analytics/shadow?days=30"
レスポンス(形):
{
"period": "last_30_days",
"primary_model": "gpt-4o-mini",
"shadow_model": "gpt-4o",
"overlap": 1240,
"primary_avg_usd": 0.00042,
"shadow_avg_usd": 0.0021,
"delta_pct": 399.9,
"verdict": "pricier",
"by_model": [ ... ]
}
判定: cheaper / pricier / insufficient_data。重なるリクエストが 20 未満、または |delta| が 1% 未満の場合、判定は insufficient_data です — エンドポイントは、ノイズに対して過大な主張をすることを拒みます。シャドウのトラフィックがないウィンドウは有効なレポート(overlap: 0)であり、エラーではありません。
会計のセマンティクス
- シャドウの結果は、別の
request_logs行として保存されます。同じrequest_id、ab_group='shadow'、model_used= シャドウモデル、cost_in_usd= シャドウ呼び出しの実際に計算されたコストであり、エラー時のトークン/コストはゼロです。 counterfactual_cost_usdはシャドウには使われません。その列はキャッシュの反実仮想に属します。経路の反実仮想とキャッシュの反実仮想は異なる量であり、ab_groupの識別子なしに列を共有してはなりません。- クライアントに見えるすべての集計(節約レポート、コストの利用分析、キャッシュの利用分析、支出アラート、リクエスト統計、上位のモデル/組織、時系列、エラーの内訳、レイテンシのパーセンタイル、最近のエラー)は、明示的に
ab_group='shadow'を除外します。 - クレジットの Deductor がシャドウ行に対して呼ばれることは決してありません。 Deductor は
request_idで重複を排除します。プライマリの id を共有するシャドウ行は、組織へ二重に課金します。これは専用テストを持つ硬い不変条件です。
レジデンシーの立場
レジデンシーピンを持つ組織(organizations.residency_region が global 以外に設定されているもの)がミラーされることは決してありません。そのデータはピンされたリージョンの外へ出てはならず、シャドウプロバイダは任意です。スキップは yabanin_shadow_skipped_total{reason="residency"} に計上されます。組織ごとのオプトインには新しい列が必要です ⇒ マイグレーション ⇒ 凍結、となるため、範囲外です。
ストリーミングの立場
ストリーミングのプライマリはミラーされます(v10)。ゲートウェイは、アップストリーム接続が成功した直後(ドレインの前)に、ストリーミング経路からシャドウ呼び出しを発火します。そのため、候補のレイテンシは実負荷と同時に計測されます。
シャドウ呼び出し自体は、常に候補への通常の非ストリーミングリクエストです。ゲートウェイはシャドウのボディを書き換え、"stream": false を強制します。シャドウのストリームを誰かに再送する意味はありません — シャドウモードが必要とするのは、候補の実際のトークン、コスト、レイテンシだけであり、通常の補完がそれらを返します。クライアントの SSE バイトが触れられることは決してありません(シャドウは独自のコンテキストを持つ独自のゴルーチンで動きます。SSE のパススルー不変条件のテストは、シャドウ対象が死んでいるかハングしていても、ストリームがバイト単位で変わらないことをアサートします)。
正直さに関する注意: シャドウの使用量は非ストリーミング呼び出しで計測されますが、プライマリはストリームしていた可能性があります。プロバイ ダはトランスポートごとにキャッシュとチャンク分割を異なる方法で適用するため、トークン数はわずかに異なり得ます。コスト比較としてはこれは許容され、「候補ならいくらかかったか」が意味するところです。ビット単位で正確な再生ではありません。
可観測性
Prometheus(ゲートウェイの /metrics。メトリクスとシャドウがオンのときに登録されます):
| メトリクス | 意味 |
|---|---|
yabanin_shadow_requests_total{result} | 結果: completed/error/timeout/panic/skipped |
yabanin_shadow_skipped_total{reason} | ゲートの内訳 |
yabanin_shadow_latency_seconds{model} | シャドウ呼び出しの所要時間 |
yabanin_shadow_cost_usd_total{model} | 実際に支出した USD |
yabanin_shadow_budget_exhausted_total | 予算によるスキップ |
yabanin_shadow_enabled | ランタイム状態のゲージ(1/0) |
Grafana ダッシュボード。 deploy/grafana/dashboards/shadow.json は自動でプロビジョニングされます(他の Yabanin ダッシュボードと同様です)。Yabanin — Shadow Mode は、有効状態、支出レート(USD/s)、消費した予算(24 時間)、予算枯渇イベント(1 時間)、結果別のリクエスト、理由別のスキップ、モデル別のレイテンシ P95、モデル別の支出を表示します。Grafana ホストで開いてください(デモ: http://localhost:3001、admin / yabanin)。
アラート。 deploy/prometheus/alert-rules.yml(グループ yabanin-shadow):
ShadowHighErrorRate(warning)— シャドウのトラフィックが流れているあいだ、15 分間でシャドウ呼び出しの 50% 超が失敗しています。継続するエラーは、対象の設定ミスか到達不能を意味します。ShadowBudgetBurn(info)— 日次の予算上限が新しいシャドウ呼び出しをブロックしています。YABANIN_SHADOW_DAILY_BUDGET_USDを調整するか、サンプル率を下げてください。
ランブック
- 候補を選びます。
YABANIN_SHADOW_MODELを設定します(別のプロバイダなら URL/キーも)。 - 小さく始めます。
YABANIN_SHADOW_SAMPLE_RATE=0.05、実際に承認できる数字のYABANIN_SHADOW_DAILY_BUDGET_USD。YABANIN_SHADOW_ENABLED=true。 - 24–72 時間動かします。
shadow_requests_total{result="error"}を監視してください — 継続するエラーは、対象の設定ミス(または想定したワイヤプロトコルを話さないこと)を意味します。その場合、使用量/コストはゼロであり、行は役に立ちません。 /api/analytics/shadow?days=Nを読みます。判断します。- 問いが答え られたらオフにします(トグルまたは環境変数)。読まないシャドウのトラフィックは、費やす必要のないお金です。
これが何ではないか
- A/B テストではありません。クライアントは常にプライマリモデルの答えを受け取ります。
- ロードバランサでもフェイルオーバー経路でもありません。シャドウ呼び出しは、独自のコンテキストによるファイア・アンド・フォーゲットです。リクエストコンテキストのキャンセルはそこへ届かず、レスポンスへも届きません。
- 請求ではありません。シャドウの支出は運用者のものであり、決してクライアントのものではありません。