このページは Cloud Translation API によって翻訳されました。

ベクトルエンベディングを使用した検索とフィルタ

MySQL | PostgreSQL | SQL Server

ベクトル検索の一般提供版を使用するには、インスタンスのメンテナンスバージョンがバージョン MYSQL_8_0_version.R20241208.01_00 以降である必要があります。ここで、バージョンはマイナーバージョン番号です。一般提供のベクトルエンベディングをサポートする新しいバージョンにインスタンスをアップグレードする方法については、インスタンスをアップグレードするをご覧ください。

この機能のパブリックプレビューバージョンのベクトルエンベディングの構文と動作については、ベクトルエンベディングを使用する（プレビュー）をご覧ください。

このページでは、ベクトルエンベディングをクエリするさまざまな方法について説明します。ANN と KNN の類似性検索の概要については、ベクトル検索をご覧ください。

近似最近傍（ANN）を検索する

ANN 検索を実行するには、SELECT 句と ORDER BY 句で approx_distance 関数を使用します。ANN 検索では LIMIT 句を使用する必要があります。approx_distance を SELECT リストに追加することで、距離値を取得することもできます。

ANN クエリには次の構文を使用します。

# Ordering by distance
SELECT title
FROM books
ORDER BY approx_distance(embedding, string_to_vector('[1,2,3]'), 'distance_measure=l2_squared')
LIMIT 4;

# Selecting the distance value
SELECT
  approx_distance(
    embedding_name,
    string_to_vector('[1,2,3]'),
    'distance_measure=cosine,num_leaves_to_search=3')
    dist
FROM table
ORDER BY dist
LIMIT limit_value;

approx_distance 関数では、次のオプションを使用します。

embedding: ベーステーブルのベクトルエンベディング列名を使用します。
string_to_vector または vector_to_string: ベクトルを文字列に変換し、文字列をベクトルに変換して、ベクトルを人が読める形式に変換します。
distance_measure: ベクトル類似性検索に使用する距離測定を指定します。この値は、インデックスの作成時に distance_measure パラメータで設定した値と一致する必要があります。このパラメータは必須です。このパラメータで指定できる値は次のとおりです。
- COSINE
- L2_SQUARED
- DOT_PRODUCT
num_leaves_to_search: 省略可。ANN ベクトル類似性検索でプローブするリーフの数を指定します。リーフの数を指定しない場合、Cloud SQL はテーブルのサイズ、ベクトルインデックス内のリーフの数、その他の要因に基づいて生成された値を使用します。この値は information_schema.innodb_vector_indexes で確認できます。特定のワークロードの検索品質とパフォーマンスの最適なバランスを実現するには、num_leaves_to_search を微調整することをおすすめします。値を大きくするとパフォーマンスに影響しますが、再現率は向上します。

次の例は、approx_distance を使用して l2_squared 距離測定を使用して最も近い上位 K 行を見つけ、距離で結果を並べ替える方法を示しています。

# Ordering by distance
SELECT title
FROM books
ORDER BY approx_distance(embedding, string_to_vector('[1,2,3]'),
                         'distance_measure=l2_squared')
LIMIT 4;

# Selecting the distance value
SELECT
    approx_distance
        (embedding, string_to_vector('[1,2,3]'),
         'distance_measure=l2_squared') dist
FROM table
ORDER BY dist
LIMIT 4;

approx_distance クエリの結果をフィルタする

approx_distance 関数は、ベクトル以外の述語でクエリ結果をフィルタする WHERE 条件で使用して、後処理フィルタリングを実行できます。approx_distance 関数はフィルタの適用前に評価されるため、返される結果の数は不確定です。

たとえば、次のクエリの場合:

SELECT id FROM products WHERE price < 100
ORDER BY approx(embedding, @query_vector,'distance_measure=cosine')
LIMIT 11;

approx_distance 関数は、価格に関係なく、クエリベクトルの 11 個の最近傍を返します。後処理では、価格が 100 未満の商品が選択されます。すべての最近傍の価格が 100 未満であるため、クエリの結果が 11 件になる可能性があります。または、最近傍のいずれも価格が 100 未満でない場合、返される行は 0 行になります。

WHERE 条件のフィルタが非常に選択的になると予想される場合は、十分な数の行が返されるように、完全一致検索（KNN）の方が適している可能性があります。

ANN 検索のフォールバックステータスを確認する

