AlloyDB でハイブリッド検索を使ってみる

1. はじめに

この Codelab では、（ランキング更新メソッド）RUM 拡張機能とスケーラブルな近似最近傍（ScaNN）インデックスを使用して AlloyDB でハイブリッド検索を実行する方法を学びます。このラボは、AlloyDB AI 機能専用のラボコレクションの一部です。詳細については、ドキュメントの AlloyDB AI ページをご覧ください。

前提条件

Google Cloud コンソールの基本的な知識
コマンドラインインターフェースと Google Shell の基本的なスキル

学習内容

AlloyDB クラスタとプライマリインスタンスをデプロイする方法
Google Compute Engine VM から AlloyDB に接続する方法
データベースを作成して AlloyDB AI を有効にする方法
データベースにデータを読み込む方法
AlloyDB Studio の使用方法
Vertex AI でエンベディングを生成する
ScaNN ベクトルインデックスを作成してベクトル検索を高速化する方法
全文検索用に RUM 拡張機能を有効にして使用する方法
全文検索、ベクトル検索、Reciprocal Rank Fusion（RRF）を組み合わせてハイブリッド検索を実行する

必要なもの

Google Cloud アカウントと Google Cloud プロジェクト
ウェブブラウザ（Chrome など）

2. 設定と要件

プロジェクトのセットアップ

Google Cloud コンソールにログインします。Gmail アカウントも Google Workspace アカウントもまだお持ちでない場合は、アカウントを作成してください。

仕事用または学校用のアカウントではなく、個人用のアカウントを使用します。

Google Cloud プロジェクトの作成

Google Cloud コンソールのプロジェクトセレクタページで、Google Cloud プロジェクトを選択または作成します。
Cloud プロジェクトに対して課金が有効になっていることを確認します。プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。

課金を有効にする

課金を有効にするには、次の 2 つの方法があります。個人用の請求先アカウントを使用するか、次の手順でクレジットを利用できます。

個人用の請求先アカウントを設定する

Google Cloud クレジットを使用して課金を設定した場合は、この手順をスキップできます。

個人用の請求先アカウントを設定するには、Cloud コンソールでこちらに移動して課金を有効にします。

注意事項:

このラボを完了するのにかかる Cloud リソースの費用は 3 米ドル未満です。
このラボの最後の手順に沿ってリソースを削除すると、それ以上の料金は発生しません。
新規ユーザーは、300 米ドル分の無料トライアルをご利用いただけます。

Cloud Shell の起動

Google Cloud はノートパソコンからリモートで操作できますが、この Codelab では、Google Cloud Shell（Cloud 上で動作するコマンドライン環境）を使用します。

Cloud Shell は、必要なツールがプリロードされた Google Cloud で動作するコマンドライン環境です。

Google Cloud コンソールの上部にある [Cloud Shell をアクティブにする] をクリックします。
Cloud Shell に接続したら、認証を確認します。
```
gcloud auth list
```
プロジェクトが構成されていることを確認します。
```
gcloud config get project
```
プロジェクトが想定どおりに設定されていない場合は、設定します。
```
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
```

この仮想マシンには、必要な開発ツールがすべて用意されています。永続的なホームディレクトリが 5 GB 用意されており、Google Cloud で稼働します。そのため、ネットワークのパフォーマンスと認証機能が大幅に向上しています。この Codelab での作業はすべて、ブラウザ内から実行できます。インストールは不要です。

3. はじめに

API を有効にする

出力:

AlloyDB、Compute Engine、ネットワーキングサービス、Vertex AI を使用するには、Google Cloud プロジェクトでそれぞれの API を有効にする必要があります。

API の有効化

Cloud Shell のターミナルで、プロジェクト ID が設定されていることを確認します。

gcloud config set project [YOUR-PROJECT-ID]

環境変数 PROJECT_ID を設定します。

PROJECT_ID=$(gcloud config get-value project)

必要な API をすべて有効にします。

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com

想定される出力

student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417
Updated property [core/project].
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$ 
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com
Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.

API の概要

