Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

다중 데이터베이스 지속성을 사용하여 지능형 전자상거래 카탈로그 빌드

1. 소개

현대 소매업에서 데이터는 다양하고 광범위한 생태계를 구성합니다. 견고한 트랜잭션 데이터 (가격 및 인벤토리), '복잡한' 다형성 카탈로그 (전자제품 사양과 의류 사이즈), 페타바이트 규모의 행동 로그가 있습니다. 이러한 기능을 하나의 모놀리식 구조로 강제하면 기술적 부채가 발생할 뿐만 아니라 사용자 경험이 저하됩니다.

이 Codelab에서는 다음을 조화롭게 결합하는 다국어 파워하우스를 설계합니다.

AlloyDB: 고속 일관성 및 이미지 임베딩을 위한 트랜잭션 백본입니다.
Google Cloud 기반 MongoDB Atlas: 유연하고 스키마에 구애받지 않는 카탈로그 레이어입니다.
Cloud Storage: 실시간 트렌드 예측을 위한 분석 두뇌입니다.
BigQuery: 고해상도 디지털 웨어하우스입니다.

'특별한 비결'은 무엇일까요? 데이터베이스용 MCP 도구 상자를 사용하여 Cloud Run에서 실행되는 데이터 소스를 시맨틱 브리지로 지능적으로 조정하고 통합한 다음 에이전트 개발 키트 (ADK)를 사용하여 멀티 에이전트 채팅 앱을 배포합니다. 단순히 검색창을 만드는 것이 아니라 컨텍스트를 이해하고, 제약 조건을 준수하며, 원시 데이터와 인간의 의도 사이의 간극을 메우는 지능형 소매 브레인을 구축하는 것입니다.

불가능한 사용자 질문

표준 전자상거래 에이전트는 다차원 추론 (부정적 제약 조건, 시각적 유사성, 실시간 재고 결합)에 실패합니다. 예를 들어 저는 일반적으로 다음과 같이 소매 사이트와 대화하고 싶습니다.

"안녕, 고지대 사진 촬영 여행을 계획 중이야. 'AeroGlow Pro'와 스타일은 비슷하지만 가죽 소재가 사용되지 않은 내후성 백팩을 보여 줘. 그리고 실제로 재고가 있는지, 다른 사진작가가 리뷰에서 스트랩 내구성에 대해 불만을 제기했는지도 알려 줘."

이 질문이 '상담사 킬러'인 이유:

시각적 유사성 (AlloyDB + 벡터 검색): 'AeroGlow Pro와 스타일이 유사한 제품'을 찾으려면 이미지 임베딩 비교가 필요합니다.
부정 제약 조건 (MongoDB): '가죽이 없는'이라는 조건은 일반적으로 표준 SQL 스키마에 없는 유연한 중첩 속성을 통해 필터링해야 합니다.
실시간 인벤토리(AlloyDB): '재고 있음'을 확인하려면 오래된 검색 색인이 아닌 실시간 트랜잭션 확인이 필요합니다.
시맨틱 합성 (BigQuery + 멀티 에이전트): '스트랩 내구성'에 대한 리뷰를 분석하려면 에이전트가 BigQuery의 비정형 의견을 즉시 요약해야 합니다.

대부분의 소매 봇은 '백팩'과 '가죽'만 보고 가죽 백팩 10개를 표시합니다. YouTube의 대처 방법

단순히 키워드를 일치시키는 것이 아니기 때문입니다. MCP 도구 상자를 사용하여 에이전트가 AlloyDB의 트랜잭션 정보 소스와 MongoDB의 유연한 속성을 동시에'추론'할 수 있도록 하고 있습니다. 만들어 봅시다.

실습할 내용

핵심 제품 데이터를 위한 AlloyDB 클러스터 프로비저닝
Google Cloud 기반 MongoDB Atlas를 구성하여 반정형 제품 세부정보 저장
제품 이미지를 제공할 Cloud Storage 버킷 만들기
균일한 데이터 액세스를 위해 Cloud Run에 데이터베이스용 MCP 도구 상자 배포
ETL 프로세스를 실행하여 분석을 위해 데이터를 BigQuery로 푸시
자연어로 AI 에이전트와 대화합니다.

