nemo-evaluator-plugin

Evaluator Plugin

プラグインの CLI エントリポイントは uv run nemo evaluator です。

目的

このスキルを使用して、評価インターフェースとメトリクスを選択し、最小限の例を検証して、NeMo Platform の評価ジョブを送信し、結果を取得します。

入力

評価を構築する前に、次の入力を確定します。

• 評価インターフェース：データセット駆動型評価とタスク駆動型エージェント評価
• 実行インターフェース：スタンドアロン SDK による評価、または永続的な NeMo Platform ジョブ。
• 合格／不合格のデータセット例：代表的な最小限の合格ケースと失敗ケース。
• メトリクス：採点する動作と、それらが使用するテンプレートフィールド。
• 対象：オフライン採点では対象なし、または出力を生成するモデル、エージェント、ランナー、事前計算済み試行。

手順

1. 入力がデータセット駆動型の行か、 タスク駆動型のエージェント作業かを明確にします。
2. 要求された動作を測定できる最もシンプルなメトリクスを選択します。可能な場合は、決定論的なメトリクスを優先します。
3. 期待される合格ケースを1つ、失敗ケースを1つ含む小さなスモークケースを作成します。
4. スタンドアロン SDK でメトリクスの動作を検証し、行レベルの出力と集計結果を確認します。
5. フィールドのマッピング、プロンプト、パーサー、タスク定義を、規模を拡大する前に修正します。
6. 入力と採点の形式が機能することを確認してから、プラットフォームジョブを送信します。

ルーブリック、RAG ワークフロー、またはツール呼び出しの評価に使うメトリクスを選択する前に、メトリクスの選択をお読みください。

実行インターフェースを選択する

必要なこと	インターフェース
NeMo Platform を使わずにメトリクスをすばやく反復する	nemo_evaluator_sdk.Evaluator
データセット駆動型のプラットフォームジョブ	client.evaluator.submit(...) または nemo evaluator evaluate submit
1つのジョブで複数のインライン／保存済みメトリクス参照を使用する	EvaluateInputSpec を指定した nemo evaluator evaluate submit
タスク駆動型のプラットフォームジョブ	nemo evaluator agent-evaluate submit
再利用可能なプラットフォーム定義と結果インデックス	client.evaluator.metrics、.tasks、.tasksets、.eval_results、.agent_eval_results

すべてのプラグイン評価では、デフォルトで submit を使用します。プラグインのローカル実行パスである client.evaluator.run() と nemo evaluator ... run CLI 動詞は廃止予定です。--help に表示されていても、これらを基盤として構築しないでください。プラットフォームを使わずにメトリクスをすばやく反復するには、スタンドアロンの nemo_evaluator_sdk.Evaluator を使用します。

• データセット、対象、設定、フィールドマッピング、ジョブのライフサイクル、カスタムメトリクスのパッケージ化については、SDK による実行をお読みください。
• 永続化された定義と結果クエリについては、保存済みリソースをお読みください。

制限事項

• api_key_secret は、スタンドアロンでは環境変数名ですが、submit では NeMo Platform のシークレット名です。API 認証をご覧ください。
• 送信時の HTTP 409 は、重複ジョブではなく、参照先のプラットフォームシークレットが存在しないことを意味する場合がよくあります。レスポンス本文を確認してください。
• intent は採点者のメタデータであり、エージェントには表示されません。エージェントに渡されるのは inputs のみです。
• メトリクステンプレートでは、データセットの行に item.* を使用しますが、エージェント評価では reference.*、sample.*、inputs.* を使用します。
• プラットフォームジョブが終端状態になる前に、メトリクスの進捗が100％に達することがあります。結果の取得やアーティファクトのダウンロードの前に、必ず job.wait_until_done() を呼び出してください。

CLI インターフェース

前提条件

このファイル内のすべてのコマンドは、シェルの作業ディレクトリが NVIDIA-NeMo/nemo-platform リポジトリのルートであることを前提とします。

NeMo Platform リポジトリのチェックアウト内では、ワークスペース経由でコマンドを実行します。

# confirms plugin readiness and lists the registered evaluator jobs.
uv run nemo evaluator info
# lists available metric names; add a metric name to print its schema.
uv run nemo evaluator metric-types
# next two commands print the dataset-driven and task-driven job input and
# output schemas - can be very large, use with caution to avoid filling up the context window.
uv run nemo evaluator evaluate explain
uv run nemo evaluator agent-evaluate explain

