ベクトル アシストを使用する

このページでは、ベクトル アシストを使用して、Cloud SQL for PostgreSQL インスタンスにベクトル ワークロードをデプロイして管理する方法について説明します。

ベクトル アシストの概要と仕組みについては、ベクトル アシストの概要をご覧ください。

始める前に

  • インスタンスで正しいメンテナンス バージョンが使用されていることを確認します。ベクトル アシストには、PostgreSQL_$version.R20251004.01_07 以上のメンテナンス バージョン番号が必要です。セルフサービス メンテナンスの実施の詳細については、パフォーマンス セルフサービス メンテナンスをご覧ください。
  • cloudsql.enable_vector_assist データベース フラグを ON に設定します。

  • 使用するデータベースで次のコマンドを使用して、ベクトル アシスト拡張機能を有効にします。

    CREATE EXTENSION vector_assist CASCADE;

    これにより、ベクトル アシストで使用される vector_assist スキーマが生成されます。

ベクトル アシストを使用してベクトル ワークロードをデプロイする

ベクトル アシストを使用してベクトル ワークロードをデプロイして管理するには、次の操作を行う必要があります。

ベクトル仕様を定義する

ベクトル仕様（ベクトル仕様）を定義することは、ベクトル アシストを使用する最初のステップです。ベクトル ワークロードのタイプに応じて、ベクトル仕様の定義に使用するフィールドが異なる場合があります。

たとえば、テーブルの特定の列でセマンティック検索を有効にする場合は、vector_assist.define_spec 関数を実行してベクトル仕様を定義します。

SELECT vector_assist.define_spec(
  table_name => 'TABLE_NAME',
  vector_column_name => 'VECTOR_COLUMN_NAME',
  target_recall => TARGET_RECALL,
  tune_vector_index => TUNE_INDEX
);

次のパラメータを置き換えます。

  • TABLE_NAME: ベクトル ワークロードで使用するテーブルの名前。
  • VECTOR_COLUMN_NAME: セマンティック検索を実行する列。
  • TARGET_RECALL: ベクトル アシストで達成する目標再現率。
  • TUNE_INDEX: ベクトル アシストがワークロードのベクトル インデックスを調整するかどうかを指定するブール値。

ベクトル仕様で使用可能なすべてのパラメータの一覧については、ベクトル アシストのリファレンスをご覧ください。

ベクトル仕様を作成するクエリを実行すると、ベクトル アシストは、ベクトル ワークロードをデプロイするために実行する必要があるステップ（推奨事項）を自動的に生成します。

ベクトル アシストの推奨事項を表示する

ベクトル仕様を使用してベクトル アシストによって生成された推奨事項を表示するには、vector_assist.get_recommendations 関数を実行します。

SELECT vector_assist.get_recommendations(
  spec_id => 'SPEC_ID'
);

次のパラメータを置き換えます。

  • SPEC_ID: 推奨事項を表示するベクトル仕様の仕様 ID。

すべての推奨事項を含む vector_assist.RECOMMENDATIONS というテーブルを返します。各推奨事項は、関連する spec_id とともにテーブルに保存されます。各推奨事項には通常、実行する必要がある SQL クエリ、推奨事項の詳細な説明、推奨事項を説明するその他の関連情報が含まれています。

ベクトル アシストの推奨事項を適用する

生成された推奨事項は、個別に適用することも、まとめて適用することもできます。

特定の推奨事項を適用するには、vector_assist.apply_recommendation 関数を実行します。

SELECT vector_assist.apply_recommendation(
  recommendation_id => 'RECOMMENATION_ID',
);

次のパラメータを置き換えます。

  • RECOMMENDATION_ID: vector_assist.RECOMMENDATIONS テーブルから適用するベクトル アシストの推奨事項の ID。

すべての推奨事項をまとめて適用するには、spec_id パラメータまたは table_name パラメータを使用して vector_assist.apply_spec 関数を実行します。

SELECT vector_assist.apply_spec(
  spec_id => 'SPEC_ID',
  table_name => 'TABLE_NAME'
);

次のパラメータを置き換えます。

  • SPEC_ID: 使用するベクトル仕様の ID。
  • TABLE_NAME: ベクトル仕様の定義に使用したテーブルの名前。

必要に応じて、schema_name パラメータまたは column_name パラメータを入力することもできます。

ベクトル アシストによって生成された推奨事項を適用すると、ベクトル インデックスを使用できるようになります。

検索クエリを生成する

ベクトル アシストを使用すると、ワークロードのベクトル仕様と生成されたベクトル インデックスを使用して、デプロイされたベクトル ワークロード用に最適化された検索クエリを作成できます。最適化された検索クエリを生成するには、vector_assist.generate_query 関数を実行します。

SELECT vector_assist.generate_query(
  spec_id => 'SPEC_ID',
  table_name => 'TABLE_NAME',
  column_name => 'COLUMN_NAME',
  search_text => 'SEARCH_TEXT',
  top_k => 'TOP_K_NAME',
  target_recall => TARGET_RECALL,
  filter_expression => 'FILTER_EXPRESSION'
);

次のパラメータを置き換えます。

  • SPEC_ID: 使用する仕様の ID。
  • TABLE_NAME: ベクトル仕様の定義に使用したテーブルの名前。
  • COLUMN_NAME: ベクトル仕様で定義した元のテキスト列の名前。
  • SEARCH_TEXT: 列で検索するテキスト。
  • TOP_K: 返される最近傍の数。
  • TARGET_RECALL: ベクトル アシストで達成する目標再現率。
  • FILTER_EXPRESSION: 検索クエリのフィルタ（他の列に基づくフィルタなど）。

検索クエリの生成に使用できるすべてのパラメータの一覧については、ベクトル アシストのリファレンスをご覧ください。

この関数の出力は、SQL クエリを含むテキストを返します。この SQL クエリは、必要に応じて実行または保存できます。

次のステップ