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

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

始める前に

ベクトル インデックスを作成する前に、ベクトル エンベディング値を使用してベーステーブルにデータを読み込む必要があります。ベーステーブルには 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 個のディメンションを持つインデックスの場合、1,000 * 768 * 4 * 2 = 6,144,000 バイトの TREE_MEMORY になります。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 194 MB
8 GB 515 MB
16 GB 1.2 GB
32 GB 2.56 GB
64 GB 5.12 GB
128 GB 10.24 GB
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 を使用してベクトル インデックスを作成するには、次の構文を使用します。

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

次のステップ