전자상거래 멀티 데이터베이스 아키텍처

기본 요건

웹브라우저(예: Chrome)
결제가 사용 설정된 Google Cloud 프로젝트
무료 Google Cloud 기반 MongoDB Atlas 계정

2. 시작하기 전에

Google Cloud 프로젝트 만들기

Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요.

Cloud Shell 시작

Cloud Shell은 Google Cloud에서 실행되는 명령줄 환경으로, 필요한 도구가 미리 로드되어 있습니다.

Google Cloud 콘솔 상단에서 Cloud Shell 활성화를 클릭합니다.
Cloud Shell에 연결되면 인증을 확인합니다.
```
gcloud auth list
```
프로젝트가 구성되었는지 확인합니다.
```
gcloud config get project
```

프로젝트가 예상대로 설정되지 않은 경우 설정합니다.

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

변수 설정

Cloud Shell에서 프로젝트 ID 및 프로젝트 번호의 환경 변수를 설정합니다.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

필요한 API 사용 설정

다음 명령어를 실행하여 필요한 모든 API를 사용 설정합니다.

gcloud services enable \
  alloydb.googleapis.com \
  bigquery.googleapis.com \
  storage.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  iam.googleapis.com \
  secretmanager.googleapis.com \
  compute.googleapis.com \
  servicenetworking.googleapis.com \
  aiplatform.googleapis.com

3. Cloud Storage 설정

Cloud Storage는 제품 이미지와 같은 비정형 미디어 애셋을 위한 대규모 저장소 역할을 합니다.

Google Cloud 콘솔에서 Cloud Storage로 이동하여 버킷 만들기를 클릭합니다.
버킷에 전역적으로 고유한 이름(예: -ecommerce-images)을 지정합니다.
만들기를 클릭합니다.
데모 애플리케이션이 인증 없이 이미지에 액세스할 수 있도록 하려면 이 버킷에 공개 액세스 방지 적용 옵션을 선택 해제하고 확인을 클릭합니다.
권한 탭으로 이동합니다.
권한에서 액세스 권한 부여를 클릭합니다.
새 주 구성원에서 allUsers를 입력합니다.
역할 선택에서 Cloud Storage > 스토리지 객체 뷰어를 선택합니다.
저장을 클릭한 다음 공개 액세스 허용을 클릭하여 리소스를 공개로 설정하는지 확인합니다.
Cloud Shell에서 버킷 이름을 변수에 저장합니다.
```
export BUCKET=<your-bucket-name>
```
을 만든 버킷의 이름으로 바꿉니다.

플레이스홀더 이미지 업로드

프로젝트는 최상의 시각적 환경을 위해 플레이스홀더 이미지를 사용합니다.

Cloud Shell에서 저장소를 클론합니다.

git clone https://github.com/AbiramiSukumaran/polyglot-persist-ecommerce.git

UploadImages 폴더로 이동합니다.

cd polyglot-persist-ecommerce/UploadImages

샘플 이미지를 버킷에 업로드합니다.
```
gcloud storage cp *.jpg gs://$BUCKET/
```

4. AlloyDB 설정

AlloyDB는 제품 ID, 이름, SKU, 가격, 인벤토리와 같은 정형, 트랜잭션, 중요 데이터의 단일 정보 소스 역할을 합니다. AlloyDB는 추천 및 자연어 쿼리를 위한 유사성 검색 기능으로 AI 에이전트를 지원합니다.

AlloyDB 클러스터 프로비저닝

Google Cloud 콘솔에서 PostgreSQL용 AlloyDB로 이동합니다.
클러스터 만들기를 클릭합니다.
클러스터 ID에 ecommerce-cluster을 입력합니다.
postgres 사용자의 안전한 비밀번호를 설정합니다. 학습 목적으로는 alloydb를 사용할 수 있습니다.
데이터베이스 버전은 기본값을 유지합니다.
리전에서 us-central1 (또는 원하는 리전)을 선택합니다.

기본 인스턴스 구성

