AlloyDB Omni と Kubernetes 上のローカル AI モデル。

1. はじめに

この Codelab では、GKE に AlloyDB Omni をデプロイし、同じ Kubernetes クラスタにデプロイされたオープンエンベディングモデルで使用する方法について学習します。同じ GKE クラスタ内のデータベースインスタンスの横にモデルをデプロイすると、レイテンシとサードパーティサービスへの依存関係が軽減されます。また、データが組織外に漏洩してはならない場合や、サードパーティサービスの利用が許可されていない場合など、セキュリティ要件によって求められることもあります。

前提条件

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

学習内容

Google Kubernetes クラスタに AlloyDB Omni をデプロイする方法
AlloyDB Omni に接続する方法
AlloyDB Omni にデータを読み込む方法
オープンエンベディングモデルを GKE にデプロイする方法
AlloyDB Omni にエンベディングモデルを登録する方法
セマンティック検索用のエンベディングを生成する方法
AlloyDB Omni で生成されたエンベディングをセマンティック検索に使用する方法
AlloyDB でベクトルインデックスを作成して使用する方法

必要なもの

Google Cloud アカウントと Google Cloud プロジェクト
Google Cloud コンソールと Cloud Shell をサポートするウェブブラウザ（Chrome など）

2. 設定と要件

セルフペース型の環境設定

Google Cloud Console にログインして、プロジェクトを新規作成するか、既存のプロジェクトを再利用します。Gmail アカウントも Google Workspace アカウントもまだお持ちでない場合は、アカウントを作成してください。

プロジェクト名は、このプロジェクトの参加者に表示される名称です。Google API では使用されない文字列です。いつでも更新できます。
プロジェクト ID は、すべての Google Cloud プロジェクトにおいて一意でなければならず、不変です（設定後は変更できません）。Cloud コンソールでは一意の文字列が自動生成されます。通常は、この内容を意識する必要はありません。ほとんどの Codelab では、プロジェクト ID（通常は PROJECT_ID と識別されます）を参照する必要があります。生成された ID が好みではない場合は、ランダムに別の ID を生成できます。または、ご自身で試して、利用可能かどうかを確認することもできます。このステップ以降は変更できず、プロジェクトを通して同じ ID になります。
なお、3 つ目の値として、一部の API が使用するプロジェクト番号があります。これら 3 つの値について詳しくは、こちらのドキュメントをご覧ください。

次に、Cloud のリソースや API を使用するために、Cloud コンソールで課金を有効にする必要があります。この Codelab の操作をすべて行って、費用が生じたとしても、少額です。このチュートリアルの終了後に請求が発生しないようにリソースをシャットダウンするには、作成したリソースを削除するか、プロジェクトを削除します。Google Cloud の新規ユーザーは、300 米ドル分の無料トライアルプログラムをご利用いただけます。

Cloud Shell を起動する

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

Google Cloud Console で、右上のツールバーにある Cloud Shell アイコンをクリックします。

プロビジョニングと環境への接続にはそれほど時間はかかりません。完了すると、次のように表示されます。

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

3. はじめに

API を有効にする

出力:

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

PROJECT_ID=$(gcloud config get-value project)
echo $PROJECT_ID

Cloud Shell 構成で定義されていない場合は、次のコマンドを使用して設定します。

export PROJECT_ID=<your project>
gcloud config set project $PROJECT_ID

必要なサービスをすべて有効にします。

gcloud services enable compute.googleapis.com
gcloud services enable container.googleapis.com

想定される出力

student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=test-project-001-402417
student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417
Updated property [core/project].
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable compute.googleapis.com
gcloud services enable container.googleapis.com
Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.

4. GKE に AlloyDB Omni をデプロイする

GKE に AlloyDB Omni をデプロイするには、AlloyDB Omni Operator の要件に記載されている要件に従って Kubernetes クラスタを準備する必要があります。

GKE クラスタを作成する

AlloyDB Omni インスタンスを含む Pod をデプロイするのに十分なプール構成で、標準の GKE クラスタをデプロイする必要があります。Omni には、オペレーターサービスとモニタリングサービス用に少なくとも 2 つの CPU と 8 GB の RAM が必要です。

デプロイの環境変数を設定します。

export PROJECT_ID=$(gcloud config get project)
export LOCATION=us-central1
export CLUSTER_NAME=alloydb-ai-gke
export MACHINE_TYPE=e2-standard-4

次に、gcloud を使用して GKE Standard クラスタを作成します。

gcloud container clusters create ${CLUSTER_NAME} \
  --project=${PROJECT_ID} \
  --region=${LOCATION} \
  --workload-pool=${PROJECT_ID}.svc.id.goog \
  --release-channel=rapid \
  --machine-type=${MACHINE_TYPE} \
  --num-nodes=1

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

