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

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개를 표시합니다. 어떻게 이를 막고 있나요?

단순히 키워드를 매칭하는 것이 아니기 때문입니다. Google은 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

필요한 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-app-images)을 지정합니다.
만들기를 클릭합니다.
데모 애플리케이션이 인증 없이 이미지에 액세스하도록 허용하려면 이 버킷에 공개 액세스 방지 적용 옵션을 선택 해제하고 확인을 클릭합니다.
권한 탭으로 이동합니다.
권한에서 액세스 권한 부여를 클릭합니다.
새 주 구성원에서 allUsers를 입력합니다.
역할 선택에서 Cloud Storage > 스토리지 객체 사용자를 선택합니다.
저장을 클릭한 다음 공개 액세스 허용을 클릭하여 리소스를 공개로 설정하는 것을 확인합니다.

자리표시자 이미지 업로드

BRK2-149-multidb-ecommerce는 최상의 시각적 환경을 위해 자리표시자 이미지를 사용합니다.

Cloud Shell에서 next-26-sessions 저장소를 클론합니다.

git clone https://github.com/GoogleCloudPlatform/next-26-sessions.git

UploadImages 폴더로 이동합니다.

cd next-26-sessions/BRK2-149-multidb-ecommerce/UploadImages

Google Cloud 콘솔에서 Cloud Storage로 이동한 다음 버킷을 클릭합니다.
새로 만든 버킷의 이름을 클릭합니다.
업로드 > 파일 업로드를 클릭하고 다운로드한 샘플 이미지를 선택한 다음 열기를 클릭합니다.

4. AlloyDB 설정

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

AlloyDB 클러스터 프로비저닝

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

기본 인스턴스 구성

인스턴스 ID에 ecommerce-cluster-primary를 입력합니다.
영역 가용성에서 단일 영역을 선택합니다.
머신 유형에서 소형 머신 유형 (예: N2, vCPU 4개, RAM 32GB)을 선택합니다.
비공개 IP 연결에서 비공개 서비스 액세스 (PSA)를 선택하고 default 네트워크를 선택합니다.아직 기본 네트워크가 설정되지 않은 경우 네트워크 설정 확인을 클릭하여 네트워크를 만듭니다.
공개 IP 연결에서 공개 IP 사용 설정 체크박스를 선택하여 이 Codelab에서 MCP 도구 상자가 올바르게 연결되도록 합니다.
승인된 외부 네트워크에 0.0.0.0/0을 입력합니다. 위험을 확인했습니다 체크박스를 선택하고 저장을 클릭합니다.
클러스터 만들기를 클릭합니다.

참고: 공개 IP 주소를 기록해 두세요 (34.124.240.26와 유사함).

데이터베이스 초기화

