AlloyDB에서 생성형 AI 및 에이전트 애플리케이션용 Toolbox 설치 및 설정

1. 개요

데이터베이스용 생성형 AI 도구 상자는 데이터베이스와 상호작용하는 생성형 AI 도구를 더 쉽게 빌드할 수 있는 Google의 오픈소스 서버입니다. 이를 통해 연결 풀링, 인증 등의 복잡성을 처리하여 도구를 더 쉽고 빠르고 안전하게 개발할 수 있습니다. 상담사가 데이터베이스의 데이터에 액세스할 수 있는 생성형 AI 도구를 빌드하는 데 도움이 됩니다. Toolbox는 다음을 제공합니다.

간소화된 개발: 10줄 미만의 코드로 도구를 상담사에게 통합하고, 여러 상담사 또는 프레임워크 간에 도구를 재사용하며, 새 버전의 도구를 더 쉽게 배포할 수 있습니다.

성능 개선: 연결 풀링, 인증 등 권장사항

보안 강화: 통합 인증을 통해 데이터에 더 안전하게 액세스할 수 있습니다.

엔드 투 엔드 관측 가능성: OpenTelemetry를 기본적으로 지원하는 즉시 사용 가능한 측정항목 및 추적

Toolbox는 애플리케이션의 오케스트레이션 프레임워크와 데이터베이스 사이에 있으며 도구를 수정, 배포 또는 호출하는 데 사용되는 제어 영역을 제공합니다. 도구를 저장하고 업데이트할 수 있는 중앙 위치를 제공하여 도구 관리를 간소화하므로 상담사와 애플리케이션 간에 도구를 공유하고 애플리케이션을 다시 배포하지 않고도 이러한 도구를 업데이트할 수 있습니다.

빌드할 항목

이 실습에서는 도구를 사용하여 상담사 또는 생성형 AI 애플리케이션에서 호출할 수 있는 간단한 데이터베이스 (AlloyDB) 쿼리를 실행하는 애플리케이션을 빌드합니다. 이렇게 하려면

  1. Toolbox 설치
  2. Toolbox 서버에서 AlloyDB에서 작업을 실행하도록 설계된 도구 설정
  3. Cloud Run에 Toolbox 배포
  4. 배포된 Cloud Run 엔드포인트로 도구 테스트
  5. Toolbox를 호출하는 Cloud Run 함수 빌드

요구사항

  • 브라우저(Chrome 또는 Firefox 등)
  • 결제가 사용 설정된 Google Cloud 프로젝트 (다음 섹션의 단계 참고)

2. 시작하기 전에

프로젝트 만들기

  1. Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
  2. Cloud 프로젝트에 결제가 사용 설정되어 있어야 하므로 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요.
  3. Google Cloud에서 실행되는 명령줄 환경인 Cloud Shell을 사용합니다. Google Cloud 콘솔 상단에서 Cloud Shell 활성화를 클릭합니다.

Cloud Shell 활성화 버튼 이미지

  1. Cloud Shell에 연결되면 다음 명령어를 사용하여 이미 인증되었는지, 프로젝트가 올바른 프로젝트 ID로 설정되어 있는지 확인합니다.
gcloud auth list
  1. Cloud Shell에서 다음 명령어를 실행하여 gcloud 명령어가 프로젝트를 알고 있는지 확인합니다.
gcloud config list project
  1. 프로젝트가 설정되지 않은 경우 다음 명령어를 사용하여 설정합니다.
gcloud config set project <YOUR_PROJECT_ID>
  1. Cloud Shell 터미널에서 다음 명령어를 하나씩 실행하여 필수 API를 사용 설정합니다.

아래를 실행하는 단일 명령어도 있지만 무료 체험판 계정 사용자인 경우 일괄 사용 설정 시 할당량 문제가 발생할 수 있습니다. 따라서 명령어는 한 줄에 하나씩 표시됩니다.

gcloud services enable alloydb.googleapis.com
gcloud services enable compute.googleapis.com 
gcloud services enable cloudresourcemanager.googleapis.com 
gcloud services enable servicenetworking.googleapis.com 
gcloud services enable run.googleapis.com 
gcloud services enable cloudbuild.googleapis.com 
gcloud services enable cloudfunctions.googleapis.com 
gcloud services enable aiplatform.googleapis.com

