Implantar um banco de dados de vetores Weaviate no GKE

Neste tutorial, mostramos como implantar um cluster de banco de dados de vetores PostgreSQL no Google Kubernetes Engine (GKE).

O Weaviate é um banco de dados vetorial de código aberto com desempenho de baixa latência e compatibilidade básica com diferentes tipos de mídia, como texto e imagens. Ele é compatível com a pesquisa semântica, respostas a perguntas e classificação. O Weaviate é totalmente desenvolvido em Go e armazena objetos e vetores, permitindo o uso de pesquisa vetorial, pesquisa de palavras-chave e uma combinação de ambos como uma pesquisa híbrida. Do ponto de vista da infraestrutura, o Weaviate é um banco de dados nativo da nuvem e tolerante a falhas. A tolerância a falhas é fornecida por uma arquitetura sem líder, em que cada nó do cluster de banco de dados pode atender a solicitações de leitura e gravação, o que exclui um ponto único de falha.

Este tutorial é destinado a administradores e arquitetos de plataformas de nuvem, engenheiros de ML e profissionais de MLOps (DevOps) interessados em implantar clusters de banco de dados vetoriais no GKE.

Benefícios

O Weaviate oferece os seguintes benefícios:

  • Bibliotecas para várias linguagens de programação e API aberta para integração com outros serviços.
  • Escalonamento horizontal.
  • Equilíbrio entre custo-benefício e velocidade de consulta, especialmente ao lidar com grandes conjuntos de dados. Você pode escolher quantos dados são armazenados na memória e no disco.

Objetivos

Neste tutorial, você aprenderá a realizar as seguintes tarefas:

  • Planejar e implantar a infraestrutura do GKE para Weaviate.
  • Implantar e configurar o banco de dados do Weaviate em um cluster do GKE.
  • Executar um notebook para gerar e armazenar exemplos de embeddings vetoriais no seu banco de dados e realizar consultas de pesquisa baseadas em vetores.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.

Antes de começar

Neste tutorial, use o Cloud Shell para executar os comandos. O Cloud Shell é um ambiente shell para gerenciar recursos hospedados no Google Cloud. Ele vem pré-instalado com CLI do Google Cloud, kubectl, Helm e ferramentas de linha de comando do Terraform. Se você não estiver usando o Cloud Shell, instale a CLI do Google Cloud.

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

Configurar seu ambiente

Para configurar o ambiente com o Cloud Shell, siga estas etapas:

  1. Defina variáveis de ambiente para o projeto, a região e um prefixo de recurso de cluster do Kubernetes:

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

    Substitua o PROJECT_ID pelo ID do projeto do Google Cloud.

    Este tutorial usa a região us-central1 para criar seus recursos de implantação.

  2. Verifique a versão do Helm:

    helm version

    Atualize a versão se ela for anterior à 3.13:

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

  3. Clone o repositório de exemplo de código do GitHub:

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

  4. Acesse o diretório weaviate:

    cd kubernetes-engine-samples/databases/weaviate

Criar a infraestrutura do cluster

Nesta seção, você vai executar um script do Terraform para criar um cluster privado, altamente disponível e regional do GKE a fim de implantar o banco de dados do Weaviate.

É possível usar um cluster Standard ou Autopilot para a implantação do Weaviate. Cada um tem vantagens específicas e modelos de preços diferentes.

Piloto automático

O diagrama a seguir mostra um cluster do GKE Autopilot implantado no projeto.

Cluster do Autopilot do GKE

Para implantar a infraestrutura do cluster, execute os seguintes comandos no 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}

O GKE substitui as seguintes variáveis no ambiente de execução:

  • GOOGLE_OAUTH_ACCESS_TOKEN usa o comando gcloud auth print-access-token para recuperar um token de acesso que autentique interações com várias APIs do Google Cloud.
  • PROJECT_ID, REGION e KUBERNETES_CLUSTER_PREFIX são as variáveis de ambiente definidas na seção Configurar seu ambiente e atribuídas às novas variáveis relevantes para o cluster do Autopilot que você está criando.

Quando solicitado, digite yes.

O resultado será assim:

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

Outputs:

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

