GKE に Weaviate ベクトルデータベースをデプロイする

Autopilot Standard

このチュートリアルでは、Google Kubernetes Engine（GKE）に Weaviate ベクトルデータベースクラスタをデプロイする方法について説明します。

Weaviate は、低レイテンシのパフォーマンスと、テキストや画像などのさまざまなメディアタイプの基本サポートを備えたオープンソースのベクトルデータベースです。セマンティック検索、質問応答、分類をサポートしています。Weaviate は Go で構築されており、オブジェクトとベクトルの両方を保存します。これにより、ベクトル検索、キーワード検索、両方の組み合わせたハイブリッド検索を使用できます。インフラストラクチャの観点から、Weaviate はクラウドネイティブでフォールトトレラントなデータベースです。このフォールトトレランスは、データベースクラスタの各ノードが読み取りリクエストと書き込みリクエストを処理できるリーダーレスアーキテクチャによって実現され、これにより、単一障害点が排除されます。

このチュートリアルは、GKE にベクトルデータベースクラスタをデプロイすることに関心があるクラウドプラットフォーム管理者とアーキテクト、ML エンジニア、MLOps（DevOps）の専門家を対象としています。

利点

Weaviate には次のような利点があります。

さまざまなプログラミング言語に対応しているライブラリと、他のサービスと統合できるオープン API。
水平方向のスケーリング。
費用対効果とクエリ速度のバランス（特に大規模なデータセットを扱う場合）。メモリとディスクに保存するデータの量を選択できます。

目標

このチュートリアルでは、以下の方法について学習します。

Weaviate 向けに GKE インフラストラクチャを計画して、デプロイする。
GKE クラスタに Weaviate データベースをデプロイして構成する。
Notebook を実行して、サンプルベクトルエンベディングの生成と保存、ベクトルベースの検索クエリを実行する。

費用

このドキュメントでは、課金対象である次の Google Cloudコンポーネントを使用します。

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。

新規の Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

このドキュメントに記載されているタスクの完了後、作成したリソースを削除すると、それ以上の請求は発生しません。詳細については、クリーンアップをご覧ください。

始める前に

このチュートリアルでは、Cloud Shell を使用してコマンドを実行します。Cloud Shell は、 Google Cloudでホストされているリソースを管理するためのシェル環境です。これには、Google Cloud CLI、kubectl、Helm、Terraform コマンドラインツールがプリインストールされています。Cloud Shell を使用しない場合は、Google Cloud CLI をインストールする必要があります。

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

注: すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して、最新バージョンがインストールされていることを確認してください。

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Resource Manager, Compute Engine, GKE, and IAM Service Account Credentials APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

Install the Google Cloud CLI.

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Resource Manager, Compute Engine, GKE, and IAM Service Account Credentials APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/compute.securityAdmin, roles/compute.viewer, roles/container.clusterAdmin, roles/container.admin, roles/iam.serviceAccountAdmin, roles/iam.serviceAccountUser, roles/monitoring.viewer
```
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
```
Replace the following:
- PROJECT_ID: Your project ID.
- USER_IDENTIFIER: The identifier for your user account. For example, [email protected].
- ROLE: The IAM role that you grant to your user account.

環境の設定

Cloud Shell を使用して環境を設定するには、次の操作を行います。

プロジェクト、リージョン、Kubernetes クラスタリソースの接頭辞に環境変数を設定します。
```
export PROJECT_ID=PROJECT_ID
export KUBERNETES_CLUSTER_PREFIX=weaviate
export REGION=us-central1
```
PROJECT_ID は、実際の Google CloudPROJECT_ID に置き換えます。

このチュートリアルでは、us-central1 リージョンを使用して Deployment リソースを作成します。
Helm のバージョンを確認します。
```
helm version
```
3.13 より古い場合は、バージョンを更新します。
```
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
```
GitHub からサンプルコードリポジトリのクローンを作成します。
```
git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples
```

weaviate ディレクトリに移動します。

cd kubernetes-engine-samples/databases/weaviate

クラスタインフラストラクチャを作成する

