# 获取评测任务列表

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`POST https://ark.cn-beijing.volcengineapi.com/?Action=ListEvaluationJobs&Version=2024-01-01`

获取评测任务列表，支持按创建时间/更新时间排序，并可通过标签、状态、模型等条件进行筛选。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* Access Key 鉴权，请在 [Access Key 管理](https://console.volcengine.com/iam/keymanage) 页面，获取 Access Key。本接口仅支持 Access Key 鉴权。

---

<span id="request-parameters"></span>
## 请求参数

### Body 参数

**Filter** `object` | 任务筛选条件

评测任务的筛选条件，可按状态、模型、ID 等过滤。

**CustomModelIds** `string[]` | 定制模型 ID 列表

`Filter.CustomModelIds`

定制模型 ID 列表，用于筛选评测对象为指定定制模型的任务。

**Description** `string` | 任务描述模糊匹配

`Filter.Description`

评测任务描述的模糊匹配关键字。

**FoundationModels** `object[]` | 基础模型筛选

`Filter.FoundationModels`

基础模型筛选条件列表，多项为「或」关系。

**Name** `string` `必选` | 基础模型名称

`Filter.FoundationModels.Name`

**ModelVersions** `string[]` | 基础模型版本列表

`Filter.FoundationModels.ModelVersions`

基础模型版本列表，多版本为「或」关系。

**Id** `string` | 任务 ID 模糊匹配

`Filter.Id`

评测任务 ID 的模糊匹配关键字。

**Ids** `string[]` | 任务 ID 列表

`Filter.Ids`

精确匹配的评测任务 ID 列表。

**Name** `string` | 任务名称模糊匹配

`Filter.Name`

评测任务名称的模糊匹配关键字。

**Phases** `string[]` | 任务状态列表

`Filter.Phases`

评测任务状态列表，取值参考 *EvaluationJobStatus.Phase*。多值为「或」关系。

**PageNumber** `integer` `默认值 1` | 起始页码

分页查询的起始页码，从 1 开始。

**最小值**：`1`

**PageSize** `integer` `默认值 10` | 每页记录数

每页返回的记录数。

**取值范围**：`[1, 100]`

**ProjectName** `string` `默认值 default` | 所属项目

资源所属的项目名称。若资源不在默认项目中，需填写正确的项目名称。

**SortBy** `string` `默认值 CreateTime` | 排序指标

排序指标：

- `CreateTime`：按创建时间排序。
- `UpdateTime`：按更新时间排序。

**SortOrder** `string` `默认值 Desc` | 排序顺序

排序顺序：

- `Asc`：升序。
- `Desc`：降序。

**TagFilters** `object[]` | 标签筛选条件

基于绑定标签的筛选条件。多个标签为「与」关系。

**Key** `string` `必选` | 标签键

`TagFilters.Key`

**Values** `string[]` | 标签值列表

`TagFilters.Values`

标签值列表，多值为「或」关系。

## 响应参数

**Items** `object[]` | 任务列表

本页返回的模型评测任务列表。

**CreateTime** `string` | 创建时间

`Items.CreateTime`

评测任务的创建时间，RFC 3339 格式。

**Description** `string` | 任务描述

`Items.Description`

模型评测任务描述。

**Id** `string` | 评测任务 ID

`Items.Id`

模型评测任务的 ID。

**ModelReference** `object` | 评测对象

`Items.ModelReference`

评测对象（模型）的引用信息。

**CustomModelId** `string` | 定制模型 ID

`Items.ModelReference.CustomModelId`

定制模型的 ID。

**FoundationModel** `object` | 基础模型

`Items.ModelReference.FoundationModel`

基础模型引用。

**ModelVersion** `string` | 基础模型版本

`Items.ModelReference.FoundationModel.ModelVersion`

基础模型版本号。

**Name** `string` | 基础模型名称

`Items.ModelReference.FoundationModel.Name`

**Name** `string` | 任务名称

`Items.Name`

模型评测任务名称。

**ProjectName** `string` | 所属项目

`Items.ProjectName`

评测任务所属的项目名称。

**Tags** `object[]` | 任务标签

`Items.Tags`

评测任务绑定的标签列表。

**Key** `string` | 标签键

`Items.Tags.Key`

**Value** `string` | 标签值

`Items.Tags.Value`

**UpdateTime** `string` | 更新时间

`Items.UpdateTime`

评测任务最近一次更新时间，RFC 3339 格式。

**EndpointId** `string` | 接入点 ID

`Items.EndpointId`

评测任务对应接入点的 ID。

**ResultTosLocation** `object` | 评测结果 TOS 地址

`Items.ResultTosLocation`

评测结果在 TOS 的存储地址。

**BucketName** `string` | TOS 桶名称

`Items.ResultTosLocation.BucketName`

> **说明：注意**
>
> 当前火山方舟仅支持华北 2-北京地域（`region: cn-beijing`）的 TOS 桶。

**ObjectKey** `string` | TOS 对象路径

`Items.ResultTosLocation.ObjectKey`

TOS 对象路径（Object Key）。

**Status** `object` | 任务状态

`Items.Status`

评测任务的状态元信息。

**Phase** `string` | 任务状态

`Items.Status.Phase`

评测任务的当前状态阶段。取值通常为 `Queued`、`Running`、`Succeeded`、`Failed`、`Terminated` 等。

> **说明**
>
> 状态机：`Queued` -> `Running` -> `Succeeded` / `Failed` / `Terminated`，终态后不可恢复运行。

**PhaseTime** `string` | 状态更新时间

`Items.Status.PhaseTime`

任务最近一次进入当前状态的时间，RFC 3339 格式。

**Message** `string` | 状态说明

`Items.Status.Message`

状态附加说明。当任务为 `Failed` 状态时通常包含失败原因。

**PageNumber** `integer` | 起始页码

当前返回结果的页码。

**PageSize** `integer` | 每页记录数

当前返回结果的单页记录数。

**TotalCount** `integer` | 任务总数

符合筛选条件的评测任务总数。


## 代码示例

## 默认

### cURL

#### Request

```bash
curl 'https://ark.cn-beijing.volcengineapi.com/?Action=ListEvaluationJobs&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'X-Date: <X-Date>' \
  -H 'X-Content-Sha256: <X-Content-Sha256>' \
  -H 'Authorization: HMAC-SHA256 Credential=<AK>/<X-Date>/cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=<Signature>' \
  -d '{
    "PageNumber": 1,
    "PageSize": 1,
    "SortOrder": "Asc",
    "SortBy": "CreateTime",
    "TagFilters": [],
    "ProjectName": "default",
    "Filter": {
        "Phases": [
            "Succeeded"
        ]
    }
}
'
```

#### Response

```
{
    "ResponseMetadata": {
        "RequestId": "20240411145356A067F3B9F09679456C",
        "Action": "ListEvaluationJobs",
        "Version": "2024-01-01",
        "Service": "ark",
        "Region": "cn-beijing"
    },
    "Result": {
        "TotalCount": 10,
        "PageNumber": 1,
        "PageSize": 10,
        "Items": [
            {
                "Id": "ej-20240401114848-w5b8f",
                "Name": "test-evaluation-job",
                "Description": "示例评测任务",
                "ModelReference": {
                    "CustomModelId": "cm-20240401114541-5gzd8"
                },
                "EndpointId": "ep-20240401114848-hzfcz",
                "ResultTosLocation": {
                    "BucketName": "ark-auto-created-required-0123456789-cn-beijing",
                    "ObjectKey": "ark/ej-20240401114848-w5b8f/inference_result/results/"
                },
                "Status": {
                    "Phase": "Succeeded",
                    "PhaseTime": "2024-04-01T11:54:41Z",
                    "Message": "评测任务已成功完成"
                },
                "Tags": [
                    {
                        "Key": "owner",
                        "Value": "team-a"
                    }
                ],
                "ProjectName": "default",
                "CreateTime": "2024-04-01T11:48:48Z",
                "UpdateTime": "2024-04-01T11:54:41Z"
            }
        ]
    }
}
```