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

注册数据（db_set）

注册数据指用户向服务内指定的数据库添加数据，并为该数据指定group_id、intra_id及图片URL。

以下介绍该接口的参数说明及调用示例：
  • 输入参数说明
    参数 是否必选 描述 示例值 类型
    url 是 图片或视频的URL地址。 "" STRING
    database_name 是 数据库名称。 "" STRING
    group_id 是 注册单张图片必须指定的ID信息。 "1" STRING
    intra_id 否 同一个group_id下的内部ID。如果没有指定该参数，则默认递增。 None INT
  • 输出参数说明
    参数 描述 示例值 类型
    success 请求是否成功，取值包括：
    • true：请求成功。
    • false：请求失败。
    		true BOOL
    info 返回调用函数的相关信息。 {"add": true} DICT
    error_code 请求失败时，返回的错误码。 None INT
    error_msg 请求失败时，返回的错误信息。 None STRING
  • 示例
    以下为Python代码调用接口的示例。
    import requests, json

datas = json.dumps({
            "input": {
                "url": "http://pai-vision-data-hz.cn-hangzhou.oss.aliyun-inc.com/EasyMM/DataSet/COCO_2014/train2014/COCO_train2014_000000098038.jpg",
                "function_name": "db_set",
                "function_params": {
                    "database_name": "i2t_coco",
                    "group_id" : 0,
                    "intra_id" : 1,
                },
            }})
head = {"Authorization": "XXXX"} #服务部署成功后，PAI-EAS返回的Token密钥。
hosts = "xxxxxx/test"  #服务部署成功后，PAI-EAS返回的服务地址。
r = requests.post(hosts, data=datas, headers=head)

查询数据（db_get）

查询数据指用户向服务内指定的数据库查询指定group_id及intra_id的数据，该接口支持通过以下两种方式查询数据：
  • 指定group_id进行查询，接口返回数据库内所有符合该group_id的相关信息。
  • 指定group_id和intra_id进行查询，接口返回数据库内符合查询条件的唯一数据记录的相关信息。
以下介绍该接口的调用示例及参数说明：
  • 输入参数说明
    参数 是否必选 描述 示例值 类型
    database_name 是 在该数据库内查询数据。 "test" STRING
    group_id 是 待查询数据的group_id。 "6000" STRING
    intra_id 否 待查询数据的intra_id。如果未指定该参数，则接口返回数据库内所有符合group_id的相关信息。 0 INT
  • 输出参数说明
    参数 描述 示例值 类型
    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
  • 输出示例
    以下为Python代码调用接口的示例。
    import requests, json

datas = json.dumps({
            "input": {
                "function_name": "db_get",
                "function_params": {
                    "database_name": "i2t_coco",
                    "group_id" : 1,
                    "intra_id" : 0,
                },
            }})
head = {"Authorization": "XXXX"} #服务部署成功后，PAI-EAS返回的Token密钥。
hosts = "xxxxxx/test"  #服务部署成功后，PAI-EAS返回的服务地址。
r = requests.post(hosts, data=datas, headers=head)

删除数据（db_delete）

删除数据指用户向服务内指定的数据库删除指定group_id及intra_id的数据，该接口支持通过以下两种方式删除数据：
  • 指定group_id进行删除，可以删除数据库内所有符合该group_id的相关信息。
  • 指定group_id和intra_id进行删除，仅删除数据库内符合条件的唯一数据记录的相关信息。
以下介绍该接口的调用示例及参数说明：
  • 输入参数说明
    参数 是否必选 描述 示例值 类型
    database_name 是 在该数据库中删除数据。 "test" STRING
    group_id 是 待删除数据的group_id。 "test_gid" STRING
    intra_id 否 待删除数据的intra_id，如果未指定，则删除group_id对应的所有数据。 0 INT
  • 输出参数说明
    字段 描述 示例值 类型
    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
  • 输出示例
    以下为Python代码调用接口的示例。
    import requests, json