인스턴스 ID에 ecommerce-cluster-primary를 입력합니다.
영역 가용성에서 단일 영역을 선택합니다.
머신 시리즈에서 N2를 선택하고 머신 유형에서 4 vCPU, 32 GB를 선택합니다.
비공개 IP 연결에서 비공개 서비스 액세스 (PSA)를 선택하고 default 네트워크를 선택합니다.기본 네트워크가 아직 설정되지 않은 경우 네트워크 설정 확인을 클릭하여 네트워크를 만듭니다.
이 Codelab에서 MCP 도구 상자가 제대로 연결되도록 공개 IP 연결에서 공개 IP 사용 설정 체크박스를 선택합니다. 콘솔은 AlloyDB가 공개 IP에 필요로 하는 password.enforce_complexity 플래그를 자동으로 사용 설정합니다.
승인된 외부 네트워크에 0.0.0.0/0를 입력합니다. 위험을 인지함 체크박스를 선택하고 저장을 클릭합니다.
클러스터 만들기를 클릭합니다.

데이터베이스 초기화

왼쪽 탐색 메뉴에서 AlloyDB Studio를 클릭합니다.
데이터베이스 드롭다운에서 postgres를 선택합니다.
기본 제공 인증을 선택하여 데이터베이스에 로그인합니다.
사용자 이름에 postgres 사용자를 사용합니다.
비밀번호에 이전에 설정한 비밀번호를 입력합니다.
인증을 클릭합니다.
편집기 화면에서 새로운 '제목 없는 쿼리' 탭을 엽니다.

다음 DDL을 복사하고 실행을 클릭합니다.

CREATE TABLE products_core_table (
  product_id UUID PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  sku VARCHAR(50) UNIQUE NOT NULL,
  price NUMERIC(10, 2) NOT NULL,
  stock INT NOT NULL
);

Cloud Shell에서 프로젝트 루트 폴더로 이동합니다.
```
cd ~/polyglot-persist-ecommerce
```
Cloud Shell에서 alloydb_insert_queries.sql 파일을 열고 삽입 쿼리를 복사합니다.
```
cat alloydb_insert_queries.sql
```
새로운 제목 없는 쿼리 탭에 INSERT 문만 붙여넣고 실행을 클릭합니다.
제목 없는 새 쿼리 탭에서 다음 DDL을 복사하고 실행을 클릭하여 products_core_table 테이블에 색인을 만듭니다.
```
CREATE INDEX idx_products_core_sku ON products_core_table(sku);
```

AI 에이전트가 유사한 제품을 가져올 수 있도록 이미지 임베딩 만들기

AI 에이전트 통합은 이미지 임베딩을 사용하여 유사한 제품을 가져옵니다. 임베딩은 multimodalembedding@001 모델을 사용하여 생성되고 AlloyDB 데이터베이스에 저장됩니다. 임베딩은 1408차원 벡터이며 img_embeddings 열에 저장됩니다.

임베딩을 생성하려면 먼저 AlloyDB 서비스 계정에 Cloud Storage에 액세스하는 데 필요한 역할을 부여해야 합니다.

Cloud Storage에 액세스할 수 있도록 AlloyDB 서비스 계정에 역할 부여

AlloyDB 서비스 계정에 Cloud Storage에서 이미지를 읽고 Vertex AI 임베딩을 생성하는 데 필요한 역할을 부여합니다.

for role in roles/storage.objectUser roles/storage.objectViewer roles/aiplatform.user; do
  gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUMBER}@gcp-sa-alloydb.iam.gserviceaccount.com" \
    --role=$role --condition=None
done

확장 프로그램 사용 설정

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

Google Cloud 콘솔에서 PostgreSQL용 AlloyDB로 이동합니다.
왼쪽 탐색 메뉴에서 AlloyDB Studio를 클릭합니다.
편집기 화면에서 새로운 '제목 없는 쿼리' 탭을 엽니다.

다음 DDL을 복사하고 실행을 클릭합니다.

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

임베딩으로 데이터베이스 초기화

products_core_table에 img_embeddings 열을 추가합니다.

ALTER TABLE products_core_table
ADD COLUMN img_embeddings vector(1408);

버킷 이름을 입력하여 임베딩 쿼리를 출력합니다.

