AlloyDB의 생성형 AI 및 에이전트 애플리케이션용 데이터베이스용 MCP 도구 상자 설치 및 설정

이 Codelab 정보

최종 업데이트: 4월 28, 2025

작성자: Author: Abirami Sukumaran Anubhav Dhawan

1. 개요

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

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

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

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

엔드 투 엔드 관측 가능성: OpenTelemetry가 기본적으로 지원되므로 즉시 사용 가능한 측정항목 및 추적이 가능합니다.

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

빌드할 항목

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

데이터베이스용 MCP 도구 상자 설치
Toolbox 서버에서 도구 설정 (AlloyDB에서 태스크를 수행하도록 설계됨)
Cloud Run에서 데이터베이스용 MCP 도구 상자 배포
배포된 Cloud Run 엔드포인트로 도구 테스트
Cloud Run 함수를 빌드하여 도구 상자 호출

요구사항

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

2. 시작하기 전에

프로젝트 만들기

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

Cloud Shell 활성화 버튼 이미지

Cloud Shell에 연결되면 다음 명령어를 사용하여 이미 인증되었는지, 프로젝트가 올바른 프로젝트 ID로 설정되었는지 확인합니다.

gcloud auth list

Cloud Shell에서 다음 명령어를 실행하여 gcloud 명령어가 프로젝트를 알고 있는지 확인합니다.

gcloud config list project

프로젝트가 설정되지 않은 경우 다음 명령어를 사용하여 설정합니다.

gcloud config set project <YOUR_PROJECT_ID>

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 클러스터, 인스턴스, 테이블을 만들어 보겠습니다.

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

Cloud 콘솔에서 AlloyDB 페이지를 탐색합니다.

Cloud 콘솔에서 대부분의 페이지를 쉽게 찾을 수 있는 방법은 콘솔의 검색창을 사용하여 검색하는 것입니다.

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

아래와 같은 화면이 표시됩니다. 다음 값을 사용하여 클러스터 및 인스턴스를 만듭니다. 저장소에서 애플리케이션 코드를 클론하는 경우 값이 일치해야 합니다.

클러스터 ID: 'vector-cluster'
비밀번호: 'alloydb'
PostgreSQL 15 호환
리전: 'us-central1'
네트워킹: 'default'

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

인스턴스 ID를 '

vector-instance"

클러스터를 만드는 데 10분 정도 걸립니다. 성공하면 방금 만든 클러스터의 개요를 보여주는 화면이 표시됩니다.

4. 데이터 수집

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

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

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

AlloyDB Studio에 인증이 완료되면 편집기에 SQL 명령어를 입력할 수 있습니다. 마지막 창의 오른쪽에 있는 더하기 기호를 사용하여 편집기 창을 여러 개 추가할 수 있습니다.

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

확장 프로그램 사용

이 앱을 빌드하기 위해 pgvector 및 google_ml_integration 확장 프로그램을 사용합니다. pgvector 확장 프로그램을 사용하면 벡터 임베딩을 저장하고 검색할 수 있습니다. google_ml_integration 확장 프로그램은 SQL에서 예측을 얻기 위해 Vertex AI 예측 엔드포인트에 액세스하는 데 사용하는 함수를 제공합니다. 다음 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 필드가 포함되어 있습니다. 다른 필드는 실습 후반부에서 채웁니다.

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

표 콘텐츠를 보려면 의류라는 표가 표시될 때까지 탐색기 섹션을 펼칩니다. 트리콜론 (⋮)을 선택하여 테이블 쿼리 옵션을 확인합니다. SELECT 문이 새 편집기 탭에서 열립니다.

권한 부여

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

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. 컨텍스트에 대한 임베딩 만들기

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

예를 들어 해변 위치는 '바닷가', '해변', '방에서 바다로 가기', '수르 라 메르', 'на WRITEре 안함 океана' 등으로 불릴 수 있습니다. 이러한 용어는 모두 다르게 보이지만 의미론적 의미나 머신러닝 용어로 임베딩이 서로 매우 가까워야 합니다.

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

참고: 이전 Google Cloud 프로젝트를 사용하는 경우 textEmbed-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;

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

