一、接口描述
·以图搜图：输入一张图片，检索出与输入图片内容相似的图片。
·以文搜图：输入自然语言文本，检索出符合输入文本语义的图片。例如输入包含人名的检索语句，即可检索出数据集内与该人相关的图片。
·混合检索-图片检索支持使用标量过滤能力，支持的字段和操作符请参见 标量过滤字段与操作符支持列表。
二、授权说明
通过子账号使用时，需要在 授权策略 的 action 中添加 ci:DatasetHybridSearch 权限。数据万象支持的所有操作接口请参见 CI action。
三、服务开通
首次使用该功能时将默认为你开通数据万象，同时该存储桶将自动绑定数据万象，无需角色授权，即可直接使用。
四、使用限制
·使用检索前需要先完成 创建数据集。
·仅支持北京、上海、成都地域，即请求 Host 中 Region 仅支持填写为 ap-beijing、ap-shanghai、ap-chengdu。
·更多使用限制，详情请参见 使用限制。
五、费用说明
有关混合检索-图片检索的费用，请参见 智能检索费用。
六、请求示例
POST /datasetquery/hybridsearch HTTP/1.1Host: <AppId>.ci.<Region>.myqcloud.comAuthorization: Auth StringContent-Length: xxxContent-Type: application/jsonAccept: application/json
注意：说明：
注意：Authorization: Auth String，详情请参见 请求签名 文档。
七、请求头
此接口仅使用公共请求头部，详情请参见 公共请求头部 文档。
八、请求体
请求体示例1：以图搜图搭配标量过滤
{ "DatasetName": "imagesearch", "Mode": "pic", "Templates": "ImageSearch", "SearchURIs": ["cos://examplebucket-1250000000/test.jpg"], "Limit": 10, "MatchThreshold": 1, "Filter": { "$and": [{ "MediaType": { "$in": ["image", "document"] } }, { "Size": { "$gt": 123 } } ] }}
请求体示例2：以文搜图搭配标量过滤
{ "DatasetName": "imagesearch", "Mode": "text", "Templates" : "ImageSearch", "SearchText": "包含一棵大树的图片", "Limit": 10, "MatchThreshold": 1, "Filter": { "$and": [{ "MediaType": { "$in": ["image", "document"] } }, { "Size": { "$gt": 123 } } ] }}
九、请求参数
| 参数名称 | 描述 | 类型 | 是否必选 |
| DatasetName | 数据集名称，同一个账户下唯一 | String | 是 |
| Mode | 指定检索的输入类型，默认值为 pic。有效值为：pic：表示输入图片进行以图搜图的检索text：表示输入文本进行以文搜图的检索，支持输入自然语言，例如“包含一棵大树的图片”，也支持输入名人姓名检索该名人的相关图片 | String | 否 |
| Templates | 指定输出的数据类型，有效值为：ImageSearch：进行图像检索，输出图片类型的结果，支持 pic 与 text 两种模式FullImageSearch：进行完整图像检索，输出图片类型的结果（Mode 必须为 text） | String | 是 |
| SearchURIs | 资源标识字段。当前仅支持 COS 存储桶，字段规则：cos://<BucketName>/<Path>，其中 BucketName 表示 COS 存储桶名称，Path 表示资源路径，例如：cos://examplebucket-1250000000/test.jpg | String Array | 否，当 Mode 为 pic 时必选 |
| SearchText | 检索语句。最多支持60个 UTF-8 编码字符。例如“包含一棵大树的图片”，或某位名人的姓名 | String | 否，当 Mode 为 text 时必选 |
| Limit | 返回相关图片的数量，默认值为10，取值范围为 (0, 100] | Integer | 否 |
| MatchThreshold | 限制返回图片的最低相关度分数，只有大于或等于 MatchThreshold 值的图片才会返回。默认值为 0，取值范围为 (0, 100]例如：设置 MatchThreshold 的值为80，则检索结果中仅会返回相关度分数大于等于80分的图片 | Integer | 否 |
| Filter | 简单查询参数条件，可选参数，可以包含三个条件。关于数据格式，请参见 标量过滤字段与操作符支持列表 | Container | 否 |
十、响应头
此接口仅返回公共响应头部，详情请参见 公共响应头部 文档。
十一、响应体
响应体示例：以图搜图、以文搜图返回结果
{ "ImageResult": [{ "URI": "cos://examplebucket-1250000000/test.jpg", "Score": 99 }], "RequestId": "NjYwYzEwYjhfNGQ2ODk0MGJfMjcxxxx"}
响应包体具体数据内容如下：
| 参数名称 | 类型 | 描述 |
| RequestId | String | 请求 ID |
| ImageResult | Container Array | 图像检索识别结果信息列表 |
ImageResult 节点内容：
| 参数名称 | 类型 | 描述 |
| URI | String | 资源标识字段，表示匹配图片的 COS 地址 |
| Score | Integer | 相关图片匹配得分 |
十二、案例一：以图搜图
以一张图片作为输入，检索数据集内与其内容相似的图片。以图搜图时，若数据集内包含与输入图片完全一致的图片，其匹配得分可达100。
请求：
POST /datasetquery/hybridsearch HTTP/1.1Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=****************************************Host: 1234567890.ci.ap-beijing.myqcloud.comContent-Length: 166Content-Type: application/jsonAccept: application/json{ "DatasetName": "imagesearch", "Mode": "pic", "Templates": "ImageSearch", "SearchURIs": ["cos://examplebucket-1250000000/query.jpg"], "Limit": 10, "MatchThreshold": 80}
响应：
HTTP/1.1 200 OKContent-Type: application/jsonServer: tencent-cix-ci-request-id: NjMxMDJhYTNfMThhYTk0MGFfYmU1OV8zZjc={ "ImageResult": [{ "URI": "cos://examplebucket-1250000000/query.jpg", "Score": 100 }], "RequestId": "NjYwYzEwYjhfNGQ2ODk0MGJfMjcxxxx"}
十三、案例二：以文搜图（输入自然语言）
以自然语言文本作为输入，检索数据集内符合该文本语义的图片。例如输入“穿西装的男性正面照”，返回具备相应语义特征的多张图片，并按相关度分数降序排列。
请求：
POST /datasetquery/hybridsearch HTTP/1.1Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=****************************************Host: 1234567890.ci.ap-beijing.myqcloud.comContent-Type: application/jsonAccept: application/json{ "DatasetName": "imagesearch", "Mode": "text", "Templates": "ImageSearch", "SearchText": "穿西装的男性正面照", "Limit": 10, "MatchThreshold": 50}
响应：
HTTP/1.1 200 OKContent-Type: application/jsonServer: tencent-ci{ "ImageResult": [ { "URI": "cos://examplebucket-1250000000/image_01.webp", "Score": 59 }, { "URI": "cos://examplebucket-1250000000/image_02.webp", "Score": 58 }, { "URI": "cos://examplebucket-1250000000/image_03.webp", "Score": 58 }, { "URI": "cos://examplebucket-1250000000/image_04.webp", "Score": 57 }, { "URI": "cos://examplebucket-1250000000/image_05.webp", "Score": 56 } ], "RequestId": "NmExZDJiMTBfMjYyOTVhMTVfMTYyYzk1XzIxN2E="}
十四、案例三：以文搜图（输入人名）
以文搜图支持直接输入包含人名的检索语句，检索数据集内与该人相关的图片。
请求：
{ "DatasetName": "imagesearch", "Mode": "text", "Templates": "ImageSearch", "SearchText": "张三", "Limit": 10, "MatchThreshold": 50}
响应：
{ "ImageResult": [ { "URI": "cos://examplebucket-1250000000/person_01.webp", "Score": 88 }, { "URI": "cos://examplebucket-1250000000/person_02.webp", "Score": 85 } ], "RequestId": "NmExZDJiMGVfMjYyOTVhMTVfMTYyYzk1XzIxNzk="}
注意：以图搜图（自身命中）的匹配得分可达100，而以文搜图的语义匹配得分通常偏低。建议初次调试时将 MatchThreshold 从30 ~ 40开始逐步调整，避免默认较高阈值过滤掉全部结果。
十五、错误码
该请求操作无特殊错误信息，常见的错误信息请参见 错误码 文档。