gcloud 명령어의 대안은 각 제품을 검색하거나 이 링크를 사용하여 콘솔을 통하는 방법입니다.

누락된 API가 있으면 구현 과정에서 언제든지 사용 설정할 수 있습니다.

gcloud 명령어 및 사용법은 문서를 참조하세요.

3. 데이터베이스 설정

이 실습에서는 소매 데이터를 보관할 데이터베이스로 AlloyDB를 사용합니다. 클러스터를 사용하여 데이터베이스 및 로그와 같은 모든 리소스를 보관합니다. 각 클러스터에는 데이터에 대한 액세스 포인트를 제공하는 기본 인스턴스가 있습니다. 테이블에는 실제 데이터가 포함됩니다.

전자상거래 데이터 세트가 로드될 AlloyDB 클러스터, 인스턴스, 테이블을 만들어 보겠습니다.

클러스터 및 인스턴스 만들기

  1. Cloud 콘솔에서 AlloyDB 페이지로 이동합니다.

Cloud Console에서 대부분의 페이지를 찾는 가장 쉬운 방법은 콘솔의 검색창을 사용하는 것입니다.

  1. 이 페이지에서 '클러스터 만들기'를 선택합니다.

f76ff480c8c889aa.png

  1. 아래와 같은 화면이 표시됩니다. 다음 값으로 클러스터 및 인스턴스를 만듭니다 (저장소에서 애플리케이션 코드를 클론하는 경우 값이 일치하는지 확인).
  • 클러스터 ID: 'vector-cluster'
  • 비밀번호: "alloydb"
  • PostgreSQL 15 호환
  • 지역: 'us-central1'
  • 네트워킹: 'default'

538dba58908162fb.png

  1. 기본 네트워크를 선택하면 아래와 같은 화면이 표시됩니다. '연결 설정'을 선택합니다.
    7939bbb6802a91bf.png
  2. 여기에서 '자동으로 할당된 IP 범위 사용'을 선택하고 계속합니다. 정보를 검토한 후 '연결 만들기'를 선택합니다. 768ff5210e79676f.png
  3. 네트워크가 설정되면 클러스터를 계속 만들 수 있습니다. '클러스터 만들기'를 클릭하여 아래와 같이 클러스터 설정을 완료합니다.

e06623e55195e16e.png

인스턴스 ID를 '로 변경해야 합니다.

vector-instance"

.

클러스터를 만드는 데 약 10분이 소요됩니다. 완료되면 방금 만든 클러스터의 개요를 보여주는 화면이 표시됩니다.

4. 데이터 수집

이제 매장 데이터가 포함된 표를 추가하겠습니다. AlloyDB로 이동하여 기본 클러스터를 선택한 다음 AlloyDB Studio를 선택합니다.

847e35f1bf8a8bd8.png

인스턴스 생성이 완료될 때까지 기다려야 할 수 있습니다. 완료되면 클러스터 생성 중에 만든 사용자 인증 정보를 사용하여 AlloyDB에 로그인합니다. PostgreSQL에 인증할 때 다음 데이터를 사용하세요.

  • 사용자 이름 : 'postgres'
  • 데이터베이스 : 'postgres'
  • 비밀번호 : 'alloydb'

AlloyDB 스튜디오에 성공적으로 인증하면 편집기에 SQL 명령어를 입력할 수 있습니다. 마지막 창 오른쪽에 있는 더하기 기호를 사용하여 여러 편집기 창을 추가할 수 있습니다.

91a86d9469d499c4.png

필요에 따라 실행, 형식 지정, 지우기 옵션을 사용하여 편집기 창에 AlloyDB 명령어를 입력할 수 있습니다.

확장 프로그램 사용 설정

이 앱을 빌드하는 데 pgvector 및 google_ml_integration 확장 프로그램을 사용합니다. pgvector 확장 프로그램을 사용하면 벡터 임베딩을 저장하고 검색할 수 있습니다. google_ml_integration 확장 프로그램은 Vertex AI 예측 엔드포인트에 액세스하여 SQL로 예측을 가져오는 데 사용하는 함수를 제공합니다. 다음 DDL을 실행하여 이러한 확장 프로그램을 사용 설정합니다.

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;

데이터베이스에서 사용 설정된 확장 프로그램을 확인하려면 다음 SQL 명령어를 실행합니다.

