Déployer une base de données vectorielle Weaviate sur GKE

Ce tutoriel vous explique comment déployer un cluster de base de données vectorielle Weaviate sur Google Kubernetes Engine (GKE).

Weaviate est une base de données vectorielle Open Source offrant des performances à faible latence et une compatibilité de base avec différents types de médias, tels que le texte et les images. Il est compatible avec la recherche sémantique, les systèmes de questions-réponses et la classification. Weaviate est entièrement basé sur Go et stocke à la fois des objets et des vecteurs, ce qui permet d'utiliser la recherche vectorielle, la recherche par mots clés et une combinaison des deux en tant que recherche hybride. Du point de vue de l'infrastructure, Weaviate est une base de données cloud native et tolérante aux pannes. La tolérance aux pannes est assurée par une architecture sans leader dans laquelle chaque nœud du cluster de base de données peut diffuser des requêtes de lecture et d'écriture, ce qui exclut un point de défaillance unique.

Ce tutoriel est destiné aux administrateurs et architectes de plate-forme cloud, aux ingénieurs en ML et aux professionnels du MLOps (DevOps) qui souhaitent déployer des clusters de base de données vectorielles sur GKE.

Avantages

Weaviate offre les avantages suivants :

  • Bibliothèques pour divers langages de programmation et API pouvant être intégrée à d'autres services.
  • Scaling horizontal
  • Équilibre entre l'efficacité et la vitesse des requêtes, en particulier lorsque vous travaillez avec de grands ensembles de données. Vous pouvez choisir la quantité de données stockées en mémoire plutôt que sur disque.

Objectifs

Dans ce tutoriel, vous allez apprendre à effectuer les opérations suivantes :

  • Planifier et déployer l'infrastructure GKE pour Weaviate.
  • Déployer et configurer la base de données Weaviate dans un cluster GKE.
  • Exécutez un notebook pour générer et stocker des exemples d'embeddings vectoriels dans votre base de données, et effectuer des requêtes de recherche vectorielle.

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût. Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Une fois que vous avez terminé les tâches décrites dans ce document, vous pouvez éviter de continuer à payer des frais en supprimant les ressources que vous avez créées. Pour en savoir plus, consultez la section Effectuer un nettoyage.

Avant de commencer

Dans ce tutoriel, vous utilisez Cloud Shell pour exécuter des commandes. Cloud Shell est un environnement shell permettant de gérer les ressources hébergées sur Google Cloud. Il est doté des outils de ligne de commande préinstallés suivants : Google Cloud CLI, kubectl, Helm et Terraform. Si vous n'utilisez pas Cloud Shell, vous devez installer 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

  4. 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.

  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

  9. 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.

  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: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.

Configurer votre environnement

Pour configurer votre environnement avec Cloud Shell, procédez comme suit :

  1. Définissez des variables d'environnement pour votre projet, une région et un préfixe de ressource de cluster Kubernetes :

    export PROJECT_ID=PROJECT_ID
export KUBERNETES_CLUSTER_PREFIX=weaviate
export REGION=us-central1

    Remplacez PROJECT_ID par l'ID de votre projet Google Cloud.

    Ce tutoriel utilise la région us-central1 pour créer vos ressources de déploiement.

  2. Vérifiez la version de Helm :

    helm version

    Mettez à jour la version si elle est antérieure à la version 3.13 :

    curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

  3. Clonez l'exemple de dépôt de code depuis GitHub :

    git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples

  4. Accédez au répertoire weaviate :

    cd kubernetes-engine-samples/databases/weaviate

Créer l'infrastructure de votre cluster

Dans cette section, vous allez exécuter un script Terraform pour créer un cluster GKE régional, privé et à disponibilité élevée pour déployer votre base de données Weaviate.

Vous pouvez choisir de déployer Weaviate à l'aide d'un cluster Standard ou Autopilot. Chacun présente ses propres avantages et différents modèles de tarification.

Autopilot

