在 GKE 上部署 Qdrant 向量資料庫

本指南說明如何在 Google Kubernetes Engine (GKE) 上部署 Qdrant 向量資料庫叢集。

向量資料庫是專門用於管理及搜尋大量高維度向量的資料儲存庫。這些向量代表文字、圖片、音訊、影片等資料，或任何可編碼為數值的資料。傳統資料庫依賴完全相符的項目，而向量資料庫則專門從大型資料集中找出類似項目或識別模式。因此 Qdrant 適用於各種應用程式，包括神經網路或語意比對、多面向搜尋等。Qdrant 不僅是向量資料庫，也是向量相似度搜尋引擎。

本教學課程適用於有興趣在 GKE 上部署 Qdrant 資料庫叢集的雲端平台管理員和架構師、機器學習工程師，以及 MLOps (DevOps) 專業人員。

優點

Qdrant 具有下列優點：

  • 提供各種程式設計語言的程式庫和開放式 API，可與其他服務整合。
  • 支援水平擴充，以及簡化擴充和高可用性的分片和複製作業。
  • 支援容器和 Kubernetes，可在新式雲端原生環境中部署及管理。
  • 彈性酬載，可透過進階篩選功能精確調整搜尋條件。
  • 多種量化選項和其他最佳化措施，可降低基礎架構成本並提升效能。

目標

在本教學課程中，您將瞭解以下內容：

  • 規劃及部署 Qdrant 的 GKE 基礎架構。
  • 部署 StatefulHA 運算子，確保 Qdrant 高可用性。
  • 部署及設定 Qdrant 叢集。
  • 上傳示範資料集，然後執行簡單的搜尋查詢。
  • 收集指標並執行資訊主頁。

部署架構

這個架構會在多個可用區中，為 Qdrant 設定容錯且可擴充的 GKE 叢集，確保正常運作時間和可用性，並盡量減少滾動式更新造成的服務中斷。包括使用 StatefulHA 運算子，有效管理容錯移轉。詳情請參閱「區域叢集」一節。

架構圖

下圖顯示在 GKE 叢集的多個節點和區域中執行的 Qdrant 叢集：

Qdrant 部署架構

在這個架構中，Qdrant StatefulSet 會部署在三個不同可用區的三個節點上。

  • 您可以在 Helm 圖表值檔案中設定必要的 Pod 親和性規則和拓撲擴散限制，控管 GKE 在節點間分配 Pod 的方式。
  • 如果一個區域失效，GKE 會根據建議的設定，在新節點上重新排定 Pod。

為確保資料持續性，本教學課程的架構具有下列特徵：

  • 並使用區域 SSD 磁碟 (自訂regional-pd StorageClass) 持久儲存資料。我們建議為資料庫使用地區 SSD 磁碟，因為這類磁碟的延遲時間短，且 IOPS 效能高。
  • 區域中的主要和次要可用區之間會複製所有磁碟資料，提高對潛在可用區故障的容錯能力。

設定環境

如要使用 Cloud Shell 設定環境，請按照下列步驟操作：

  1. 為專案、區域和 Kubernetes 叢集資源前置字串設定環境變數：

    基於本教學課程的目的，請使用 us-central1 地區建立部署資源。

    export PROJECT_ID=PROJECT_ID
export KUBERNETES_CLUSTER_PREFIX=qdrant
export REGION=us-central1
    • 將 PROJECT_ID 替換為專案 ID。 Google Cloud

  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 目錄，開始建立部署資源：

    cd kubernetes-engine-samples/databases/qdrant

建立叢集基礎架構

在本節中，您將執行 Terraform 指令碼，建立高可用性的地區性私人 GKE 叢集，以部署 Qdrant 資料庫。

您可以選擇使用標準或 Autopilot 叢集部署 Qdrant。各有優點，且採用不同的定價模式。

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}

系統會在執行階段替換下列變數：

  • GOOGLE_OAUTH_ACCESS_TOKEN：已由 gcloud auth print-access-token 指令擷取的存取權杖取代，用於驗證與各種 Google Cloud API 的互動
  • 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 qdrant-cluster --region us-central1"

Terraform 會建立下列資源：

  • Kubernetes 節點的自訂虛擬私有雲網路和私人子網路。
  • 透過網路位址轉譯 (NAT) 存取網際網路的 Cloud Router。
  • us-central1 地區的私人 GKE 叢集。
  • 具有叢集記錄和監控權限的 ServiceAccount。
  • Google Cloud Managed Service for Prometheus 設定，用於叢集監控和快訊。

標準

下圖顯示部署在三個不同區域的標準私人區域 GKE 叢集。

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}

