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

環境を設定する

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

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

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

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

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

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. qdrant ディレクトリに移動して、Deployment リソースの作成を開始します。

   cd kubernetes-engine-samples/databases/qdrant
   

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

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

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

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}

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

Outputs:

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

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}

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

Outputs:

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

クラスタに接続する

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

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

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

このチュートリアルでは、Helm チャートを使用して、Qdrant データベース（分散モード）と Stateful HA Operator を GKE クラスタにデプロイします。

デプロイにより、次の構成で GKE クラスタが作成されます。

• Qdrant ノードの 3 つのレプリカ。
• Kubernetes ノード全体に適切に分散されるように、toleration、ノード アフィニティ、トポロジ分散の制約が構成されます。これにより、ノードプールとさまざまなアベイラビリティ ゾーンが利用されます。
• SSD ディスクタイプの RePD ボリュームは、データ ストレージ用にプロビジョニングされます。
• Stateful HA オペレーターは、フェイルオーバー プロセスを管理し、高可用性を確保するために使用されます。
• 認証のため、データベースは API キーを含む Kubernetes Secret を作成します。

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

1. StatefulHA アドオンを有効にする

   Autopilot

   GKE は、クラスタの作成時に StatefulHA アドオンを自動的に有効にします。

   Standard

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

   gcloud container clusters update ${KUBERNETES_CLUSTER_PREFIX}-cluster \
       --project=${PROJECT_ID} \
       --region=${REGION} \
       --update-addons=StatefulHA=ENABLED
   

   このコマンドが完了し、クラスタが準備完了ステータスになるまでに 15 分かかることがあります。

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

   helm repo add qdrant https://qdrant.github.io/qdrant-helm
   

3. データベースの Namespace qdrant を作成します。

   kubectl create ns qdrant
   

4. マニフェストを適用して、リージョン SSD 永続ディスク StorageClass を作成します。

   kubectl apply -n qdrant -f manifests/01-regional-pd/regional-pd.yaml
   

   regional-pd.yaml マニフェストには、永続 SSD ディスク StorageClass が記述されています。

   apiVersion: storage.k8s.io/v1
   kind: StorageClass
   allowVolumeExpansion: true
   metadata:
     name: ha-regional
   parameters:
     replication-type: regional-pd
     type: pd-ssd
     availability-class: regional-hard-failover
   provisioner: pd.csi.storage.gke.io
   reclaimPolicy: Retain
   volumeBindingMode: WaitForFirstConsumer