このセクションでは、Terraform スクリプトを実行して、限定公開の高可用性リージョン GKE クラスタを作成し、Weaviate データベースをデプロイします。

Weaviate のデプロイには、Standard クラスタまたは Autopilot クラスタを使用できます。それぞれに利点があり、料金モデルも異なります。

Autopilot

次の図は、プロジェクトにデプロイされた Autopilot GKE クラスタを示しています。

GKE Autopilot クラスタ

クラスタインフラストラクチャをデプロイするには、Cloud Shell で次のコマンドを実行します。

export GOOGLE_OAUTH_ACCESS_TOKEN=$(gcloud auth print-access-token)
terraform -chdir=terraform/gke-autopilot init
terraform -chdir=terraform/gke-autopilot apply \
-var project_id=${PROJECT_ID} \
-var region=${REGION} \
-var cluster_prefix=${KUBERNETES_CLUSTER_PREFIX}

GKE は、実行時に次の変数を置き換えます。

GOOGLE_OAUTH_ACCESS_TOKEN は、gcloud auth print-access-token コマンドを使用して、さまざまな Google Cloud APIs とのやり取りを認証するアクセストークンを取得します。
PROJECT_ID、REGION、KUBERNETES_CLUSTER_PREFIX は、環境を設定するセクションで定義した環境変数で、作成する Autopilot クラスタの新しい関連変数に割り当てられます。

プロンプトが表示されたら、「yes」と入力します。

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

...
Apply complete! Resources: 9 added, 0 changed, 0 destroyed.

Outputs:

kubectl_connection_command = "gcloud container clusters get-credentials weaviate-cluster --region us-central1"

Terraform が次のリソースを作成します。

Kubernetes ノード用のカスタム VPC ネットワークとプライベートサブネット
ネットワークアドレス変換（NAT）を介してインターネットにアクセスするための Cloud Router。
us-central1 リージョンの限定公開 GKE クラスタ。
クラスタのロギングとモニタリングの権限を持つ ServiceAccount。
クラスタのモニタリングおよびアラート用の Google Cloud Managed Service for Prometheus の構成。

Standard

次の図は、3 つの異なるゾーンにデプロイされた限定公開のリージョン GKE Standard クラスタを示しています。

GKE Standard クラスタ

クラスタインフラストラクチャをデプロイするには、Cloud Shell で次のコマンドを実行します。

export GOOGLE_OAUTH_ACCESS_TOKEN=$(gcloud auth print-access-token)
terraform -chdir=terraform/gke-standard init
terraform -chdir=terraform/gke-standard apply \
-var project_id=${PROJECT_ID} \
-var region=${REGION} \
-var cluster_prefix=${KUBERNETES_CLUSTER_PREFIX}

GKE は、実行時に次の変数を置き換えます。

GOOGLE_OAUTH_ACCESS_TOKEN は、gcloud auth print-access-token コマンドを使用して、さまざまな Google Cloud APIs とのやり取りを認証するアクセストークンを取得します。
PROJECT_ID、REGION、KUBERNETES_CLUSTER_PREFIX は、環境を設定するセクションで定義した環境変数で、作成する Standard クラスタの新しい関連変数に割り当てられます。

プロンプトが表示されたら、「yes」と入力します。これらのコマンドが完了し、クラスタが「準備完了」ステータスになるまでに数分かかることがあります。

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

...
Apply complete! Resources: 10 added, 0 changed, 0 destroyed.

Outputs:

kubectl_connection_command = "gcloud container clusters get-credentials weaviate-cluster --region us-central1"

Terraform が次のリソースを作成します。

Kubernetes ノード用のカスタム VPC ネットワークとプライベートサブネット
ネットワークアドレス変換（NAT）を介してインターネットにアクセスするための Cloud Router。
自動スケーリングを有効にした us-central1 リージョンの限定公開 GKE クラスタ（ゾーンあたり 1～2 ノード）。
クラスタのロギングとモニタリングの権限を持つ ServiceAccount。
クラスタのモニタリングおよびアラート用の Google Cloud Managed Service for Prometheus の構成。

クラスタに接続する

認証情報を取得し、新しい GKE クラスタと通信できるように kubectl を構成します。