系統會在執行階段替換下列變數：

  • GOOGLE_OAUTH_ACCESS_TOKEN 會替換為透過 gcloud auth print-access-token 指令擷取的存取權杖，用於驗證與各種 Google Cloud API 的互動。
  • 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 qdrant-cluster --region us-central1"

Terraform 會建立下列資源：

  • Kubernetes 節點的自訂虛擬私有雲網路和私人子網路。
  • 透過網路位址轉譯 (NAT) 存取網際網路的 Cloud Router。
  • us-central1 地區中已啟用自動調度的私人 GKE 叢集 (每個區域有一到兩個節點)。
  • 具有叢集記錄和監控權限的 ServiceAccount。
  • Google Cloud Managed Service for Prometheus 設定，用於叢集監控和快訊。

連線至叢集

設定 kubectl，以擷取憑證並與新的 GKE 叢集通訊：

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

將 Qdrant 資料庫部署至叢集

在本教學課程中，您將使用 Helm chart，在 GKE 叢集部署 Qdrant 資料庫 (分散式模式) 和 Stateful HA 運算子。

部署作業會建立具有下列設定的 GKE 叢集：

  • 三個 Qdrant 節點副本。
  • 容許度、節點親和性和拓撲分散限制已設定完成，可確保在 Kubernetes 節點之間適當分配。這會運用節點集區和不同的可用區。
  • 系統會為資料儲存空間佈建 SSD 磁碟類型的 RePD 磁碟區。
  • 狀態型高可用性運算子可用於管理容錯移轉程序，並確保高可用性。StatefulSet 是 Kubernetes 控制器，可為每個 Pod 維護永久專屬 ID。
  • 資料庫會建立包含 API 金鑰的 Kubernetes 密鑰，以進行驗證。

如要使用 Helm 圖表部署 Qdrant 資料庫，請按照下列步驟操作：

  1. 啟用 StatefulHA 外掛程式：

    Autopilot

    GKE 會在建立叢集時自動啟用 StatefulHA 外掛程式。

    標準

    執行下列指令：

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

    這項指令可能需要 15 分鐘才能完成，且叢集會顯示就緒狀態。

  2. 如要在 GKE 叢集上部署 Qdrant 資料庫，請先新增 Qdrant 資料庫 Helm Chart 存放區：

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

  3. 為資料庫建立命名空間 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 部署 Kubernetes Configmap，其中包含 metrics Sidecar 設定和 Qdrant 叢集：

    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 Sidecar 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.29
    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 的 Qdrant 資料庫：

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

    ilb.yaml 資訊清單說明 LoadBalancer 服務：

    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 資源：

    • 控制三個 Pod 副本的 Qdrant StatefulSet。
    • A PodDisruptionBudget，確保最多只有一個無法使用的副本。
    • qdrant-database Service，公開 Qdrant 連接埠，用於節點之間的傳入連線和複製作業。
    • qdrant-database-headless 服務，提供執行中 Qdrant Pod 的清單。
    • qdrant-database-apikey Secret，方便安全連線至資料庫。
    • 有狀態的 HA 運算子 Pod 和 HighlyAvailableApplication 資源，主動監控 Qdrant 應用程式。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

使用 Vertex AI Colab Enterprise 筆記本執行查詢

Qdrant 會將向量和酬載整理到集合中。向量嵌入技術可將字詞或實體表示為數值向量，同時維持語意關係。這對相似度搜尋來說非常重要，因為這類搜尋是根據意義而非完全比對來找出相似之處，因此搜尋和推薦系統等工作會更有效率且細緻。

本節說明如何將向量上傳至新的 Qdrant Collection，並執行搜尋查詢。

在本範例中，您會使用 CSV 檔案中的資料集，其中包含不同類型書籍的清單。您會建立 Colab Enterprise 筆記本，對 Qdrant 資料庫執行搜尋查詢。

如要進一步瞭解 Vertex AI Colab Enterprise，請參閱 Colab Enterprise 說明文件。

建立執行階段範本

如要建立 Colab Enterprise 執行階段範本，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的 Colab Enterprise「執行階段範本」頁面，並確認已選取專案：

    前往「執行階段範本」

  2. 按一下「新增範本」。「建立新的執行階段範本」頁面隨即顯示。

  3. 在「執行階段基本資訊」部分：

    • 在「Display name」(顯示名稱) 欄位中，輸入 qdrant-connect。
    • 在「Region」(區域) 下拉式清單中選取「us-central1」。與 GKE 叢集位於相同地區。

  4. 在「設定運算」部分：

    • 在「Machine type」(機器類型) 下拉式清單中，選取「e2-standard-2」。
    • 在「Disk size」(磁碟大小) 欄位中，輸入 30。

  5. 在「網路與安全性」部分中：

    • 在「Network」(網路) 下拉式選單中，選取 GKE 叢集所在的網路。
    • 在「Subnetwork」(子網路) 下拉式清單中，選取對應的子網路。
    • 取消勾選「啟用公開網際網路存取權」核取方塊。

  6. 按一下「建立」，完成建立執行階段範本。執行階段範本會顯示在「執行階段範本」分頁的清單中。

