搜索查询 V2-RunSearch

project_id

是

String

参数解释：

用户的项目ID。获取方法请参见获取项目ID和名称。

约束限制：

不涉及。

取值范围：

只能由英文字母和数字组成，且长度为[1-64]个字符。

默认取值：

不涉及。

service_name

是

String

参数解释：

服务实例的名称，用户创建服务实例时设置的实例名称。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

search_type

是

String

参数解释：

搜索类型，必须为服务实例支持的搜索类型，服务实例的搜索类型列表可在创建服务实例时进行配置。

注意：可以使用枚举名或者枚举值（例如IMAGE/0），枚举值可能会变动，建议使用枚举名。

约束限制：

不涉及。

取值范围：

• IMAGE
• KEYWORD
• TEXT
• CATEGORY

默认取值：

不涉及。

limit

否

Integer

参数解释：

返回搜索结果的数量。

约束限制：

不涉及。

取值范围：

取值范围为[1, 1000]。

默认取值：

默认为10。

offset

否

Integer

参数解释：

返回搜索结果的偏移量，即返回序号在[offset, offset+limit]内的搜索结果。

约束限制：

• 默认情况下，搜索要求offset+limit <= 1000。
• 针对支持全量召回的场景，使用全量召回时要求offset必须为0。

取值范围：

取值范围为[0, N]。

默认取值：

默认为0。

last_item

否

SearchAfterParam object

参数解释：

前一次搜索的最后一个搜索结果的排序信息。仅对全量召回场景生效，可将上一次搜索返回结果中的last_item字段直接用于此处。

约束限制：

• 目前仅有KEYWORD支持全量召回。
• 使用全量召回时，offset必须为0。

取值范围：

不涉及。

默认取值：

不涉及。

min_score

否

Double

参数解释：

返回搜索结果的最小得分，用于对搜索结果进行score过滤。

约束限制：

目前仅对IMAGE/CATEGORY搜索类型生效。

取值范围：

取值范围为[0, 1]。

默认取值：

不涉及。

custom_tags

否

Map<String,Array<String>>

参数解释：

自定义字符标签，用于对搜索结果进行条件过滤。格式为键值对{key:value}。

约束限制：

• key: 必须为服务实例custom_tags中已存在的key，可在创建服务实例时进行配置，或在更新服务实例时进行新增。
• value: 标签值列表，列表内多个标签值为“或”关系，即满足一个即可。

取值范围：

value: 列表长度范围为[1, 32]，标签值类型为字符串，字符长度范围为[1, 64]。

默认取值：

不涉及。

custom_num_tags

否

Map<String,RangeParam>

参数解释：

自定义数值标签，用于对搜索结果进行条件过滤。格式为键值对{key:value}。

约束限制：

• key: 必须为服务实例custom_num_tags中已存在的key，可在创建服务实例时进行配置，或在更新服务实例时进行新增。针对没有设置该数值标签的数据，会直接过滤。
• value: 标签值的取值范围，标签值在给定的取值范围内即视为符合条件。

取值范围：

不涉及。

默认取值：

不涉及。

image_base64

否

String

参数解释：

图像文件的base64字符串，基于图像搜索时，与image_url二选一。

约束限制：

• 目前仅支持JPEG/JPG/PNG/BMP/WEBP格式的图像。
• 图像文件大小要求不超过5M。
• 图片中不能包含旋转信息。

取值范围：

默认情况下，要求图像的最短边大于64px，最长边小于4096px。部分服务类型有特殊要求，可参见服务类型说明。

默认取值：

不涉及。

image_url

否

String

参数解释：

图片的URL路径，目前支持公网http:/https url，图像入库时，与image_base64二选一。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

keywords

否

Array of strings

参数解释：

关键词列表。

约束限制：

使用KEYWORD搜索类型进行搜索时，必须提供该参数。

取值范围：

搜索时关键词数量范围为[1, 10]，关键词字符长度范围为[1, 64]。

默认取值：

不涉及。

text

否

String

参数解释：

文本字符串。

约束限制：

不涉及。

取值范围：

字符长度范围为[1, 512]。

默认取值：

不涉及。

optional_params

否

SearchOptionalParam object

参数解释：

搜索的可选参数，其中每个参数仅对部分服务类型生效，具体可参见服务类型说明。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

score

否

Double

参数解释：

搜索结果的相似度。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

id

否

String

参数解释：

搜索结果的唯一ID。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

from

否

Double

参数解释：

自定义数值标签数值下界，默认包含该下界。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

to

否

Double

参数解释：

自定义数值标签数值上界，默认包含该上界。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

do_det

否

Boolean

参数解释：

是否进行目标检测，默认为true。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

box

否

String

参数解释：

