更新时间:2024-08-21 GMT+08:00
分享

搜索查询 V2

功能介绍

从指定服务实例中进行搜索。

调试

您可以在API Explorer中调试该接口,支持自动认证鉴权。API Explorer可以自动生成SDK代码示例,并提供SDK代码示例调试功能。

URI

POST /v2/{project_id}/mms/{service_name}/search

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

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

service_name

String

服务实例的名称,用户创建服务实例时指定。

请求参数

表2 请求Body参数

参数

是否必选

参数类型

描述

search_type

String

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

说明:

可以使用枚举名或者枚举值(例如IMAGE/0),枚举值可能会变动,建议使用枚举名。

枚举值:

  • IMAGE
  • KEYWORD
  • TEXT
  • CATEGORY

limit

Integer

返回搜索结果的数量,默认为10,取值范围为[1, 1000]。

offset

Integer

返回搜索结果的偏移量,即返回序号在[offset, offset+limit]内的搜索结果。默认为0,取值范围为[0, N]。

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

last_item

SearchAfterParam object

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

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

min_score

Double

返回搜索结果的最小得分,用于对搜索结果进行score过滤,取值范围为[0, 1]。

说明:

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

custom_tags

Map<String,Array<String>>

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

  • key: 必须为服务实例custom_tags中已存在的key,可在创建服务实例时进行配置,或在更新服务实例时进行新增。
  • 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

关键词列表,搜索时关键词数量范围为[1, 10],关键词字符长度范围为[1, 64]。使用KEYWORD搜索类型进行搜索时,必须提供该参数。

text

String

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

optional_params

SearchOptionalParam object

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

表3 SearchAfterParam

参数

是否必选

参数类型

描述

score

Double

搜索结果的相似度。

id

String

搜索结果的唯一ID。

表4 RangeParam

参数

是否必选

参数类型

描述

from

Double

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

to

Double

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

表5 SearchOptionalParam

参数

是否必选

参数类型

描述

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

文本字符串的语言类型枚举值,默认值:zh。

可选值:

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

响应参数

状态码: 200

表6 响应Body参数

参数

参数类型

描述

result

String

搜索完成返回success。

data

SearchRestInfo object

搜索的相关信息。

表7 SearchRestInfo

参数

参数类型

描述

items

Array of SearchItem objects

搜索结果列表。

search_info

SearchInfo object

搜索结果的相关信息。

image_info

image_info object

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

表8 SearchItem

参数

参数类型

描述

id

String

数据唯一ID。

score

Double

数据匹配分数。

source

ItemSource object

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

表9 ItemSource

参数

参数类型

描述

desc

String

数据描述信息。

custom_tags

Map<String,String>

数据自定义字符标签。

custom_num_tags

Map<String,Number>

数据自定义数值标签。

keywords

Array of strings

数据关键词列表。

表10 SearchInfo

参数

参数类型

描述

total_num

Integer

搜索结果总数。

return_num

Integer

返回结果总数。

search_time

Integer

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

last_item

SearchAfterParam object

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

表11 SearchAfterParam

参数

参数类型

描述

score

Double

搜索结果的得分。

id

String

搜索结果的唯一ID。

表12 image_info

参数

参数类型

描述

box

String

用于搜索的主体目标框。

category

Integer

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

category_name

String

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

objects

Array of objects objects

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

表13 objects

参数

参数类型

描述

box

String

主体目标框。

category

Integer

主体类目序号。

category_name

String

主体类目名称。

状态码: 400

表14 响应Body参数

参数

参数类型

描述

error_code

String

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

调用成功时无此字段。

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

失败响应示例。

错误码

请参见错误码

相关文档