gcloud container clusters get-credentials \
    ${KUBERNETES_CLUSTER_PREFIX}-cluster --location ${REGION}

Weaviate データベースをクラスタにデプロイする

Helm チャートを使用して Weaviate データベースを GKE クラスタにデプロイするには、次の操作を行います。

GKE クラスタにデプロイする前に、Weaviate データベースの Helm チャートリポジトリを追加します。
```
helm repo add weaviate https://weaviate.github.io/weaviate-helm
```
データベースに Namespace weaviate を作成します。
```
kubectl create ns weaviate
```

API キーを保存する Secret を作成します。

kubectl create secret generic apikeys --from-literal=AUTHENTICATION_APIKEY_ALLOWED_KEYS=$(openssl rand -base64 32) -n weaviate

内部ロードバランサをデプロイして、仮想ネットワーク内から Weaviate にアクセスします。

kubectl apply -n weaviate -f manifests/05-ilb/ilb.yaml

ilb.yaml マニフェストには、ロードバランササービスが記述されています。

apiVersion: v1
kind: Service
metadata:
  annotations:
    #cloud.google.com/neg: '{"ingress": true}'
    networking.gke.io/load-balancer-type: "Internal"
  labels:
    app.kubernetes.io/name: weaviate
  name: weaviate-ilb
spec:
  ports:
  - name: http
    port: 8080
    protocol: TCP
    targetPort: 8080
  - name: grpc
    port: 50051
    protocol: TCP
    targetPort: 50051
  selector:
    app: weaviate
  type: LoadBalancer

このマニフェストを適用して Weaviate クラスタをデプロイします。

helm upgrade --install "weaviate" weaviate/weaviate \
--namespace "weaviate" \
--values ./manifests/01-basic-cluster/weaviate_cluster.yaml

weaviate_cluster.yaml マニフェストには Deployment が記述されています。Deployment は、クラスタ内のノードに分散された Pod の複数のレプリカを実行できる Kubernetes API オブジェクトです。

initContainers:
  sysctlInitContainer:
    enabled: false
  extraInitContainers: {}
resources: 
   requests:
     cpu: '1'
     memory: '4Gi'
   limits:
     cpu: '2'
     memory: '4Gi'
replicas: 3
storage:
  size: 10Gi
  storageClassName: "premium-rwo"
service:
  name: weaviate
  ports:
    - name: http
      protocol: TCP
      port: 80
  type: ClusterIP
grpcService:
  enabled: true
  name: weaviate-grpc
  ports:
    - name: grpc
      protocol: TCP
      port: 50051
  type: ClusterIP
authentication:
  anonymous_access:
    enabled: false
authorization:
  admin_list:
    enabled: true
    users:
      - [email protected]
modules:
  text2vec-palm:
    enabled: true
env:
  AUTHENTICATION_APIKEY_ENABLED: 'true'
  AUTHENTICATION_APIKEY_USERS: '[email protected]'
  PROMETHEUS_MONITORING_ENABLED: true
envSecrets:
  AUTHENTICATION_APIKEY_ALLOWED_KEYS: apikeys
tolerations:
  - key: "app.stateful/component"
    operator: "Equal"
    value: "weaviate"
    effect: NoSchedule

Weaviate クラスタが完全に起動するまで数分待ちます。

Deployment のステータスを確認します。

kubectl get weaviate -n weaviate --watch

weaviate データベースが正常にデプロイされると、次のように出力されます。

NAME: weaviate
LAST DEPLOYED: Tue Jun 18 13:15:53 2024
NAMESPACE: weaviate
STATUS: deployed
REVISION: 1
TEST SUITE: None

Kubernetes がリソースを起動するまで待ちます。

kubectl wait pods -l app.kubernetes.io/name=weaviate --for condition=Ready --timeout=300s -n weaviate

Vertex AI Colab Enterprise ノートブックでクエリを実行する

このセクションでは、Colab Enterprise を使用して Weaviate データベースに接続する方法について説明します。ノートブックが GKE クラスタ内のリソースと通信できるように、weaviate-vpc へのデプロイを行う専用のランタイムテンプレートを使用します。

