混合检索-图片检索
下载
聚焦模式
字号
接口描述
本接口对数据集内的图片文件进行图片检索，基于
DatasetHybridSearch 接口，支持以图搜图、以文搜图两种方式：以图搜图：输入一张图片，检索出与输入图片内容相似的图片。
以文搜图：输入自然语言文本，检索出符合输入文本语义的图片。例如输入包含人名的检索语句，即可检索出数据集内与该人相关的图片。
混合检索-图片检索支持使用标量过滤能力，支持的字段和操作符请参见 标量过滤字段与操作符支持列表。
授权说明
服务开通
首次使用该功能时将默认为您开通数据万象，同时该存储桶将自动绑定数据万象，无需角色授权，即可直接使用。
使用限制
使用检索前需要先完成 创建数据集。
仅支持雅加达地域，即请求 Host 中 Region 仅支持填写为
ap-jakarta。更多使用限制，详情请参见 使用限制。
费用说明
请求
请求示例
POST /datasetquery/hybridsearch HTTP/1.1Host: <AppId>.ci.ap-jakarta.myqcloud.comAuthorization: Auth StringContent-Length: xxxContent-Type: application/jsonAccept: application/json
说明：
请求头
请求体
请求体示例1：以图搜图搭配标量过滤
{"DatasetName": "imagesearch","Mode": "pic","Templates": "ImageSearch","SearchURIs": ["cos://examplebucket-1250000000/test.jpg"],"Limit": 10,"MatchThreshold": 1,"Filter": {"$and": [{"MediaType": {"$in": ["image"]}},{"Size": {"$gt": 123}}]}}
请求体示例2：以文搜图搭配标量过滤
{"DatasetName": "imagesearch","Mode": "text","Templates" : "ImageSearch","SearchText": "包含一棵大树的图片","Limit": 10,"MatchThreshold": 1,"Filter": {"$and": [{"MediaType": {"$in": ["image"]}},{"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-jakarta.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-jakarta.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开始逐步调整，避免默认较高阈值过滤掉全部结果。
错误码
文档反馈