Evaluations — 鍛えたモデルの出来を測る

これは何か

第 4 章の Playground で 1 つのプロンプトに 1 つの応答を目で確認するやり方は、モデルの「感触」を掴むには十分だが、「ファインチューン前後でどちらが良いか」「本番に出してよい品質か」を判断する材料にはならない。1 回きりの目視では再現できず、数十〜数千件の入力に対する合否を人手で数えるのも現実的ではないからだ。この章で扱う Evaluations（評価）は、この判断を勘ではなく評価ジョブ（Evaluation Job）という繰り返し実行できる仕組みに置き換える機能である。

評価の中核にあるのは Evaluator（評価器）という Fireworks 上のリソースで、コンソールでは「Evaluations dashboard」という画面から扱う（個別ページの URL は app.fireworks.ai/dashboard/evaluators/<EVALUATOR_ID> の形式）。この画面は「evaluators」と「evaluation jobs」という 2 つのリソースを一覧・フィルタでき、Evaluator の状態列には後述する Active・Building・Failed の 3 状態が表示される。Evaluator の実体は Python プロジェクト一式（requirements.txt と @evaluation_test を含む test_*.py）で、Eval Protocol（EP）という、Fireworks 以外のトレーナー（TRL・rLLM・OpenAI RFT など）からも使えるオープンな枠組みがその書き方を定義している。コンソールにはこの Python ソースを直接編集できるコードエディタもある。

いつ使うのか

Evaluations が向くのは次のような場面である。

• ファインチューン前後の比較 — 第 11 章で作った SFT・DPO・RFT モデルが、ベースモデルより実際に良くなったかを数値で確認する。Evaluation Job にモデルを指定するフィールドは無く、比較対象は Evaluator 側の completion_params に埋め込む。ベースモデルとファインチューン済みモデルを比べるなら、対象モデルごとに Evaluator を用意するか、mode="groupwise" で completion_params を 2 つ渡して 1 つの Evaluator にまとめる（後述）
• 本番投入前の合否判定 — passed_threshold のような明示的な閾値で「合格ラインを超えたか」を機械的に判定する
• RFT の報酬関数の検証 — RFT を始める前に、報酬がちゃんと点差を付けているか（平坦なスコアになっていないか）を小さく確かめる
• CI での継続的な回帰チェック — Eval Protocol は EP_PASSED_THRESHOLD のような環境変数でパラメータを上書きできるため、コードを書き換えずに CI から実行しやすい

紛らわしいのは、第 11 章で扱った「学習済みモデルの評価（Evaluating Trained Models）」ページとの関係である。両者は「評価」という同じ言葉を使うが、役割が違う。あちらは学習直後に preemptible デプロイ（アイドルの予約 GPU を間借りする、評価・バッチ専用の安価なデプロイ）を立てて 1 リクエストだけ手動で疎通確認する、評価対象モデルを動かす実行環境の用意である。この章の Evaluator・Evaluation Job は、その実行環境に対して何をもって合格とするかを自動で採点する仕組みである。実務では preemptible デプロイ（または本番デプロイ）でモデルを動かし、そのエンドポイントを Evaluator の completion_params に指定して Evaluation Job で採点する、という組み合わせで使うこともある。

仕組み（1）— 評価はどこに挟まるか

Evaluations は単独の機能ではなく、学習からデプロイまでの意思決定ループの中に挟まる。第 11 章の学習ジョブが終わったら、第 9 章の本番デプロイを作る前に、まずこの章の評価で「合格」かどうかを確かめる。合格しなければ、学習の設定（データセット・エポック数・手法の選び直しなど）に戻ってやり直すことになる。ここで言う「評価」は Evaluator からモデルを直接呼び出せることが前提だが、ファインチューン済みモデルは Serverless では呼べないため（第 11 章）、先に第 11 章の preemptible デプロイ（評価専用の安価なデプロイ）でエンドポイントを立て、そのモデル名を Evaluator の completion_params に渡す必要がある。本番運用中のモデルを測り直すときは、既存の on-demand デプロイをそのまま指してもよい。

仕組み（2）— Evaluator の中身と作り方