5. Helm を使用して、metrics サイドカー構成と Qdrant クラスタを含む Kubernetes configmap をデプロイします。

   kubectl apply -n qdrant -f manifests/03-prometheus-metrics/metrics-cm.yaml
   helm install qdrant-database qdrant/qdrant -n qdrant \
   -f manifests/02-values-file/values.yaml
   

   metrics-cm.yaml マニフェストには、metrics サイドカー ConfigMap が記述されています。

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: nginx-conf
   data:
     default.conf.template: |
       server {
         listen 80;
         location / {
           proxy_pass http://localhost:6333/metrics;
           proxy_http_version 1.1;
           proxy_set_header Host $http_host;
           proxy_set_header api-key ${QDRANT_APIKEY};
           proxy_set_header X-Forwarded-For $remote_addr;
         }
       }

   values.yaml マニフェストには、Qdrant クラスタの構成が記述されています。

   replicaCount: 3
   
   config:
     service:
       enable_tls: false
     cluster:
       enabled: true
     storage:
       optimizers:
         deleted_threshold: 0.5
         vacuum_min_vector_number: 1500
         default_segment_number: 2
         max_segment_size_kb: null
         memmap_threshold_kb: null
         indexing_threshold_kb: 25000
         flush_interval_sec: 5
         max_optimization_threads: 1
   
   livenessProbe:
     enabled: true
     initialDelaySeconds: 60
   
   resources:
     limits:
       cpu: "2"
       memory: 4Gi
     requests:
       cpu: "1"
       memory: 4Gi
   
   tolerations:
     - key: "app.stateful/component"
       operator: "Equal"
       value: "qdrant"
       effect: NoSchedule
   
   affinity:
     nodeAffinity:
       preferredDuringSchedulingIgnoredDuringExecution:
       - weight: 1
         preference:
           matchExpressions:
           - key: "app.stateful/component"
             operator: In
             values:
             - "qdrant"
   
   topologySpreadConstraints:
     - maxSkew: 1
       topologyKey: "topology.kubernetes.io/zone"
       whenUnsatisfiable: ScheduleAnyway
       labelSelector:
         matchLabels:
           app.kubernetes.io/name: qdrant
           app.kubernetes.io/instance: qdrant
   
   podDisruptionBudget:
     enabled: true
     maxUnavailable: 1
   
   persistence:
     accessModes: ["ReadWriteOnce"]
     size: 10Gi
     storageClassName: ha-regional
   
   apiKey: true
   
   sidecarContainers:
     - name: metrics
       image: nginx:1.27
       resources:
         requests:
           memory: "128Mi"
           cpu: "250m"
         limits:
           memory: "128Mi"
           cpu: "500m"
       ports:
       - containerPort: 80
       env:
       - name: QDRANT_APIKEY 
         valueFrom:
           secretKeyRef:
             name: qdrant-database-apikey          
             key: api-key
       volumeMounts:
           - name: nginx-conf
             mountPath: /etc/nginx/templates/default.conf.template
             subPath: default.conf.template
             readOnly: true
   additionalVolumes:
     - name: nginx-conf
       configMap:
         name: nginx-conf
         items:
           - key: default.conf.template
             path: default.conf.template 

   この構成により、クラスタモードが有効になり、高可用性の分散 Qdrant クラスタを設定できます。

6. Qdrant StatefulSet にラベルを追加します。

   kubectl label statefulset qdrant-database examples.ai.gke.io/source=qdrant-guide -n qdrant
   

7. 内部ロードバランサをデプロイして、GKE クラスタと同じ VPC で実行されている Elasticsearch データベースにアクセスします。

   kubectl apply -n qdrant -f manifests/02-values-file/ilb.yaml
   

   ilb.yaml マニフェストには、LoadBalancer Service が記述されています。

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

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

   helm ls -n qdrant
   

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

   NAME    NAMESPACE       REVISION        UPDATED                                 STATUS          CHART           APP VERSION
   qdrant-database  qdrant          1               2024-02-06 20:21:15.737307567 +0000 UTC deployed        qdrant-0.7.6    v1.7.4
   

9. GKE が必要なワークロードを開始するまで待ちます。

   kubectl wait pods -l app.kubernetes.io/instance=qdrant-database --for condition=Ready --timeout=300s -n qdrant
   

   このコマンドが正常に完了するまで数分かかる場合があります。

10. GKE がワークロードを開始したら、GKE は Qdrant ワークロードを作成したことを確認します。

    kubectl get pod,svc,statefulset,pdb,secret -n qdrant
    

11. Qdrant の HighAvailabilityApplication（HAA）リソースを起動します。

    kubectl apply -n qdrant -f manifests/01-regional-pd/ha-app.yaml
    

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

    kind: HighAvailabilityApplication
    apiVersion: ha.gke.io/v1
    metadata:
      name: qdrant-database
      namespace: qdrant
    spec:
      resourceSelection:
        resourceKind: StatefulSet
      policy:
        storageSettings:
          requireRegionalStorage: true
        failoverSettings:
          forceDeleteStrategy: AfterNodeUnreachable
          afterNodeUnreachable:
            afterNodeUnreachableSeconds: 20 # 60 seconds total

    Qdrant クラスタ用に、次の GKE リソースが作成されます。

    • 3 つの Pod レプリカを制御する Qdrant StatefulSet。
    • A PodDisruptionBudget。使用できないレプリカが最大 1 つ確保されます。
    • qdrant-database Service。ノード間のインバウンド接続とレプリケーション用に Qdrant ポートを公開します。
    • qdrant-database-headless Service。実行中の Qdrant Pod のリストを提供します。
    • qdrant-database-apikey Secret。安全なデータベース接続を容易にします。
    • Qdrant アプリケーションをアクティブにモニタリングする、ステートフル HA オペレーター Pod と HighlyAvailableApplication リソース。HighlyAvailableApplication リソースは、Qdrant に適用するフェイルオーバー ルールを定義します。

