벡터 검색 빠른 시작

Vertex AI 벡터 검색 빠른 시작에서는 가상의 전자상거래 의류 사이트의 샘플 데이터 세트에서 색인을 만드는 방법을 알아봅니다. 이 빠른 시작에서는 임베딩이 이미 생성되어 있습니다. 이 빠른 시작은 30분 이내에 색인을 만들고 배포하기 시작할 수 있도록 고안되었습니다.

기본 요건

이 튜토리얼을 진행하려면 결제 계정과 연결된 Google Cloud 프로젝트가 필요합니다. 새 프로젝트를 만들려면 프로젝트 및 개발 환경 설정을 참조하세요. 프로젝트를 만들고 결제 계정을 설정해야 합니다.

런타임 환경 선택

이 튜토리얼은 Colab 또는 Vertex AI Workbench에서 실행할 수 있습니다.

Colab: Colab에서 이 튜토리얼을 엽니다.
Vertex AI Workbench: Vertex AI Workbench에서 이 튜토리얼을 엽니다. Google Cloud 프로젝트에서 Vertex AI Workbench를 처음 사용하는 경우, Google Cloud 콘솔의 Vertex AI Workbench 섹션으로 이동하여 사용 설정(Enable)을 클릭해 Notebooks API를 활성화하세요.

GitHub에서 이 노트북을 보려면 GitHub를 참조하세요.

이 빠른 시작을 완료하는 데 드는 비용

이 튜토리얼을 완료하는 데 대략 몇 달러(USD)의 비용이 발생합니다. 이 튜토리얼에서 사용되는 Google Cloud 서비스 가격은 다음 페이지에서 확인할 수 있습니다.

가격 계산기를 사용하여 예상 사용량을 기준으로 예상 비용을 산출할 수도 있습니다.

설정

Vertex AI를 시작하기 전에 다음을 설정해야 합니다.

Vertex AI SDK for Python 설치
환경 변수 설정하기
인증(Colab만 해당)
IAM 권한 설정
API 사용 설정

Vertex AI SDK for Python 설치

Vertex AI 및 Cloud Storage API는 REST API, Vertex AI SDK for Python 등 다양한 방법으로 액세스할 수 있습니다. 이 튜토리얼에서는 Vertex AI SDK for Python이 사용됩니다.

!pip install --upgrade --user google-cloud-aiplatform>=1.29.0 google-cloud-storage

이 Jupyter 런타임에 새로 설치된 패키지를 사용하려면 다음 코드 스니펫에 표시된 것처럼 런타임을 다시 시작해야 합니다.

# Restart kernel after installs so that your environment can access the new packages
import IPython

app = IPython.Application.instance()
app.kernel.do_shutdown(True)

환경 변수

환경 변수를 설정하세요. 요청이 있으면 your-project-id를 프로젝트 ID로 바꾸고 셀을 실행합니다.

# get project ID
PROJECT_ID = ! gcloud config get-value project
PROJECT_ID = PROJECT_ID[0]
LOCATION = "us-central1"
if PROJECT_ID == "(unset)":
    print(f"Please set the project ID manually below")

# define project information
if PROJECT_ID == "(unset)":
  PROJECT_ID = "[your-project-id]"

# generate a unique id for this session
from datetime import datetime
UID = datetime.now().strftime("%m%d%H%M")

인증(Colab만 해당)

Colab에서 이 노트북을 실행하는 경우에는 다음 셀 인증을 실행해야 합니다. Vertex AI Workbench를 사용하는 경우 사전 인증되었으므로 이 단계는 필요하지 않습니다.

import sys

# if it's Colab runtime, authenticate the user with Google Cloud
if 'google.colab' in sys.modules:
    from google.colab import auth
    auth.authenticate_user()

IAM 권한 설정

서비스를 사용하려면 기본 서비스 계정에 액세스 권한을 추가해야 합니다.

Google Cloud 콘솔에서 IAM 페이지로 이동합니다.
기본 컴퓨팅 서비스 계정의 주 구성원을 찾습니다. 다음과 같이 표시됩니다. compute@developer.gserviceaccount.com
수정 버튼을 클릭하고 기본 컴퓨팅 서비스 계정에 Vertex AI 사용자, 스토리지 관리자, 서비스 사용량 관리자 역할을 부여합니다.

API 사용 설정

이 Google Cloud 프로젝트로 Compute Engine, Vertex AI, Cloud Storage용 API를 사용 설정하려면 다음 명령어를 실행합니다.

! gcloud services enable compute.googleapis.com aiplatform.googleapis.com storage.googleapis.com --project {PROJECT_ID}

