商品检索服务的数据库层支持图像存储和检索,您可以通过POST方式调用该服务提供的接口,对数据库中的数据进行增加、查询、删除、检索及清理操作。本文介绍各接口的详细信息,包括POST内容示例、输入参数、输出参数及输出示例。

商品检索服务的数据库层提供的接口列表如下: 在数据库中,每张图片数据必须指定对应的group_id,从而实现后续的查询和检索功能。下文详细介绍数据库层提供的接口,此处仅介绍每个接口的特有参数,关于接口中的通用参数说明请参见接口格式及调用说明(必读)

注册数据(db_set)

注册数据指用户向服务内指定的数据库添加数据。您可以上传图片数据,并为该数据指定group_idintra_id,进而为数据库添加该数据。如果您是OSS用户,还可以将上传的Base 64编码的图像内容写到指定路径下。

以下介绍该接口的调用示例及参数说明:
  • POST内容示例(单图像注册)
    {   
        "function_name": "db_set",
        "function_params": {
            "database_name":"libai",
            "image" : base64.b64encode(open(image_path, 'rb').read()).decode(ENCODING), #图像的Base 64编码。
            "group_id" : "1",
            "savename" : imagea
        },
    }
  • 输入参数说明
    参数 是否必选 描述 示例值 类型
    image 图片内容的Base 64编码字符串。如果您是OSS 用户,则该参数可以填写图片对应的OSS地址。 STRING
    group_id 注册单张图片必须指定的ID信息。 "1" STRING
    intra_id 同一个group_id下的内部ID。如果没有指定该参数,则默认递增。 None INT
    savename OSS后端限定参数。 如果传入的image是Base 64编码,则指定该参数可以把图片写入到您提供的root_path/database_name/savename下。 "xxx.jpg" STRING
    data Elasticsearch后端限定参数。您可以将data的附加信息写入到该条特征对应的doc中。 [] DICT
  • 输出参数说明
    参数 描述 示例值 类型
    request_id 请求的唯一标识。 "54092937-191e-45b6-8be4-415b45a4****" STRING
    success 请求是否成功,取值包括:
    • true:请求成功。
    • false:请求失败。
    true BOOL
    info 返回调用函数的相关信息。 {"add": true} DICT
    error_code 请求失败时,返回的错误码。 None INT
    error_msg 请求失败时,返回的错误信息。 None STRING
  • 输出示例
    {
    "request_id": "54092937-191e-45b6-8be4-415b45a4****", 
    "success": true, 
    "info": {"add": true}
    }

查询数据(db_get)

查询数据指用户向服务内指定的数据库查询指定group_idintra_id的数据,该接口支持通过以下两种方式查询数据:
  • 指定group_id进行查询,接口返回数据库内所有符合该group_id的相关信息。
  • 指定group_idintra_id进行查询,接口返回数据库内符合查询条件的唯一数据记录的相关信息。
以下介绍该接口的调用示例及参数说明:
  • POST内容示例
    {   
        "function_name": "db_get", # 查询数据的操作名称。
        "function_params": {
            "database_name":"test", # 用户指定的数据库名称。
            "group_id" : "6000" # 待查询的ID信息。
            "intra_id" : 1   # 待查询的数据内部的ID,选填。
        },
    }
  • 输入参数说明
    参数 是否必选 描述 示例值 类型
    database_name 在该数据库内查询数据。 "test" STRING
    group_id 待查询数据的group_id "6000" STRING
    intra_id 待查询数据的intra_id。如果未指定该参数,则接口返回数据库内所有符合group_id的相关信息。 0 INT
    source Elasticsearch后端限定参数,限定返回doc里面的内容。您可以通过数据库管理层的get接口查看doc,通常doc可以包括:
    • "group_id"
    • "intra_id"
    • "_id"
    • "feature"
    ["group_id", "intra_id"] LIST/None
  • 输出参数说明
    参数 描述 示例值 类型
    request_id 请求的唯一标识。 "a666a783-b6a9-49ca-a5fb-e9c1091e****" STRING
    success 请求是否成功,取值包括:
    • true:请求成功。
    • false:请求失败。
    true BOOL
    status 是否查询到指定数据,取值包括:
    • true:查询成功。
    • false:查询失败。
    true BOOL
    info 如果查询成功,则返回查询到的信息,包括数据ID和地址信息。如果查询失败,则返回相关提示。 {"oss_path_name": ["oss://xxxxx/xxxx.jpg"],"group_id": ["test_group_id"],"intra_id": [0.0]} DICT
    error_code 请求失败时,返回的错误码。 None INT
    error_msg 请求失败时,返回的错误信息。 None STRING
  • 输出示例
    {
    "request_id": "a666a783-b6a9-49ca-a5fb-e9c1091e****", 
    "success": true, 
    "info": {
      "oss_path_name": ["oss://xxxxx/xxxx.jpg"], 
      "group_id": ["test_group_id"], 
      "intra_id": [0.0]
      }
    }

删除数据(db_delete)

删除数据指用户向服务内指定的数据库删除指定group_idintra_id的数据,该接口支持通过以下两种方式删除数据:
  • 指定group_id进行删除,可以删除数据库内所有符合该group_id的相关信息。
  • 指定group_idintra_id进行删除,仅删除数据库内符合条件的唯一数据记录的相关信息。