12. フェイルオーバー ルールが適用されているかどうかを確認するには、リソースの説明を取得して Status: Message: Application is protected を確認します。

    kubectl describe highavailabilityapplication qdrant-database -n qdrant
    

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

    Status:
    Conditions:
        Last Transition Time:  2023-11-30T09:54:52Z
        Message:               Application is protected
        Observed Generation:   1
        Reason:                ApplicationProtected
        Status:                True
        Type:                  Protected
    

データセットをアップロードして、Jupyter Notebook で検索クエリを実行する

Qdrant はベクトルとペイロードをコレクションに整理します。ベクトル エンベディングは、セマンティック関係を維持しながら単語やエンティティを数値ベクトルとして表す手法です。これは類似検索にとって重要な機能となります。完全一致ではなく意味に基づいて類似性を見つけて、検索やレコメンデーション システムなどのタスクをより効果的に、細やかに処理できるためです。

このセクションでは、新しい Qdrant コレクションにベクトルをアップロードし、検索クエリを実行する方法について説明します。

この例では、さまざまなジャンルの書籍のリストを含む CSV ファイルのデータセットを使用します。Qdrant は検索エンジンとして機能し、作成した Jupyter ノートブック Pod は Qdrant データベースをクエリするクライアントとして機能します。

1. books-dataset ConfigMap と demo-app ConfigMap を作成し、Jupyter ノートブックをデプロイします。

   kubectl create -n qdrant configmap books-dataset --from-file=manifests/04-notebook/dataset.csv
   kubectl create -n qdrant configmap notebook --from-file=manifests/04-notebook/vector-database.ipynb
   kubectl apply -n qdrant -f manifests/04-notebook/jupyter.yaml
   

   • 先ほど作成した qdrant-apikey という名前の Secret が、APIKEY という環境変数としてクライアント Pod にマウントされます。
   • books-dataset ConfigMap には、Qdrant コレクションの書籍データを含む csv ファイルが含まれています。
   • notebook ConfigMap には、books-dataset から Qdrant コレクションを作成する Jupyter ノートブックが含まれています。

2. GKE による Jupyter Pod の起動を待ちます。

   kubectl wait pods -l app=jupyter-notebook --for condition=Ready --timeout=300s -n qdrant
   

3. この URL を開き、vector-database.ipynb ファイルをクリックします。[実行] -> [すべてのセルを実行] を押します。Jupyter はすべてのコードを実行し、検索クエリを実行します。

   このクエリは、Qdrant の my_books コレクションに対してセマンティック検索を行い、クエリテキストに関連する一致スコアが最も高い検索結果を最大 2 件取得します。

   各結果が次のような形式で出力されます。それぞれの結果はダッシュのみの行で区切って出力されます。

   • Title: 書籍のタイトル
   • Author: 書籍の著者
   • Description: ドキュメントの description メタデータ フィールドに保存されている値
   • Published: 書籍の出版日
   • Score: Qdrant の関連性スコア

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

   Title: Romeo and Juliet
   Author: William Shakespeare, Paul Werstine (Editor), Barbara A. Mowat (Editor),
   Paavo Emil Cajander (Translator)
   Description: In Romeo and Juliet, Shakespeare creates a violent world, in which
   two young people fall in love. It is not simply that their families disapprove;
   the Montagues and the Capulets are engaged in a blood feud.In this death-filled
   setting, the movement from love at first sight to the lovers' final union in
   death seems almost inevitable. And yet, this play set in an extraordinary world
   has become the quintessential story of young love. In part because of its exquisite
   language, it is easy to respond as if it were about all young lovers. Published: 01/01/04
   Score: 0.8935013
   -----
   Title: The Unbearable Lightness of Being
   Author: Milan Kundera, Michael Henry Heim (Translator)
   Description: In The Unbearable Lightness of Being, Milan Kundera tells the story
   of a young woman in love with a man torn between his love for her and his incorrigible
   womanizing and one of his mistresses and her humbly faithful lover. This magnificent
   novel juxtaposes geographically distant places, brilliant and playful reflections,
   and a variety of styles, to take its place as perhaps the major achievement of
   one of the world's truly great writers. Published: 10/27/09
   Score: 0.8931863
   -----
   

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

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

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

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

