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 contenus multimédias tels que le texte et les images. Il est compatible avec la recherche sémantique, les questions-réponses et la classification. Weaviate est entièrement conçu en Go et stocke à la fois des objets et des vecteurs, ce qui permet d'utiliser la recherche vectorielle, la recherche par mot clé et une combinaison des deux sous forme de recherche hybride. D'un point de vue 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, où chaque nœud du cluster de base de données peut traiter les 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
  • Un équilibre entre rentabilité et vitesse des requêtes, en particulier lorsque vous traitez de grands ensembles de données. Vous pouvez choisir la quantité de données stockées en mémoire par rapport à celles stockées sur le 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 effectuez des requêtes de recherche vectorielle.

Coûts

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

Vous pouvez obtenir 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 sans frais.

Une fois que vous avez terminé les tâches décrites dans ce document, supprimez les ressources que vous avez créées pour éviter que des frais vous soient facturés. 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. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  4. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

  5. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Cloud Resource Manager, Compute Engine, GKE, and IAM Service Account Credentials APIs:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

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

  8. Install the Google Cloud CLI.

  9. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  10. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

  11. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

  12. Verify that billing is enabled for your Google Cloud project.

  13. Enable the Cloud Resource Manager, Compute Engine, GKE, and IAM Service Account Credentials APIs:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

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

  14. 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 the following:

    • PROJECT_ID: Your project ID.
    • USER_IDENTIFIER: The identifier for your user account. For example, myemail@example.com.
    • ROLE: The IAM role that you grant to your user account.

    15. 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 du projet Google Cloud.

      Ce tutoriel utilise la région us-central1 pour créer les 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 --location ${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. Un déploiement est un objet de l'API Kubernetes qui vous permet d'exécuter plusieurs instances dupliquées de pods répartis entre les nœuds d'un cluster :

      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 un notebook Vertex AI Colab Enterprise

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

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

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

    Pour créer un modèle d'exécution Colab Enterprise :

    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 page 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 sur 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 Internet public.

    6. Pour terminer la création du modèle d'exécution, cliquez sur Créer. 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 Colab Enterprise :

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

    2. Pour créer un environnement d'exécution basé sur votre modèle, cliquez sur Créer.

    3. Dans l'onglet Environnements d'exécution qui s'ouvre, attendez que l'état passe à Sain.

    Importer le notebook

    Pour importer le notebook dans Colab Enterprise :

    1. Accédez à l'onglet Mes notebooks, puis cliquez sur Importer. Le volet Importer des notebooks s'affiche.

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

    3. Sous URL de notebook, saisissez le lien suivant :

      https://raw.githubusercontent.com/GoogleCloudPlatform/kubernetes-engine-samples/main/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 Connect (Se connecter).

    4. Pour exécuter les cellules du notebook, cliquez sur le bouton Exécuter la cellule à côté de chaque cellule de code.

    Le notebook contient à la fois des cellules de code et du texte qui décrit chaque bloc de code. L'exécution d'une cellule de code exécute ses commandes et affiche un résultat. Vous pouvez exécuter les cellules dans l'ordre ou exécuter des cellules individuelles selon vos besoins.

    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 le nombre 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