2023-07-13 15:22:47 +08:00

30 KiB
Raw Permalink Blame History

人脸搜索服务API

简介:人脸搜索服务API

HOST:http://127.0.0.1:8080

联系人:

Version:2.0.0

接口路径:/v3/api-docs?group=2.0.0

[TOC]

01、集合(数据库)管理

1、创建一个集合(数据库)

接口地址:/visual/collect/create

请求方式:POST

请求数据类型:application/x-www-form-urlencoded,application/json

响应数据类型:*/*

接口描述:

请求示例:

{
  "collectionComment": "",
  "collectionName": "",
  "faceColumns": [
    {
      "comment": "",
      "dataType": "",
      "name": ""
    }
  ],
  "namespace": "",
  "replicasNum": 0,
  "sampleColumns": [
    {
      "comment": "",
      "dataType": "",
      "name": ""
    }
  ],
  "shardsNum": 0,
  "storageEngine": "",
  "storageFaceInfo": false
}

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 schema
collectReqVo 集合信息 body true CollectReqVo CollectReqVo
collectionComment 集合描述最大128个字符 false string
collectionName 集合名称最大24个字符,支持小写字母、数字和下划线的组合 true string
faceColumns 自定义的人脸属性字段 false array FiledColumn
comment 字段描述,最大64个字符 false string
dataType 字段类型不能为UNDEFINED类型,可用值:BOOL,DOUBLE,FLOAT,INT,STRING,UNDEFINED true string
name 字段名称,支持小写字母、数字和下划线的组合最大32个字符 true string
namespace 命名空间最大12个字符,支持小写字母、数字和下划线的组合 true string
replicasNum 数据分片中最大的文件个数默认为0不限制,仅对Proxima引擎生效 false integer(int64)
sampleColumns 自定义的样本属性字段 false array FiledColumn
comment 字段描述,最大64个字符 false string
dataType 字段类型不能为UNDEFINED类型,可用值:BOOL,DOUBLE,FLOAT,INT,STRING,UNDEFINED true string
name 字段名称,支持小写字母、数字和下划线的组合最大32个字符 true string
shardsNum 要创建的集合的分片数默认为0即系统默认,仅对Milvus引擎生效 false integer(int32)
storageEngine 保留图片及人脸信息的存储组件,可用值:ALI_OSS,CURR_DB,MIN_IO,TCE_COS false string
storageFaceInfo 是否保留图片及人脸信息 false boolean

响应状态:

状态码 说明 schema
200 OK ResponseInfo«boolean»
201 Created
401 Unauthorized
403 Forbidden
404 Not Found

响应参数:

参数名称 参数说明 类型 schema
code 返回代码 integer(int32) integer(int32)
data 数据信息 boolean
message 返回信息 string

响应示例:

{
	"code": 0,
	"data": false,
	"message": ""
}

2、根据命名空间集合名称删除集合

接口地址:/visual/collect/delete

请求方式:GET

请求数据类型:application/x-www-form-urlencoded

响应数据类型:*/*

接口描述:

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 schema
namespace 命名空间 query true string
collectionName 集合名称 query true string

响应状态:

状态码 说明 schema
200 OK ResponseInfo«boolean»
401 Unauthorized
403 Forbidden
404 Not Found

响应参数:

参数名称 参数说明 类型 schema
code 返回代码 integer(int32) integer(int32)
data 数据信息 boolean
message 返回信息 string

响应示例:

{
	"code": 0,
	"data": false,
	"message": ""
}

3、根据命名空间集合名称查看集合信息

接口地址:/visual/collect/get

请求方式:GET

请求数据类型:application/x-www-form-urlencoded