샘플 데이터 준비

이 튜토리얼에서는 가상의 전자상거래 의류 사이트의 합성 제품 데이터로 약 30,000개의 행이 포함된 제품 테이블이 있는 TheLook 데이터 세트를 사용합니다.

이 테이블에서는 product-embs.json 파일을 준비했습니다.

이 파일은 JSONL 형식이며 각 행에는 제품 ID의 ID, 제품 이름의 이름, 이전에 텍스트용 Vertex AI 임베딩으로 생성된 768차원의 제품 이름 임베딩에 대한 임베딩이 있습니다.

텍스트 임베딩은 의류 제품 이름의 의미를 나타냅니다. 이 튜토리얼에서는 벡터 검색을 사용하여 항목의 시맨틱 검색을 완료합니다. 이 샘플 코드는 '이 제품과 유사한 다른 제품'을 빠르게 찾을 수 있는 다른 빠른 추천 시스템의 기반으로 사용될 수 있습니다.

BigQuery 테이블의 데이터에서 임베딩을 만들어 JSON 파일에 저장하는 방법을 자세히 알아보려면 텍스트 임베딩 + Vertex AI 벡터 검색 시작하기를 참조하세요.

Cloud Storage에서 데이터 준비

Vertex AI로 색인을 빌드하려면 임베딩 파일을 Cloud Storage 버킷에 배치합니다. 다음 코드는 두 가지 작업을 완료합니다.

Cloud Storage 버킷을 만듭니다.
예시 파일을 Cloud Storage 버킷에 복사합니다.

BUCKET_URI = f"gs://{PROJECT_ID}-vs-quickstart-{UID}"

! gcloud storage buckets create $BUCKET_URI --location=$LOCATION --project=$PROJECT_ID
! gcloud storage cp "gs://github-repo/data/vs-quickstart/product-embs.json" $BUCKET_URI

또한 벡터 검색을 사용하여 쿼리를 실행하려면 임베딩 파일을 로컬 디렉터리에 복사해야 합니다.

! gcloud storage cp "gs://github-repo/data/vs-quickstart/product-embs.json" . # for query tests

벡터 검색 색인 빌드 및 배포

색인을 만들고 색인 엔드포인트를 만든 다음 색인을 엔드포인트에 배포하는 방법을 알아보세요.

색인 만들기

이제 임베딩을 벡터 검색에 로드할 차례입니다. API는 SDK의 aiplatform 패키지에서 제공됩니다.

# init the aiplatform package
from google.cloud import aiplatform
aiplatform.init(project=PROJECT_ID, location=LOCATION)

create_tree_ah_index 함수로 MatchingEngineIndex를 만듭니다. Matching Engine은 백터 검색의 이전 이름입니다.

# create Index
my_index = aiplatform.MatchingEngineIndex.create_tree_ah_index(
    display_name = f"vs-quickstart-index-{UID}",
    contents_delta_uri = BUCKET_URI,
    dimensions = 768,
    approximate_neighbors_count = 10,
)

MatchingEngineIndex.create_tree_ah_index() 메서드는 색인을 빌드합니다. 데이터 세트가 작으면 10분 미만, 그렇지 않으면 데이터 세트 크기에 따라 약 60분 이상이 소요됩니다. 백터 검색 Google Cloud 콘솔에서 색인 생성 상태를 확인할 수 있습니다.

색인 보기

색인을 만들기 위한 매개변수:

contents_delta_uri: 임베딩 JSON 파일을 저장한 Cloud Storage 디렉터리의 URI
dimensions: 각 임베딩의 차원 크기. 이 경우 텍스트 임베딩 API의 임베딩을 사용하므로 768입니다.
approximate_neighbors_count: 일반적인 경우에 검색하려는 유사 항목 수

색인 생성 및 사용 가능한 매개변수에 대해 자세히 알아보려면 색인 생성 및 관리를 참조하세요.

색인 엔드포인트 만들기 및 색인 배포

색인을 사용하려면 색인 엔드포인트를 만들어야 합니다. 색인 쿼리 요청을 수락하는 서버 인스턴스 역할을 합니다.

## create `IndexEndpoint`
my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint.create(
    display_name = f"vs-quickstart-index-endpoint-{UID}",
    public_endpoint_enabled = True
)

색인 엔드포인트에서 배포된 고유 색인 ID를 지정하여 색인을 배포합니다.

DEPLOYED_INDEX_ID = f"vs_quickstart_deployed_{UID}"

# deploy the Index to the Index Endpoint
my_index_endpoint.deploy_index(
    index = my_index, deployed_index_id = DEPLOYED_INDEX_ID
)