Le schéma suivant présente un cluster GKE Autopilot déployé dans le projet.

Cluster GKE Autopilot

Pour déployer l'infrastructure du cluster, exécutez les commandes suivantes dans 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 remplace les variables suivantes lors de l'exécution :

  • GOOGLE_OAUTH_ACCESS_TOKEN utilise la commande gcloud auth print-access-token pour récupérer un jeton d'accès qui authentifie les interactions avec diverses API Google Cloud.
  • PROJECT_ID, REGION et KUBERNETES_CLUSTER_PREFIX sont les variables d'environnement définies dans la section Configurer votre environnement et attribuées aux nouvelles variables pertinentes pour le cluster Autopilot que vous êtes en train de créer.

Lorsque vous y êtes invité, saisissez yes.

Le résultat ressemble à ce qui suit :

...
Apply complete! Resources: 9 added, 0 changed, 0 destroyed.

Outputs:

kubectl_connection_command = "gcloud container clusters get-credentials weaviate-cluster --region us-central1"

Terraform crée les ressources suivantes :

  • Un réseau VPC personnalisé et un sous-réseau privé pour les nœuds Kubernetes
  • Un routeur cloud pour accéder à Internet via la traduction d'adresse réseau (NAT)
  • Un cluster GKE privé dans la région us-central1.
  • Un ServiceAccount avec les autorisations de journalisation et de surveillance pour le cluster
  • Configuration de Google Cloud Managed Service pour Prometheus pour la surveillance et les alertes relatives au cluster.

Standard

Le schéma suivant présente un cluster GKE régional privé Standard déployé dans trois zones différentes.

Cluster GKE standard

Pour déployer l'infrastructure du cluster, exécutez les commandes suivantes dans 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 remplace les variables suivantes lors de l'exécution :

  • GOOGLE_OAUTH_ACCESS_TOKEN utilise la commande gcloud auth print-access-token pour récupérer un jeton d'accès qui authentifie les interactions avec diverses API Google Cloud.
  • PROJECT_ID, REGION et KUBERNETES_CLUSTER_PREFIX sont les variables d'environnement définies dans la section Configurer votre environnement et attribuées aux nouvelles variables pertinentes pour le cluster Standard que vous êtes en train de créer.

Lorsque vous y êtes invité, saisissez yes. L'exécution de ces commandes et le passage du cluster à l'état prêt peuvent prendre plusieurs minutes.

Le résultat ressemble à ce qui suit :

...
Apply complete! Resources: 10 added, 0 changed, 0 destroyed.

Outputs:

kubectl_connection_command = "gcloud container clusters get-credentials weaviate-cluster --region us-central1"

Terraform crée les ressources suivantes :

  • Un réseau VPC personnalisé et un sous-réseau privé pour les nœuds Kubernetes
  • Un routeur cloud pour accéder à Internet via la traduction d'adresse réseau (NAT)
  • Un cluster GKE privé dans la région us-central1 avec l'autoscaling activé (un à deux nœuds par zone)
  • Un ServiceAccount avec les autorisations de journalisation et de surveillance pour le cluster
  • Configuration de Google Cloud Managed Service pour Prometheus pour la surveillance et les alertes relatives au cluster.

Se connecter au cluster

Configurez kubectl pour récupérer les identifiants et communiquer avec votre nouveau cluster GKE :

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

Déployer la base de données Weaviate sur votre cluster