select extname, extversion from pg_extension;

테이블 만들기

아래 DDL 문을 사용하여 테이블을 만듭니다.

CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;

위 명령어를 실행하면 데이터베이스에서 테이블을 볼 수 있습니다.

데이터 수집

이 실습에서는 이 SQL 파일에 약 72개의 레코드로 구성된 테스트 데이터가 있습니다. 여기에는 id, name, description, quantity, price, image_url 필드가 포함됩니다. 나머지 필드는 실습 후반부에서 입력합니다.

여기에서 줄/삽입 문을 복사한 다음 빈 편집기 탭에 해당 줄을 붙여넣고 실행을 선택합니다.

테이블 콘텐츠를 보려면 탐색기 섹션을 펼쳐 apparels라는 테이블이 표시될 때까지 펼칩니다. 테이블을 쿼리하는 옵션을 보려면 삼중 콜론 (⋮)을 선택합니다. 새 편집기 탭에 SELECT 문장이 열립니다.

cfaa52b717f9aaed.png

권한 부여

아래 문을 실행하여 embedding 함수에 대한 실행 권한을 사용자 postgres에게 부여합니다.

GRANT EXECUTE ON FUNCTION embedding TO postgres;

AlloyDB 서비스 계정에 Vertex AI 사용자 역할을 부여합니다.

Cloud Shell 터미널로 이동하여 다음 명령어를 실행합니다.

PROJECT_ID=$(gcloud config get-value project)

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

5. 컨텍스트의 임베딩 만들기

컴퓨터는 텍스트를 처리하는 것보다 숫자를 처리하는 것이 훨씬 쉽습니다. 임베딩 시스템은 텍스트를 벡터 임베딩이라고 하는 일련의 부동 소수점 수로 변환합니다. 벡터 임베딩은 표현 방식, 사용하는 언어 등에 관계없이 텍스트를 나타내야 합니다.

예를 들어 바닷가 위치는 '바다 옆', '해변가', '객실에서 바다까지 걸어갈 수 있음', 'sur la mer', 'на берегу океана' 등으로 표현할 수 있습니다. 이러한 용어는 모두 다르게 보이지만 의미론적 의미 또는 머신러닝 용어로 보면 임베딩이 서로 매우 근접해야 합니다.

이제 데이터와 컨텍스트가 준비되었으므로 SQL을 실행하여 제품 설명의 임베딩을 embedding 필드의 테이블에 추가합니다. 사용할 수 있는 다양한 임베딩 모델이 있습니다. Vertex AI의 text-embedding-005를 사용합니다. 프로젝트 전체에서 동일한 임베딩 모델을 사용해야 합니다.

참고: 이전 Google Cloud 프로젝트를 사용하는 경우 textembedding-gecko와 같은 이전 버전의 텍스트 삽입 모델을 계속 사용해야 할 수 있습니다.

AlloyDB Studio 탭으로 돌아가서 다음 DML을 입력합니다.

UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);

toys 표를 다시 살펴보고 임베딩을 확인합니다. 변경사항을 확인하려면 SELECT 문을 다시 실행해야 합니다.

SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;

그러면 아래와 같이 장난감 설명에 대한 임베딩 벡터(부동 소수점 배열처럼 보임)가 반환됩니다.

7d32f7cd7204e1f3.png

참고: 무료 등급으로 새로 만든 Google Cloud 프로젝트는 삽입 모델에 허용되는 초당 삽입 요청 수와 관련하여 할당량 문제가 발생할 수 있습니다. 임베딩을 생성하는 동안 ID에 필터 쿼리를 사용한 후 1~5개의 레코드 등을 선택적으로 선택하는 것이 좋습니다.

6. 벡터 검색 실행

이제 테이블, 데이터, 임베딩이 모두 준비되었으므로 사용자 검색 텍스트에 대한 실시간 벡터 검색을 실행해 보겠습니다.

사용자가 다음과 같이 묻는다고 가정해 보겠습니다.

"I want a white plush teddy bear toy with a floral pattern."

다음 쿼리를 실행하여 일치하는 항목을 찾을 수 있습니다.

select * from toys
ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', 'I want a white plush teddy bear toy with a floral pattern') as vector(768))
LIMIT 5;