AlloyDB API（alloydb.googleapis.com）を使用すると、AlloyDB for PostgreSQL クラスタの作成、管理、スケーリングを行うことができます。要求の厳しいエンタープライズトランザクションワークロードと分析ワークロード用に設計された、PostgreSQL 互換のフルマネージドデータベースサービスを提供します。
Compute Engine API（compute.googleapis.com）を使用すると、仮想マシン（VM）、永続ディスク、ネットワーク設定を作成して管理できます。これは、ワークロードの実行と、多くのマネージドサービスの基盤となるインフラストラクチャのホストに必要な、Infrastructure-as-a-Service（IaaS）の基盤となるものです。
Cloud Resource Manager API（cloudresourcemanager.googleapis.com）を使用すると、Google Cloud プロジェクトのメタデータと構成をプログラムで管理できます。これにより、リソースの整理、Identity and Access Management（IAM）ポリシーの処理、プロジェクト階層全体での権限の検証が可能になります。
Service Networking API（servicenetworking.googleapis.com）を使用すると、Virtual Private Cloud（VPC）ネットワークと Google のマネージドサービス間のプライベート接続の設定を自動化できます。AlloyDB などのサービスが他のリソースと安全に通信できるように、プライベート IP アクセスを確立するために必要です。
Vertex AI API（aiplatform.googleapis.com）を使用すると、アプリケーションで ML モデルを構築、デプロイ、スケーリングできます。これは、生成 AI モデル（Gemini など）へのアクセスやカスタムモデルのトレーニングなど、Google Cloud のすべての AI サービスに統合インターフェースを提供します。

必要に応じて、Vertex AI エンベディングモデルを使用するようにデフォルトのリージョンを構成できます。Vertex AI で使用可能なロケーションの詳細を確認する。この例では、us-central1 リージョンを使用しています。

gcloud config set compute/region us-central1

4. AlloyDB をデプロイする

AlloyDB クラスタを作成する前に、将来の AlloyDB インスタンスで使用する VPC で使用可能なプライベート IP 範囲が必要です。ない場合は、作成して内部の Google サービスで使用されるように割り当てる必要があります。その後、クラスタとインスタンスを作成できます。

プライベート IP 範囲を作成する

AlloyDB の VPC でプライベートサービスアクセス構成を構成する必要があります。ここでは、プロジェクトに「デフォルト」の VPC ネットワークがあり、すべてのアクションで使用されることを前提としています。

プライベート IP 範囲を作成します。

gcloud compute addresses create psa-range \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=24 \
    --description="VPC private service access" \
    --network=default

割り振られた IP 範囲を使用してプライベート接続を作成します。

gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=psa-range \
    --network=default

想定されるコンソール出力:

student@cloudshell:~ (test-project-402417)$ gcloud compute addresses create psa-range \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=24 \
    --description="VPC private service access" \
    --network=default
