LLM の委譲先を「成功率 × コスト」で決める eval ハーネス

安いモデルへ処理を移す前に、品質が落ちないことを数字で確認するための計測ツールを作る指示書。 Anthropic 公式 cookbook cost_optimization の「まず測る、モデル格下げは最後」という順序をそのまま道具にする。

この指示書の価値は実装コードではなく「測定を歪める3つの罠」にある。 素直に作ると必ず踏み、 その結果「安くて十分なモデルを品質が低いと誤判定して排除する」という、削減とは逆方向の判断を生む。

---

何を作るか

eval-harness CLI（Node/Python どちらでもよい。外部依存なしで書ける）。

eval --provider <名前> [--model X] [--limit N] [--category C]
eval --all          # 候補を横断。キーが無い提供元はスキップ（エラーで止めない）
eval --pareto       # パレート表 + カテゴリ別の推奨

1. ゴールデンタスクセット

1行1タスクの JSONL。カテゴリごとに3件程度、計15件から始める。

{"id":"cls-01","category":"classification","system":"...","prompt":"...","max":256,
 "expect":{"type":"contains","value":"見積依頼"}}

expect.type:

• contains / not_contains / regex … 機械判定（無料）
• regex_all … 複数条件のAND（1本の巨大正規表現より保守しやすい）
• json_path … JSON出力の指定パスが期待値と一致
• judge … LLM採点。採点役は安い高速モデルに固定し「PASS か FAIL だけ返せ」と指示する

カテゴリ例: 分類 / 抽出 / 要約 / 顧客向け文章 / コード生成。 実務で実際に流している処理を写すこと。汎用ベンチマークでは自社の委譲判断に使えない。

2. 記録

1実行1行を集計ファイルへ追記: {t, provider, model, n, graded, pass, fail, errors, truncated, rate, inTok, outTok, costUsd, msAvg, byCategory}

個票も別ファイルに残す（後述の罠3の切り分けに必須）: {id, status, output(先頭2000字), expect, judgeVerdict, finishReason, error, inTok, outTok, ms}

3. パレート表と推奨

• 成功率 / 1タスクあたりコスト / 平均レイテンシ を成功率降順で表示
• 3軸で劣位判定する。他の行が「成功率が同等以上 かつ 安い かつ 速い」時だけ劣位にする （コストだけで判定すると、速度が売りの提供元が不当に切られる）
• カテゴリ別に「最高成功率との差が5ポイント以内で最安/最速」を推奨として出す
• 推奨を出す関数は1つだけにして他の出力先から呼ぶ。2か所で別々に計算すると結論が食い違う（実際に食い違った）

---

測定を歪める3つの罠（本題）

罠1: API エラーを「品質の不合格」に数えてしまう

429 レート制限 404 モデル名違い 503 で応答を得られなかったタスクを不合格に混ぜると、 インフラの問題が品質スコアとして現れる。

実測例（同じ設問セット・同じ日）:

提供元	混ぜた場合	分けた場合	実体
A社	13.3%	100%	無料枠のレート制限
B社	26.7%	91.7%	同上
ローカル	0%	計測対象外	モデル未導入

対策

• 結果を pass / fail / error の3値にする
• 成功率 = pass ÷ (pass + fail)。error は分母に入れない
• 採点可能な件数が0なら「0%」ではなく**「計測不能」**と表示する（0%と計測不能は全く違う）
• 429 と 5xx は指数バックオフで数回リトライし、Retry-After があれば従う。それでも駄目なら error
• 提供元ごとに 並列数 と 最小送信間隔 を設定できるようにする（無料枠は並列3で即死する）
• 対象が「未導入」なら明示的にスキップ扱いにし、0%として記録しない

罠2: 出力の切断を「品質の不合格」に数えてしまう

max_tokens が小さいと、思考トークンを先に吐くモデルは本文が出る前に予算を使い切る。 結果は「本文が空」か「文の途中で切れる」。どちらも採点すれば不合格になるが、品質の問題ではない。

実測例: 出力がちょうど239トークンで打ち切られ、コードが setTimeout(() = で途切れていた。 同じ設問が全提供元で失敗し続けた真因がこれだった。

対策

• 終了理由を読む（OpenAI互換=finish_reason:'length' / Anthropic=stop_reason:'max_tokens' / Gemini=finishReason:'MAX_TOKENS'）
• 切断は第4の状態 truncated にして、pass+fail の分母から外す
• max_tokens は用途相応に上げる（要約・文章生成・コードは 1024 程度から）
• 思考トークンを持つモデルには reasoning_effort 等を明示的に下げる設定を渡せるようにする
• 未知のパラメータで 400 が返ったら、そのパラメータを外して1回だけ再試行する

罠3: 期待値が正解を弾いている

「全モデルが必ず落とす設問」は識別力ゼロで、全員のスコアを一律に下げるだけの装飾になる。

実測例: 再試行関数を書かせる設問で async function を要求する正規表現にしていたため、 Promise を返す非 async の正しい実装が不合格になっていた。

対策

• 全提供元が同じ設問で落ちたら、まず設問を疑う（モデルではなく）
• そのために個票へ モデルの出力 と 採点役の判定理由 を必ず残す。これが無いと 「採点役が壊れている」のか「期待値が厳しすぎる」のかを切り分けられない
• 直すときは緩めすぎない。全員が満点になる設問も識別力ゼロ
• 逆に「全モデルが必ず通る」設問も削る

---

タスクセットの配布で必ず踏む罠（4つ目）

タスクセットを「テンプレートから初期生成し、以後は利用者のファイルを使う」実装にすると、 テンプレートを改善しても、一度でも実行した環境には永久に届かない。 実測では設問15問すべてが初版のまま動き続け、上の罠1〜3の修正が一度も反映されていなかった。

対策: 3方向マージ

1. 「最後に同期したテンプレート」の写しを保存しておく
2. 実行のたびにテンプレートと写しを比較する
3. 利用者のタスクが写しと同一（＝未編集）なら新しいテンプレートで置き換える。 編集済みなら据え置いて警告を1行出す。テンプレートに無い独自タスクは必ず残す
4. 書き換え前にバックアップを取り、置換N件 / 追加N件 / 据え置きN件 を1行報告する（差分が無い時は黙る）

---

完了条件（ここまでやって初めて使える）

• 実際の提供元に本物のAPIで流す。モック・合成データでの確認を完了と呼ばない
• 結果行に graded エラーN件 切断N件 が出る
• 全提供元で落ちる設問が残っていない（残っているなら罠3を切り分けていない）
• --pareto の推奨と、他の出力先（日次レポート等）の推奨が一字一句一致する
• 古い実行結果や成功0件の行が「パレート最適」と表示されない
• 個票に出力・採点理由・終了理由が入っている

---

運用への組み込み

• 計測結果から「このカテゴリはこの提供元に落として安全」を数行で生成し、 エージェントが毎回読む場所（セッション開始時に読ませる指示ファイル等）へ埋め込む
• 併せて プロンプトキャッシュのヒット率 を監視する。実測では 安定した前置きを先頭に置くだけで 43〜52% 安くなる（キャッシュ指定の有無ではなく、 動的な値をどこに置いたかで決まる）。書き込みばかりで読み取りが伸びない状態が最も損
• 計測が14日以上走っていなければ「品質の裏付けが古い」と警告する