genai-hub-prompt-evaluation

ステップ 0 — 最初に認証情報を確認する（必須）

ほかのステップを実行する前に、AI Core の認証情報が設定されていることを確認します。aicore-admin-resources を呼び出し、check_setup.py を実行します。

• 成功した場合は、ワークフローに進みます。
• 失敗した場合（変数が不足している、invalid_client、または認証情報が正しくない場合）は、停止してユーザーに依頼し、以下の環境変数に記載されている変数をエクスポートしてもらいます。処理を続けたり、ほかの場所（ノートブック、ほかのリポジトリ、ワークスペースファイル）で認証情報やワークフローの手順を探したりしないでください。このスキルでサポートされている方法は、scripts/ のみです。

---

ルール

1. すべてのスクリプトは、このスキルのルートディレクトリから uv run scripts/<name>.py で実行します。
2. 共通のライフサイクル／管理手順はほかのスキルが担当します。再実装せず、それらを呼び出してください。オブジェクトストアとリソースグループ → aicore-admin-resources、アーティファクト登録、実行、実行ステータス → aicore-lifecycle-management。
3. 認証情報の値を出力またはログに記録しないでください。スクリプトは SDK を通じて環境変数から読み取ります。
4. 評価シナリオ ID は genai-evaluations です。実行可能 ID は必ず genai-evaluations-simplified を使用してください。ハードコードし、バージョンやユーザーの接尾辞が付いたものは使用しないでください。テナントには、このようなカスタム構築イメージが多数表示される場合がありますが、無視してください。テナントに genai-evaluations-simplified がまったくない場合に限り、検出にフォールバックしてください（aicore-lifecycle-management の get_executables.py --scenario-id genai-evaluations）。
5. カスタムメトリックまたはプロンプトレジストリ設定を作成する前に、既存のものを一覧表示し、名前／シナリオ／バージョンで再利用して重複を避けてください。create_evaluation_metric.py はすでに作成または取得を行います。
6. 実行ステータスが COMPLETED になるまでは、結果（get_evaluation_results.py）を取得しないでください（UNKNOWN → PENDING → RUNNING → COMPLETED）。ステータスは aicore-lifecycle-management を呼び出して確認します（get_executions.py --execution-id <id>）。
7. データセットに参照／正解列がない場合、参照を必要とするメトリックは選択しないでください。

---

環境変数

このスキルのすべてのスクリプトは、認証情報を CLI 引数ではなく環境変数から読み取ります。

AI Core 認証情報（すべてのスクリプトで必須）

変数	説明	備考
AICORE_AUTH_URL	OAuth トークンエンドポイント	/oauth/token で終わる必要があります
AICORE_CLIENT_ID	OAuth クライアント ID	BTP AI Core サービスキーから取得
AICORE_CLIENT_SECRET	OAuth クライアントシークレット	BTP AI Core サービスキーから取得
AICORE_BASE_URL	AI Core API ベース URL	指定されていない場合、/v2 が自動的に追加されます
AICORE_RESOURCE_GROUP	操作対象のリソースグループ	デフォルト：default

取得元：BTP cockpit → サブアカウント → Instances & Subscriptions → AI Core インスタンス → Service Keys。

aicore configure で一度設定する（~/.aicore/config.json に保存）か、各変数をエクスポートします。

export AICORE_AUTH_URL=https://<subdomain>.authentication.<region>.hana.ondemand.com/oauth/token
export AICORE_CLIENT_ID=<client-id>
export AICORE_CLIENT_SECRET=<client-secret>
export AICORE_BASE_URL=https://api.ai.<region>.aws.ml.hana.ondemand.com
export AICORE_RESOURCE_GROUP=default

シェル構文： AICORE_RESOURCE_GROUP='default' — = の前にスペースを入れないでください。

オブジェクトストアの認証情報（download_evaluation_results.py でのみ必須）

行ごとの SQLite DB は S3 から直接ダウンロードされます。ここでは AI Core の認証情報は使用しません。標準の AWS SDK 環境変数を設定してください。スクリプトは boto3 の認証情報チェーンを直接使用します。

変数	説明
AWS_ACCESS_KEY_ID	S3 アクセスキー ID
AWS_SECRET_ACCESS_KEY	S3 シークレットアクセスキー

バケット名はコマンドラインで --bucket <name> として渡します（環境変数からは読み取りません）。 取得元：aicore-admin-resources でオブジェクトストアのシークレットを作成する際に使用したものと同じ AWS 認証情報。

---

エンドツーエンドのワークフロー

すべてのコマンドと各要素の連携方法を含む完全な実行手順は、references/WORKFLOW.md にあります。概要と各ステップを担当するスキルは次のとおりです。

