Implementa una base de datos vectorial de Weaviate en GKE

En este instructivo, se muestra cómo implementar un clúster de base de datos vectorial de 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 medios, como texto e imágenes. Admite la búsqueda semántica, la clasificación y la respuesta a preguntas. Weaviate está completamente creado en Go y almacena tanto objetos como vectores, lo que permite usar la búsqueda de vectores, la búsqueda de palabras clave y una combinación de ambas como búsqueda híbrida. Desde una perspectiva de infraestructura, Weaviate es una base de datos nativa de la nube y tolerante a errores. La tolerancia a errores se logra con una arquitectura sin líder en la que cada nodo del clúster de bases de datos puede atender solicitudes de lectura y escritura, lo que a su vez excluye un único punto de falla.

Este instructivo está dirigido a administradores y arquitectos de plataformas de nube, ingenieros de AA y profesionales de MLOps (DevOps) interesados en implementar clústeres de bases de datos vectoriales en GKE.

Beneficios

Weaviate ofrece los siguientes beneficios:

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

Objetivos

En este instructivo, aprenderás a realizar lo siguiente:

  • Planificar y, además, implementar la infraestructura de GKE para Weaviate
  • Implementar y configurar la base de datos de Weaviate en un clúster de GKE
  • Ejecuta un notebook para generar y almacenar embeddings de vectores de ejemplo en tu base de datos, y realiza consultas de búsqueda basadas en vectores.

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios.

Es posible que los usuarios de Google Cloud nuevos cumplan con los requisitos para acceder a una prueba gratuita.

Cuando completes las tareas que se describen en este documento, podrás borrar los recursos que creaste para evitar que se te siga facturando. Para obtener más información, consulta Realiza una limpieza.

Antes de comenzar

En este instructivo, usarás Cloud Shell para ejecutar comandos. Cloud Shell es un entorno de shell que se usa para administrar recursos alojados en Google Cloud. Viene preinstalado con las herramientas de línea de comandos de Google Cloud CLI, kubectl, Helm y Terraform. Si no usas Cloud Shell, debes instalar Google Cloud CLI.

  1. Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

  2. Instala Google Cloud CLI.

  3. Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

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

    gcloud init

  5. Crea o selecciona un Google Cloud proyecto.

    Roles necesarios para seleccionar o crear un proyecto

    • Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
    • Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

    • Crea un proyecto de Google Cloud :

      gcloud projects create PROJECT_ID

      Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

    • Selecciona el proyecto Google Cloud que creaste:

      gcloud config set project PROJECT_ID

      Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

  6. Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

  7. Habilita las APIs de Cloud Resource Manager, Compute Engine, GKE y Service Account Credentials de IAM:

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles. 

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

  8. Instala Google Cloud CLI.

  9. Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

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

    gcloud init

  11. Crea o selecciona un Google Cloud proyecto.

    Roles necesarios para seleccionar o crear un proyecto

    • Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
    • Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

    • Crea un proyecto de Google Cloud :

      gcloud projects create PROJECT_ID

      Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

    • Selecciona el proyecto Google Cloud que creaste:

      gcloud config set project PROJECT_ID

      Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

  12. Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

  13. Habilita las APIs de Cloud Resource Manager, Compute Engine, GKE y Service Account Credentials de IAM:

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles. 

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

  14. Otorga roles a tu cuenta de usuario. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM: 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

    Reemplaza lo siguiente:

    • PROJECT_ID: ID del proyecto
    • USER_IDENTIFIER: Es el identificador de tu cuenta de usuario de . Por ejemplo, myemail@example.com.
    • ROLE: Es el rol de IAM que otorgas a tu cuenta de usuario.

Configura tu entorno

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

  1. Configura las variables de entorno del proyecto, la región y el prefijo de recursos del clúster de Kubernetes:

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

    Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud.

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

  2. Verifica 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 muestra de GitHub:

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

  4. Navega al directorio weaviate:

    cd kubernetes-engine-samples/databases/weaviate

Crea la infraestructura del clúster

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

Puedes elegir implementar Weaviate con un clúster de Standard o Autopilot. Cada uno tiene sus propias ventajas y diferentes modelos de precios.

Autopilot

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

Clúster de GKE Autopilot

Para implementar 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 reemplaza las siguientes variables en el entorno de ejecución:

  • GOOGLE_OAUTH_ACCESS_TOKEN usa el comando gcloud auth print-access-token para recuperar 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 Configura tu entorno y asignadas a las nuevas variables relevantes para el clúster de Autopilot que creas.

Cuando se te solicite, escribe yes.

El resultado es 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 supervisión para el clúster.
  • Configuración de Google Cloud Managed Service para Prometheus para la supervisión y las alertas de clústeres.

Estándar

En el siguiente diagrama, se muestra un clúster de GKE regional privado de Standard implementado en tres zonas diferentes.

Clúster de GKE Standard

