在 GKE 上部署 Weaviate 向量資料庫

本教學課程說明如何在 Google Kubernetes Engine (GKE) 部署 Weaviate 向量資料庫叢集。

Weaviate 是開放原始碼的向量資料庫，具有低延遲效能，並基本支援文字和圖片等不同媒體類型。這項功能支援語意搜尋、問答和分類。Weaviate 完全以 Go 語言建構，可儲存物件和向量，因此能使用向量搜尋、關鍵字搜尋，以及兩者結合的混合型搜尋。從基礎架構的角度來看，Weaviate 是雲端原生且容錯的資料庫。無領導者架構可提供容錯能力，資料庫叢集的每個節點都能處理讀取和寫入要求，因此不會出現單點故障。

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

優點

Weaviate 具有下列優點：

  • 適用於各種程式設計語言的程式庫，以及可與其他服務整合的開放式 API。
  • 水平資源調度。
  • 在成本效益和查詢速度之間取得平衡，尤其是在處理大型資料集時。您可以選擇要將多少資料儲存在記憶體中，而不是磁碟上。

目標

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

  • 規劃及部署 Weaviate 的 GKE 基礎架構。
  • 在 GKE 叢集中部署及設定 Weaviate 資料庫。
  • 執行筆記本，在資料庫中生成及儲存範例向量嵌入，並執行以向量為準的搜尋查詢。

費用

在本文件中，您將使用下列 Google Cloud計費元件：

您可以使用 Pricing Calculator，根據預測用量估算費用。

初次使用 Google Cloud 的使用者可能符合免費試用期資格。

完成本文所述工作後，您可以刪除建立的資源，避免繼續計費，詳情請參閱「清除所用資源」。

事前準備

在本教學課程中，您會使用 Cloud Shell 執行指令。Cloud Shell 是一種殼層環境，可用來管理託管於 Google Cloud的資源。這個環境已預先安裝 Google Cloud CLI、kubectl、Helm 和 Terraform 指令列工具。如果您未使用 Cloud Shell，請務必安裝 Google Cloud CLI。

  1. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自體驗產品的實際應用成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

  2. 安裝 Google Cloud CLI。

  3. 若您採用的是外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

  4. 執行下列指令，初始化 gcloud CLI：

    gcloud init

  5. 建立或選取 Google Cloud 專案。

    選取或建立專案所需的角色

    • 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您在專案中獲派角色，即可選取該專案。
    • 建立專案：如要建立專案，您需要專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

    • 建立 Google Cloud 專案：

      gcloud projects create PROJECT_ID

      將 PROJECT_ID 替換為要建立的專案名稱。 Google Cloud

    • 選取您建立的 Google Cloud 專案：

      gcloud config set project PROJECT_ID

      將 PROJECT_ID 替換為 Google Cloud 專案名稱。

  6. 確認 Google Cloud 專案已啟用計費功能。

  7. 如果尚未啟用 Cloud Resource Manager、Compute Engine、GKE 和 IAM Service Account Credentials API，請啟用這些 API：

    啟用 API 時所需的角色

    如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過服務使用情形管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

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

  8. 安裝 Google Cloud CLI。

  9. 若您採用的是外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

  10. 執行下列指令，初始化 gcloud CLI：

    gcloud init

  11. 建立或選取 Google Cloud 專案。

    選取或建立專案所需的角色

    • 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您在專案中獲派角色，即可選取該專案。
    • 建立專案：如要建立專案，您需要專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

    • 建立 Google Cloud 專案：

      gcloud projects create PROJECT_ID

      將 PROJECT_ID 替換為要建立的專案名稱。 Google Cloud

    • 選取您建立的 Google Cloud 專案：

      gcloud config set project PROJECT_ID

      將 PROJECT_ID 替換為 Google Cloud 專案名稱。

  12. 確認 Google Cloud 專案已啟用計費功能。

  13. 如果尚未啟用 Cloud Resource Manager、Compute Engine、GKE 和 IAM Service Account Credentials API，請啟用這些 API：

    啟用 API 時所需的角色

    如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過服務使用情形管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

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

  14. 將角色授予使用者帳戶。針對下列各個 IAM 角色執行下列指令一次：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

    更改下列內容：

    • PROJECT_ID：專案 ID。
    • USER_IDENTIFIER：使用者帳戶的 ID。 例如：myemail@example.com。
    • ROLE：授予使用者帳戶的 IAM 角色。