cd ~/polyglot-persist-ecommerce
sed "s/<STORAGE_BUCKET_NAME>/$BUCKET/g" alloydb_generate_embeddings.sql

출력을 복사하여 새 AlloyDB Studio 쿼리 탭에 붙여넣고 실행을 클릭합니다. 1분 정도 걸립니다. 시간 초과가 발생하면 다시 실행합니다. 이미 임베딩이 있는 제품은 건너뜁니다.
스크립트는 UploadImages/에 이미지가 있는 제품만 처리합니다.

5. Google Cloud에서 MongoDB Atlas 설정

MongoDB는 풍부한 반정형 제품 세부정보와 유연한 사용자 행동 데이터 (예: 클릭수, 조회수)를 저장합니다.

MongoDB 클러스터 만들기

MongoDB Atlas에 로그인합니다(필요한 경우 무료 계정 만들기).
클러스터 배포에서 무료를 선택합니다. (Atlas는 유료 등급을 미리 선택합니다. 무료가 선택되어 있는지 확인하세요.)
제공업체에서 Google Cloud를 선택하고 리전에서 아이오와 (us-central1)를 선택합니다.
이름에 ecommerce-cluster를 입력하고 샘플 데이터 세트 미리 로드를 선택 해제합니다.
배포 만들기를 클릭합니다.

액세스 허용 및 데이터베이스 사용자 만들기

Atlas에서 ecommerce-cluster에 연결 대화상자가 열립니다.

다른 IP 주소 추가를 클릭하고 0.0.0.0/0를 입력한 후 추가합니다.
0.0.0.0/0를 사용하면 모든 IP 주소에서 액세스할 수 있습니다. 임시 데모에서는 이 방법이 허용되지만 프로덕션에서는 특정 IP 범위로 액세스를 제한해야 합니다.
사용자 이름에 store-user을 입력하고 비밀번호에 storeuser을 입력한 다음 데이터베이스 사용자 만들기를 클릭합니다.
연결 방법 선택을 클릭한 다음 드라이버 및 클라이언트 라이브러리를 클릭합니다.
애플리케이션에서 이 연결 문자열 사용에서 연결 문자열을 복사합니다. mongodb+srv://store-user:@ecommerce-cluster.xxxxx.mongodb.net/과 같이 표시됩니다. 를 storeuser로 바꾸고 문자열을 저장합니다. 이 문자열은 tools.yaml에서 사용합니다.

데이터베이스 및 컬렉션 만들기

왼쪽 탐색 메뉴에서 데이터 탐색기를 클릭한 다음 데이터베이스 만들기를 클릭하고 세부정보를 입력합니다.
- 데이터베이스 이름: ecommerce_db
- 컬렉션 이름: product_details_collection
데이터베이스 만들기를 클릭합니다.
데이터 탐색기에서 컬렉션 이름을 선택합니다.
데이터 추가 (+) 아이콘을 클릭한 다음 문서 삽입을 클릭합니다.
product_details_export.json에서 JSON 콘텐츠를 복사하여 문서 삽입 편집기 대화상자에 붙여넣습니다.
Atlas에 텍스트를 셸 문법으로 변환하는 배너가 표시됩니다. 변환을 클릭한 다음 삽입을 클릭합니다. 문서 192개가 추가되었는지 확인합니다.
데이터 탐색기에서 ecommerce_db 데이터베이스 옆에 있는 컬렉션 만들기 (+)를 클릭합니다.
컬렉션 이름으로 user_interactions_collection을 입력하고 컬렉션 만들기를 클릭합니다.
데이터 탐색기에서 user_interactions_collection 컬렉션을 선택합니다.
데이터 추가 (+) 아이콘을 클릭한 다음 문서 삽입을 클릭합니다.
user_interactions_export.json에서 JSON 콘텐츠를 복사하여 문서 삽입 편집기 대화상자에 붙여넣습니다.
Atlas에 텍스트를 셸 문법으로 변환하는 배너가 표시됩니다. 변환을 클릭한 다음 삽입을 클릭합니다. 문서 211개가 추가되었는지 확인합니다.

6. BigQuery 설정하기

