功能描述
对数据集内文件进行多种跨模态检索，支持进行以文搜图、以图搜图、以文搜文档等多种检索方式。
当进行图片检索时，支持输入自然语言文本或者图片，在指定数据集中检索出符合输入的文本语义或图片内容相似的图片。
当进行文档检索时，支持输入自然语言文本，在指定数据集中检索出符合输入的文本语义相似的文本段及其所归属的文档。
授权说明
服务开通
首次使用该功能时将默认为您开通数据万象，同时该存储桶将自动绑定数据万象，无需角色授权，即可直接使用。
注意：
智能检索控制台需开通白名单才可使用，同时文档检索功能当前处于内测阶段，若您需使用控制台的文档检索相关功能，需开通白名单，可 联系我们 进行处理。
数据万象绑定后，如果您手动对存储桶进行数据万象的解绑操作，将无法继续使用该功能。
使用限制
使用检索前需要先完成 创建数据集。
仅支持北京、上海、成都地域，即请求 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
说明：
请求头
请求体
请求体示例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}}]}}
请求体示例3：文档检索搭配元数据过滤
{"DatasetName": "docsearch","Mode": "text","Templates" : "DocSearch","SearchText": "包含一棵大树的文档","Limit": 10,"MatchThreshold": 1,"Filter": {"$and": [{"MediaType": {"$in": ["image", "document"]}},{"Size": {"$gt": 123}}]}}
请求参数
参数名称 | 描述 | 类型 | 是否必选 |
DatasetName | 数据集名称，同一个账户下唯一 | String | 是 |
Mode | 指定检索的输入类型，默认值为 pic。有效值为： pic：表示输入图片进行以图搜图的检索 text：表示输入文本进行检索，支持输入自然语言，例如“包含一棵大树的图片” | String | 否 |
Templates | 指定输出的数据类型，有效值为： ImageSearch：进行图像检索，输出的是图片类型的结果 DocSearch：进行文档检索，输出的是文档类型的结果(Mode 必须为 text) | String | 是 |
SearchURIs | 资源标识字段。当前仅支持 COS 存储桶，字段规则：cos:/// ，其中 BucketName 表示 COS 存储桶名称，Path 表示资源路径，例如：cos://examplebucket-1250000000/test.jpg | String Array | 否 当 Mode 为 pic 时必选 当使用的 算子模板 是图像搜索模板，并进行“以图搜图”操作时必选 |
SearchText | 检索语句。最多支持60个 UTF-8编码字符。例如“包含一棵大树的图片” | String | 否 当 Mode 为 text 时必选 当使用的 算子模板 是图像搜索模板，并进行“以文搜图”操作时必选 使用文档类 Template 时必选 |
Limit | 返回相关图片的数量，默认值为10，取值范围为(0, 100] | Integer | 否 |
MatchThreshold | 限制返回图片或文档的最低相关度分数，只有超过 MatchThreshold 值的图片才会返回。默认值为0，推荐值为80，取值范围为(0, 100] 例如：设置 MatchThreshold 的值为80，则检索结果中仅会返回相关度分数大于等于80分的图片或文档 | Integer | 否 |
Filter | Container | 否 |
响应
响应头
响应体
响应体示例1：以图搜图、以文搜图返回结果
{"ImageResult": [{"URI": "cos://examplebucket-1250000000/test.jpg","Score": 99}],"RequestId": "NjYwYzEwYjhfNGQ2ODk0MGJfMjcxxxx"}
响应体示例2：文档检索返回结果
{"DocResult": [{"Text": "2025年整体财务数据如图:{Image_0}; 增长数据如图:{Image_1}","Score": 90,"URI": "cos://examplebucket-1250000000/test.docx","TextPage": 10,"ImageUrls": {"Image_0": "img123","Image_1": "img456"}}],"RequestId": "NjYwYzEwYjhfNGQ2ODk0MGJfMjcxxxx"}
响应包体具体数据内容如下：
参数名称 | 类型 | 描述 |
RequestId | String | 请求 ID |
ImageResult | Container Array | 图像检索识别结果信息列表 |
DocResult | Container Array | 文档检索识别结果信息列表 |
ImageResult 节点内容：
参数名称 | 类型 | 描述 |
URI | String | 资源标识字段，表示需要建立索引的文件地址 |
Score | Integer | 相关图片匹配得分 |
DocResult 节点内容：
参数名称 | 类型 | 描述 |
URI | String | 文档在对象存储中的统一资源标识符（URI） |
TextPage | Integer | 文档中匹配内容所在的页码（仅部分结果包含） |
Score | Integer | 搜索结果的相关度评分，数值越高表示相关性越强 |
Text | String | 匹配的原始文本内容，可能包含占位符（如 {Image_0}） |
ImageUrls | Container | 图片占位符到实际图片标识符（或 URL）的映射集 |
ImageUrls 节点内容：
参数名称 | 类型 | 描述 |
Image_0 | string | 图片标识符（或 URL） |
Image_1 | string | 图片标识符（或 URL） |
实际案例
请求：图片检索搭配元数据过滤
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:test-1234567890.ci.ap-beijing.myqcloud.comContent-Length: 166Content-Type: application/xml<Request><DatasetName>imagesearch</DatasetName><Mode>pic</Mode><Templates>ImageSearch</Templates><SearchURIs><URI>cos://examplebucket-1250000000/test.jpg</URI></SearchURIs><Limit>10</Limit><MatchThreshold>1</MatchThreshold><Filter><$and><Condition><MediaType><$in><Value>image</Value><Value>document</Value></$in></MediaType></Condition><Condition><Size><$gt>123</$gt></Size></Condition></$and></Filter></Request>
响应
HTTP/1.1 200 OKContent-Type: application/xmlContent-Length: 230Connection: keep-aliveDate: Mon, 28 Jun 2022 15:23:12 GMTServer: tencent-cix-ci-request-id: NjMxMDJhYTNfMThhYTk0MGFfYmU1OV8zZjc=<Response><ImageResult><Item><URI>cos://examplebucket-1250000000/test.jpg</URI><Score>99</Score></Item></ImageResult><RequestId>NjYwYzEwYjhfNGQ2ODk0MGJfMjcxxxx</RequestId></Response>
请求：进行文档检索搭配元数据过滤
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:test-1234567890.ci.ap-beijing.myqcloud.comContent-Length: 166Content-Type: application/xml<Request><DatasetName>docsearch</DatasetName><Mode>text</Mode><Templates>DocSearch</Templates><SearchText>包含一棵大树的文档</SearchText><Limit>10</Limit><MatchThreshold>1</MatchThreshold><Filter><$and><Condition><MediaType><$in><Value>image</Value><Value>document</Value></$in></MediaType></Condition><Condition><Size><$gt>123</$gt></Size></Condition></$and></Filter></Request>
响应
HTTP/1.1 200 OKContent-Type: application/xmlContent-Length: 230Connection: keep-aliveDate: Mon, 28 Jun 2022 15:23:12 GMTServer: tencent-cix-ci-request-id: NjMxMDJhYTNfMThhYTk0MGFfYmU1OV8zZjc=<Response><DocResult><Item><Text>2025年整体财务数据如图:{Image_0}; 增长数据如图:{Image_1}</Text><Score>90</Score><URI>cos://examplebucket-1250000000/test.docx</URI><TextPage>10</TextPage><ImageUrls><Image_0>img123</Image_0><Image_1>img456</Image_1></ImageUrls></Item></DocResult><RequestId>NjYwYzEwYjhfNGQ2ODk0MGJfMjcxxxx</RequestId></Response>
错误码
错误码 | 错误信息 | 说明 |
InvalidArgument | Group not exists | 图库不存在 |
InvalidArgument | Image not exists | 图片不存在 |
InvalidArgument | Person not exists | 人员不存在 |
InvalidArgument | Group already exists | 图库已存在 |
InvalidArgument | Params is invalid | 非法请求参数 |
InvalidArgument | Unable to obtain vector feature information | 无法获取向量特征信息 |
InvalidArgument | Input image's size exceeded limit | 图片大小超限 |
InvalidArgument | File format not supported | 文件格式不支持 |
InvalidArgument | Input image's width or height exceeded limit | 图片宽高超限 |
InvalidArgument | Image decode failed | 图片解码失败 |
InvalidArgument | Image encode failed | 图片编码失败 |
InvalidArgument | Text length exceed | 文本长度超限 |
InvalidArgument | Dataset template invalid | 数据集模板不匹配 |
InvalidArgument | Unable to recognize face | 未提取有效人脸 |
InvalidArgument | The sceneType and moduleVersion not exists | 该场景模型不支持 |
InvalidArgument | Invalid object | 下载对象失败 |
InternalError | Request limit exceed | 内部错误，请稍后重试 |
InternalError | Data Exception | 内部错误，请稍后重试 |
InternalError | System Overload | 内部错误，请稍后重试 |
InvalidArgument | Parse Filter Fail | 解析标量过滤条件失败 |
InvalidArgument | Filter Exceeds Limit | 标量过滤条件数量超限 |
InvalidArgument | The size of image exceeds the limit | 图片大小超限 |
InvalidArgument | The number of personnel faces exceeds the limit | 人脸数量超限 |
InternalError | Failed to parse embedding service response | 内部错误，请稍后重试 |
InternalError | Request rate limited | 请求速率超限 |
