ae-evaluation

ae-evaluation

既存の操作には ae-cli evaluation +<command> [options] を使用し、新しい機能には以下のリソースコマンドを使用します。全121個のコマンドが Agent Evaluation プラットフォームを対象としています。 AE Agent のリソース管理は ae-agent が担当します。このスキルは、評価アセットとテスト対象エージェントを管理します。

関連するリファレンスのみを読む

コマンドを実行する前に、その操作のリファレンスを読んでください。すべてのリファレンスを読み込まないでください。 リファレンスには、コマンドの入力、JSON コントラクト、タスク固有のワークフローが記載されています。追加フラグについては、コマンドの --help を使用してください。

タスク	リファレンス
データセットの作成／インポート、フィールドとケースの管理、バージョンの公開	datasets.md
LLM ジャッジ／テンプレートの設定、評価器バージョンの公開、プロンプトの調整または最適化	evaluators.md
実行の作成／設定／開始／再試行／キャンセル、結果／トレースの確認、結果のエクスポート	runs.md
モデルとエージェントの設定／テスト、認証情報の管理	connections.md
リソースの公開範囲の変更、またはプロジェクトメンバーの管理	access-and-members.md
インポート／エクスポートしたファイルのディスクへのダウンロード	files.md
定期評価スケジュールの作成／更新／削除	schedules.md
AI Monitor データの接続／インポート、TE レポートの設定、TE Claude カタログの検索	integrations.md

エンドポイントと認証

• 個人のターミナルと AE サンドボックスのどちらでも、評価コマンドは現在の AE Host をデフォルトで使用し、<current-host>/agenteval/api/v1/... を呼び出します（ホスト末尾の任意の /agent は削除されます）。別の AE Host を選択するには --host を使用してください。評価リクエストでは、その AE Host に設定された HTTP または HTTPS スキームが使用され、他の AE コマンドと同じ動作になります。従来の --endpoint と AE_EVAL_BASE_URL の値は、現在の AE Host と一致する場合に限り使用できます。それ以外の値は、認証情報が送信される前にエラーになります。これらの設定を削除し、ホストの選択には --host を使用してください。
• セッション交換と評価リクエストではリダイレクトが拒否されます。セッション交換のタイムアウトは30秒です。
• パス内のリソース ID に使用できるのは、英字、数字、ハイフン、アンダースコアのみです。区切り文字と URL エスケープ構文はローカルで拒否されます。
• オンラインプラットフォームを使用してください。localhost／ループバックエンドポイントを提案したり、ローカルの agent-test/.env からトークンを取得したりしないでください。
• 認証では、AE_EVAL_ACCESS_TOKEN が明示的に設定されている場合にそれを使用します。この値は Authorization: Bearer としてのみ送信され、コマンド引数や出力に決して表示してはなりません。
• AE サンドボックスで AE_EVAL_ACCESS_TOKEN が未設定の場合、ae-cli は te-claude を介してサンドボックスにプロビジョニングされた cli-token を自動的に交換し、有効期間の短い評価セッションを取得します。CLI トークンが Agent Evaluation に送信されることはありません。そのトークンが複数の TE プロジェクトにアクセスできる場合は、認証された TE プロジェクト ID を AE_EVAL_TE_PROJECT_ID に設定してください。
• サンドボックス外でトークンが未設定の場合、CLI はただちに EVAL_ACCESS_TOKEN_MISSING を返し、token_missing のオンボーディング案内を表示します。このとき、ネットワークリクエストは送信されません。モジュールの利用可否とサービスの正常性も確認されません。ユーザーには、プラットフォームのウェブコンソール（sessionStorage.getItem('agent.evaluation.session-token')）または POST /agenteval/api/v1/auth/session を通じてセッショントークンを取得するよう案内してください。チャットでトークンを求めてはいけません。
• コマンドはデフォルトで JSON を返します。障害の診断には、実際のエラーエンベロープを使用してください。

評価の利用可否とオンボーディング

AI Evaluation Center はオプションのデプロイモジュールです。CLI コマンド／スキルが利用可能であっても、サーバーモジュールがインストール済みであることや、ユーザーにアクセス権があることを示すものではありません。