Evaluator は Eval Protocol の @evaluation_test というデコレータで書く。1 行が 1 件の入力（messages と、正解があれば ground_truth）を表す JSONL データセットを読み込み、行ごとに ロールアウト（モデルを実際に呼び出して応答を得ること）を実行し、その応答（トラジェクトリ）を採点関数に渡して 0〜1 のスコアを返す、という一連の流れをひとまとめにしたものである。ロールアウトをどう起こすかは rollout_processor で切り替えられ、たとえば SingleTurnRolloutProcessor は completion_params に指定したモデルを 1 回呼び出す。Fireworks のモデルを呼ぶときは、LiteLLM（複数の LLM プロバイダを同じ書き方で呼び分けられるライブラリ）互換のプロバイダルート表記で fireworks_ai/accounts/fireworks/models/<モデル名> のように書く。

採点の粒度は mode パラメータで 3 通り選べる。既定の pointwise は行を 1 件ずつ独立に採点し、groupwise は同じ入力に対する複数モデル・複数パラメータの結果をまとめて比較する（completion_params を 2 つ以上渡す必要がある）、all はデータセット全体を関数に渡して横断的な分析を行う。合否判定は passed_threshold に成功率（例: 0.8）を渡すだけでもよいし、{"success": 0.8, "standard_error": 0.05} のように標準誤差（スコアのばらつきの目安）の条件を足すこともできる。

書いた Evaluator を Fireworks に登録する主な経路は 2 つある。推奨は ep upload CLI で、テストファイルをスキャンして選択し、アップロードまでを自動でやってくれる。API を直接叩く場合は次の 6 ステップが要る（Create Evaluator API のドキュメントに明記されている手順）。このほかに、後述の ep local-test でローカルテストを実行すると、その時点で Evaluator とデータセットが自動的に Fireworks へ登録される経路もある。

1. Evaluator リソースを作成する（POST .../evaluatorsV2。後で状態を取得する Get Evaluator は V2 サフィックスなしの .../evaluators/{id} で、この非対称は取り違えやすい）
2. ソースディレクトリを .gitignore を尊重しつつ .tar.gz に固める
3. 署名付きアップロード URL を取得する
4. その URL へ .tar.gz を PUT する
5. アップロード検証（バリデーション）をトリガーする
6. Evaluator の状態が ACTIVE になるまでポーリングする

登録後の Evaluator は ACTIVE・BUILDING・BUILD_FAILED のいずれかの状態を持つ。BUILDING は「e2b（Evaluator のコードをサードパーティのサンドボックス基盤で隔離実行する仕組み）のテンプレートをビルド中」という意味で、Evaluation Job にも RFT にもまだ使えない。BUILD_FAILED になったら、専用のビルドログ取得エンドポイントでログを確認できる。

仕組み（3）— Evaluation Job を走らせる

Evaluator が ACTIVE になったら、Evaluation Job（POST .../evaluationJobs）でデータセット全体に対する採点を 1 回のジョブとして走らせられる。必須フィールドは evaluator・inputDataset・outputDataset の 3 つで、いずれも accounts/<アカウント ID>/評価器またはデータセットの種類/<ID> という完全修飾名で指定する。少しつまずきやすいのは outputDataset で、これは「ジョブが作成する出力データセット」の名前でありながら必須フィールドになっている。つまり、まだ存在しないリソースの名前を、作成前に自分で決めて渡す設計になっている。

ジョブの状態（gatewayJobState）は非同期ジョブ全般で使い回される共通の enum で、API はより細かい 20 の状態を返す。ポーリングで判定すべきは終端状態で、JOB_STATE_COMPLETED（成功）・JOB_STATE_FAILED（失敗）・JOB_STATE_CANCELLED（途中停止）のいずれかに達したら処理を止める。そこに至るまでに JOB_STATE_VALIDATING・JOB_STATE_RUNNING・JOB_STATE_WRITING_RESULTS などの中間状態を通るが、遷移の順序は docs で定義されていない。完了すると、レスポンスの metrics（メトリック名 → スコアの map）と outputStats（出力データセットの集計統計）にジョブ全体の結果が入る。

仕組み（4）— 評価と RFT 報酬の二役

