在 GKE 上部署 Weaviate 向量数据库

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

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

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

优势

Weaviate 具有以下优势：

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

目标

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

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

费用

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

如需根据您的预计使用量来估算费用，请使用价格计算器。

新 Google Cloud 用户可能有资格申请免费试用。

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

准备工作

在本教程中，您将使用 Cloud Shell 运行命令。Cloud Shell 是一种 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 角色，您可以选择已获授角色的任何项目。
    • 创建项目：如需创建项目，您需要拥有 Project Creator 角色 (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，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则，您可以通过 Service Usage Admin 角色 (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 角色，您可以选择已获授角色的任何项目。
    • 创建项目：如需创建项目，您需要拥有 Project Creator 角色 (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，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则，您可以通过 Service Usage Admin 角色 (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：您的用户 账号的标识符。例如，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 节点的自定义 VPC 网络和专用子网。
  • 用于通过网络地址转换 (NAT) 访问互联网的 Cloud Router 路由器。
  • 专用 GKE 集群（在 us-central1 区域中）。
  • 具有集群的日志记录和监控权限的 ServiceAccount。
  • 用于集群监控和提醒的 Google Cloud Managed Service for Prometheus 配置。

标准

下图展示了部署在三个不同可用区中的专用区域级 Standard 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 节点的自定义 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 --location ${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。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 运行时模板页面，并确保您的项目已被选中：

    进入运行时模板

  2. 点击 新建模板。系统会显示创建新的运行时模板页面。

  3. 在运行时基本信息部分中：

    • 在显示名称字段中，输入 weaviate-connect。
    • 在区域下拉列表中，选择 us-central1。该区域与 GKE 集群所在的区域相同。

  4. 在配置计算部分中：

    • 在机器类型下拉列表中，选择 e2-standard-2。
    • 在磁盘大小字段中，输入 30。

  5. 在网络和安全部分中：

    • 在网络下拉列表中，选择 GKE 集群所在的网络。
    • 在子网下拉列表中，选择相应的子网。
    • 清除启用公共互联网访问权限复选框。

  6. 点击创建以完成运行时模板的创建过程。您的运行时模板会显示在运行时模板标签页上的列表中。

创建运行时

如需创建 Colab Enterprise 运行时，请执行以下操作：

  1. 在运行时模板列表中，对于您刚刚创建的模板，点击操作列中的 ，然后点击创建运行时。此时会显示创建 Vertex AI 运行时窗格。

  2. 如需根据模板创建运行时，请点击创建。

  3. 在打开的运行时标签页中，等待状态转换为健康。

导入笔记本

如需在 Colab Enterprise 中导入笔记本，请执行以下操作：

  1. 前往我的笔记本标签页，然后点击导入。系统会显示导入笔记本窗格。

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

  3. 在笔记本网址下方，输入以下链接：

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

  4. 点击导入。

连接到运行时并运行查询

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

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

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

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

  4. 如需运行笔记本单元，请点击每个代码单元旁边的 运行单元按钮。

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

查看集群的 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. 如需使用 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 账号产生费用，请删除包含这些资源的项目，或者保留项目但删除各个资源。

删除项目

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

删除 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}

    将 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/

后续步骤