Desplegar una base de datos de vectores de Weaviate en GKE

En este tutorial se explica cómo desplegar un clúster de base de datos de vectores Weaviate en Google Kubernetes Engine (GKE).

Weaviate es una base de datos vectorial de código abierto con un rendimiento de baja latencia y compatibilidad básica con diferentes tipos de contenido multimedia, como texto e imágenes. Admite la búsqueda semántica, la respuesta a preguntas y la clasificación. Weaviate se basa completamente en Go y almacena tanto objetos como vectores, lo que permite usar la búsqueda vectorial, la búsqueda por palabras clave y una combinación de ambas como búsqueda híbrida. Desde el punto de vista de la infraestructura, Weaviate es una base de datos nativa de la nube y tolerante a fallos. La tolerancia a fallos se consigue mediante una arquitectura sin líder, en la que cada nodo del clúster de la base de datos puede atender solicitudes de lectura y escritura, lo que a su vez elimina un único punto de fallo.

Este tutorial está dirigido a administradores y arquitectos de plataformas en la nube, ingenieros de aprendizaje automático y profesionales de MLOps (DevOps) que quieran desplegar clústeres de bases de datos vectoriales en GKE.

Ventajas

Weaviate ofrece las siguientes ventajas:

  • Bibliotecas para varios lenguajes de programación y API abierta para integrarse con otros servicios.
  • Escalado horizontal.
  • Un equilibrio entre la rentabilidad y la velocidad de las consultas, sobre todo cuando se trata de conjuntos de datos grandes. Puedes elegir cuántos datos se almacenan en la memoria y cuántos en el disco.

Objetivos

En este tutorial, aprenderás a hacer lo siguiente:

  • Planifica y despliega la infraestructura de GKE para Weaviate.
  • Despliega y configura la base de datos Weaviate en un clúster de GKE.
  • Ejecuta un cuaderno para generar y almacenar incrustaciones de vectores de ejemplo en tu base de datos y realiza consultas de búsqueda basadas en vectores.

Costes

En este documento, se utilizan los siguientes componentes facturables de Google Cloud:

Para generar una estimación de costes basada en el uso previsto, utiliza la calculadora de precios.

Los usuarios nuevos Google Cloud pueden disfrutar de una prueba gratuita.

Cuando termines las tareas que se describen en este documento, puedes evitar que se te siga facturando eliminando los recursos que has creado. Para obtener más información, consulta la sección Limpiar.

Antes de empezar