スキルとプラグインがインストールされている場合は、リポジトリのルートを前提としたり、手動で .venv を有効化したりせずに、インストール済みの nemo コマンドを使用します。

同梱アセットは、このスキルのディレクトリを基準に解決してください。このリポジトリでは、正規のパスは skills/nemo-evaluator-plugin です。インストール済みのスキルは、別の skills ルートに置かれている場合があります。

同梱アセット

パス	用途
assets/specs/exact_match_metric.json	2 行のオフラインスモーク仕様。そのまま送信できます
assets/specs/llm_as_judge.json	オンライン生成 + ジャッジ。ローカル優先（NVIDIA_API_KEY）
assets/specs/fabric_agent_eval.json	タスク駆動型の Fabric ランナー仕様
assets/examples/plugin_sdk_examples.py	各プラグインサーフェス向けのコピー可能な SDK スニペット

利用可能なスクリプト

スクリプト	目的	引数
scripts/generate_example_specs.py	同梱仕様の生成またはドリフトチェック	--check、--write

このリポジトリでは、NeMo は表示されているワークスペースコマンドを使用します:

uv run --frozen python skills/nemo-evaluator-plugin/scripts/generate_example_specs.py --check

クライアント固有の run_script() ヘルパーを前提にしないでください。表示されている uv run コマンドを使用してください。

例

データセット駆動型評価の例

• 2 行の合否スモークテストとその CLI 送信については、Validate standalone, then submit to the platform に従ってください。
• データセットの列に field_mapping が必要な場合は、Map noncanonical fields に従ってください。
• 送信、終端の待機、結果の取得、アーティファクトのダウンロードについては、Getting job results に従ってください。
• 再利用可能な定義については Store a metric, task, and taskset を、結果の検索については Query persisted results を参照してください。

タスク駆動型エージェント評価の例

スタンドアロン SDK 評価

スタンドアロンのタスク駆動型 SDK 評価には AgentEvaluator().run(...) を使用します。その target には Model、GenericAgent、または直接 AgentTaskRunner を指定できます。

プラットフォームジョブ評価

プラットフォームのタスク評価には、プラグインの agent-evaluate submit ジョブを使用します。その ターゲットは ModelTarget、AgentTarget、CodexRunnerTarget、 FabricRunnerTarget、または HarborRunnerTarget です。あるいは、事前に計算された trials を指定します。target または trials のいずれか一方を必ず指定してください。

送信では、インラインタスクまたは保存済みの TasksetRef を受け付けます。保存済みタスクセットは ターゲットワークスペースで解決されます。

インラインタスク、TasksetRef、並行処理、フェイルファストの動作、結果アーティファクト、ランナー 設定については、Agent Evaluation をお読みください。

リポジトリのチェックアウトで Fabric を準備する

Fabric ランナーの例とテストには、オプションのハーネスアダプターと、対応する Relay ゲートウェイが必要です:

uv sync --frozen --package nemo-evaluator-sdk --extra fabric --inexact
script/dev-install-fabric.sh

インストールスクリプトは、ロックされた Python バインディングと一致するチェックサム検証済みの nemo-relay バイナリをダウンロードします。報告されたディレクトリを PATH に追加し、Fabric の チェックには uv run --frozen --no-sync ... を使用して、uv がオプションのアダプターを削除しない ようにしてください。

出力形式

完了したプラットフォーム評価は、この形式で報告してください:

Job: <job-name>
Status: <terminal-status>
Metrics: <metric-names>
Mean: <aggregate-mean>
Artifacts: <downloaded result or artifact location>
Errors: <error messages>

専門的なリファレンスを読む

• モデル、エージェント、リモートメトリック、または永続的な送信を使用する前に、Evaluator API Auth をお読みください。
• ジャッジのスコア、プロンプト、またはパーサーを書く前に、LLM Judge をお読みください。

トラブルシューティング

スキーマ、認証、ジョブ、結果、またはランナーの動作が失敗した場合は、Evaluator troubleshooting をお読みください。

セキュリティのベストプラクティスに従う

シークレットの値を印刷、シリアライズ、またはコミットしないでください。仕様と例には、環境変数 名またはプラットフォームのシークレット参照のみを保存してください。