GKE에 Weaviate 벡터 데이터베이스를 배포합니다.

Autopilot Standard

이 튜토리얼에서는 Google Kubernetes Engine(GKE)에 Weaviate 벡터 데이터베이스 클러스터를 배포하는 방법을 보여줍니다.

Weaviate는 지연 시간이 짧은 성능과 텍스트 및 이미지와 같은 다양한 미디어 유형에 대한 기본 지원을 제공하는 오픈소스 벡터 데이터베이스입니다. 의미 검색, 질의 응답, 분류를 지원합니다. Weaviate는 Go를 기반으로 완전히 빌드되었으며 객체와 벡터를 모두 저장하므로 벡터 검색, 키워드 검색, 이 둘의 조합을 하이브리드 검색으로 사용할 수 있습니다. 인프라 관점에서 Weaviate는 클라우드 네이티브 및 내결함성 데이터베이스입니다. 내결함성은 데이터베이스 클러스터의 각 노드가 단일 장애점을 제외하는 읽기 및 쓰기 요청을 처리할 수 있는 리더 없는 아키텍처에 의해 제공됩니다.

이 튜토리얼은 GKE에서 벡터 데이터베이스 클러스터를 배포하는 데 관심이 있는 클라우드 플랫폼 관리자 및 설계자, ML 엔지니어, MLOps(DevOps) 전문가를 대상으로 합니다.

이점

Weaviate는 다음과 같은 이점을 제공합니다.

다양한 프로그래밍 언어를 위한 라이브러리와 다른 서비스와 통합하기 위한 개방형 API
수평 확장
특히 대규모 데이터 세트를 처리할 때 비용 효율성과 쿼리 속도 간의 균형. 메모리와 디스크에 저장되는 데이터의 양을 선택할 수 있습니다.

목표

이 튜토리얼에서는 다음을 수행하는 방법을 알아봅니다.

Weaviate용 GKE 인프라를 계획하고 배포합니다.
GKE 클러스터에 Weaviate 데이터베이스를 배포하고 구성합니다.
노트북을 실행하여 데이터베이스 내에 예시 벡터 임베딩을 생성하고 저장하고 벡터 기반 검색 쿼리를 실행합니다.

비용

이 문서에서는 비용이 청구될 수 있는 다음과 같은 Google Cloud 구성요소를 사용합니다.

프로젝트 사용량을 기준으로 예상 비용을 산출하려면 가격 계산기를 사용하세요. Google Cloud를 처음 사용하는 사용자는 무료 체험판을 사용할 수 있습니다.

이 문서에 설명된 태스크를 완료했으면 만든 리소스를 삭제하여 청구가 계속되는 것을 방지할 수 있습니다. 자세한 내용은 삭제를 참조하세요.

시작하기 전에

이 튜토리얼에서는 Cloud Shell을 사용하여 명령어를 실행합니다. Cloud Shell은 Google Cloud에서 호스팅되는 리소스를 관리하는 데 사용되는 셸 환경입니다. Google Cloud CLI, kubectl, Helm, Terraform 명령줄 도구가 사전에 설치되어 있습니다. Cloud Shell을 사용하지 않는 경우에는 Google Cloud CLI를 설치해야 합니다.

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.

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

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.

Make sure that billing is enabled for your Google Cloud project.

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

Install the Google Cloud CLI.

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

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.

Make sure that billing is enabled for your Google Cloud project.

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

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:myemail@example.com.
- Replace ROLE with each individual role.

환경 설정

Cloud Shell로 환경을 설정하려면 다음 단계를 따르세요.

프로젝트, 리전, Kubernetes 클러스터 리소스 프리픽스의 환경 변수를 설정합니다.
```
export PROJECT_ID=PROJECT_ID
export KUBERNETES_CLUSTER_PREFIX=weaviate
export REGION=us-central1
```
PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.

이 튜토리얼에서는 us-central1 리전을 사용하여 배포 리소스를 만듭니다.

Helm의 버전을 확인합니다.

helm version

3.13 이전인 경우 버전을 업데이트합니다.

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

GitHub에서 샘플 코드 저장소를 클론합니다.

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

weaviate 디렉터리로 이동합니다.

cd kubernetes-engine-samples/databases/weaviate

