> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 运行评测实验

`eval run` 是串联评测闭环的核心命令：它以一个评测集、一个或多个评估器，对一个已部署的运行时或 TEA 源评测目标提交一次实验。评测集、评估器与目标均可用 ID 或名称指定，字段映射默认自动完成。

```bash lines theme={null}
agentkit eval run \
  --dataset qa-set \
  --evaluator 相关性 \
  --evaluator-version 0.0.1 \
  --target my-agent
```

<Note>
  CLI 会先解析当前账号使用的评测后端。TEA 后端要求每个 `--evaluator` 都对应一个 `--evaluator-version`；Coze 后端继续使用评估器当前版本。需要查看当前后端时，运行 [`eval backend`](/productions/agentkit-cli/preview/zh/commands/eval/backend)。
</Note>

## eval run

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `--dataset <id\|name>` | 评测集 ID 或精确名称。 | 必填 |
| `--dataset-version <id\|name>` | TEA 评测集版本 ID 或版本号；未传时使用已有已提交版本，必要时自动发布草稿版本。 | — |
| `--evaluator <id\|name>` | 评估器 ID 或精确名称；可重复指定多个。 | 必填 |
| `--evaluator-version <id\|name>` | TEA 评估器版本 ID 或版本号；必须与 `--evaluator` 数量一致。 | — |
| `--target <runtime name\|id>` | 被评测的已部署 Runtime 或 TEA 源评测目标。 | 必填 |
| `--target-type <n>` | TEA 源评测目标类型。 | `101` |
| `--target-version <version>` | TEA 源评测目标版本；未传时使用版本列表中的最新版本。 | 最新版本 |
| `--name <name>` | 实验名称。 | `<数据集>-<时间戳>` |
| `--description <text>` | 实验描述。 | — |
| `--concurrency <n>` | 并发执行的用例数。 | `5` |
| `--map <spec>` | 覆盖字段映射，可重复，语法见下文。 | 自动 |
| `--dry-run` | 仅打印将提交的请求，不真正发起实验。 | `false` |
| `-p, --project <name>` | Coze 项目名称；TEA 后端忽略。 | `default` |
| `--json` | 输出原始 JSON。 | `false` |

```bash lines theme={null}
agentkit eval run \
  --dataset qa-set \
  --dataset-version 0.0.1 \
  --evaluator 相关性 \
  --evaluator-version 0.0.1 \
  --target my-agent \
  --target-version <target-version> \
  --concurrency 8
```

## 自动字段映射

一次实验中有三层数据需要对齐：评测集字段、目标输入与输出、评估器输入。`eval run` 会按约定自动连接：

* 目标运行时通常以 `user_input` 为输入字段、`actual_output` 为输出字段；评测集的主输入字段（如 `input`）会传入目标的 `user_input`。
* 评估器中表示模型答案的字段（如 `output`）取自目标输出 `actual_output`；其余字段（如 `input`、`reference_output`）按同名从评测集取值。

多数场景无需手动映射。当字段名不一致时，用 `--map` 覆盖。

### `--map` 语法

TEA 后端使用带前缀的箭头语法：

| 形式 | 含义 |
| - | - |
| `evaluator.<字段> <- dataset.<字段>` | 评估器输入取自评测集字段。 |
| `evaluator.<字段> <- target.<字段>` | 评估器输入取自目标输出字段。 |
| `target.<字段> <- dataset.<字段>` | 目标输入取自评测集字段。 |

```bash lines theme={null}
agentkit eval run --dataset qa-set --evaluator 相关性 --evaluator-version 0.0.1 --target my-agent \
  --map "evaluator.output <- target.actual_output" \
  --map "target.user_input <- dataset.question"
```

Coze 后端使用等号语法：

| 形式 | 含义 |
| - | - |
| `<评估器字段>=<评测集字段>` | 评估器输入取自评测集字段。 |
| `<评估器字段>=target:<目标输出>` | 评估器输入取自目标输出字段。 |
| `target:<目标输入>=<评测集字段>` | 目标输入取自评测集字段。 |

## 提交前先核对

建议首次运行前加 `--dry-run`，确认解析出的评测集版本、评估器版本、目标版本与字段映射无误：

```bash lines theme={null}
agentkit eval run \
  --dataset qa-set \
  --evaluator 相关性 \
  --evaluator-version 0.0.1 \
  --target my-agent \
  --dry-run
```

<Note>
  实验要求评测集有一个已提交的版本。未指定 `--dataset-version` 且评测集只有未提交草稿时，`eval run` 会在提交前自动发布一个版本；指定 `--dataset-version` 时会使用该版本。
</Note>

提交成功后返回实验 ID；TEA 后端还会返回 run ID。可用 [`eval experiment show`](/productions/agentkit-cli/preview/zh/commands/eval/experiment#eval-experiment-show) 跟踪：

```bash lines theme={null}
agentkit eval run --dataset qa-set --evaluator 相关性 --evaluator-version 0.0.1 --target my-agent --json
# → { "experimentId": "75901...", "runId": "75902...", "name": "qa-set-<timestamp>" }
```