eval-model

MAX でモデルの精度を評価する

モデルが問題なくサービングできても、ベンチマークの問題に誤答することがあります。このスキルでは、MAX の背後で動作するテキストモデルが、標準的なデータセット（GSM8K、MMLU、HellaSwag、ARC、AIME、GPQA、TruthfulQA、WinoGrande、BABILong）にどれだけ正確に回答できるかを測定します。各実行の前にエンドポイントとの互換性を確認し、サービングの失敗と誤答を分けて扱い、タスクごとの再現可能なスコアを記録するため、モデルカードのスコアと比較できます。

このスキルを使う場面： サービング中のモデルをベンチマークする場合、モデルカードや参照スコアと比較する場合、新たにインポートした MAX モデルが正しく回答できるか確認する場合、または MAX の OpenAI 互換エンドポイントに対してデータセット評価を繰り返し実行する場合です。

このスキルを使わない場面： モデルがまだサービングされていない場合です。まずモデルを起動してください（import-model）。サービングできているのに誤った出力が生成される場合は、ベンチマークの前に debug-model を使って差異の原因を調べてください。

参考資料

ファイル	読むタイミング
references/examples.md	リモートエンドポイント、アーティファクトのパス、長いコンテキストなど、コマンドのバリエーションを確認したい場合
references/fast-fail-thresholds.md	シードの下限値を変更する前、またはシードタスクを追加する前
references/heartbeat-protocol.md	進行状況ストリームを利用するプログラムを構築する場合

すべての資料を最初から読むのではなく、実施する作業に関する資料を読んでください。

評価環境をセットアップする

この SKILL.md を含むディレクトリの絶対パスを解決し、SKILL_DIR として保存します。以下のすべてのコマンドで必要になるため、ユーザーの作業ディレクトリや、下記の仮のパスではなく、スキルの実際の場所から設定してください。スキルのパスが提示されている場合は、そのパスを直接エクスポートしてください。そうでない場合は、このファイルのパスから解決してください。

export SKILL_DIR="$(cd "$(dirname /path/to/eval-model/SKILL.md)" && pwd)"

続行する前に、マニフェストを指していることを確認してください。これにより、誤った値が途中ではなくこの段階で検出されます。

test -f "$SKILL_DIR/pixi.toml" && echo "SKILL_DIR ok: $SKILL_DIR"

Pixi マニフェストから評価環境をインストールします。

pixi install --manifest-path "$SKILL_DIR/pixi.toml"

この環境には、評価用の依存関係（lm-eval、datasets、transformers）が含まれます。

一部のデータセットでは、インターネット接続、Hugging Face 認証、またはライセンスへの同意が必要です。データセットで必要な場合は、実行前に HF_TOKEN を設定してください。

モデルをサービングする

タスクは、モデルのサービング方法が異なる2つのグループに分かれています。実行するグループを選ぶか、両方を実行できるようにサービングしてください。

• 生成タスク（gsm8k、aime）では、生成された回答を採点し、通常どおりサービングされたモデルに対して実行します。
• 多肢選択タスク（mmlu、hellaswag、arc_easy、arc_challenge、winogrande、truthfulqa、gpqa）では、プロンプトの対数確率で採点します。MAX がこれを返すのは、サーバーの起動時に --enable-echo を指定した場合のみです。

MAX がインストールされた環境からサービングしてください。

生成タスクでは、モデルを通常どおり起動します。

max serve --model meta-llama/Llama-3.1-8B-Instruct

多肢選択タスクでは、--enable-echo を追加します。

max serve \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --enable-echo

稼働中のサーバーで echo を有効・無効に切り替えることはできません。--enable-echo を指定せずに起動したサーバーがすでに動いている場合は、多肢選択タスクの評価前に停止して再起動してください。稼働中のプロセスにこの機能を追加する方法はありません。評価の事前チェックが最終的な判定となり、データセットをダウンロードする前にプロンプトの対数確率を検証します。利用できない場合は設定エラーを報告します。