响应数据类型:*/*

接口描述:

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 schema
namespace 命名空间 query true string
collectionName 集合名称 query true string

响应状态:

状态码 说明 schema
200 OK ResponseInfo«CollectRepVo»
401 Unauthorized
403 Forbidden
404 Not Found

响应参数:

参数名称 参数说明 类型 schema
code 返回代码 integer(int32) integer(int32)
data 数据信息 CollectRepVo CollectRepVo
collectionComment 集合描述最大128个字符 string
collectionName 集合名称最大24个字符,支持小写字母、数字和下划线的组合 string
faceColumns 自定义的人脸属性字段 array FiledColumn
comment 字段描述,最大64个字符 string
dataType 字段类型不能为UNDEFINED类型,可用值:BOOL,DOUBLE,FLOAT,INT,STRING,UNDEFINED string
name 字段名称,支持小写字母、数字和下划线的组合最大32个字符 string
namespace 命名空间最大12个字符,支持小写字母、数字和下划线的组合 string
replicasNum 数据分片中最大的文件个数默认为0不限制,仅对Proxima引擎生效 integer(int64)
sampleColumns 自定义的样本属性字段 array FiledColumn
comment 字段描述,最大64个字符 string
dataType 字段类型不能为UNDEFINED类型,可用值:BOOL,DOUBLE,FLOAT,INT,STRING,UNDEFINED string
name 字段名称,支持小写字母、数字和下划线的组合最大32个字符 string
shardsNum 要创建的集合的分片数默认为0即系统默认,仅对Milvus引擎生效 integer(int32)
storageEngine 保留图片及人脸信息的存储组件,可用值:ALI_OSS,CURR_DB,MIN_IO,TCE_COS string
storageFaceInfo 是否保留图片及人脸信息 boolean
message 返回信息 string

响应示例:

{
	"code": 0,
	"data": {
		"collectionComment": "",
		"collectionName": "",
		"faceColumns": [
			{
				"comment": "",
				"dataType": "",
				"name": ""
			}
		],
		"namespace": "",
		"replicasNum": 0,
		"sampleColumns": [
			{
				"comment": "",
				"dataType": "",
				"name": ""
			}
		],
		"shardsNum": 0,
		"storageEngine": "",
		"storageFaceInfo": false
	},
	"message": ""
}

4、根据命名空间查看集合列表

接口地址:/visual/collect/list

请求方式:GET

请求数据类型:application/x-www-form-urlencoded

响应数据类型:*/*

接口描述:

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 schema
namespace 命名空间 query true string

响应状态:

状态码 说明 schema
200 OK ResponseInfo«List«CollectRepVo»»
401 Unauthorized
403 Forbidden
404 Not Found

响应参数:

参数名称 参数说明 类型 schema
code 返回代码 integer(int32) integer(int32)
data 数据信息 array CollectRepVo
collectionComment 集合描述最大128个字符 string
collectionName 集合名称最大24个字符,支持小写字母、数字和下划线的组合 string
faceColumns 自定义的人脸属性字段 array FiledColumn
comment 字段描述,最大64个字符 string
dataType 字段类型不能为UNDEFINED类型,可用值:BOOL,DOUBLE,FLOAT,INT,STRING,UNDEFINED string
name 字段名称,支持小写字母、数字和下划线的组合最大32个字符 string
namespace 命名空间最大12个字符,支持小写字母、数字和下划线的组合 string
replicasNum 数据分片中最大的文件个数默认为0不限制,仅对Proxima引擎生效 integer(int64)
sampleColumns 自定义的样本属性字段 array FiledColumn
comment 字段描述,最大64个字符 string
dataType 字段类型不能为UNDEFINED类型,可用值:BOOL,DOUBLE,FLOAT,INT,STRING,UNDEFINED string
name 字段名称,支持小写字母、数字和下划线的组合最大32个字符 string
shardsNum 要创建的集合的分片数默认为0即系统默认,仅对Milvus引擎生效 integer(int32)
storageEngine 保留图片及人脸信息的存储组件,可用值:ALI_OSS,CURR_DB,MIN_IO,TCE_COS string
storageFaceInfo 是否保留图片及人脸信息 boolean
message 返回信息 string

响应示例:

{
	"code": 0,
	"data": [
		{
			"collectionComment": "",
			"collectionName": "",
			"faceColumns": [
				{
					"comment": "",
					"dataType": "",
					"name": ""
				}
			],
			"namespace": "",
			"replicasNum": 0,
			"sampleColumns": [
				{
					"comment": "",
					"dataType": "",
					"name": ""
				}
			],
			"shardsNum": 0,
			"storageEngine": "",
			"storageFaceInfo": false
		}
	],
	"message": ""
}