O Terraform cria os seguintes recursos:

  • Uma rede VPC personalizada e uma sub-rede particular para os nós do Kubernetes.
  • Um Cloud Router para acessar a Internet por meio da conversão de endereços de rede (NAT).
  • Um cluster do GKE particular na região us-central1.
  • Um ServiceAccount com permissões de geração de registros e monitoramento para o cluster.
  • Configuração do Google Cloud Managed Service para Prometheus para monitoramento e alertas de clusters.

Padrão

O diagrama a seguir mostra um cluster do GKE regional particular padrão implantado em três zonas diferentes.

Cluster do GKE Standard

Para implantar a infraestrutura do cluster, execute os seguintes comandos no 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}

O GKE substitui as seguintes variáveis no ambiente de execução:

  • GOOGLE_OAUTH_ACCESS_TOKEN usa o comando gcloud auth print-access-token para recuperar um token de acesso que autentique interações com várias APIs do Google Cloud.
  • PROJECT_ID, REGION e KUBERNETES_CLUSTER_PREFIX são as variáveis de ambiente definidas na seção Configurar seu ambiente e atribuídas às novas variáveis relevantes para o cluster padrão que você está criando.

Quando solicitado, digite yes. Pode levar vários minutos para que esses comandos sejam concluídos e o cluster mostre um status pronto.

O resultado será assim:

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

Outputs:

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

O Terraform cria os seguintes recursos:

  • Uma rede VPC personalizada e uma sub-rede particular para os nós do Kubernetes.
  • Um Cloud Router para acessar a Internet por meio da conversão de endereços de rede (NAT).
  • Um cluster do GKE particular na região us-central1 com escalonamento automático ativado (de um a dois nós por zona).
  • Um ServiceAccount com permissões de geração de registros e monitoramento para o cluster.
  • Configuração do Google Cloud Managed Service para Prometheus para monitoramento e alerta de clusters.

Conectar ao cluster

Configure kubectl para buscar credenciais e se comunicar com o novo cluster do GKE:

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

Implantar o banco de dados do Weaviate no cluster

Para usar o gráfico do Helm e implantar o banco de dados do Weaviate no cluster do GKE, siga estas etapas:

  1. Adicione o repositório Helm Chart do banco de dados da Weaviate antes de implantá-lo no cluster do GKE:

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

  2. Crie o namespace weaviate para o banco de dados:

    kubectl create ns weaviate

  3. Crie um secret para armazenar a chave de API:

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

  4. Implante um balanceador de carga interno para acessar o Weaviate na rede virtual:

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

    O manifesto ilb.yaml descreve o serviço do 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. Aplique o manifesto para implantar o cluster do Weaviate.

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

    O manifesto weaviate_cluster.yaml descreve a implantação:

    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

    Aguarde alguns minutos até que o cluster do Weaviate seja totalmente iniciado.

  6. Verifique o status da implantação:

    kubectl get weaviate -n weaviate --watch

    Se o banco de dados weaviate for implantado com sucesso, a saída será semelhante à seguinte:

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

  7. Aguarde o Kubernetes iniciar os recursos:

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

Executar consultas com o notebook do Colab Enterprise da Vertex AI

Esta seção explica como se conectar ao banco de dados do Weaviate usando o Colab Enterprise. É possível usar um modelo de ambiente de execução dedicado para implantar no weaviate-vpc, para que o notebook possa se comunicar com os recursos no cluster do GKE.

Criar um modelo de ambiente de execução

Para criar um modelo de ambiente de execução:

  1. No console do Google Cloud, acesse a página Modelos de ambiente de execução do Colab Enterprise e verifique se o projeto está selecionado:

    Acessar "Modelos de ambiente de execução"

  2. Clique em Novo modelo. A página Criar novo modelo de ambiente de execução será exibida.

  3. Na seção Fundamentos do ambiente de execução:

    • No campo Nome de exibição, insira weaviate-connect.
    • Na lista suspensa Região, selecione us-central1. É a mesma região do cluster do GKE.

  4. Na seção Configurar computação:

    • Na lista suspensa Tipo de máquina, selecione e2-standard-2.
    • No campo Tamanho do disco, digite 30.

  5. Na seção Rede e segurança:

    • Na lista suspensa Rede, selecione uma rede em que o cluster do GKE esteja localizado.
    • Na lista suspensa Sub-rede, selecione uma sub-rede correspondente.
    • Desmarque a caixa de seleção Ativar acesso à Internet pública.

  6. Clique em Criar para concluir a criação do modelo de ambiente de execução. Seu modelo de ambiente de execução aparece na lista da guia Modelos de ambiente de execução.

