批量添加评测集条目 - BatchCreateOpsDatasetItems

功能介绍

该接口用于向指定评测集的草稿态批量注入数据行，支持增量添加、覆盖更新或基于历史版本还原数据，并强制校验数据与Schema的符合性。

适用场景：

数据初始化：在创建评测集后，通过API批量导入首批业务数据或基准测试集。
版本回滚：当前草稿数据出现异常时，通过指定源版本ID将评测集内容恢复至特定历史快照。

调用方法

请参见如何调用API。

授权信息

账号根用户具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备如下身份策略权限，更多的权限说明请参见权限和授权项。

授权项	访问级别	资源类型（*为必须）	条件键	别名	依赖的授权项
agentarts:dataset:batchCreateOpsDatasetItems	Write	dataset *	g:ResourceTag/<tag-key>	-	-

URI

POST /v1/ops/datasets/{dataset_id}/items

表1 路径参数
参数	是否必选	参数类型	描述
dataset_id	是	String	参数解释：评测集的唯一标识符（ID）。可通过调用创建评测集接口获取，或通过查询评测集列表接口获取。约束限制：不涉及。取值范围：由英文、数字、连字符(-)、下划线(_)组成的1~64个字符串。默认取值：不涉及。

表2 Query参数
参数	是否必选	参数类型	描述
source_version_id	否	String	参数解释：源版本ID。在执行版本还原或基于特定版本批量添加数据的场景下，指定作为数据来源的历史版本标识。约束限制：不涉及。取值范围：由英文字母、数字及连字符(-)、下划线(_)组成的0~100个字符的字符串。默认取值：不涉及。
overwrite	否	Boolean	参数解释：覆盖模式开关。用于控制在批量添加新条目之前，是否清空目标评测集（通常为草稿版）中的现有数据。约束限制：不涉及。取值范围： true: 覆盖模式，先清空后添加。 false: 追加模式，在现有数据基础上新增。默认取值： false。

请求参数

表3 请求Body参数
参数	是否必选	参数类型	描述
items	是	Array of OpsAddItemRequest objects	参数解释：待添加到评测集中的数据条目列表。数组内的元素为OpsAddItemRequest对象，参考OpsAddItemRequest结构定义。约束限制：数组长度1-1000。取值范围：不涉及。默认取值：不涉及。

表4 OpsAddItemRequest
参数	是否必选	参数类型	描述
turns	是	Array of OpsTurnInput objects	参数解释：构成该数据条目的交互轮次列表。对于单轮问答长度为1，多轮对话包含多个轮次。数组内的元素为OpsTurnInput对象，参考OpsTurnInput结构定义。约束限制：数组长度1-10000。取值范围：不涉及。默认取值：不涉及。

表5 OpsTurnInput
参数	是否必选	参数类型	描述
fields	是	Array of OpsFieldValueInput objects	参数解释：当前轮次中包含的具体数据字段（如Input、Output、Rationale 等）集合。列表元素为OpsFieldValueInput对象，参考OpsFieldValueInput结构定义。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。

表6 OpsFieldValueInput
参数	是否必选	参数类型	描述
key	否	String	参数解释：字段的键名，需与评测集Schema中定义的字段名保持一致。约束限制：不涉及。取值范围：需与评测集Schema中定义的字段名一致，长度为0~10000个字符。默认取值：不涉及。
type	否	String	参数解释：字段的数据存储类型，决定系统底层解析逻辑。约束限制：不涉及。取值范围： string：字符串类型 integer：整数类型 float：浮点数类型 boolean：布尔值类型 object：对象类型默认取值：不涉及。
content_type	否	String	参数解释：字段的内容表现形式，用于前端渲染或后端逻辑识别。约束限制：不涉及。取值范围： text：纯文本 markdown：Markdown格式文本 image_url：图片URL file_path：文件路径默认取值： text。
value	否	String	参数解释：字段承载的实际业务数据值。约束限制：不涉及。取值范围：根据type定义，需符合对应解析要求，长度为0~10000个字符。默认取值：不涉及。

响应参数

状态码：200

表7 响应Body参数
参数	参数类型	描述
item_ids	Array of strings	参数解释：系统为新创建的数据条目生成的唯一标识符列表。数组内的元素为String类型，符合数据库标识符规范的字符串。

请求示例

向评测集批量添加评测数据条目。此示例采用追加模式（overwrite=false），并根据Schema定义上传了两条数据。

POST https://api.example.com/v1/ops/datasets/097b0720-d6cc-48e0-ad15-5638bb6b1784/items?overwrite=false

{
  "items" : [ {
    "turns" : [ {
      "fields" : [ {
        "key" : "question",
        "type" : "string",
        "content_type" : "text",
        "value" : "如何更换汽车机油？"
      }, {
        "key" : "expected_answer",
        "type" : "string",
        "content_type" : "text",
        "value" : "1. 准备工具；2. 排出旧油；3. 更换滤清器；4. 加入新油。"
      } ]
    } ]
  }, {
    "turns" : [ {
      "fields" : [ {
        "key" : "question",
        "type" : "string",
        "content_type" : "text",
        "value" : "北京的天气怎么样？"
      }, {
        "key" : "expected_answer",
        "type" : "string",
        "content_type" : "text",
        "value" : "北京今日晴，气温 15°C到22°C。"
      } ]
    } ]
  } ]
}

响应示例

状态码：200

添加成功

{
  "item_ids" : [ "550e8400-e29b-41d4-a716-446655440021", "550e8400-e29b-41d4-a716-446655440022" ]
}

状态码

状态码	描述
200	添加成功

错误码

请参见错误码。

父主题： 评测集管理

上一篇：获取评测集条目列表 - ListOpsDatasetItems

下一篇：获取评测集条目详情 - ShowOpsDatasetItem