以下介绍该接口的调用示例及参数说明:
  • POST内容示例
    {   
        "function_name": "db_delete", # 删除数据的操作名称。
        "function_params": {
            "database_name":"test", # 用户指定的数据库名称。
            "group_id" : "test_gid" # 待删除的ID信息。
            "intra_id" : 0   # 待删除的数据内部的ID,选填。
        },
    }
  • 输入参数说明
    参数 是否必选 描述 示例值 类型
    database_name 在该数据库中删除数据。 "test" STRING
    group_id 待删除数据的group_id "test_gid" STRING
    intra_id 待删除数据的intra_id,如果未指定,则删除group_id对应的所有数据。 0 INT
  • 输出参数说明
    字段 描述 示例值 类型
    request_id 请求的唯一标识。 "e8a8c95e-d2e2-4b68-b403-2fc90bbc****" STRING
    success 请求是否成功,取值包括:
    • true:请求成功。
    • false:请求失败。
    true BOOL
    status 是否删除成功,取值包括:
    • true:删除成功。
    • false:删除失败。如果数据不存在,则返回false
    true BOOL
    info 返回删除的相关信息。 'database delete instruction params must contains group_id' STRING
    error_code 请求失败时,返回的错误码。 None INT
    error_msg 请求失败时,返回的错误信息。 None STRING
  • 输出示例
    {
     "request_id": "e8a8c95e-d2e2-4b68-b403-2fc90bbc****", 
     "success": true, 
     "info": "database delete gid xxx"
    }

检索数据(db_search)

检索数据指用户向服务内指定的数据库发送图片检索请求,系统会提取该图片的特征,并在已注册的数据中找到与该特征最接近的特征对应的图片,进而返回该图片的相关信息。该接口支持以下检索策略:
  • 与注册数据类似,检索数据支持输入图片的OSS地址或Base 64编码。
  • 检索数据可以指定TOPK距离的召回。
  • 检索数据可以指定是否返回被检索到图片的原始数据地址,默认不返回。
以下介绍该接口的调用示例及参数说明:
  • POST内容示例
    {   
        "function_name": "db_search",
        "function_params": {
            "database_name":"libai", #待检索的数据库名称。
            "image" : base64.b64encode(open(imagea, 'rb').read()).decode(ENCODING), #待检索图像的Base 64编码。
            'search_topk' : 2, # 检索返回的TOPK。
        },
    }
  • 输入参数说明
    参数 是否必选 描述 示例值 类型
    database_name 在该数据库中检索图片。 "libai" STRING
    image 图片内容的Base 64编码字符串。OSS用户也可以将该参数配置为图片的OSS地址。 STRING
    search_topk 检索返回的记录数目。 3 INT
    savename OSS后端限定参数。 如果传入的image为Base 64编码,则指定该参数可以将图片写入到您提供的root_path/database_name/savename下。 "xxx.jpg" STRING
    search_algorithm Elasticsearch后端限定参数,取值包括:
    • "hnsw": 近邻召回,速度快,但是不能保证全部召回。
    • "linear": 线性召回,能够保证召回结果的正确性。
    "hnsw" STRING
  • 输出参数说明
    参数 描述 示例值 Type
    request_id 请求的唯一标识。 "8549fde3-cd2d-4053-a3a4-fb86127b****" STRING
    success 请求是否成功,取值包括:
    • true:请求成功。
    • false:请求失败。
    true BOOL
    status 检索是否成功,取值包括:
    • true:检索成功。
    • false:检索失败。
    true BOOL
    info 检索返回的信息,不同后端返回的数据结构请参见下方的表 1 DICT
    error_code 请求失败时,返回的错误码。 None INT
    error_msg 请求失败时,返回的错误信息。 None STRING
    表 1. info的数据结构
    后端类型 数据结构 描述
    OSS ['distance', 'group_id','intra_id', 'oss_path_name'] 数据结构中的参数含义如下:
    • 'distance':检索的距离列表。如果是Cosine距离,则数值越大表示结果越接近。如果是SquaredEuclidean距离,则数值越小表示结果越接近。
    • 'group_id':检索到的图片'group_id'列表。
    • 'intra_id':检索到的图片'intra_id'列表。
    • 'oss_path_name':检索到的原数据地址列表。
    Elasticsearch ['total', 'max_score', 'hits'] 数据结构中的参数含义如下:
    • 'total':返回的记录总数量。
    • 'max_score':检索的距离得分,代表距离远近,数值越大表示结果越近。
    • 'hits':检索到的Elasticsearch后端存储的Documents,包含['_index', '_type', '_id', '_score', '_source']信息,每个字段的含义如下:
      • '_index':Elasticsearch后端中存储的数据库名称,与database_name取值相同。
      • '_type':返回的类型。
      • '_id':检索到的记录的在Elasticsearch中的唯一标识。
      • '_score':距离检索的得分,得分越大,距离越近。
      • '_source':检索返回的源数据内容。
  • 输出示例
    {
    "request_id": "8549fde3-cd2d-4053-a3a4-fb86127b****", 
    "success": true, 
    'status': True, 
    'info': {
      'distance': [0.29342561960220337, 0.287186861038208, 0.27671411633491516, 0.2678218483924866, 0.2663806676864624], 
      'group_id': ['xxgid1', 'xxgid1', 'xxgid1', 'xxgid1', 'xxgid1'], 
      'intra_id': [0.0, 6.0, 2.0, 7.0, 4.0]}
    }