클러스터 인프라 만들기

이 섹션에서는 Terraform 스크립트를 실행하여 가용성이 높은 비공개 리전 GKE 클러스터를 만들어 Weaviate 데이터베이스를 배포합니다.

Standard 또는 Autopilot 클러스터를 사용하여 Weaviate를 배포할 수 있습니다. 각 유형은 고유한 장점이 있으며 서로 다른 가격 책정 모델을 제공합니다.

Autopilot

다음 다이어그램에서는 프로젝트에 배포된 Autopilot GKE 클러스터를 보여줍니다.

GKE Autopilot 클러스터

클러스터 인프라를 배포하려면 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는 런타임 시 다음 변수를 바꿉니다.

GOOGLE_OAUTH_ACCESS_TOKEN은 gcloud auth print-access-token 명령어를 사용하여 다양한 Google Cloud API와의 상호작용을 인증하는 액세스 토큰을 검색합니다.
PROJECT_ID, REGION, KUBERNETES_CLUSTER_PREFIX는 환경 설정 섹션에 정의된 환경 변수이며 생성 중인 Autopilot 클러스터의 새 관련 변수에 할당됩니다.

메시지가 표시되면 yes를 입력합니다.

출력은 다음과 비슷합니다.

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

Outputs:

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

Terraform에서 다음 리소스를 만듭니다.

Kubernetes 노드의 커스텀 VPC 네트워크 및 비공개 서브넷
네트워크 주소 변환(NAT)을 통해 인터넷에 액세스하는 Cloud Router
us-central1 리전의 비공개 GKE 클러스터
클러스터에 대한 로깅 및 모니터링 권한이 있는 ServiceAccount
클러스터 모니터링 및 알림을 위한 Google Cloud Managed Service for Prometheus 구성

표준

다음 다이어그램에서는 서로 다른 영역 3개에 배포된 Standard 비공개 리전 GKE 클러스터를 보여줍니다.

GKE Standard 클러스터

클러스터 인프라를 배포하려면 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는 런타임 시 다음 변수를 바꿉니다.

GOOGLE_OAUTH_ACCESS_TOKEN은 gcloud auth print-access-token 명령어를 사용하여 다양한 Google Cloud API와의 상호작용을 인증하는 액세스 토큰을 검색합니다.
PROJECT_ID, REGION, KUBERNETES_CLUSTER_PREFIX는 환경 설정 섹션에 정의된 환경 변수이며 만든 Standard 클러스터의 새 관련 변수에 할당됩니다.

메시지가 표시되면 yes를 입력합니다. 이러한 명령어가 완료되고 클러스터에 준비 상태가 표시되는 데 몇 분 정도 걸릴 수 있습니다.

출력은 다음과 비슷합니다.

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

Outputs:

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

Terraform에서 다음 리소스를 만듭니다.

Kubernetes 노드의 커스텀 VPC 네트워크 및 비공개 서브넷
네트워크 주소 변환(NAT)을 통해 인터넷에 액세스하는 Cloud Router
자동 확장이 사용 설정된 us-central1 리전의 비공개 GKE 클러스터(영역당 노드 1~2개)
클러스터에 대한 로깅 및 모니터링 권한이 있는 ServiceAccount
클러스터 모니터링 및 알림을 위한 Google Cloud Managed Service for Prometheus 구성

클러스터에 연결

사용자 인증 정보를 가져오고 새 GKE 클러스터와 통신하도록 kubectl을 구성합니다.

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

클러스터에 Weaviate 데이터베이스 배포

Helm 차트를 사용하여 Weaviate 데이터베이스를 GKE 클러스터에 배포하려면 다음 단계를 수행합니다.

GKE 클러스터에 배포하기 전에 Weaviate 데이터베이스 Helm 차트 저장소를 추가합니다.
```
helm repo add weaviate https://weaviate.github.io/weaviate-helm
```
데이터베이스의 네임스페이스 weaviate을 만듭니다.
```
kubectl create ns weaviate
```

API 키를 저장할 보안 비밀을 만듭니다.

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

내부 부하 분산기를 배포하여 가상 네트워크 내에서 Weaviate에 액세스합니다.

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