참고: 무료 등급에서 새로 만든 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;

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

이 쿼리에서는

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

결과는 다음과 같습니다.

결과에서 볼 수 있듯이 일치하는 결과가 검색 텍스트와 매우 유사합니다. 텍스트를 변경해 결과가 어떻게 바뀌는지 확인해 보세요.

7. 도구 상자 상호작용을 위한 AlloyDB 준비

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

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

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

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

8. 데이터베이스 설치를 위한 MCP 도구 상자

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

mkdir toystore

cd toystore

다음 명령어를 실행하여 도구 상자를 새 폴더에 다운로드하고 설치합니다.

# 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

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 price FROM toys ORDER BY text_Embeds <=> CAST ( embedding(‘text-Embed-005', $1) AS vector(768)) LIMIT 5 )에서 avg(price)를 가격으로 선택합니다.

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

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

Cloud Shell 터미널로 전환하고 다음 명령어를 입력하여 도구 구성으로 도구 상자 서버를 시작합니다.

./toolbox --tools_file "tools.yaml"

이제 클라우드의 웹 미리보기 모드에서 서버를 열면 get-toy-price.라는 새 도구로 도구 상자 서버가 작동되어 실행되는 것을 확인할 수 있습니다.

9. 데이터베이스용 MCP 도구 상자의 Cloud Run 배포

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

'Cloud Run에 배포' 섹션의 세 번째 지점에 있는 gcloud run deploy toolbox 명령어가 나올 때까지 이 페이지의 안내를 하나씩 따릅니다. 첫 번째 옵션은 필요하지만 VPC 네트워크 방법을 사용할 때 필요한 두 번째 옵션은 필요하지 않습니다.
배포가 완료되면 도구 상자 서버의 Cloud Run 배포 엔드포인트를 수신합니다. CURL 명령어로 테스트합니다.

도움말:

페이지의 안내를 주의 깊게 따르고 놓치지 마세요.

이제 에이전트 애플리케이션에서 새로 배포한 도구를 사용할 준비가 되었습니다.

10. 데이터베이스용 MCP 도구 상자로 앱 연결

여기서는 애플리케이션의 요구 사항과 상호 작용하고 응답을 검색하는 도구를 테스트하는 작은 애플리케이션을 빌드합니다.

Google Colab으로 이동하여 새 노트북을 엽니다.
노트북에서 다음을 실행합니다.

!pip install toolbox-core
from toolbox_core import ToolboxClient

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

# This tool can be passed to your application!
tool = toolbox.load_tool("get-toy-price")

# If there are multiple tools 
# These tools can be passed to your application!
# tools = await client.load_toolset("<<toolset_name>>")

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

# Print result
print(result)

다음과 같은 결과가 표시됩니다.

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

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

11. 클라우드로 이전하세요.

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

Cloud Functions로 가져오기 위해 코드 저장소 폴더의 소스를 복사합니다.
Cloud Run Functions 콘솔로 이동하여 함수 만들기를 클릭합니다.
데모 애플리케이션에서는 인증되지 않은 상태로 유지하고 다음 페이지에서 Python 3.11 런타임을 선택하세요.
1단계에서 공유한 소스 저장소에서 main.py 및 requirements.txt 파일을 복사하여 각 파일에 붙여넣습니다.
main.py의 서버 URL을 서버 URL로 바꿉니다.
함수를 배포하면 toystore 웹 애플리케이션에서 가격 예측 도구에 액세스할 수 있는 REST 엔드포인트가 확보됩니다.
엔드포인트는 다음과 같아야 합니다.

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

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

{

           "search": "White plush toy"

}

'함수 테스트'를 클릭하거나 사용할 Cloud Shell 터미널에서 실행합니다. 'Output(출력)' 제목 아래 오른쪽에 결과가 표시됩니다.

12. 축하합니다

축하합니다. 데이터베이스, 플랫폼, 생성형 AI 조정 프레임워크 전반에서 상호작용하여 에이전트형 애플리케이션을 만드는 데 도움이 되는 강력하고 진정한 모듈형 도구를 성공적으로 만들었습니다.

오류 신고