設定環境

如要使用 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 區域建立部署資源。

  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 資料庫。

您可以選擇使用Standard 或 Autopilot 叢集部署 Weaviate。兩者各有優勢，定價模式也不同。

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 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 weaviate-cluster --region us-central1"

Terraform 會建立下列資源：

  • Kubernetes 節點的自訂虛擬私有雲網路和私人子網路。
  • Cloud Router：透過網路位址轉譯 (NAT) 存取網際網路。
  • 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}

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

  • GOOGLE_OAUTH_ACCESS_TOKEN 會使用 gcloud auth print-access-token 指令擷取存取權杖，驗證與各種 Google Cloud API 的互動。
  • PROJECT_ID、REGION 和 KUBERNETES_CLUSTER_PREFIX 是在「設定環境」一節中定義的環境變數，並指派給您要建立的標準叢集相關新變數。

系統顯示提示訊息時，請輸入 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 節點的自訂虛擬私有雲網路和私人子網路。
  • 透過網路位址轉譯 (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}

將 Weaviate 資料庫部署至叢集

如要使用 Helm 資訊套件將 Weaviate 資料庫部署至 GKE 叢集，請按照下列步驟操作：

  1. 新增 Weaviate 資料庫 Helm Chart 存放區，才能在 GKE 叢集上部署：

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

  2. 為資料庫建立 weaviate 命名空間：

    kubectl create ns weaviate

  3. 建立 Secret 來儲存 API 金鑰：

    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. 套用資訊清單來部署 Weaviate 叢集：

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

    weaviate_cluster.yaml 資訊清單會說明 Deployment。 Deployment 是 Kubernetes API 物件，可讓您執行多個 Pod 副本，並分散在叢集中的節點：

    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. 查看 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

  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 資料庫。 您可以使用專屬執行階段範本部署至 weaviate-vpc，讓筆記本與 GKE 叢集中的資源通訊。

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

建立執行階段範本

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

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

    前往「Runtime Templates」(執行階段範本) 頁面

  2. 按一下「新增範本」。系統隨即會顯示「Create new runtime template」(建立新的執行階段範本) 頁面。

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

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

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

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

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

    • 在「網路」下拉式選單中，選取 GKE 叢集所在的網路。
    • 在「Subnetwork」(子網路) 下拉式選單中，選取對應的子網路。
    • 取消勾選「啟用公開網路連線能力」核取方塊。

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

建立執行階段

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

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

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

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

匯入筆記本

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

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

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

  3. 在 Notebook URLs 下方，輸入下列連結：

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

  4. 按一下「匯入」。

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

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

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

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

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

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

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

查看叢集的 Prometheus 指標

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

下圖顯示 Prometheus 如何收集叢集的指標：

收集 Prometheus 指標

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

  • 在路徑 /metrics 和通訊埠 2112 公開指標的 Weaviate Pod。
  • 以 Prometheus 為基礎的收集器，可處理 Weaviate Pod 的指標。
  • 將指標傳送至 Cloud Monitoring 的 PodMonitoring 資源。

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

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

    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. 如要匯入自訂 Cloud Monitoring 資訊主頁，並使用 dashboard.json 中定義的設定，請按照下列步驟操作：

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

  3. 指令執行成功後，請前往 Cloud Monitoring 的「Dashboards」(資訊主頁)：

    前往資訊主頁總覽

  4. 從資訊主頁清單中開啟 Weaviate Overview 資訊主頁。系統可能需要一些時間才能收集及顯示指標。資訊主頁會顯示 shard 數量、向量和作業延遲時間

清除所用資源

為避免因為本教學課程所用資源，導致系統向 Google Cloud 收取費用，請刪除含有相關資源的專案，或者保留專案但刪除個別資源。

刪除專案

如要避免產生費用，最簡單的方法就是刪除您為了本教學課程建立的專案。

刪除 Google Cloud 專案：

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 叢集類型，將 FOLDER 替換為 gke-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/

後續步驟