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

BrowseIndex 接口主要用于需要批量获取、展示或导出索引数据的场景，尤其适用于不依赖关键词搜索（即无 query 输入）的情况。它允许您通过设置过滤、排序和分页条件，来精确地访问和消费索引中的物品。

您可以使用此接口来浏览、查询应用下关联的，已生效索引的数据集中的数据：

注意事项

使用范围：

仅可用于【物品数据集】类型的数据集，文档数据集和用户行为数据集不支持使用浏览接口获取

请求体限制：

受到HTTP Body大小限制，单次请求的包体大小最大不超过10MB。

物品量级限制：

单个索引（在应用中关联的数据集）仅可最多翻页查询 1 万条数据。

请求说明

请求方式：POST

请求地址：

服务	区域	URL
火山引擎	华北(北京)	https://aisearch.cn-beijing.volces.com/api/v1/application/{application_id}/browse_index
火山引擎	东南亚(柔佛)	https://aisearch.ap-southeast-1.volces.com/api/v1/application/{application_id}/browse_index
BytePlus	东南亚(柔佛)	https://aisearch.ap-southeast-1.bytepluses.com/api/v1/application/{application_id}/browse_index

{application_id}：在控制台创建应用后系统指定的应用唯一标识，可在控制台查看

接口限流

每租户调用限流：20QPS。

超过接口限流的调用频率，将返回 429 状态码。

鉴权方式

可使用API Key或Access Key鉴权，详情参考API 鉴权机制说明

请求参数

Path 参数

参数	类型	是否必选	示例	描述
application_id	String	必选	76414365027	您的应用唯一标识符。

Body 参数

参数	类型	是否必选	示例	描述
dataset_id	String	必选	"14365027"	数据集的唯一 ID。您可以在平台的“数据集管理”页面找到此 ID。每次请求都必须明确指定要浏览的数据集。
page_number	Integer	必选	1	分页页码，用于获取指定页的数据。该值从 1 开始计算。
page_size	Integer	必选	20	每页返回的物品数量。默认值为 10，最大值 1000，最小值 1
filter	Filter结构	可选	参考请求示例	搜索过滤条件对象。您可以使用在数据源中已配置为“可筛选”的字段来过滤结果。关于 Filter 对象的详细结构和用法，请参考相关文档。
sort_by	String	可选	metrics.score	用于排序的字段名称。该字段必须存在于数据集中，且在应用中已勾选“用于过滤”，支持以下类型：基础类型：int32, int64, float, bool, string 复杂类型：对于 object 类型的字段的子层级字段的排序，请使用 . 连接符引用其内部字段，格式为 object.field，例如 product.price。
sort_order	String	可选	desc	排序顺序。支持以下枚举值： desc：降序（默认值） asc：升序
output_fields	Array<String>	可选	["item_id", "title", "image_url"]	指定在响应的 display_fields 中需要返回哪些字段。如果留空或不传此参数，将默认返回数据源中的所有字段。注意：对于嵌套对象（如 object 或 array<object>），目前仅支持传入顶层字段名。传入不存在的字段或嵌套对象内部的字段将被忽略。
facet	Facet	可选	见下方数据结构：Facet	用于指定结果分类统计字段，以及分类筛选条件，可根据指定的字段条件对接口返回结果进行分类筛选过滤。默认值为空，即不对任何分类统计或者分类筛选过滤。

Filter结构

参数	类型	是否必选	示例值	描述
op	string	是	"must"	算子类型，支持: "must"、"must_not"、"range"、"and"、"or" 算子使用方式详见下方：Filter算子说明
field	string	条件必选	"status"	需要应用过滤条件的字段。 "must"、"must_not"、"range" 算子必填。 "and"、"or"算子忽略该参数。
gte	Float	否	100.0	"range" 算子的过滤范围，语义为过滤"field"字段值大于等于指定值的数据。
gt	Float	否	100.0	"range" 算子的过滤范围，语义为过滤"field"字段值大于指定值的数据。
lte	Float	否	500.0	"range" 算子的过滤范围，语义为过滤"field"字段值小于等于指定值的数据。
lt	Float	否	500.0	"range" 算子的过滤范围，语义为过滤"field"字段值小于指定值的数据。
conds	array	条件必选	见下方示例	除 "range" 算子之外，其余算子均需指定conds条件。 "must"、"must_not"算子需要指定过滤值的集合。 "and"、"or" 算子需要指定嵌套的过滤条件。