建立執行階段

如要建立 Colab Enterprise 執行階段，請按照下列步驟操作：

  1. 在剛建立的範本執行階段範本清單中，按一下「動作」欄中的 ，然後點選「建立執行階段」。系統隨即會顯示「Create Vertex AI Runtime」(建立 Vertex AI 執行階段) 窗格。

  2. 如要根據範本建立執行階段，請按一下「建立」。

  3. 在開啟的「執行階段」分頁中，等待狀態轉換為「正常」。

匯入筆記本

如要在 Colab Enterprise 中匯入筆記本，請按照下列步驟操作：

  1. 前往「我的筆記本」分頁，然後按一下「匯入」。「匯入筆記本」窗格隨即顯示。

  2. 在「匯入來源」中選取「網址」。

  3. 在「筆記本網址」下方，輸入下列連結：

    https://raw.githubusercontent.com/GoogleCloudPlatform/kubernetes-engine-samples/refs/heads/main/databases/qdrant/manifests/04-notebook/vector-database.ipynb

  4. 按一下「匯入」。

連線至執行階段並執行查詢

如要連線至執行階段並執行查詢，請按照下列步驟操作：

  1. 在筆記本中，按一下「連線」按鈕旁邊的 「其他連線選項」。 系統隨即會顯示「Connect to Vertex AI Runtime」(連線至 Vertex AI 執行階段) 窗格。

  2. 選取「連線到執行階段」，然後選取「連線至現有的執行階段」。

  3. 選取您啟動的執行階段，然後按一下「連線」。

  4. 如要執行筆記本儲存格，請按一下每個程式碼儲存格旁的「Run cell」(執行儲存格) 按鈕 。

筆記本包含程式碼儲存格和說明每個程式碼區塊的文字。執行程式碼儲存格會執行其指令並顯示輸出內容。您可以依序執行儲存格，也可以視需要執行個別儲存格。

查看叢集的 Prometheus 指標

GKE 叢集已設定 Google Cloud Managed Service for Prometheus，可收集 Prometheus 格式的指標。這項服務提供全代管的監控和快訊解決方案，可收集、儲存及分析叢集和應用程式的指標。

下圖說明 Prometheus 如何收集叢集的指標：

收集 Prometheus 指標

圖中的 GKE 私人叢集包含下列元件：

  • 在路徑 / 和通訊埠 80 上公開指標的 Qdrant Pod。這些指標是由名為 metrics 的補充資訊容器提供。
  • 以 Prometheus 為基礎的收集器，可處理來自 Qdrant Pod 的指標。
  • 將指標傳送至 Cloud Monitoring 的 PodMonitoring 資源。

如要匯出及查看指標，請按照下列步驟操作：

  1. 建立 PodMonitoring 資源，以透過 labelSelector 抓取指標：

    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. 建立 Cloud Monitoring 資訊主頁，並使用 dashboard.json 中定義的設定：

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

  3. 指令順利執行後，請前往 Cloud Monitoring 的「資訊主頁」：

    前往資訊主頁總覽

  4. 從資訊主頁清單中開啟 Qdrant Overview 資訊主頁。系統可能需要 1 到 2 分鐘才能收集及顯示指標。

    資訊主頁會顯示主要指標的計數：

    • 集合
    • 嵌入向量
    • 待處理的作業
    • 執行節點

備份叢集設定

GKE 備份功能可讓您排定定期備份整個 GKE 叢集設定，包括已部署的工作負載及其資料。

在本教學課程中，您將為 GKE 叢集設定備份計畫，每天凌晨 3 點備份所有工作負載，包括祕密和磁碟區。為確保儲存空間管理效率，系統會自動刪除超過三天的備份。

如要設定備份方案，請按照下列步驟操作：

  1. 為叢集啟用 GKE 備份功能：

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

  2. 為叢集內的所有命名空間建立備份方案，並設定每日排程：

    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. 您可以在 GKE 備份控制台看到新建立的備份方案 qdrant-cluster-backup。

    前往 GKE 備份

如要還原已儲存的備份設定，請參閱「還原備份」。