BigQuery는 과거 사용자 행동을 집계하고 분석하여 지능형 보고서와 추천을 생성합니다.

데이터세트 만들기

Google Cloud 콘솔에서 BigQuery로 이동합니다.
탐색기 창에서 프로젝트 ID 옆에 있는 점 3개 메뉴를 클릭하고 데이터 세트 만들기를 선택합니다.
데이터 세트 ID에 ecommerce_analytics를 입력합니다.
데이터 위치로 US (multiple regions)를 선택합니다(tools.yaml 구성에는 US 위치가 필요함).
데이터 세트 만들기를 클릭합니다.

분석 테이블 만들기

BigQuery 작업공간에서 새 쿼리를 엽니다.
다음 SQL 문을 실행하여 사용자를 제품 상호작용에 연결하는 요약 테이블을 만듭니다.

CREATE TABLE ecommerce_analytics.user_product_interactions (
    user_id STRING DEFAULT 'any user',
    product_id STRING,
    interaction_score INT
);

Compute 서비스 계정에 역할 부여

기본 Compute 서비스 계정에 MCP 도구 상자와 앱에 필요한 역할을 부여합니다.

for role in \
  roles/bigquery.dataEditor \
  roles/bigquery.jobUser \
  roles/secretmanager.secretAccessor \
  roles/alloydb.client \
  roles/serviceusage.serviceUsageConsumer \
  roles/storage.objectViewer \
  roles/aiplatform.user \
  roles/artifactregistry.writer; do
  gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
    --role="$role" \
    --condition=None
done

또는 콘솔에서 IAM 및 관리자 > IAM으로 이동하여 액세스 권한 부여를 클릭하고 서비스 계정을 입력한 후 동일한 역할을 추가합니다.

7. 애플리케이션 엔드 투 엔드 이해하기

각 구성요소가 서로 어떻게 작동하는지 알아보기 위해 여러 데이터베이스와 서비스를 사용하는 전자상거래 애플리케이션을 만들어 보겠습니다. 이 애플리케이션은 Python (Flask) 백엔드로 빌드되며 여러 Google Cloud 서비스 및 데이터베이스를 통합합니다.

디렉터리 구조 이해하기

다음 섹션에서는 polyglot-persist-ecommerce 저장소를 클론하고 이를 사용하여 애플리케이션을 로컬에서 실행합니다. 로컬에서 애플리케이션을 테스트한 후 MCP 도구 상자와 애플리케이션을 모두 Cloud Run에 배포합니다.

이 디렉터리에서 다운로드한 파일을 살펴봅니다. 다음과 같은 상위 디렉터리가 있습니다.

UploadImages: 주로 전자상거래 제품 카탈로그의 문서 또는 시각적 콘텐츠에 사용되는 이미지 애셋을 저장합니다.
static: 사용자 인터페이스에 스타일을 지정하고 상호작용을 추가하는 데 사용되는 CSS 및 JavaScript 파일과 같은 애플리케이션의 정적 웹 애셋을 저장합니다 ( 소스).
templates: Python 애플리케이션에서 전자상거래 카탈로그의 웹페이지를 동적으로 렌더링하는 데 사용하는 HTML 템플릿 (Flask의 경우 Jinja2일 가능성이 높음)을 저장합니다 ( 소스).

이 저장소의 파일은 함께 작동하여 다중 데이터베이스 전자상거래 애플리케이션을 빌드, 구성, 배포합니다. app.py와 같은 중앙 파일은 SQL 및 JSON 파일에 정의된 다양한 데이터 소스를 통합하여 백엔드를 조정하고, 구성 파일은 클라우드 환경에 원활하게 배포할 수 있도록 합니다.