이 쿼리를 자세히 살펴보겠습니다.

이 쿼리에서

  1. 사용자의 검색 텍스트는 'I want a white plush teddy bear toy with a floral pattern.'입니다.
  2. text-embedding-005 모델을 사용하여 embedding() 메서드에서 임베딩으로 변환합니다. 이 단계는 테이블의 모든 항목에 삽입 함수를 적용한 마지막 단계와 유사합니다.
  3. '<=>'는 COSINE SIMILARITY 거리 메서드의 사용을 나타냅니다. 사용 가능한 모든 유사성 측정값은 pgvector 문서에서 확인할 수 있습니다.
  4. 데이터베이스에 저장된 벡터와 호환되도록 임베딩 메서드의 결과를 벡터 유형으로 변환합니다.
  5. LIMIT 5는 검색 텍스트의 최근접 이웃 5개를 추출하겠다는 의미입니다.

결과는 다음과 같습니다.

fa7f0fc3a4c68804.png

검색 결과에서 볼 수 있듯이 검색어와 상당히 유사한 검색 결과가 표시됩니다. 텍스트를 변경하여 결과가 어떻게 달라지는지 확인해 보세요.

7. Toolbox 상호작용에 맞게 AlloyDB 준비

Toolbox 설정을 준비하기 위해 새 도구가 데이터베이스에 액세스할 수 있도록 AlloyDB 인스턴스에서 공개 IP 연결을 사용 설정하겠습니다.

  1. AlloyDB 인스턴스로 이동하여 '수정'을 클릭하고 기본 인스턴스 수정 페이지로 이동합니다.
  2. 공개 IP 연결 섹션으로 이동하여 공개 IP 사용 설정 체크박스를 선택하고 Cloud Shell 머신의 IP 주소를 입력합니다.
  3. Cloud Shell 머신의 IP를 가져오려면 Cloud Shell 터미널로 이동하여 ifconfig를 입력합니다. 결과에서 eth0 inet 주소를 식별하고 마지막 2자리를 0.0으로 바꾸고 마스크 크기를 '/16'으로 지정합니다. 예를 들어 'XX.XX.0.0/16'과 같이 표시되며 여기서 XX는 숫자입니다.
  4. 이 IP를 인스턴스 수정 페이지의 승인된 외부 네트워크 '네트워크' 텍스트 상자에 붙여넣습니다.

5f6e60e8dec2cea1.png

  1. 완료되면 '인스턴스 업데이트'를 클릭합니다.

완료하는 데 몇 분 정도 걸릴 수 있습니다.

8. 도구 상자 설치

  1. 도구 세부정보를 저장할 프로젝트 폴더를 만들 수 있습니다. 이 경우 장난감 가게 데이터를 다루므로 'toystore'라는 폴더를 만들고 해당 폴더로 이동하겠습니다. Cloud Shell 터미널로 이동하여 프로젝트가 선택되어 있고 터미널 프롬프트에 표시되는지 확인합니다. Cloud Shell 터미널에서 아래 명령어를 실행합니다.
mkdir toystore

cd toystore
  1. 아래 명령어를 실행하여 새 폴더에 Toolbox를 다운로드하고 설치합니다.
# see releases page for other versions
export VERSION=0.1.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
  1. Cloud Shell 편집기로 전환합니다. 새로 만든 'toystore' 폴더를 펼치고 tools.yaml이라는 새 파일을 만듭니다. 아래 콘텐츠를 복사합니다. YOUR_PROJECT_ID를 바꾸고 다른 모든 연결 세부정보가 정확한지 확인합니다.
sources:
    alloydb-toys:
        kind: "alloydb-postgres"
        project: "YOUR_PROJECT_ID"
        region: "us-central1"
        cluster: "vector-cluster"
        instance: "vector-instance"
        database: "postgres"
        user: "postgres"
        password: "alloydb"

tools:
  get-toy-price:
    kind: postgres-sql
    source: alloydb-toys
    description: Get the price of a toy based on a description.
    parameters:
      - name: description
        type: string
        description: A description of the toy to search for.
    statement: |
      SELECT price FROM toys
      ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS vector(768))
      LIMIT 1;

이 도구에서는 사용자의 검색 텍스트 (맞춤 장난감 설명)와 가장 일치하는 항목을 찾아 가격을 반환합니다. 가장 근접한 상위 5개 장난감의 평균 가격을 찾도록 수정할 수도 있습니다.

