Esegui il deployment di un database di vettori Weaviate su GKE

Autopilot Standard

---

Questo tutorial mostra come eseguire il deployment di un cluster di database di vettori Weaviate su Google Kubernetes Engine (GKE).

Weaviate è un database vettoriale open source con prestazioni a bassa latenza e supporto di base per diversi tipi di contenuti multimediali come testo e immagini. Supporta la ricerca semantica, la risposta a domande e la classificazione. Weaviate è completamente basato su Go e memorizza sia oggetti che vettori, consentendo l'utilizzo della ricerca vettoriale, della ricerca per parole chiave e di una combinazione di entrambe come ricerca ibrida. Dal punto di vista dell'infrastruttura, Weaviate è un database cloud-native e a tolleranza di errori. La tolleranza ai guasti è garantita da un'architettura senza leader in cui ogni nodo del cluster del database può soddisfare le richieste di lettura e scrittura, il che a sua volta esclude un singolo punto di errore.

Questo tutorial è rivolto ad amministratori e architetti della piattaforma cloud, ingegneri ML e professionisti MLOps (DevOps) interessati a eseguire il deployment di cluster di database vettoriali su GKE.

Vantaggi

Weaviate offre i seguenti vantaggi:

• Librerie per vari linguaggi di programmazione e API aperte da integrare con altri servizi.
• Scalabilità orizzontale.
• Un equilibrio tra convenienza e velocità di query, soprattutto quando si tratta di set di dati di grandi dimensioni. Puoi scegliere la quantità di dati da memorizzare in memoria rispetto a quella da memorizzare su disco.

Obiettivi

In questo tutorial imparerai a:

• Pianifica ed esegui il deployment dell'infrastruttura GKE per Weaviate.
• Esegui il deployment e configura il database Weaviate in un cluster GKE.
• Esegui un notebook per generare e archiviare esempi di embedding vettoriali nel tuo database ed eseguire query di ricerca basate su vettori.

Costi

In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:

• GKE
• Google Cloud Managed Service for Prometheus

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud potrebbero essere idonei per una prova gratuita.

Al termine delle attività descritte in questo documento, puoi evitare la fatturazione continua eliminando le risorse che hai creato. Per ulteriori informazioni, consulta la sezione Pulizia.

Prima di iniziare

In questo tutorial utilizzerai Cloud Shell per eseguire comandi. Cloud Shell è un ambiente shell per la gestione delle risorse ospitate su Google Cloud. È preinstallato con gli strumenti a riga di comando Google Cloud CLI, kubectl, Helm e Terraform. Se non utilizzi Cloud Shell, devi installare 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: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.

Configura l'ambiente

Per configurare l'ambiente con Cloud Shell:

1. Imposta le variabili di ambiente per il progetto, la regione e un prefisso della risorsa del cluster Kubernetes:

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

   Sostituisci PROJECT_ID con il tuo ID progetto Google Cloud.

   Questo tutorial utilizza la regione us-central1 per creare le risorse di deployment.

2. Controlla la versione di Helm:

   helm version
   

   Aggiorna la versione se è precedente alla 3.13:

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

3. Clona il repository di codice campione da GitHub:

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

4. Vai alla directory weaviate:

   cd kubernetes-engine-samples/databases/weaviate
   

Crea l'infrastruttura del cluster

In questa sezione esegui uno script Terraform per creare un cluster GKE regionale privato e ad alta disponibilità per eseguire il deployment del database Weaviate.

Puoi scegliere di eseguire il deployment di Weaviate utilizzando un cluster standard o Autopilot. Ognuno ha i suoi vantaggi e modelli di prezzi diversi.

Autopilot

Il seguente diagramma mostra un cluster GKE Autopilot eseguito nel progetto.

Per eseguire il deployment dell'infrastruttura del cluster, esegui i seguenti comandi in 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 sostituisce le seguenti variabili in fase di runtime:

• GOOGLE_OAUTH_ACCESS_TOKEN utilizza il comando gcloud auth print-access-token per recuperare un token di accesso che autentica le interazioni con varie API Google Cloud
• PROJECT_ID, REGION e KUBERNETES_CLUSTER_PREFIX sono le variabili di ambiente definite nella sezione Configurare l'ambiente e assegnate alle nuove variabili pertinenti per il cluster Autopilot che stai creando.

Quando richiesto, digita yes.

L'output è simile al seguente:

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

Outputs:

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

Terraform crea le seguenti risorse:

• Una rete VPC personalizzata e una subnet privata per i nodi Kubernetes.
• Un router Cloud per accedere a internet tramite Network Address Translation (NAT).
• Un cluster GKE privato nella regione us-central1.
• Un ServiceAccount con autorizzazioni di logging e monitoraggio per il cluster.
• Configurazione di Google Cloud Managed Service per Prometheus per il monitoraggio e l'invio di avvisi per i cluster.

Standard

Il seguente diagramma mostra un cluster GKE regionale privato standard di cui è stato eseguito il deployment in tre zone diverse.

Per eseguire il deployment dell'infrastruttura del cluster, esegui i seguenti comandi in 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 sostituisce le seguenti variabili in fase di runtime:

• GOOGLE_OAUTH_ACCESS_TOKEN utilizza il comando gcloud auth print-access-token per recuperare un token di accesso che autentica le interazioni con varie API Google Cloud.
• PROJECT_ID, REGION e KUBERNETES_CLUSTER_PREFIX sono le variabili di ambiente definite nella sezione Configurare l'ambiente e assegnate alle nuove variabili pertinenti per il cluster standard che stai creando.

Quando richiesto, digita yes. Potrebbero essere necessari diversi minuti prima che questi comandi vengano completati e che il cluster mostri lo stato di disponibilità.

L'output è simile al seguente:

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

Outputs:

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

Terraform crea le seguenti risorse:

• Una rete VPC personalizzata e una subnet privata per i nodi Kubernetes.
• Un router Cloud per accedere a internet tramite Network Address Translation (NAT).
• Un cluster GKE privato nella regione us-central1 con la scalabilità automatica abilitata (da uno a due nodi per zona).
• Un ServiceAccount con autorizzazioni di logging e monitoraggio per il cluster.
• Configurazione di Google Cloud Managed Service per Prometheus per il monitoraggio e l'invio di avvisi dei cluster.

Connettiti al cluster

Configura kubectl per recuperare le credenziali e comunicare con il nuovo cluster GKE:

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

Esegui il deployment del database Weaviate nel tuo cluster

Per utilizzare il grafico Helm per eseguire il deployment del database Weaviate nel cluster GKE, segui questi passaggi:

1. Aggiungi il repository del grafico Helm del database Weaviate prima di poterlo eseguire sul tuo cluster GKE:

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

2. Crea lo spazio dei nomi weaviate per il database:

   kubectl create ns weaviate
   

3. Crea un segreto per memorizzare la chiave API:

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

4. Esegui il deployment di un bilanciatore del carico interno per accedere a Weaviate dall'interno della rete virtuale:

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

   Il manifest ilb.yaml descrive il servizio bilanciatore del carico:

   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. Applica il manifest per eseguire il deployment del cluster Weaviate:

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

   Il manifest weaviate_cluster.yaml descrive il 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

   Attendi qualche minuto per il completamento dell'avvio del cluster Weaviate.

6. Controlla lo stato del deployment:

   kubectl get weaviate -n weaviate --watch
   

   L'output è simile al seguente, se il database weaviate è stato eseguito correttamente:

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

7. Attendi che Kubernetes avvii le risorse:

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

Esegui query con il notebook Vertex AI Colab Enterprise

Questa sezione spiega come connetterti al database Weaviate utilizzando Colab Enterprise. Puoi utilizzare un modello di runtime dedicato per eseguire il deployment in weaviate-vpc, in modo che il notebook possa comunicare con le risorse nel cluster GKE.

Creare un modello di runtime

Per creare un modello di runtime:

1. Nella console Google Cloud, vai alla pagina Modelli di runtime di Colab Enterprise e assicurati che il progetto sia selezionato:

   Vai a Modelli di runtime

2. Fai clic su Nuovo modello. Viene visualizzata la pagina Crea nuovo modello di runtime.

3. Nella sezione Nozioni di base del runtime:

   • Nel campo Nome visualizzato, inserisci weaviate-connect.
   • Nell'elenco a discesa Regione, seleziona us-central1. È la stessa regione del tuo cluster GKE.

4. Nella sezione Configura calcolo:

   • Nell'elenco a discesa Tipo di macchina, seleziona e2-standard-2.
   • Nel campo Dimensione disco, inserisci 30.

5. Nella sezione Networking e sicurezza:

   • Nell'elenco a discesa Rete, seleziona la rete in cui si trova il cluster GKE.
   • Nell'elenco a discesa Subnet, seleziona una subnet corrispondente.
   • Deseleziona la casella di controllo Attiva l'accesso a internet pubblico.

