Implemente uma base de dados de vetores Weaviate no GKE

Autopilot Padrão

Este tutorial mostra como implementar um cluster de base de dados vetorial Weaviate no Google Kubernetes Engine (GKE).

O Weaviate é uma base de dados de vetores de código aberto com desempenho de baixa latência e suporte básico para diferentes tipos de multimédia, como texto e imagens. Suporta a pesquisa semântica, a resposta a perguntas e a classificação. O Weaviate é totalmente criado em Go e armazena objetos e vetores, o que permite a utilização da pesquisa vetorial, da pesquisa por palavras-chave e de uma combinação de ambas como uma pesquisa híbrida. Do ponto de vista da infraestrutura, o Weaviate é uma base de dados nativa da nuvem e tolerante a falhas. A tolerância a falhas é fornecida pela arquitetura sem líder, em que cada nó do cluster da base de dados pode processar pedidos de leitura e escrita, o que, por sua vez, exclui um único ponto de falha.

Este tutorial destina-se a administradores e arquitetos da plataforma na nuvem, engenheiros de ML e profissionais de MLOps (DevOps) interessados na implementação de clusters de bases de dados vetoriais no GKE.

Vantagens

O Weaviate oferece as seguintes vantagens:

• Bibliotecas para várias linguagens de programação e API aberta para integração com outros serviços.
• Escalabilidade horizontal.
• Um equilíbrio entre a rentabilidade e a velocidade das consultas, especialmente quando trabalha com grandes conjuntos de dados. Pode escolher a quantidade de dados armazenados na memória em comparação com o disco.

Objetivos

Neste tutorial, vai aprender a:

• Planeie e implemente a infraestrutura do GKE para o Weaviate.
• Implemente e configure a base de dados Weaviate num cluster do GKE.
• Execute um notebook para gerar e armazenar exemplos de incorporações de vetores na sua base de dados e execute consultas de pesquisa baseadas em vetores.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• GKE
• Google Cloud Managed Service for Prometheus

Para gerar uma estimativa de custos com base na sua utilização prevista, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Quando terminar as tarefas descritas neste documento, pode evitar a faturação contínua eliminando os recursos que criou. Para mais informações, consulte o artigo Limpe.

Antes de começar

Neste tutorial, vai usar a Cloud Shell para executar comandos. O Cloud Shell é um ambiente de shell para gerir recursos alojados no Google Cloud. É fornecido pré-instalado com as ferramentas de linha de comandos CLI do Google Cloud, kubectl, Helm e Terraform. Se não usar o Cloud Shell, tem de instalar a CLI Google Cloud.

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.

Install the Google Cloud CLI.

Nota: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

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.

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.

Verify that billing is enabled for your Google Cloud project.

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

Install the Google Cloud CLI.

Nota: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

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.

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.

Verify that billing is enabled for your Google Cloud project.

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

1. 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, [e-mail].
   • ROLE: The IAM role that you grant to your user account.

Configure o seu ambiente

Para configurar o seu ambiente com o Cloud Shell, siga estes passos:

1. Defina variáveis de ambiente para o seu projeto, 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 PROJECT_ID pelo seu Google Cloud ID do projeto.

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

2. Verifique a versão do Helm:

   helm version
   

   Atualize a versão se for anterior à 3.13:

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

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

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

4. Navegue para o diretório weaviate:

   cd kubernetes-engine-samples/databases/weaviate
   

Crie a infraestrutura do cluster

Nesta secção, executa um script do Terraform para criar um cluster do GKE regional privado e de elevada disponibilidade para implementar a sua base de dados do Weaviate.

Pode optar por implementar o Weaviate através de um cluster padrão ou do Autopilot. Cada um tem as suas próprias vantagens e modelos de preços diferentes.

Piloto automático

O diagrama seguinte mostra um cluster do GKE do Autopilot implementado no projeto.



Para implementar 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 tempo de execução:

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

Quando lhe for pedido, escreva yes.

O resultado é semelhante ao seguinte:

...
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 privada para os nós do Kubernetes.
• Um Cloud Router para aceder à Internet através da tradução de endereços de rede (NAT).
• Um cluster do GKE privado na região us-central1.
• Um ServiceAccount com autorizações de registo e monitorização para o cluster.
• Configuração do Google Cloud Managed Service for Prometheus para monitorização e alertas de clusters.

Standard

O diagrama seguinte mostra um cluster GKE regional privado padrão implementado em três zonas diferentes.



Para implementar 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 tempo de execução:

• GOOGLE_OAUTH_ACCESS_TOKEN usa o comando gcloud auth print-access-token para obter um token de acesso que autentica as interações com várias APIs Google Cloud.
• PROJECT_ID, REGION e KUBERNETES_CLUSTER_PREFIX são as variáveis de ambiente definidas na secção Configure o seu ambiente e atribuídas às novas variáveis relevantes para o cluster padrão que está a criar.

Quando lhe for pedido, escreva yes. Estes comandos podem demorar vários minutos a serem concluídos e o cluster a apresentar o estado pronto.

O resultado é semelhante ao seguinte:

...
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 privada para os nós do Kubernetes.
• Um Cloud Router para aceder à Internet através da tradução de endereços de rede (NAT).
• Um cluster do GKE privado na região us-central1 com a escala automática ativada (um a dois nós por zona).
• Um ServiceAccount com autorizações de registo e monitorização para o cluster.
• Configuração do Google Cloud Managed Service for Prometheus para monitorização e alertas de clusters.

Estabeleça ligação ao cluster

Configure o kubectl para obter credenciais e comunicar com o seu novo cluster do GKE:

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

Implemente a base de dados Weaviate no seu cluster