왼쪽 탐색 메뉴에서 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에서 BRK2-149-multidb-ecommerce 폴더로 이동합니다.
```
cd next-26-sessions/BRK2-149-multidb-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 열에 저장됩니다.

삽입을 생성하려면 Cloud Storage에 액세스할 수 있도록 AlloyDB 서비스 계정에 필수 역할을 부여해야 합니다.

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

AlloyDB 서비스 계정이 Cloud Storage 버킷에서 객체를 읽을 수 있도록 스토리지 객체 사용자 및 스토리지 객체 뷰어 역할을 부여합니다.

IAM 및 관리자로 이동합니다.
액세스 권한 부여를 클릭합니다.
새 주 구성원 필드에 AlloyDB 검색 서비스 계정을 입력합니다. 서비스 계정은 service-991742412753@gcp-sa-alloydb.iam.gserviceaccount.com와 유사합니다.
역할 선택을 클릭합니다.
스토리지 객체 사용자 역할을 찾아 선택합니다.
다른 역할 추가를 클릭하고 스토리지 객체 뷰어 역할을 선택합니다.
다른 역할 추가를 클릭하고 Vertex AI 사용자 역할을 선택합니다.
저장을 클릭합니다.

확장 프로그램 사용 설정

이 앱을 빌드하기 위해 확장 프로그램 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);

이미지의 임베딩을 생성하고 img_embeddings 열에 저장합니다.

UPDATE products_core_table
SET img_embeddings = google_ml.image_embedding(
    model_id => 'multimodalembedding@001',
    image => 'gs://<STORAGE_BUCKET_NAME>/' || sku || '.jpg',
    mimetype => 'image/jpeg')
WHERE sku IN (
    SELECT
    sku
    FROM
    products_core_table
    WHERE
    img_embeddings IS NULL
    AND sku IS NOT NULL
    LIMIT 10
);

을 Cloud Storage 버킷 이름으로 바꿉니다.

스튜디오에는 5분 제한이 있으므로 전체 세트의 이미지 삽입을 생성하려면 이전 쿼리를 5회 이상 반복하세요. 이 쿼리가 시간 초과되면 LIMIT를 5로 변경하고 쿼리를 10번 다시 실행합니다. 이 단계를 완료하는 데 몇 분 정도 걸릴 수 있습니다.

5. Google Cloud에서 MongoDB Atlas 설정

MongoDB는 풍부한 반구조화된 제품 세부정보와 클릭, 조회수와 같은 유연한 사용자 행동 데이터를 저장합니다.\

MongoDB 클러스터 만들기

Google Cloud 기반 MongoDB Atlas로 이동하여 무료 등급 계정을 선택합니다.
무료 클러스터 등급을 선택하고 클러스터 이름을 입력합니다(예: ecommerce-cluster).
제공업체로 Google Cloud를 선택하고 리전이 Google Cloud 리전 (예: us-central1)과 일치하는지 확인합니다.
배포 만들기를 클릭합니다.
닫기를 클릭합니다.

네트워크 액세스 구성

Atlas 콘솔에서 Database & Network Access로 이동합니다.
IP 액세스 목록을 클릭합니다.
IP 주소 추가를 클릭합니다.
어디서나 액세스를 허용하는 0.0.0.0/0 추가
확인을 클릭합니다.

데이터베이스 사용자 만들기

Atlas 콘솔에서 Database & Network Access로 이동합니다.
데이터베이스 사용자를 클릭합니다.
새 데이터베이스 사용자 추가를 클릭합니다.
인증 방법으로 비밀번호를 선택합니다.
사용자 이름은 store-user, 비밀번호는 storeuser로 입력합니다.
기본 제공 역할 추가를 클릭하고 모든 데이터베이스에 읽기 및 쓰기를 선택합니다.
사용자 추가를 클릭합니다.

연결 문자열 가져오기

데이터베이스 > 클러스터 > 연결로 이동합니다.
애플리케이션 연결에서 드라이버를 클릭합니다.
연결 문자열을 애플리케이션 코드에 추가에 표시된 연결 문자열을 복사합니다. 문자열은 다음과 같이 표시됩니다.
```
mongodb+srv://store-user:<db_password>@ecommerce-cluster.g8vaekh.mongodb.net/?appName=ecommerce-cluster
```
db_password를 MongoDB 비밀번호로 바꿉니다. 이 Codelab에서는 storeuser입니다.

이 연결 문자열을 저장합니다. 나중에 MONGODB_CONNECTION_STRING 환경 변수에 사용됩니다.

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

Atlas 콘솔에서 Database > Clusters > Browse Collections로 이동합니다.
데이터베이스 만들기를 클릭하고 세부정보를 입력합니다.
- 데이터베이스 이름: ecommerce_db
- 컬렉션 이름: product_details_collection
데이터베이스 만들기를 클릭합니다.
데이터 탐색기에서 컬렉션 이름을 선택합니다.
데이터 추가 (+) 아이콘을 클릭한 다음 문서 삽입을 클릭합니다.
product_details_export.json에서 JSON 콘텐츠를 복사하여 문서 삽입 편집기 대화상자에 붙여넣습니다.
삽입을 클릭하여 문서 배열을 삽입하고 문서 192개가 추가되었는지 확인합니다.
데이터 탐색기에서 ecommerce_db 데이터베이스 옆에 있는 컬렉션 만들기 (+)를 클릭합니다.
컬렉션 이름에 user_interactions_collection을 입력하고 컬렉션 만들기를 클릭합니다.
데이터 탐색기에서 user_interactions_collection 컬렉션을 선택합니다.
데이터 추가 (+) 아이콘을 클릭한 다음 문서 삽입을 클릭합니다.
user_interactions_export.json에서 JSON 콘텐츠를 복사하여 문서 삽입 편집기 대화상자에 붙여넣습니다.
문서 삽입을 클릭합니다.

6. BigQuery 설정

BigQuery는 이전 사용자 행동을 집계하고 분석하여 지능형 보고 및 추천을 생성합니다.

데이터세트 만들기

Google Cloud 콘솔에서 BigQuery로 이동합니다.
탐색기 창에서 프로젝트 ID 옆에 있는 점 3개 메뉴를 클릭하고 데이터 세트 만들기를 선택합니다.
데이터 세트 ID에 ecommerce_analytics를 입력합니다.
데이터 세트 만들기를 클릭합니다.

애널리틱스 테이블 만들기

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

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

MCP 도구 상자의 Compute 서비스 계정에 역할 부여

Google에서는 Toolbox에 사용되는 Compute 서비스 계정에 역할을 부여합니다. 이는 MCP 도구 상자가 BigQuery, Secret Manager, 기타 클라우드 서비스에 액세스할 수 있도록 하기 위한 것입니다.

역할을 부여하려면 다음 단계를 완료하세요.

IAM 및 관리자로 이동합니다.
액세스 권한 부여를 클릭합니다.
새 주 구성원 필드에 YOUR_PROJECT_NUMBER-compute@developer.gserviceaccount.com라는 기본 Compute 서비스 계정을 입력합니다. YOUR_PROJECT_NUMBER를 Google Cloud 프로젝트 번호로 바꿉니다.
역할 선택을 클릭합니다.
BigQuery 데이터 편집자 역할을 찾아 선택합니다.
다른 역할 추가를 클릭하고 BigQuery 작업 사용자 역할을 선택합니다.
다른 역할 추가를 클릭하고 Secret Manager 보안 비밀 접근자 역할을 선택합니다.
다른 역할 추가를 클릭하고 편집자 역할을 선택합니다.
저장을 클릭합니다.

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

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

디렉터리 구조 이해하기

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

이 디렉터리에서 다운로드된 파일을 탐색합니다. 다음과 같은 최상위 디렉터리가 있습니다.

UploadImages: 이미지 애셋을 저장합니다. 주로 문서 또는 전자상거래 제품 카탈로그의 시각적 콘텐츠에 사용됩니다.
static: 사용자 인터페이스의 스타일을 지정하고 상호작용을 추가하는 데 사용되는 CSS 및 JavaScript 파일과 같은 애플리케이션의 정적 웹 애셋을 저장합니다 ( 소스).
templates: Python 애플리케이션이 전자상거래 카탈로그의 웹페이지를 동적으로 렌더링하는 데 사용하는 HTML 템플릿 (Flask의 경우 Jinja2일 가능성이 높음)을 저장합니다 ( 소스).
toolbox-implementation: 모델 컨텍스트 프로토콜 (MCP) 도구 상자의 구성 및 구현 세부정보를 저장하여 사전 정의된 도구를 사용한 멀티 DB 데이터베이스 상호작용을 지원합니다.

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

app.py: Flask 백엔드와 다중 데이터베이스 통합을 오케스트레이션합니다.
agentengine.py: Vertex AI 에이전트를 초기화하고 구성하는 핵심 로직입니다.
.env: 데이터베이스 및 스토리지 연결의 보안 비밀을 저장합니다.
tools.yaml: multidb 데이터베이스 작업을 위해 MCP 도구 상자를 구성합니다.
Dockerfile: 컨테이너 이미지 및 환경 설정을 정의합니다.
requirements.txt: 애플리케이션 런타임에 필요한 Python 라이브러리를 나열합니다.
tools.yaml: MCP Toolbox 구성
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 도구 상자와 인터페이스하고 데이터 가져오기 조정을 처리하며 UI의 API 역할을 하는 app.py 경로를 구현합니다.
멀티 에이전트 오케스트레이션: 코드 내에서 ADK 에이전트를 구성하여 사용자 의도를 추론하고, 복잡한 멀티 소스 소매 쿼리를 해결하기 위한 올바른 '도구'를 선택합니다.
프런트엔드 통합: 상호작용 기록 기능, 제품 실적 분석을 파악하는 분석 탭, ADK 멀티 에이전트 채팅을 사용하여 원활한 대화형 쇼핑 환경을 제공하는 전용 '에이전트 탭'이 포함된 제품 카탈로그를 갖춘 index.html 인터페이스를 빌드합니다.

이제 오케스트레이션과 배포를 구현해 보겠습니다.

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

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

MCP 도구 상자를 로컬로 설치

Cloud Shell에서 toolbox-implementation 폴더로 이동합니다.

cd next-26-sessions/BRK2-149-multidb-ecommerce/toolbox-implementation

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

export VERSION=0.29.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

tools.yaml 구성

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

내장된 편집기를 사용하여 tools.yaml 파일을 만들고 수정합니다.
```
cloudshell edit tools.yaml
```
전체 tools.yaml 파일은 GitHub 저장소에서 확인할 수 있습니다. 콘텐츠를 새 tools.yaml 파일에 복사합니다.

이전 단계에서 프로비저닝한 인프라와 일치하도록 호스트, 사용자, 비밀번호, 프로젝트 ID, 연결 문자열을 업데이트합니다.

데이터베이스	필드	예시 값
AlloyDB/BigQuery	`project_id`	`YOUR_PROJECT_ID`
AlloyDB	`region`	`us-central1`
AlloyDB	`cluster`	`ecommerce-cluster`
AlloyDB	`instance`	`ecommerce-cluster-primary`
AlloyDB	`database`	`postgres`
AlloyDB	`password`	`alloydb`
MongoDB	`connection_string`	`mongodb+srv://store-user:storeuser@ecommerce-cluster.urcxr6q.mongodb.net`