Created [https://www.googleapis.com/compute/v1/projects/test-project-402417/global/addresses/psa-range].

student@cloudshell:~ (test-project-402417)$ gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=psa-range \
    --network=default
Operation "operations/pssn.p24-4470404856-595e209f-19b7-4669-8a71-cbd45de8ba66" finished successfully.

student@cloudshell:~ (test-project-402417)$

AlloyDB クラスタを作成する

このセクションでは、us-central1 リージョンに AlloyDB クラスタを作成します。

postgres ユーザーのパスワードを定義します。独自のパスワードを定義することも、ランダム関数を使用してパスワードを生成することもできます。

export PGPASSWORD=`openssl rand -hex 12`

想定されるコンソール出力:

student@cloudshell:~ (test-project-402417)$ export PGPASSWORD=`openssl rand -hex 12`

後で使用できるように PostgreSQL のパスワードをメモしておきます。

echo $PGPASSWORD

このパスワードは、後で postgres ユーザーとしてインスタンスに接続するために必要になります。後で使用できるように、書き留めるかどこかにコピーしておくことをおすすめします。

想定されるコンソール出力:

student@cloudshell:~ (test-project-402417)$ echo $PGPASSWORD
bbefbfde7601985b0dee5723

AlloyDB クラスタを作成する

リージョンと AlloyDB クラスタ名を定義します。ここでは、us-central1 リージョンと alloydb-hybrid-search をクラスタ名として使用します。

export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search

コマンドを実行してクラスタを作成します。

gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION

想定されるコンソール出力:

export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION 
Operation ID: operation-1697655441138-6080235852277-9e7f04f5-2012fce4
Creating cluster...done.

同じ Cloud Shell セッションで、クラスタの AlloyDB プライマリインスタンスを作成します。切断された場合は、リージョンとクラスタ名の環境変数を再度定義する必要があります。

gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=2 \
    --region=$REGION \
    --cluster=$ADBCLUSTER

想定されるコンソール出力:

student@cloudshell:~ (alloydb-hybrid-search)$ gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=2 \
    --region=$REGION \
    --availability-type ZONAL \
    --cluster=$ADBCLUSTER
Operation ID: operation-1697659203545-6080315c6e8ee-391805db-25852721
Creating instance...done.

5. AlloyDB に接続する

AlloyDB はプライベート接続のみを使用してデプロイされるため、データベースを操作するには PostgreSQL クライアントがインストールされた VM が必要です。

GCE VM をデプロイする

AlloyDB クラスタと同じリージョンと VPC に GCE VM を作成します。

Cloud Shell で、次のコマンドを実行します。

export ZONE=us-central1-a
gcloud compute instances create instance-1 \
    --zone=$ZONE \
    --create-disk=auto-delete=yes,boot=yes,image=projects/debian-cloud/global/images/$(gcloud compute images list --filter="family=debian-12 AND family!=debian-12-arm64" --format="value(name)") \
    --scopes=https://www.googleapis.com/auth/cloud-platform

想定されるコンソール出力:

student@cloudshell:~ (alloydb-hybrid-search)$ export ZONE=us-central1-a
student@cloudshell:~ (talloydb-hybrid-search)$ export ZONE=us-central1-a
gcloud compute instances create instance-1 \
    --zone=$ZONE \
    --create-disk=auto-delete=yes,boot=yes,image=projects/debian-cloud/global/images/$(gcloud compute images list --filter="family=debian-12 AND family!=debian-12-arm64" --format="value(name)") \
    --scopes=https://www.googleapis.com/auth/cloud-platform

Created [https://www.googleapis.com/compute/v1/projects/test-project-402417/zones/us-central1-a/instances/instance-1].
NAME: instance-1
ZONE: us-central1-a
MACHINE_TYPE: n1-standard-1
PREEMPTIBLE: 
INTERNAL_IP: 10.128.0.2
EXTERNAL_IP: 34.71.192.233
STATUS: RUNNING

Postgres クライアントをインストールする

デプロイされた VM に PostgreSQL クライアントソフトウェアをインストールします。

VM に接続します。

gcloud compute ssh instance-1 --zone=us-central1-a

想定されるコンソール出力:

student@cloudshell:~ (alloydb-hybrid-search)$ gcloud compute ssh instance-1 --zone=us-central1-a
Updating project ssh metadata...working..Updated [https://www.googleapis.com/compute/v1/projects/alloydb-hybrid-search].                                                                                                                                                         
Updating project ssh metadata...done.                                                                                                                                                                                                                                              
Waiting for SSH key to propagate.
Warning: Permanently added 'compute.5110295539541121102' (ECDSA) to the list of known hosts.
Linux instance-1.us-central1-a.c.gleb-test-short-001-418811.internal 6.1.0-18-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.76-1 (2024-02-01) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
student@instance-1:~$

VM 内でソフトウェア実行コマンドをインストールします。

sudo apt-get update
sudo apt-get install --yes postgresql-client

想定されるコンソール出力:

student@instance-1:~$ sudo apt-get update
sudo apt-get install --yes postgresql-client
Get:1 https://packages.cloud.google.com/apt google-compute-engine-bullseye-stable InRelease [5146 B]
Get:2 https://packages.cloud.google.com/apt cloud-sdk-bullseye InRelease [6406 B]   
Hit:3 https://deb.debian.org/debian bullseye InRelease  
Get:4 https://deb.debian.org/debian-security bullseye-security InRelease [48.4 kB]
Get:5 https://packages.cloud.google.com/apt google-compute-engine-bullseye-stable/main amd64 Packages [1930 B]
Get:6 https://deb.debian.org/debian bullseye-updates InRelease [44.1 kB]
Get:7 https://deb.debian.org/debian bullseye-backports InRelease [49.0 kB]
...redacted...
update-alternatives: using /usr/share/postgresql/13/man/man1/psql.1.gz to provide /usr/share/man/man1/psql.1.gz (psql.1.gz) in auto mode
Setting up postgresql-client (13+225) ...
Processing triggers for man-db (2.9.4-2) ...
Processing triggers for libc-bin (2.31-13+deb11u7) ...

インスタンスに接続する

psql を使用して VM からプライマリインスタンスに接続します。

インスタンス 1 VM への SSH セッションが開いている Cloud Shell の同じタブで、次の操作を行います。

メモした AlloyDB パスワード（PGPASSWORD）の値と AlloyDB クラスタ ID を使用して、GCE VM から AlloyDB に接続します。

export PGPASSWORD=<Noted password>

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
export INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
psql "host=$INSTANCE_IP user=postgres sslmode=require"

想定されるコンソール出力:

student@instance-1:~$ export PGPASSWORD=CQhOi5OygD4ps6ty
student@instance-1:~$ ADBCLUSTER=alloydb-aip-01
student@instance-1:~$ REGION=us-central1
student@instance-1:~$ INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
gleb@instance-1:~$ psql "host=$INSTANCE_IP user=postgres sslmode=require"
psql (15.6 (Debian 15.6-0+deb12u1), server 15.5)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

postgres=>

psql セッションを閉じます。

exit

6. データベースを準備する

データベースを作成し、Vertex AI インテグレーションを有効にして、データベースオブジェクトを作成し、データをインポートする必要があります。

AlloyDB に必要な権限を付与する

AlloyDB サービスエージェントに Vertex AI 権限を追加します。

上部の「+」記号を選択して、別の Cloud Shell タブを開きます。

新しい Cloud Shell タブで、次のコマンドを実行します。

PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

想定されるコンソール出力:

student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-11039]
student@cloudshell:~ (test-project-001-402417)$ gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
Updated IAM policy for project [test-project-001-402417].
bindings:
- members:
  - serviceAccount:service-4470404856@gcp-sa-alloydb.iam.gserviceaccount.com
  role: roles/aiplatform.user
- members:
...
etag: BwYIEbe_Z3U=
version: 1

タブに実行コマンド「exit」を入力して、タブを閉じます。

exit

データベースを作成する

quickstart という名前のデータベースを作成します。

GCE VM セッションで、次のコマンドを実行します。

データベースを作成します。

psql "host=$INSTANCE_IP user=postgres" -c "CREATE DATABASE quickstart_db"

想定されるコンソール出力:

student@instance-1:~$ psql "host=$INSTANCE_IP user=postgres" -c "CREATE DATABASE quickstart_db"
CREATE DATABASE
student@instance-1:~$

Vertex AI の統合を有効にする

Vertex AI の統合とデータベースの pgvector 拡張機能を有効にします。

GCE VM で次のコマンドを実行します。

psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE"
psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "CREATE EXTENSION IF NOT EXISTS vector"

想定されるコンソール出力:

student@instance-1:~$ psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE"
psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "CREATE EXTENSION IF NOT EXISTS vector"
CREATE EXTENSION
CREATE EXTENSION
student@instance-1:~$

データをインポート

準備したデータをダウンロードして、新しいデータベースにインポートします。

GCE VM で次のコマンドを実行します。

gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_demo_schema.sql |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db"
gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_products.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_products from stdin csv header"
gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_inventory.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_inventory from stdin csv header"
gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_stores.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_stores from stdin csv header"

想定されるコンソール出力:

student@instance-1:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_demo_schema.sql |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db"
SET
SET
SET
SET
SET
 set_config 
------------
 
(1 row)
SET
SET
SET
SET
SET
SET
CREATE TABLE
ALTER TABLE
CREATE TABLE
ALTER TABLE
CREATE TABLE
ALTER TABLE
CREATE TABLE
ALTER TABLE
CREATE SEQUENCE
ALTER TABLE
ALTER SEQUENCE
ALTER TABLE
ALTER TABLE
ALTER TABLE
student@instance-1:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_products.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_products from stdin csv header"
COPY 941
student@instance-1:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_inventory.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_inventory from stdin csv header"
COPY 263861
student@instance-1:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_stores.csv |psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db" -c "\copy cymbal_stores from stdin csv header"
COPY 4654
student@instance-1:~$

7. ベクトルエンベディングを生成する

データをインポートすると、商品に関する情報を格納する cymbal_products、各店舗の商品の在庫を追跡する cymbal_inventory、店舗のリストである cymbal_stores の各テーブルが作成されます。商品に対してセマンティック検索を実行するには、initialize_embeddings 関数を使用して商品説明のベクトルエンベディングを生成する必要があります。Vertex AI のインテグレーションを使用して、商品説明に基づいてベクトルデータを計算し、テーブルに追加します。使用されているテクノロジーの詳細については、ドキュメントをご覧ください。

この統合を使用するには、AlloyDB インスタンスの IP と postgres パスワードを使用して、VM から psql を使用してデータベースに接続します。

psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db"

google_ml_integration 拡張機能のバージョンを確認します。

SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';

バージョンは 1.5.2 以降である必要があります。出力例を次に示します。

quickstart_db=> SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
 extversion 
------------
 1.5.2
(1 row)

デフォルトのバージョンは 1.5.2 以降ですが、インスタンスに古いバージョンが表示されている場合は、更新が必要になる可能性があります。インスタンスのメンテナンスが無効になっているかどうかを確認します。

バッチエンベディング生成を使用して効率を向上させます。さまざまなエンベディング生成オプションと手法については、ガイドをご覧ください。バッチエンベディングを使用するには、goole_ml_integration.enable_faster_embedding_generation を有効にする必要があります。

show google_ml_integration.enable_faster_embedding_generation;

フラグが正しい位置にある場合、出力は次のようになります。

quickstart_db=> show google_ml_integration.enable_faster_embedding_generation;                          
 google_ml_integration.enable_faster_embedding_generation 
----------------------------------------------------------
 on
(1 row)

[オフ] と表示されている場合は、インスタンスを更新する必要があります。ドキュメントに記載されているように、ウェブコンソールまたは gcloud コマンドを使用して実行できます。ここでは、gcloud コマンドを使用してこれを行う方法を示します。

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags google_ml_integration.enable_faster_embedding_generation=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

数分かかることがありますが、最終的にはフラグの値が「オン」に切り替わります。その後、次の手順に進むことができます。

psql "host=$INSTANCE_IP user=postgres dbname=quickstart_db"

データベースに接続された psql セッションで、cymbal_products にエンベディングを保存する新しい列を作成します。

ALTER TABLE cymbal_products ADD COLUMN product_embedding vector(768);

想定されるコンソール出力:

quickstart_db=> ALTER TABLE cymbal_products ADD COLUMN product_embedding vector(768);
ALTER TABLE
quickstart_db=>

最後に、関数呼び出しに incremental_refresh_mode 引数を含めることで、列の値が変更されたときにエンベディングが更新されるようにします。これによりデータベースにオーバーヘッドが発生しますが、エンベディングとコンテンツの同期を自動的に維持するためのトレードオフです。エンベディングを手動で更新する場合は、ドキュメントをご覧ください。

すべてをまとめてエンベディングを生成するには、initialize_embeddings 関数を使用し、バッチヒントとして batch_size の 50 を渡し、incremental_refresh_mode を transactional に設定します。

CALL ai.initialize_embeddings(
    model_id => 'text-embedding-005',
    table_name => 'cymbal_products',
    content_column => 'product_description',
    embedding_column => 'product_embedding',
    batch_size => 50,
    incremental_refresh_mode => 'transactional'
);

product_embedding 列に NULL 値を指定してテーブルに新しい行を挿入すると、

INSERT INTO "cymbal_products" ("uniq_id", "crawl_timestamp", "product_url", "product_name", "product_description", "list_price", "sale_price", "brand", "item_number", "gtin", "package_size", "category", "postal_code", "available", "product_embedding") VALUES ('fd604542e04b470f9e6348e640cff794', NOW(), 'https://example.com/new_product', 'New Cymbal Product', 'This is a new cymbal product description.', 199.99, 149.99, 'Example Brand', 'EB123', '1234567890', 'Single', 'Cymbals', '12345', TRUE, NULL);

挿入した行をクエリすると、product_embedding 列が自動的に更新されていることがわかります。

SELECT uniq_id, (product_embedding::real[])[1:5] as product_embedding  FROM cymbal_products WHERE uniq_id='fd604542e04b470f9e6348e640cff794';

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

quickstart_db=> SELECT uniq_id,(product_embedding::real[])[1:5] as product_embedding  FROM cymbal_products WHERE uniq_id='fd604542e04b470f9e6348e640cff794';
             uniq_id              |                      product_embedding                       
----------------------------------+---------------------------------------------------------------
 fd604542e04b470f9e6348e640cff794 | {0.015003494,-0.005349732,-0.059790313,-0.0087091,-0.0271452}
(1 row)

Time: 3.295 ms

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

ベクトル検索のパフォーマンスを改善するために、ScaNN インデックスを追加します。

ScaNN インデックスを作成する

SCANN インデックスを構築するには、もう 1 つの拡張機能を有効にする必要があります。拡張機能 alloydb_scann は、Google の ScaNN アルゴリズムを使用して ANN タイプのベクトルインデックスを操作するためのインターフェースを提供します。

CREATE EXTENSION IF NOT EXISTS alloydb_scann;

予想される出力:

quickstart_db=> CREATE EXTENSION IF NOT EXISTS alloydb_scann;
CREATE EXTENSION
Time: 27.468 ms
quickstart_db=>

インデックスは MANUAL モードまたは AUTO モードで作成できます。MANUAL モードはデフォルトで有効になっており、他のインデックスと同様にインデックスを作成して維持できます。ただし、AUTO モードを有効にすると、ユーザー側でメンテナンスを必要としないインデックスを作成できます。すべてのオプションの詳細については、ドキュメントをご覧ください。この例では、自動モードでインデックスを作成するのに十分な行がないため、手動で作成し、チューニングパラメータを含めます。インデックスパラメータのチューニングについては、ドキュメントをご覧ください。

チューニングパラメータを変更できるように、scann.enable_preview_features フラグを有効にする必要があります。Cloud Shell で

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags scann.enable_preview_features=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

数分かかることがありますが、最終的にはフラグの値が「オン」に切り替わります。フラグを設定したら、VM の psql セッションに戻り、チューニングパラメータを使用してインデックスを作成できます。

CREATE INDEX cymbal_products_embeddings_scann ON cymbal_products
  USING scann (product_embedding cosine)
  WITH (mode='MANUAL', num_leaves=31, max_num_levels = 2);

予想される出力:

quickstart_db=> CREATE INDEX cymbal_products_embeddings_scann ON cymbal_products
  USING scann (product_embedding cosine)
  WITH (num_leaves=31, max_num_levels = 2);
CREATE INDEX
quickstart_db=>

インデックスの使用状況を検査する

これで、EXPLAIN モードでベクトル検索クエリを実行し、インデックスが使用されているかどうかを確認できます。

EXPLAIN (analyze) 
WITH trees as (
SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        cp.uniq_id as product_id
FROM
        cymbal_products cp
JOIN cymbal_inventory ci on
        ci.uniq_id=cp.uniq_id
JOIN cymbal_stores cs on
        cs.store_id=ci.store_id
        AND ci.inventory>0
        AND cs.store_id = 1583
ORDER BY
        (cp.product_embedding <=> embedding('text-embedding-005','What kind of fruit trees grow well here?')::vector) ASC
LIMIT 1)
SELECT json_agg(trees) FROM trees;

想定される出力（明確にするために記すと秘匿化済み）:

...
Aggregate (cost=16.59..16.60 rows=1 width=32) (actual time=2.875..2.877 rows=1 loops=1)
-> Subquery Scan on trees (cost=8.42..16.59 rows=1 width=142) (actual time=2.860..2.862 rows=1 loops=1)
-> Limit (cost=8.42..16.58 rows=1 width=158) (actual time=2.855..2.856 rows=1 loops=1)
-> Nested Loop (cost=8.42..6489.19 rows=794 width=158) (actual time=2.854..2.855 rows=1 loops=1)
-> Nested Loop (cost=8.13..6466.99 rows=794 width=938) (actual time=2.742..2.743 rows=1 loops=1)
-> Index Scan using cymbal_products_embeddings_scann on cymbal_products cp (cost=7.71..111.99 rows=876 width=934) (actual time=2.724..2.724 rows=1 loops=1)
Order By: (embedding <=> '[0.008864171,0.03693164,-0.024245683,-0.00355923,0.0055611245,0.015985578,...<redacted>...5685,-0.03914233,-0.018452475,0.00826032,-0.07372604]'::vector)
...

出力から、クエリが「cymbal_products の cymbal_products_embeddings_scann を使用したインデックススキャン」を使用していることがわかります。

9. 全文検索インデックス

AlloyDB は、ネイティブの PostgreSQL がサポートするフルテキスト検索のすべてのインデックスタイプをサポートしています。インデックスの選択は、検索速度、インデックスのビルド時間、更新速度、フレーズ検索や関連性ランキングなど必要な特定の検索機能のバランスによって異なります。

この例では、RUM 拡張機能を使用して、よりパフォーマンスの高い全文検索オペレーションを実行します。RUM は、位置情報をインデックスに直接保存することで標準の GIN インデックスを改善し、テーブルデータにアクセスすることなく、より高速なフレーズ検索と関連性ランキングを実行できるようにします。

AlloyDB Studio を使用するか、psql クライアントを引き続き使用して、rum 拡張機能を有効にできます。

RUM インデックスを作成する

CREATE EXTENSION IF NOT EXISTS rum;

cymbal_products テーブル内の商品説明を検索するには、商品説明を tsvector として保存する列を作成する必要があります。この列には、処理されたテキストが自動的に保存され、クエリのパフォーマンスが向上します。

ALTER TABLE cymbal_products
ADD COLUMN product_search_vector tsvector
GENERATED ALWAYS AS (to_tsvector('english', product_description)) STORED;

これで、product_search_vector 列の新しい RUM インデックスを作成できます。

CREATE INDEX cymbal_products_rum
ON cymbal_products
USING rum (product_search_vector rum_tsvector_ops);

インデックスを使用してテーブルをクエリするには、「cherry tree」の一致を検索する次のクエリを実行します。<=> 演算子は、ドキュメントとクエリの関連性スコアまたは距離をインデックスから直接計算します。

SELECT product_name, product_description
FROM cymbal_products
WHERE product_search_vector @@ to_tsquery('english', 'cherry <-> tree')
ORDER BY product_search_vector <=> to_tsquery('english', 'cherry <-> tree');

10. ハイブリッド検索を実行する

google_vector_utils.hybrid_search() 関数を使用すると、ベクトル検索や全文検索など、複数の検索タイプの結果を組み合わせることができます。この関数は、Reciprocal Rank Fusion（RRF）アルゴリズムを使用して、各検索コンポーネントのランキング結果を 1 つの統合リストに統合します。このアプローチでは、単一の検索タイプのみを使用するよりも関連性の高い結果が得られます。

hybrid_search() 関数は、単一の SQL クエリを動的に構築して実行します。定義した検索コンポーネントごとに共通テーブル式（CTE）を作成します。次に、関数はすべての CTE の結果を結合し、各ドキュメントの最終的な RRF スコアを計算して、統一されたランキングリストを生成します。

この関数を使用するには、プライマリインスタンスで enable_preview_ai_functions を有効にする必要があります。cloudshell で次のコマンドを実行します。

export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags google_ml_integration.enable_preview_ai_functions=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

次のクエリは、前のベクトル検索の質問と全文検索の質問を組み合わせたものです。これは非常にシンプルなハイブリッド検索クエリです。ベクトル検索コンポーネントで「家よりも高い木」、FTS コンポーネントで「カリフォルニア」を使用するなど、より複雑なクエリを試すことができます。

SELECT score, id, p.product_name
FROM ai.hybrid_search(
  search_inputs => ARRAY[
      '{
        "data_type": "vector",
        "table_name": "cymbal_products",
        "key_column": "uniq_id",
        "vec_column": "product_embedding",
        "distance_operator": "public.<=>",
        "limit": 5,
        "query_vector": "ai.embedding(''text-embedding-005'', ''cherry'')::vector"
      }'::JSONB,
      '{
        "data_type": "text",
        "table_name": "cymbal_products",
        "key_column": "uniq_id",
        "text_column": "product_search_vector",
        "limit": 5,
        "ranking_function": "<=>",
        "query_text_input": "tree"
      }'::JSONB
  ]
) JOIN cymbal_products p ON id = p.uniq_id;

