View a markdown version of this page

开始批量评估 - 亚马逊基岩 AgentCore

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

开始批量评估

启动批量评估,针对多个代理会话运行评估器。该服务从 CloudWatch 日志中发现会话,针对每个会话运行每个评估器,并生成汇总结果。

代码示例

例
AgentCore CLI

当您使用--runtime以下内容时,CLI logGroupNames 会自动从项目配置中解析serviceNames并自动解析:

agentcore run batch-evaluation \ --runtime MyAgent \ --evaluator Builtin.GoalSuccessRate Builtin.Helpfulness Builtin.Faithfulness

带有可选标志:

# Custom name and lookback window agentcore run batch-evaluation \ --runtime MyAgent \ --evaluator Builtin.GoalSuccessRate \ --name my_baseline_eval \ --lookback-days 1 # Specific sessions agentcore run batch-evaluation \ --runtime MyAgent \ --evaluator Builtin.GoalSuccessRate \ --session-ids session-abc123 session-def456 # With ground truth agentcore run batch-evaluation \ --runtime MyAgent \ --evaluator Builtin.GoalSuccessRate Builtin.Correctness \ --ground-truth ground-truth.json

默认情况下,该命令启动任务并立即返回。传递--wait到区块直到任务达到终端状态(COMPLETEDFAILED、或STOPPED),之后 CLI 会显示每个评估者的平均分数并将结果保存到。.cli/jobs/batch-eval-results/

agentcore run batch-evaluation还支持以下标志:

  • --wait— 阻塞直到任务达到终端状态。

  • --json— 发出机器可读的 JSON 输出。

  • --kms-key <arn>— 使用客户管理的 KMS 密钥加密批量评估结果。

  • --dataset <name>/--dataset-version <version>— 在批量评估之前使用数据集场景调用代理(省略本地文件的版本,或使用N/DRAFT)。

  • --endpoint <name>— 以特定的运行时端点为目标(例如,PROMPT_V1);则默认为AGENTCORE_RUNTIME_ENDPOINT环境变量DEFAULT。

  • --evaluator-arn <arns…​>— 按 ARN 来引用评估者,而不是. -e

    大多数标志都有简短的别名:-r(--runtime)、-e (--evaluator)、-n (--name)、-d (--lookback-days)、-s (--session-ids) 和 -g (--ground-truth)。

    要在作业启动后对其进行管理,请运行agentcore stop batch-evaluation -i <id>以停止正在运行的作业并agentcore archive batch-evaluation -i <id>存档作业记录。

AWS SDK (boto3)
import boto3 import uuid import time import json client = boto3.client("bedrock-agentcore", region_name="us-west-2") # All sessions in the log group response = client.start_batch_evaluation( batchEvaluationName=f"baseline_eval_{uuid.uuid4().hex[:8]}", evaluators=[ {"evaluatorId": "Builtin.GoalSuccessRate"}, {"evaluatorId": "Builtin.Helpfulness"}, {"evaluatorId": "Builtin.Faithfulness"}, ], dataSourceConfig={ "cloudWatchLogs": { "serviceNames": ["MyAgent.DEFAULT"], "logGroupNames": ["/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"], } }, clientToken=str(uuid.uuid4()), ) batch_eval_id = response["batchEvaluationId"] print(f"Started: {batch_eval_id}") # Poll until complete while True: result = client.get_batch_evaluation(batchEvaluationId=batch_eval_id) status = result["status"] print(f"Status: {status}") if status in ("COMPLETED", "COMPLETED_WITH_ERRORS", "FAILED", "STOPPED"): break time.sleep(30) print(json.dumps(result, indent=4, default=str))

使用会话 ID 过滤:

response = client.start_batch_evaluation( batchEvaluationName=f"targeted-eval-{uuid.uuid4().hex[:8]}", evaluators=[ {"evaluatorId": "Builtin.GoalSuccessRate"}, ], dataSourceConfig={ "cloudWatchLogs": { "serviceNames": ["MyAgent.DEFAULT"], "logGroupNames": ["/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"], "filterConfig": { "sessionIds": ["session-001", "session-002", "session-003"] }, } }, clientToken=str(uuid.uuid4()), )

使用时间范围过滤:

from datetime import datetime, timedelta, timezone now = datetime.now(timezone.utc) response = client.start_batch_evaluation( batchEvaluationName=f"weekly-eval-{uuid.uuid4().hex[:8]}", evaluators=[ {"evaluatorId": "Builtin.GoalSuccessRate"}, ], dataSourceConfig={ "cloudWatchLogs": { "serviceNames": ["MyAgent.DEFAULT"], "logGroupNames": ["/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"], "filterConfig": { "timeRange": { "startTime": (now - timedelta(days=7)).isoformat(), "endTime": now.isoformat(), } }, } }, clientToken=str(uuid.uuid4()), )

请求参数

参数 Type 必需 描述

batchEvaluationName

字符串

是

批量评估作业的名称。模式:以字母、字母数字和下划线开头,最多 48 个字符。

dataSourceConfig

对象

是

在哪里可以找到代理会话。使用代理的服务名称和确切的日志组名称或日志组名称前缀指定cloudWatchLogs来源。请参阅下面的会话来源。

evaluators

列表

是