02、人脸样本管理

1、创建一个样本

接口地址:/visual/sample/create

请求方式:POST

请求数据类型:application/x-www-form-urlencoded,application/json

响应数据类型:*/*

接口描述:

请求示例:

{
  "collectionName": "",
  "namespace": "",
  "sampleData": [
    {
      "key": "",
      "value": {}
    }
  ],
  "sampleId": ""
}

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 schema
sampleDataReqVo 样本信息 body true SampleDataReqVo SampleDataReqVo
collectionName 集合名称最大24个字符,支持小写字母、数字和下划线的组合 true string
namespace 命名空间最大12个字符,支持小写字母、数字和下划线的组合 true string
sampleData 扩展字段 false array FieldKeyValue
key 字段名,与创建集合时给定的字段名一致 true string
value 字段值与创建集合时给定的类型一致若为字符串最大为512个字符 false object
sampleId 样本ID最大32个字符,支持小写字母、数字和下划线的组合 true string

响应状态:

状态码 说明 schema
200 OK ResponseInfo«boolean»
201 Created
401 Unauthorized
403 Forbidden
404 Not Found

响应参数:

参数名称 参数说明 类型 schema
code 返回代码 integer(int32) integer(int32)
data 数据信息 boolean
message 返回信息 string

响应示例:

{
	"code": 0,
	"data": false,
	"message": ""
}

3、根据条件删除样本

接口地址:/visual/sample/delete

请求方式:GET

请求数据类型:application/x-www-form-urlencoded

响应数据类型:*/*

接口描述:

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 schema
namespace 命名空间 query true string
collectionName 集合名称 query true string
sampleId 样本ID query true string

响应状态:

状态码 说明 schema
200 OK ResponseInfo«boolean»
401 Unauthorized
403 Forbidden
404 Not Found

响应参数:

参数名称 参数说明 类型 schema
code 返回代码 integer(int32) integer(int32)
data 数据信息 boolean
message 返回信息 string

响应示例:

{
	"code": 0,
	"data": false,
	"message": ""
}

4、根据条件查看样本

接口地址:/visual/sample/get

请求方式:GET

请求数据类型:application/x-www-form-urlencoded

响应数据类型:*/*

接口描述:

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 schema
namespace 命名空间 query true string
collectionName 集合名称 query true string
sampleId 样本ID query true string

响应状态:

状态码 说明 schema
200 OK ResponseInfo«SampleDataRepVo»
401 Unauthorized
403 Forbidden
404 Not Found

响应参数:

参数名称 参数说明 类型 schema
code 返回代码 integer(int32) integer(int32)
data 数据信息 SampleDataRepVo SampleDataRepVo
collectionName 集合名称最大24个字符,支持小写字母、数字和下划线的组合 string
faces 人脸数据 array SimpleFaceVo
faceData 人脸扩展的额外数据 array FieldKeyValue
key 字段名,与创建集合时给定的字段名一致 string
value 字段值与创建集合时给定的类型一致若为字符串最大为512个字符 object
faceId 人脸ID string
faceScore 人脸分数 number
namespace 命名空间最大12个字符,支持小写字母、数字和下划线的组合 string
sampleData 扩展字段 array FieldKeyValue
key 字段名,与创建集合时给定的字段名一致 string
value 字段值与创建集合时给定的类型一致若为字符串最大为512个字符 object
sampleId 样本ID最大32个字符,支持小写字母、数字和下划线的组合 string
message 返回信息 string

响应示例:

{
	"code": 0,
	"data": {
		"collectionName": "",
		"faces": [
			{
				"faceData": [
					{
						"key": "",
						"value": {}
					}
				],
				"faceId": "",
				"faceScore": 0
			}
		],
		"namespace": "",
		"sampleData": [
			{
				"key": "",
				"value": {}
			}
		],
		"sampleId": ""
	},
	"message": ""
}

5、根据查询信息查看样本列表

接口地址:/visual/sample/list

请求方式:GET

请求数据类型:application/x-www-form-urlencoded

响应数据类型:*/*