• エラーに error.details.onboarding が含まれている場合は、以下のステータス別の範囲に従ってください。失敗した操作をむやみに繰り返したり、フラグを変更したり、トークンを更新したり、拒否を回避するために直接 HTTP 呼び出しを行ったりしないでください。これはホストエージェントへの指示であり、永続的な CLI のサーキットブレーカーではありません。独立したローカル作業は続行できます。
• まずローカルの作業を保護してください。データセットの整理とアップロードを依頼された場合は、可能であればローカルの CSV/JSON を完成させて保存してください。実際のファイルパスを確認してください。書き込みがタイムアウトした場合、応答が失われた場合、またはゲートウェイ／サーバーエラーが返された場合は、書き込み結果を確認できていないことを説明してください。サーバーはすでに受け付けている可能性があります。成功とも失敗とも断定せず、むやみに再送信しないでください。接続が復旧したら、既知のリソース ID／インポート ID があれば、それを使って許可された読み取り専用のステータス確認を行い、結果を照合してください。信頼できる識別子や照会手段がない場合は、別の書き込みを行う前に管理者／サポートに確認を依頼してください。
• onboarding.status を読み取り、ユーザーの言語で根拠を説明し、next_steps に従ってください。
  • module_not_detected：デプロイ／ルーティングが確認されるまで、該当ホストでの以降の評価コマンドを停止してください。API ルートが検出されませんでした（一般的なルート 404 または HTML フォールバック）。オプションモジュールが存在しないか、ルーティングに誤りがある可能性があります。デプロイ／ルーティングを確認し、必要に応じてモジュールをインストールしてアクセス権を付与するよう、ThinkingData のサービス担当者（CSM またはテクニカルサポート）に連絡してください。インストールされていないと断定しないでください。
  • access_not_granted：拒否された操作のみ停止してください。許可された独立した操作は続行できます。たとえば、削除が拒否されても、許可されたデータセットの読み取りは禁止されません。拒否を調べたり回避したりするためだけに、ほかのコマンドを実行しないでください。アクセス範囲が確認された場合に限り、プロジェクトまたはモジュール全体の操作を停止してください。必要な権限（該当する READER／EDITOR／ADMIN）を確認するよう、管理者または ThinkingData サポートに依頼してください。403 だけでは、クラスター全体での拒否もモジュールのインストール状況も証明されません。再インストールやトークンのローテーションを勧めないでください。
  • token_missing：このホストでトークンが設定されるまで、リモート評価操作を停止してください。外部ターミナルにトークンがないため、リクエストは送信されておらず、エンドポイントの可用性も確認されていません。条件に応じた Web コンソールの手順に従ってください。アプリランチャーに該当項目がない場合は、存在しないページへユーザーを案内するのではなく、管理者／サポートに確認を依頼してください。このステータスは、すべての評価サービスの正常性を示すものではありません。
  • availability_unknown：失敗した操作のむやみな再試行を停止してください。ネットワークエラー、タイムアウト、サーバー障害、無効な応答、サンドボックスセッションルートの欠落からは、インストール状況を確認できません。ホスト／ネットワーク／サービス／ルーティングの確認を依頼してください。障害をインストール要件として提示しないでください。接続が復旧した後、許可された読み取り専用のステータス確認で未確認の書き込み結果を照合できますが、再送信してはいけません。
• 3 つの機能がユーザーのタスクにどう関係するかを簡潔に説明してください。データセットでは、CSV/JSON のインポートと AI Monitor のトレースを使って、単一ターン／マルチターンのテストケースやバージョンを管理します。評価器では、テンプレート／カスタム LLM ジャッジ、人によるキャリブレーション、プロンプト最適化を利用できます。評価実行では、実稼働中のエージェントをテストしたり、事前設定済みの出力を採点したり、回帰テストをスケジュールしたり、低スコアのケースやトレースを調べたりできます。この説明は、中国語または英語のユーザーには自然な表現に翻訳してください。CLI のエンベロープは英語のままにしてください。
• ユーザーが機能についてのみ質問している場合は、ネットワーク呼び出しを行わずに説明してください。現在のデータセット／実行結果も求められており、最初の呼び出しでオンボーディングが報告された場合は、上記のステータス別の停止範囲に従ってください。別の機能を実演するためだけに、追加の呼び出しを行わないでください。
• 既存のビジネスエラーコード、エラータイプ（api）、終了コードは変更しないでください。オンボーディングは追加情報です。通常のビジネス上の 404 エラー（DATASET_NOT_FOUND など）は、モジュールの欠落を示すものではありません。古い CLI ではオンボーディング情報が省略される場合があります。診断の根拠は慎重に扱い、単なる 404/5xx からインストール状況を推測しないでください。

ID、バージョン、変更