app.py: Flask 백엔드 및 멀티 데이터베이스 통합을 조정합니다.
agentengine.py: Vertex AI 에이전트를 초기화하고 구성하는 핵심 로직입니다.
.env: 데이터베이스 및 스토리지 연결의 보안 비밀을 저장합니다.
tools.yaml: multidb 데이터베이스 작업을 위해 MCP 도구 상자를 구성합니다.
Dockerfile: 컨테이너 이미지 및 환경 설정을 정의합니다.
requirements.txt: 애플리케이션 런타임에 필요한 Python 라이브러리를 나열합니다.
tools.yaml: MCP 도구 상자의 구성입니다.
Procfile: 배포를 위한 프로덕션 실행 명령어를 지정합니다.
alloydb_insert_queries.sql: 관계형 데이터에 대한 SQL 쿼리가 포함되어 있습니다.
product_details_export.json 및 user_interactions_export.json: NoSQL 데이터베이스의 샘플 JSON 데이터를 제공합니다.
README.md: 설정, 배포, 프로젝트 이해를 안내합니다.

애플리케이션의 엔드 투 엔드 플로우

AlloyDB 설정: 고성능 클러스터를 프로비저닝하고 제공된 SQL 스크립트를 사용하여 이미지 임베딩을 위한 벡터 열이 있는 products_core_table을 만듭니다.
MongoDB Atlas 설정: Google Cloud에 클러스터를 배포하여 product_details에 유동적인 제품 속성을 저장하고 user_interactions에 실시간 클릭스트림을 로깅합니다.
BigQuery 분석: 상호작용 로그를 집계하는 데이터 세트를 만들어 수백만 개의 이벤트에서 '상위 5개' 인기 항목을 식별하는 복잡한 분석 쿼리를 지원합니다.
Cloud Storage 저장소: 고해상도 제품 이미지를 보관할 공개 버킷을 만들어 프런트엔드에서 서명된 URL 또는 공개 URL을 사용하여 각 애셋에 액세스할 수 있도록 합니다.
MCP 도구 상자 배포: 도구 상자를 Cloud Run에 배포하여 자연어 의도를 멀티 데이터베이스 쿼리로 변환하는 중앙 RESTful 브리지로 설정합니다.
Tools.yaml 구성: get_product_core_data 또는 get_top_5_views와 같은 '도구'를 정의하여 특정 SQL 및 NoSQL 작업을 에이전트가 읽을 수 있는 간단한 이름에 매핑합니다.
Flask 백엔드 로직: MCP 도구 상자와 상호작용하는 app.py 경로를 구현하여 데이터 검색 조정을 처리하고 UI의 API 역할을 합니다.
멀티 에이전트 조정: 코드 내에서 ADK 에이전트를 구성하여 사용자 의도를 추론하고, 복잡한 다중 소스 소매 쿼리를 해결하는 데 적합한 '도구'를 선택합니다.
프런트엔드 통합: 상호작용 기록 기능이 있는 제품 카탈로그, 제품 실적 분석을 이해할 수 있는 분석 탭, ADK 멀티 에이전트 채팅을 사용하여 원활한 대화형 쇼핑 환경을 제공하는 전용 '에이전트 탭'이 포함된 index.html 인터페이스를 빌드합니다.

이제 조정 및 배포를 구현해 보겠습니다.

8. MCP 도구 상자 설정 및 Cloud Run에 배포

MCP 도구 상자는 여러 데이터 소스를 추상화하여 애플리케이션이 데이터를 균일하게 가져오고 쓸 수 있도록 합니다.

로컬에 MCP 도구 상자 설치

MCP 도구 상자 바이너리를 홈 디렉터리에 다운로드하고 실행 파일로 만듭니다.

export VERSION=1.15.0
curl -L -o ~/toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x ~/toolbox

tools.yaml 구성

AlloyDB, MongoDB, BigQuery의 추상화를 정의해야 합니다. tools.yaml 파일은 MCP 도구 상자에 서로 상호작용하는 방법을 알려줍니다.

저장소에 이미 tools.yaml이 포함되어 있습니다. 열기:
```
cd ~/polyglot-persist-ecommerce
cloudshell edit tools.yaml
```

***** 자리표시자를 값으로 바꿉니다.

데이터베이스	필드	예시 값
AlloyDB/BigQuery	`project`	`YOUR_PROJECT_ID`
AlloyDB	`region`	`us-central1`
AlloyDB	`cluster`	`ecommerce-cluster`
AlloyDB	`instance`	`ecommerce-cluster-primary`
AlloyDB	`database`	`postgres`
AlloyDB	`password`	`alloydb`
AlloyDB	`ipType`	`public`(`alloydb-source` 아래에 이 줄이 없으면 추가)
MongoDB	`uri`	이전에 저장한 연결 문자열