select avg(price) from ( SELECT price FROM toys ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) as price;

도구 정의가 완료되었습니다.

tools.yaml 구성에 관한 자세한 내용은 이 문서를 참고하세요.

  1. Cloud Shell 터미널로 전환하고 다음 명령어를 입력하여 도구 구성으로 도구 상자 서버를 시작합니다.
./toolbox --tools_file "tools.yaml"
  1. 이제 클라우드에서 웹 미리보기 모드로 서버를 열면 get-toy-price.라는 새 도구가 있는 Toolbox 서버가 실행 중인 것을 볼 수 있습니다.

9. Toolbox의 Cloud Run 배포

이 도구를 실제로 사용할 수 있도록 Cloud Run에 배포해 보겠습니다.

  1. 이 페이지의 안내를 하나씩 따라 'Cloud Run에 배포' 섹션의 세 번째 항목에 있는 gcloud run deploy toolbox 명령어에 도달합니다. VPC 네트워크 방법을 사용하는 경우의 두 번째 옵션이 아닌 첫 번째 옵션이 필요합니다.
  2. 배포가 완료되면 Toolbox 서버의 Cloud Run 배포 엔드포인트가 표시됩니다. CURL 명령어로 테스트합니다.

이제 상담 애플리케이션에서 새로 배포된 도구를 사용할 수 있습니다.

10. Toolbox에 앱 연결

이 부분에서는 도구가 애플리케이션의 요구사항과 상호작용하고 응답을 검색하는지 테스트하는 소규모 애플리케이션을 빌드합니다.

  1. Google Colab으로 이동하여 새 노트북을 엽니다.
  2. 노트북에서 다음을 실행합니다.
pip install toolbox-langchain
from toolbox_langchain import ToolboxClient

# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")
tool = toolbox.load_tool("get-toy-price")

# Invoke the tool with a search text to pass as the parameter
result = tool.invoke({"description": "white plush toy"})

# Print result
print(result)
  1. 다음과 같은 결과가 표시됩니다.

5074f209a86c4f15.png

툴킷 toolbox-langchain.을 사용하는 Python 애플리케이션에서 명시적으로 호출되는 도구입니다.

  1. 이 도구를 사용하고 LangGraph 통합 애플리케이션 내에서 에이전트에 바인딩하려면 langgraph 도구 키트를 사용하면 됩니다.
  2. 자세한 내용은 코드 스니펫을 참고하세요.

11. 클라우드로 가져가세요.

이 Python 코드 스니펫을 Cloud Run Functions에 래핑하여 서버리스로 만들어 보겠습니다.

  1. Cloud Functions로 가져오려면 코드 저장소 폴더에서 소스를 복사합니다.
  2. Cloud Run Functions 콘솔로 이동하여 함수 만들기를 클릭합니다.
  3. 데모 애플리케이션의 경우 인증되지 않은 상태로 두고 다음 페이지에서 Python 3.11 런타임을 선택합니다.
  4. 1단계에서 공유된 소스 저장소에서 main.py 및 requirements.txt 파일을 복사하여 각 파일에 붙여넣습니다.
  5. 함수를 배포하면 장난감 스토어 웹 애플리케이션에서 가격 예측 도구에 액세스할 수 있는 REST 엔드포인트가 생성됩니다.
  6. 엔드포인트는 다음과 같이 표시됩니다.

https://us-central1-*****.cloudfunctions.net/toolbox-toys

  1. Cloud Functions 콘솔에서 TESTING 탭으로 이동하여 다음을 요청 입력으로 입력하면 직접 테스트할 수 있습니다.

{

               "`search`"`:` "`White plush toy`"

}

  1. 사용하려는 방법에 따라 함수 테스트를 클릭하거나 Cloud Shell 터미널에서 실행합니다. 오른쪽의 '출력' 제목 아래에 결과가 표시됩니다.

d7ba57cf5e5ca553.png

12. 축하합니다

축하합니다. 데이터베이스, 플랫폼, 생성형 AI 오케스트레이션 프레임워크 간에 상호작용할 수 있는 강력하고 진정한 모듈식 도구를 만들어 에이전트 애플리케이션을 만드는 데 도움을 주었습니다.