Criar um ambiente de execução

Para criar um ambiente de execução:

  1. Na lista de modelos de ambiente de execução, para o modelo que você acabou de criar, clique em na coluna Ações e, em seguida, clique em Criar ambiente de execução. O painel Criar ambiente de execução da Vertex AI será exibido.

  2. Clique em Criar para criar um ambiente de execução com base no modelo.

  3. Na guia Ambientes de execução que é aberta, aguarde até que o status mude para Íntegro.

Importar o notebook

Para importar o notebook:

  1. Acesse a guia Notebooks e clique em Importar notebook de URLs.

  2. Em Origem da importação, selecione URL.

  3. Em URLs do notebook, cole o seguinte link: raw.githubusercontent.com/epam/kubernetes-engine-samples/Weaviate/databases/weaviate/manifests/02-notebook/vector-database.ipynb

  4. Clique em Importar.

Conectar-se ao ambiente de execução e executar consultas

Para se conectar ao ambiente de execução e executar consultas:

  1. No notebook, ao lado do botão Conectar, clique em Opções de conexão adicionais. O painel Conectar ao ambiente de execução da Vertex AI é exibido.

  2. Selecione Conectar a um ambiente de execução e Conectar a um ambiente de execução.

  3. Selecione o ambiente de execução iniciado e clique em Conectar.

  4. Clique no botão Executar célula à esquerda de cada célula de código para executar as células do notebook.

O notebook contém células de código e texto que descrevem cada bloco de código. A execução de uma célula de código executa os comandos e mostra uma saída. É possível executar as células em ordem ou individualmente, conforme necessário.

Para mais informações sobre o Vertex AI Colab Enterprise, consulte a documentação do Colab Enterprise.

Conferir as métricas do Prometheus para seu cluster

O cluster do GKE é configurado com o Google Cloud Managed Service para Prometheus, que permite a coleta de métricas no formato do Prometheus. Esse serviço oferece uma solução totalmente gerenciada para monitoramento e alerta, permitindo a coleta, o armazenamento e a análise de métricas do cluster e dos aplicativos dele.

O diagrama a seguir mostra como o Prometheus coleta métricas para o cluster:

Coleta de métricas do Prometheus

O cluster particular do GKE no diagrama contém os seguintes componentes:

  • Pods Weaviate que expõem métricas no caminho /metrics e na porta 2112.
  • Coletores baseados em Prometheus que processam as métricas dos pods do Weaviate.
  • Um recurso de PodMonitoring que envia métricas ao Cloud Monitoring.

Para exportar e visualizar as métricas, siga estas etapas:

  1. Crie o recurso PodMonitoring para coletar métricas por labelSelector:

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

    O manifesto pod-monitoring.yaml descreve o 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 um painel personalizado do Cloud Monitoring com as configurações definidas em dashboard.json:

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

  3. Depois que o comando for executado, acesse os Painéis do Cloud Monitoring:

    Acessar "Visão geral dos painéis"

  4. Na lista de painéis, abra o painel Weaviate Overview. A coleta e a exibição das métricas podem levar algum tempo. O painel mostra a quantidade de fragmentos, vetores e latência das operações

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Exclua o projeto

A maneira mais fácil de evitar o faturamento é excluir o projeto criado para o tutorial.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Se você tiver excluído o projeto, a limpeza estará completa. Se você não excluiu o projeto, exclua os recursos individuais.

Excluir recursos individuais

  1. Defina variáveis de ambiente.

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

  2. Execute o 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}

    Substitua FOLDER por gke-autopilot ou gke-standard, dependendo do tipo de cluster do GKE que você criou.

    Quando solicitado, digite yes.

  3. Encontre todos os discos desanexados:

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

  4. Exclua os 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. Para excluir o repositório do GitHub, faça o seguinte:

    rm -r ~/kubernetes-engine-samples/

A seguir