student@cloudshell:~ (gleb-test-short-001-415614)$ export PROJECT_ID=$(gcloud config get project)
export LOCATION=us-central1
export CLUSTER_NAME=alloydb-ai-gke
export MACHINE_TYPE=n2-highmem-2
Your active configuration is: [gleb-test-short-001-415614]
student@cloudshell:~ (gleb-test-short-001-415614)$ gcloud container clusters create ${CLUSTER_NAME} \
  --project=${PROJECT_ID} \
  --region=${LOCATION} \
  --workload-pool=${PROJECT_ID}.svc.id.goog \
  --release-channel=rapid \
  --machine-type=${MACHINE_TYPE} \
  --num-nodes=1
Note: The Kubelet readonly port (10255) is now deprecated. Please update your workloads to use the recommended alternatives. See https://cloud.google.com/kubernetes-engine/docs/how-to/disable-kubelet-readonly-port for ways to check usage and for migration instructions.
Note: Your Pod address range (`--cluster-ipv4-cidr`) can accommodate at most 1008 node(s).
Creating cluster alloydb-ai-gke in us-central1..


NAME: omni01
ZONE: us-central1-a
MACHINE_TYPE: e2-standard-4
PREEMPTIBLE: 
INTERNAL_IP: 10.128.0.3
EXTERNAL_IP: 35.232.157.123
STATUS: RUNNING
student@cloudshell:~ (gleb-test-short-001-415614)$

クラスタを準備する

cert-manager サービスなどの必要なコンポーネントをインストールする必要があります。cert-manager のインストールに関するドキュメントの手順に沿って操作します。

Cloud Shell にインストール済みの Kubernetes コマンドラインツール kubectl を使用します。ユーティリティを使用する前に、クラスタの認証情報を取得する必要があります。

gcloud container clusters get-credentials ${CLUSTER_NAME} --region=${LOCATION}

kubectl を使用して cert-manager をインストールできるようになりました。

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.yaml

想定されるコンソール出力（秘匿化済み）:

student@cloudshell:~$ kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.yaml
namespace/cert-manager created
customresourcedefinition.apiextensions.k8s.io/certificaterequests.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/certificates.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/challenges.acme.cert-manager.io created
customresourcedefinition.apiextensions.k8s.io/clusterissuers.cert-manager.io created
...
validatingwebhookconfiguration.admissionregistration.k8s.io/cert-manager-webhook created

AlloyDB Omni をインストール

AlloyDB Omni Operator は、helm ユーティリティを使用してインストールできます。

次のコマンドを実行して、AlloyDB Omni Operator をインストールします。

