本指南介绍如何在 Google Kubernetes Engine (GKE) 上部署 Qdrant 向量数据库集群。
向量数据库是专门用于管理和搜索大型高维向量集合的数据存储区。这些矢量表示文本、图片、音频、视频等数据或可进行数字编码的任何数据。与依赖于完全匹配的传统数据库不同,向量数据库专注于在大量数据集中查找相似项或识别模式。这些特性使得 Qdrant 非常适合各种应用,包括神经网络或基于语义的匹配、分面搜索等。Qdrant 不仅可用作向量数据库,还可用作向量相似度搜索引擎。
本教程适用于想要在 GKE 上部署 Qdrant 数据库集群的云平台管理员和架构师、机器学习工程师以及 MLOps (DevOps) 专业人员。
优势
Qdrant 具有以下优势:
- 包含适用于各种编程语言的大量库,并提供可与其他服务集成的开放式 API。
- 可横向扩缩,支持分片和复制,可简化扩缩和高可用性。
- 支持容器和 Kubernetes 模式,可让您在现代化云原生环境中轻松开展部署和管理工作。
- 提供灵活的载荷模式,可通过高级过滤功能精确定制搜索条件。
- 不同的量化选项和其他优化,以降低基础设施费用并提高性能。
目标
在本教程中,您将学习如何:
- 为 Qdrant 规划和部署 GKE 基础设施。
- 部署 StatefulHA 运算符以确保 Qdrant 高可用性。
- 部署并配置 Qdrant 集群。
- 上传演示数据集并运行简单的搜索查询。
- 收集指标并运行信息中心。
部署架构
此架构可跨多个可用区为 Qdrant 设置一个具有容错能力且可扩缩的 GKE 集群,通过滚动更新确保正常运行时间和可用性,并最大限度地减少中断。它包括使用 StatefulHA Operator 进行高效的故障切换管理。如需了解详情,请参阅区域级集群。
架构图
下图显示了在 GKE 集群中的多个节点和可用区上运行的 Qdrant 集群:
在此架构中,Qdrant StatefulSet
部署在三个不同可用区的三个节点上。
- 您可以在 Helm 图表值文件中配置必要的 Pod 亲和性规则和拓扑分布限制,从而控制 GKE 在各个节点之间分发 Pod 的方式。
- 如果一个可用区发生故障,GKE 会根据推荐的配置在新节点上重新调度 Pod。
为了实现数据持久性,本教程中的架构具有以下特征:
- 使用区域性 SSD 磁盘(自定义
regional-pd
StorageClass)来保留数据。我们建议将区域 SSD 磁盘用于数据库,因为其延迟时间短、IOPS 高。 - 所有磁盘数据都会在区域内的主要可用区和次要可用区之间进行复制,以更好地应对可能发生的可用区故障。
费用
在本文档中,您将使用 Google Cloud 的以下收费组件:
您可使用价格计算器根据您的预计使用情况来估算费用。
完成本文档中描述的任务后,您可以通过删除所创建的资源来避免继续计费。如需了解详情,请参阅清理。
准备工作
在本教程中,您将使用 Cloud Shell 运行命令。Cloud Shell 是一种 shell 环境,用于管理托管在 Google Cloud 上的资源。它预装了 Google Cloud CLI、kubectl、Helm 和 Terraform 命令行工具。如果您不使用 Cloud Shell,则必须安装 Google Cloud CLI。
- 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.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Create or select a Google Cloud 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.
-
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Resource Manager, Compute Engine, GKE, IAM Service Account Credentials, and Backup for GKE APIs:
gcloud services enable cloudresourcemanager.googleapis.com
compute.googleapis.com container.googleapis.com iamcredentials.googleapis.com gkebackup.googleapis.com - Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Create or select a Google Cloud 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.
-
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Resource Manager, Compute Engine, GKE, IAM Service Account Credentials, and Backup for GKE APIs:
gcloud services enable cloudresourcemanager.googleapis.com
compute.googleapis.com container.googleapis.com iamcredentials.googleapis.com gkebackup.googleapis.com -
Grant roles to your user account. Run the following command once for each of the following IAM roles:
roles/storage.objectViewer, roles/container.admin, roles/iam.serviceAccountAdmin, roles/compute.admin, roles/gkebackup.admin, roles/monitoring.viewer
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
- Replace
PROJECT_ID
with your project ID. -
Replace
USER_IDENTIFIER
with the identifier for your user account. For example,user:myemail@example.com
. - Replace
ROLE
with each individual role.
- Replace
设置您的环境
如需使用 Cloud Shell 设置您的环境,请按照以下步骤操作:
为您的项目、区域和 Kubernetes 集群资源前缀设置环境变量:
在本教程中,请使用
us-central1
区域创建部署资源。export PROJECT_ID=PROJECT_ID export KUBERNETES_CLUSTER_PREFIX=qdrant export REGION=us-central1
- 将
PROJECT_ID
替换为您的 Google Cloud 项目 ID。
- 将
检查 Helm 的版本:
helm version
更新版本(如果低于 3.13):
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
从 GitHub 克隆示例代码库:
git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples
转到
qdrant
目录以开始创建部署资源:cd kubernetes-engine-samples/databases/qdrant
创建集群基础架构
本部分涉及运行 Terraform 脚本来创建可用性高的专用区域级 GKE 集群,以部署 Qdrant 数据库。
您可以选择使用标准集群或 Autopilot 集群部署 Qdrant。每种类型都有自己的优势和不同的价格模式。
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}
以下变量会在运行时被替换:
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 节点的自定义 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}
以下变量会在运行时被替换:
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 qdrant-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}
将 Qdrant 数据库部署到您的集群
在本教程中,您会使用 Helm 图表将 Qdrant 数据库(分布式模式)和有状态 HA 运算符部署到 GKE 集群。
部署会创建具有以下配置的 GKE 集群:
- Qdrant 节点的三个副本。
- 配置了容忍、节点亲和性和拓扑分布限制,以确保在各个 Kubernetes 节点之间正确分发资源。这会利用节点池和不同的可用区。
- 预配了具有 SSD 磁盘类型的 RePD 卷来存储数据。
- 有状态 HA 运算符用于管理故障切换过程并确保高可用性。
- 数据库会创建一个包含 API 密钥的 Kubernetes Secret,用于进行身份验证。
如需使用 Helm 图表部署 Qdrant 数据库,请按照以下步骤操作:
启用 StatefulHA 插件:
Autopilot
GKE 会在创建集群时自动启用
StatefulHA
插件。标准
运行以下命令:
gcloud container clusters update ${KUBERNETES_CLUSTER_PREFIX}-cluster \ --project=${PROJECT_ID} \ --region=${REGION} \ --update-addons=StatefulHA=ENABLED
完成此命令并使集群显示就绪状态可能需要 15 分钟。
先添加 Qdrant 数据库 Helm 图表代码库,然后才能将其部署到您的 GKE 集群:
helm repo add qdrant https://qdrant.github.io/qdrant-helm
为数据库创建命名空间
qdrant
:kubectl create ns qdrant
应用此清单以创建区域级永久性 SSD 磁盘
StorageClass
:kubectl apply -n qdrant -f manifests/01-regional-pd/regional-pd.yaml
regional-pd.yaml
清单描述了永久性 SSD 磁盘StorageClass
:使用 Helm 部署具有
metrics
Sidecar 配置和 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
sidecarConfigMap
:values.yaml
清单描述了 Qdrant 集群配置:此配置会启用集群模式,允许您设置高可用性和分布式 Qdrant 集群。
检查部署状态:
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
等待 GKE 启动所需工作负载:
kubectl wait pods -l app.kubernetes.io/instance=qdrant-database --for condition=Ready --timeout=300s -n qdrant
此命令可能需要几分钟时间才能成功完成。
GKE 启动工作负载后,验证 GKE 是否已创建 Qdrant 工作负载:
kubectl get pod,svc,statefulset,pdb,secret -n qdrant
启动 Qdrant 的
HighAvailabilityApplication
(HAA) 资源:kubectl apply -n qdrant -f manifests/01-regional-pd/ha-app.yaml
ha-app.yaml
清单描述了HighAvailabilityApplication
资源:系统会为 Qdrant 集群创建以下 GKE 资源:
- 控制三个 Pod 副本的 Qdrant
StatefulSet
。 A PodDisruptionBudget
,确保最多只有一个不可用的副本。qdrant-database
Service,公开节点之间的入站连接和复制的 Qdrant 端口。qdrant-database-headless
Service,提供正在运行的 Qdrant Pod 的列表。qdrant-database-apikey
Secret,帮助实现安全的数据库连接。- 有状态 HA 运算符 Pod 和
HighlyAvailableApplication
资源,主动监控 Qdrant 应用。HighlyAvailableApplication
资源定义了要应用于 Qdrant 的故障切换规则。
- 控制三个 Pod 副本的 Qdrant
如需检查故障切换规则是否已应用,请描述资源并确认
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 笔记本上传数据集并运行搜索查询
Qdrant 以集合的形式组织向量和载荷。向量嵌入是一种将字词或实体表示为数值向量并同时保留其语义关系的方法。该方法对于相似性搜索非常重要,因为它可以根据含义而非完全匹配项来查找相似项,这使得搜索和推荐系统等任务更有效、更精细。
本部分介绍了如何将矢量上传到新的 Qdrant集合,以及如何运行简单的搜索查询。
在此示例中,您将使用包含不同类型图书列表的 CSV 文件中的数据集。Qdrant 会充当搜索引擎,您创建的 Jupyter 笔记本 Pod 会充当查询 Qdrant 数据库的客户端。
创建
books-dataset
和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 包含一个csv
文件,其中包含用于 Qdrant 集合的图书数据notebook
ConfigMap 包含用于从books-dataset
创建 Qdrant 集合的 Jupyter 笔记本。
- 之前创建的名为
等待 GKE 启动 Jupyter Pod:
kubectl wait pods -l app=jupyter-notebook --for condition=Ready --timeout=300s -n qdrant
打开此网址,然后点击 vector-database.ipynb 文件。按“运行”->“Run all cells”。Jupyter 会执行所有代码并执行搜索查询。
此查询对 Qdrant 中的
my_books
集合执行语义搜索,检索最多两个具有与查询文本相关最高匹配得分的结果。输出的每个结果都由一行短划线进行分隔,格式如下:
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
的边车容器提供。 - 基于 Prometheus 的收集器,用于处理来自 Qdrant Pod 的指标。
- 将指标发送到 Cloud Monitoring 的 PodMonitoring 资源。
如需导出和查看指标,请按照以下步骤操作:
创建
PodMonitoring
资源,以按labelSelector
爬取指标:kubectl apply -n qdrant -f manifests/03-prometheus-metrics/pod-monitoring.yaml
pod-monitoring.yaml
清单描述了PodMonitoring
资源:使用
dashboard.json
中定义的配置创建 Cloud Monitoring 信息中心:gcloud --project "${PROJECT_ID}" monitoring dashboards create --config-from-file monitoring/dashboard.json
命令成功运行后,前往 Cloud Monitoring 信息中心:
从信息中心列表中,打开
Qdrant Overview
信息中心。收集和显示指标可能需要 1-2 分钟时间。信息中心会显示关键指标的计数:
- 集合
- 嵌入式向量
- 待处理的操作
- 正在运行的节点
备份集群配置
借助 Backup for GKE 功能,您可以定期备份整个 GKE 集群的配置,包括已部署的工作负载及其数据。
在本教程中,您将为 GKE 集群配置备份方案,以在每天凌晨 3 点对所有工作负载(包括 Secret 和卷)执行备份。为确保高效存储管理,三天前的备份会被自动删除。
如需配置备份方案,请按照以下步骤操作:
为集群启用 Backup for GKE 功能:
gcloud container clusters update ${KUBERNETES_CLUSTER_PREFIX}-cluster \ --project=${PROJECT_ID} \ --region=${REGION} \ --update-addons=BackupRestore=ENABLED
为集群中的所有命名空间创建具有每日时间表的备份方案:
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].
您可以看到 Backup for GKE 控制台中列出新创建的备份方案
qdrant-cluster-backup
。
如果您要恢复已保存的备份配置,请参阅恢复备份。
清理
为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用,请删除包含这些资源的项目,或者保留项目但删除各个资源。
删除项目
为了避免产生费用,最简单的方法是删除您为本教程创建的项目。
Delete a Google Cloud project:
gcloud projects delete PROJECT_ID
如果您删除了项目,则表示您的清理已完成。如果您没有删除项目,请继续删除各个资源。
删除各个资源
设置环境变量。
export PROJECT_ID=${PROJECT_ID} export KUBERNETES_CLUSTER_PREFIX=qdrant export REGION=us-central1
运行
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
。查找所有未挂接的磁盘:
export disk_list=$(gcloud compute disks list --filter="-users:* AND labels.name=${KUBERNETES_CLUSTER_PREFIX}-cluster" --format "value[separator=|](name,region)")
删除磁盘:
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
删除 GitHub 代码库:
rm -r ~/kubernetes-engine-samples/
后续步骤
- 探索 GKE 市场中的 Qdrant。
- 探索 Qdrant 开源软件。
- 试用 Qdrant 运算符,该运算符提供了 API 密钥管理功能、TLS 支持(带证书管理功能)和备份安排功能。
- 了解在 GKE 上部署数据库的最佳实践。
- 探索使用 GKE 运行数据密集型工作负载的解决方案。