이 색인을 색인 엔드포인트에 처음 배포하는 경우 백엔드를 자동으로 빌드하고 시작하는 데 약 30분 정도 걸릴 수 있습니다. 색인 배포 상태를 보려면 Google Cloud 콘솔의 Vertex AI 섹션에서 배포 및 사용 섹션으로 이동합니다. 색인을 선택합니다.

색인 보기

벡터 검색으로 쿼리 실행

다음 코드에서는 지정된 제품 이름의 임베딩을 찾고 벡터 검색으로 유사한 제품 이름을 찾습니다.

쿼리 실행을 위한 임베딩 가져오기

먼저 임베딩 JSON 파일을 로드하여 제품 이름 및 임베딩의 dict를 빌드하세요.

import json

# build dicts for product names and embs
product_names = {}
product_embs = {}
with open('product-embs.json') as f:
    for l in f.readlines():
        p = json.loads(l)
        id = p['id']
        product_names[id] = p['name']
        product_embs[id] = p['embedding']

product_embs 딕셔너리를 사용하면 제품 ID를 지정하여 임베딩을 가져올 수 있습니다.

 # Get the embedding for ID 6523 "cloudveil women's excursion short"
 # You can also try with other IDs such as 12711, 18090, 19536 and 11863
query_emb = product_embs['6523']

쿼리 실행

임베딩을 Endpoint.find_neighbors() 메서드에 전달하여 유사한 제품 이름을 찾습니다.

# run query
response = my_index_endpoint.find_neighbors(
    deployed_index_id = DEPLOYED_INDEX_ID,
    queries = [query_emb],
    num_neighbors = 10
)

# show the results
for idx, neighbor in enumerate(response[0]):
    print(f"{neighbor.distance:.2f} {product_names[neighbor.id]}")

find_neighbors() 메서드는 ScaNN 알고리즘 덕분에 색인에 항목이 수십억 개 있더라도 유사한 항목을 가져오는 데 몇 밀리초밖에 걸리지 않습니다. 또한 벡터 검색은 워크로드 수요에 따라 노드 수를 자동으로 조정할 수 있는 자동 확장을 지원합니다.

삭제

Qwiklab의 임시 프로젝트가 아닌 자체 Cloud 프로젝트를 사용하는 경우 이 튜토리얼을 완료한 후에 모든 색인, 색인 엔드포인트, Cloud Storage 버킷을 삭제해야 합니다. 그렇지 않으면 남아있는 리소스에서 예기치 않은 비용이 발생할 수 있습니다.

Workbench를 사용한 경우 콘솔에서 노트북을 삭제해야 할 수도 있습니다.


# wait for a confirmation
input("Press Enter to delete Index Endpoint, Index and Cloud Storage bucket:")

# delete Index Endpoint
my_index_endpoint.undeploy_all()
my_index_endpoint.delete(force = True)

# delete Index
my_index.delete()

# delete Cloud Storage bucket
! gcloud storage rm {BUCKET_URI} --recursive

유틸리티

색인을 만들거나 배포하는 데 시간이 걸릴 수 있으며 이 경우 Colab 런타임과의 연결이 끊어질 수 있습니다. 연결이 끊어지면 새 색인을 다시 만들거나 배포하는 대신 벡터 검색 Google Cloud 콘솔을 확인하고 기존 색인을 사용하여 계속 진행할 수 있습니다.

기존 색인 가져오기

이미 존재하는 색인 객체를 가져오려면 다음 your-index-id를 색인 ID로 바꾸고 셀을 실행합니다. 벡터 검색 Google Cloud 콘솔을 확인하여 색인 ID를 가져올 수 있습니다. Google Cloud 콘솔의 Vertex AI 섹션에서 배포 및 사용 섹션으로 이동합니다. 색인을 선택합니다.

색인 보기

my_index_id = "[your-index-id]"
my_index = aiplatform.MatchingEngineIndex(my_index_id)

기존 색인 엔드포인트 가져오기

이미 존재하는 색인 엔드포인트 객체를 가져오려면 다음 your-index-endpoint-id를 색인 엔드포인트 ID로 바꾸고 셀을 실행합니다. 벡터 검색 Google Cloud 콘솔을 확인하여 색인 엔드포인트를 가져올 수 있습니다. Google Cloud 콘솔의 Vertex AI 섹션에서 배포 및 사용 섹션으로 이동합니다. 색인 엔드포인트를 선택합니다.

색인 엔드포인트 보기

my_index_endpoint_id = "[your-index-endpoint-id]"
my_index_endpoint = aiplatform.MatchingEngineIndexEndpoint(my_index_endpoint_id)