モデルの generation_config.json で、デフォルト以外の repetition_penalty が設定されている場合（たとえば Qwen2.5 ファミリーでは 1.05 が設定されています）、MAX はペナルティサンプリングの経路を自動的に有効にします。この経路は echo と形状に互換性がないため、起動時に repetition_penalty のテンソル形状エラーが発生し、サービングワーカーがクラッシュします。repetition_penalty が設定されていないモデル（Llama-3.1 や Qwen3 など）では、この経路は有効になりません。クラッシュが発生した場合は、repetition_penalty が未設定の生成設定を持つモデルを評価するか、生成タスク（gsm8k、aime）のみに限定して実行してください。

評価を実行する

作業ディレクトリを問わず、Pixi マニフェストを通じて評価ツールを呼び出します。

pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval \
  --model "meta-llama/Llama-3.1-8B-Instruct" \
  --tasks gsm8k

エンドポイントとスコアリングを手早く確認するには、両方の上限を下げ、同梱のスコアラーを使用します。

pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval \
  --model "meta-llama/Llama-3.1-8B-Instruct" \
  --tasks gsm8k \
  --seed-limit 4 \
  --full-limit 8 \
  --direct-http

--direct-http は、この例のような接続と解析の確認にのみ使用してください。同梱のスコアラーはカスタムプロンプトを使う 0-shot 方式のため、モデルカードに記載されている few-shot の chain-of-thought スコアを大きく下回る数値になります。ある測定では、同じモデルのスコアは direct seed スコアラーで 33％、lm-eval のフルパスで 82％でした。--direct-http の結果を公開ベンチマークと比較しないでください。モデルカードと比較する場合は、このフラグを外してデフォルトの lm-eval パスを実行してください。

エイリアスが設定されたサービングモデルで多肢選択タスクを実行する場合は、--tokenizer に Hugging Face のトークナイザー ID を渡してください。これは必須です。lm-eval がトークン境界を計算するには実際のトークナイザーが必要であり、指定しないとトークナイザーのデフォルト値が --model になります。その結果、lm-eval はエイリアスを Hugging Face リポジトリとして読み込もうとして失敗します。

pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval \
  --model "my-served-alias" \
  --tokenizer "meta-llama/Llama-3.1-8B-Instruct" \
  --tasks mmlu,hellaswag

--model の値は、/v1/models が返す ID と一致している必要があります。

--apply-chat-template は、各プロンプトをモデルのチャットテンプレートでラップします。使用するかどうかは、モデルが指示調整済みかどうかだけでなく、比較対象のベースラインによって決まります。

• 公開されている多肢選択リーダーボードのスコア（MMLU、HellaSwag、ARC、WinoGrande）を再現するには、オフのままにしてください。これらの参照スコアは、生の補完プロンプトで測定されています。追加しても実行は成功しますが、モデルカードと比較できない数値になります。
• モデルが実際にチャットで使われる方法で測定し、チャットテンプレートを使ったベースラインと比較する場合にのみ使用してください。

結果を解釈する

コマンドは次の終了コードを使用します。

• 0：すべてのタスクが完了したか、明示的に指定した --target をすべて達成しました。
• 1：セットアップ、依存関係、エンドポイント、データセット、または lm-eval で失敗しました。
• 2：明示的に指定した --target のうち、少なくとも 1 つを達成できませんでした。
• 3：直接実行する seed タスクのスコアが、早期失敗の下限を下回りました。

--target を指定しない場合、有効なフル実行のステータスは completed です。評価ツールは、モデルに依存しない精度目標を設定しません。ステータスが completed または met であれば、実行が正常に完了したことを意味しますが、それだけでモデルが正しい、または同等の性能であると判定されるわけではありません。実行を合格／不合格の判定や比較に使うには、ベースラインを自分で指定してください。