datas = json.dumps({
            "input": {
                "function_name": "db_delete",
                "function_params": {
                    "database_name": "i2t_coco",
                    "group_id" : 1,
                    "intra_id" : 0,
                },
            }})
head = {"Authorization": "XXXX"} #服务部署成功后，PAI-EAS返回的Token密钥。
hosts = "xxxxxx/test"  #服务部署成功后，PAI-EAS返回的服务地址。
r = requests.post(hosts, data=datas, headers=head)

检索数据（db_search）

检索数据指用户向服务内指定的数据库发送文本检索请求，系统会在已注册的数据中找到与该文本最接近的图片，并返回该图片的相关信息。该接口支持以下检索策略：
  • 与注册数据类似，检索数据支持输入图片的OSS地址。
  • 检索数据可以指定TOPK距离的召回。
  • 检索数据可以指定是否返回被检索到图片的原始数据地址，默认不返回。
以下介绍该接口的调用示例及参数说明：
  • 输入参数说明
    参数 是否必选 描述 示例值 类型
    database_name 是 在该数据库中检索图片。 "" STRING
    text 是 输入文本。 "" STRING
    search_topk 是 检索返回的记录数目。 3 INT
  • 输出参数说明
    参数 描述 示例值 Type
    success 请求是否成功，取值包括：
    • true：请求成功。
    • false：请求失败。
    		true BOOL
    status 检索是否成功，取值包括：
    • true：检索成功。
    • false：检索失败。
    		true BOOL
    info 检索返回的信息，数据结构请参见下方的表 1。 无 DICT
    error_code 请求失败时，返回的错误码。 None INT
    error_msg 请求失败时，返回的错误信息。 None STRING
    表 1. info的数据结构
    数据结构 描述
    ['distance', 'group_id','intra_id', 'oss_path_name'] 数据结构中的参数含义如下：
    • 'distance'：检索的距离列表。如果是Cosine距离，则数值越大表示结果越接近。如果是SquaredEuclidean距离，则数值越小表示结果越接近。
    • 'group_id'：检索到的图片'group_id'列表。
    • 'intra_id'：检索到的图片'intra_id'列表。
    • 'oss_path_name'：检索到的原数据地址列表。
  • 输出示例
    以下为Python代码调用接口的示例。
    import requests, json

datas = json.dumps({
            "input": {
                "function_name": "db_search",
                "function_params": {
                    "database_name": "i2t_coco",
                    "text": "一个骑摩托车的人停在一群奶牛前面。",
                    "search_topk": 5
                },
            }})
head = {"Authorization": "XXXX"} #服务部署成功后，PAI-EAS返回的Token密钥。
hosts = "xxxxxx/test"  #服务部署成功后，PAI-EAS返回的服务地址。
r = requests.post(hosts, data=datas, headers=head)
    返回结果如下所示。
    {
    'status': True,
    'info': {
    'distance': [0.46677274, 0.46677262, 0.46677262, 0.46677262, 0.4667726],
    'group_id': [0.0, 0.0, 0.0, 0.0, 0.0],
    'intra_id': [1.0, 4.0, 2.0, 3.0, 0.0],
    'oss_path_name': (['http://pai-vision-data-hz.cn-hangzhou.oss.aliyun-inc.com/EasyMM/DataSet/COCO_2014/train2014/COCO_train2014_00000009****.jpg', 'http://pai-vision-data-hz.cn-hangzhou.oss.aliyun-inc.com/EasyMM/DataSet/COCO_2014/train2014/COCO_train2014_00000009****.jpg', 'http://pai-vision-data-hz.cn-hangzhou.oss.aliyun-inc.com/EasyMM/DataSet/COCO_2014/train2014/COCO_train2014_00000009****.jpg', 'http://pai-vision-data-hz.cn-hangzhou.oss.aliyun-inc.com/EasyMM/DataSet/COCO_2014/train2014/COCO_train2014_00000009****.jpg', 'http://pai-vision-data-hz.cn-hangzhou.oss.aliyun-inc.com/EasyMM/DataSet/COCO_2014/train2014/COCO_train2014_00000009****.jpg'],)
    }
}