ベクトル インデックスを作成して管理する

MySQL   |  PostgreSQL   |  SQL Server

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

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

このページでは、ベクトル インデックスのメモリを構成する方法、ベクトル インデックスの作成、チューニング、モニタリング、削除を行う方法について説明します。

始める前に

ベクトル インデックスを作成する前に、ベクトル エンベディング値を使用してベーステーブルにデータを読み込む必要があります。ベーステーブルには 1,000 行以上が必要です。利用可能なデータポイントが多いほど、インデックスのパーティショニングとトレーニングが向上します。

ベクトル インデックスのメモリ割り当てを構成する

cloudsql_vector_max_mem_size データベース フラグは、Cloud SQL インスタンスがベクトル インデックスに割り当てるメモリ量を制御します。これは、インスタンスの再起動が必要な静的フラグです。このメモリには、主に次の 2 つの目的があります。

1. ベクトル インデックス構造の保存: ベクトル インデックスのリーフ以外の部分（TREE_MEMORY）は、このメモリに格納されます。このツリーのサイズは、リーフノードの数（num_leaves）とベクトルのディメンションによって異なります。

    Approximate TREE_MEMORY = num_leaves * vector dimensions * 4 * 2
   

   たとえば、1,000 個のリーフと 768 個のディメンションを持つインデックスの場合、TREE_MEMORY は約 1,000 * 768 * 4 * 2 = 6,144,000 バイトになります。information_schema.innodb_vector_indexes テーブルを使用して、実際の TREE_MEMORY を確認することもできます。そのメモリは Cloud SQL が管理します。非アクティブなインデックスは他のリクエストのためのスペースを確保するためにアンロードされるため、すべてのベクトル インデックスに同時にスペースを割り当てる必要はありません。

2. インデックス作成用のメモリ（トレーニング データ）: ベクトル インデックスの作成中、ベーステーブルのデータのサンプルを処理してインデックスを構築するためにメモリが必要になります。このメモリはインデックス作成プロセス中にのみ使用され、その後解放されます。トレーニングに必要なメモリのサイズは次のとおりです。

    approximate_training_memory = num_rows in base table * 0.1 * 4 * vector dimensions
   

   たとえば、1,000,000 行と 768 ディメンションのテーブルの場合、training_memory は 1000000 * 0.1 * 768 * 4 バイト、つまり 307,200,000 バイトになります。ベーステーブル データの 10% のみがサンプリングされ、ツリーの重心が計算されます。

   cloudsql_vector フラグを有効にすると、Cloud SQL は VM サイズに基づいてデフォルトの cloudsql_vector_max_mem_size を自動的に設定します。通常、このデフォルト値は一般的なワークロードで十分です。Cloud SQL は、このメモリを割り当てるために innodb_buffer_pool_size フラグを減らします。cloudsql_vector_max_mem_size のデフォルトの最大値は 16 GB です。メモリサイズをチューニングする必要がある場合は、ベクトル インデックスの使用状況に基づいて cloudsql_vector_max_mem_size を動的に調整できます。

   重要: cloudsql_vector_max_mem_size を増やす場合は、メモリの問題を回避するために、innodb_buffer_pool_size を対応して減らす必要があります。

cloudsql_vector_max_mem_size 個の値

VM サイズ	cloudsql_vector_max_mem_size
4 GB	194MB
8 GB	515MB
16 GB	1.2GB
32 GB	2.56GB
64 GB	5.12GB
128 GB	10.24GB
256 GB 以上	16 GB

割り当てられるベクトル インデックス メモリの範囲は次のとおりです。

• 最小 128 MB
• バッファプールの 10%
• 最大 16 GB

必要に応じて後でメモリを調整できます。詳細については、ベクトル エンベディング用にデータベース フラグを有効にするをご覧ください。

ベクトル インデックスのサイズのモニタリングについては、ベクトル インデックスをモニタリングするをご覧ください。

インスタンスのベクトル インデックスに割り当てるメモリを更新するには、次のコマンドを使用します。

gcloud sql instances patch INSTANCE_NAME \
 --database-flags= cloudsql_vector_max_mem_size=NEW_MEMORY_VALUE;

次のように置き換えます。

• INSTANCE_NAME: メモリ割り当てを変更するインスタンスの名前。
• NEW_MEMORY_VALUE: ベクトル インデックスの更新されたメモリ割り当て（バイト単位）。

この変更は、データベースの再起動後すぐに有効になります。

ベクトル インデックスを作成する

ベクトル インデックスを作成する方法は 2 つあります。

• CREATE VECTOR INDEX ステートメント。標準 MySQL 構文に対する Cloud SQL 拡張機能。
• Cloud SQL ADD VECTOR INDEX 句拡張機能を使用して ALTER TABLE ステートメントを実行します。このステートメントは、テーブルの他の DDL ステートメントと同時に実行することはできません。

注: ベーステーブルのサイズは、テーブルでベクトル エンベディング列に NULL 以外のエントリを含む行の数をスキャンして計算されます。

CREATE VECTOR INDEX を使用してベクトル インデックスを作成するには、次の構文を使用します。