评估人员名单。每个条目都有一个evaluatorId字段(例如,Builtin.GoalSuccessRate)。最多 10 名评估者。

evaluationMetadata

对象

否

包含sessionMetadata每个会话的真实情况和元数据列表。最多 500 个条目。

outputConfig

对象

否

每个会话结果和分数指标的可选 CloudWatch 目的地。指定 a cloudWatchConfig 以选择结果日志组和指标命名空间。请参阅下面的结果输出。

clientToken

字符串

否

等效性标记。如果您使用相同的客户端令牌重试请求,该服务将返回现有任务,而不是创建新任务。

会话来源

该dataSourceConfig参数指定服务发现代理会话的 CloudWatch 日志位置。

必填字段

字段 Type 说明

cloudWatchLogs.serviceNames

字符串列表(正好是 1)

用于识别您的代理在中的痕迹的服务名称 CloudWatch。公约:{RuntimeName}.DEFAULT。

cloudWatchLogs.logGroupNames

字符串列表 (1—5)

选择输入日志组的一种方法。指定存储代理遥测数据的确切 CloudWatch 日志组名称。与 logGroupNamePrefixes 互相排斥。

cloudWatchLogs.logGroupNamePrefixes

字符串列表 (1—5)

选择输入日志组的一种方法。该服务会发现名称以其中一个前缀开头的每个日志组的会话,因此系统会自动选取新创建的匹配日志组。与 logGroupNames 互相排斥。

请仅指定logGroupNames或中的一个logGroupNamePrefixes。在这两种情况下,serviceNames都需要在所选日志组中识别代理的跟踪。

如果您使用logGroupNamePrefixes来匹配 Amazon Bedrock AgentCore 运行时日志组,请确保您的运行时将跨度发送到代理自己的日志组。对于仍在使用共享aws/spans日志组的代理,请在运行时UNIFIED_TRACES_DESTINATION_ENABLED=true进行设置。有关更多信息,请参阅 Amazon Bedrock AgentCore 运行时中托管的代理的跨度目标。

# Match input log groups by prefix instead of exact names dataSourceConfig={ "cloudWatchLogs": { "logGroupNamePrefixes": ["/aws/bedrock-agentcore/runtimes/MyAgent-"], "serviceNames": ["MyAgent.DEFAULT"] } }

可选字段

字段 Type 说明

cloudWatchLogs.filterConfig.sessionIds

字符串列表

仅评估这些特定的会话 ID。省略时,该服务会发现日志组中的所有会话。

cloudWatchLogs.filterConfig.timeRange.startTime

ISO 8601 日期时间

筛选在此时间之后创建的会话。

cloudWatchLogs.filterConfig.timeRange.endTime

ISO 8601 日期时间

筛选在此时间之前创建的会话。

结果输出

默认情况下,批量评估结果将转到由服务管理的专用日志组。outputConfig.cloudWatchConfig用于控制每个会话结果的写入位置以及哪些 CloudWatch 指标命名空间接收评估分数。

选择写入结果的位置

  • DEDICATED_LOG_GROUP(默认)-将结果写入专用的结果日志组。如果您未设置logGroupName,则该服务会为您管理群组。要使用自己的群组,请设置logGroupName(参见使用自定义输出日志组)。

  • SOURCE_LOG_GROUP— 将结果写回读取代理跟踪的同一个日志组。当你使用这个值时,不要设置logGroupName。

使用自定义输出日志组

对于DEDICATED_LOG_GROUP,设置logGroupName为将结果写入您选择的日志组。现有日志组按原样使用;如果不存在,则服务会创建该日志组,这需要执行角色授权logs:CreateLogGroup。除了服务管理的默认组外,该名称不能位于服务预留/aws/bedrock-agentcore/evaluations/命名空间下。

# Write results back to the trace source log group outputConfig={ "cloudWatchConfig": { "resultDestination": "SOURCE_LOG_GROUP" } } # Write results to a custom dedicated log group outputConfig={ "cloudWatchConfig": { "resultDestination": "DEDICATED_LOG_GROUP", "logGroupName": "/my/team/batch-evaluation-results" } }

将指标发布到自定义命名空间

设置metricsNamespace为在自己的 CloudWatch 命名空间下发布分数指标,而不是Bedrock-AgentCore/Evaluations。该值不能以此开头AWS/。

outputConfig={ "cloudWatchConfig": { "metricsNamespace": "MyTeam/Evaluations" } }

响应

字段 Type 说明

batchEvaluationId

字符串

批量评估的唯一标识符。

batchEvaluationArn

字符串

批量评估的 ARN。

batchEvaluationName

字符串

你指定的名字。

status

字符串

初始状态。其中之一:PENDING,IN_PROGRESS.

evaluators

列表

使用的评估人员。

createdAt

Timestamp

创建任务的时间。

outputConfig

对象

CloudWatch 每个会话结果和分数指标的目的地。

错误

错误 HTTP 状态 说明

ValidationException

400

请求参数无效。检查字段限制和必填字段。

AccessDeniedException

403

权限不足。验证 IAM 策略。

ConflictException

409

已经存在具有相同客户令牌且参数不同的批量评估。

ThrottlingException

429

超出请求速率。使用指数回退进行重试。

InternalServerException

500

Service-side 错误。重试请求。