ilb.yaml 매니페스트는 부하 분산기 서비스를 설명합니다.

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

매니페스트를 적용하여 Weaviate 클러스터를 배포합니다.

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

weaviate_cluster.yaml 매니페스트는 배포를 설명합니다.

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

Weaviate 클러스터가 완전히 시작될 때까지 몇 분 정도 기다립니다.

배포 상태를 확인합니다.

kubectl get weaviate -n weaviate --watch

weaviate 데이터베이스가 성공적으로 배포되면 출력은 다음과 비슷합니다.

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

Kubernetes에서 리소스를 시작할 때까지 기다립니다.

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

Vertex AI Colab Enterprise 노트북으로 쿼리 실행

이 섹션에서는 Colab Enterprise를 사용하여 Weaviate 데이터베이스에 연결하는 방법을 설명합니다. 전용 런타임 템플릿을 사용하여 weaviate-vpc에 배포하면 노트북이 GKE 클러스터의 리소스와 통신할 수 있습니다.

런타임 템플릿 만들기

런타임 템플릿을 만들려면 다음 안내를 따르세요.

Google Cloud 콘솔에서 Colab Enterprise 런타임 템플릿 페이지로 이동하여 프로젝트가 선택되어 있는지 확인합니다.

런타임 템플릿으로 이동
새 템플릿을 클릭합니다. 새 런타임 템플릿 만들기 페이지가 나타납니다.
런타임 기본사항 섹션에서 다음을 수행합니다.
- 표시 이름 필드에 weaviate-connect을 입력합니다.
- 리전 드롭다운 목록에서 us-central1을 선택합니다. GKE 클러스터와 동일한 리전입니다.
컴퓨팅 구성 섹션에서 다음을 수행합니다.
- 머신 유형 드롭다운 목록에서 e2-standard-2를 선택합니다.
- 디스크 크기 필드에 30을 입력합니다.
네트워킹 및 보안 섹션에서 다음을 수행합니다.
- 네트워크 드롭다운 목록에서 GKE 클러스터가 상주하는 네트워크를 선택합니다.
- 서브네트워크 드롭다운 목록에서 해당 서브네트워크를 선택합니다.
- 공개 인터넷 액세스 사용 설정 체크박스를 선택 취소합니다.
만들기를 클릭하여 런타임 템플릿 만들기를 마칩니다. 런타임 템플릿이 런타임 템플릿 탭의 목록에 나타납니다.

런타임 만들기

런타임을 만들려면 다음 단계를 따르세요.

런타임 템플릿 목록에서 방금 만든 템플릿의 작업 열에서 를 클릭한 다음 런타임 만들기를 클릭합니다. Vertex AI 런타임 만들기 창이 나타납니다.
만들기를 클릭하여 템플릿을 기반으로 런타임을 만듭니다.
열리는 런타임 탭에서 상태가 정상으로 전환될 때까지 기다립니다.

노트북 가져오기

노트북을 가져오려면 다음 안내를 따르세요.

노트북 탭으로 이동하여 URL에서 노트북 가져오기를 클릭합니다.
소스 가져오기에서 URL을 선택합니다.
노트북 URL 아래에 다음 링크를 붙여넣습니다. raw.githubusercontent.com/epam/kubernetes-engine-samples/Weaviate/databases/weaviate/manifests/02-notebook/vector-database.ipynb
가져오기를 클릭합니다.

런타임에 연결하고 쿼리 실행

런타임에 연결하고 쿼리를 실행하려면 다음 안내를 따르세요.

노트북에서 연결 버튼 옆에 있는 추가 연결 옵션을 클릭합니다. Vertex AI 런타임에 연결 창이 나타납니다.
런타임에 연결을 선택한 후 기존 런타임에 연결을 선택합니다.
시작한 런타임을 선택하고 연결을 클릭합니다.
각 코드 셀 왼쪽에 있는 셀 실행 버튼을 클릭하여 노트북 셀을 실행합니다.

노트북에는 각 코드 블록을 설명하는 코드 셀과 텍스트가 포함됩니다. 코드 셀을 실행하면 명령어가 실행되고 출력이 표시됩니다. 셀을 순서대로 실행하거나 필요에 따라 개별 셀을 실행할 수 있습니다.

