Prediction クエリを使用したテキスト、画像、または動画による検索 - OpenSearch

説明

予測クエリは、Vector Search Edition の組み込みベクトル化モデルを使用して、テキスト、画像、または動画をベクトルデータに変換します。その後、元のテキスト、画像、または動画を使用してデータを検索できます。

注：すでにベクトルデータがあり、それを直接 Vector Search Edition インスタンスにインポートして取得したい場合は、「ベクトルクエリ」をご参照ください。

URL

/vector-service/inference-query

サンプル 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` プレフィックスを追加してください。

例 (ヘッダーに追加)：

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

リクエスト本文パラメーター

パラメーター名	説明	デフォルト	タイプ	必須
tableName	クエリ対象のテーブル名。	None	string	はい
indexName	クエリ対象のインデックス名。	最初に設定されたインデックス	string	いいえ
content	予測用のデータ。	None	string	はい
contentType	動画予測のデータ型。有効値： text、image、video_uri、video_base64	None	string	いいえ
modal	ベクトル化モデル。有効値： text：テキストによるテキスト検索およびテキストによる画像検索に使用します。 image：画像による検索に使用します。 video：テキストによる動画検索、画像による動画検索、および動画による動画検索に使用します。	None	string	はい
videoFrameTopK	取得するフレーム数。	100	int	いいえ
namespace	クエリ対象のベクトルの名前空間。	""	string	いいえ
topK	返される結果の数。	100	int	いいえ
includeVector	ドキュメントにベクトル情報を返すかどうかを指定します。	false	bool	いいえ
outputFields	返すフィールドのリスト。	[]	list[string]	いいえ
order	ソート順。`ASC`：昇順。`DESC`：降順。	ASC	string	いいえ
searchParams	クエリパラメーター。 Qc アルゴリズムパラメーター Hnsw アルゴリズムパラメーター	""	string	いいえ
filter	フィルター式。	""	string	いいえ
scoreThreshold	フィルタリング用のスコアしきい値。ユークリッド距離を使用する場合、スコアが `scoreThreshold` 未満の結果のみが返されます。内積を使用する場合、スコアが `scoreThreshold` より大きい結果のみが返されます。	デフォルトではフィルタリングなし	float	いいえ

レスポンスパラメータ

フィールド名	説明	タイプ
result	結果のリストです。	list[Item]
totalCount	結果リスト内のアイテム数です。	int
totalTime	エンジンがリクエストを処理するのに要した時間です。単位はミリ秒です。	float
errorCode	エラーコードです。このフィールドはエラーが発生した場合にのみ返されます。	int
errorMsg	エラーメッセージです。このフィールドはエラーが発生した場合にのみ返されます。	string

項目の定義

フィールド名	説明	タイプ
score	距離スコア。	float
fields	フィールド名とそれに対応する値。	map<string, FieldType>
vector	ベクトル値。	リスト[浮動]
id	プライマリキーの値。型は、定義されたフィールドの型と同じです。	FieldType
namespace	ベクターの名前空間です。このフィールドは、名前空間が設定されている場合に返されます。	文字列

例

テキストエンベディングの取得

リクエスト本文：

{
  "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
}

画像のベクトル化

テキストによる画像検索:

リクエスト本文：

{
  "tableName": "gist",
  "indexName": "test",
  "content": "Bicycle",
  "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
}

画像で検索:

リクエスト本文：

{
  "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
}

被写体識別

リクエストボディ：
`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` パラメーターは、イメージ内の主題エリアを指定します。4 つの数字は、主題エリアの左上の点の x 座標と y 座標、幅、高さを表します。
レスポンス：
```
{
 "result":[
 {
 "id": 1,
 "score":1.0508723258972169,
 "vector": [0.1, 0.2, 0.3]
 }
 ],
 "__meta__": {
 "__range__": "100,100,60,70;",
 }
 "totalCount":1,
 "totalTime":2.943
}
```
注:
- `__range__` フィールドは、`modal` パラメーターが `image` に設定されている主題識別クエリの場合にのみ返されます。
- __range__ は、イメージ内の主題エリアを指定します。4 つの数字は、主題エリアの左上の点の x 座標と y 座標、幅、高さを表します。
- モデルが複数の主題を検出した場合、__range__ フィールドには、モデルのスコアの降順でソートされた主題エリアのリストが含まれます。デフォルトでは、クエリはリスト内の最初の主題に対応する結果を返します。

テキストによるビデオ取得

リクエスト本文：

{
  "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。

リクエスト本文：
```
{
  "tableName": "video",
  "content": "oss://...",
  "modal": "video",
  "topK": 3,
  "videoFrameTopK":100,
  "contentType":"video_uri",
  "searchParams":"{\"qc.searcher.scan_ratio\":0.01}"
}
```
入力ファイルの OSS パスを指定できます。例：`oss://bucket-name/xxx/xxx.mp4`
```
{
  "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 です。

リクエスト本文：
```
{
  "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 エンコードされたイメージデータを、image パラメーターに 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
}