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


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

  1. 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.
  2. Install the Google Cloud CLI.
  3. To initialize the gcloud CLI, run the following command:

    gcloud init
  4. Create or select a Google Cloud project.

    • 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.

  5. Make sure that billing is enabled for your Google Cloud project.

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

    gcloud services enable cloudresourcemanager.googleapis.com compute.googleapis.com container.googleapis.com iamcredentials.googleapis.com
  7. Install the Google Cloud CLI.
  8. To initialize the gcloud CLI, run the following command:

    gcloud init
  9. Create or select a Google Cloud project.

    • 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.

  10. Make sure that billing is enabled for your Google Cloud project.

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

    gcloud services enable cloudresourcemanager.googleapis.com compute.googleapis.com container.googleapis.com iamcredentials.googleapis.com
  12. 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 PROJECT_ID with your project ID.
    • Replace USER_IDENTIFIER with the identifier for your user account. For example, user:myemail@example.com.

    • Replace ROLE with each individual role.

環境を設定する

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

  1. プロジェクト、リージョン、Kubernetes クラスタ リソースの接頭辞に環境変数を設定します。

    export PROJECT_ID=PROJECT_ID
    export KUBERNETES_CLUSTER_PREFIX=weaviate
    export REGION=us-central1
    

    PROJECT_ID は、実際の Google Cloud プロジェクト ID に置き換えます。

    このチュートリアルでは、us-central1 リージョンを使用して Deployment リソースを作成します。

  2. Helm のバージョンを確認します。

    helm version
    

    3.13 より古い場合は、バージョンを更新します。

    curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
    
  3. GitHub からサンプルコード リポジトリのクローンを作成します。

    git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples
    
  4. 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_IDREGIONKUBERNETES_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_IDREGIONKUBERNETES_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 --region ${REGION}

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

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

  1. GKE クラスタにデプロイする前に、Weaviate データベースの Helm チャート リポジトリを追加します。

    helm repo add weaviate https://weaviate.github.io/weaviate-helm
    
  2. データベースに Namespace weaviate を作成します。

    kubectl create ns weaviate
    
  3. API キーを保存する Secret を作成します。

    kubectl create secret generic apikeys --from-literal=AUTHENTICATION_APIKEY_ALLOWED_KEYS=$(openssl rand -base64 32) -n weaviate
    
  4. 内部ロードバランサをデプロイして、仮想ネットワーク内から 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
  5. このマニフェストを適用して Elasticsearch クラスタをデプロイします。

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

    weaviate_cluster.yaml マニフェストには Deployment が記述されています。

    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:
          - admin@example.com
    modules:
      text2vec-palm:
        enabled: true
    env:
      AUTHENTICATION_APIKEY_ENABLED: 'true'
      AUTHENTICATION_APIKEY_USERS: 'admin@example.com'
      PROMETHEUS_MONITORING_ENABLED: true
    envSecrets:
      AUTHENTICATION_APIKEY_ALLOWED_KEYS: apikeys
    tolerations:
      - key: "app.stateful/component"
        operator: "Equal"
        value: "weaviate"
        effect: NoSchedule

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

  6. デプロイのステータスを確認します。

    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
    
  7. 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 へのデプロイを行う専用のランタイム テンプレートを使用します。

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

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

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

    [ランタイム テンプレート] に移動

  2. [ 新しいテンプレート] をクリックします。[ランタイム テンプレートの新規作成] ページが表示されます。

  3. [ランタイムの基本情報] セクションで、次の操作を行います。

    • [表示名] フィールドに「weaviate-connect」と入力します。
    • [リージョン] プルダウン リストで、us-central1 を選択します。これは、GKE クラスタと同じリージョンです。
  4. [コンピューティングの構成] セクションで、次の操作を行います。

    • [マシンタイプ] プルダウン リストで [e2-standard-2] を選択します。
    • [ディスクサイズ] フィールドに「30」と入力します。
  5. [ネットワーキングとセキュリティ] セクションで、次の操作を行います。

    • [ネットワーク] プルダウン リストで、GKE クラスタが存在するネットワークを選択します。
    • [サブネットワーク] プルダウン リストで、対応するサブネットワークを選択します。
    • [公共のインターネット アクセスを有効にする] チェックボックスをオフにします。
  6. [作成] をクリックして、ランタイム テンプレートの作成を完了します。ランタイム テンプレートが [ランタイム テンプレート] タブのリストに表示されます。

ランタイムを作成する

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

  1. ランタイム テンプレートのリストで、作成したテンプレートの [操作] 列の をクリックし、[ランタイムを作成] をクリックします。[Vertex AI ランタイムの作成] ペインが表示されます。

  2. [作成] をクリックして、テンプレートに基づいてランタイムを作成します。

  3. 表示された [ランタイム] タブで、ステータスが「正常」に切り替わるまで待ちます。

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

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

  1. [ノートブック] タブに移動し、[Import notebook from URLs] をクリックします。

  2. [インポート ソース] で [URL] を選択します。

  3. [ノートブックの URL] に、raw.githubusercontent.com/epam/kubernetes-engine-samples/Weaviate/databases/weaviate/manifests/02-notebook/vector-database.ipynb を貼り付けます。

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

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

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

  1. ノートブックで、[接続] ボタンの横にある [ Additional connection options] をクリックします。[Vertex AI ランタイムへの接続] ペインが表示されます。

  2. [Connect to a runtime] を選択し、[既存のランタイムに接続] を選択します。

  3. 起動したランタイムを選択し、[接続] をクリックします。

  4. 各コードセルの左側にある [ セルを実行] ボタンをクリックして、ノートブック セルを実行します。

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

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

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

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

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

Prometheus 指標の収集

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

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

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

  1. 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
  2. dashboard.json で定義された構成を使用して、カスタムの Cloud Monitoring ダッシュボードをインポートするには:

    gcloud --project "${PROJECT_ID}" monitoring dashboards create --config-from-file monitoring/dashboard.json
    
  3. コマンドが正常に実行されたら、Cloud Monitoring のダッシュボードに移動します。

    ダッシュボードの概要に移動

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

クリーンアップ

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

プロジェクトを削除する

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

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

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

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

  1. 環境変数を設定します。

    export PROJECT_ID=${PROJECT_ID}
    export KUBERNETES_CLUSTER_PREFIX=weaviate
    export REGION=us-central1
    
  2. 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 クラスタのタイプに応じて、FOLDERgke-autopilot または gke-standard に置き換えます。

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

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

    export disk_list=$(gcloud compute disks list --filter="-users:* AND labels.name=${KUBERNETES_CLUSTER_PREFIX}-cluster" --format "value[separator=|](name,region)")
    
  4. ディスクを削除します。

    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
    
  5. GitHub リポジトリを削除します。

    rm -r ~/kubernetes-engine-samples/
    

次のステップ