이미지 미리보기를 버킷으로 가리킵니다.

sed -i "s/ecommerce-app-images/$BUCKET/g" tools.yaml

도구 UI 테스트

Cloud Shell 터미널에서 로컬로 도구 상자를 실행하여 UI를 제공합니다.
```
~/toolbox --config tools.yaml --ui --enable-api
```
Cloud Shell에서 웹 미리보기 > 포트 변경을 클릭하고 5000를 입력한 후 열리는 URL 끝에 /ui를 추가합니다.

다음 MCP 도구 상자 UI가 표시됩니다.

MCP 도구 상자 UI

완료되면 Ctrl+C를 눌러 로컬 도구 상자를 중지합니다.

Cloud Run에 배포

MCP 도구 상자를 Cloud Run에 배포하여 애플리케이션이 데이터베이스를 쿼리하는 데 사용할 수 있는 안전한 관리형 서비스로 제공합니다. 민감한 연결 세부정보를 보호하기 위해 구성을 Secret Manager에 저장합니다.

tools.yaml 구성을 Google Secret Manager에 업로드합니다.
```
gcloud secrets create tools --data-file=tools.yaml
```
나중에 tools.yaml를 변경하는 경우 다음을 사용하여 새 버전을 업로드합니다.
```
gcloud secrets versions add tools --data-file=tools.yaml
```

공개 MCP 도구 상자 컨테이너 이미지를 사용하여 배포합니다.

gcloud run deploy toolbox \
    --image us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION \
    --region us-central1 \
    --service-account ${PROJECT_NUMBER}-compute@developer.gserviceaccount.com \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --args="--config=/app/tools.yaml","--address=0.0.0.0","--port=8080","--ui","--enable-api" \
    --allow-unauthenticated

--enable-api는 웹 앱에서 사용하는 REST API를 사용 설정합니다.

도구 상자 URL을 저장합니다.

export TOOLBOX_URL=$(gcloud run services describe toolbox --region us-central1 --format='value(status.url)')
echo $TOOLBOX_URL

브라우저에서 $TOOLBOX_URL/ui를 열어 도구를 확인할 수 있습니다.

9. 전자상거래 애플리케이션 설정 및 Cloud Run에 배포

데이터베이스가 실행되고 MCP 도구 상자 추상화가 배포되었으므로 Flask 웹 애플리케이션을 실행할 수 있습니다.

제품 카탈로그를 제공하기 위해 Flask 애플리케이션은 다음 단계를 수행하여 데이터를 처리합니다.

핵심 데이터 가져오기: AlloyDB (list_products_core)에서 전체 제품 목록을 가져옵니다.
확장된 세부정보 가져오기: MongoDB (list_all_product_details)에서 모든 제품 세부정보를 가져옵니다.
목록 결합: 두 목록을 연결합니다.
미디어로 보강: 모든 항목에 Cloud Storage 이미지 URL을 추가합니다.

에이전트 엔진 만들기

종속 항목 설치
```
cd ~/polyglot-persist-ecommerce
pip install -r requirements.txt
```
참고: 이 단계에서는 패키지를 확인하고 설치하는 데 몇 분 정도 걸릴 수 있습니다.

Vertex AI Reasoning Engine을 사용하여 AI 에이전트를 초기화하고 등록합니다.

export REASONING_ENGINE_LOCATION=us-central1
export APP_NAME=$(python agentengine.py)
echo $APP_NAME

출력은 다음과 비슷하게 표시됩니다.

projects/991742412753/locations/us-central1/reasoningEngines/4933254136889081856

앱은 아래의 배포 명령어에 전달하는 환경 변수에서 설정을 읽으므로 .env를 수정할 필요가 없습니다.

Cloud Run에 프런트엔드 배포

웹 애플리케이션을 Cloud Run에 배포하여 아키텍처를 완성합니다.