Pour déployer la base de données Weaviate sur votre cluster GKE à l'aide du chart Helm, procédez comme suit :

  1. Ajoutez le dépôt du chart Helm de la base de données Weaviate pour pouvoir le déployer sur votre cluster GKE :

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

  2. Créez l'espace de noms weaviate pour la base de données :

    kubectl create ns weaviate

  3. Créez un secret pour stocker la clé API :

    kubectl create secret generic apikeys --from-literal=AUTHENTICATION_APIKEY_ALLOWED_KEYS=$(openssl rand -base64 32) -n weaviate

  4. Déployez un équilibreur de charge interne pour accéder à Weaviate depuis le réseau virtuel :

    kubectl apply -n weaviate -f manifests/05-ilb/ilb.yaml

    Le fichier manifeste ilb.yaml décrit le service d'équilibrage de charge :

    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. Appliquez le fichier manifeste pour déployer le cluster Weaviate.

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

    Le fichier manifeste weaviate_cluster.yaml décrit le déploiement :

    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

    Attendez quelques minutes que le cluster Weaviate démarre complètement.

  6. Vérifiez l'état du déploiement :

    kubectl get weaviate -n weaviate --watch

    Le résultat ressemble à ce qui suit, si la base de données weaviate est bien déployée :

    NAME: weaviate
LAST DEPLOYED: Tue Jun 18 13:15:53 2024
NAMESPACE: weaviate
STATUS: deployed
REVISION: 1
TEST SUITE: None

  7. Attendez que Kubernetes démarre les ressources :

    kubectl wait pods -l app.kubernetes.io/name=weaviate --for condition=Ready --timeout=300s -n weaviate

Exécuter des requêtes avec le notebook Vertex AI Colab Enterprise

Cette section explique comment se connecter à votre base de données Weaviate à l'aide de Colab Enterprise. Vous pouvez utiliser un modèle d'exécution dédié pour le déploiement sur weaviate-vpc afin que le notebook puisse communiquer avec les ressources du cluster GKE.

Créer un modèle d'environnement d'exécution

Pour créer un modèle d'exécution, procédez comme suit :

  1. Dans la console Google Cloud, accédez à la page Modèles d'exécution de Colab Enterprise et assurez-vous que votre projet est sélectionné :

    Accéder aux modèles d'exécution

  2. Cliquez sur  Nouveau modèle. La boîte de dialogue Créer un modèle d'exécution s'affiche.

  3. Dans la section Principes de base de l'exécution :

    • Dans le champ Nom à afficher, saisissez weaviate-connect.
    • Dans la liste déroulante Région, sélectionnez us-central1. Il s'agit de la même région que votre cluster GKE.

  4. Dans la section Configurer le calcul :

    • Dans la liste déroulante Type de machine, sélectionnez e2-standard-2.
    • Dans le champ Taille de disque disponible, saisissez 30.

  5. Dans la section Mise en réseau et sécurité :

    • Dans la liste déroulante Réseau, sélectionnez le réseau dans lequel réside votre cluster GKE.
    • Dans la liste déroulante Sous-réseau, sélectionnez un sous-réseau correspondant.
    • Décochez la case Activer l'accès à l'Internet public.

  6. Cliquez sur Créer pour terminer la création du modèle d'exécution. Votre modèle d'exécution apparaît dans la liste sur l'onglet Modèles d'exécution.

Créer un environnement d'exécution

Pour créer un environnement d'exécution, procédez comme suit :

  1. Dans la liste des modèles d'exécution, cliquez sur dans la colonne Actions pour le modèle que vous venez de créer, puis sur Créer un environnement d'exécution. Le volet Créer un environnement d'exécution Vertex AI s'affiche.

  2. Cliquez sur Créer pour créer un environnement d'exécution basé sur votre modèle.

  3. Dans l'onglet Environnements d'exécution qui s'affiche, attendez que l'état passe à Opérationnel.

Importer le notebook

Pour importer le notebook :

  1. Accédez à l'onglet Notebooks, puis cliquez sur Importer un notebook à partir d'URL.

  2. Dans Source d'importation, sélectionnez URL.

  3. Sous URL de notebook, collez le lien suivant : raw.githubusercontent.com/epam/kubernetes-engine-samples/Weaviate/databases/weaviate/manifests/02-notebook/vector-database.ipynb

  4. Cliquez sur Importer.

Se connecter à l'environnement d'exécution et exécuter des requêtes

