批量导入物品数据--全域AI搜索-火山引擎

文档中心

立即注册

导航

批量导入物品数据

最近更新时间：2025.12.17 00:05:00首次发布时间：2025.12.17 00:05:00

使用场景

在创建完成物品数据集后，您可能在以下场景下可能会遇到大批量导入数据的场景：

首次构建完整的测试/生产数据集，一次性批量导入全部商品、内容数据
定期更新数据中的某个字段，如大批量（超过10W条数据）的批量上/下架状态变更
新增数据集字段，批量写入全量商品、内容数据的新增字段值

在此类场景下，如果每次要更新的数据量级过万级，实时写入接口可能无法满足您的需求，您可以使用批量导入物品数据的接口流程来实现这个操作。
当前批式导入数据仅支持物品数据集，支持以下数据操作：

批量导入新数据：适用于创建数据集后，批量导入全量候选数据。物品数据使用JSON Object列表形式上传。上传的数据 schema 必须遵循您在控制台创建数据集时定义的 schema。
批量更新数据：通过重复上传物品数据（传入的数据唯一标识已存在于数据集中）则触发数据更新，最新上传的数据将覆盖已有的数据。如果您只需要更新一批数据中的某几个字段，则每条数据仅需要上传物品数据的id和待更新字段。

适用数据集类型

数据集类型	是否支持批量导入
图文物品数据集	✅
视频物品数据集	✅
文档数据集	❌ 暂不支持

批量导入流程介绍

使用以下接口组来完成批量导入的操作：

接口鉴权：API鉴权机制说明
创建批量导入任务：CreateBatchImport - 创建批量导入任务
批量导入数据：BatchImport - 批量导入数据
完成批量导入任务：CompleteBatchImportTask - 结束批量导入
查询批量导入任务状态；GetBatchImportStatus - 查询导入状态

Step 1：创建批量导入任务

在数据集路径下调用create_batch_import接口，创建一个批式导入任务。接口详情请查看：CreateBatchImport - 创建批量导入任务
可上传estimated_count 传入预计导入的数据量，可在查询状态时返回用于对照：

curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/dataset/{dataset_id}/create_batch_import \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API Key>' \
  -d '{
    "estimated_count":1500000
}'

dataset_id：其中路径中需要传入目标导入的数据集ID
API Key：您可以根据鉴权机制的操作流程创建一个可用的API Key

接口将返回这个导入任务对应的batch_id，可以使用batch_id继续调用后续的批量上传和状态查询。
返回示例：

{
    "request_id": "a8207cf1-2230-9f9b-a819-324b5b325c19",
    "result": {
        "batch_id": "a8fd2b826203421bb977",
        "status": "initialized",
        "expired_time": "2025-12-17T21:15:59+08:00"
    }
}

Step 2：上传批量数据

您可以多次调用batch_import接口，传入batch_id和批量数据。接口详情请查看：BatchImport - 批量导入数据

图文数据集

视频数据集

图文数据集批量上传示例：

curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/dataset/{dataset_id}/batch_import'   -H 'Content-Type: application/json'   -H 'Authorization: Bearer <API Key>'   -d '{
    "batch_id":"a8fd2b826203421bb977",
    "fields": [
                {
                    "item_id": "WSHOE001",
                    "title": "舒适通勤 尖头浅口高跟鞋 - 黑色",
                    "category": "女士高跟鞋",
                    "status": 1,
                    "images": [
                        {
                            "image_url": "https://example.com/images/womens_pump_black.jpg"
                        }
                    ]
                },
                {
                    "item_id": "WSHOE002",
                    "title": "轻便网面 跑步运动鞋 - 粉色拼灰色",
                    "category": "女士运动鞋",
                    "status": 1,
                    "images": [
                        {
                            "image_url": "https://example.com/images/womens_sneaker_pink.jpg"
                        }
                    ]
                }
            ]
}'

视频数据集批量上传示例：

curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/dataset/142460036/batch_import'   -H 'Content-Type: application/json'   -H 'Authorization: <火山鉴权的一系列相关header>'   -d '{
    "fields": [
                {
                    "content_id": "video_900026",
                    "content_type": "video",
                    "parent_content_id": "collection_342534",
                    "sequence_index": 26,
                    "video_url": [
                        "http://xxxx.mp4"
                    ],
                    "my_title": "三体第二十六集"
                },
                {
                    "content_id": "video_900027",
                    "content_type": "video",
                    "parent_content_id": "collection_342534",
                    "sequence_index": 27,
                    "video_url": [
                        "http://xxxx.mp4"
                    ],
                    "my_title": "三体第二十七集"
                }
    ]
}'

每次接口请求可以在接口请求体大小不超过10MB的限制前提下，使用Array of Object传入多个物品数据对象。上传的所有对象将在同一个批量上传任务中完成导入。例如您可以使用同一个batch_id在同一个物品数据集下，每次上传5000条物品数据对象，调用接口100次直到50W条数据上传完毕。
每次接口调用将返回本次上传的数据条数和当前批次下累积上传的数据条数：

{
    "request_id": "41feb961-6b21-94e0-ba4e-c063aaff0784",
    "result": {
        "batch_id": "a8fd2b826203421bb977",
        "accepted_count": 2,
        "total_received": 2,
        "status": "processing",
        "expired_time": "2025-12-17T21:15:59+08:00"
    }
}

Step 3：确认批量上传完成

在完成上传全量数据后，调用complete_batch_import_task接口指示上传完成，系统将启动这批数据的入库和解析、处理。接口详情请查看CompleteBatchImportTask - 结束批量导入。

注意

在不调用complete接口的情况下，系统将不会启动数据的入库和解析处理流程，上传的数据将保持上传中（processing）状态。任务超时后这批数据将会被丢弃，不会进行入库和处理。

curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/dataset/142460036/complete_batch_imports_task \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API Key>' \
  -d '{
    "batch_id":"a8fd2b826203421bb977"
}'

接口将返回上传任务的最终状态"complete"

{
    "request_id": "c7e10e6a-9764-9ada-b361-6aa642c76514",
    "result": {
        "batch_id": "a8fd2b826203421bb977",
        "status": "completed"
    }
}

查询批量上传的任务状态

您可以在导入过程中随时调用get_batch_import_status接口查询当前任务的状态和导入的数据量。接口详情请查看GetBatchImportStatus - 查询导入状态。

curl -X GET 'https://aisearch.cn-beijing.volces.com/api/v1/dataset/142460036/batch_import_status \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API Key>' \
  -d '{
    "batch_id":"6c0001b0-f696-4bfc-acda-a2ee05170485"
}'

接口将返回任务的当前状态和累积导入的数据条数：

{
    "request_id": "346c59cc-0c28-945e-b504-92d2a45cc2b7",
    "result": {
        "batch_id": "a8fd2b826203421bb977",
        "status": "completed",
        "total_received": 2,
        "expired_time": "2025-12-17T21:15:59+08:00"
    }
}