文档首页/ 图像搜索 ImageSearch/ API参考/ API/ 搜索查询 V2
更新时间：2024-08-21 GMT+08:00
查看PDF
分享

搜索查询 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

失败响应示例。

错误码

请参见错误码。

父主题： API

相关文档