評価ハーネス
laya.evals は、ラベル付きデータセットを再現可能なスコアに、ベースラインを合否ゲートに変えます。これにより、品質の変化が手作業の確認ではなくレビュー可能な差分になります。
指標の計算とデータセットのパーサは純粋な Python と numpy だけで書かれており、torch をインポートしないので、重みなしで動きます。データセットをチェックポイントに対して実行するにはチェックポイントが必要で、通常の読み込み時間がかかります。
クイックスタート
# check the format without a model
laya-evals validate research/evals/fixture.jsonl
# score a labelled set on one checkpoint, with thresholds and a baseline
laya-evals run data.jsonl --model english --device cpu \
--min-accuracy 0.8 --max-ece 0.05 --score-within 0.25 --slice language \
--json report.json --markdown report.md
# compare a saved report to a baseline
laya-evals compare report.json --baseline baseline.json --tolerance choice_accuracy=0.02
laya eval ... はメイン CLI から同じことを行うもので、laya eval validate data.jsonl も動きます。
終了コードは、成功時が 0、しきい値かベースラインの許容差に失敗したときが 1、使い方のエラーが 2 です。run は全体の指標と要求されたスライスを標準出力に表示し、--json / --markdown を指定すると完全なレポートと Markdown の要約を書き出します。
反復する教師の判断と生徒を比較する
教師が同じ入力に異なる答えを返すとき、1 つ保存された答えではその再現性を記述できません。compare_agreement は、生徒と独立した教師の反復を、1 つの固定された参照教師観測と比較します。3 つの保存済み実行を取り、モデルの重みも教師サービスも必要としません:
laya-evals agreement reference.json repeat.json student.json \
--bootstrap-samples 2000 --seed 0 --json agreement.json
--json がなければ、コマンドはレポートを標準出力に書きます。--seed はブートストラップだけを制御し、モデル生成は制御しません。成功は 0 で終了し、不正または整列していない実行は 2 で終了します。このコマンドは置換や品質のゲートを適用しません。
各入力は次の形の JSON オブジェクトです:
{
"schema": "laya-agreement-run/1",
"run_id": "teacher-reference",
"provenance": {
"model": "teacher-checkpoint",
"revision": null,
"settings": {"temperature": 0.7, "prompt_template": "Choose one label."},
"seed": 42
},
"cases": [{
"id": "ticket-001",
"state": "I was charged twice.",
"questions": {"route": {
"type": "choice",
"instructions": "Select the team responsible for this request.",
"criteria": ["billing", "support"]
}},
"answers": {"route": "billing"},
"language": "en",
"tags": ["duplicate-charge"]
}]
}
観測実行ごとに異なる run_id を使ってください。3 つの実行は、ちょうど同じ一意のケース id、state、質問定義、言語、タグを含まなければなりません。行の順序は異なってかまいません。state は非 null の JSON でなければなりません。質問定義は選択肢の順序を保ち、空でない criteria の dict か、重複を除いた文字列ラベルのリストを受け付けます。答えはすべての質問を覆わなければなりません。生徒の答えは棄権のために null でかまいません。教師の答えはラベルでなければなりません。欠けたケース、未知のラベル、非有限の JSON 値、CLI 入力の重複した JSON オブジェクトキーは、省略されたサンプルではなくエラーです。
2 つの教師実行は、まったく同じ model、revision、settings を宣言しなければなりません。サンプリングパラメータとプロンプトテンプレートを settings に入れ、反復のシードをその外に置いてください。データセットのリビジョンや生成スクリプトのような他のメタデータは保たれます。可能なら不変のモデルリビジョンを記録し、不明なときは明示的に null を使ってください。レポートは不明なリビジョンを示しますが、記録された来歴が正確であることや、教師の呼び出しが独立していたことは検証できません。入力オブジェクトの順序は有意で、Laya の構造化 state と質問のシリアライズに一致します。実行間で同一に保ってください。
教師レコードを検証した後にローカルの生徒を実行するには:
import json
import laya
from laya.evals import evaluate_agreement
with open("reference.json", encoding="utf-8") as handle:
reference = json.load(handle)
with open("repeat.json", encoding="utf-8") as handle:
repeat = json.load(handle)
revision = "YOUR_CHECKPOINT_COMMIT"
with laya.Router(device="cpu", revision=revision) as runner:
report = evaluate_agreement(
runner, reference, repeat, model="english",
student_provenance={
"model": "convaiinnovations/laya", "revision": revision,
"settings": {"device": "cpu"},
},
)
print(report["overall"])
runner はラベル付きハーネスと同じ predict(state, questions, model=...) プロトコルを使います(たとえば laya.Router)。入力は推論の前にコピーされます。runner の失敗は伝播し、不正または不完全な出力は EvalError を送出します。abstention="abstained" と印付けられた choice は null の観測になりますが、その基になる choice は依然として有効なラベルでなければなりません。
別の laya-agreement-report/1 レポートは、来歴、入力ハッシュ、個々の対にした意思決定、そして質問 id・言語・タグでスライスした率を記録します。すべての意思決定について、教師の反復一致は repeat == reference、生徒の一致は student == reference、対のデルタはその差です。すべての率は意思決定の全件数を使います。棄権は一致 0 として寄与し、student_coverage を下げます。95% パーセンタイル区間は、ケース id 全体をリサンプルし、その質問をまとめて保ち、意思決定の和の比を再計算します。固定の入力、シード、ブートストラップ回数(100〜100000)に対して決定的です。ケースが 2 つ未満なら区間は null です。スライスの率には区間がありません。
一致は accuracy ではなく、教師の再現性は理論上の上限ではありません。どちらのモデルも間違った答えで一致しえます。区間は、保存された観測とともに与えられたケースにわたる変動を記述します。追加の教師生成は捉えません。ゼロを含む区間は等価性を確立しません。ラベルの偏りについてスライスと個々の意思決定を調べ、正しさや較正の主張にはラベル付きの評価を使ってください。
examples/evals/teacher_agreement.py は、固定された公開データセットの 2 つの公開教師観測をローカルの Laya チェックポイントに対して再生し、3 つの実行とそのレポートを保存します。その小さな固定サンプルはワークフローを示すもので、配備の準備ができていることを示すものではありません。
ショートリスト誤りの帰属
ラベル付きの高基数の選択肢集合に対して、laya.evals_shortlist.evaluate_shortlist は既存の predict_shortlist 経路と通常の評価ハーネスを使います。これは 2 つの別々の問いに答えます。検索が正解ラベルを保持したか、そしてそれが存在したときに Laya がそれを選んだかです。これは choice ラベルのためのオプトインの Python API であり、通常の laya-evals run のレポートは変わりません。
import laya
from laya.evals import Dataset
from laya.evals_shortlist import evaluate_shortlist
from laya.shortlist import embed_fn_from_agent
agent = laya.load()
dataset_path = "intents.jsonl"
dataset = Dataset.from_jsonl(dataset_path)
report = evaluate_shortlist(
agent, dataset, embed_fn_from_agent(agent), k=20,
checkpoint_id="my-checkpoint@revision", embedder_id="my-encoder@revision",
dataset_path=dataset_path,
)
print(report.overall)
print(report.cases[0]["shortlist_status"])
計測対象のデプロイと同じ埋め込み関数とチェックポイントを使ってください。2 つの識別子は呼び出し元が指定し、不変のリビジョンを名指すべきです。レポートは任意の callable の背後にある重みを推測できません。dataset_path は、既存の質問指紋と並んでそのファイルの SHA256 を記録します。各ケースは実際のショートリストラベルと、correct、retrieval_miss、decision_miss のいずれかを保持します。shortlist_recall_at_k は保持された正解ラベルの割合です。shortlist_accuracy_on_recalled は保持されたケースで割った正しい意思決定で、1 つも保持されなかったときは省略されます。既存の choice_accuracy は、検索ミスを含むすべてのケースにわたるエンドツーエンドの精度のままです。ショートリストの指標は、同じ言語・モデル・質問・タグのスライスに現れます。リクエストのレイテンシには埋め込みと意思決定の呼び出しが含まれ、レポートは段階ごとのタイミングを分離しません。k >= n のときは、元の質問がそのまま素通りし、埋め込み器を呼ばずに検索再現率は 1 になります。
これは issue #102 の BANKING77 の結果を再現するものではありません。それらの数値は、そのデータセット、チェックポイント、バイエンコーダに依存します。この API は、呼び出し元自身のラベル付きセットで同じ種類の診断を再現可能にします。
ONNX エクスポートの評価
run --onnx PATH は、torch の Router ではなく ONNXAgent を通してエクスポート済みの ONNX モデルを採点します。そのため、ONNX デプロイ(scripts/export_onnx.py --quantize による INT8 コピーを含む)も、torch 経路と同じしきい値とベースラインでゲートされます。
python scripts/export_onnx.py --model convaiinnovations/laya --output laya.onnx --quantize
laya-evals run data.jsonl --onnx laya.int8.onnx --max-ece 0.05
--model はエクスポート元のチェックポイントを指定します。Hub の id かローカルパスで、english のような Router のショートネームではありません(この経路に Router がないため。既定は convaiinnovations/laya)。その config と tokenizer はそこから読み込まれます。エージェントは 1 つのチェックポイントを提供するので、データセットの行の model フィールドが別のチェックポイントを指す場合は、間違ったモデルが黙って答えるのではなく、明確なエラーで失敗します。--device は適用されません。--batch-size はエージェントにバッチ API があればそれを使い、なければ state ごとに 1 回の呼び出しにフォールバックします。--sort-by-length はそのバッチ API に転送されます。state ごとのフォールバックには並べ替えるグループがありません。--calibration PATH を渡すと、適合済みの較正マップを ONNXAgent に読み込み、--max-ece などの較正ゲートが較正済みの確率に対して評価するようになります。レポートの config ブロックには onnx のパスと(設定されていれば)calibration のパスが記録されます。
research/evals/fixture.jsonl(ラベル付き 12 行、英語チェックポイント、CPU)での実測:
| runner | choice_acc | noul_acc | score_mae | ece | mean_conf | p50 ms |
|---|---|---|---|---|---|---|
| torch Router | 0.75 | 1.00 | 1.3418 | 0.1596 | 0.7304 | 116.8 |
--onnx fp32 |
0.75 | 1.00 | 1.3418 | 0.1596 | 0.7304 | 66.3 |
--onnx int8 |
0.75 | 1.00 | 1.3512 | 0.1658 | 0.7304 | 46.3 |
fp32 エクスポートは torch の数値を正確に再現し、量子化コピーは score_mae を 0.009、ece を 0.006 動かします。これは compare --tolerance がゲートすることを想定した種類のドリフトです。
データセット形式
1 行に 1 つの JSON オブジェクト(JSONL)です。空行と # で始まる行は無視されます。
| フィールド | 必須 | 意味 |
|---|---|---|
state |
はい | 判断対象のテキスト、メール、チケット、JSON 文書 |
questions |
はい | Laya の質問 dict。Router.predict が受け取るのとまったく同じ形 |
expected |
はい | 質問 id をキーにした正解。choice はラベル、score は数値、noul は true/false |
tags |
いいえ | スライスに使う文字列 |
language |
いいえ | スライスに使う言語コード |
model |
いいえ | この行のチェックポイントを強制します。--model がこれを上書きします。何も強制しない行は、Router が答えたチェックポイントでラベル付けされます |
research/evals/dataset.template.jsonl にコメント付きの例があります。
指標
各指標は該当する答えごとに計算され、データセット全体で集計されます。
| 指標 | 対象 | 意味 |
|---|---|---|
choice_accuracy |
choice |
選ばれたラベルが一致した割合 |
noul_accuracy |
noul |
真偽値(確率 >= 0.5)が一致した割合 |
score_mae |
score |
平均絶対誤差 |
score_within_<tol> |
score |
絶対許容差の範囲内に入った割合 |
ece |
信頼度と既知のラベルを持つ任意の答え | 期待キャリブレーション誤差。15 ビン、laya.evals._answer_confidence が読む列で計算します —— 答えがそれを運ぶところでは answer["answer_confidence"]、運ばないところではフォールバック。どの信頼度を指標が読むかを参照 |
brier |
信頼度と既知のラベルを持つ任意の答え | 信頼度を P(correct) とした Brier スコア、mean((confidence - correct)**2)。低いほど良い |
aurc |
信頼度と既知のラベルを持つ任意の答え | リスク・カバレッジ曲線の下の面積。異なる信頼度レベルごとに 1 つのリスク値を持ち、それぞれがそのレベルにまたがる答えで重み付けされます。低いほど良く、単に較正されているだけでなく正誤を順位付けできる信頼度を評価します |
selective_accuracy@50、selective_accuracy@80 |
信頼度と既知のラベルを持つ任意の答え | 50% / 80% カバレッジ点における信頼度しきい値が受け入れる答えにわたる精度 —— 最も信頼度の低い裾で棄権することが何をもたらすか。しきい値は等しい信頼度のグループを分割できないので、名目上の割合より多くをカバーしえます。詳しくはカバレッジのカットと同値を参照 |
mean_confidence |
信頼度を持つ任意の答え | 同じ列の平均 —— 答えがそれを運ぶところでは answer["answer_confidence"] |
latency_p50_ms、latency_p95_ms |
リクエストごと | 各リクエストが待った実時間。参考情報 —— バッチ処理とタイミングを参照 |
cost_per_decision_p50_ms、cost_per_decision_p95_ms |
意思決定ごと | 呼び出しの実時間を運んだ行数で割ったもの。参考情報 |
「既知のラベル」とは _correct が判定できるものです。文字列ラベルに対する choice の答え、または真偽値に対する noul の答えです。score の答えはどの許容差でも correct 値を持たないので、それら 5 つの指標すべてから外れます —— ece も含みます。ece、brier、aurc、そして両方の selective_accuracy@* は、同じ 1 つの (confidence, correct) 列を読むからです。したがって score だけのデータセットは、答えがどれだけ確信的でも ece を公開せず、それに対する --max-ece は、計算されなかった数値で合格するのではなく metric 'ece' is not in the report で失敗します。
どの信頼度を指標が読むか
上の表で信頼度を取るすべての行(ece、brier、aurc、両方の selective_accuracy@*、mean_confidence)は、laya.evals._answer_confidence からその列を得ます。これは answer["answer_confidence"] を優先します —— 報告される答えの確率で、temperature スケーリングが当てはめる量です。それは、出荷時のままでその数値が正しいという主張ではありません。両方のベースチェックポイントは過信で、laya-multilingual は当てはめた温度を一切同梱していません —— README の較正を参照 —— これは ece が仮定するのではなく測るものです。
answer_confidence を運ばない答えは、順に confidence へ、次に noul では max(p, 1 - p) へ、次に max(probabilities) へフォールスルーします。これらは異なる量です。choice と score では confidence フィールドは正規化エントロピーで、答えがどれだけ正しいかではなく選択肢数(#394)とともに動きます。max(probabilities) は最上位の選択肢に載る質量で、報告される答えが argmax のときにだけ報告される答えの確率と等しくなります。
実際にフィールドなしで届く形は、厳格な Jev ワイヤ契約です:LAYA_JEV_STRICT はすべての答えから answer_confidence を落とすので(laya/serve.py::_project_jev_strict、そして HTTP API のページのそのフラグの行)、記録された厳格なレスポンスに対して実行されたレポートはエントロピーの数値を較正します。3 つのラベル付き行 —— answer_confidence 0.95 を持つ choice がエントロピーの confidence 0.7887、score が 0.90 対 0.6410、noul が 0.87 —— で測ると、同じデータセットは完全なペイロードで mean_confidence 0.9067、ece 0.0900、厳格な射影で 0.7666、0.1707 をスコアします。2 つのレポートは、答えが同じフィールドを運ぶときにだけ比較可能です。tests/test_evals.py は両方の経路を固定しているので、そのフォールバック順の変更は意図的に行われなければなりません。
カバレッジのカットと同値
両方のカバレッジ指標は信頼度のしきい値でカットし、しきい値はその信頼度にあるすべての答えを受け入れます。したがってカットは、同じ信頼度を共有する答えのグループを決して分割しません。coverage * n がそのようなグループの内側に落ちるとき、グループのすべてのメンバーが受け入れられます。したがってその数値の背後にある答えの数は、名目上の割合ではなくグループの上端です —— 信頼度がすべて等しいスライスに対する selective_accuracy@50 は、そのスライスの良いい半分ではなく、スライス自身の精度です。ゲートが表示するカウント(ルールの失敗メッセージの n=)は、受け入れられたサイズではなくスライスのサイズなので、非常に幅の広いグループはメッセージだけからは見えません。
同値は隅のケースではなく通常のケースです。適合した温度はバケットに点質量を報告させることがあり、laya.common.answer_confidence は出荷済みの choice:11+ についてそれを記録しています。また、実際のチェックポイントは 12 個の答えのうち 6 行がちょうど 1.0 のグループを生みました。代わりに行インデックスでカットすると、両方の指標がデータセットの到着順に依存するようになりました —— 同じ行をシャッフルすると、selective_accuracy@50 は 0.000 と 1.000 の間を動きました。
aurc は異なるレベルごとに 1 つのリスク値を積分し、そのレベルにまたがる答えで重み付けするので、不均一なサイズの点の平均ではなく、リスク・カバレッジ曲線の下の面積のままです。
計画しておく価値のある帰結が 2 つあります。
- 数値は、並べ替えがなしうる以上に、どちらの方向にも動きえます。 グループがカットをまたぐところでは、しきい値の読みは同じデータのあらゆる行インデックスの読みと異なります。400,001 個の同値の形をしたデータセットで測定すると、
selective_accuracy@50では最大 0.500、aurcでは 0.351 でした。上記の 12 個の答えの形 —— 6 個が正しく、すべて信頼度 1.0 —— では、aurcは 0.327(0.173 から 0.500)動きます。合格していたゲートが失敗し、失敗していたゲートが合格しえます。以前の判定は行順に依存しており、絶対的なminやmaxの制限についても同様で、これは単一の実行を読むだけなので何も拒否しません。 - コミット済みのベースラインを再生成してください。
config.coverage_metric_definitionは、どの定義がレポートを生成したかを記録します。2 つの定義にまたがってカバレッジ指標を比較することは、ベースラインを差し引く両方のゲート ——--baseline --tolerance(EvalReport.compare)と、--gate-policyの下の相対ルール(max_drop/max_increase)—— で拒否され、しかもベースラインだけでなくどちらの側が古い場合も拒否されます。古いlayaが生成した候補は行順のアーティファクトを抱えており、真実より良く読めることがあるので、それを正しく再生成されたベースラインに対してゲートすると、正しく採点されたレポートが失敗する回帰を合格させてしまいます。その拒否がなければ、古いベースラインが実際の回帰を隠します。古い定義で 0.033 と記録されたスライスはこの定義では 0.517 と読めるので、本当に 0.217 低下した候補は 0.05 のmax_dropをクリアしてしまいます。eceとbrierはカットせず、比較可能なままです。
データに同値がなければ答えごとに 1 つのレベルがあり、両方の指標はこれまでどおりのものです —— 単に近いのではなく、ビット単位で同一です。
許容差の指標を使うには、評価器のリストに ScoreWithin(0.25) を追加します。既定の評価器セットは choice_accuracy、noul_accuracy、score_mae、mean_confidence です。信頼度の指標は評価器ではなく、オプトインでもありません。ece、brier、aurc、selective_accuracy@50、selective_accuracy@80 はすべて、信頼度と既知のラベルの両方を運ぶ答えが少なくとも 1 つあるすべての実行で計算されます。どんな評価器リストを与えられてもです。CLI からは同じことが 1 つのフラグで済みます。laya-evals run data.jsonl --score-within 0.25 は既定に加えて score_within_0.25 を報告します。フラグは繰り返せるので、--score-within 0.25 --score-within 0.5 は両方を報告します。
許容差の指標には数値ラベル付きの score の答えが必要なので、それがないデータセットでは値を持ちません。run は黙って 0 を出すのではなく計算できなかった指標を名指しし、その指標を名指す --min / --max ゲートは欠落として失敗します。実行に要求された許容差はレポートの config ブロックに記録されるので、レビュー済みのベースラインはどの列を期待するかを示します。
バッチ処理とタイミング
--batch-size N は、チェックポイントと質問スキーマを共有する最大 N 個の連続した行を 1 回の呼び出しで採点します。両方のタイミング指標は同じ計測に由来し、別の問いに答えます。バッチの各行はバッチが返るときに返るので、その latency は呼び出し全体で、cost_per_decision はその 1/N です。したがってバッチ処理は、変わらない意思決定の集合に対して latency_* を上げ、cost_per_decision_* を下げます。--max latency_p50_ms=... はリクエストが速く提供されたかを問うのであり、実行が安かったかを問うのではありません。--batch-size がなければ両者は一致します。
compare は許容差が名指ししない限り *_ms 指標を無視するので、タイミングのノイズでベースラインが落ちることはありません。ハーネスが実際に行ったこと —— 要求されたバッチサイズ、解決された runner の形、何行が 1 回の呼び出しを共有したか、最大のチャンク —— はレポートの config.timing に記録されます。フラグだけでは何かがバッチ化されたか分からないからです。これらのカウンタは発行された呼び出しを記録し、返った呼び出しは記録しません。laya-evals run --on-error skip では、呼び出しが例外を投げたチャンクも rows_grouped と max_chunk に数えられ、config.errored のエントリと並びます。既定は --on-error fail で、返ってきた呼び出しだけを指標がカバーするレポートを発行するのではなく、再送出します。2 つの *_ms 指標は返った呼び出しだけを数えるので、失敗した呼び出しが計測していないレイテンシを寄与することはありません。
バッチ内の行のグループ化
--sort-by-length は似た長さの行を同じフォワードパスにグループ化するので、各パスはその中の最長行ではなく短い最大長にパディングします。これは呼び出しの形であって答えではありません。結果は同じ順序で返り、同じように採点されます。だからこそ research/ は 10,000 チケットで、意思決定を変えずに 2.15 倍を報告できます。
並べ替えるには複数のパスが必要なので、--batch-size N が実行のグループ化する行数より小さいときにだけ効きます。config.timing は 2 つの主張を切り分けて保持します。sort_by_length はコマンドラインが言ったことで、sort_by_length_sent は runner に届いたことです。--batch-size のない実行は起こりえないことを要求し、sent: false でそう述べます。predict_batch がこのつまみより前の runner は、長い実行の途中で TypeError を投げるのではなく、並べ替えなしで採点されます。
しきい値における棄権ゲート
--min-confidence T は、コアのオプトインの棄権しきい値(#361)を実行が行うすべての呼び出しに転送するので、Router と ONNXAgent は、ハーネスがそれらを見る前に、answer_confidence が T を下回る答えを low_confidence: True と abstention: "abstained" で印付けします。ゲートは報告の制御であり、採点の制御ではありません。apply_confidence_gate は answer["choice"] / ["noul"] / ["score"] を生の argmax のまま残し、_aggregate はそれらのキーだけを読むので、あらゆる accuracy、較正、カバレッジの数値 —— ece、brier、aurc、selective_accuracy@NN —— は T=0 と T=0.7 で同じです。変わるのはレポートの config.timing.min_confidence と config.timing.min_confidence_sent、そしてハーネスの下流でそのフラグに基づいて行動する呼び出し元です。
受け入れられる範囲は、ここでのコピーではなくコアの laya.confidence.check_min_confidence —— [0.0, 1.0] で、有限、bool ではない —— なので、ゲート自体が拒否する値は、チェックポイントが読み込まれる前に使い方のエラー(終了 2)として失敗します。0.0 は正当な要求です。それは棄権の掃引の対照アームであり、flag_low_confidence が no-op として扱う値なので、それを落とすチェックは、どのアームが実際に走ったかを隠してしまいます。
predict が、または(バッチ実行では)predict_batch がゲートより前の runner は、しきい値なしで実行されるのではなく、名前付きの EvalError で拒否されます。黙って落とすと、report.config["timing"]["min_confidence"] がハーネスが決して適用しなかったしきい値を名指ししてしまいます —— 指標の数値は同じままでも、このハーネスが防ぐために存在する種類の嘘です。config.timing は要求と事実の両方を記録します。min_confidence は要求されたしきい値で、min_confidence_sent はこの実行が行ったいずれかの呼び出しが実際にそれを運んだかどうかを述べます。
スライス
compare と run は全体の数値を報告し、--slice language|model|qid|tag に対してはスライス値ごとに同じ指標を報告します。だから 1 つの言語や 1 つの質問での回帰が、集計を読まなくても見えます。model スライスは各行に答えたチェックポイントを保持します。Router 自身のリクエストごとの選択か、ルーティングしない runner ならその runner の model です。
オプトインのスライスゲート
全体のベースラインゲートが合格しても、より小さな言語や質問のスライスが回帰することがあります。レビュー済みの 1 つのスライスを CI の要件にするには、gates.json のような JSON ポリシーを保存します:
{
"version": 1,
"rules": [
{"slice": {"language": "zh"}, "metric": "choice_accuracy",
"min_count": 50, "max_drop": 0.05},
{"slice": {"qid": "intent"}, "metric": "ece",
"min_count": 50, "max": 0.10}
]
}
laya-evals run data.jsonl --baseline baseline.json --tolerance choice_accuracy=0.02 \
--gate-policy gates.json --json report.json
laya-evals compare report.json --baseline baseline.json \
--tolerance choice_accuracy=0.02 --gate-policy gates.json
各ルールは language、model、qid、tag のいずれか 1 つの値を正確に選び、スライスレポートに現れるとおりに指標を名指しします。正の min_count と、ちょうど 1 つの制限を持ちます。min か max は候補の値を検査します。max_drop はベースラインからのその減少を最大限許容します。max_increase はその増加を最大限許容します。後者 2 つは --baseline を必要とします。カウントは選択されたスライスにおけるその指標の採点済みの答えの数で、相対ルールでは両方のレポートで必要です。ece では、有限の信頼度と真偽値の correct 値を持つ答えの数です。スライスや指標の欠落、採点済みの答えの不足、スキップ/エラーになったケースは、オプトインしたゲートを失敗させます。相対ルールはまた、両方のレポートが一致する実行同一性を持つことを要求するので、証拠の欠落が合格として現れることはありません。測定された回帰は、スライス、指標、カウント、値、制限を報告します。不正なポリシー構文はチェックポイントが読み込まれる前に終了 2 になります。品質の失敗は終了 1 になります。ポリシーは run --json レポートの config.gate_policy に記録されます。compare --gate-policy はそのコマンドラインで与えられたポリシーを保存済みの測定に適用します。レポートに記録されたポリシーと異なる場合、compare はそう述べます。新しいポリシーの下での明示的な再チェックは、元の実行がなされたポリシーを変えません。
通常の全体比較は、その許容差と旧式ベースラインの挙動を含めて、依然として適用されます。--gate-policy がなければ、スライスの報告と比較はこれまでどおりに振る舞います。
実行の同一性
run は測定したものをレポートの config ブロックに記録するので、レビュー担当者が読む成果物はそれ自体でレビュー可能です。
| キー | 意味 |
|---|---|
schema |
レポートの形。laya-evals-report/1。読み取れないものを消費者が拒否できるようにしています |
dataset |
入力されたとおりのパス —— ハッシュではなく名前 |
dataset_sha256 |
解析されたデータセットのバイト列の sha256 |
questions_sha256 |
質問スキーマの指紋。データセット全体にわたる各質問の id、type、instructions、criteria |
laya_version |
数値を計算した laya |
coverage_metric_definition |
aurc / selective_accuracy@* のどの定義がこのレポートを生成したか(カバレッジのカットと同値を参照)。どちらかに対する相対ゲートルールは、同じ意味を持たない数値を差し引くのではなく、異なる定義の下で記録されたベースラインを拒否します |
gate_policy |
run --gate-policy が適用した任意のスライスゲートポリシー |
thresholds |
この実行が適用したゲート。min、max、baseline_tolerance |
revisions |
答えた各チェックポイントがどのコミットから読み込まれたか(下記を参照) |
dataset はパスであり、パスは同一性ではありません。データセットはその場で編集され、移動され、同じ名前で再取得されうるし、CI のキャッシュは 2 つの実行に同じファイル名と異なるバイト列を渡しえます。questions_sha256 は行数ではなく何を尋ねたかを対象にするので、変わらない質問セットに state を追加しても指紋はそのままです。dataset_sha256 はそれでも動きます。行の追加はデータの変更であり、質問の変更ではないからです。
instructions も対象に含みます。指示テキストがプロンプトだからです。build_sequence は "<type> question: <instructions>" をトークン化されたヘッドにレンダリングし、Agent はそれのない質問を拒否し(「モデルが答えるべきテキストを追加してください」)、Laya 自身の質問の同一性もすでにそれを数えています。Router._question_schema とこのハーネスのバッチグループ化はどちらも questions dict 全体をキーにし、tests/test_router_batch.py は instructions を言い換えるだけで行が別のバッチグループに移ることを固定しています。では言い換えた指示は依然としてベースラインと等しく比較されるのでしょうか。いいえ —— そしてそこが要点です。「返金が正当かどうかを判断せよ」と「保守的に、明示的な返金要求のみを承認せよ」は別の質問であり、指標ゲートはその差がたまたま名指しした許容差より大きく数値を動かしたときにしか気づけません。choice の選択肢に名前を付けるのも同じ論法です。criteria は意思決定空間であり、research/eval/metamorphic.py のメタモルフィック検査が存在するのは、ラベルの改名が答えを反転させるからです。
指示テキストについて正規化されるものは、エンジン自身が適用する 1 つのステップを除いて何もありません。文字列でない instructions は json.dumps(ins, ensure_ascii=False) としてハッシュされ、Agent._to_internal と一致します。したがって空白も言い回しも数えられ、人間が校正とみなす言い換えも新しい実験として扱われます。これが正直な既定です —— 代替案は、実行とそのベースラインの間に類似度ヒューリスティックを置くことで、常用される評価システムにそんなものはありません。
時間を含むものは何も記録されないので、固定した runner に対してレポートは依然としてバイト単位で再現可能です。
REPORT_SCHEMA、questions_fingerprint(dataset)、file_fingerprint(path) は公開されているので、laya.evals.evaluate を直接駆動する呼び出し元も CLI 実行と同じ同一性を得ます。
ベースラインと CI ゲート
- データセット、ベースラインレポート(レビュー済みの
--json出力)、許容差を一緒に、コミットして保つと、変更がレビュー可能な差分になります。--tolerance METRIC=VALUEはその指標に許される最大の絶対ドリフトです。 laya-evals run ... --baseline baseline.json --tolerance ...はドリフトで非ゼロ終了するので、そのまま CI に組み込めます。laya.evals.EvalReport.compareとassert_regressionはテスト向けに同じロジックを公開します。
指標ゲートは「数値が動いたか」に答えます。「同じ数値だったか」には答えられません。compare は overall だけを読み、overall しか読まないからです。そのため、あるデータセットに対して記録されたベースラインは、別のデータセットで採点された候補を、算術が同一のまま通してしまいます。EvalReport.comparable_to がそれを埋めます。schema、dataset_sha256、questions_sha256 を比較し、run --baseline と compare はすべての差分を表示したうえで、キーと両方の値を名指しして非ゼロ終了で失敗します。
FAIL: baseline is not comparable: dataset_sha256 (dataset bytes): baseline is <sha>, this run is <sha>
どちらかの側に欠けているキーは競合ではなく不明なので、同一性が存在する前に書かれたすべてのレポートはこれまでとまったく同じように比較され続けます。これには下のスケジュール済みゲートのベースラインも含まれ、それは research/eval/ から来ており config.schema をまったく持ちません。
この仕組みを使う CI の面は 2 つあります。
.github/workflows/ci.ymlの重み不要のジョブはtests/test_evals.pyとtests/test_evals_api.pyを実行するので、指標の計算・データセットの解析・CLI が、チェックポイントをダウンロードせずにすべての PR でカバーされます。.github/workflows/evals.ymlは週次で、リリース前とオンデマンドに実行されます。MASSIVE 英語スイートで英語チェックポイントを評価し、research/evals/thresholds.jsonの許容差でresearch/results/eval_english_51_languages.jsonと比較します。レポートを成果物としてアップロードし、PR はブロックしません。
ハーネスは固定したチェックポイントリビジョンに対して決定的なので、レポートは再現可能です。run はデータセット・モデル・デバイスに加えて、実行のタイミングの事実をレポートの config ブロックに記録し、revisions には答えた各チェックポイントが実際に読み込まれたコミットを記録します。--revision <SHA> は実行が読み込むすべてのチェックポイントについてそのコミットを固定し、--revision english=<SHA> は 1 つのチェックポイントを固定します(繰り返し可)。自動ルーティングの実行が望むのはこの形です。3 つのチェックポイントは 3 つのリポジトリで、1 つのコミットがそのすべてに存在することはできないからです。固定しなければ、実行はチェックポイントの既定ブランチを取り、レポートはどのコミットが答えたかを依然として示すので、ベースラインのドリフトを重みのせいにもコードのせいにもできます。laya/revisions.py はオプトインしたい呼び出し元向けに、レビュー済みのコミット SHA を PINNED_REVISIONS で公開しています。--onnx では、素の --revision <SHA> だけが config と tokenizer のダウンロードに適用されます。
実際のラベル付きセットを追加する
research/evals/ に JSONL を、その隣にレビュー済みのベースラインを置き、ワークフロー(または research/evals/check_regression.py)を両方に向けてください。形式は fixture と同じで、ハーネスのどこも MASSIVE を知りません。
証拠の検査
evidence は、ファインチューニング/評価の実行がすでに永続化した成果物を読み —— 決して書き込まず —— 、どの証拠が存在し、何が欠けており、何が不十分かを述べます。モデルの重みを読み込まず、torch を必要としません。
laya-evals evidence --checkpoint ./my-checkpoint [--report report.json]
チェックポイントディレクトリは rl_agent_config.json を含まなければなりません。較正の証拠は、永続化された training.laya_train_calibration ブロックから導かれます。学習メタデータのない旧式のチェックポイントは UNKNOWN、アイテムが 0 件の質問型は MISSING、そのエントリが上流の issues テキストを記録している型(not fitted、MIN_TYPE_N/CALIB_WARN_N 未満、clamp 済み、unchanged fit)は INSUFFICIENT、きれいな当てはめは PRESENT です。ヘルパーは、2 つ目の数値しきい値の出所を保つのではなく、#933 が書いた永続化された issues を信頼します。
評価レポートの同一性フィールド(schema、dataset_sha256、questions_sha256、laya_version)は、run と同じ意味で報告されます。チェックポイントとレポートの関係は、決定的な競合としてだけ主張されます。両方の成果物が同じ dataset_sha256/questions_sha256 を異なる値で示すなら INCOMPARABLE です。それ以外はすべて UNKNOWN です —— laya_version が一致することだけでは一致を証明せず、laya_version が異なることだけでは競合を証明しません。