En este tutorial, usarás Cloud Shell para ejecutar comandos. Cloud Shell es un entorno de shell para gestionar recursos alojados en Google Cloud. Viene preinstalado con las herramientas de línea de comandos Google Cloud CLI, kubectl, Helm y Terraform. Si no usas Cloud Shell, debes instalar 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 utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  4. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    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 (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 utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  10. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    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 (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. Configurar un entorno

    Para configurar tu entorno con Cloud Shell, sigue estos pasos:

    1. Define las variables de entorno de tu proyecto, región y prefijo de recurso de clúster de Kubernetes:

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

      Sustituye PROJECT_ID por el ID de tu proyecto. Google Cloud

      En este tutorial se usa la región us-central1 para crear los recursos de implementación.

    2. Comprueba la versión de Helm:

      helm version

      Actualiza la versión si es anterior a la 3.13:

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

    3. Clona el repositorio de código de ejemplo de GitHub:

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

    4. Ve al directorio weaviate:

      cd kubernetes-engine-samples/databases/weaviate

    Crear la infraestructura del clúster

    En esta sección, ejecutarás una secuencia de comandos de Terraform para crear un clúster de GKE privado, de alta disponibilidad y regional para desplegar tu base de datos de Weaviate.

    Puedes elegir desplegar Weaviate con un clúster estándar o de Autopilot. Cada una tiene sus propias ventajas y modelos de precios diferentes.

    Autopilot

    En el siguiente diagrama se muestra un clúster de Autopilot de GKE desplegado en el proyecto.

    Clúster de Autopilot de GKE

    Para desplegar la infraestructura del clúster, ejecuta los siguientes comandos en 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 sustituye las siguientes variables en el tiempo de ejecución:

    • GOOGLE_OAUTH_ACCESS_TOKEN usa el comando gcloud auth print-access-token para obtener un token de acceso que autentica las interacciones con varias APIs de Google Cloud.
    • PROJECT_ID, REGION y KUBERNETES_CLUSTER_PREFIX son las variables de entorno definidas en la sección Configurar el entorno y asignadas a las nuevas variables relevantes del clúster de Autopilot que estás creando.

    Cuando se te solicite, escribe yes.

    El resultado debería ser similar al siguiente:

    ...
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 los siguientes recursos:

    • Una red de VPC personalizada y una subred privada para los nodos de Kubernetes.
    • Un Cloud Router para acceder a Internet a través de la traducción de direcciones de red (NAT).
    • Un clúster de GKE privado en la región us-central1.
    • Un ServiceAccount con permisos de registro y monitorización para el clúster.
    • Configuración de Google Cloud Managed Service para Prometheus para la monitorización y las alertas de clústeres.

    Estándar

    En el siguiente diagrama se muestra un clúster de GKE regional privado estándar desplegado en tres zonas diferentes.

    Clúster de GKE Standard

    Para desplegar la infraestructura del clúster, ejecuta los siguientes comandos en 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 sustituye las siguientes variables en el tiempo de ejecución:

    • GOOGLE_OAUTH_ACCESS_TOKEN usa el comando gcloud auth print-access-token para obtener un token de acceso que autentica las interacciones con varias APIs de Google Cloud.
    • PROJECT_ID, REGION y KUBERNETES_CLUSTER_PREFIX son las variables de entorno definidas en la sección Configurar el entorno y asignadas a las nuevas variables relevantes del clúster estándar que estás creando.

    Cuando se te solicite, escribe yes. Estos comandos pueden tardar varios minutos en completarse y el clúster en mostrar el estado "Listo".

    El resultado debería ser similar al siguiente:

    ...
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 los siguientes recursos:

    • Una red de VPC personalizada y una subred privada para los nodos de Kubernetes.
    • Un Cloud Router para acceder a Internet a través de la traducción de direcciones de red (NAT).
    • Un clúster privado de GKE en la región us-central1 con el autoescalado habilitado (de uno a dos nodos por zona).
    • Un ServiceAccount con permisos de registro y monitorización para el clúster.
    • Configuración de Google Cloud Managed Service para Prometheus para la monitorización y las alertas de clústeres.

    Conéctate al clúster

    Configura kubectl para obtener las credenciales y comunicarte con tu nuevo clúster de GKE:

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

    Desplegar la base de datos de Weaviate en el clúster

    Para usar el gráfico de Helm y desplegar la base de datos de Weaviate en tu clúster de GKE, sigue estos pasos:

    1. Añade el repositorio del gráfico de Helm de la base de datos Weaviate antes de poder implementarlo en tu clúster de GKE:

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

    2. Crea el espacio de nombres weaviate para la base de datos:

      kubectl create ns weaviate

    3. Crea un secreto para almacenar la clave de API:

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

    4. Despliega un balanceador de carga interno para acceder a Weaviate desde la red virtual:

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

      El manifiesto ilb.yaml describe el servicio del balanceador de carga:

      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. Aplica el manifiesto para desplegar el clúster de Weaviate:

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

      El manifiesto weaviate_cluster.yaml describe la implementación. Un Deployment es un objeto de la API de Kubernetes que te permite ejecutar varias réplicas de pods distribuidas entre los nodos de un clúster:

      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

      Espera unos minutos a que el clúster de Weaviate se inicie por completo.

    6. Comprueba el estado del despliegue:

      kubectl get weaviate -n weaviate --watch

      El resultado será similar al siguiente si la base de datos weaviate se implementa correctamente:

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

    7. Espera a que Kubernetes inicie los recursos:

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

    Ejecutar consultas con un cuaderno de Vertex AI Colab Enterprise

    En esta sección se explica cómo conectarse a su base de datos de Weaviate mediante Colab Enterprise. Puedes usar una plantilla de tiempo de ejecución específica para desplegar en weaviate-vpc, de modo que el cuaderno pueda comunicarse con los recursos del clúster de GKE.

    Para obtener más información sobre Vertex AI Colab Enterprise, consulta la documentación de Colab Enterprise.

    Crear una plantilla de tiempo de ejecución

    Para crear una plantilla de entorno de ejecución de Colab Enterprise, sigue estos pasos:

    1. En la Google Cloud consola, ve a la página Plantillas de tiempo de ejecución de Colab Enterprise y asegúrate de que tu proyecto esté seleccionado:

      Ir a Plantillas de entorno de ejecución

    2. Haz clic en Nueva plantilla. Aparecerá la página Crear plantilla de tiempo de ejecución.

    3. En la sección Información básica de Runtime:

      • En el campo Nombre visible, introduce weaviate-connect.
      • En la lista desplegable Región, selecciona us-central1. Es la misma región que tu clúster de GKE.

    4. En la sección Configurar recursos de computación:

      • En la lista desplegable Tipo de máquina, selecciona e2-standard-2.
      • En el campo Tamaño del disco, introduce 30.

    5. En la sección Redes y seguridad:

      • En la lista desplegable Red, selecciona la red en la que se encuentra tu clúster de GKE.
      • En la lista desplegable Subred, selecciona la subred correspondiente.
      • Desmarca la casilla Habilitar el acceso público a Internet.

    6. Para terminar de crear la plantilla de tiempo de ejecución, haga clic en Crear. Tu plantilla de entorno de ejecución aparece en la lista de la pestaña Plantillas de entorno de ejecución.

    Crear un tiempo de ejecución

    Para crear un entorno de ejecución de Colab Enterprise, sigue estos pasos:

    1. En la lista de plantillas de tiempo de ejecución de la plantilla que acaba de crear, vaya a la columna Acciones, haga clic en y, a continuación, en Crear tiempo de ejecución. Aparecerá el panel Crear tiempo de ejecución de Vertex AI.

    2. Para crear un tiempo de ejecución basado en tu plantilla, haz clic en Crear.

    3. En la pestaña Tiempos de ejecución que se abre, espera a que el estado cambie a Correcto.

    Importar el cuaderno

    Para importar el cuaderno en Colab Enterprise, sigue estos pasos:

    1. Ve a la pestaña Mis cuadernos y haz clic en Importar. Aparecerá el panel Importar cuadernos.

    2. En Importar fuente, selecciona URL.

    3. En URLs de cuadernos, introduce el siguiente enlace:

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

    4. Haz clic en Importar.

    Conectarse al entorno de ejecución y ejecutar consultas

    Para conectarte al entorno de ejecución y ejecutar consultas, sigue estos pasos:

    1. En el cuaderno, junto al botón Conectar, haz clic en Opciones de conexión adicionales. Aparecerá el panel Conectar con el entorno de ejecución de Vertex AI.

    2. Selecciona Conectar a un tiempo de ejecución y, a continuación, Conectar a un tiempo de ejecución existente.

    3. Selecciona el tiempo de ejecución que has iniciado y haz clic en Conectar.

    4. Para ejecutar las celdas del cuaderno, haz clic en el botón Ejecutar celda situado junto a cada celda de código.

    El cuaderno contiene celdas de código y texto que describe cada bloque de código. Al ejecutar una celda de código, se ejecutan sus comandos y se muestra un resultado. Puedes ejecutar las celdas en orden o ejecutar celdas concretas según sea necesario.

    Ver las métricas de Prometheus de un clúster

    El clúster de GKE está configurado con Managed Service para Prometheus de Google Cloud, lo que permite recoger métricas en formato Prometheus. Este servicio proporciona una solución totalmente gestionada para la monitorización y las alertas, lo que permite recoger, almacenar y analizar métricas del clúster y sus aplicaciones.

    En el siguiente diagrama se muestra cómo recopila Prometheus las métricas de tu clúster:

    Recogida de métricas de Prometheus

    El clúster privado de GKE del diagrama contiene los siguientes componentes:

    • Pods de Weaviate que exponen métricas en la ruta /metrics y el puerto 2112.
    • Recogedores basados en Prometheus que procesan las métricas de los pods de Weaviate.
    • Un recurso PodMonitoring que envía las métricas a Cloud Monitoring.

    Para exportar y ver las métricas, sigue estos pasos:

    1. Crea el recurso PodMonitoring para recoger métricas por labelSelector:

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

      El manifiesto pod-monitoring.yaml describe el recurso PodMonitoring:

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

    2. Para importar un panel de control de Cloud Monitoring personalizado con las configuraciones definidas en dashboard.json, sigue estos pasos:

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

    3. Una vez que se haya ejecutado correctamente el comando, vaya a Paneles de control de Cloud Monitoring:

      Ir a Información general sobre los paneles de control

    4. En la lista de paneles de control, abre el panel Weaviate Overview. Puede que se tarde un poco en recoger y mostrar las métricas. En el panel de control se muestra la cantidad de fragmentos, vectores y latencia de las operaciones.

    Limpieza

    Para evitar que los recursos utilizados en este tutorial se cobren en tu cuenta de Google Cloud, elimina el proyecto que contiene los recursos o conserva el proyecto y elimina los recursos.

    Eliminar el proyecto

    La forma más fácil de evitar que te cobren es eliminar el proyecto que has creado para este tutorial.

    Delete a Google Cloud project:

    gcloud projects delete PROJECT_ID

    Si has eliminado el proyecto, ya has terminado. Si no has eliminado el proyecto, elimina los recursos individuales.

    Eliminar recursos concretos

    1. Define las variables de entorno.

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

    2. Ejecuta el 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}

      Sustituye FOLDER por gke-autopilot o gke-standard, según el tipo de clúster de GKE que hayas creado.

      Cuando se te solicite, escribe yes.

    3. Para encontrar todos los discos sin adjuntar, haz lo siguiente:

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

    4. Elimina los discos:

      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 el repositorio de GitHub:

      rm -r ~/kubernetes-engine-samples/

    Siguientes pasos