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

# 开始批量评估
<a name="batch-evaluations-start"></a>

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

## 代码示例
<a name="start-batch-eval-examples"></a>

**Example**  
当您使用`--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`到区块，直到作业达到终端状态（`COMPLETED``FAILED`、或`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>`存档作业记录。

```
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()),
)
```

## 请求参数
<a name="start-batch-eval-params"></a>


| 参数 | 类型 | 必需 | 描述 | 
| --- | --- | --- | --- | 
|  `batchEvaluationName`  | 字符串 | 是 | 批量评估作业的名称。模式：以字母、字母数字和下划线开头，最多 48 个字符。 | 
|  `dataSourceConfig`  | 对象 | 是 | 在哪里可以找到代理会话。使用代理的服务名称以及确切的日志组名称或日志组名称前缀来指定`cloudWatchLogs`来源。请参阅下面的[会话来源](#start-batch-eval-session-source)。 | 
|  `evaluators`  | 列表 | 是 | 评估者名单。每个条目都有一个`evaluatorId`字段（例如，`Builtin.GoalSuccessRate`）。最多 10 个赋值器。 | 
|  `evaluationMetadata`  | 对象 | 否 | 包含`sessionMetadata`每个会话的基本事实和元数据的列表。最多 500 个参赛作品。 | 
|  `outputConfig`  | 对象 | 否 | 每个会话结果和分数指标的可选 CloudWatch 目的地。指定 a `cloudWatchConfig` 以选择结果日志组和指标命名空间。请参阅下面的[结果输出](#start-batch-eval-output)。 | 
|  `clientToken`  | 字符串 | 否 | 等能令牌。如果您使用相同的客户端令牌重试请求，服务将返回现有任务，而不是创建新任务。 | 

## 会话来源
<a name="start-batch-eval-session-source"></a>

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

### 必填字段
<a name="start-batch-eval-session-source-required"></a>


| 字段 | 类型 | 说明 | 
| --- | --- | --- | 
|  `cloudWatchLogs.serviceNames`  | 字符串列表（正好是 1） | 用于识别您的代理跟踪的服务名称 CloudWatch。惯例：`{RuntimeName}.DEFAULT`。 | 
|  `cloudWatchLogs.logGroupNames`  | 字符串列表 (1—10) | 一种选择输入日志组的方法。指定存储代理遥测数据的确切 CloudWatch 日志组名称。与 `logGroupNamePrefixes` 互相排斥。 | 
|  `cloudWatchLogs.logGroupNamePrefixes`  | 字符串列表 (1—5) | 一种选择输入日志组的方法。该服务会从名称以其中一个前缀开头的每个日志组中发现会话，因此系统会自动选择新创建的匹配日志组。与 `logGroupNames` 互相排斥。 | 

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

如果您使用`logGroupNamePrefixes`匹配 Amazon Bedrock AgentCore 运行时日志组，请确保您的运行时将跨度发送到代理自己的日志组。对于仍在使用共享`aws/spans`日志组的代理，请在运行时`UNIFIED_TRACES_DESTINATION_ENABLED=true`进行设置。有关更多信息，请参阅 [Amazon Bedrock AgentCore 运行时中托管的代理的 Span 目标](observability-configure.md#observability-configure-unified-traces)。

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

### 可选字段
<a name="start-batch-eval-session-source-optional"></a>


| 字段 | 类型 | 说明 | 
| --- | --- | --- | 
|  `cloudWatchLogs.filterConfig.sessionIds`  | 字符串列表 | 仅评估这些特定的会话 ID。省略时，服务会发现日志组中的所有会话。 | 
|  `cloudWatchLogs.filterConfig.timeRange.startTime`  | ISO 8601 日期时间 | 筛选在此时间之后创建的会话。 | 
|  `cloudWatchLogs.filterConfig.timeRange.endTime`  | ISO 8601 日期时间 | 筛选在此时间之前创建的会话。 | 

## 结果输出
<a name="start-batch-eval-output"></a>

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

### 选择结果写在哪里
<a name="start-batch-eval-output-destination"></a>
+  `DEDICATED_LOG_GROUP`（默认）-将结果写入专用的结果日志组。如果您未设置`logGroupName`，则该服务会为您管理群组。要使用自己的群组，请设置`logGroupName`（请参阅[使用自定义输出日志组](#start-batch-eval-custom-output-log-group)）。
+  `SOURCE_LOG_GROUP`— 将结果写回读取代理跟踪的同一日志组。使用此值时，请不要设置`logGroupName`。

### 使用自定义输出日志组
<a name="start-batch-eval-custom-output-log-group"></a>

对于`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"
    }
}
```

### 将指标发布到自定义命名空间
<a name="start-batch-eval-custom-metrics-namespace"></a>

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

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

## 响应
<a name="start-batch-eval-response"></a>


| 字段 | 类型 | 说明 | 
| --- | --- | --- | 
|  `batchEvaluationId`  | 字符串 | 批次评估的唯一标识符。 | 
|  `batchEvaluationArn`  | 字符串 | 批量评估的 ARN。 | 
|  `batchEvaluationName`  | 字符串 | 您指定的名称。 | 
|  `status`  | 字符串 | 初始状态。其中之一：`PENDING`，`IN_PROGRESS`。 | 
|  `evaluators`  | 列表 | 使用的评估者。 | 
|  `createdAt`  | Timestamp | 创建作业的时间。 | 
|  `outputConfig`  | 对象 | CloudWatch 每个会话结果和分数指标的目的地。 | 

## 错误
<a name="start-batch-eval-errors"></a>


| 错误 | HTTP 状态 | 说明 | 
| --- | --- | --- | 
|  `ValidationException`  | 400 | 请求参数无效。检查字段限制和必填字段。 | 
|  `AccessDeniedException`  | 403 | 权限不足。验证 IAM 策略。 | 
|  `ConflictException`  | 409 | 已经存在使用相同客户端令牌的批量评估，参数不同。 | 
|  `ThrottlingException`  | 429 | 超出请求速率。使用指数回退进行重试。 | 
|  `InternalServerException`  | 500 | Service-side 错误。重试请求。 |