モデルカードと比較する

評価ツールは各モデルの期待スコアを把握していないため、実際に比較するには、いくつかの手順が必要です。

1. モデルカードまたはリファレンスで、ツールが生成するバリアントに一致する特定の指標を確認します。生成タスクの場合は few-shot chain-of-thought です（たとえば、Llama-3.1-8B-Instruct の GSM8K は 8-shot CoT で約 84.5 と報告されています）。ショット数とチャットテンプレートを使用したかどうかを確認してください。
2. その数値を --target として渡します。--target は片側の下限です。精度がその値を下回った場合にのみ実行が失敗（終了コード 2）するため、両側の差を測定するのではなく、下限として機能します。
3. タスクのサマリー JSON から accuracy を読み取り、参照値との差を実際に報告します。サンプリングによるばらつきを考慮してください。デフォルトのフル実行では、各タスク（グループ化されたタスクの場合は各サブタスク）につき 200 サンプルを使用し、テストセット全体は使用しないため、小さな差は性能の低下ではなくノイズとして扱ってください。より精度の高い推定が必要な場合は、--full-limit をデータセット全体に近づけてください。

pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval \
  --model "meta-llama/Llama-3.1-8B-Instruct" \
  --tasks gsm8k,mmlu \
  --target "gsm8k:0.84,mmlu:0.68"

サマリーはデフォルトで eval-results/<model-name>/ に保存されます。

eval-results/meta-llama_Llama-3.1-8B-Instruct/
├── eval_summary.json
├── gsm8k_summary.json
└── mmlu_summary.json

--output-dir を使うと別の場所を選択でき、--run-id を使うとデフォルトのディレクトリ名のみを変更できます。統合サマリーには、実行を解釈するために必要な有効な CLI 設定と評価ツールの依存関係のバージョンが記録されます。

タスクを選択する

各タスクの動作は次のとおりです。

• gsm8k と aime：直接 HTTP によるシードチェックを行った後、lm-eval のフル実行を行います。 フル実行にバンドルされた完全一致スコアラーを使用するには、--direct-http を追加します。
• mmlu、hellaswag、arc_easy、arc_challenge、winogrande、 truthfulqa：/v1/completions 経由で lm-eval のフル実行を行います。--enable-echo が必要です。
• gpqa：/v1/completions 経由で lm-eval の多肢選択式の実行を行います。--enable-echo が必要で、データセットへのアクセスに Hugging Face が必要な場合があります。
• babilong：lm-eval のチャット実行を行います。メタデータはデフォルトで {"max_seq_lengths": "16k"} です。

各フル実行のサンプル数はデフォルトで 200 です（mmlu などのグループ化されたタスクではサブタスクごとに 200、gpqa と babilong ではデフォルトで 100）。これはスポットチェックであり、テストセット全体ではありません。より精度の高い推定が必要な場合は --full-limit を増やしてください。また、デフォルトのサンプル数では実行ごとに小さなばらつきが生じることがあります。グループ化されたタスクでは、サマリーに有効な子サンプルの合計数が表示されます。

直接シードパスを実行するのは生成タスク（gsm8k、aime）のみです。多肢選択式タスクはシードチェックを行わず、そのままフル実行に進むため、mmlu などでシード精度が表示されないのは想定どおりです。シードの早期失敗しきい値は、接続確認のためのゲートです。使用できないエンドポイント、不正なリクエスト、回答抽出の不具合を検出するもので、モデルの品質に通常生じるばらつきを判定するものではありません。品質を判断するには、早期失敗しきい値ではなく、--target を使用してください（「モデルカードとの比較」を参照）。

標準の lm-eval における ChartQA のプロンプト形式は MAX の画像トークン挿入と互換性がないため、ChartQA は登録されていません。有効化する前に、検証済みの MAX 固有タスク設定を追加してください。

MAX をインストールしたりサーバーを起動したりせずに、有効なタスク設定を表示します。

