调用预测查询API实现多模态向量检索-智能开放搜索OpenSearch-阿里云-智能开放搜索 OpenSearch(Open Search)-阿里云帮助中心

功能说明

预测查询是指将文本、图片、视频通过向量检索版内置的向量化模型生成向量数据，并通过文本、图片或视频进行检索的查询方式。

注：若您已有向量并直接将向量导入向量检索版实例中进行检索，请参考向量查询。

URL

/vector-service/inference-query

以上 URL 省略了请求Header参数及编码等因素。
以上 URL 中省略了访问应用的 host 地址。
以上URL 中拼接的所有查询参数，请查看下方“查询参数”的参数定义、使用方式及样例。

请求协议

HTTP

请求方式

POST

支持格式

JSON

签名机制

可用以下方法计算签名（authorization）

参数	类型	描述
accessUserName	string	用户名，可在实例详情>网络信息模块查看
accessPassWord	string	密码，可在实例详情>网络信息模块修改

import com.aliyun.darabonba.encode.Encoder;
import com.aliyun.darabonbastring.Client;

public class GenerateAuthorization {
 public static void main(String[] args) throws Exception {
 String accessUserName = "username";
 String accessPassWord = "password";
 String realmStr = "" + accessUserName + ":" + accessPassWord + "";
 String authorization = Encoder.base64EncodeToString(Client.toBytes(realmStr, "UTF-8"));
 System.out.println(authorization);
 }
}

authorization正确返回格式：

cm9vdDp******mdhbA==

使用HTTP请求设置authorization参数需加上Basic前缀

示例：（在header中加入）

authorization: Basic cm9vdDp******mdhbA==

请求body参数

参数名称	描述	默认值	类型	是否必须
tableName	查询的表名	无	string	是
indexName	查询的索引名称	配置的第一个索引	string	否
content	需要预测的数据。非融合向量场景使用此参数	无	string	是（非融合向量场景）
contents	需要预测的数据列表。融合向量场景使用此参数，支持传入多个不同模态的内容	无	list[string]	是（融合向量场景）
contentType	预测数据类型：text（文本）、image_encode（Base64编码的图片）、video_uri（视频的OSS路径）、video_encode（Base64编码的视频）。融合向量场景下支持多个类型用逗号分隔，如 `text,image_encode`，与`contents`中的内容一一对应	无	string	否
modal	向量化模型的模态类型：text（以文搜文/以文搜图）、image（以图搜图）、video（视频检索，支持文本、图片、视频搜视频）、fusion（融合向量检索，将多个字段编码为单一向量进行跨模态检索）	无	string	是
videoFrameTopK	召回帧的数量	100	int	否
namespace	查询向量的空间	""	string	否
topK	返回个数	100	int	否
includeVector	是否返回文档中的向量信息	false	bool	否
outputFields	需要返回值的字段列表	[]	list[string]	否
order	排序顺序，ASC：升序，DESC：降序	ASC	string	否
searchParams	查询参数： QcSearcher HNSW（Hierarchical Navigable Small World）配置	""	string	否
filter	过滤表达式	""	string	否
scoreThreshold	分数过滤。使用欧式距离时，只返回小于scoreThreshold的结果。使用内积时，只返回大于scoreThreshold的结果	默认不过滤	float	否

返回参数

字段名称	描述	类型
result	结果列表	list[Item]
totalCount	result中的个数	int
totalTime	引擎处理耗时，单位ms	float
errorCode	错误码，有错误时才有该字段	int
errorMsg	错误信息，有错误时才有该字段	string

item定义

字段名称	描述	类型
score	距离分	float
fields	字段名称和对应的值	map<string, FieldType>
vector	向量值	list[float]
id	主键值，类型为所定义的字段类型	FieldType
namespace	向量的名称空间，如果设置了namespace会返回该字段	string

API实际返回的结果中可能包含附加字段（如__source__、coveredPercent等），这些字段用于内部调试，不影响业务逻辑。

示例

文本向量化检索

请求body：