Vertex AI Colab Enterprise の詳細については、Colab Enterprise のドキュメントをご覧ください。

ランタイムテンプレートを作成する

Colab Enterprise ランタイムテンプレートを作成するには:

Google Cloud コンソールで、Colab Enterprise の [ランタイムテンプレート] ページに移動し、プロジェクトが選択されていることを確認します。

[ランタイムテンプレート] に移動
[ 新しいテンプレート] をクリックします。[ランタイムテンプレートの新規作成] ページが表示されます。
[ランタイムの基本情報] セクションで、次の操作を行います。
- [表示名] フィールドに「weaviate-connect」と入力します。
- [リージョン] プルダウンリストで、us-central1 を選択します。これは、GKE クラスタと同じリージョンです。
[コンピューティングの構成] セクションで、次の操作を行います。
- [マシンタイプ] プルダウンリストで [e2-standard-2] を選択します。
- [ディスクサイズ] フィールドに「30」と入力します。
[ネットワーキングとセキュリティ] セクションで、次の操作を行います。
- [ネットワーク] プルダウンリストで、GKE クラスタが存在するネットワークを選択します。
- [サブネットワーク] プルダウンリストで、対応するサブネットワークを選択します。
- [公共のインターネットアクセスを有効にする] チェックボックスをオフにします。
ランタイムテンプレートの作成を完了するには、[作成] をクリックします。ランタイムテンプレートが [ランタイムテンプレート] タブのリストに表示されます。

ランタイムを作成する

Colab Enterprise ランタイムを作成するには:

ランタイムテンプレートのリストで、作成したテンプレートの [操作] 列のをクリックし、[ランタイムを作成] をクリックします。[Vertex AI ランタイムの作成] ペインが表示されます。
テンプレートに基づいてランタイムを作成するには、[作成] をクリックします。
表示された [ランタイム] タブで、ステータスが「正常」に切り替わるまで待ちます。

ノートブックをインポートする

Colab Enterprise でノートブックをインポートするには:

[マイノートブック] タブに移動し、[インポート] をクリックします。[ノートブックのインポート] ペインが表示されます。
[インポートソース] で [URL] を選択します。

[ノートブックの URL] に、次のリンクを貼り付けます。

https://raw.githubusercontent.com/GoogleCloudPlatform/kubernetes-engine-samples/main/databases/weaviate/manifests/02-notebook/vector-database.ipynb

[インポート] をクリックします。

ランタイムに接続してクエリを実行する

ランタイムに接続してクエリを実行するには:

ノートブックで、[接続] ボタンの横にある [ その他の接続オプション] をクリックします。[Vertex AI ランタイムへの接続] ペインが表示されます。
[ランタイムに接続] を選択し、[既存のランタイムに接続] を選択します。
起動したランタイムを選択し、[接続] をクリックします。
ノートブックセルを実行するには、各コードセルの横にある [ セルを実行] ボタンをクリックします。

ノートブックには、コードセルと、各コードブロックを説明するテキストの両方が含まれています。コードセルを実行すると、そのコマンドが実行され、出力が表示されます。セルを順番に実行することも、必要に応じて個別に実行することもできます。

クラスタの Prometheus 指標を表示する

GKE クラスタは Google Cloud Managed Service for Prometheus で構成されており、Prometheus 形式での指標の収集が可能です。このサービスは、モニタリングとアラート用のフルマネージドソリューションを提供し、クラスタとそのアプリケーションからの指標の収集、保存、分析を可能にします。

次の図は、Prometheus がクラスタの指標を収集する方法を示しています。

Prometheus 指標の収集

この図の GKE 限定公開クラスタには、次のコンポーネントが含まれています。

パス /metrics とポート 2112 で指標を公開する Weaviate Pod。
Weaviate Pod からの指標を処理する Prometheus ベースのコレクタ。
Cloud Monitoring に指標を送信する PodMonitoring リソース

指標をエクスポートして表示する手順は次のとおりです。

labelSelector で指標を収集する PodMonitoring リソースを作成します。

kubectl apply -n weaviate -f manifests/03-prometheus-metrics/pod-monitoring.yaml

