段階的な導入

Laya が返すのは型付きの意思決定であり、それを実行する許可ではありません。証拠が積み上がる間、アプリケーションが実際のアクションの制御を保てるよう、意思決定エンジンを段階的に導入します。

このガイドは Laya を中心としたアプリケーション側のロールアウトを説明します。Laya は意思決定、確率、信頼度、フックイベントを提供します。現行のアクション、ロールアウト方針、レビュー境界、ロールバックはアプリケーションが持ちます。

1. シャドー：副作用なしで観察する

代表的な実トラフィックで Laya を動かしつつ、現行のアクションを権威あるものとして保ちます。シャドー記録には、後で比較を再現できるだけのコンテキストを含めます。

リクエストのクラスと Laya の質問スキーマ
Laya の答え、選択肢ごとの確率、信頼度、チェックポイント、run_id
現行のアクションと、最終的にレビュー済みまたは正解となった結果
レイテンシ、エラー、フォールバックやレビューの判断

Laya 側の証拠には既存の予測フックを使います。以下のログ関数はアプリケーション側のプレースホルダーであり、Laya の API ではありません：

from laya import Router

class ShadowLog:
    def on_predict_end(self, ctx):
        result = ctx.results[0] if ctx.results else None
        write_shadow_record({
            "run_id": ctx.run_id,
            "model": ctx.model,
            "decision": ctx.decision,
            "result": result,
            "elapsed_ms": ctx.elapsed_ms,
            "error": None if ctx.error is None else repr(ctx.error),
        })

router = Router(hooks=[ShadowLog()])

def handle(request):
    try:
        laya_result = router.predict(request.state, request.questions)
    except Exception as exc:
        record_laya_failure(request, exc)
        return run_incumbent_action(request)
    # The shadow result is recorded by the hook; do not execute it here.
    return run_incumbent_action(request)

機微なフィールドはアプリケーションの方針に従って伏せてください。アプリケーション境界で router.predict(...) の周りの例外を捕捉してログに記録します。予測フックは予測のライフサイクルを対象としますが、そのライフサイクルより前の失敗はアプリケーション側での捕捉が必要です。 on_predict_end がそれらを見たと想定しないでください。シャドーのロガーがログを新しいユーザー向けアクションに変えてはいけません。

イベントの順序と run_id の相関については、予測フック、フックのライフサイクル、トレーシングを参照してください。

2. 比較：不一致は信号であり、判定ではない

同じリクエストと同じ質問の意味で Laya と現行を比較します。不一致は自動的にエラーではありません。現行が間違っていることも、ケースが曖昧なことも、そのアクションに人の判断が要ることもあります。利用できる場合はレビュー済みラベルや正解の結果を使い、すべての不一致を二値のスコアに押し込むのではなく、明示的な unknown またはレビューのバケットを保ちます。

比較はチェックポイント、言語またはルート、質問スキーマ、アクション種別、リスククラスごとにレビューします。カバレッジと不一致を精度と並べて記録します。易しい部分集合での高い一致率は、別の言語、アクション、質問形への昇格を正当化しません。

3. ホールドアウトの証拠から方針を選ぶ

信頼度のしきい値はアプリケーションの方針であり、Laya が提供する性質ではありません。代表的なホールドアウトデータで意思決定スコアをフィットまたはキャリブレーションし、次に、アプリケーションが許容できるカバレッジにおける実測の精度とエラーコストからしきい値を選びます。チェックポイント、質問タイプ、言語、アクションのリスクをまたいで移せる普遍的な数値はありません。

方針とともに、チェックポイントと質問スキーマのバージョン、キャリブレーション手法、しきい値、評価セット、オーナーを記録します。それらの入力が変わったら再評価します。信頼度は意思決定を順序付けるものであり、その意思決定が正しいことを確立するものではありません。そして高い信頼度それ自体が実行許可になることは決してありません。

その 6 つのうち 4 つは評価 harness から得られます。laya-evals run --json のレポートは、回答したチェックポイントのコミット（config.revisions）、データセットのバイト列と質問スキーマ（config.dataset_sha256、config.questions_sha256）、スコア付けに使ったゲート（config.thresholds）を記録します。キャリブレーション手法とオーナーはアプリケーションが記録するものです。実行の同一性と、ベースラインと候補の間の比較可能性の検査については評価 harness を参照してください。

README の Automated Confidence Gating、 Calibration、 Honest limits の各節が、既存のキャリブレーションと信頼度の文脈を与えます。不可逆または高コストのアクションは、信頼度が高くても明示的なレビュー境界の内側に置いてください。

4. 限定されたスライスを昇格する

昇格は全体のオン/オフスイッチではなく、測定され、可逆な変更であるべきです。自動化を有効にする前に適格性の境界を定義します。たとえば：

チェックポイント、言語/ルート、質問スキーマが評価済みの集合にある
アクションが可逆であるか、明示的な人手レビューの経路がある
リクエストに必須のコンテキストが欠けておらず、Laya のエラーがない
スライスにサイズまたはトラフィックの上限があり、ロールバック条件が名指しされている

小さなカナリアから始めます。適格でないケース、曖昧なケース、失敗したケースにはレビューやフォールバックを残します。昇格した意思決定のサンプリングを続け、現行およびレビュー済みの結果と比較し、不一致、カバレッジ、フォールバック率、エラー、レイテンシを監視します。合意したガードレールを破ったらロールバックします。昇格は限定された一歩であり、モデルが正しいという永続的な宣言ではありません。

アプリケーションと Laya の境界

Laya は意思決定の証拠を提供し、既存の API とフックを通じて公開します。現行の結果、アクションの実行、適格性のルール、しきい値、レビュー、フォールバック、ロールバックはアプリケーションが持ちます。フックは証拠を記録したり注釈を付けたりできますが、影響の大きいアクションの実行を安全にするものではありません。

したがって実務的なロールアウトはこうなります：

real request
    ├─ incumbent action (authoritative)
    └─ Laya shadow decision ──> log, compare, evaluate
                                  └─ bounded eligible slice
                                      └─ review / fallback / rollback

ロールアウトのチェックリスト

シャドーのログは副作用がなく、run_id で相関している。
比較データには現行の結果と、利用できる場合はレビュー済みまたは正解のラベルが含まれる。
しきい値は代表的なホールドアウトデータでフィットし検証されている。
不可逆または高コストのアクションには明示的なレビュー境界がある。
昇格は限定され、サンプリングされ、可逆で、名指しされたフォールバックとロールバックの経路がある。
方針のオーナーと再評価のトリガーが記録されている。

参照

予測フック —— 監査、メトリクス、ゲートのための拡張点。
評価 harness —— ベースラインが持つ実行の同一性と、ベースラインと候補の間の比較可能性の検査。
フック API リファレンス —— PredictContext のフィールドとライフサイクルイベント。
トレーシング —— run_id とスパンの相関。
README: Automated Confidence Gating —— 信頼度は方針の入力であり、正しさの保証ではありません。
README: Calibration と Honest limits。