想定される出力

"score","id","product_name"
"0.00819672631147241","d536e9e823296a2eba198e52dd23e712","Cherry Tree"
"0.015873015873015872","23e41a71d63d8bbc9bdfa1d118cfddc5","Apple Tree"
"0.00819672631147241","dc789a2f87b142e94e6e325689482af9","Oak Tree"
"0.008064521129029258","f5c70d62ccf3118d73863bf3b17edcbe","Cypress Tree"
"0.008064521129029258","b70c44b1a38c0a2329fa583c9109a80f","Peach Tree"

結果には、指定された key_column である id と、RRF によって計算された最終値である score が含まれます。Reciprocal Rank Fusion（RRF）は、ランクベースのアルゴリズムの一種で、複数の検索結果のランキングリストを 1 つのランキングリストに統合するために、各ドキュメントにスコアを割り当てます。このスコアは、すべての貢献リストにおける RRF の逆数ランクに基づいており、ランクが上位のドキュメントほど貢献度が高くなります。パラメータで include_json_output => true を使用すると、各コンポーネントのスコア計算の内訳を含む detail_json 列が返されます。

全文検索は特定の用語や完全一致の検索に最適ですが、ベクトル検索は単語が一致しない場合でも類義語や意図の検索に優れています。この 2 つの方法を組み合わせることで、ハイブリッド検索では、文字どおり正確で意味的に関連性の高い結果をユーザーに確実に提供できます。

