# 搜索查询 V2-RunSearch #### 功能介绍 从指定服务实例中进行搜索。 #### 调试 您可以在[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/ImageSearch/doc?api=RunSearch)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。 #### URI POST /v2/{project_id}/mms/{service_name}/search 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | String | **参数解释：** 用户的项目ID。获取方法请参见[获取项目ID和名称](https://support.huaweicloud.com/api-imagesearch/imagesearch_02_0035.html)。 **约束限制：** 不涉及。 **取值范围：** 只能由英文字母和数字组成，且长度为\[1-64\]个字符。 **默认取值：** 不涉及。 | | service_name | 是 | String | **参数解释：** 服务实例的名称，用户创建服务实例时设置的实例名称。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | #### 请求参数 表2请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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\\> | **参数解释：** 自定义字符标签，用于对搜索结果进行条件过滤。格式为键值对{key:value}。 **约束限制：** - key: 必须为服务实例custom_tags中已存在的key，可在创建服务实例时进行配置，或在更新服务实例时进行新增。 - value: 标签值列表，列表内多个标签值为"或"关系，即满足一个即可。 **取值范围：** value: 列表长度范围为\[1, 32\]，标签值类型为字符串，字符长度范围为\[1, 64\]。 **默认取值：** 不涉及。 | | custom_num_tags | 否 | Map\ | **参数解释：** 自定义数值标签，用于对搜索结果进行条件过滤。格式为键值对{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 | **参数解释：** 搜索的可选参数，其中每个参数仅对部分服务类型生效，具体可参见服务类型说明。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表3SearchAfterParam | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | score | 否 | Double | **参数解释：** 搜索结果的相似度。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | id | 否 | String | **参数解释：** 搜索结果的唯一ID。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表4RangeParam | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | from | 否 | Double | **参数解释：** 自定义数值标签数值下界，默认包含该下界。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | to | 否 | Double | **参数解释：** 自定义数值标签数值上界，默认包含该上界。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表5SearchOptionalParam | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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。 | #### 响应参数 **状态码： 200** 表6响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | result | String | **参数解释：** 搜索完成返回success。 **取值范围：** 不涉及。 | | data | [SearchRestInfo] object | **参数解释：** 搜索的相关信息。 **取值范围：** 不涉及。 | 表7SearchRestInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | items | Array of [SearchItem] objects | **参数解释：** 搜索结果列表。 **取值范围：** 不涉及。 | | search_info | [SearchInfo] object | **参数解释：** 搜索结果的相关信息。 **取值范围：** 不涉及。 | | image_info | [image_info] object | **参数解释：** 搜索图像的相关信息，不同服务类型返回信息不同，具体可参见服务类型说明。 **取值范围：** 不涉及。 | 表8SearchItem | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | **参数解释：** 数据唯一ID。 **取值范围：** 不涉及。 | | score | Double | **参数解释：** 数据匹配分数。 **取值范围：** 不涉及。 | | source | [ItemSource] object | **参数解释：** 数据的元信息，不同数据包含的字段可能不同。 **取值范围：** 不涉及。 | 表9ItemSource | 参数 | 参数类型 | 描述 | |:---|:---|:---| | desc | String | **参数解释：** 数据描述信息。 **取值范围：** 不涉及。 | | custom_tags | Map\ | **参数解释：** 数据自定义字符标签。 **取值范围：** 不涉及。 | | custom_num_tags | Map\ | **参数解释：** 数据自定义数值标签。 **取值范围：** 不涉及。 | | keywords | Array of strings | **参数解释：** 数据关键词列表。 **取值范围：** 不涉及。 | 表10SearchInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | total_num | Integer | **参数解释：** 搜索结果总数。 **取值范围：** 不涉及。 | | return_num | Integer | **参数解释：** 返回结果总数。 **取值范围：** 不涉及。 | | search_time | Integer | **参数解释：** 搜索过程耗时，单位为毫秒。 **取值范围：** 不涉及。 | | last_item | [SearchAfterParam] object | **参数解释：** 最后一个搜索结果的排序信息。仅对全量召回生效，非全量召回场景返回null。 **取值范围：** 不涉及。 | 表11SearchAfterParam | 参数 | 参数类型 | 描述 | |:---|:---|:---| | score | Double | **参数解释：** 搜索结果的得分。 **取值范围：** 不涉及。 | | id | String | **参数解释：** 搜索结果的唯一ID。 **取值范围：** 不涉及。 | 表12image_info | 参数 | 参数类型 | 描述 | |:---|:---|:---| | box | String | **参数解释：** 用于搜索的主体目标框。 **取值范围：** 不涉及。 | | category | Integer | **参数解释：** 用于搜索的主体类目序号。 **取值范围：** 不涉及。 | | category_name | String | **参数解释：** 用于搜索的主体类目名称。 **取值范围：** 不涉及。 | | objects | Array of [objects] objects | **参数解释：** 搜索图像中的所有主体列表。 **取值范围：** 不涉及。 | 表13objects | 参数 | 参数类型 | 描述 | |:---|:---|:---| | box | String | **参数解释：** 主体目标框。 **取值范围：** 不涉及。 | | category | Integer | **参数解释：** 主体类目序号。 **取值范围：** 不涉及。 | | category_name | String | **参数解释：** 主体类目名称。 **取值范围：** 不涉及。 | **状态码： 400** 表14响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 调用失败时的错误码，具体请参见[错误码](https://support.huaweicloud.com/api-imagesearch/imagesearch_02_0043.html)。 调用成功时无此字段。 **取值范围：** 不涉及。 | | error_msg | String | **参数解释：** 调用失败时的错误信息。 调用成功时无此字段。 **取值范围：** 不涉及。 | #### 请求示例 搜索商品图像，使用图像BASE64编码 ``` POST https://{endpoint}/v2/{project_id}/mms/{service_name}/search { "search_type" : "CATEGORY", "image_base64" : "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAAgABwESAAMAAAABAAEAAAEaAAUAAAABAAAAYgEbAA...", "custom_tags" : { "brand" : [ "HUAWEI" ] }, "custom_num_tags" : { "year" : { "from" : 2020, "to" : 2022 } } } ``` #### 响应示例 **状态码： 200** 成功响应示例 ``` { "result" : "success", "data" : { "items" : [ { "id" : "electronics_01", "score" : 1, "source" : { "desc" : "天地纵横自然", "custom_tags" : { "brand" : "HUAWEI" }, "custom_num_tags" : { "year" : 2022 } } } ], "search_info" : { "total_num" : 10, "return_num" : 1, "search_time" : 512 }, "image_info" : { "box" : "26,223,771,704", "category" : 11, "category_name" : "electronics", "objects" : [ { "box" : "26,223,771,704", "category" : 11, "category_name" : "electronics" }, { "box" : "55,66,420,315", "category" : 0, "category_name" : "others" } ] } } } ``` **状态码： 400** 失败响应示例 ``` { "error_code" : "MMS.0003", "error_msg" : "Invalid parameter: custom_tags" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 成功响应示例。 | | 400 | 失败响应示例。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-imagesearch/imagesearch_02_0043.html)。