結果と出力について

バッチ評価結果には、API レスポンスの集計概要と CloudWatch Logs のセッションごとの詳細の 2 つのレイヤーがあります。

結果を集計する

バッチ評価が完了すると、GetBatchEvaluationレスポンスには集計概要を含むevaluationResultsオブジェクトが含まれます。

セッション数

評価者ごとの概要

の各エントリevaluatorSummariesは、1 つの評価者の集計メトリクスを提供します。

レスポンスの例

{
    "batchEvaluationId": "12345678-1234-1234-1234-123456789012",
    "status": "COMPLETED",
    "evaluationResults": {
        "numberOfSessionsCompleted": 47,
        "numberOfSessionsFailed": 3,
        "numberOfSessionsIgnored": 0,
        "totalNumberOfSessions": 50,
        "evaluatorSummaries": [
            {
                "evaluatorId": "Builtin.GoalSuccessRate",
                "statistics": {
                    "averageScore": 0.72
                },
                "totalEvaluated": 47,
                "totalFailed": 0
            },
            {
                "evaluatorId": "Builtin.Helpfulness",
                "statistics": {
                    "averageScore": 0.81
                },
                "totalEvaluated": 47,
                "totalFailed": 0
            }
        ]
    }
}

CloudWatch Logs のセッションごとの詳細

GetBatchEvaluation レスポンスの outputConfigフィールドは、セッションごと、評価者ごとの結果が OpenTelemetry イベントとして書き込まれる CloudWatch Logs の場所を指定します。

{
    "outputConfig": {
        "cloudWatchConfig": {
            "logGroupName": "/aws/bedrock-agentcore/evaluations/batch",
            "logStreamName": "12345678-1234-1234-1234-123456789012"
        }
    }
}

ログストリームの各イベントには、ターンごと、評価者ごとの詳細が含まれます。

これらのイベントを読み取るには、CloudWatch Logs API を使用します。

import boto3

logs_client = boto3.client("logs", region_name="us-west-2")

response = logs_client.get_log_events(
    logGroupName="/aws/bedrock-agentcore/evaluations/batch",
    logStreamName="12345678-1234-1234-1234-123456789012",
)

for event in response["events"]:
    print(event["message"])

スコアの解釈

バッチ評価スコアは、オンデマンド評価と同じ規則に従います。

エラー処理

ジョブレベルのエラー

バッチ評価ジョブが完全に失敗した場合、 statusは FAILEDであり、問題を説明する 1 つ以上のエラーメッセージerrorDetailsが含まれています。一般的な原因:

セッションレベルのエラー

ジョブ全体が成功している間、個々のセッションが失敗する可能性があります。のnumberOfSessionsFailedカウントは、エラーが発生したセッションの数evaluationResultsを示します。セッションごとのエラーは CloudWatch Logs 出力に記録されます。

評価者レベルのエラー

正常に評価されたセッション内では、個々の評価者が失敗する可能性があります。各評価者の概要のtotalFailedカウントは、評価者がスコアリングできなかったセッションの数を示します。一般的な原因には、不正な形式のスパンや必須属性の欠落などがあります。

実行間での結果の比較

一般的なワークフローは、変更 (プロンプト更新、モデルスワップ、ツール変更) の前後にバッチ評価を実行し、集計スコアを比較することです。

# After running two batch evaluations
baseline = client.get_batch_evaluation(batchEvaluationId=baseline_id)
treatment = client.get_batch_evaluation(batchEvaluationId=treatment_id)

baseline_summaries = {
    s["evaluatorId"]: s["statistics"]["averageScore"]
    for s in baseline["evaluationResults"]["evaluatorSummaries"]
}
treatment_summaries = {
    s["evaluatorId"]: s["statistics"]["averageScore"]
    for s in treatment["evaluationResults"]["evaluatorSummaries"]
}

print(f"{'Evaluator':<35} {'Baseline':>10} {'Treatment':>10} {'Delta':>10}")
print("=" * 67)
for eid in baseline_summaries:
    b = baseline_summaries[eid]
    t = treatment_summaries.get(eid, 0)
    delta = t - b
    print(f"{eid:<35} {b:>10.4f} {t:>10.4f} {delta:>+10.4f}")

CLI からの結果の表示

GetBatchEvaluation API に加えて、AgentCore CLI は同じ結果を表示します。

# View a single batch evaluation job and its results
agentcore view batch-evaluation 12345678-1234-1234-1234-123456789012 --json

# List batch evaluation jobs (running jobs are refreshed from the service)
agentcore batch-evaluations history --json