Filter算子说明

算子	被过滤字段（field）类型	算子含义说明	示例
must	int32 int64 string Bool array(int32) array(int64) array(string)	条件表达式参数写法： op：传入"must" field：传入过滤目标字段 conds：传入过滤值列表，列表元素需与field中的类型相同当field为整数、字符串的单个元素，含义为“属于”，即“字段中的值属于传入的过滤列表”。当field为整数、字符串列表，含义为“有交集”，即“目标字段和过滤列表中的元素有重叠”	示例一：地区必须属于"cn"或"sg"其中之一 { "op": "must", "field": "region", "conds": ["cn", "sg"] } 示例二：status值必须属于1,2,3其中之一 { "op": "must", "field": "status", "conds": [1, 2, 3] }
must_not	int32 int64 string Bool array(int32) array(int64) array(string)	条件表达式参数写法： op：传入"must_not" field：传入过滤目标字段 conds：传入过滤值列表，列表元素需与field中的类型相同当field为整数、字符串的单个元素，含义为“不属于”，即“目标字段值不在过滤列表中” 当field为整数、字符串列表，其含义为“没有交集”，即“目标字段和过滤列表中的元素不重叠”	status值必须不能为1,2,3其中任何一个 { "op": "must_not", "field": "status", "conds": [1, 2, 3] }
range	int32 int64 Float	条件表达式参数写法： op：传入"range" field：传入过滤目标字段 gt：大于 gte：大于等于（对整数有效） lt：小于 lte：小于等于（对整数有效）含义为目标数值字段值必须在指定范围内。配置使用gte（大于等于）, gt（大于）, lte（小于等于）, lt（小于），用以圈选数值范围。	price >= 100.0 { "op": "range", "field": "price", "gte": 100.0 } price 在100.0到500.0之间 { "op": "range", "field": "price", "gte": 100.0, "lt": 500.0 }
time_range	被过滤字段需要上传标注为“上新时间”属性的字段，支持： int64：UNIX时间戳 string：ISO8601时间格式；或"YYYY-Mm-DD hh:mm:ss.sss"格式详情见检查预留字段属性	条件表达式参数写法： op：传入"time_range" field：传入过滤目标字段 gt：晚于 lt：早于目标过滤字段必须满足在一个时间段内。gt 和 lt 传入值支持：绝对时间条件（固定时间段）：使用精确到毫秒的UNIX时间戳传入（int）相对时间条件（以请求时间为参考点的相对时间段）：使用表达式 "now[+/-][数值][d/h/m/s]"以字符串的形式传入。相对时间表达式示例： now+2d：距当前时间2天以后的时间点 now-24h：距当前时间24小时之前的时间点	发布时间在2026年之后 { "op": "time_range", "field": "publish_time", "gt": 1767196800000, } 发布时间在最近前一个月内 { "op": "time_range", "field": "publish_time", "gt": "now-30d", }
and	不涉及	逻辑算子，针对逻辑查询需求，对多个条件取交集。	{ "op": "and", "conds": [ // 条件列表，支持嵌套and/or/must/must_not/range 算子 { "op": "must", "field": "status", "conds": [1, 2, 3] }, { ... // 支持>=1的任意数量的条件进行组合 } ] }
or	不涉及	逻辑算子，针对逻辑查询需求，对多个条件取并集。	{ "op": "or", "conds": [ // 条件列表，支持嵌套and/or/must/must_not/range 算子 { "op": "must", "field": "status", "conds": [1, 2, 3] }, { ... // 支持>=1的任意数量的条件进行组合 } ] }

Facet

参数	类型	是否必选	示例值	描述
facets	Array <facets>	否	"facets": [ { "field": "tags", // 指定字符串类型字段用于分类聚合统计 "max_facet_buckets": 10 // 取统计值最大的N个，默认10，[1, 50] }, { "field": "price", // 指定数值类型字段用于分类聚合统计 "number_ranges": [ { "gte": 0, "lt": 19},{ "gte": 10, "lt": 100},{"gte": 200, "lt": 999} // 可自定义数值区间 ] } ]	传入 facets 对象，指定针对接口结果进行聚合统计的维度字段、数值区间、最多返回多少个枚举值等。未传入时，默认为空，即不做任何分类统计。参数详情可查看：facets
facet_filter	facet_filter	否	"facet_filter":{ { "op": "must", "field": "region", "conds": ["cn", "sg"] }, { "op": "must_not", "field": "status", "conds": [1, 2, 3] } }	该参数用于指定当前请求的分类筛选条件。未传入时，默认当前搜索请求不进行分类筛选过滤，展示初始的搜索结果。协议同 Filter，参考：

facets

参数	类型	是否必选	示例值	描述
facets	Array <facets>	否	"facets": [ { "field": "tags", // 指定字符串类型字段用于分类聚合统计 "max_facet_buckets": 10 // 取统计值最大的N个，默认10，[1, 50] }, { "field": "price", // 指定数值类型字段用于分类聚合统计 "number_ranges": [ { "gte": 0, "lt": 19},{ "gte": 10, "lt": 100},{"gte": 200, "lt": 999} // 可自定义数值区间 ] } ]	传入 facets 对象，指定针对结果进行聚合统计的维度字段、数值区间、最多返回多少个枚举值等。未传入时，默认为空，即不做任何分类统计。参数详情可查看：facets
facet_filter	facet_filter	否	"facet_filter":{ { "op": "must", "field": "region", "conds": ["cn", "sg"] }, { "op": "must_not", "field": "status", "conds": [1, 2, 3] } }	该参数用于指定当前请求的分类筛选条件。未传入时，默认当前请求不进行分类筛选过滤，展示初始的搜索结果。协议同 Filter，参考：

响应结构

响应体为一个 JSON 对象，包含请求的唯一 ID 和结果数据。

参数	类型	描述
request_id	String	唯一标识本次请求的 ID。在排查问题时，可使用此 ID 快速定位请求日志。
result	Object	请求成功时返回的结果对象。详细结构见下文。

Result 对象

参数	类型	描述
result	Object	包含内容的对象
total_items	Integer	满足当前过滤条件的总物品数量。
items	Array<Object>	本次分页返回的物品列表。这是一个对象数组，每个对象代表一个物品。

Item 对象

items 数组中的每个对象代表一个独立的物品，其结构如下：

参数	类型	描述
_id	String	物品在数据存储中的主键，通常源自您上传数据时标记为“唯一标识”的字段值。
display_fields	Object	包含物品其他字段的键值对集合。返回哪些字段由请求参数 output_fields 控制。如果 output_fields 未指定，则返回所有字段。

示例

请求示例

以下示例演示了如何请求一个应用下关联的商用图片素材库数据集（dataset_id）中，筛选出 tag 为 "户外" 且 quality_score 大于等于 80 的素材，并按 upload_timestamp 降序排序，获取第一页的 200 条数据。

响应示例（成功）

错误码

HTTP 状态码	错误码	错误信息	含义
400	MissingParameter	The request is missing the following parameter: {parameters}	请求参数缺失错误，如未传入必填参数。
400	InvalidParameter	A parameter in the request is not valid: {parameters}	参数不合法，如参数类型错误、长度不合法、枚举值不合法、不满足正则规则等。
400	InvalidRequestFormat	The request cannot be parsed in JSON format.	请求体解析失败，通常是请求体格式异常，是非法的 json 格式或与请求定义的结构不符。请参考对应的 API 文档检查请求结构。
400	InvalidAction	The specified action is invalid: {Action}	当请求路径中的 Action 不存在或暂时无法请求： browse_index：无法进行数据集索引浏览，可能是关联数据集后索引未生效，或应用中没有关联对应dataset_id的数据集

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