You need to enable JavaScript to run this app.
导航
全域AI搜索
  • 文档首页
    • /全域AI搜索/AI搜索引擎用户手册/API参考/数据API/Write - 实时导入/更新数据
Write - 实时导入/更新数据
最近更新时间：2025.12.17 00:04:59首次发布时间：2025.04.24 20:27:18
复制全文
我的收藏
有用
有用
无用
无用

调用本接口，可将物品和行为数据数据实时写入指定的数据集中。

通过这个接口，用户能写入物品数据集和用户行为数据集：

  • 物品数据集：​存储 AI 搜索引擎中被搜索的对象数据，为结构化数据，使用JSON Object列表形式上传。上传的数据 schema 必须遵循您在控制台创建数据集时定义的 schema。
  • 用户行为数据集： 存储用户的历史和增量行为数据，为结构化数据，使用JSON Object列表形式上传。上传的数据schema 必须遵循您在控制台创建数据集时定义的 schema。

通过这个接口，您也能更新数据集内的数据：

  • 物品数据集： 通过重复上传物品数据（传入的数据唯一标识已存在于数据集中）则触发数据更新，最新上传的数据将覆盖已有的数据。
  • 用户行为数据集：不支持更新历史行为数据。

注意事项

  • 使用限制：
    • 受到 HTTP Body 大小限制，单次请求的包体大小最大不超过 10MB。
  • 导入限速：为保障数据实时导入和处理的稳定性，我们对实时数据导入设置了限速逻辑，具体逻辑如下：

数据集类型

限速逻辑

超出限速提示

物品数据集

2000 条/分钟

1分钟内传入超过2000条数据，返回429状态码，接口返回限流错误码WriteDataLimitExceeded
若您有短时间大批量上传、更新物品数据的诉求，请使用 批量导入数据 接口。

行为数据集

60000 条/分钟

1分钟内传入超过60000条数据，返回429状态码，接口返回限流错误码WriteDataLimitExceeded
行为数据暂不支持批量导入接口，若您的行为数据实时导入速率超出限流阈值，请与我们取得联系。

请求说明

{dataset_id}：在控制台创建数据集后系统指定的数据集唯一标识，可在控制台查看。

请求参数

图文数据集请求体

参数

类型

是否必选

示例值

描述

fields

Array of Object

是

图文数据：

［
    {
        "item_id": "WSHOE001",
         "title": "舒适通勤 尖头浅口高跟鞋 - 黑色",
         "category": "女士高跟鞋",
         "status": 1,
         "images": [
         {
             "image_url": "https://example.com/images/womens_pump_black.jpg"
          }
         ]
     }
］

需要写入数据集的数据内容，输入 Array，Array 中每个元素为一条数据。

上传图片文件

上传数据时，请根据您已经在数据集中定义的字段类型来上传图片文件数据。您必须上传符合以下说明中格式和限制的图片文件，AI 搜索引擎才可以对图片进行处理并索引：

说明

  1. 支持格式：​jpeg、png、 webp、bmp、tiff、ico、dib、icns、sgi、jpeg2000。其中，tiff、sgi、icns、jpeg2000 格式图片，需要保证和元数据对齐，如在对象存储中正确设置文件元数据，否则会解析失败。
  2. 宽高比（宽/高）：​在范围[1/100, 100] 。
  3. 边长： [10, 6000] px，即短边像素需大于 10 px，长边像素需小于6000 px。

您可以按照您在数据集配置中的属性定义，上传可公开访问的URL链接或使用Base64编码直接上传图片文件：

  1. 使用URL链接上传：​请确保您的URL链接保持公开可访问，如果您的链接有访问限制，请对 aisearch.cn-beijing.volces.com 域名开放访问的白名单。
  2. 使用Base64编码的图片文件上传：​请确保Base64编码符合标准格式，包含数据头（Data URI Scheme）​与 Base64 编码正文两部分：
data:<MIME类型>;base64,<Base64编码字符串>

组成部分

格式要求

说明

数据头前缀

固定为 data:

标识该字符串为 Data URI 格式，不可省略或修改

MIME 类型

需与图片实际格式严格匹配

用于服务端识别图片类型，禁止随意填写（如 JPG 图填 PNG 的 MIME）

分隔符

固定为 ;base64,

连接 MIME 类型与 Base64 编码正文，分号、“base64”、逗号均不可省略或替换

Base64 编码正文

符合 RFC 4648 标准的 Base64 编码字符串

由图片文件二进制数据直接编码生成，禁止包含空格、换行符、特殊字符，需为连续的 ASCII 字符串

视频数据集请求体

参数

类型

是否必选

示例值

描述

fields

Array of Object

是

[
    {
        "content_id": "video_900026",
        "content_type": "video",
        "parent_content_id": "collection_342534",
        "sequence_index": 26,
        "video_url": [
            "http://xxxx.mp4"
        ],
        "my_title": "三体第二十六集"
    }
]

需要写入数据集的数据内容，输入 Array，Array 中每个元素为一条数据。

上传视频文件

上传数据时，请根据您已经在数据集中定义的字段类型来上传视频数据。在视频数据集中需要使用video_url（Array）上传单个视频的url列表（支持多个视频片段拼接为1个视频）。视频的上传格式和要求如下：

说明

  1. 在导入视频下载链接前，请确保这些视频的下载 URL 能够被火山引擎的官方接口域名访问。不支持通过上传任意网页链接来爬取网页上的视频。
  2. 在上传前，请确保列表内所有视频文件的总大小不超过 10GB，总时长不超过 3 小时。
  3. 支持上传以下格式的视频文件：
    mp4、flv、asf、rm、rmvb、mpeg、mov、avi、mpegts、m4s、m3u8、matroska、wmv、3gp、ts、mpg、webm、mkv、wm、asx、ram、mpe、vob、dat、mp4v、m4v、f4v、mxf、qt

用户行为数据集请求体

参数

类型

是否必选

示例值

描述

fields

Array of Object

是

[
    {
        "user_id": "user134",
        "item_id": "1235",
        "event_type": "曝光",
        "event_timestamp": 1678886400000,
        "event_scene": "home"
    }
]
  1. 需要写入数据集的数据内容，输入 Array，Array 中每个元素为一条数据。

注意

每一条行为数据必须要有： 用户 ID、物品 ID、行为类型、行为发生时间、行为发生场景。如果缺失必须字段，下游数据处理会自动忽略无效行为数据

响应参数

请求响应

参数

类型

示例值

描述

request_id

String

25ee998a-5462-9385-9f18-035f1da7a6e5

用于唯一标识一次请求，可根据 request_id 快速定位一次请求的执行。

请求示例

图文数据集请求示例

curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/dataset/142460036/write'   -H 'Content-Type: application/json'   -H 'Authorization: <火山鉴权的一系列相关header>'   -d '{
    "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"
                }
            ]
        }
    ]
}'

响应示例

{
    "request_id": "25ee998a-5462-9385-9f18-035f1da7a6e5"
}

错误处理

错误码

HTTP 状态码

错误码

错误信息

含义

429

WriteDataLimitExceeded

The specified data write limit has been exceeded: items per minute

物品数据实时写入超过流量限制

429

WriteDataLimitExceeded

The specified data write limit has been exceeded: events per minute

行为数据实时写入超过流量限制

其他公共错误码请参见公共错误码文档。