# 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件から始める。 ```json {"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日以上走っていなければ「品質の裏付けが古い」と警告する ---