#	ステップ	担当
1	S3 オブジェクトストアのシークレットを登録する（入力元）	aicore-admin-resources create_object_store.py
2	データセットをバケットにアップロードする	ユーザー — サンプルデータセットは data/ にあります
3	データセットフォルダーをアーティファクトとして登録する（prompt-evaluation ラベルを付与）	このスキル register_eval_artifact.py
4	オーケストレーションのデプロイメントが実行中であることを確認する（デプロイメント URL 用）	aicore-lifecycle-management + genai-hub-orchestration
5	システムメトリクスを選択する／カスタムメトリクスを作成する	このスキル list_evaluation_metrics.py、create_evaluation_metric.py
6	評価対象を作成する（以下の評価タイプを参照）	このスキル create_prompt_template.py または create_orchestration_registry_config.py
7	評価設定を作成する	このスキル create_evaluation_configuration.py
8	実行を開始する	aicore-lifecycle-management create_execution.py
9	COMPLETED になるまでステータスをポーリングする	aicore-lifecycle-management get_executions.py
10	集計結果を取得する	このスキル get_evaluation_results.py
11	（任意）行ごとの分析のために、生の SQLite DB をダウンロードする	このスキル download_evaluation_results.py

---

評価タイプ

1 つ選択してください。選択したタイプによって、ステップ 6 で作成するものと、ステップ 7 で create_evaluation_configuration.py に渡すバインディングが決まります。

タイプ	評価対象	作成に使用	設定バインディング
プロンプトレジストリ	プロンプトテンプレート + 1 つ以上のモデル	create_prompt_template.py	--prompt-template-id（+ --models）
オーケストレーションレジストリ	オーケストレーション設定（prompt_templating）	create_orchestration_registry_config.py	--orchestration-registry-ids
グラウンディングオーケストレーションレジストリ	グラウンディング（RAG）モジュールを含むオーケストレーション設定	create_orchestration_registry_config.py（グラウンディングテンプレート）	--orchestration-registry-ids

3 つすべてでステップ 1～5 と 7～11 は共通です。異なるのはステップ 6 と設定バインディングのみです。グラウンディングタイプでは、グラウンディングの前提条件（グラウンディングが有効なリソースグループ、グラウンディングシークレット、ドキュメントグラウンディングパイプライン）も必要です。references/GROUNDING_SETUP.md を参照してください。

---

評価メトリクス

# Discover system metric names (use these verbatim in --metrics later)
uv run scripts/list_evaluation_metrics.py --kind system
uv run scripts/list_evaluation_metrics.py --kind system --name "Pointwise"

# List your custom metrics and their IDs
uv run scripts/list_evaluation_metrics.py --kind custom --json | jq '.[] | {id, name}'

# Create (or reuse) custom LLM-as-a-judge metrics from a definition file (idempotent).
# See templates/custom-metric.json. Prints the resulting metric ID(s).
uv run scripts/create_evaluation_metric.py --file templates/custom-metric.json

一般的なシステムメトリクス：Pointwise Conciseness、Pointwise Answer Relevance、 Pointwise Instruction Following、Pointwise Correctness、Pointwise RAG Context Relevance、 Pointwise RAG Groundedness、Pointwise RAG Context Precision、Pointwise RAG Completeness。 list_evaluation_metrics.py --kind system を使用して、テナントでの正確な名称を確認してください。

---

ステップ 6 — 評価対象を作成する

タイプ 1 — プロンプトレジストリ

Prompt Registry でプロンプトテンプレートを作成（または既存のものを再利用）し、モデル間でベンチマークを実施します。

uv run scripts/list_prompt_templates.py --scenario genai-evaluations          # reuse?
uv run scripts/create_prompt_template.py --file templates/prompt-template.json \
  --name prompt-registry-eval-demo --version 1.0.0

プロンプトテンプレート ID が返されます。ステップ 7 で --prompt-template-id と、--models（例："gpt-4o:2024-05-13"）を渡してください。

タイプ 2 — オーケストレーションレジストリ

オーケストレーション設定（prompt_templating、グラウンディングなし）を作成（または既存のものを再利用）します。

uv run scripts/list_orchestration_registry_configs.py --scenario genai-evaluations   # reuse?
uv run scripts/create_orchestration_registry_config.py \
  --file templates/orchestration-registry-config.json \
  --name genai-eval-prompt-config --version 0.0.1

設定 ID が返されます。ステップ 7 で --orchestration-registry-ids を渡してください。

タイプ 3 — グラウンディングオーケストレーションレジストリ（RAG）