{
  "tableName": "gist",
  "indexName": "test",
  "content": "hello",
  "modal": "text",
  "topK": 3,
  "searchParams":"{\"qc.searcher.scan_ratio\":0.01}",
  "includeVector": true
}

返回参数：

{
  "result":[
    {
      "id": 1,
      "score":1.0508723258972169,
      "vector": [0.1, 0.2, 0.3]
    },
    {
      "id": 2,
      "score":1.0329746007919312,
      "vector": [0.2, 0.2, 0.3]
    },
    {
      "id": 3,
      "score":0.980593204498291,
      "vector": [0.3, 0.2, 0.3]
    }
  ],
  "totalCount":3,
  "totalTime":2.943
}

图片向量化

以文搜图：

请求body：

{
  "tableName": "gist",
  "indexName": "test",
  "content": "自行车",
  "modal": "text",
  "topK": 3,
  "searchParams":"{\"qc.searcher.scan_ratio\":0.01}",
  "includeVector": true
}

返回参数：

{
  "result":[
    {
      "id": 1,
      "score":1.0508723258972169,
      "vector": [0.1, 0.2, 0.3]
    },
    {
      "id": 2,
      "score":1.0329746007919312,
      "vector": [0.2, 0.2, 0.3]
    },
    {
      "id": 3,
      "score":0.980593204498291,
      "vector": [0.3, 0.2, 0.3]
    }
  ],
  "totalCount":3,
  "totalTime":2.943
}

以图搜图：

请求body：

{
  "tableName": "gist",
  "indexName": "test",
  "content": "base64编码的图片",
  "modal": "image",
  "topK": 3,
  "searchParams":"{\"qc.searcher.scan_ratio\":0.01}",
  "includeVector": true
}

返回参数：

{
    "totalCount": 5,
    "result": [
        {
            "id": 5,
            "score": 1.103209137916565
        },
        {
            "id": 3,
            "score": 1.1278988122940064
        },
        {
            "id": 2,
            "score": 1.1326735019683838
        }
    ],
    "totalTime": 242.615
}

主体识别

请求body：

未传入range：

{
 "tableName": "gist",
 "indexName": "test",
 "content": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQ",
 "modal": "image",
 "searchParams": "{\"crop\": true}",
 "topK": 3,
 "includeVector": true
}

注："crop":true表示使用主体进行查询，未传入range则会调用主体识别模型。

传入range：

{
 "tableName": "gist",
 "indexName": "test",
 "content": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQ",
 "modal": "image",
 "searchParams": "{\"crop\": true, \"range\": \"100,100,60,70\"}",
 "topK": 3,
 "includeVector": true
}

"crop":true, "range":"100,100,60,70"表示使用主体进行查询，range表示主体在图片中的区域，四个数分别表示主体区域左上角点的(x, y)坐标、宽度width和高度height。

返回参数：
```
{
 "result":[
 {
 "id": 1,
 "score":1.0508723258972169,
 "vector": [0.1, 0.2, 0.3]
 }
 ],
 "__meta__": {
 "__range__": "100,100,60,70;",
 }
 "totalCount":1,
 "totalTime":2.943
}
```
- 主体识别中modal=image时，返回参数中才会有__range__相关主体识别的内容返回。
- __range__表示主体在图片中的区域，四个数分别表示主体区域左上角点的(x, y)坐标、宽度width和高度height。
- 如果模型识别出了多个主体，__range__按照模型打分从高到低排列每个主体，且默认返回第一个主体的向量查询结果。

文本召回视频

请求body：

{
  "tableName": "video",
  "content": "hello",
  "modal": "video",
  "topK": 3,
  "videoFrameTopK":100,
  "contentType":"text",
  "searchParams":"{\"qc.searcher.scan_ratio\":0.01}"
}

返回参数：

{
  "result":[
    {
      "videoId": 1,
      "videoUri": "oss://...",
      "fields" : {
        "tag" : "demo"
      },
      "clips": [{
          "queryStartTime": 5,
          "startTime": 5,
          "duration": 5,
          "queryStartFrameIndex": 150,
          "queryEndFrameIndex": 300,
          "startFrameIndex": 150,
          "endFrameIndex": 300,
          "sim": 0.8
       }]
    }
  ],
  "totalCount":1,
  "totalTime":2.943
}