6. Fai clic su Crea per completare la creazione del modello di runtime. Il modello di runtime viene visualizzato nell'elenco della scheda Modelli di runtime.

Creare un runtime

Per creare un runtime:

1. Nell'elenco dei modelli di runtime, fai clic su nella colonna Azioni per il modello appena creato, quindi fai clic su Crea runtime. Viene visualizzato il riquadro Crea runtime di Vertex AI.

2. Fai clic su Crea per creare un runtime in base al modello.

3. Nella scheda Ambienti di esecuzione che si apre, attendi che lo stato passi a Intatto.

Importa il notebook

Per importare il notebook:

1. Vai alla scheda Notebook e fai clic su Importa notebook da URL.

2. In Origine importazione, seleziona URL.

3. In URL notebook, incolla il seguente link: raw.githubusercontent.com/GoogleCloudPlatform/kubernetes-engine-samples/main/databases/weaviate/manifests/02-notebook/vector-database.ipynb

4. Fai clic su Importa.

Connettiti al runtime ed esegui query

Per connetterti al runtime ed eseguire query:

1. Nel notebook, accanto al pulsante Connetti, fai clic su Altre opzioni di connessione. Viene visualizzato il riquadro Connetti al runtime di Vertex AI.

2. Seleziona Connetti a un runtime e poi Connetti a un runtime esistente.

3. Seleziona il runtime che hai avviato e fai clic su Connetti.

4. Fai clic sul pulsante Esegui cella a sinistra di ogni cella di codice per eseguire le celle del blocco note.

Il notebook contiene celle di codice e testo che descrivono ogni blocco di codice. L'esecuzione di una cella di codice esegue i relativi comandi e mostra un output. Puoi eseguire le celle in ordine o eseguire singole celle in base alle esigenze.

Per ulteriori informazioni su Vertex AI Colab Enterprise, consulta la documentazione di Colab Enterprise.

Visualizzare le metriche Prometheus per il cluster

Il cluster GKE è configurato con Google Cloud Managed Service per Prometheus, che consente la raccolta delle metriche nel formato Prometheus. Questo servizio fornisce una soluzione completamente gestita per il monitoraggio e l'invio di avvisi, consentendo la raccolta, lo stoccaggio e l'analisi delle metriche del cluster e delle sue applicazioni.

Il seguente diagramma mostra come Prometheus raccoglie le metriche per il cluster:

Il cluster privato GKE nel diagramma contiene i seguenti componenti:

• Pod Weaviate che espongono le metriche sul percorso /metrics e sulla porta 2112.
• Raccoglitori basati su Prometheus che elaborano le metriche dei pod Weaviate.
• Una risorsa PodMonitoring che invia le metriche a Cloud Monitoring.

Per esportare e visualizzare le metriche:

1. Crea la risorsa PodMonitoring per eseguire lo scraping delle metriche per labelSelector:

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

   Il manifest pod-monitoring.yaml descrive la risorsa PodMonitoring:

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

2. Per importare una dashboard di Cloud Monitoring personalizzata con le configurazioni definite in dashboard.json:

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

3. Una volta eseguito correttamente il comando, vai alle dashboard di Cloud Monitoring:

   Vai alla panoramica delle dashboard

4. Dall'elenco delle dashboard, apri la dashboard Weaviate Overview. Potrebbe essere necessario un po' di tempo per raccogliere e visualizzare le metriche. La dashboard mostra la quantità di latenza di Shard, Vettori e operazioni

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Elimina il progetto

Il modo più semplice per evitare la fatturazione è eliminare il progetto che hai creato per questo tutorial.

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività descritte in questo documento, quando lo elimini elimini anche tutto il lavoro svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, il riuso dei progetti può aiutarti a non superare i limiti di quota.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Se hai eliminato il progetto, la pulizia è completata. Se non hai eliminato il progetto, procedi con l'eliminazione delle singole risorse.

Elimina singole risorse

1. Imposta le variabili di ambiente.

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

2. Esegui il comando 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}
   

   Sostituisci FOLDER con gke-autopilot o gke-standard, a seconda del tipo di cluster GKE che hai creato.

   Quando richiesto, digita yes.

3. Trova tutti i dischi scollegati:

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

4. Elimina i dischi:

   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. Elimina il repository GitHub:

   rm -r ~/kubernetes-engine-samples/
   

Passaggi successivi

• Esplora Weaviate nel marketplace GKE.
• Scopri le best practice per il deployment dei database su GKE.
• Scopri le soluzioni per l'esecuzione di carichi di lavoro con utilizzo intensivo di dati con GKE.