Pour vous connecter à l'environnement d'exécution et exécuter des requêtes :

  1. Dans le notebook, à côté du bouton Connecter, cliquez sur Options de connexion supplémentaires. Le volet Se connecter à l'environnement d'exécution Vertex AI s'affiche.

  2. Sélectionnez Se connecter à un environnement d'exécution, puis Se connecter à un environnement d'exécution existant.

  3. Sélectionnez l'environnement d'exécution que vous avez lancé, puis cliquez sur Se connecter.

  4. Cliquez sur le bouton Exécuter la cellule situé à gauche de chaque cellule de code pour exécuter les cellules de notebook.

Le notebook contient des cellules de code et du texte décrivant chaque bloc de code. L'exécution d'une cellule de code exécute ses commandes et affiche une sortie. Vous pouvez exécuter les cellules dans l'ordre ou exécuter des cellules individuelles si nécessaire.

Pour en savoir plus sur Vertex AI Colab Enterprise, consultez la documentation Colab Enterprise.

Afficher les métriques Prometheus pour votre cluster

Le cluster GKE est configuré avec Google Cloud Managed Service pour Prometheus, ce qui permet de collecter des métriques au format Prometheus. Ce service fournit une solution entièrement gérée pour la surveillance et les alertes, permettant la collecte, le stockage et l'analyse des métriques du cluster et de ses applications.

Le schéma suivant montre comment Prometheus collecte les métriques pour votre cluster :

Collecte de métriques Prometheus

Le cluster privé GKE du schéma contient les composants suivants :

  • Pods Weaviate qui exposent des métriques sur le chemin d'accès /metrics et le port 2112.
  • Collecteurs basés sur Prometheus qui traitent les métriques à partir des pods Weaviate.
  • Une ressource PodMonitoring qui envoie des métriques à Cloud Monitoring.

Pour exporter et afficher les métriques, procédez comme suit :

  1. Créez la ressource PodMonitoring pour extraire les métriques par labelSelector :

    kubectl apply -n weaviate -f manifests/03-prometheus-metrics/pod-monitoring.yaml

    Le fichier manifeste pod-monitoring.yaml décrit la ressource PodMonitoring :

    apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: weaviate
spec:
  selector:
    matchLabels:
      app: weaviate
  endpoints:
  - port: 2112
    interval: 30s
    path: /metrics

  2. Pour importer un tableau de bord Cloud Monitoring personnalisé avec les configurations définies dans dashboard.json :

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

  3. Une fois la commande exécutée, accédez aux tableaux de bord Cloud Monitoring :

    Accéder à la page de présentation des tableaux de bord

  4. Dans la liste des tableaux de bord, ouvrez le tableau de bord Weaviate Overview. La collecte et l'affichage des métriques peuvent prendre un certain temps. Le tableau de bord affiche la quantité de fragments, de vecteurs et la latence des opérations.

Effectuer un nettoyage

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez les ressources individuelles.

Supprimer le projet

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez créé pour ce tutoriel.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Si vous avez supprimé le projet, le nettoyage est terminé. Si vous n'avez pas supprimé le projet, suivez les étapes ci-après afin de supprimer les ressources individuelles.

Supprimer des ressources individuelles

  1. Définissez les variables d'environnement.

    export PROJECT_ID=${PROJECT_ID}
export KUBERNETES_CLUSTER_PREFIX=weaviate
export REGION=us-central1

  2. Exécutez la commande 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}

    Remplacez FOLDER par gke-autopilot ou gke-standard, selon le type de cluster GKE que vous avez créé.

    Lorsque vous y êtes invité, saisissez yes.

  3. Recherchez tous les disques non associés :

    export disk_list=$(gcloud compute disks list --filter="-users:* AND labels.name=${KUBERNETES_CLUSTER_PREFIX}-cluster" --format "value[separator=|](name,region)")

  4. Supprimez les disques :

    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. Supprimez le dépôt GitHub :

    rm -r ~/kubernetes-engine-samples/

Étape suivante