说明

Viking AI 搜索是一款基于生成式 AI 的企业级 AI 搜索产品，基于大模型的多模态语义表征和理解能力，结合字节跳动信息检索领域多年最佳实践，为客户提供开箱即用的 AI 搜索搭建平台服务，帮助客户轻松搭建和集成端到端的多模态图文搜索和推荐能力。

*

想要体验更多 Viking AI 搜索能力，点击前往：Viking AI 搜索引擎，企业搜推问一体化智能引擎

调用本接口，可将物品和行为数据数据**实时**写入指定的数据集中，并立即开始数据处理和索引。通过这个接口，用户能写入物品数据集和用户行为数据集： * **物品数据集：** 存储 AI 搜索引擎中被搜索的对象数据，为结构化数据，使用JSON Object列表形式上传。上传的数据 schema 必须遵循您在控制台创建物品数据集时定义的 schema。 * **用户行为数据集**：存储用户的历史和增量行为数据，为结构化数据，使用JSON Object列表形式上传。上传的数据schema 必须遵循您在控制台创建行为数据集时定义的 schema。通过这个接口，您也能更新数据集内的数据： * **物品数据集： ** 通过重复上传物品数据（传入的数据唯一标识已存在于数据集中）则触发数据更新，最新上传的数据将覆盖已有的数据。 * **用户行为数据集**：不支持更新历史行为数据。 ## 注意事项 * **使用限制：** * 受到 HTTP Body 大小限制，单次请求的包体大小最大不超过 10MB。 * **导入限速：为保障数据**实时导入和处理的稳定性，我们对实时数据导入设置了限速逻辑，具体逻辑如下： |**数据集类型** |**限速逻辑** |**超出限速提示** | |---|---|---| |物品数据集 |2,000 条/分钟 |1分钟内传入超过2000条数据，返回429状态码，接口返回限流错误码WriteDataLimitExceeded

若您有短时间大批量上传、更新物品数据的诉求，请使用批量导入数据接口。查看 [批量导入物品数据](https://www.volcengine.com/docs/85296/2123240) | |行为数据集 |500,000 条/分钟 |1分钟内传入超过500,000条数据，返回429状态码，接口返回限流错误码WriteDataLimitExceeded

行为数据暂不支持批量导入接口，若您的行为数据实时导入速率超出限流阈值，可与我们取得联系。 | ## 请求说明 * 请求方式：POST * 请求地址： |**服务** |**区域** |**URL** | |---|---|---| |火山引擎 |华北(北京) |`https://aisearch.cn-beijing.volces.com/api/v1/dataset/{dataset_id}/write` | |火山引擎 |东南亚(柔佛) |`https://aisearch.ap-southeast-1.volces.com/api/v1/dataset/{dataset_id}/write` | |BytePlus |东南亚(柔佛) |`https://aisearch.ap-southeast-1.bytepluses.com/api/v1/dataset/{dataset_id}/write` | *{dataset_id}* *：在控制台创建数据集后系统指定的数据集唯一标识，可在控制台查看。* ## 请求参数 ### 图文数据集请求体 |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |fields |Array of Object |必选 |

```JSON```
```［```
``` { ```
``` "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、icns。其中，tiff、icns 格式图片，需要保证和元数据对齐，如在对象存储中正确设置文件元数据，否则会解析失败。

2.

宽高比（宽/高）：在范围[1/100, 100] 。

3.

边长： [10, 6000] px，即短边像素需大于 10 px，长边像素需小于6000 px。

您可以按照您在数据集配置中的属性定义，上传可公开访问的URL链接或使用Base64编码直接上传图片文件： 1. **使用URL链接上传：** 请确保您的URL链接保持公开可访问，如果您的链接有访问限制，请对 [aisearch.cn-beijing.volces.com](http://aisearch.cn-beijing.volces.com/) 域名开放访问的白名单。 2. **使用Base64编码的图片文件上传：** 请确保Base64编码符合标准格式，包含**数据头（Data URI Scheme）** 与 **Base64 编码正文**两部分：格式 ```JSON data:;base64, ``` JPEG 图片 ```JSON data:image/jpeg;base64, ``` PNG 图片 ```JSON data:image/png;base64, ``` WebP 图片 ```JSON data:image/webp;base64, ``` |**组成部分** |**格式要求** |**说明** | |---|---|---| |数据头前缀 |固定为 `data:` |标识该字符串为 Data URI 格式，不可省略或修改 | |MIME 类型 |需与图片实际格式严格匹配 |用于服务端识别图片类型，禁止随意填写（如 JPG 图填 PNG 的 MIME） | |分隔符 |固定为 `;base64,` |连接 MIME 类型与 Base64 编码正文，分号、“base64”、逗号均不可省略或替换 | |Base64 编码正文 |符合 RFC 4648 标准的 Base64 编码字符串 |由图片文件二进制数据直接编码生成，**禁止包含空格、换行符、特殊字符**，需为连续的 ASCII 字符串 | ### 视频数据集请求体 |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |fields |Array of Object |必选 |```JSON```
```[```
``` {```
``` "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 |必选 |```JSON```
```[```
``` {```
``` "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 快速定位一次请求的执行。 | ## 请求示例图文数据集 ### 图文数据集请求示例 ```JSON curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/dataset/142460036/write' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer <火山鉴权的一系列相关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" } ] } ] }' ``` 视频数据集 ### 视频数据集请求示例 ```JSON curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/dataset/142460036/write' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer <火山鉴权的一系列相关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": "三体第二十七集" } ] }' ``` 用户行为数据集 ### 用户行为数据集请求示例 ```JSON curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/dataset/142460036/write' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer <火山鉴权的一系列相关header>' \ -d '{ "fields": [ { "user_id": "user134", "item_id": "1235", "event_type": "曝光", "event_timestamp": 1678886400000, "event_scene": "home" }, { "user_id": "user134", "item_id": "1235", "event_type": "点击", "event_timestamp": 1678886400300, "event_scene": "home" } ] }' ``` ## 响应示例 ```Plain Text { "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 |行为数据实时写入超过流量限制 | 其他公共错误码请参见[公共错误码](https://www.volcengine.com/docs/85296/1544941)文档。

说明

想要体验更多 Viking AI 搜索能力，点击前往：Viking AI 搜索引擎，企业搜推问一体化智能引擎