文档中心

Viking AI 搜索

数据API

Write - 实时导入/更新数据

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 若您有短时间大批量上传、更新物品数据的诉求，请使用批量导入数据接口。查看批量导入物品数据
行为数据集	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	必选	[ { "item_id": "WSHOE001", "title": "舒适通勤尖头浅口高跟鞋 - 黑色", "category": "女士高跟鞋", "status": 1, "images": [ { "image_url": "https://example.com/images/womens_pump_black.jpg" } ] } ]	需要写入数据集的数据内容，输入 Array，Array 中每个元素为一条数据。

上传图片文件

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

传入图片需要满足以下条件：

支持格式：jpeg、png、 webp、bmp、tiff、icns。其中，tiff、icns 格式图片，需要保证和元数据对齐，如在对象存储中正确设置文件元数据，否则会解析失败。

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

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

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

使用URL链接上传：请确保您的URL链接保持公开可访问，如果您的链接有访问限制，请对 aisearch.cn-beijing.volces.com 域名开放访问的白名单。

使用Base64编码的图片文件上传：请确保Base64编码符合标准格式，包含数据头（Data URI Scheme）与 Base64 编码正文两部分：

格式

JPEG 图片

PNG 图片

WebP 图片

组成部分	格式要求	说明
数据头前缀	固定为 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<String>）上传单个视频的url列表（支持多个视频片段拼接为1个视频）。视频的上传格式和要求如下：

视频格式和要求说明

在导入视频下载链接前，请确保这些视频的下载 URL 能够被火山引擎的官方接口域名访问。不支持通过上传任意网页链接来爬取网页上的视频。

在上传前，请确保列表内所有视频文件的总大小不超过 10GB，总时长不超过 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" } ]	需要写入数据集的数据内容，输入 Array，Array 中每个元素为一条数据。行为发生时间戳必须是 UNIX 毫秒时间戳注意每一条行为数据必须要有：用户 ID、物品 ID、行为类型、行为发生时间、行为发生场景。如果缺失必须字段，下游数据处理会自动忽略无效行为数据

响应参数

请求响应

参数	类型	示例值	描述
request_id	String	25ee998a-5462-9385-9f18-035f1da7a6e5	用于唯一标识一次请求，可根据 request_id 快速定位一次请求的执行。

请求示例

图文数据集

视频数据集

用户行为数据集

图文数据集请求示例

响应示例

错误处理

错误码

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	行为数据实时写入超过流量限制

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

说明

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

最近更新时间：2026.08.09 01:06:39

这个页面对您有帮助吗？

有用

无用