视频召回视频

支持的视频格式有mp4、avi、mkv、mov、flv、webm。

请求body：

输入文件的OSS路径：

{
  "tableName": "video",
  "content": "oss://...",
  "modal": "video",
  "topK": 3,
  "videoFrameTopK":100,
  "contentType":"video_uri",
  "searchParams":"{\"qc.searcher.scan_ratio\":0.01}"
}

输入Base64编码的视频：

{
  "tableName": "video",
  "content": "data:video/mp4;base64,AAAAIGZ0eXBtcDQyAAABAGlxxxxxxx",
  "modal": "video",
  "topK": 3,
  "videoFrameTopK":100,
  "contentType":"video_encode",
  "searchParams":"{\"qc.searcher.scan_ratio\":0.01}"
}

格式为data:video/{format};base64,{base64_video}，其中：

video/{format}：视频的格式，例如视频为mp4格式，则设置为video/mp4。
base64_video：视频的BASE64数据。

返回参数：

{
  "result":[
    {
      "videoId": 1,
      "videoUri": "oss://...",
      "fields" : {
        "tag" : "demo"
      },      
      "clips": [{
          "queryStartTime": 5,
          "startTime": 5,
          "duration": 5,
          "queryStartFrameIndex": 150,
          "queryEndFrameIndex": 300,
          "startFrameIndex": 150,
          "endFrameIndex": 300,
          "sim": 0.8
       }]
    }
  ],
  "totalCount":1,
  "totalTime":2.943
}

图片召回视频

支持的图片格式有png、jpeg、jpg。

请求body：
```
{
  "tableName": "video",
  "content": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAxxxxxx",
  "modal": "video",
  "topK": 3,
  "videoFrameTopK":100,
  "contentType":"image_encode", 
  "searchParams":"{\"qc.searcher.scan_ratio\":0.01}"
}
```
图片使用base64数据，将编码后的base64数据传递给content参数，格式为data:image/{format};base64,{base64_image}，其中：
- image/{format}：图像的格式，例如图片为jpg格式，则设置为image/jpeg。
- base64_image：图像的base64数据。

返回参数：

{
  "result":[
    {
      "videoId": 1,
      "videoUri": "oss://...",
      "fields" : {
        "tag" : "demo"
      },      
      "clips": [{
          "queryStartTime": 5,
          "startTime": 5,
          "duration": 5,
          "queryStartFrameIndex": 150,
          "queryEndFrameIndex": 300,
          "startFrameIndex": 150,
          "endFrameIndex": 300,
          "sim": 0.8
       }]
    }
  ],
  "totalCount":3,
  "totalTime":2.943
}

融合向量检索

融合向量检索将多个不同模态的内容（如文本和图片）通过多模态模型编码为单一向量进行检索。使用前需在表配置中完成融合向量的字段配置，请参见配置融合向量

融合向量检索与其他预测查询方式的区别：

modal参数设置为fusion。
使用contents参数（list类型）替代content参数，传入多个不同模态的内容。
contentType参数使用逗号分隔多个类型，与contents中的内容一一对应。

请求body：

{
  "tableName": "gist",
  "indexName": "test",
  "contents": ["hello", "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAxxxxxx"],
  "modal": "fusion",
  "contentType": "text,image_encode",
  "topK": 3,
  "searchParams":"{\"qc.searcher.scan_ratio\":0.01}",
  "includeVector": true
}

contents中第一个元素为文本内容"hello"，第二个元素为Base64编码的图片数据。contentType中的text和image_encode分别对应contents中两个元素的类型。

返回参数：

{
  "result":[
    {
      "id": 1,
      "score":1.0508723258972169,
      "vector": [0.1, 0.2, 0.3]
    },
    {
      "id": 2,
      "score":1.0329746007919312,
      "vector": [0.2, 0.2, 0.3]
    },
    {
      "id": 3,
      "score":0.980593204498291,
      "vector": [0.3, 0.2, 0.3]
    }
  ],
  "totalCount":3,
  "totalTime":2.943
}