メインコンテンツまでスキップ

評価スイート

yb CLI には、固定のラベル付きデータセット上で、変更の前と後に経路の品質とガードフックの検出品質を測る、2 つのオフライン評価コマンドがあります。どちらも決定的で、CI で実行できます。

yb evaluate routing --golden datasets/eval/golden_routing.jsonl [--save] [--against datasets/eval/routing_baseline.json] [--max-mismatch N]
yb evaluate guards --corpus datasets/eval/guards_labeled.jsonl [--min-precision 0.98] [--min-recall 0.90]
yb evaluate guards --revision datasets/eval/guards-revision.json [--min-precision 0.98] [--min-recall 0.90]

Make ターゲットは、これらをラップします。

make evaluate-routing
make evaluate-guards

make evaluate-guards ターゲットは、引き続きレガシーの --corpus 入力を使います。結果に、評価した正確なローカルのリビジョンドキュメントを特定させたいときは、--revision を直接使います。


経路の回帰(yb evaluate routing)​

経路は、分類器とティアルータのパイプラインです。分類器、ルール、料金、またはルータを変えると、プロンプトが着地するモデルが、気づかないうちにずれることがあります。経路の評価は、その挙動を固定します。

データセット。 datasets/eval/golden_routing.jsonl は、ラベル付きのリクエスト集合です。各行は 1 件のリクエスト(プロンプトとメタデータ)と、現在の経路の方針のもとで対応すべき経路のティアです。この集合は、本番の rule_tier の挙動に一致するよう生成されているため、「正しさのオラクル」ではなく、回帰のベースラインです。

動作。

  1. すべての行に対して、現在の経路パイプラインを実行します。
  2. 結果のティアをゴールデンラベルと比較します。
  3. 不一致の件数と率を報告します。
  4. --save を付けると、現在の対応関係のスナップショット(datasets/eval/routing_baseline.json)を書き出します。--against <file> を付けると、現在の実行を保存済みベースラインと比較し、変わった行を報告します。
  5. --max-mismatch N は、不一致の行が N を超えると、コマンドを失敗させます(0 以外の終了コード)。これを CI に組み込み、経路の回帰を捕捉します。

クリーンな実行とは、現在のパイプラインがゴールデンのティアを再現する実行です。--against を使う場合は、保存済みベースラインを再現する実行です。


ガード検出(yb evaluate guards)​

ガードフック(エージェントガバナンスを参照)は、決定的な検出器です。ガードの評価は、ラベル付きコーパスに対する適合率と再現率を測ります。

データセット。 datasets/eval/guards_labeled.jsonl は、ラベル付きサンプルの集合です。陽性の行には、チェックディジットまたは Luhn で検証された本物の機微データ(INN、SNILS、PAN、シークレット、またはインジェクション句)が含まれ、検出器はこれにフラグを立てるべきです。陰性の行はクリーンです。これには、機微に見えてチェックサムには失敗するデコイ(たとえば、有効な INN ではない 10 桁の並び)が含まれ、検出器はフラグを立てるべきではありません。コーパスは scripts/gen_guards_corpus.py が生成します。このスクリプトは有効なチェックサムを計算するため、陽性ラベルは本物です。

動作。

  1. すべての行に対して検出器を実行します。
  2. ラベルに対して採点します。真陽性、偽陽性、偽陰性です。
  3. 適合率(検出され、かつ正しいもの / 検出されたもの)と再現率(検出されたもの / 検出すべきもの)を報告します。
  4. 適合率が --min-precision(デフォルト 0.98)未満、または再現率が --min-recall(デフォルト 0.90)未満のとき、失敗します(0 以外の終了コード)。

デフォルトは意図的に厳格です。deny モードで動くガードは、正当なトラフィックをブロックしないために非常に高い適合率と、機微データを漏らさないために高い再現率を持たなければなりません。

ローカルのガードデータセットのリビジョンを固定する​

--revision FILE は、--corpus FILE に対するオプトインの代替です。明示的なスキーマバージョン、データセット ID、サンプル ID を持つローカルの JSON ドキュメントを読みます。各サンプルのペイロードは、ガード評価器と同じ text、type、expect フィールドを使います。

--revision オプションを含むコミットの yb ビルドを使ってください。インストールすべき、別途リリースされた最小バージョンはありません。yb version でバイナリを確認します。古いバイナリが未知の --revision フラグを報告する場合は、このオプションを含むビルドへ再ビルドまたはアップグレードするか、レガシーの --corpus 入力を使い続けます。

たとえば、小さな合成リビジョンは次のようになります。

{
"schema_version": 1,
"dataset_id": "demo-guards",
"samples": [
{
"id": "sample-detect-1",
"payload": {
"text": "<SYNTHETIC_SECRET>",
"type": "secret",
"expect": "detect"
}
},
{
"id": "sample-clean-1",
"payload": {
"text": "ordinary synthetic text",
"type": "clean",
"expect": "clean"
}
}
]
}