• パス / とポート 80 で指標を公開する Qdrant Pod。これらの指標は、metrics というサイドカー コンテナによって提供されます。
• Qdrant Pod からの指標を処理する Prometheus ベースのコレクタ。
• Cloud Monitoring に指標を送信する PodMonitoring リソース

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

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

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

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

   apiVersion: monitoring.googleapis.com/v1
   kind: PodMonitoring
   metadata:
     name: qdrant
   spec:
     selector:
       matchLabels:
         app: qdrant
         app.kubernetes.io/instance: qdrant-database
     endpoints:
     - port: 80
       interval: 30s
       path: / 

2. dashboard.json で定義された構成を使用して、Cloud Monitoring ダッシュボードを作成します。

   gcloud --project "${PROJECT_ID}" monitoring dashboards create --config-from-file monitoring/dashboard.json
   

3. コマンドが正常に実行されたら、Cloud Monitoring のダッシュボードに移動します。

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

4. ダッシュボードのリストで、Qdrant Overview ダッシュボードを開きます。指標の収集と表示には 1～2 分かかる場合があります。

   ダッシュボードには、次の主要な指標のカウントが表示されます。

   • コレクション
   • 埋め込みベクトル
   • 保留中のオペレーション
   • 実行中のノード

クラスタ構成をバックアップする

Backup for GKE 機能を使用すると、デプロイされたワークロードとそのデータを含む GKE クラスタ構成全体の定期的なバックアップ スケジュールを設定できます。

このチュートリアルでは、Secret と Volume を含むすべてのワークロードのバックアップを毎日午前 3 時に実行するように、GKE クラスタのバックアップ プランを構成します。ストレージ管理を効率的に行うため、3 日以上経過したバックアップは自動的に削除されます。

バックアップ プランを構成する手順は次のとおりです。

1. クラスタで Backup for GKE 機能を有効にします。

   gcloud container clusters update ${KUBERNETES_CLUSTER_PREFIX}-cluster \
   --project=${PROJECT_ID} \
   --region=${REGION} \
   --update-addons=BackupRestore=ENABLED
   

2. クラスタ内のすべての Namespace の日次スケジュールでバックアップ プランを作成します。

   gcloud beta container backup-restore backup-plans create ${KUBERNETES_CLUSTER_PREFIX}-cluster-backup \
   --project=${PROJECT_ID} \
   --location=${REGION} \
   --cluster="projects/${PROJECT_ID}/locations/${REGION}/clusters/${KUBERNETES_CLUSTER_PREFIX}-cluster" \
   --all-namespaces \
   --include-secrets \
   --include-volume-data \
   --cron-schedule="0 3 * * *" \
   --backup-retain-days=3
   

   このコマンドは、実行時に関連する環境変数を使用します。

   クラスタ名の形式は、プロジェクトとリージョンに対して相対的です。

   projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME
   

   プロンプトが表示されたら、「y.」と入力します。出力は次のようになります。

   Create request issued for: [qdrant-cluster-backup]
   Waiting for operation [projects/PROJECT_ID/locations/us-central1/operations/operation-1706528750815-610142ffdc9ac-71be4a05-f61c99fc] to complete...⠹
   

   このオペレーションが正常に完了するまで数分かかることがあります。実行が完了すると、出力は次のようになります。

   Created backup plan [qdrant-cluster-backup].
   

3. 新しく作成したバックアップ プラン qdrant-cluster-backup が Backup for GKE コンソールに表示されます。

   Backup for GKE に移動

保存したバックアップ構成を復元する場合は、バックアップを復元するをご覧ください。