• list/get コマンドで実際の ID を確認します。UUID はバージョン 7 の文字列です。ID、JSON ペイロードの形式、頻度フィールド、lock_version の値を推測してはいけません。
• 公開済みのデータセット、評価器、評価タスクのバージョンは変更できず、下書きとは別に管理されます。実行とスケジュールにはバージョンが固定され、既存の公開済みバージョンを上書きすることはできません。変更されていないアセットを公開すると、ASSET_VERSION_NO_CHANGES が返されます。
• 入力が確定していれば、読み取り操作は実行できます。書き込みにはユーザーの意思確認が必要です。高リスクの操作では、ユーザーが --yes で確認を省略するよう許可しない限り、確認が維持されます。
• 認証情報の有効化／無効化、実行のキャンセル、削除、所有権の移転、テンプレートの無効化、アクセス範囲の変更、メンバーの参加承認／権限変更は、高リスクの書き込み操作です。リスクとロール要件については、コマンドのヘルプを確認してください。参照資料では、ADMIN 専用の操作が示されています。
• --lock-version が必要な変更を行う前に、毎回、現在のリソースを読み取ります。変更が成功するたびにバージョンが増加するため、次の変更の前に再度読み取ってください。
• 実行、データセット、評価器、モデル、エージェント、認証情報、データセットケース、TE レポート設定、AI Monitor 接続には、それぞれ対応する get コマンドを使用します。スケジュールには +list_schedules を、キャリブレーションケースには +list_calibration_cases を使用します。
• フィールドの変更にはデータセットのバージョンを、ケースの変更にはケースのバージョンを使用します。TE レポート設定または AI Monitor 接続を初めて作成する場合は --lock-version を省略します。更新では、0 を含め、現在の値を指定する必要があります。
• 非同期のデータセットインポート、評価セットのインポート、結果のエクスポートでは、試行ごとに新しい一意の --idempotency-key が必要です。完了するまで、該当するステータスをポーリングしてください。リソースの作成だけでは、準備が完了したことにはなりません。
• 対象が検証されていない大規模な書き込みや破壊的な書き込みの前には、--dry-run を使用してください。リクエストのプレビューが表示され、実際には実行されません。
• 評価エラーでは、送信された認証情報の値とセッショントークンが秘匿化されます。サーバーが返すエラーメッセージとヒントは、CLI ログに保存されません。安定したビジネスエラーコードは変更されずに維持され、機密性のない診断情報は JSON エラーエンベロープで引き続き確認できます。
• 単一ケースと一括のどちらの書き込みでも、ケースデータはコマンドログ上で秘匿化されます。機密性の高い JSON の解析に失敗した場合は、入力を表示せずに、フラグと構文に関するガイダンスが示されます。
• 認証情報のシークレットは書き込み専用です。シークレット、セッションクレーム、機密性の高いトレース証拠を表示してはいけません。秘匿化されたドライラン出力を使用してください。

評価のライフサイクル

1. +list_dataset_versions で、公開済みのデータセットバージョンを選択します。
2. Agent／モデルを呼び出すには LIVE_AGENT（デフォルト）を、データセットに保存されている出力を採点するには PRESET_RESULT を選択します。PRESET_RESULT では、エージェント／モデル設定 ID を省略する必要があります。IMPORTED_OUTPUT はレガシーデータ専用です。推奨してはいけません。
3. 下書きの実行を作成し、少なくとも 1 つの ACTIVE な評価器をバインドします（公開済みのバージョンを固定することを推奨します）。フィールドマッピングを完全に設定し、結果フィルターフィールドも設定します。フィールドを選択しない場合は、結果フィルターを明示的に空にする必要があります。
4. 開始前に +validate_run を実行することを推奨します。これは本文やロックバージョンを必要とせず、開始前のチェックを実行します。最新の実行を読み取ってから、現在のロックバージョンを指定して +start_run を実行します。
5. 概要／分布を確認し、ケースの詳細を調べます。再試行、トレース、エクスポートの仕様については、実行の参照資料を使用します。

実行手順とマッピング例については、runs.md を参照してください。データセット、評価器、接続のセットアップには、上記の対応する参照資料だけが必要です。

トランスポートの移行

既存のプラットフォーム契約では、このリポジトリに登録された評価機能ではなく、REST 操作が公開されています。新しいコマンドでも、型付き入力、権限の確認、ファイル処理には引き続きそのトランスポートを使用します。これらは移行期間中のものです。移行記録については、対応する参照先を確認してください。これらのコマンドを拡張する前に、デプロイ済みの Gateway の対応状況を確認し、既存の同等機能を優先してください。

移行状況：移行期間中 担当モジュール：Agent Evaluation（agent-test） 現在のトランスポート：認証済み REST /agenteval/api/v1 Gateway の移行先：未定（評価機能の登録） 見直し日：2027-01-21 完了条件：同等の評価機能が利用可能になったら、選択した型付き／ファイルコマンドを L2 に移行するか、単純なラッパーを L3 に置き換えます。既存の + コマンドは、互換性またはオーケストレーション上の理由がある場合に限り維持します。

この記録は、既存の evaluator/run 参照におけるロケールおよびプロセス証跡の更新にも適用されます。これは移行計画であり、特定のデプロイ済み Gateway を調査したことを示すものではありません。