gcloud run deploy polyglot --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="MCP_TOOLBOX_SERVER_URL=$TOOLBOX_URL,GCS_PRODUCT_BUCKET=$BUCKET,FALLBACK_IMAGE_URL=https://storage.googleapis.com/$BUCKET/fallback.jpg,GOOGLE_GENAI_USE_VERTEXAI=TRUE,PROJECT_ID=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global,REASONING_ENGINE_LOCATION=$REASONING_ENGINE_LOCATION,APP_NAME=$APP_NAME,MODEL=gemini-3.5-flash"

이제 애플리케이션이 작동합니다. Cloud Run에서 제공하는 서비스 URL을 열어 Multidb 이커머스 카탈로그를 확인합니다. URL은 https://polyglot-*********-uc.a.run.app/과 유사합니다.

10. 애플리케이션 살펴보기

제품 카탈로그를 클릭하여 모든 제품을 확인합니다.
제품 아이콘을 클릭하여 제품 세부정보를 확인합니다. 이미지는 Cloud Storage에서 가져오고, 제품 세부정보는 MongoDB에서 가져오고, 제품 인벤토리는 AlloyDB에서 가져옵니다.
제품 카탈로그와 상호작용하여 MongoDB로 전송되는 모의 뷰 및 쓰기를 생성합니다.
ETL 및 분석을 클릭하여 제품 분석을 확인합니다. 제품 분석이 BigQuery에서 가져온 것임을 알 수 있습니다.

AI 에이전트 탭을 클릭하여 AI 에이전트와 상호작용합니다. 다음과 같은 자연어 질문을 합니다.

I'm planning a high-altitude photography trip.
Show me some weather-resistant backpacks similar in style to aero glow pro
but without any leather components. Also, let me know if they are actually in
stock and if other photographers have complained about the strap durability
in the reviews.

검색 결과는 가죽 부품이 없고 재고가 있으며 리뷰에 스트랩 내구성에 대한 불만이 없는 배낭이라는 요청에 정확히 부합합니다.

AI 에이전트

11. 삭제

Google Cloud 계정에 지속적으로 요금이 청구되지 않도록 하려면 이 Codelab에서 만든 리소스를 삭제하세요.

다음 Cloud Shell 명령어를 실행합니다.

gcloud run services delete toolbox --region us-central1 --quiet
gcloud run services delete polyglot --region us-central1 --quiet
gcloud secrets delete tools --quiet
bq rm -r -f -d $PROJECT_ID:ecommerce_analytics
gcloud storage rm --recursive gs://$BUCKET
gcloud alloydb clusters delete ecommerce-cluster --region us-central1 --force --quiet

원하는 경우 Agent Engine 인스턴스를 삭제합니다.

curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://us-central1-aiplatform.googleapis.com/v1/$APP_NAME?force=true"

또는 Google Cloud 콘솔에서 Vertex AI > Agent Engine으로 이동하여 인스턴스를 삭제합니다.

선택적으로, Google Cloud 프로젝트 전체와 모든 리소스를 삭제하려면 다음 명령어를 실행합니다.

gcloud projects delete $PROJECT_ID

12. 축하합니다

수고하셨습니다 크로스 클라우드 Multidb 아키텍처를 빌드했습니다.

MCP 도구 상자가 최신 전문 애플리케이션의 아키텍처를 연결하는 역할을 한다는 것을 보여주었습니다. 적절한 데이터베이스를 적절한 작업에 매칭하여 다음을 달성했습니다.

유연한 데이터 쓰기: 이벤트 로그용 MongoDB
트랜잭션 일관성: 핵심 무결성을 위한 AlloyDB
고성능 분석: 비즈니스 인텔리전스를 위한 BigQuery
통합 개발: MCP 도구 상자를 사용하여 모든 복잡성을 추상화하는 단일 Python 백엔드입니다.

참조 문서

관련 Google Cloud 제품에 대해 자세히 알아보고 다음 Codelab을 살펴보세요.

AlloyDB AI: AlloyDB AI로 벡터 임베딩 시작하기
AlloyDB AI: AlloyDB의 멀티모달 임베딩
MCP 도구 상자: AlloyDB에서 데이터베이스용 MCP 도구 상자 설치 및 설정

이 Codelab에서 사용되는 제품에 관한 자세한 내용은 다음을 참고하세요.