export GCS_BUCKET=alloydb-omni-operator
export HELM_PATH=$(gcloud storage cat gs://$GCS_BUCKET/latest)
export OPERATOR_VERSION="${HELM_PATH%%/*}"
gcloud storage cp gs://$GCS_BUCKET/$HELM_PATH ./ --recursive
helm install alloydbomni-operator alloydbomni-operator-${OPERATOR_VERSION}.tgz \
--create-namespace \
--namespace alloydb-omni-system \
--atomic \
--timeout 5m

想定されるコンソール出力（秘匿化済み）:

student@cloudshell:~$ gcloud storage cp gs://$GCS_BUCKET/$HELM_PATH ./ --recursive
Copying gs://alloydb-omni-operator/1.2.0/alloydbomni-operator-1.2.0.tgz to file://./alloydbomni-operator-1.2.0.tgz
  Completed files 1/1 | 126.5kiB/126.5kiB
student@cloudshell:~$ helm install alloydbomni-operator alloydbomni-operator-${OPERATOR_VERSION}.tgz \
> --create-namespace \
> --namespace alloydb-omni-system \
> --atomic \
> --timeout 5m
NAME: alloydbomni-operator
LAST DEPLOYED: Mon Jan 20 13:13:20 2025
NAMESPACE: alloydb-omni-system
STATUS: deployed
REVISION: 1
TEST SUITE: None
student@cloudshell:~$

AlloyDB Omni Operator がインストールされたら、データベースクラスタのデプロイに進みます。

googleMLExtension パラメータと内部（プライベート）ロードバランサが有効になっているデプロイマニフェストの例を次に示します。

apiVersion: v1
kind: Secret
metadata:
  name: db-pw-my-omni
type: Opaque
data:
  my-omni: "VmVyeVN0cm9uZ1Bhc3N3b3Jk"
---
apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
  name: my-omni
spec:
  databaseVersion: "15.13.0"
  primarySpec:
    adminUser:
      passwordRef:
        name: db-pw-my-omni
    features:
      googleMLExtension:
        enabled: true
    resources:
      cpu: 1
      memory: 8Gi
      disks:
      - name: DataDisk
        size: 20Gi
        storageClass: standard
    dbLoadBalancerOptions:
      annotations:
        networking.gke.io/load-balancer-type: "internal"
  allowExternalIncomingTraffic: true

パスワードのシークレット値は、パスワード「VeryStrongPassword」の Base64 表現です。より信頼性の高い方法は、Google Secret Manager を使用してパスワード値を保存することです。詳しくは、こちらのドキュメントをご覧ください。

次のステップで適用するために、マニフェストを my-omni.yaml として保存します。Cloud Shell を使用している場合は、ターミナルの右上にある [エディタを開く] ボタンを押してエディタを使用します。

my-omni.yaml という名前でファイルを保存したら、[ターミナルを開く] ボタンを押してターミナルに戻ります。

kubectl ユーティリティを使用して、my-omni.yaml マニフェストをクラスタに適用します。

kubectl apply -f my-omni.yaml

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

secret/db-pw-my-omni created
dbcluster.alloydbomni.dbadmin.goog/my-omni created

kubectl ユーティリティを使用して、my-omni クラスタのステータスを確認します。

kubectl get dbclusters.alloydbomni.dbadmin.goog my-omni -n default

デプロイ中、クラスタはさまざまなフェーズを経て、最終的に DBClusterReady 状態になります。

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

$ kubectl get dbclusters.alloydbomni.dbadmin.goog my-omni -n default
NAME      PRIMARYENDPOINT   PRIMARYPHASE   DBCLUSTERPHASE   HAREADYSTATUS   HAREADYREASON
my-omni   10.131.0.33        Ready          DBClusterReady

AlloyDB Omni に接続する

Kubernetes Pod を使用して接続する

クラスタの準備ができたら、AlloyDB Omni インスタンス Pod で PostgreSQL クライアントバイナリを使用できます。Pod ID を見つけてから、kubectl を使用して Pod に直接接続し、クライアントソフトウェアを実行します。パスワードは VeryStrongPassword です。これは、my-omni.yaml のハッシュで設定されています。

DB_CLUSTER_NAME=my-omni
DB_CLUSTER_NAMESPACE=default
DBPOD=`kubectl get pod --selector=alloydbomni.internal.dbadmin.goog/dbcluster=$DB_CLUSTER_NAME,alloydbomni.internal.dbadmin.goog/task-type=database -n $DB_CLUSTER_NAMESPACE -o jsonpath='{.items[0].metadata.name}'`
kubectl exec -ti $DBPOD -n $DB_CLUSTER_NAMESPACE -c database -- psql -h localhost -U postgres

コンソールの出力例:

DB_CLUSTER_NAME=my-omni
DB_CLUSTER_NAMESPACE=default
DBPOD=`kubectl get pod --selector=alloydbomni.internal.dbadmin.goog/dbcluster=$DB_CLUSTER_NAME,alloydbomni.internal.dbadmin.goog/task-type=database -n $DB_CLUSTER_NAMESPACE -o jsonpath='{.items[0].metadata.name}'`
kubectl exec -ti $DBPOD -n $DB_CLUSTER_NAMESPACE -c database -- psql -h localhost -U postgres
Password for user postgres: 
psql (15.7)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_128_GCM_SHA256, compression: off)
Type "help" for help.

postgres=#

5. GKE に AI モデルをデプロイする

ローカルモデルで AlloyDB Omni AI インテグレーションをテストするには、モデルをクラスタにデプロイする必要があります。

モデルのノードプールを作成する

モデルを実行するには、推論を実行するノードプールを準備する必要があります。パフォーマンスの観点から最適なアプローチは、L4 Nvidia アクセラレータを備えた g2-standard-8 などのノード構成を使用するグラフィックアクセラレータを含むプールです。

L4 アクセラレータを使用してノードプールを作成します。

export PROJECT_ID=$(gcloud config get project)
export LOCATION=us-central1
export CLUSTER_NAME=alloydb-ai-gke
gcloud container node-pools create gpupool \
  --accelerator type=nvidia-l4,count=1,gpu-driver-version=latest \
  --project=${PROJECT_ID} \
  --location=${LOCATION} \
  --node-locations=${LOCATION}-a \
  --cluster=${CLUSTER_NAME} \
  --machine-type=g2-standard-8 \
  --num-nodes=1

想定される出力