CREATE
  VECTOR INDEX INDEX_NAME
ON TABLE_NAME(COLUMN_NAME)
USING
  SCANN[QUANTIZER = SQ8]
    DISTANCE_MEASURE
  = L2_SQUARED | COSINE | DOT_PRODUCT[NUM_LEAVES = INT_VALUE { '</var>' }}];

インデックス オプションは次のとおりです。

• USING SCANN: 省略可。使用するインデックス タイプを示します。サポートされる値は SCANN のみです。
• QUANTIZER: 省略可。高次元ベクトルを圧縮表現にマッピングします。サポートされている値は SQ8 のみです。
• DISTANCE_MEASURE: 必須。2 つのベクトルの類似性を計算するために使用する数式を指定します。このパラメータには、approx_distance 検索オプションで設定した距離と同じ距離の単位を設定する必要があります。サポートされているリテラルは次のとおりです。
  • L2_SQUARED
  • COSINE
  • DOT_PRODUCT
• NUM_LEAVES: 省略可。作成するパーティション（リーフ）の数を指定します。この設定をデフォルト設定から変更するのは、ANN 検索とデータセットを十分に理解している場合に限ってください。指定する数は、ベーステーブル内のエンベディングの数より大きくすることはできません。

たとえば、ベクトル インデックスを作成するには、次のコマンドを実行します。

CREATE
  VECTOR INDEX vectorIndex
ON dbname.books(embeddings) DISTANCE_MEASURE = L2_SQUARED;

CREATE ステートメントの実行中、ベーステーブルは読み取り専用モードになり、ベーステーブルに対する DML は許可されません。

既存のテーブルにインデックスを作成するには、次の構文を使用します。

ALTER TABLE tbl_name
  ADD VECTOR INDEX index_name(key_part)[index_option];

たとえば、既存のテーブルにインデックスを作成するには、次のようにします。

ALTER TABLE t1 ADD VECTOR INDEX index1(j)
USING SCANN QUANTIZER = SQ8 DISTANCE_MEASURE = l2_squared NUM_LEAVES = 10;

ベクトル インデックスをチューニングする

このセクションでは、ベクトル インデックスの作成に使用するパラメータについて詳しく説明します。ベクトル インデックスをチューニングするには、この情報を使用して、ビルドプロセスにどのように影響するかを判断します。

パラメータ	説明	デフォルト	スコープ	効果
cloudsql_vector_max_mem_size	インデックス トレーニングに割り当てられたメモリ。	場合によって異なる	インスタンス	メモリが不足すると、ビルドが失敗する可能性があります。ベクトル インデックスのメモリ割り当てを構成するをご覧ください。
innodb_ddl_threads	インデックスのトレーニングとビルドの並列処理の程度。	4	セッション	値を大きくするとビルド時間が短縮されますが、CPU 負荷は増加します。この値は、データベース オペレーションに悪影響を及ぼさずに使用できる CPU の数に設定します。

cloudsql_vector_max_mem_size がトレーニング用に適切に構成されていることを確認します。同時実行データベース オペレーションへの影響を考慮して、ビルド時間と CPU 負荷のバランスをとるように innodb_ddl_threads を調整します。ビルド中の CPU 使用率をモニタリングします。

ベクトル インデックスを削除する

ベクトル インデックスを削除するには、削除するインデックス名を指定して SQL DROP INDEX ステートメントまたは ALTER TABLE ステートメントを使用します。

DROP INDEX index_name ON books;

ALTER TABLE table_name
DROP INDEX index_name;

ベクトル インデックスをモニタリングする

Cloud SQL には、メモリに読み込まれたベクトル インデックスに関するリアルタイム情報が次の情報スキーマ テーブルに用意されています。

• information_schema.innodb_vector_indexes は、再起動後にメモリ内で開かれているすべてのベクトル インデックスを一覧表示します。
• information_schema.innodb_all_vector_indexes は、インスタンス上に存在するすべてのベクトル インデックスを一覧表示します（メモリでまだ開いていないインデックスも表示されます）。
• information_schema.innodb_vector_indexes_memory には、インスタンス内のベクトル インデックスの全体的なメモリ使用量に関する情報が表示されます。

詳細については、情報スキーマをご覧ください。

innodb_vector_indexes テーブルの情報を表示するには、次のコマンドを実行します。

SELECT * FROM information_schema.innodb_vector_indexes \ G;

出力は次のようになります。

 INDEX_NAME: t1_vec_index
 TABLE_NAME: test.t1
 INDEX_TYPE: TREE_SQ
 DIMENSION: 3
 DIST_MEASURE: COSINE
 STATUS: Ready
 STATE: INDEX_READY_TO_USE
 NUM_LEAVES: 10
 NUM_LEAVES_TO_SEARCH: 10
 QUERIES: 1
 MUTATIONS: 1
 TREE_MEMORY: 443

次のステップ

• Cloud SQL でのベクトル検索の概要を確認する。
• インスタンスでベクトル エンベディングを有効または無効にする方法を学習する。
• ベクトル エンベディングを生成する方法を学習する。
• ベクトル エンベディングで検索を行う方法を学習する。