pod-monitoring.yaml マニフェストには、PodMonitoring リソースが記述されています。

apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: weaviate
spec:
  selector:
    matchLabels:
      app: weaviate
  endpoints:
  - port: 2112
    interval: 30s
    path: /metrics

dashboard.json で定義された構成を使用して、カスタムの Cloud Monitoring ダッシュボードをインポートするには:
```
gcloud --project "${PROJECT_ID}" monitoring dashboards create --config-from-file monitoring/dashboard.json
```
コマンドが正常に実行されたら、Cloud Monitoring のダッシュボードに移動します。

ダッシュボードの概要に移動
ダッシュボードのリストで、Weaviate Overview ダッシュボードを開きます。指標の収集と表示に時間がかかる場合があります。ダッシュボードに、シャード、ベクトル、オペレーションのレイテンシの量が表示されます

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

プロジェクトを削除する

課金が発生しないようにする最も簡単な方法は、このチュートリアル用に作成したプロジェクトを削除することです。

注意: プロジェクトを削除すると、次のような影響があります。

プロジェクト内のすべてのものが削除されます。このドキュメントのタスクで既存のプロジェクトを使用した場合、それを削除すると、そのプロジェクトで行った他の作業もすべて削除されます。
カスタムプロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタムプロジェクト ID を作成した可能性があります。そのプロジェクト ID を使用した URL（たとえば、appspot.com）を保持するには、プロジェクト全体ではなくプロジェクト内の選択したリソースだけを削除します。

複数のアーキテクチャ、チュートリアル、クイックスタートを実施する予定がある場合は、プロジェクトを再利用すると、プロジェクトの割り当て上限を超えないようにすることができます。

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

プロジェクトを削除すると、クリーンアップが完了します。プロジェクトを削除していない場合は、個々のリソースを削除します。

リソースを個別に削除する

環境変数を設定します。

export PROJECT_ID=${PROJECT_ID}
export KUBERNETES_CLUSTER_PREFIX=weaviate
export REGION=us-central1

terraform destroy コマンドを実行します。
```
export GOOGLE_OAUTH_ACCESS_TOKEN=$(gcloud auth print-access-token)
terraform  -chdir=terraform/FOLDER destroy \
-var project_id=${PROJECT_ID} \
-var region=${REGION} \
-var cluster_prefix=${KUBERNETES_CLUSTER_PREFIX}
```
作成した GKE クラスタのタイプに応じて、FOLDER を gke-autopilot または gke-standard に置き換えます。

プロンプトが表示されたら、「yes」と入力します。

アタッチされていないすべてのディスクを検索します。

export disk_list=$(gcloud compute disks list --filter="-users:* AND labels.name=${KUBERNETES_CLUSTER_PREFIX}-cluster" --format "value[separator=|](name,region)")

ディスクを削除します。

for i in $disk_list; do
 disk_name=$(echo $i| cut -d'|' -f1)
 disk_region=$(echo $i| cut -d'|' -f2|sed 's|.*/||')
 echo "Deleting $disk_name"
 gcloud compute disks delete $disk_name --region $disk_region --quiet
done

GitHub リポジトリを削除します。
```
rm -r ~/kubernetes-engine-samples/
```

次のステップ

GKE Marketplace で Weaviate を確認する。
GKE にデータベースをデプロイするためのベストプラクティスについて学習する。
GKE でデータ量の多いワークロードを実行するためのソリューションを確認する。

GKE に Weaviate ベクトル データベースをデプロイする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

利点

目標

費用

始める前に

環境の設定

クラスタ インフラストラクチャを作成する

Autopilot

Standard

クラスタに接続する

Weaviate データベースをクラスタにデプロイする

Vertex AI Colab Enterprise ノートブックでクエリを実行する

ランタイム テンプレートを作成する

ランタイムを作成する

ノートブックをインポートする

ランタイムに接続してクエリを実行する

クラスタの Prometheus 指標を表示する

クリーンアップ

プロジェクトを削除する

リソースを個別に削除する

次のステップ

GKE に Weaviate ベクトルデータベースをデプロイする

クラスタインフラストラクチャを作成する

ランタイムテンプレートを作成する