接口描述:

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 schema
namespace 命名空间 query true string
collectionName 集合名称 query true string
offset 起始记录:默认0 query true integer(int32)
limit 样本数目默认10 query true integer(int32)
order 排列方式默认asc包括asc升序和desc降序 query true string

响应状态:

状态码 说明 schema
200 OK ResponseInfo«List«SampleDataRepVo»»
401 Unauthorized
403 Forbidden
404 Not Found

响应参数:

参数名称 参数说明 类型 schema
code 返回代码 integer(int32) integer(int32)
data 数据信息 array SampleDataRepVo
collectionName 集合名称最大24个字符,支持小写字母、数字和下划线的组合 string
faces 人脸数据 array SimpleFaceVo
faceData 人脸扩展的额外数据 array FieldKeyValue
key 字段名,与创建集合时给定的字段名一致 string
value 字段值与创建集合时给定的类型一致若为字符串最大为512个字符 object
faceId 人脸ID string
faceScore 人脸分数 number
namespace 命名空间最大12个字符,支持小写字母、数字和下划线的组合 string
sampleData 扩展字段 array FieldKeyValue
key 字段名,与创建集合时给定的字段名一致 string
value 字段值与创建集合时给定的类型一致若为字符串最大为512个字符 object
sampleId 样本ID最大32个字符,支持小写字母、数字和下划线的组合 string
message 返回信息 string

响应示例:

{
	"code": 0,
	"data": [
		{
			"collectionName": "",
			"faces": [
				{
					"faceData": [
						{
							"key": "",
							"value": {}
						}
					],
					"faceId": "",
					"faceScore": 0
				}
			],
			"namespace": "",
			"sampleData": [
				{
					"key": "",
					"value": {}
				}
			],
			"sampleId": ""
		}
	],
	"message": ""
}

2、更新一个样本

接口地址:/visual/sample/update

请求方式:POST

请求数据类型:application/x-www-form-urlencoded,application/json

响应数据类型:*/*

接口描述:

请求示例:

{
  "collectionName": "",
  "namespace": "",
  "sampleData": [
    {
      "key": "",
      "value": {}
    }
  ],
  "sampleId": ""
}

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 schema
sampleDataReqVo 样本信息 body true SampleDataReqVo SampleDataReqVo
collectionName 集合名称最大24个字符,支持小写字母、数字和下划线的组合 true string
namespace 命名空间最大12个字符,支持小写字母、数字和下划线的组合 true string
sampleData 扩展字段 false array FieldKeyValue
key 字段名,与创建集合时给定的字段名一致 true string
value 字段值与创建集合时给定的类型一致若为字符串最大为512个字符 false object
sampleId 样本ID最大32个字符,支持小写字母、数字和下划线的组合 true string

响应状态:

状态码 说明 schema
200 OK ResponseInfo«boolean»
201 Created
401 Unauthorized
403 Forbidden
404 Not Found

响应参数:

参数名称 参数说明 类型 schema
code 返回代码 integer(int32) integer(int32)
data 数据信息 boolean
message 返回信息 string

响应示例:

{
	"code": 0,
	"data": false,
	"message": ""
}

03、人脸数据管理

1、创建一个人脸数据

接口地址:/visual/face/create

请求方式:POST

请求数据类型:application/x-www-form-urlencoded,application/json

响应数据类型:*/*

接口描述:

请求示例:

{
  "collectionName": "",
  "faceData": [
    {
      "key": "",
      "value": {}
    }
  ],
  "faceScoreThreshold": 0,
  "imageBase64": "",
  "maxConfidenceThresholdWithOtherSample": 0,
  "minConfidenceThresholdWithThisSample": 0,
  "namespace": "",
  "sampleId": ""
}

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 schema
faceDataReqVo FaceDataReqVo body true FaceDataReqVo FaceDataReqVo
collectionName 集合名称最大24个字符,支持小写字母、数字和下划线的组合 true string
faceData 扩展字段 false array FieldKeyValue
key 字段名,与创建集合时给定的字段名一致 true string
value 字段值与创建集合时给定的类型一致若为字符串最大为512个字符 false object
faceScoreThreshold 人脸质量分数阈值,范围:[0,100]默认0。当设置为0时会默认使用当前模型的默认值该方法为推荐使用方式 false number(float)
imageBase64 图像Base64编码值 true string
maxConfidenceThresholdWithOtherSample 当前样本与其他样本的人脸相似度的最大阈值,范围:[0,100]默认0。当设置为0时表示不做类间相似度判断逻辑,开启后对效率有较大影响 false number(float)
minConfidenceThresholdWithThisSample 当前样本的人脸相似度的最小阈值,范围:[0,100]默认0。当设置为0时表示不做类间相似度判断逻辑,开启后对效率有较大影响 false number(float)
namespace 命名空间最大12个字符,支持小写字母、数字和下划线的组合 true string
sampleId 样本ID最大32个字符,支持小写字母、数字和下划线的组合 true string

响应状态:

状态码 说明 schema
200 OK ResponseInfo«FaceDataRepVo»
201 Created
401 Unauthorized
403 Forbidden
404 Not Found

响应参数:

参数名称 参数说明 类型 schema
code 返回代码 integer(int32) integer(int32)
data 数据信息 FaceDataRepVo FaceDataRepVo
collectionName 集合名称最大24个字符,支持小写字母、数字和下划线的组合 string
faceData 扩展字段 array FieldKeyValue
key 字段名,与创建集合时给定的字段名一致 string
value 字段值与创建集合时给定的类型一致若为字符串最大为512个字符 object
faceId 人脸ID string
faceScore 人脸人数质量 number(float)
namespace 命名空间最大12个字符,支持小写字母、数字和下划线的组合 string
sampleId 样本ID最大32个字符,支持小写字母、数字和下划线的组合 string
message 返回信息 string

响应示例:

{
	"code": 0,
	"data": {
		"collectionName": "",
		"faceData": [
			{
				"key": "",
				"value": {}
			}
		],
		"faceId": "",
		"faceScore": 0,
		"namespace": "",
		"sampleId": ""
	},
	"message": ""
}

2、根据条件删除人脸数据

接口地址:/visual/face/delete

请求方式:GET

请求数据类型:application/x-www-form-urlencoded

响应数据类型:*/*

接口描述:

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 schema
namespace 命名空间 query true string
collectionName 集合名称 query true string
sampleId 样本ID query true string
faceId 人脸ID query true string

响应状态:

状态码 说明 schema
200 OK ResponseInfo«boolean»
401 Unauthorized
403 Forbidden
404 Not Found

响应参数:

参数名称 参数说明 类型 schema
code 返回代码 integer(int32) integer(int32)
data 数据信息 boolean
message 返回信息 string

响应示例:

{
	"code": 0,
	"data": false,
	"message": ""
}

04、人脸搜索服务

1、人脸搜索M:N

接口地址:/visual/search/do

请求方式:POST

请求数据类型:application/x-www-form-urlencoded,application/json

响应数据类型:*/*

接口描述:

请求示例:

{
  "collectionName": "",
  "confidenceThreshold": 0,
  "faceScoreThreshold": 0,
  "imageBase64": "",
  "limit": 0,
  "maxFaceNum": 0,
  "namespace": ""
}

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 schema
faceSearchReqVo 人脸搜索参数 body true FaceSearchReqVo FaceSearchReqVo
collectionName 集合名称 true string
confidenceThreshold 人脸匹配分数阈值,范围:[-100,100]默认0 false number(float)
faceScoreThreshold 人脸质量分数阈值,范围:[0,100]默认0。当设置为0时会默认使用当前模型的默认值该方法为推荐使用方式 false number(float)
imageBase64 图像Base64编码值 true string
limit 最大搜索条数默认5 false integer(int32)
maxFaceNum 对输入图像中多少个人脸进行检索比对默认5 false integer(int32)
namespace 命名空间 true string

响应状态:

状态码 说明 schema
200 OK ResponseInfo«List«FaceSearchRepVo»»
201 Created
401 Unauthorized
403 Forbidden
404 Not Found

