使用預測查詢API通過文本或圖片進行向量檢索-智能OpenSearch OpenSearch-阿里雲 - OpenSearch

功能說明

預測查詢是指將文本、圖片、視頻通過向量檢索版內建的向量化模型產生向量資料，並通過文本、圖片或視頻進行檢索的查詢方式。

註：若您已有向量並直接將向量匯入向量檢索版執行個體中進行檢索，請參考向量查詢。

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
}