MCP 도구 상자의 Compute 서비스 계정에 역할 부여

Google에서는 Toolbox에 사용되는 Compute 서비스 계정에 역할을 부여합니다. 이는 MCP 도구 상자가 AlloyDB에 액세스할 수 있도록 하기 위한 것입니다.

IAM 및 관리자로 이동합니다.
액세스 권한 부여를 클릭합니다.
새 주 구성원 필드에 YOUR_PROJECT_NUMBER-compute@developer.gserviceaccount.com라는 기본 Compute 서비스 계정을 입력합니다. YOUR_PROJECT_NUMBER를 Google Cloud 프로젝트 번호로 바꿉니다.
프로젝트 번호: 프로젝트 번호를 찾으려면 Google Cloud 콘솔에서 Cloud 개요 > 대시보드를 클릭합니다. 프로젝트 정보 카드에 표시된 프로젝트 번호를 확인합니다.
역할 선택을 클릭합니다.
BigQuery 데이터 편집자 역할을 찾아 선택합니다.
다른 역할 추가를 클릭하고 AlloyDB 클라이언트 역할을 선택합니다.
다른 역할 추가를 클릭하고 서비스 사용량 소비자 역할을 선택합니다.
다른 역할 추가를 클릭하고 스토리지 객체 뷰어 역할을 선택합니다.
저장을 클릭합니다.

