帮你快速理解、总结文档立即下载
文档中心>数据万象>API 文档>智能检索 MetaInsight>多模态检索>混合检索-图片检索

混合检索-图片检索

最近更新时间：2026-07-27 18:26:32

我的收藏

本页目录：

接口描述

本接口对数据集内的图片文件进行图片检索，基于 DatasetHybridSearch 接口，支持以图搜图、以文搜图两种方式：
以图搜图：输入一张图片，检索出与输入图片内容相似的图片。
以文搜图：输入自然语言文本，检索出符合输入文本语义的图片。例如输入包含人名的检索语句，即可检索出数据集内与该人相关的图片。
混合检索-图片检索支持使用标量过滤能力，支持的字段和操作符请参见 标量过滤字段与操作符支持列表。


授权说明

通过子账号使用时，需要在 授权策略 的 action 中添加 ci:DatasetHybridSearch 权限。数据万象支持的所有操作接口请参见 CI action。

服务开通

首次使用该功能时将默认为您开通数据万象，同时该存储桶将自动绑定数据万象，无需角色授权，即可直接使用。
注意：
数据万象绑定后，如果您手动对存储桶进行数据万象的解绑操作，将无法继续使用该功能。
当前如需在图片检索中使用人名信息进行检索需开通白名单，请 联系我们。

使用限制

使用检索前需要先完成 创建数据集。
仅支持北京、上海、成都地域，即请求 Host 中 Region 仅支持填写为 ap-beijing、ap-shanghai、ap-chengdu。
更多使用限制，详情请参见 使用限制。

费用说明

有关混合检索-图片检索的费用，请参见 智能检索费用。

请求

请求示例

POST /datasetquery/hybridsearch HTTP/1.1
Host: <AppId>.ci.<Region>.myqcloud.com
Authorization: Auth String
Content-Length: xxx
Content-Type: application/json
Accept: 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.1
Authorization: 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.com
Content-Length: 166
Content-Type: application/json
Accept: application/json

{
	"DatasetName": "imagesearch",
	"Mode": "pic",
	"Templates": "ImageSearch",
	"SearchURIs": ["cos://examplebucket-1250000000/query.jpg"],
	"Limit": 10,
	"MatchThreshold": 80
}
响应：
HTTP/1.1 200 OK
Content-Type: application/json
Server: tencent-ci
x-ci-request-id: NjMxMDJhYTNfMThhYTk0MGFfYmU1OV8zZjc=

{
	"ImageResult": [{
		"URI": "cos://examplebucket-1250000000/query.jpg",
		"Score": 100
	}],
	"RequestId": "NjYwYzEwYjhfNGQ2ODk0MGJfMjcxxxx"
}

案例二：以文搜图（输入自然语言）

以自然语言文本作为输入，检索数据集内符合该文本语义的图片。例如输入“穿西装的男性正面照”，返回具备相应语义特征的多张图片，并按相关度分数降序排列。

请求：
POST /datasetquery/hybridsearch HTTP/1.1
Authorization: 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.com
Content-Type: application/json
Accept: application/json

{
	"DatasetName": "imagesearch",
	"Mode": "text",
	"Templates": "ImageSearch",
	"SearchText": "穿西装的男性正面照",
	"Limit": 10,
	"MatchThreshold": 50
}
响应：
HTTP/1.1 200 OK
Content-Type: application/json
Server: 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开始逐步调整，避免默认较高阈值过滤掉全部结果。

错误码

该请求操作无特殊错误信息，常见的错误信息请参见 错误码 文档。

中国站