11. 環境をクリーンアップする

ラボの終了時に AlloyDB インスタンスとクラスタを破棄します。

AlloyDB クラスタとすべてのインスタンスを削除する

AlloyDB の試用版を使用した場合。トライアルクラスタを使用して他のラボやリソースをテストする予定がある場合は、トライアルクラスタを削除しないでください。同じプロジェクトに別のトライアルクラスタを作成することはできません。

クラスタは force オプションで破棄され、クラスタに属するすべてのインスタンスも削除されます。

接続が切断され、以前の設定がすべて失われた場合は、Cloud Shell でプロジェクトと環境変数を定義します。

gcloud config set project <your project id>

export REGION=us-central1
export ADBCLUSTER=alloydb-hybrid-search
export PROJECT_ID=$(gcloud config get-value project)

クラスタを削除します。

gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force

想定されるコンソール出力:

student@cloudshell:~ (test-project-001-402417)$ gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force
All of the cluster data will be lost when the cluster is deleted.

Do you want to continue (Y/n)?  Y

Operation ID: operation-1697820178429-6082890a0b570-4a72f7e4-4c5df36f
Deleting cluster...done.

AlloyDB バックアップを削除する

クラスタの AlloyDB バックアップをすべて削除します。

for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done

想定されるコンソール出力:

student@cloudshell:~ (test-project-001-402417)$ for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done
Operation ID: operation-1697826266108-60829fb7b5258-7f99dc0b-99f3c35f
Deleting backup...done.

これで、VM を破棄できます。

GCE VM を削除する

Cloud Shell で、次のコマンドを実行します。

export GCEVM=instance-1
export ZONE=us-central1-a
gcloud compute instances delete $GCEVM \
    --zone=$ZONE \
    --quiet

想定されるコンソール出力:

student@cloudshell:~ (test-project-001-402417)$ export GCEVM=instance-1
export ZONE=us-central1-a
gcloud compute instances delete $GCEVM \
    --zone=$ZONE \
    --quiet
Deleted

12. 完了

以上で、この Codelab は完了です。

学習した内容

AlloyDB クラスタとプライマリインスタンスをデプロイする方法
Google Compute Engine VM から AlloyDB に接続する方法
データベースを作成して AlloyDB AI を有効にする方法
データベースにデータを読み込む方法
AlloyDB Studio の使用方法
Vertex AI でエンベディングを生成する
ScaNN ベクトルインデックスを作成してベクトル検索を高速化する方法
全文検索用に RUM 拡張機能を有効にして使用する方法
全文検索、ベクトル検索、Reciprocal Rank Fusion（RRF）を組み合わせてハイブリッド検索を実行する

AlloyDB でハイブリッド検索を使ってみる

1. はじめに

前提条件

学習内容

必要なもの

2. 設定と要件

プロジェクトのセットアップ

Google Cloud プロジェクトの作成

課金を有効にする

個人用の請求先アカウントを設定する

Cloud Shell の起動

3. はじめに

API を有効にする

API の有効化

API の概要

4. AlloyDB をデプロイする

プライベート IP 範囲を作成する

AlloyDB クラスタを作成する

AlloyDB クラスタを作成する

5. AlloyDB に接続する

GCE VM をデプロイする

Postgres クライアントをインストールする

インスタンスに接続する

6. データベースを準備する

AlloyDB に必要な権限を付与する

データベースを作成する

Vertex AI の統合を有効にする

データをインポート

7. ベクトル エンベディングを生成する

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

ScaNN インデックスを作成する

インデックスの使用状況を検査する

9. 全文検索インデックス

RUM インデックスを作成する

10. ハイブリッド検索を実行する

11. 環境をクリーンアップする

AlloyDB クラスタとすべてのインスタンスを削除する

AlloyDB バックアップを削除する

GCE VM を削除する

12. 完了

学習した内容

7. ベクトルエンベディングを生成する

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