도구 UI 테스트

Cloud Shell 터미널에서 툴박스를 로컬로 실행하여 UI를 제공합니다.
```
./toolbox --ui
```
Cloud Shell에서 포트 5000으로 웹 미리보기를 열고 도구 페이지로 이동합니다. 예를 들어 세션 URL에 따라 https://5000-cs-71152278760-default.cs-asia-southeast1-cash.cloudshell.dev/ui에서 확인할 수 있습니다.

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

MCP 도구 상자 UI

Cloud Run에 배포

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

새 Cloud Shell 세션을 엽니다.

toolbox-implementation 폴더로 이동합니다.

cd next-26-sessions/BRK2-149-multidb-ecommerce/toolbox-implementation

tools.yaml 구성을 Google Secret Manager에 업로드합니다.
```
gcloud secrets create tools --data-file=tools.yaml
```
참고: 기존 보안 비밀에 새 버전을 추가하려면 다음 명령어를 사용하세요.
```
gcloud secrets versions add tools --data-file=tools.yaml
```

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

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:0.29.0
export PROJECT_ID=$(gcloud config get-value project)

gcloud run deploy toolbox \
    --image $IMAGE \
    --region us-central1 \
    --service-account $(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")-compute@developer.gserviceaccount.com \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080","--ui" \
    --allow-unauthenticated

배포가 완료되면 제공된 Cloud Run 서비스 URL을 기록해 둡니다. 다음과 같이 표시됩니다. https://toolbox-*********-uc.a.run.app/ui

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

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

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

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

추론 엔진 애플리케이션 경로 생성

Google Cloud의 Vertex AI Reasoning Engine을 사용하여 AI 에이전트를 초기화하고 등록하려면 다음 명령어를 실행합니다.

Cloud Shell 터미널에서 BRK2-149-multidb-ecommerce 폴더로 이동합니다.
```
cd next-26-sessions/BRK2-149-multidb-ecommerce
```
requirements.txt를 실행하여 종속 항목을 설치합니다.
```
pip install -r requirements.txt
```
agentengine.py 스크립트를 실행하여 추론 엔진 애플리케이션 경로를 생성합니다.
```
python agentengine.py
```

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

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

환경 변수 구성

.env 파일을 만들고 수정합니다.
```
cloudshell edit .env
```

값을 특정 데이터베이스 연결 및 새 Cloud Run Toolbox URL로 바꿉니다.

# 1. MongoDB Connection String
MONGODB_CONNECTION_STRING="mongodb+srv://<db_user>:<db_password>@cluster0.mongodb.net"

# 2. MCP Toolbox Server Location
# Must match the address where you run the toolbox server
MCP_TOOLBOX_SERVER_URL="https://toolbox-*********-uc.a.run.app"

# 3. Google Cloud Storage Bucket Name
GCS_PRODUCT_BUCKET="ecommerce-app-images"

# 4. Fallback image URL
FALLBACK_IMAGE_URL="https://storage.googleapis.com/ecommerce-media-bold-circuit-492711-n9/fallback.jpg"

# 5. Google Gen AI Vertex AI flag
GOOGLE_GENAI_USE_VERTEXAI=TRUE

# 6. Project ID
PROJECT_ID=codelab-project-491117

# 7. Google Cloud Location of AlloyDB, BigQuery databases
GOOGLE_CLOUD_LOCATION=us-central1

# 8. Reasoning engine application path
APP_NAME=projects/991742412753/locations/us-central1/reasoningEngines/4933254136889081856

# 9. Model ID
MODEL=gemini-1.5-flash-lite

프런트엔드를 Cloud Run에 배포

Cloud Run에 웹 애플리케이션을 배포하여 아키텍처를 완료합니다.
```
gcloud run deploy polyglot --source . --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars \
  MONGODB_CONNECTION_STRING="<MONGODB_CONNECTION_STRING>", \
  MCP_TOOLBOX_SERVER_URL="<MCP_TOOLBOX_SERVER_URL>", \
  GCS_PRODUCT_BUCKET="<GCS_PRODUCT_BUCKET>", \
  FALLBACK_IMAGE_URL="<FALLBACK_IMAGE_URL>", \
  GOOGLE_GENAI_USE_VERTEXAI=TRUE, \
  PROJECT_ID="YOUR_PROJECT_ID", \
  GOOGLE_CLOUD_LOCATION=us-central1, \
  APP_NAME="<YOUR_REASONING_ENGINE_APP_PATH>", \
  MODEL="gemini-1.5-flash-lite"
```
다음 값을 바꿉니다.
- YOUR_PROJECT_ID: Google Cloud 프로젝트 ID입니다.
- YOUR_REASONING_ENGINE_APP_PATH: python agentengine.py 실행 결과입니다(예: projects/991742412753/locations/us-central1/reasoningEngines/4933254136889081856).
- MCP_TOOLBOX_SERVER_URL: MCP 도구 상자 서버의 URL(예: https://toolbox-*********-uc.a.run.app)
- GCS_PRODUCT_BUCKET: Google Cloud Storage 버킷의 이름입니다(예: ecommerce-app-images).
- MONGODB_CONNECTION_STRING: MongoDB 데이터베이스의 연결 문자열입니다(예: mongodb+srv://store-user:storeuser@ecommerce-cluster.g8vaekh.mongodb.net).
- FALLBACK_IMAGE_URL: 대체 이미지의 URL(예: https://storage.googleapis.com/ecommerce-app-images/fallback.jpg)
배포가 실패하면 gcloud auth login 명령어를 실행하여 배포를 승인한 다음 배포 명령어를 다시 실행합니다.

이제 애플리케이션이 작동합니다. Cloud Run에서 제공하는 서비스 URL을 열어 Multidb Ecommerce 카탈로그를 확인합니다. 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 multi-db-app --region us-central1 --quiet
bq rm -r -f -d $PROJECT_ID:ecommerce_analytics
gcloud storage rm --recursive gs://ecommerce-app-images
gcloud alloydb clusters delete ecommerce-cluster --region us-central1 --force --quiet

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

gcloud projects delete $PROJECT_ID

12. 축하합니다

축하합니다. 크로스 클라우드 멀티 DB 아키텍처를 성공적으로 구축했습니다.

MCP 도구 상자가 최신 전문 애플리케이션의 아키텍처 접착제 역할을 하는 방법을 보여주었습니다. 올바른 데이터베이스를 올바른 작업에 매칭하면 다음과 같은 결과를 얻을 수 있습니다.

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

참조 문서

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

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

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