目标矩形框坐标，如给定则不进行目标检测，直接使用该box作为目标。格式为“x1,y1,x2,y2”（无空格），x1/y1为目标左上角坐标，x2/y2为目标右下角坐标、

约束限制：

• 0 <= x1 < x2 <= width，默认要求x2-x1 >= 15，具体可参考服务类型说明。
• 0 <= y1 < y2 <= height，默认要求y2-y1 >= 15，具体可参考服务类型说明。

取值范围：

不涉及。

默认取值：

不涉及。

do_cls

否

Boolean

参数解释：

是否进行对象分类，默认为true。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

category

否

Integer

参数解释：

对象类目，如给定则不进行对象分类，直接使用该category作为类目。具体类目信息可参见对应的服务类型说明。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

collapse_key

否

String

参数解释：

去重标签名，必须为服务实例custom_tags中已存在的key。

约束限制：

• 如给定则会对该key下相同value的数据进行去重，仅保留得分最高的数据。
• 针对没有设置该标签的数据，会直接过滤。

取值范围：

不涉及。

默认取值：

不涉及。

max_scan_num

否

Integer

参数解释：

查询考察中心点的数目。值越大精度越高，查询速度变慢。

约束限制：

不涉及。

取值范围：

取值范围：1-100000，默认值为10000。

默认取值：

不涉及。

nprobe

否

Integer

参数解释：

扫描节点上限。值越大精度越高，查询速度变慢。

约束限制：

不涉及。

取值范围：

取值范围：1-100000，默认值为100。

默认取值：

不涉及。

text_lang

否

String

参数解释：

文本字符串的语言类型枚举值。

约束限制：

不涉及。

取值范围：

• ar：阿拉伯语
• de：德语
• ru：俄罗斯语
• fr：法语
• ko：朝鲜语
• pt：葡萄牙语
• ja：日语
• th：泰语
• tr：土耳其语
• es：西班牙语
• en：英语
• vi：越南语
• zh：简体中文
• zhTW：繁体中文

默认取值：

zh。

result

String

参数解释：

搜索完成返回success。

取值范围：

不涉及。

data

SearchRestInfo object

参数解释：

搜索的相关信息。

取值范围：

不涉及。

items

Array of SearchItem objects

参数解释：

搜索结果列表。

取值范围：

不涉及。

search_info

SearchInfo object

参数解释：

搜索结果的相关信息。

取值范围：

不涉及。

image_info

image_info object

参数解释：

搜索图像的相关信息，不同服务类型返回信息不同，具体可参见服务类型说明。

取值范围：

不涉及。

id

String

参数解释：

数据唯一ID。

取值范围：

不涉及。

score

Double

参数解释：

数据匹配分数。

取值范围：

不涉及。

source

ItemSource object

参数解释：

数据的元信息，不同数据包含的字段可能不同。

取值范围：

不涉及。

desc

String

参数解释：

数据描述信息。

取值范围：

不涉及。

custom_tags

Map<String,String>

参数解释：

数据自定义字符标签。

取值范围：

不涉及。

custom_num_tags

Map<String,Number>

参数解释：

数据自定义数值标签。

取值范围：

不涉及。

keywords

Array of strings

参数解释：

数据关键词列表。

取值范围：

不涉及。

total_num

Integer

参数解释：

搜索结果总数。

取值范围：

不涉及。

return_num

Integer

参数解释：

返回结果总数。

取值范围：

不涉及。

search_time

Integer

参数解释：

搜索过程耗时，单位为毫秒。

取值范围：

不涉及。

last_item

SearchAfterParam object

参数解释：

最后一个搜索结果的排序信息。仅对全量召回生效，非全量召回场景返回null。

取值范围：

不涉及。

score

Double

参数解释：

搜索结果的得分。

取值范围：

不涉及。

id

String

参数解释：

搜索结果的唯一ID。

取值范围：

不涉及。

box

String

参数解释：

用于搜索的主体目标框。

取值范围：

不涉及。

category

Integer

参数解释：

用于搜索的主体类目序号。

取值范围：

不涉及。

category_name

String

参数解释：

用于搜索的主体类目名称。

取值范围：

不涉及。

objects

Array of objects objects

参数解释：

搜索图像中的所有主体列表。

取值范围：

不涉及。

box

String

参数解释：

主体目标框。

取值范围：

不涉及。

category

Integer

参数解释：

主体类目序号。

取值范围：

不涉及。

category_name

String

参数解释：

主体类目名称。

取值范围：

不涉及。

error_code

String

参数解释：

调用失败时的错误码，具体请参见错误码。

调用成功时无此字段。

取值范围：

不涉及。

error_msg

String

参数解释：

调用失败时的错误信息。

调用成功时无此字段。

取值范围：

不涉及。

200

成功响应示例。

400

失败响应示例。