guards-revision.json として保存します。評価する前に、合成シークレットのフィクスチャを生成してください。実際の資格情報は使わないでください。

python3 - <<'PY'
import json
from pathlib import Path

path = Path("guards-revision.json")
revision = json.loads(path.read_text())
revision["samples"][0]["payload"]["text"] = "synthetic marker " + "sk-" + "abcdefghijklmnop12345678"
path.write_text(json.dumps(revision, indent=2) + "\n")
PY
yb evaluate guards --revision guards-revision.json

レポートには、データセット ID と、読み取った正確なバイト列に対する小文字 SHA-256 の revision_id が含まれます。結果を生んだファイルを残し、実行同士を比較する必要があるときは、この ID をメトリクスと一緒に記録します。ファイルを編集すると、そのリビジョン ID は変わります。1 回の呼び出しは、同じメモリ上のバイトスナップショットを評価し、ハッシュします。そのスナップショットを読み取ったあとにファイルが置き換えられても、進行中の結果は、評価したバイト列を依然として特定します。後続の呼び出しは現在のファイルを読み、別のリビジョン ID を報告することがあります。

リビジョンドキュメントは、8 MiB および 10,000 サンプルまでに制限されます。スキーマバージョンは 1 でなければなりません。データセット ID とサンプル ID は空であってはならず、サンプル ID はドキュメント内で一意でなければなりません。各 payload はオブジェクトであり、空でない text と、detect または clean に設定された expect を持たなければなりません。未知のフィールド、繰り返された JSON キー、不正な JSON、末尾にある 2 つ目の JSON ドキュメント、重複するサンプル ID は、メトリクスが出力される前に拒否されます。検証に失敗した場合は、ドキュメントを直し、コマンドを再実行します。--corpus と --revision を同時に渡すのはエラーです。1 回の呼び出しにつき、入力モードは 1 つ選んでください。

レガシーの --corpus オプションとその出力は、引き続き使えます。リビジョン入力は、この CLI の流れにローカルです。サンプルをアップロードしたり永続化したりせず、サーバ側のカタログを追加せず、既存の実行マニフェスト形式も変えません。リビジョン ID は、この評価に使った正確な入力を特定します。データセットの品質を保証するものではなく、別の実行生成側がリビジョン固定を採用したという主張でもありません。


ベースラインの方針​

評価スイートは、ベースラインを保ち、それと比較するためにあります。

  • 経路またはガードに影響する変更の前に、両方の評価を実行し、数値を記録します(または経路のベースラインを --save します)。
  • 変更のあと、再度実行して比較します。経路の回帰は不一致率の上昇として現れます。ガードの回帰は、しきい値を下回る適合率または再現率の低下として現れます。
  • CI では、make evaluate-routing -- --max-mismatch 0 と make evaluate-guards をゲートとして実行します。(--max-mismatch の正確な予算は、方針として選ぶものです。0 が最も厳格で、正確な再現だけを許します。)

PR ゲートとしての評価(yb-eval)​

.github/actions/yb-eval/action.yml にある再利用可能なコンポジットアクションが、これらのスイートをプルリクエストへ組み込みます。

  • リポジトリから、yb バイナリをランナー上でビルドします(ネットワークはありません。経路とガードの評価はプロセス内で、決定的です)。
  • yb evaluate routing --against <baseline> --max-mismatch 0 と yb evaluate guards --min-precision … --min-recall … を実行します。
  • 機械可読のサマリ(成功または失敗とカウンタ)を、yb-eval アーティファクトへ書き出します。
  • PR のサマリコメントを 1 件投稿します(再実行時は置き換え、重複はしません)。
  • どちらかのゲートが赤のとき、ステップを失敗させます(赤いチェック)。経路またはガードの回帰は CI を壊します。

経路、料金、ガードフックのソースと、評価データセットに対するパスフィルタを付けて、pull_request ワークフローへ組み込みます。例:

on:
pull_request:
paths:
- 'pkg/classifier/**'
- 'pkg/router/**'
- 'pkg/guardhooks/**'
- 'pkg/pricing/**'
- 'datasets/eval/**'
- 'cmd/yb/**'
jobs:
eval-gate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ./.github/actions/yb-eval
with:
comment: true

すべての入力にはリポジトリ側のデフォルトがあるため、このアクションはそのまま追加できます。方針に合わせてゲートを緩めるには、routing-max-mismatch、guards-min-precision、または guards-min-recall を上書きします。

これは回帰ハーネスであり、ベンチマークスイートではありません。絶対的な「クラス最高」の数値を追うものではなく、変更が、動かすつもりがなかった挙動を動かさないことを保証します。

ここで報告される数値は、同梱されたデータセットに対して測定されたものです。外部のホワイトペーパーや第三者の評価から引用したものではありません。