响应参数:

参数名称 参数说明 类型 schema
code 返回代码 integer(int32) integer(int32)
data 数据信息 array FaceSearchRepVo
faceScore 人脸分数:[0,100] number(float)
location 人脸位置信息 FaceLocation FaceLocation
h 人脸高度 integer
w 人脸宽度 integer
x 左上角x坐标 integer
y 左上角y坐标 integer
match 匹配的人脸列表 array SampleFaceVo
confidence 转换后的置信度:[-100,100],值越大,相似度越高。 number
faceData 人脸扩展的额外数据 array FieldKeyValue
key 字段名,与创建集合时给定的字段名一致 string
value 字段值与创建集合时给定的类型一致若为字符串最大为512个字符 object
faceId 人脸ID string
faceScore 人脸分数:[0,100] number
sampleData 样本扩展的额外数据 array FieldKeyValue
key 字段名,与创建集合时给定的字段名一致 string
value 字段值与创建集合时给定的类型一致若为字符串最大为512个字符 object
sampleId 样本ID string
message 返回信息 string

响应示例:

{
	"code": 0,
	"data": [
		{
			"faceScore": 0,
			"location": {
				"h": 0,
				"w": 0,
				"x": 0,
				"y": 0
			},
			"match": [
				{
					"confidence": 0,
					"faceData": [
						{
							"key": "",
							"value": {}
						}
					],
					"faceId": "",
					"faceScore": 0,
					"sampleData": [
						{
							"key": "",
							"value": {}
						}
					],
					"sampleId": ""
				}
			]
		}
	],
	"message": ""
}

05、人脸比对服务

1、人脸比对1:1

接口地址:/visual/compare/do

请求方式:POST

请求数据类型:application/x-www-form-urlencoded,application/json

响应数据类型:*/*

接口描述:

请求示例:

{
  "faceScoreThreshold": 0,
  "imageBase64A": "",
  "imageBase64B": "",
  "needFaceInfo": false
}

请求参数:

参数名称 参数说明 请求类型 是否必须 数据类型 schema
faceCompareReqVo FaceCompareReqVo body true FaceCompareReqVo FaceCompareReqVo
faceScoreThreshold 人脸质量分数阈值,范围:[0,100]默认0。当设置为0时会默认使用当前模型的默认值该方法为推荐使用方式 false number(float)
imageBase64A 图像A的Base64编码值 true string
imageBase64B 图像B的Base64编码值 true string
needFaceInfo 是否需要人脸信息,默认为:true false boolean

响应状态:

状态码 说明 schema
200 OK ResponseInfo«FaceCompareRepVo»
201 Created
401 Unauthorized
403 Forbidden
404 Not Found

响应参数:

参数名称 参数说明 类型 schema
code 返回代码 integer(int32) integer(int32)
data 数据信息 FaceCompareRepVo FaceCompareRepVo
confidence 余弦距离转换后的置信度:[-100,100],值越大,相似度越高。 number(float)
distance 向量欧式距离:>=0 number(float)
faceInfo 人脸信息,参数needFaceInfo=false时值为null CompareFace CompareFace
faceScoreA A图片人脸分数:[0,100] number
faceScoreB B图片人脸分数:[0,100] number
locationA A图片人脸位置信息 FaceLocation FaceLocation
h 人脸高度 integer
w 人脸宽度 integer
x 左上角x坐标 integer
y 左上角y坐标 integer
locationB B图片人脸位置信息 FaceLocation FaceLocation
h 人脸高度 integer
w 人脸宽度 integer
x 左上角x坐标 integer
y 左上角y坐标 integer
message 返回信息 string

响应示例:

{
	"code": 0,
	"data": {
		"confidence": 0,
		"distance": 0,
		"faceInfo": {
			"faceScoreA": 0,
			"faceScoreB": 0,
			"locationA": {
				"h": 0,
				"w": 0,
				"x": 0,
				"y": 0
			},
			"locationB": {
				"h": 0,
				"w": 0,
				"x": 0,
				"y": 0
			}
		}
	},
	"message": ""
}