pixi run --manifest-path "$SKILL_DIR/pixi.toml" validate

推論モデルを評価する

reasoning_effort を受け付けるチャットテンプレートを使用する MAX モデルでは、low、medium、high、xhigh のいずれかを指定します。

pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval \
  --model "<MODEL_ID>" \
  --tasks gsm8k,aime \
  --reasoning-effort low

評価ツールはこの値を chat_template_kwargs={"reasoning_effort": ...} 経由で送信し、サポート対象の生成タスクでは直接 HTTP のフルスコアラーを自動的に選択します。エンドポイントがこのフィールドを受け付けない場合、事前チェックで明確なエラーが発生します。

進行状況を監視する

ハートビートの記録は標準出力に、人間が読めるログは標準エラー出力に書き込まれます。アーカイブするには、それぞれのストリームを個別のファイルに保存します。

pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval \
  --model "<MODEL_ID>" \
  --tasks gsm8k \
  > heartbeats.jsonl \
  2> eval.log

実行中に稼働状況を監視するには、標準出力を通常のファイルではなくパイプにつないでください。そうすれば、受信側でハートビートを到着と同時に読み取れます。ハートビートのリファレンスにある受信側の例では、ファイルへのリダイレクトだけではファイルを追跡できません。

pixi run --manifest-path "$SKILL_DIR/pixi.toml" eval \
  --model "<MODEL_ID>" --tasks gsm8k \
  2> eval.log | tee heartbeats.jsonl | python your_consumer.py

--heartbeat-interval の 2 倍の時間、ハートビートが届かない場合は、停止の可能性があるとみなしてください。推論モデルでは、1 回の生成にデフォルトの 30 秒間隔を超える時間がかかることがあります。そのため、処理が遅くても正常に実行されている場合に誤報が発生しないよう、--heartbeat-interval を増やしてください（停止とみなすしきい値も同時に引き上げられます）。評価ツールは、対応するタスクサマリーを書き込んだ後にのみ done を出力します。

失敗のトラブルシューティング

以下を確認してください。

• 接続またはモデルのエラー：curl http://localhost:8000/v1/models を実行し、返されたモデル ID を正確に指定します。
• プロンプトの logprobs が見つからない：MAX を --enable-echo を付けて再起動します（実行中のサーバーでは有効にできません）。選択したランタイムが対数確率に対応していることを確認してください。
• echo を有効にして起動すると、repetition_penalty のテンソル形状エラーでサービングワーカーがクラッシュする：サービング対象のモデルの generation_config.json で、デフォルト以外の repetition_penalty が設定されています（Qwen2.5 でよく見られます）。そのため、MAX は echo に対応していないペナルティ処理を自動的に有効にします。多肢選択式タスクには、モデルの生成設定で repetition_penalty が未設定のもの（Llama-3.1、Qwen3）を使うか、実行対象を生成タスク（gsm8k、aime）に限定してください。
• max serve で No module named 'pydantic' が表示される：サービング環境には軽量版の max パッケージのみがあり、max-pipelines がありません。max-pipelines をインストールしてください。
• パッケージが見つからない：もう一度 pixi install --manifest-path "$SKILL_DIR/pixi.toml" を実行します。
• データセットへのアクセスエラー：Hugging Face に認証し、データセットの利用規約に同意してください。
• lm-eval のタスクエラー：インストール済みの lm-eval バージョンでタスクを一覧表示するには、pixi run --manifest-path "$SKILL_DIR/pixi.toml" lm-eval ls tasks を実行します。次に、 pixi run --manifest-path "$SKILL_DIR/pixi.toml" validate を実行して、有効なタスク設定を表示します（validate タスクはスクリプトの --validate-thresholds モードを実行します）。
• メモリ不足またはコンテキスト長のエラー：必要に応じて、--num-concurrent、--full-limit、またはモデルのサービング時のコンテキスト長を減らします。