ANN 検索が KNN 検索にフォールバックする場合があります。たとえば、次のようなものです。

ベーステーブルにベクトルインデックスがない。
ベーステーブルにベクトルインデックスがありますが、approx_distance 検索オプションの distance_measure パラメータとは異なる距離測定を使用しています。
ベクトルインデックスが破損しているか、現在のトランザクションには表示されません。
指定された LIMIT が 10,000 を超えています。
LIMIT が指定されていない。
現在のクエリでは、同じベーステーブルに対して複数の approx_distance 呼び出しが行われています。
オプティマイザーは、KNN を使用する方が効率的であると計算します。

これらのケースではすべて、完全一致検索が実行されたこととその理由を示す警告がクライアントにプッシュされます。

mysql クライアントで次のコマンドを使用して、フォールバックステータスを表示します。

SHOW global status LIKE '%cloudsql_vector_knn_fallback%';

ANN を使用するつもりが KNN にフォールバックすると、クエリの実行速度が低下する可能性があります。フォールバックしている理由を特定し、代わりに ANN が使用されるように変更するかどうかを評価する必要があります。

例: ベクトルインデックスを作成し、ANN クエリを実行する

次のチュートリアルの例では、Cloud SQL でベクトルインデックスを作成し、ANN クエリを実行する手順を示します。

ベクトルエンベディングを生成します。ベクトルエンベディングの作成は手動で行うことも、任意のテキストエンベディング API を使用することもできます。Vertex AI を使用する例については、行データに基づいてベクトルエンベディングを生成するをご覧ください。
Cloud SQL で、3 つのディメンションを持つベクトルエンベディング列を含むテーブルを作成します。
```
CREATE TABLE books(
id INTEGER PRIMARY KEY AUTO_INCREMENT, title VARCHAR(60), embedding VECTOR(3) USING VARBINARY);
```

ベクトルエンベディングを 1 つ、その列に挿入します。

INSERT INTO books VALUES ((1, 'book title', string_to_vector('[1,2,3]')));

変更を commit します。
```
commit;
```

L2_squared 関数を使用してベクトルインデックスを作成し、距離を測定します。

CREATE
  VECTOR INDEX vectorIndex
ON dbname.books(embeddings)
USING SCANN QUANTIZER = SQ8 DISTANCE_MEASURE = l2_squared;

検索結果が 4 件の LIMIT を使用して ANN 検索を実行するには、次の構文を使用します。

SELECT title
FROM books
ORDER BY approx_distance(embedding, string_to_vector('[1,2,3]'), 'distance_measure=l2_squared')
LIMIT 4;

SELECT approx_distance(embedding, string_to_vector('[1,2,3]'), 'distance_measure=cosine') dist
FROM books
ORDER BY dist
LIMIT 4;

K 最近傍（KNN）を検索する

K 最近傍探索を実行するには、SELECT ステートメントで距離測定オプションとベクトル変換関数（string_to_vector または vector_to_string）を使用して vector_distance 関数を使用します。次の構文を使用します。

SELECT vector_distance(string_to_vector('[1,2,3]'),
                      string_to_vector('[1,2,3]'),
                      'Distance_Measure=dot_product');

値 [1,2,3] は、データのエンベディング値に置き換えます。

次の例は、このクエリを cosine_distance 関数と string_to_vector ベクトル変換関数で使用する方法を示しています。

SELECT id,cosine_distance(embedding, string_to_vector('[1,2,3]')) dist
FROM books
ORDER BY distance
LIMIT 10;

KNN クエリでコサイン距離を取得する

Cloud SQL の cosine_distance 関数を使用して、余弦を使用して距離を計算します。

SELECT cosine_distance(embedding, string_to_vector('[3,1,2]')) AS distance FROM books WHERE id = 10;

KNN クエリでドット積距離を取得する

Cloud SQL の dot_product 関数を使用して、ドット積を使用して距離を計算します。

SELECT dot_product(embedding, string_to_vector('[3,1,2]')) AS distance FROM books WHERE id = 10;

KNN クエリで L2 二乗距離を取得する

Cloud SQL の l2_squared_distance 関数を使用して、L2 平方を使用して距離を計算します。

SELECT
  l2_squared_distance(embedding, string_to_vector('[3,1,2]'))
    AS distance
FROM books
WHERE id = 10;

ベクトル エンベディングを使用した検索とフィルタ