Para implementar 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 reemplaza las siguientes variables en el entorno de ejecución:

  • GOOGLE_OAUTH_ACCESS_TOKEN usa el comando gcloud auth print-access-token para recuperar 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 Configura tu entorno y asignadas a las nuevas variables relevantes para el clúster de Standard que creas.

Cuando se te solicite, escribe yes. Es posible que estos comandos tarden varios minutos en completarse y que el clúster muestre un estado de preparación.

El resultado es 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 de GKE privado en la región us-central1 con el ajuste de escala automático habilitado (de uno a dos nodos por zona).
  • Un ServiceAccount con permisos de registro y supervisión para el clúster.
  • Configuración de Google Cloud Managed Service para Prometheus para la supervisión y las alertas de clústeres.

Conéctate al clúster

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

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

Implementa la base de datos de Weaviate en tu clúster

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

  1. Agrega el repositorio de gráficos de Helm de la base de datos de Weaviate para 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. Implementa un balanceador de cargas 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 cargas:

    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 implementar el clúster de Weaviate:

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

    En el manifiesto weaviate_cluster.yaml, se describe el Deployment. Un Deployment es un objeto de la API de Kubernetes que te permite ejecutar varias réplicas de Pods que se distribuyen 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 para que el clúster de Weaviate se inicie por completo.

  6. Verifica el estado de la implementación:

    kubectl get weaviate -n weaviate --watch

    El resultado es similar al siguiente, si la base de datos weaviate se implementó de forma correcta:

    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

Ejecuta consultas con el notebook de Colab Enterprise de Vertex AI

En esta sección, se explica cómo conectarte a tu base de datos de Weaviate con Colab Enterprise. Puedes usar una plantilla de tiempo de ejecución dedicada para realizar la implementación en weaviate-vpc, de modo que el notebook 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.

Crea una plantilla de entorno de ejecución

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

  1. En la consola de Google Cloud , ve a la página Plantillas de entorno 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 New Template. Aparecerá la página Crear nueva plantilla de entorno de ejecución.

  3. En la sección Conceptos básicos del entorno de ejecución, haz lo siguiente:

    • En el campo Nombre visible, escribe 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 proceso, haz lo siguiente:

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

  5. En la sección Herramientas de redes y seguridad, haz lo siguiente:

    • En la lista desplegable Red, selecciona la red en la que reside tu clúster de GKE.
    • En la lista desplegable Subred, selecciona una subred correspondiente.
    • Desmarca la casilla de verificación Habilitar el acceso a Internet pública.

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

Crea un entorno de ejecución

Para crear un entorno de ejecución de Colab Enterprise, haz lo siguiente:

  1. En la lista de plantillas de ejecución de la plantilla que acabas de crear, en la columna Acciones, haz clic en y, luego, en Crear tiempo de ejecución. Aparecerá el panel Crear entorno de ejecución de Vertex AI.

  2. Para crear un entorno 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.

Importa el notebook

Para importar el notebook en Colab Enterprise, haz lo siguiente:

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

  2. En Fuente de importación, selecciona URL.

  3. En URLs de notebooks, ingresa el siguiente vínculo:

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

  4. Haz clic en Importar.

Conéctate al entorno de ejecución y ejecuta consultas

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

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

  2. Selecciona Conectar a un entorno de ejecución y, luego, Conectarse a un entorno de ejecución existente.

  3. Selecciona el entorno de ejecución que iniciaste y haz clic en Conectar.

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

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

Visualiza las métricas de Prometheus de tu clúster

El clúster de GKE se configura con Google Cloud Managed Service para Prometheus, que permite la recopilación de métricas en el formato Prometheus. Este servicio proporciona una solución completamente administrada para la supervisión y las alertas, lo que permite la recopilación, el almacenamiento y el análisis de métricas del clúster y sus aplicaciones.

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

Recopilación de métricas de Prometheus

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

  • Pods de Weaviate que exponen métricas en la ruta /metrics y el puerto 2112.
  • Recopiladores 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 extraer 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 Cloud Monitoring personalizado con los parámetros de configuración definidos en dashboard.json, haz lo siguiente:

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

  3. Después de que el comando se ejecute de forma correcta, ve a los Paneles de Cloud Monitoring:

    Ir a Descripción general de los paneles

  4. En la lista de paneles, abre el panel Weaviate Overview. La recopilación y visualización de las métricas puede llevar un tiempo. En el panel, se muestra la cantidad de fragmentos, vectores y la latencia de las operaciones.

Realiza una limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o conserva el proyecto y borra los recursos individuales.

Borra el proyecto

La manera más fácil de evitar la facturación es borrar el proyecto que creaste para el instructivo.

Borra un Google Cloud proyecto:

gcloud projects delete PROJECT_ID

Si borraste el proyecto, tu limpieza se completó. Si no borraste el proyecto, borra los recursos individuales.

Borra los recursos individuales

  1. Configurar 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}

    Reemplaza 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. Busca todos los discos no conectados:

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

  4. Borra 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. Borra el repositorio de GitHub

    rm -r ~/kubernetes-engine-samples/

¿Qué sigue?