まず references/GROUNDING_SETUP.md のグラウンディングの前提条件を完了してから、グラウンディングテンプレートを使用して設定を作成します（grounding モジュールが追加されます）。

uv run scripts/create_orchestration_registry_config.py \
  --file templates/orchestration-registry-grounding-config.json \
  --name genai-eval-grounding-config --version 0.0.1

設定 ID が返されます。ステップ 7 で --orchestration-registry-ids を渡してください。このタイプでは、RAG メトリクス（Pointwise RAG Groundedness、Pointwise RAG Context Relevance、…）を選択してください。

---

Step 7 — 評価の設定と実行

実行可能 ID genai-evaluations-simplified をそのまま使用してください（ルール 4 に従い、バージョンやユーザー名が付加された形式は使用しないでください）。次に、このスキルのスクリプトで設定を作成します。

# 2a. Create the evaluation configuration — ORCHESTRATION / GROUNDING types
uv run scripts/create_evaluation_configuration.py \
  --executable-id genai-evaluations-simplified \
  --dataset-artifact-id <artifact-id> \
  --test-dataset-path testdata/full_dataset.csv \
  --test-dataset-type csv \
  --metrics "Pointwise Correctness,Pointwise Answer Relevance" \
  --orchestration-registry-ids <registry-config-id> \
  --orchestration-deployment-url <orchestration-deployment-url> \
  --repetitions 1

# 2b. Create the evaluation configuration — PROMPT REGISTRY type
uv run scripts/create_evaluation_configuration.py \
  --executable-id genai-evaluations-simplified \
  --dataset-artifact-id <artifact-id> \
  --test-dataset-path testdata/full_dataset.csv \
  --metrics "Pointwise Correctness" \
  --prompt-template-id <prompt-template-id> \
  --models "gpt-4o:2024-05-13" \
  --orchestration-deployment-url <orchestration-deployment-url>

create_evaluation_metric.py で作成したカスタムメトリクス ID は、--metrics に追加できます。--test-row-count N で行数を制限します。--variable-mapping '{"all_metrics/reference":"data/ground_truth"}' で変数をデータセットの列にマッピングします。

次に、実行自体は aicore-lifecycle-management に引き継ぎます。

• 実行を開始する — create_execution.py --configuration-id <config-id>
• COMPLETED になるまでポーリングする — get_executions.py --execution-id <execution-id> （ステータスは UNKNOWN → PENDING → RUNNING → COMPLETED の順に変化します）

---

結果

# Aggregate metrics per model/prompt run (only once COMPLETED)
uv run scripts/get_evaluation_results.py --execution-id <execution-id>
uv run scripts/get_evaluation_results.py --execution-id <execution-id> --json

インスタンス単位の結果（行ごとのスコア、レイテンシ、ログ）を取得するには、オブジェクトストレージから SQLite DB（<execution-id>/tmp/results.db）をダウンロードします。環境に AWS_ACCESS_KEY_ID と AWS_SECRET_ACCESS_KEY を設定し、--bucket でバケット名を渡してください。

uv run scripts/download_evaluation_results.py --execution-id <execution-id> --bucket <bucket> --show-tables

ダウンロードからローカルでの確認までの手順（テーブルスキーマ、行ごとのメトリクスのクエリ）については、references/RESULTS_ANALYSIS.md を参照してください。

---

引き継ぎ

• 認証情報、リソースグループ、またはオブジェクトストアのシークレットが未設定ですか？ → aicore-admin-resources を呼び出してください
• 実行の開始、停止、確認、実行可能ファイルの検出、またはデプロイメントの管理が必要ですか？ → aicore-lifecycle-management を呼び出してください
• 実行中のオーケストレーションデプロイメントが必要ですか？ またはプロンプト／RAG パイプラインを設計しますか？ → genai-hub-orchestration を呼び出してください
• グラウンディングタイプ用のグラウンディング（RAG）を設定していますか？ → references/GROUNDING_SETUP.md を参照してください（リソースグループとシークレットには aicore-admin-resources を使用します）
• オフラインサービスを使ってエージェント（プロンプト／LLM ではなく）を評価しますか？ → aeval-offline-evaluation を呼び出してください

---

参照ファイルを読み込むタイミング

トリガー	読み込むファイル
エンドツーエンド評価を一通り実行する場合、または次に実行するコマンドが不明な場合	references/WORKFLOW.md
グラウンディングオーケストレーションタイプの前提条件としてグラウンディング（RAG）を設定する場合	references/GROUNDING_SETUP.md
行ごとの未加工の結果（オブジェクトストレージ内の SQLite DB）をダウンロードして確認する場合	references/RESULTS_ANALYSIS.md