student@cloudshell$ export PROJECT_ID=$(gcloud config get project)
Your active configuration is: [pant]
export LOCATION=us-central1
export CLUSTER_NAME=alloydb-ai-gke
student@cloudshell$ gcloud container node-pools create gpupool \
>   --accelerator type=nvidia-l4,count=1,gpu-driver-version=latest \
>   --project=${PROJECT_ID} \
>   --location=${LOCATION} \
>   --node-locations=${LOCATION}-a \
>   --cluster=${CLUSTER_NAME} \
>   --machine-type=g2-standard-8 \
>   --num-nodes=1
Note: Machines with GPUs have certain limitations which may affect your workflow. Learn more at https://cloud.google.com/kubernetes-engine/docs/how-to/gpus
Note: Starting in GKE 1.30.1-gke.115600, if you don't specify a driver version, GKE installs the default GPU driver for your node's GKE version.
Creating node pool gpupool...done.
Created [https://container.googleapis.com/v1/projects/student-test-001/zones/us-central1/clusters/alloydb-ai-gke/nodePools/gpupool].
NAME     MACHINE_TYPE   DISK_SIZE_GB  NODE_VERSION
gpupool  g2-standard-8  100           1.31.4-gke.1183000

Deployment マニフェストを準備する

モデルをデプロイするには、デプロイマニフェストを準備する必要があります。

Hugging Face の BGE Base v1.5 エンベディングモデルを使用しています。モデルカードはこちらでご覧いただけます。モデルをデプロイするには、Hugging Face の準備済みの手順と GitHub のデプロイパッケージを使用します。

パッケージのクローンを作成する

git clone https://github.com/huggingface/Google-Cloud-Containers

マニフェストを編集して、cloud.google.com/gke-accelerator の値を nvidia-l4 に置き換え、リソースに上限を追加します。

vi Google-Cloud-Containers/examples/gke/tei-deployment/gpu-config/deployment.yaml

修正後のマニフェストは次のとおりです。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: tei-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: tei-server
  template:
    metadata:
      labels:
        app: tei-server
        hf.co/model: Snowflake--snowflake-arctic-embed-m
        hf.co/task: text-embeddings
    spec:
      containers:
        - name: tei-container
          image: us-docker.pkg.dev/deeplearning-platform-release/gcr.io/huggingface-text-embeddings-inference-cu122.1-4.ubuntu2204:latest
          resources:
            requests:
              nvidia.com/gpu: 1
            limits:
              nvidia.com/gpu: 1
          env:
            - name: MODEL_ID
              value: Snowflake/snowflake-arctic-embed-m
            - name: NUM_SHARD
              value: "1"
            - name: PORT
              value: "8080"
          volumeMounts:
            - mountPath: /dev/shm
              name: dshm
            - mountPath: /data
              name: data
      volumes:
        - name: dshm
          emptyDir:
            medium: Memory
            sizeLimit: 1Gi
        - name: data
          emptyDir: {}
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-l4

モデルをデプロイする

デプロイ用にサービスアカウントと Namespace を準備する必要があります。

Kubernetes Namespace hf-gke-namespace を作成します。

export NAMESPACE=hf-gke-namespace
kubectl create namespace $NAMESPACE

Kubernetes サービスアカウントを作成する

export SERVICE_ACCOUNT=hf-gke-service-account
kubectl create serviceaccount $SERVICE_ACCOUNT --namespace $NAMESPACE

モデルをデプロイする

kubectl apply -f Google-Cloud-Containers/examples/gke/tei-deployment/gpu-config

デプロイを確認する

kubectl get pods

モデルサービスを確認する

kubectl get service tei-service

実行中の Service タイプ ClusterIP が表示されます。

出力例:

student@cloudshell$ kubectl get service tei-service
NAME          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
tei-service   ClusterIP   34.118.233.48   <none>        8080/TCP   10m

サービス用の CLUSTER-IP をエンドポイントアドレスとして使用します。モデルエンベディングは、URI http://34.118.233.48:8080/embed で応答できます。これは、後で AlloyDB Omni にモデルを登録するときに使用されます。

kubectl port-forward コマンドを使用して公開することで、テストできます。

kubectl port-forward service/tei-service 8080:8080

ポート転送は 1 つの Cloud Shell セッションで実行されるため、テストするには別のセッションが必要です。

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

新しいシェルセッションで curl コマンドを実行します。

curl http://localhost:8080/embed \
    -X POST \
    -d '{"inputs":"Test"}' \
    -H 'Content-Type: application/json'

次のサンプル出力（編集済み）のようなベクトル配列が返されます。

curl http://localhost:8080/embed \
>     -X POST \
>     -d '{"inputs":"Test"}' \
>     -H 'Content-Type: application/json'
[[-0.018975832,0.0071419072,0.06347208,0.022992613,0.014205903
...
-0.03677433,0.01636146,0.06731572]]

6. AlloyDB Omni にモデルを登録する

AlloyDB Omni がデプロイされたモデルと連携して動作するかどうかをテストするには、データベースを作成してモデルを登録する必要があります。

データベースを作成する

ジャンプボックスとして GCE VM を作成し、クライアント VM から AlloyDB Omni に接続してデータベースを作成します。

Omni 用の GKE 外部ロードバランサは、プライベート IP アドレスを使用して VPC からアクセスできますが、VPC の外部から接続することはできません。そのため、ジャンプボックスが必要です。一般的にセキュリティが高く、データベースインスタンスがインターネットに公開されません。図でご確認ください。

Cloud Shell セッションで VM を作成するには、次のコマンドを実行します。

export ZONE=us-central1-a
gcloud compute instances create instance-1 \
    --zone=$ZONE

Cloud Shell で kubectl を使用して AlloyDB Omni エンドポイントの IP を見つけます。

kubectl get dbclusters.alloydbomni.dbadmin.goog my-omni -n default

PRIMARYENDPOINT をメモします。たとえば、

output:

student@cloudshell:~$ kubectl get dbclusters.alloydbomni.dbadmin.goog my-omni -n default
NAME      PRIMARYENDPOINT   PRIMARYPHASE   DBCLUSTERPHASE   HAREADYSTATUS   HAREADYREASON
my-omni   10.131.0.33        Ready          DBClusterReady
student@cloudshell:~$

10.131.0.33 は、AlloyDB Omni インスタンスに接続するために例で使用する IP です。

gcloud を使用して VM に接続します。

gcloud compute ssh instance-1 --zone=$ZONE

SSH 認証鍵の生成を求めるメッセージが表示された場合は、手順に沿って操作します。SSH 接続の詳細については、ドキュメントをご覧ください。

VM への ssh セッションで、PostgreSQL クライアントをインストールします。

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

次の例のように AlloyDB Omni ロードバランサの IP をエクスポートします（IP はロードバランサの IP に置き換えます）。

export INSTANCE_IP=10.131.0.33

AlloyDB Omni に接続します。パスワードは my-omni.yaml のハッシュで設定した VeryStrongPassword です。

psql "host=$INSTANCE_IP user=postgres sslmode=require"

確立された psql セッションで、次のコマンドを実行します。

create database demo;

セッションを終了してデータベースデモに接続します（または、同じセッションで「\c demo」を実行することもできます）。

psql "host=$INSTANCE_IP user=postgres sslmode=require dbname=demo"

変換関数を作成する

サードパーティのエンベディングモデルの場合、モデルと内部関数で想定される形式に入力と出力をフォーマットする変換関数を作成する必要があります。

入力処理を行う変換関数は次のとおりです。

-- Input Transform Function corresponding to the custom model endpoint
CREATE OR REPLACE FUNCTION tei_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_input JSON;
  model_qualified_name TEXT;
BEGIN
  SELECT json_build_object('inputs', input_text, 'truncate', true)::JSON INTO transformed_input;
  RETURN transformed_input;
END;
$$;

サンプル出力に示すように、デモデータベースに接続した状態で、提供されたコードを実行します。

demo=# -- Input Transform Function corresponding to the custom model endpoint
CREATE OR REPLACE FUNCTION tei_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_input JSON;
  model_qualified_name TEXT;
BEGIN
  SELECT json_build_object('inputs', input_text, 'truncate', true)::JSON INTO transformed_input;
  RETURN transformed_input;
END;
$$;
CREATE FUNCTION
demo=#

モデルからのレスポンスを実数の配列に変換する出力関数は次のとおりです。

-- Output Transform Function corresponding to the custom model endpoint
CREATE OR REPLACE FUNCTION tei_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS REAL[]
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_output REAL[];
BEGIN
  SELECT ARRAY(SELECT json_array_elements_text(response_json->0)) INTO transformed_output;
  RETURN transformed_output;
END;
$$;

同じセッションで実行します。

demo=# -- Output Transform Function corresponding to the custom model endpoint
CREATE OR REPLACE FUNCTION tei_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS REAL[]
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_output REAL[];
BEGIN
  SELECT ARRAY(SELECT json_array_elements_text(response_json->0)) INTO transformed_output;
  RETURN transformed_output;
END;
$$;
CREATE FUNCTION
demo=#

モデルを登録する

これで、モデルをデータベースに登録できます。

モデル名 bge-base-1.5 を登録するプロシージャ呼び出しは次のとおりです。IP アドレス 34.118.233.48 は、モデルサービス IP アドレス（kubectl get service tei-service の出力）に置き換えます。

CALL
  google_ml.create_model(
    model_id => 'bge-base-1.5',
    model_request_url => 'http://34.118.233.48:8080/embed',
    model_provider => 'custom',
    model_type => 'text_embedding',
    model_in_transform_fn => 'tei_text_input_transform',
    model_out_transform_fn => 'tei_text_output_transform');

デモデータベースに接続した状態で、提供されたコードを実行します。

demo=# CALL
  google_ml.create_model(
    model_id => 'bge-base-1.5',
    model_request_url => 'http://34.118.233.48:8080/embed',
    model_provider => 'custom',
    model_type => 'text_embedding',
    model_in_transform_fn => 'tei_text_input_transform',
    model_out_transform_fn => 'tei_text_output_transform');
CALL
demo=#

次のテストクエリを使用して、登録モデルをテストできます。このクエリは実数の配列を返します。

select google_ml.embedding('bge-base-1.5','What is AlloyDB Omni?');

7. AlloyDB Omni でモデルをテストする

データの読み込み

AlloyDB Omni がデプロイされたモデルとどのように連携するかをテストするには、データを読み込む必要があります。AlloyDB のベクトル検索に関する他の Codelab の 1 つと同じデータを使用しました。

データを読み込む方法の 1 つは、Google Cloud SDK と PostgreSQL クライアントソフトウェアを使用することです。デモデータベースの作成に使用したクライアント VM を使用できます。VM イメージのデフォルトを使用している場合は、Google Cloud SDK がすでにインストールされています。ただし、Google SDK を使用せずにカスタムイメージを使用している場合は、ドキュメントに沿って追加できます。

次の例のように AlloyDB Omni ロードバランサの IP をエクスポートします（IP はロードバランサの IP に置き換えます）。

export INSTANCE_IP=10.131.0.33

データベースに接続し、pgvector 拡張機能を有効にします。

psql "host=$INSTANCE_IP user=postgres sslmode=require dbname=demo"

psql セッションで次の操作を行います。

CREATE EXTENSION IF NOT EXISTS vector;

psql セッションを終了し、コマンドラインセッションでコマンドを実行して、データをデモデータベースに読み込みます。

テーブルを作成します。

gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_demo_schema.sql |psql "host=$INSTANCE_IP user=postgres dbname=demo"

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

student@cloudshell:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_demo_schema.sql |psql "host=$INSTANCE_IP user=postgres dbname=demo"
Password for user postgres:
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@cloudshell:~$

作成されたテーブルのリストは次のとおりです。

psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "\dt+"

出力:

student@cloudshell:~$ psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "\dt+"
Password for user postgres: 
                                           List of relations
 Schema |       Name       | Type  |  Owner   | Persistence | Access method |    Size    | Description 
--------+------------------+-------+----------+-------------+---------------+------------+-------------
 public | cymbal_embedding | table | postgres | permanent   | heap          | 8192 bytes | 
 public | cymbal_inventory | table | postgres | permanent   | heap          | 8192 bytes | 
 public | cymbal_products  | table | postgres | permanent   | heap          | 8192 bytes | 
 public | cymbal_stores    | table | postgres | permanent   | heap          | 8192 bytes | 
(4 rows)
student@cloudshell:~$

cymbal_products テーブルにデータを読み込みます。

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

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

student@cloudshell:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_products.csv |psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "\copy cymbal_products from stdin csv header"
COPY 941
student@cloudshell:~$

cymbal_products テーブルの数行のサンプルを次に示します。

psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "SELECT uniq_id,left(product_name,30),left(product_description,50),sale_price FROM cymbal_products limit 3"

出力:

student@cloudshell:~$ psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "SELECT uniq_id,left(product_name,30),left(product_description,50),sale_price FROM cymbal_products limit 3"
Password for user postgres: 
             uniq_id              |              left              |                        left                        | sale_price 
----------------------------------+--------------------------------+----------------------------------------------------+------------
 a73d5f754f225ecb9fdc64232a57bc37 | Laundry Tub Strainer Cup       |   Laundry tub strainer cup Chrome For 1-.50, drain |      11.74
 41b8993891aa7d39352f092ace8f3a86 | LED Starry Star Night Light La |  LED Starry Star Night Light Laser Projector 3D Oc |      46.97
 ed4a5c1b02990a1bebec908d416fe801 | Surya Horizon HRZ-1060 Area Ru |  The 100% polypropylene construction of the Surya  |       77.4
(3 rows)
student@cloudshell:~$

cymbal_inventory テーブルにデータを読み込みます。

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

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

student@cloudshell:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_inventory.csv |psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "\copy cymbal_inventory from stdin csv header"
Password for user postgres: 
COPY 263861
student@cloudshell:~$

cymbal_inventory テーブルの数行のサンプルを次に示します。

psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "SELECT * FROM cymbal_inventory LIMIT 3"

出力:

student@cloudshell:~$ psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "SELECT * FROM cymbal_inventory LIMIT 3"
Password for user postgres: 
 store_id |             uniq_id              | inventory 
----------+----------------------------------+-----------
     1583 | adc4964a6138d1148b1d98c557546695 |         5
     1490 | adc4964a6138d1148b1d98c557546695 |         4
     1492 | adc4964a6138d1148b1d98c557546695 |         3
(3 rows)
student@cloudshell:~$

cymbal_stores テーブルにデータを読み込みます。

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

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

student@cloudshell:~$ gcloud storage cat gs://cloud-training/gcc/gcc-tech-004/cymbal_stores.csv |psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "\copy cymbal_stores from stdin csv header"
Password for user postgres: 
COPY 4654
student@cloudshell:~$

cymbal_stores テーブルの数行のサンプルを次に示します。

psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "SELECT store_id, name, zip_code FROM cymbal_stores limit 3"

出力:

student@cloudshell:~$ psql "host=$INSTANCE_IP user=postgres dbname=demo" -c "SELECT store_id, name, zip_code FROM cymbal_stores limit 3"
Password for user postgres: 
 store_id |       name        | zip_code 
----------+-------------------+----------
     1990 | Mayaguez Store    |      680
     2267 | Ware Supercenter  |     1082
     4359 | Ponce Supercenter |      780
(3 rows)
student@cloudshell:~$

エンベディングを構築する

psql を使用してデモデータベースに接続し、cymbal_products テーブルに記述されている商品のエンベディングを商品名と説明に基づいて構築します。

デモデータベースに接続します。

psql "host=$INSTANCE_IP user=postgres sslmode=require dbname=demo"

ここでは、列エンベディングを含む cymbal_embedding テーブルを使用してエンベディングを保存し、関数へのテキスト入力として商品説明を使用しています。

クエリのタイミングを有効にして、後でリモートモデルと比較します。

\timing

クエリを実行してエンベディングを構築します。

INSERT INTO cymbal_embedding(uniq_id,embedding)  SELECT uniq_id, google_ml.embedding('bge-base-1.5',product_description)::vector FROM cymbal_products;

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

demo=#  INSERT INTO cymbal_embedding(uniq_id,embedding)  SELECT uniq_id, google_ml.embedding('bge-base-1.5',product_description)::vector FROM cymbal_products;
INSERT 0 941
Time: 11069.762 ms (00:11.070)
demo=#

この例では、941 件のレコードのエンベディングの構築に約 11 秒かかりました。

テストクエリを実行する

psql を使用してデモデータベースに接続し、エンベディングの構築と同様に、クエリの実行時間を測定するためのタイミングを有効にします。

ベクトル検索のアルゴリズムとしてコサイン距離を使用して、「この地域でよく育つ果樹は何ですか？」というリクエストに一致する上位 5 つの商品を見つけます。

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

SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        (ce.embedding <=> google_ml.embedding('bge-base-1.5','What kind of fruit trees grow well here?')::vector) as distance
FROM
        cymbal_products cp
JOIN cymbal_embedding ce on
        ce.uniq_id=cp.uniq_id
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
        distance ASC
LIMIT 5;

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

demo=# SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        (ce.embedding <=> google_ml.embedding('bge-base-1.5','What kind of fruit trees grow well here?')::vector) as distance
FROM
        cymbal_products cp
JOIN cymbal_embedding ce on
        ce.uniq_id=cp.uniq_id
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
        distance ASC
LIMIT 5;
     product_name      |                                   description                                    | sale_price | zip_code |      distance
-----------------------+----------------------------------------------------------------------------------+------------+----------+---------------------
 California Sycamore   | This is a beautiful sycamore tree that can grow to be over 100 feet tall. It is  |     300.00 |    93230 | 0.22753925487632942
 Toyon                 | This is a beautiful toyon tree that can grow to be over 20 feet tall. It is an e |      10.00 |    93230 | 0.23497374266229387
 California Peppertree | This is a beautiful peppertree that can grow to be over 30 feet tall. It is an e |      25.00 |    93230 | 0.24215884459965364
 California Redwood    | This is a beautiful redwood tree that can grow to be over 300 feet tall. It is a |    1000.00 |    93230 | 0.24564130578287147
 Cherry Tree           | This is a beautiful cherry tree that will produce delicious cherries. It is an d |      75.00 |    93230 | 0.24846117929767153
(5 rows)

Time: 28.724 ms
demo=#

クエリは 28 ミリ秒で実行され、リクエストに一致し、店舗 1583 で在庫がある cymbal_products テーブルのツリーのリストを返しました。

ANN インデックスを構築する

データセットが小さい場合は、すべてのエンベディングをスキャンする完全一致検索を簡単に使用できますが、データが増加すると、読み込み時間と応答時間も増加します。パフォーマンスを向上させるには、エンベディングデータにインデックスを作成します。ベクトルデータに Google ScaNN インデックスを使用する例を次に示します。

接続が切断された場合は、デモデータベースに再接続します。

psql "host=$INSTANCE_IP user=postgres sslmode=require dbname=demo"

alloydb_scann 拡張機能を有効にします。

CREATE EXTENSION IF NOT EXISTS alloydb_scann;

インデックスをビルドします。

CREATE INDEX cymbal_embedding_scann ON cymbal_embedding USING scann (embedding cosine);

前と同じクエリを試して、結果を比較します。

demo=# SELECT
        cp.product_name,
        left(cp.product_description,80) as description,
        cp.sale_price,
        cs.zip_code,
        (ce.embedding <=> google_ml.embedding('bge-base-1.5','What kind of fruit trees grow well here?')::vector) as distance
FROM
        cymbal_products cp
JOIN cymbal_embedding ce on
        ce.uniq_id=cp.uniq_id
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
        distance ASC
LIMIT 5;
     product_name      |                                   description                                    | sale_price | zip_code |      distance
-----------------------+----------------------------------------------------------------------------------+------------+----------+---------------------
 California Sycamore   | This is a beautiful sycamore tree that can grow to be over 100 feet tall. It is  |     300.00 |    93230 | 0.22753925487632942
 Toyon                 | This is a beautiful toyon tree that can grow to be over 20 feet tall. It is an e |      10.00 |    93230 | 0.23497374266229387
 California Peppertree | This is a beautiful peppertree that can grow to be over 30 feet tall. It is an e |      25.00 |    93230 | 0.24215884459965364
 California Redwood    | This is a beautiful redwood tree that can grow to be over 300 feet tall. It is a |    1000.00 |    93230 | 0.24564130578287147
 Fremont Cottonwood    | This is a beautiful cottonwood tree that can grow to be over 100 feet tall. It i |     200.00 |    93230 |  0.2533482837690365
(5 rows)

Time: 14.665 ms
demo=#

クエリの実行時間がわずかに短縮されました。この効果は、大規模なデータセットでより顕著になります。結果はかなり似ており、Cherry が Fremont Cottonwood に置き換えられただけです。

別のクエリを試して、ドキュメントでベクトルインデックスの選択について詳しくご覧ください。

AlloyDB Omni には、さらに多くの機能とラボがあります。

AlloyDB Omni でカラム型エンジンを使用して分析クエリを高速化する

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

これで、AlloyDB Omni と AI モデルを使用して GKE クラスタを削除できます。

GKE クラスタを削除する

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

export PROJECT_ID=$(gcloud config get project)
export LOCATION=us-central1
export CLUSTER_NAME=alloydb-ai-gke
gcloud container clusters delete ${CLUSTER_NAME} \
  --project=${PROJECT_ID} \
  --region=${LOCATION}

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

student@cloudshell:~$ gcloud container clusters delete ${CLUSTER_NAME} \
>   --project=${PROJECT_ID} \
>   --region=${LOCATION}
The following clusters will be deleted.
 - [alloydb-ai-gke] in [us-central1]

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

Deleting cluster alloydb-ai-gke...done.
Deleted

VM の削除

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

export PROJECT_ID=$(gcloud config get project)
export ZONE=us-central1-a
gcloud compute instances delete instance-1 \
  --project=${PROJECT_ID} \
  --zone=${ZONE}

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

student@cloudshell:~$ export PROJECT_ID=$(gcloud config get project)
export ZONE=us-central1-a
gcloud compute instances delete instance-1 \
  --project=${PROJECT_ID} \
  --zone=${ZONE}
Your active configuration is: [cloudshell-5399]
The following instances will be deleted. Any attached disks configured to be auto-deleted will be deleted unless they are attached to any other instances or the `--keep-disks` flag is given and specifies them for keeping. Deleting a disk 
is irreversible and any data on the disk will be lost.
 - [instance-1] in [us-central1-a]

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

Deleted

この Codelab 用に新しいプロジェクトを作成した場合は、代わりにプロジェクト全体を削除できます。https://console.cloud.google.com/cloud-resource-manager

9. 完了

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

学習した内容

Google Kubernetes クラスタに AlloyDB Omni をデプロイする方法
AlloyDB Omni に接続する方法
AlloyDB Omni にデータを読み込む方法
オープンエンベディングモデルを GKE にデプロイする方法
AlloyDB Omni にエンベディングモデルを登録する方法
セマンティック検索用のエンベディングを生成する方法
AlloyDB Omni で生成されたエンベディングをセマンティック検索に使用する方法
AlloyDB でベクトルインデックスを作成して使用する方法

AlloyDB Omni での AI の使用について詳しくは、ドキュメントをご覧ください。

10. アンケート

出力:

このチュートリアルをどのように使用されますか？

全体を通して読むだけ

内容を読んで演習をやり遂げる