在 GKE 上部署 Weaviate 向量数据库

Autopilot Standard

---

本教程介绍如何在 Google Kubernetes Engine (GKE) 上部署 Weaviate 矢量数据库集群。

Weaviate 是一个开源矢量数据库，具有低延迟性能，并对文本和图片等不同媒体类型提供基本支持。它支持语义搜索、问题解答和分类。Weaviate 完全基于 Go 构建，它既存储对象又存储向量，允许使用向量搜索、关键字搜索以及两者的组合作为混合搜索。从基础架构角度来看，Weaviate 是一个云原生且具有容错功能的数据库。容错由无主节点架构提供，其中数据库集群的每个节点都可以处理读写请求，从而排除单点故障。

本教程适用于想要在 GKE 上部署向量数据库集群的云平台管理员和架构师、机器学习工程师以及 MLOps (DevOps) 专业人员。

优势

Weaviate 具有以下优势：

• 包含适用于各种编程语言的库，并提供可与其他服务集成的开放式 API。
• 横向扩缩。
• 平衡成本效益和查询速度，尤其是在处理大型数据集时。您可以选择在内存中存储的数据量与在磁盘中存储的数据量。

目标

在本教程中，您将学习如何：

• 为 Weaviate 规划和部署 GKE 基础设施。
• 在 GKE 集群中部署和配置 Weaviate 数据库。
• 运行笔记本以在数据库中生成和存储示例向量嵌入，并执行基于向量的搜索查询。

费用

在本文档中，您将使用 Google Cloud 的以下收费组件：

• GKE
• Google Cloud Managed Service for Prometheus

您可使用价格计算器根据您的预计使用情况来估算费用。 Google Cloud 新用户可能有资格申请免费试用。

完成本文档中描述的任务后，您可以通过删除所创建的资源来避免继续计费。如需了解详情，请参阅清理。

准备工作

在本教程中，您将使用 Cloud Shell 运行命令。Cloud Shell 是一种 shell 环境，用于管理托管在 Google Cloud 上的资源。它预装了 Google Cloud CLI、kubectl、Helm 和 Terraform 命令行工具。如果您不使用 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

   Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

4. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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

   Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

9. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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_IDENTIFIER" --role=ROLE

    • Replace PROJECT_ID with your project ID.

    • Replace USER_IDENTIFIER with the identifier for your user account. For example, user:[e-mail].

    • 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 区域来创建部署资源。

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 集群。

若要部署集群基础设施，请在 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 节点的自定义 VPC 网络和专用子网。
• 用于通过网络地址转换 (NAT) 访问互联网的 Cloud Router 路由器。
• 专用 GKE 集群（在 us-central1 区域中）。
• 具有集群的日志记录和监控权限的 ServiceAccount。
• 用于集群监控和提醒的 Google Cloud Managed Service for Prometheus 配置。

标准

下图展示了部署在三个不同可用区中的专用区域级 Standard GKE 集群。

若要部署集群基础设施，请在 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 节点的自定义 VPC 网络和专用子网。
• 用于通过网络地址转换 (NAT) 访问互联网的 Cloud Router 路由器。
• 位于 us-central1 区域并且启用了自动扩缩功能的专用 GKE 集群（每个可用区一个到两个节点）。
• 具有集群的日志记录和监控权限的 ServiceAccount。
• 用于集群监控和提醒的 Google Cloud Managed Service for Prometheus 配置。

连接到集群

配置 kubectl 以提取凭据并与新的 GKE 集群通信：

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

将 Weaviate 数据库部署到您的集群

如需使用 Helm 图表将 Weaviate 数据库部署到 GKE 集群，请按以下步骤操作：

1. 先添加 Weaviate 数据库 Helm 图表代码库，然后才能将其部署到您的 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：

   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:
         - [e-mail]
   modules:
     text2vec-palm:
       enabled: true
   env:
     AUTHENTICATION_APIKEY_ENABLED: 'true'
     AUTHENTICATION_APIKEY_USERS: '[e-mail]'
     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 数据库。您可以使用专用运行时模板部署到 weaviate-vpc，以便笔记本可以与 GKE 集群中的资源进行通信。

创建运行时模板

如需创建运行时模板，请执行以下操作：

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. 前往笔记本标签页，然后点击从网址导入笔记本。

2. 在导入来源中，选择网址。

3. 在笔记本网址下方，粘贴以下链接：raw.githubusercontent.com/epam/kubernetes-engine-samples/Weaviate/databases/weaviate/manifests/02-notebook/vector-database.ipynb

4. 点击导入。

连接到运行时并运行查询

如需连接到运行时并运行查询，请执行以下操作：

1. 在笔记本中，点击连接按钮旁边的 其他连接选项。此时会显示连接到 Vertex AI Runtime 窗格。

2. 选择连接到运行时，然后选择连接到现有运行时。

3. 选择您启动的运行时，然后点击连接。

4. 点击每个代码单元左侧的 运行单元按钮，以运行笔记本单元。

该笔记本包含代码单元和用于描述每个代码块的文本。运行代码单元会执行其命令并显示输出。您可以按顺序运行单元，也可以根据需要运行单个单元。

如需详细了解 Vertex AI Colab Enterprise，请参阅 Colab Enterprise 文档。

查看集群的 Prometheus 指标

GKE 集群配置了 Google Cloud Managed Service for 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. 如需使用 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 账号产生费用，请删除包含这些资源的项目，或者保留项目但删除各个资源。

删除项目

为了避免产生费用，最简单的方法是删除您为本教程创建的项目。

注意：删除项目会产生以下影响：

• 项目中的所有内容都会被删除。如果您将现有项目用于本文档中的任务，则删除该项目后，还将删除您已在该项目中完成的任何其他工作。
• 自定义项目 ID 丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。要保留使用该项目 ID 的网址（例如 appspot.com 网址），请删除项目内的所选资源，而不是删除整个项目。

如果您打算探索多个架构、教程或快速入门，则重复使用项目可以帮助您避免超出项目配额限制。

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}
   

   将 FOLDER 替换为 gke-autopilot 或 gke-standard，具体取决于您创建的 GKE 集群的类型。

   出现提示时，请输入 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/
   

后续步骤

• 探索 GKE 市场中的 Weaviate。
• 了解在 GKE 上部署数据库的最佳实践。
• 探索使用 GKE 运行数据密集型工作负载的解决方案。