Evaluator は Evaluation Job だけでなく、第 11 章で扱った RFT（Reinforcement Fine-Tuning）の報酬関数としても使われる。RFT の仕組みは「SFT が正解ラベル付きの例を渡すのに対し、RFT はプロンプトと Evaluator（0〜1 でスコアを返す報酬関数）を渡す」という 1 点に集約される。ここで使う Evaluator は Evaluation Job で使うものと同じ @evaluation_test の仕組みで、「ロールアウトを 1 つの報酬に変換する」という役割は変わらない。両者の違いは呼ばれる頻度にある。Evaluation Job は固定のデータセットに対して 1 回だけバッチで走るのに対し、RFT では学習が進むたびに繰り返し呼び出され、そのつど新しいロールアウトを採点する。ロールアウトの起こし方（rollout_processor）自体は Evaluator 側の設定で、たとえば自分の本番環境（エージェントサーバーなど）でロールアウトを実行したい場合は RemoteRolloutProcessor を Evaluator に設定して接続する構成も用意されている。

ハンズオン

pip install pytest requests git+https://github.com/eval-protocol/python-sdk.git

{"messages": [{"role": "user", "content": "What is the capital of France?"}], "ground_truth": "Paris"}
{"messages": [{"role": "user", "content": "What is the capital of Japan?"}], "ground_truth": "Tokyo"}

from eval_protocol.pytest import evaluation_test, SingleTurnRolloutProcessor
from eval_protocol.models import EvaluationRow

@evaluation_test(
    input_dataset=["capitals.jsonl"],
    completion_params=[{
        "model": "fireworks_ai/accounts/fireworks/models/gpt-oss-120b",
        "temperature": 0.0,
    }],
    rollout_processor=SingleTurnRolloutProcessor(),
    passed_threshold=0.8,
    mode="pointwise",
)
def test_capital_cities(row: EvaluationRow) -> EvaluationRow:
    expected = row.ground_truth
    answer = row.messages[-1].content or ""
    row.evaluation_result.score = 1.0 if expected.lower() in answer.lower() else 0.0
    return row

git+https://github.com/eval-protocol/python-sdk.git

ep logs

ep local-test --entry test_capital.py::test_capital_cities

ep upload --path . --entry test_capital.py::test_capital_cities --evaluator-id capital-cities-eval --yes

curl "https://api.fireworks.ai/v1/accounts/$ACCOUNT_ID/evaluators/capital-cities-eval" \
  -H "Authorization: Bearer $FIREWORKS_API_KEY"

firectl dataset create capitals-eval-ds capitals.jsonl

curl -X POST "https://api.fireworks.ai/v1/accounts/$ACCOUNT_ID/evaluationJobs" \
  -H "Authorization: Bearer $FIREWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "evaluationJob": {
      "evaluator": "accounts/'"$ACCOUNT_ID"'/evaluators/capital-cities-eval",
      "inputDataset": "accounts/'"$ACCOUNT_ID"'/datasets/capitals-eval-ds",
      "outputDataset": "accounts/'"$ACCOUNT_ID"'/datasets/capitals-eval-out"
    },
    "evaluationJobId": "capitals-eval-job-1"
  }'

curl "https://api.fireworks.ai/v1/accounts/$ACCOUNT_ID/evaluationJobs/capitals-eval-job-1" \
  -H "Authorization: Bearer $FIREWORKS_API_KEY"

firectl dataset delete capitals-eval-ds
firectl dataset delete capitals-eval-out

つまずきポイント

理解度チェック

まとめ

• Evaluator は Eval Protocol の @evaluation_test で書く Python プロジェクトで、テストケース→ロールアウト（推論）→採点という流れを 0〜1 のスコアに変換する
• 登録は ep upload CLI が推奨経路で、状態は ACTIVE・BUILDING・BUILD_FAILED の 3 つを持つ
• Evaluation Job は evaluator・inputDataset・outputDataset を指定してデータセット全体を一括採点し、metrics と出力データセットに結果が残る
• 同じ Evaluator は RFT の報酬関数としても使い回せる。使われ方は Evaluation Job（1 回のバッチ）と RFT（学習ステップごとの反復）で異なる

次章では、API キーの発行・利用量の把握・請求管理・チーム運用といった、アカウントまわりの実務を扱う。

参考リンク

• API Reference: Create Evaluator
• API Reference: Get Evaluator
• API Reference: Create Evaluation Job
• API Reference: Get Evaluation Job
• Evaluating Trained Models
• Reinforcement Fine-Tuning
• Eval Protocol: Introduction
• Eval Protocol: @evaluation_test reference
• Eval Protocol: CLI reference
• Eval Protocol: Specification