Para usar o gráfico Helm para implementar a base de dados Weaviate no seu cluster do GKE, siga estes passos:

1. Adicione o repositório do gráfico Helm da base de dados Weaviate antes de o poder implementar no seu cluster do GKE:

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

2. Crie o espaço de nomes weaviate para a base de dados:

   kubectl create ns weaviate
   

3. Crie um segredo para armazenar a chave da API:

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

4. Implemente um balanceador de carga interno para aceder ao Weaviate a partir da rede virtual:

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

   O manifesto ilb.yaml descreve o serviço de 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 implementar 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 implementação. Uma implementação é um objeto da API Kubernetes que lhe permite executar várias réplicas de pods distribuídos entre os nós num 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:
         - [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

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

6. Verifique o estado da implementação:

   kubectl get weaviate -n weaviate --watch
   

   O resultado é semelhante ao seguinte se a base de dados weaviate for implementada com êxito:

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

7. Aguarde que o Kubernetes inicie os recursos:

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

Execute consultas com o bloco de notas do Vertex AI Colab Enterprise

Esta secção explica como estabelecer ligação à sua base de dados Weaviate através do Colab Enterprise. Pode usar um modelo de tempo de execução dedicado para implementar no weaviate-vpc, para que o bloco de notas possa comunicar com os recursos no cluster do GKE.

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

Crie um modelo de tempo de execução

Para criar um modelo de tempo de execução do Colab Enterprise:

1. Na Google Cloud consola, aceda à página Modelos de tempo de execução do Colab Enterprise e certifique-se de que o seu projeto está selecionado:

   Aceda aos modelos do ambiente de execução

2. Clique em Novo modelo. É apresentada a página Criar novo modelo de tempo de execução.

3. Na secção Noções básicas do ambiente de execução:

   • No campo Nome a apresentar, introduza weaviate-connect.
   • Na lista pendente Região, selecione us-central1. É a mesma região que o seu cluster do GKE.

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

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

5. Na secção Redes e segurança:

   • Na lista pendente Rede, selecione a rede onde o seu cluster do GKE reside.
   • Na lista pendente Sub-rede, selecione uma sub-rede correspondente.
   • Desmarque a caixa de verificação Ativar acesso público à Internet.

6. Para concluir a criação do modelo de tempo de execução, clique em Criar. O modelo do ambiente de execução aparece na lista no separador Modelos do ambiente de execução.

Crie um tempo de execução

Para criar um tempo de execução do Colab Enterprise:

1. Na lista de modelos de tempo de execução do modelo que acabou de criar, na coluna Ações, clique em e, de seguida, clique em Criar tempo de execução. É apresentado o painel Criar tempo de execução do Vertex AI.

2. Para criar um tempo de execução com base no seu modelo, clique em Criar.

3. No separador Tempos de execução que é aberto, aguarde que o estado passe a Em bom estado.

Importe o bloco de notas

Para importar o bloco de notas no Colab Enterprise:

1. Aceda ao separador Os meus blocos de notas e clique em Importar. É apresentado o painel Importar blocos de notas.

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

3. Em URLs do notebook, introduza o seguinte link:

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

4. Clique em Importar.

Ligue-se ao tempo de execução e execute consultas

Para se ligar ao tempo de execução e executar consultas:

1. No bloco de notas, junto ao botão Associar, clique em Opções de associação adicionais. É apresentado o painel Ligar ao tempo de execução do Vertex AI.

2. Selecione Ligar a um tempo de execução e, de seguida, selecione Ligar a um tempo de execução existente.

3. Selecione o tempo de execução que iniciou e clique em Associar.

4. Para executar as células do bloco de notas, clique no botão Executar célula junto a cada célula de código.

O bloco de notas contém células de código e texto que descrevem cada bloqueio de código. A execução de uma célula de código executa os respetivos comandos e apresenta uma saída. Pode executar as células por ordem ou executar células individuais conforme necessário.

Veja as métricas do Prometheus para o seu cluster

O cluster do GKE está configurado com o serviço gerido do Google Cloud para o Prometheus, que permite a recolha de métricas no formato Prometheus. Este serviço oferece uma solução totalmente gerida para monitorização e alertas, permitindo a recolha, o armazenamento e a análise de métricas do cluster e das respetivas aplicações.

O diagrama seguinte mostra como o Prometheus recolhe métricas para o seu cluster:



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

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

Para exportar e ver as métricas, siga estes passos:

1. Crie o recurso PodMonitoring para extrair 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 de controlo do Cloud Monitoring personalizado com as configurações definidas em dashboard.json:

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

3. Depois de o comando ser executado com êxito, aceda a Cloud Monitoring Painéis de controlo:

   Aceda à vista geral dos painéis de controlo

4. Na lista de painéis de controlo, abra o painel de controlo Weaviate Overview. Pode demorar algum tempo a recolher e apresentar métricas. O painel de controlo mostra a quantidade de fragmentos, vetores e latência das operações

Limpar

Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.

Elimine o projeto

A forma mais fácil de evitar a faturação é eliminar o projeto que criou para este tutorial.

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Se eliminou o projeto, a limpeza está concluída. Se não eliminou o projeto, avance para a eliminação dos recursos individuais.

Elimine 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, consoante o tipo de cluster do GKE que criou.

   Quando lhe for pedido, escreva yes.

3. Encontre todos os discos não anexados:

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

4. Elimine 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. Elimine o repositório do GitHub:

   rm -r ~/kubernetes-engine-samples/
   

O que se segue?

• Explore o Weaviate no GKE Marketplace.
• Saiba mais sobre as práticas recomendadas para implementar bases de dados no GKE.
• Descubra soluções para executar cargas de trabalho com grande volume de dados com o GKE.