Vertex AI Colab Enterprise에 대한 자세한 내용은 Colab Enterprise 문서를 참조하세요.

클러스터의 Prometheus 측정항목 보기

GKE 클러스터는 Prometheus 형식으로 측정항목을 수집할 수 있는 Google Cloud Managed Service for Prometheus로 구성됩니다. 이 서비스는 모니터링 및 알림을 위한 완전 관리형 솔루션을 제공하여 클러스터 및 해당 애플리케이션에서 측정항목을 수집, 저장, 분석할 수 있습니다.

다음 다이어그램은 Prometheus가 클러스터에 대해 측정항목을 수집하는 방법을 보여줍니다.

Prometheus 측정항목 수집

다이어그램의 GKE 비공개 클러스터에는 다음 구성요소가 포함됩니다.

경로 /metrics 및 포트 2112에서 측정항목을 노출하는 Weaviate 포드
Weaviate 포드의 측정항목을 처리하는 Prometheus 기반 수집기
Cloud Monitoring으로 측정항목을 전송하는 PodMonitoring 리소스

측정항목을 내보내고 보려면 다음 단계를 따르세요.

labelSelector로 측정항목을 스크래핑하도록 PodMonitoring 리소스를 만듭니다.

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

pod-monitoring.yaml 매니페스트는 PodMonitoring 리소스를 설명합니다.

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

dashboard.json에 정의된 구성으로 커스텀 Cloud Monitoring 대시보드를 가져오려면 다음 단계를 따르세요.
```
gcloud --project "${PROJECT_ID}" monitoring dashboards create --config-from-file monitoring/dashboard.json
```
명령어가 성공적으로 실행되면 Cloud Monitoring 대시보드로 이동합니다.

대시보드 개요로 이동
대시보드 목록에서 Weaviate Overview 대시보드를 엽니다. 측정항목을 수집하고 표시하는 데 다소 시간이 걸릴 수 있습니다. 대시보드에는 샤드, 벡터, 작업 지연 시간의 양이 표시됩니다.

삭제

이 튜토리얼에서 사용된 리소스 비용이 Google Cloud 계정에 청구되지 않도록 하려면 리소스가 포함된 프로젝트를 삭제하거나 프로젝트를 유지하고 개별 리소스를 삭제하세요.

프로젝트 삭제

청구되지 않도록 하는 가장 쉬운 방법은 튜토리얼에서 만든 프로젝트를 삭제하는 것입니다.

주의: 프로젝트를 삭제하면 다음과 같은 효과가 발생합니다.

프로젝트의 모든 항목이 삭제됩니다. 이 문서의 태스크에 기존 프로젝트를 사용한 경우 프로젝트를 삭제하면 프로젝트에서 수행한 다른 작업도 삭제됩니다.
커스텀 프로젝트 ID가 손실됩니다. 이 프로젝트를 만들 때 앞으로 사용할 커스텀 프로젝트 ID를 만들었을 수 있습니다. appspot.com URL과 같이 프로젝트 ID를 사용하는 URL을 보존하려면 전체 프로젝트를 삭제하는 대신 프로젝트 내에서 선택한 리소스만 삭제합니다.

여러 아키텍처, 튜토리얼, 빠른 시작을 살펴보려는 경우 프로젝트를 재사용하면 프로젝트 할당량 한도 초과를 방지할 수 있습니다.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

프로젝트를 삭제하면 정리가 완료됩니다. 프로젝트를 삭제하지 않은 경우 개별 리소스 삭제를 진행합니다.

개별 리소스 삭제

환경 변수를 설정합니다.

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

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}

생성한 GKE 클러스터 유형에 따라 FOLDER를 gke-autopilot 또는 gke-standard로 바꿉니다.

메시지가 표시되면 yes를 입력합니다.

연결되지 않은 모든 디스크를 찾습니다.

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

디스크를 삭제합니다.

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

GitHub 저장소를 삭제합니다.
```
rm -r ~/kubernetes-engine-samples/
```

다음 단계

GKE Marketplace의 Weaviate 살펴보기
GKE의 데이터베이스 배포 권장사항 알아보기
GKE를 사용하여 데이터 집약적인 워크로드를 실행하기 위한 솔루션 살펴보기