Gemini 3 Flash 및 AlloyDB AI로 자율 공급망 구축

1. 개요

'읽는 챗봇'의 시대가 끝나고 있습니다. 에이전트 비전의 시대가 다가오고 있습니다.

이 Codelab에서는 추측하지 않는 AI 시스템을 빌드하는 방법인 결정론적 AI 엔지니어링을 구현합니다. 표준 AI 모델은 복잡한 이미지의 항목 수를 세어 달라는 요청을 받으면 '할루시네이션' (추측)하는 경우가 많습니다. 공급망에서는 추측이 위험합니다. 실제로 15개의 상품이 있는데 AI가 12개라고 추측하면 비용이 많이 드는 오류가 발생합니다.

Gemini 3 Flash의 새로운 생각하기, 행동하기, 관찰하기 루프를 활용하여 자율 공급망 에이전트를 빌드할 예정입니다. 단순히 살펴보는 것이 아니라 조사합니다.

결정론적 아키텍처

'블라인드' 및 '기억상실' 시스템으로 시작합니다. 다음과 같이 감각을 하나씩 수동으로 '깨워'야 합니다.

1. The Eyes (Vision Agent): 코드 실행과 함께 Gemini 3 Flash를 사용 설정합니다. 숫자를 추측하기 위해 토큰을 예측하는 대신 모델은 Python 코드 (OpenCV)를 작성하여 픽셀을 결정적으로 계산합니다.
2. 메모리 (공급업체 에이전트): ScaNN (확장 가능한 최근접 이웃)을 사용하여 AlloyDB AI를 사용 설정합니다. 이를 통해 상담사는 수백만 개의 옵션 중에서 부품의 정확한 공급업체를 밀리초 만에 떠올릴 수 있습니다.
3. 핸드셰이크 (A2A 프로토콜): 표준화된 agent_card.json을 사용하여 에이전트 간 통신을 지원하여 Vision Agent가 Supplier Agent로부터 자율적으로 재고를 주문할 수 있습니다.

빌드할 항목

• 카메라 피드에서 '시각적 수학'을 실행하는 비전 에이전트
• 고속 벡터 검색을 위해 AlloyDB ScaNN으로 지원되는 공급업체 에이전트
• 자율 루프를 시각화하는 실시간 WebSocket 업데이트가 있는 Control Tower 프런트엔드

학습할 내용

• Gemini API를 사용하여 gemini-3-flash-preview로 Agentic Vision을 사용 설정하는 방법
• AlloyDB에서 <=> (코사인 거리) 연산자를 사용하여 벡터 검색을 구현하는 방법
• 인증 프록시를 사용하여 Cloud Shell을 AlloyDB에 연결하는 방법

요구사항

• 브라우저(Chrome 또는 Firefox 등)
• 결제가 사용 설정된 Google Cloud 프로젝트.
• 비전 에이전트용 Gemini API 키 (Google AI Studio에서 무료 등급 사용 가능)

2. 시작하기 전에

프로젝트 만들기

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

이 Codelab을 사용해 보려면 GCP 무료 체험판 결제 크레딧 링크(https://bit.ly/cvs14-ghj)를 사용하세요.

이 링크를 사용하여 크레딧을 사용하려면 어떻게 해야 하나요? 추천

3. Google Cloud에서 실행되는 명령줄 환경인 Cloud Shell을 사용합니다. Google Cloud 콘솔 상단에서 Cloud Shell 활성화를 클릭합니다.

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

gcloud auth list

작업이 끝났습니다.

이제 원클릭 설정을 진행할 수 있습니다. 다음 섹션에서는 다음을 설명합니다.

• 자동으로 Cloud Shell 열기
• 저장소 복제
• 대화형 튜토리얼에서 전체 설정을 안내합니다.

3. Cloud Shell에서 클릭 한 번으로 설정

설정을 안내 Cloud Shell 튜토리얼로 간소화했습니다. 인프라 프로비저닝, AlloyDB 설정, 인증 프록시 구성, 데이터베이스 시딩 등 모든 것이 자동화됩니다.

Cloud Shell 튜토리얼 시작

⚠️ 중요 - 클릭하기 전: 아래 버튼을 클릭하면 'Cloud Shell에서 열기'를 묻는 보안 대화상자가 표시됩니다. 이는 저장소 클론 전에 표시됩니다.

상담사는 다음 작업을 수행해야 합니다.

1. ✅ '저장소 신뢰' 체크박스를 선택합니다.
2. ✅ '확인'을 클릭합니다.

이 명령어가 없으면 저장소가 클론되지 않습니다.

준비되셨나요? 클릭하여 단계별 튜토리얼로 프로젝트를 엽니다.

원클릭 실행

다음 단계:

1. 저장소가 사전 클론된 상태로 Cloud Shell이 열립니다.
2. 오른쪽에 단계별 안내가 포함된 튜토리얼 패널이 표시됩니다.
3. 다음 사항이 안내됩니다.

• Gemini API 키 가져오기 (무료 등급 사용 가능)
• 터미널에서 GCP 프로젝트 설정
• 설정 실행 (API 확인, 필요한 경우 사용 설정, AlloyDB 프로비저닝: 약 15분)
• 2가지 주요 코드 변경사항 적용 (비전 및 메모리 사용 설정)
• 에이전트 카드 만들기 (A2A 프로토콜)
• 모든 서비스 시작

이 튜토리얼은 대화형으로, 각 단계에 번호가 매겨져 있으며 진행 상황을 추적합니다.

📌 자동화됨: 설정 스크립트가 인증, API, 프로젝트 구성을 확인합니다. 주의가 필요한 사항이 있으면 메시지가 표시됩니다.

💡 다시 시작해도 안전: 설정이 멈추거나 실패하면 sh setup.sh를 안전하게 다시 실행할 수 있습니다. 스크립트가 기존 AlloyDB 인스턴스를 감지하고 프로비저닝을 건너뛰고 중단한 부분부터 시작합니다.

대안: 수동 설정

수동으로 관리하는 것을 선호하는 경우:

1. Cloud Shell을 열고 프로젝트가 설정되었는지 확인

gcloud config get-value project

2. 필요한 경우 프로젝트를 설정합니다.

gcloud config set project YOUR_PROJECT_ID

3. 저장소 복제

git clone https://github.com/MohitBhimrajka/visual-commerce-gemini-3-alloydb.git
cd visual-commerce-gemini-3-alloydb

4. 설정 실행

sh setup.sh

설정 스크립트의 화면 안내를 따릅니다.

다음 단계: 튜토리얼에서 나머지 단계를 안내합니다. 완료되면 섹션 4로 계속 진행하여 내부적으로 어떤 일이 일어났는지 확인합니다.

4. 비하인드 스토리: 인증 프록시 및 데이터베이스 시딩

참고: 전체 Cloud Shell 튜토리얼을 사용한 경우 이 모든 과정이 자동화됩니다. 이 섹션에서는 내부적으로 어떤 일이 일어났는지 설명합니다.

문제: AlloyDB는 비공개 VPC 내에 있습니다. Cloud Shell은 이 범위 밖에 있습니다. 직접 연결할 수 없습니다.

해결 방법: AlloyDB 인증 프록시는 Cloud Shell의 127.0.0.1:5432에서 AlloyDB 인스턴스로 보안 IAM 인증 터널을 만듭니다. 인스턴스에 공개 IP가 사용 설정되어 있으면 프록시가 이를 사용하고, 그렇지 않으면 VPC의 비공개 IP를 통해 연결합니다.

setup.sh가 한 작업

1. AlloyDB 인스턴스 (클러스터, 리전, 프로젝트)가 자동 감지됨
2. 모든 사용자 인증 정보 (GEMINI_API_KEY, DB_PASS, AlloyDB 세부정보)를 사용하여 .env를 만들었습니다.
3. 인증 프록시를 다운로드하고 시작했습니다 (해당하는 경우 –public-ip 사용).
4. 샘플 인벤토리 부품 8개와 ScaNN 색인으로 데이터베이스를 시딩했습니다.

.env 파일이 준비되었습니다. 향후 모든 실행에서 사용자 인증 정보가 자동으로 로드됩니다.

작동 여부 확인

아직 저장소 루트에 있는지 확인합니다.

pwd  # Should end with: visual-commerce-gemini-3-alloydb

인증 프록시가 실행 중인지 확인

ps aux | grep alloydb-auth-proxy

생성된 항목

• 8개 파트와 768차원 임베딩이 있는 인벤토리 테이블
• 빠른 벡터 검색을 위한 ScaNN 색인 (idx_inventory_scann)

일반적인 오류:

• 'DB_PASS가 설정되지 않음': sh setup.sh를 다시 실행하여 .env를 다시 만듭니다.
• '연결 거부됨': 인증 프록시에 시간이 더 필요할 수 있습니다. 30초 동안 기다렸다가 다시 시도합니다.
• '인스턴스를 찾을 수 없음': 배포 확인: gcloud alloydb instances list
• '버스 오류' (인증 프록시가 종료됨): 바이너리 손상 수정: rm alloydb-auth-proxy && sh setup.sh

5. 1단계: 메모리 (공급업체 에이전트)

참고: Cloud Shell 튜토리얼을 사용한 경우 이 코드 변경사항이 이미 적용되어 있습니다. 이 섹션에서는 이 기능이 중요한 이유와 작동 방식을 설명합니다.

공급업체 에이전트는 AlloyDB ScaNN을 사용하여 수백만 개의 부품을 기억합니다. A2A 서버로 시작한 다음 벡터 쿼리를 수정합니다.

감사: 기억상실증

지금 자리표시자 SQL로 Supplier Agent를 쿼리하면 가장 근접한 일치 항목이 아닌 첫 번째 행이 반환됩니다. 유사성 개념이 없습니다. 기억상실증 환자입니다.

공급업체 에이전트 시작

A2A 서버 (main.py)는 inventory.py의 비즈니스 로직에 프로토콜을 연결하는 agent_executor.py에 위임합니다.

💡 문제 해결 도움말: '주소가 이미 사용 중입니다' 오류가 표시되면 기존 프로세스를 종료하고 다시 시도하세요.

pkill -f uvicorn #Kill all uvicorn processes

1단계: 에이전트 디렉터리로 이동

cd agents/supplier-agent

2단계: 종속 항목 설치

pip install -r requirements.txt

3단계: 에이전트 서버 시작하기

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

> /dev/null 2>&1 &는 서버를 백그라운드에서 실행하고 출력을 억제하여 터미널을 방해하지 않습니다.

4단계: 에이전트가 실행 중인지 확인 (시작 후 2~3초 대기)

curl http://localhost:8082/.well-known/agent-card.json

예상 출력: 에이전트 구성이 포함된 JSON (오류 없이 반환되어야 함)

실제 시맨틱 임베딩

설정 중에 데이터베이스는 Google 생성형 AI SDK의 text-embedding-005 모델을 통해 생성된 실제 시맨틱 삽입으로 시딩되었습니다. 이렇게 하면 무작위 벡터가 아닌 정확한 유사성 일치가 보장됩니다. 시드 프로세스는 병렬 임베딩 생성을 사용하여 각 부분의 시맨틱 의미를 포착하는 의미 있는 768차원 벡터를 생성하는 데 샘플 항목 13개에 대해 약 10초가 걸립니다.

AlloyDB 우회: ScaNN이 필요한 이유

참고: 표준 벡터 검색 (HNSW)은 메모리를 많이 사용합니다. 인벤토리가 1억 개의 부품으로 늘어나면 색인이 RAM에 비해 너무 커집니다. ScaNN (확장 가능한 최근접 이웃)은 벡터 양자화를 사용합니다. 색인이 CPU의 L2 캐시에 맞도록 벡터를 압축합니다. 따라서 표준 HNSW보다 최대 10배 빠릅니다.

해결 방법: <=> 연산자 구현

에이전트가 자리표시자 쿼리와 함께 제공됩니다. ScaNN 벡터 검색을 사용 설정해야 합니다.

1단계: 인벤토리 파일 열기

cd agents/supplier-agent

2단계: inventory.py에서 TODO 찾기

47~60번째 줄에서 find_supplier() 함수를 찾습니다. 다음 내용이 표시됩니다.

# ============================================================
# CODELAB STEP 1: Implement ScaNN Vector Search
# ============================================================
# TODO: Replace this placeholder query with ScaNN vector search

sql = "SELECT part_name, supplier_name FROM inventory LIMIT 1;"
cursor.execute(sql)

3단계: 자리표시자 SQL을 ScaNN 벡터 검색으로 바꾸기

다음 두 줄을 삭제합니다.

sql = "SELECT part_name, supplier_name FROM inventory LIMIT 1;"
cursor.execute(sql)

다음으로 바꿉니다.

sql = """
SELECT part_name, supplier_name
FROM inventory
ORDER BY part_embedding <=> %s::vector
LIMIT 1;
"""
cursor.execute(sql, (embedding_vector,))

기능:

• <=>는 PostgreSQL의 코사인 거리 연산자입니다.
• ORDER BY part_embedding <=> %s::vector는 가장 가까운 일치 항목 (거리가 가장 짧음 = 의미가 가장 가까움)을 찾습니다.
• %s::vector는 임베딩 배열을 PostgreSQL의 벡터 유형으로 변환합니다.
• LIMIT 1은 가장 일치하는 항목만 반환합니다.
• ScaNN 색인은 이 쿼리를 자동으로 가속화합니다.

4단계: 파일 저장 (Ctrl+S 또는 Cmd+S)

이제 에이전트가 무작위 결과를 반환하는 대신 시맨틱 검색을 사용합니다.

인증

A2A 검색 및 인벤토리를 테스트합니다.

curl http://localhost:8082/.well-known/agent-card.json

python3 -c "
from inventory import find_supplier
import json
vec = [0.1]*768
r = find_supplier(vec)
if r:
    result = {'part': r[0], 'supplier': r[1]}
    if len(r) > 2:
        result['distance'] = float(r[2]) if r[2] else None
    print(json.dumps(result))
else:
    print('No result found')
"

예상: agent-card.json이 에이전트 카드를 반환합니다. Python 스니펫은 시드된 데이터에서 부품과 공급업체를 반환합니다.

일반적인 오류:

• '해당 파일 또는 디렉터리가 없음': 저장소 루트에 있지 않습니다. cd를 실행하여 홈으로 이동한 다음 cd visual-commerce-gemini-3-alloydb를 실행하거나 pwd를 사용하여 현재 위치를 확인합니다.
• 포트 8082 사용 중: 기존 프로세스 종료: lsof -ti:8082 | xargs kill -9
• ModuleNotFoundError: 종속 항목 설치: pip install -r requirements.txt
• 데이터베이스 연결 실패: 인증 프록시가 계속 실행 중인지 확인하세요.
• 확인 스크립트 실패: 4단계에서 시드가 성공적으로 완료되었는지 확인합니다.

6. 2단계: 눈 (비전 에이전트)

참고: Cloud Shell 튜토리얼을 사용한 경우 코드 실행이 이미 사용 설정되어 있습니다. 이 섹션에서는 아키텍처와 이 접근 방식이 허위 정보를 없애는 이유를 설명합니다.

데이터베이스에 액세스할 수 있는 동안 Gemini 3 Flash를 사용하여 눈을 깨워 보겠습니다. Vision Agent는 코드 실행을 통해 '시각적 수학'을 실행합니다. A2A 서버 (main.py)는 agent_executor.py에 위임하며, agent_executor.py는 Gemini 분석을 위해 agent.py를 호출합니다.

감사: 할루시네이션

표준 멀티모달 모델에 '이 어수선한 이미지에 상자가 몇 개 있어?'라고 물으면 이미지를 정적 스냅샷으로 처리하고 추측합니다.

• 모델이 '상자가 12개 정도 있습니다.'라고 말합니다.
• 실제: 상자가 15개 있습니다.
• 결과: 공급망 실패

해결 방법: 사고-행동-관찰 루프 활성화

모델이 결정적으로 계산할 수 있도록 Python (OpenCV)을 작성할 수 있도록 코드 실행 및 ThinkingConfig를 사용 설정합니다.

1. agents/vision-agent/agent.py를 엽니다 .
2. GenerateContentConfig 섹션을 찾습니다.
3. thinking_config=types.ThinkingConfig(...) 블록과 tools=[types.Tool(code_execution=...)]을 모두 주석 해제합니다.
4. 클라이언트는 환경에서 GEMINI_API_KEY를 사용하도록 이미 구성되어 있습니다.

도움말: thinking_level="LOW"는 속도와 정확성의 균형을 맞춥니다. 유효한 값: 'MINIMAL', 'LOW', 'MEDIUM', 'HIGH' google-genai>=1.56.0이 필요합니다.

아키텍처 참고: Vision Agent는 Gemini API (API 키)를 사용하고 Supplier Agent는 Vertex AI 임베딩 (GCP 사용자 인증 정보)을 사용합니다. 이 하이브리드 접근 방식을 사용하면 비전 구성요소를 간단하게 유지하면서 엔터프라이즈급 데이터베이스 기능을 유지할 수 있습니다.

파일: agents/vision-agent/agent.py

config = types.GenerateContentConfig(
    temperature=0,
    # CODELAB STEP 1: Uncomment to enable reasoning
    thinking_config=types.ThinkingConfig(
        thinking_level="LOW",  # Valid: "MINIMAL", "LOW", "MEDIUM", "HIGH"
        include_thoughts=False    # Set to True for debugging
    ),
    # CODELAB STEP 2: Uncomment to enable code execution
    tools=[types.Tool(code_execution=types.ToolCodeExecution)]
)

thinking_level이 'LOW'인 이유

이 특정 작업 (코드 실행을 통한 항목 수 세기)의 경우 'LOW'는 다음을 수행할 수 있는 충분한 추론 예산을 제공합니다.

• Python 스크립트 구조 계획
• 사용할 이미지 처리 접근 방식 결정
• 개수가 경계 상자 수와 일치하는지 확인합니다.

'높음'을 사용하면 결정론적 작업의 정확성을 개선하지 않고도 지연 시간과 비용이 2~3배 증가합니다. 복잡한 다단계 추론 (예: '이 공급망 중단을 분석하고 3개의 대체 공급업체를 추천해 줘').

비용 대비 성능 최적화는 프로덕션 AI 엔지니어링의 핵심 기술입니다. 추론 깊이를 작업 복잡도에 맞추세요.

Vision 에이전트 시작

🔄 경로 확인: 아직 agents/supplier-agent/에 있는 경우 먼저 cd ../..를 사용하여 저장소 루트로 돌아갑니다.

1단계: 비전 에이전트 디렉터리로 이동하기

cd agents/vision-agent

2단계: 종속 항목 설치

pip install -r requirements.txt

3단계: 비전 에이전트 서버 시작하기

uvicorn main:app --host 0.0.0.0 --port 8081 > /dev/null 2>&1 &

> /dev/null 2>&1 &는 서버를 백그라운드에서 실행하고 출력을 억제하여 터미널을 방해하지 않습니다.

인증

A2A 검색 테스트:

curl http://localhost:8081/.well-known/agent-card.json

예상: 에이전트 이름과 기술이 포함된 JSON 8단계에서 Control Tower UI를 사용하여 실제 비전 카운팅을 테스트합니다.

일반적인 오류:

• '해당 파일 또는 디렉터리가 없음': 저장소 루트에 있지 않습니다. cd ../.. 를 사용하여 저장소 루트로 돌아가거나 pwd를 사용하여 위치를 확인합니다.
• 포트 8081 사용 중: 기존 프로세스 종료: lsof -ti:8081 | xargs kill -9
• GEMINI_API_KEY가 설정되지 않음: cat .env | grep GEMINI_API_KEY를 사용하여 저장소 루트에 .env 파일이 있는지 확인하세요.
• API 키가 잘못됨: 키가 올바르고 만료되지 않았는지 확인합니다.
• google-genai를 찾을 수 없음: 종속 항목을 설치합니다(pip install -r requirements.txt).

7. 3단계: 핸드셰이크 (A2A 에이전트 카드)

참고: Cloud Shell 튜토리얼을 사용한 경우 이 에이전트 카드를 이미 만든 것입니다. 이 섹션에서는 A2A 프로토콜과 플러그 앤 플레이 에이전트 구성이 가능한 이유를 설명합니다.

에이전트는 문제를 확인하고 (비전) 공급업체를 알고 있습니다 (메모리). A2A 프로토콜을 사용하면 프런트엔드가 카드를 읽어 각 에이전트와 통신하는 방법을 학습하는 동적 검색이 가능합니다.

A2A와 기존 REST API 비교

측면	기존 REST	A2A 프로토콜
엔드포인트 검색	구성에서 하드코딩된 URL	/.well-known/agent-card.json을 통한 동적 방식
기능 설명	API 문서 (사람용)	기술 (컴퓨터가 읽을 수 있음)
통합	서비스별 수동 코드	시맨틱 매칭: '인벤토리 검색이 필요해' → 스킬 검색
새 상담사가 추가됨	모든 클라이언트의 구성 업데이트	구성 불필요 - 자동 검색

실제 이점: 기존 마이크로서비스에서는 세 번째 '물류 대행업체'를 추가하는 경우 URL과 API 계약으로 Control Tower의 코드를 업데이트해야 합니다. A2A를 사용하면 Control Tower가 이를 자동으로 검색하고 자연어 기술 설명을 통해 기능을 이해합니다.

이러한 이유로 A2A는 자율 시스템의 아키텍처 패턴인 플러그 앤 플레이 에이전트 구성을 지원합니다.

해결 방법: 상담사 카드 만들기

공급업체 에이전트가 할 수 있는 일을 정의해야 합니다.

1. agents/supplier-agent/agent_card_skeleton.json을 agents/supplier-agent/agent_card.json에 복사합니다.
2. 파일을 수정하여 자리표시자를 바꿉니다.

변경 전 (스켈레톤):

{
  "name": "___FILL: agent-name ___",
  "description": "___FILL: what-this-agent-does ___"
}

변경 후:

{
  "name": "Acme Supplier Agent",
  "description": "Autonomous fulfillment for industrial parts via AlloyDB ScaNN.",
  "version": "1.0.0",
  "skills": [{
    "id": "search_inventory",
    "name": "Search Inventory",
    "description": "Searches the warehouse database for semantic matches using AlloyDB ScaNN vector search.",
    "tags": ["inventory", "search", "alloydb"],
    "examples": ["Find stock for Industrial Widget X-9", "Who supplies ball bearings?"]
  }]
}

3. 새 카드를 로드하도록 공급업체 에이전트를 다시 시작합니다.

1단계: 실행 중인 에이전트 중지하기

pkill -f "uvicorn main:app.*8082"

2단계: 에이전트 디렉터리로 이동하기

cd agents/supplier-agent

3단계: 에이전트 다시 시작하기

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

> /dev/null 2>&1 &는 서버를 백그라운드에서 실행하고 출력을 억제하여 터미널을 방해하지 않습니다.

4단계: 새 상담사 카드 확인 (시작 후 2~3초 대기)

curl http://localhost:8082/.well-known/agent-card.json

예상 출력: 이름, 설명, 기술이 입력된 JSON

8. 4단계: 관제탑

참고: Cloud Shell 튜토리얼을 사용한 경우 서비스가 이미 실행 중입니다. 아래의 '시스템 테스트' 섹션으로 건너뛰어 관제탑에 액세스하고 자율 워크플로가 작동하는 것을 확인하세요.

FastAPI + WebSockets로 Control Tower 프런트엔드를 실행합니다. A2A를 통해 에이전트를 검색하고 실시간 업데이트를 통해 전체 루프를 조정합니다.

모든 서비스 시작

모든 서비스를 시작하는 가장 쉬운 방법:

저장소 루트에 있는지 확인

pwd  # Should end with: visual-commerce-gemini-3-alloydb

그런 다음 다음 단계를 따르세요.

sh run.sh

이 단일 명령어는 다음을 시작합니다.

• AlloyDB 인증 프록시 (실행되지 않은 경우)
• 포트 8081의 Vision Agent
• 포트 8082의 공급업체 에이전트
• 포트 8080의 Control Tower

모든 서비스가 초기화될 때까지 약 10초 동안 기다립니다.

💡 문제 해결 도움말: run.sh가 'address already in use'(주소가 이미 사용 중임) 오류와 함께 실패하는 경우 다음 단계를 따르세요.

모든 서비스를 종료하고 다시 시도하세요.

pkill -f uvicorn

sh run.sh

이 문제는 이전 시도에서 서비스가 여전히 실행 중인 경우 발생합니다.

시스템 테스트

관제탑에 액세스:

1. Cloud Shell 툴바에서 웹 미리보기 버튼 (눈 아이콘 👁️)을 클릭합니다.
2. '포트 8080에서 미리보기'를 선택합니다.
3. 새 탭에서 Control Tower 대시보드가 열립니다.

참고: 프런트엔드는 실시간 상담사 업데이트를 위해 실시간 WebSocket을 사용합니다. 에이전트가 생각하고 분석하고 행동할 때 에이전트 카드가 업데이트됩니다. 페이지를 새로고침할 필요가 없습니다.

데모 실행:

1. 오른쪽 상단: 연결 상태 (녹색 '라이브' 점), 데모/자동 모드 전환, 오디오 컨트롤
2. 센터: 이미지 업로드 및 분석 시각화가 포함된 기본 워크플로 캔버스
3. 측면 패널 (분석 중에 표시됨): 워크플로 타임라인 (왼쪽), 진행 상황 추적 및 코드 뷰어 (오른쪽)

옵션 1: 빠른 시작 (권장)

1. 홈페이지에 샘플 이미지가 포함된 '빠른 시작' 섹션이 표시됩니다.
2. 샘플 이미지를 클릭하여 분석을 자동 시작
3. 자율 워크플로를 시청합니다 (약 30~45초).

옵션 2: 직접 업로드

1. 창고/선반 이미지를 드래그 앤 드롭하거나 (PNG, JPG, 최대 10MB) 클릭하여 찾아보기
2. '자율 워크플로 시작'을 클릭합니다.
3. 4단계 파이프라인 관찰

결과:

1. 에이전트 검색: A2A 프로토콜 모달에는 Vision Agent 및 Supplier Agent 카드와 해당 기술 및 엔드포인트가 표시됩니다.
2. 시각적 분석: Gemini 3 Flash는 Python 코드 (OpenCV)를 생성하고 실행하여 항목을 계산합니다. 진행률 표시줄에 하위 단계가 표시됩니다. 감지된 항목에 오버레이된 경계 상자 결과 배지에 '✓ 코드 검증됨' 또는 '~ 추정됨'이 표시됨
3. 공급업체 일치: AlloyDB ScaNN 벡터 검색 애니메이션 검색어 디스플레이 (예: '산업용 금속 상자'). 결과 카드에 일치하는 부품, 공급업체, 신뢰도 점수가 표시됨
4. 주문 완료: 주문 ID, 수량, 세부정보가 포함된 영수증 카드

도움말: 프레젠테이션을 위해 각 단계에서 일시중지하려면 데모 모드를 사용 설정 (오른쪽 상단)하세요. AUTO 모드에서는 워크플로가 지속적으로 실행됩니다.

무슨 일이 일어났나요?

Control Tower는 A2A 프로토콜을 사용하여 /.well-known/agent-card.json을 통해 두 에이전트를 모두 검색하고, 시각 분석 (코드 실행이 포함된 Gemini 3 Flash)을 오케스트레이션하고, 벡터 검색 (AlloyDB ScaNN)을 실행하고, 자율 주문을 했습니다. 이 모든 작업은 실시간 WebSocket 업데이트를 통해 이루어졌습니다. 각 에이전트는 A2A 표준을 통해 기능을 노출하므로 맞춤 SDK 없이 플러그 앤 플레이 구성이 가능합니다. 자세히 알아보기: A2A 프로토콜

문제 해결

경로 관련 오류:

• 명령어를 실행할 때 '해당 파일 또는 디렉터리가 없음' 오류가 표시됨: 저장소 루트에 있지 않습니다.

# Check where you are
pwd

# If you're lost, navigate to home and back to repo
cd
cd visual-commerce-gemini-3-alloydb

서비스 오류:

• 'Address already in use': 이전 실행의 프로세스가 아직 활성 상태입니다.

# Kill all services and restart
pkill -f uvicorn
sh run.sh  # Or manually restart individual agents

• 서비스가 시작되지 않음: 포트가 사용 중인지 확인합니다.

# Check which processes are using the ports
lsof -i :8080  # Control Tower
lsof -i :8081  # Vision Agent
lsof -i :8082  # Supplier Agent

• AlloyDB에 대한 '연결 거부': 인증 프록시가 실행 중인지 확인합니다.

ps aux | grep alloydb-auth-proxy

AlloyDB 연결 문제:

127.0.0.1, 포트 5432의 서버 연결에 실패한 경우 다음 단계를 따르세요.

127.0.0.1, 포트 5432의 서버에 연결할 수 없다는 메시지가 표시되는 경우:

1. 인증 프록시 확인: ps aux | grep alloydb-auth-proxy
2. 공용 IP 사용 설정 확인: gcloud alloydb instances describe INSTANCE_NAME –cluster=CLUSTER_NAME –region=us-central1 –format="value(ipAddress)"
3. 로컬 개발 (Cloud Shell 아님):
4. 문제: Cloud Shell은 자동으로 작동하지만 로컬 머신에는 승인된 네트워크가 필요합니다.
5. 해결 방법: sh setup.sh를 다시 실행하고 메시지가 표시되면 옵션 1 (0.0.0.0/0 승인)을 선택합니다.
6. 보안 참고사항: 0.0.0.0/0을 사용하더라도 연결에는 다음이 필요합니다.
7. 유효한 GCP 사용자 인증 정보 (애플리케이션 기본 사용자 인증 정보)
8. 데이터베이스 비밀번호
9. mTLS 암호화 (인증 프록시에서 처리)

9. 삭제

요금이 발생하지 않도록 자동 정리 스크립트로 모든 리소스를 삭제합니다.

# From repo root
sh cleanup.sh

다음 항목이 안전하게 삭제됩니다.

• AlloyDB 클러스터 (기본 비용 동인)
• Cloud Run 서비스 (배포된 경우)
• 연결된 서비스 계정

스크립트에서 삭제하기 전에 확인 메시지를 표시합니다.

10. 참조 및 추가 자료

이 Codelab의 모든 기술적 주장은 공식 Google Cloud 및 Google AI 문서에서 확인되었습니다.

공식 문서

Gemini 3 Flash:

• 코드 실행 API: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/code-execution-api
• 개발자 가이드: https://ai.google.dev/gemini-api/docs/gemini-3
• 모델 문서: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-flash
• 모델 카드: https://deepmind.google/models/gemini/flash/

AlloyDB AI 및 ScaNN:

• ScaNN 성능 벤치마크: https://cloud.google.com/blog/products/databases/how-scann-for-alloydb-vector-search-compares-to-pgvector-hnsw
• ScaNN 색인 이해: https://cloud.google.com/blog/products/databases/understanding-the-scann-index-in-alloydb
• AlloyDB AI 심층 분석: https://cloud.google.com/blog/products/databases/alloydb-ais-scann-index-improves-search-on-all-kinds-of-data
• 튜닝 권장사항: https://docs.cloud.google.com/alloydb/docs/ai/best-practices-tuning-scann
• AlloyDB 문서: https://cloud.google.com/alloydb/docs

가격 정보:

• Gemini API 가격: https://ai.google.dev/gemini-api/docs/pricing
• AlloyDB 가격 책정: https://cloud.google.com/alloydb/pricing
• Vertex AI 가격 책정: https://cloud.google.com/vertex-ai/pricing

인증된 성능 주장

기능	클레임	소스
ScaNN과 HNSW 비교 (필터링됨)	속도 10배 개선	Google Cloud 블로그 (인증됨)
ScaNN과 HNSW (표준) 비교	4배 더 빠름	Google Cloud 블로그 (인증됨)
ScaNN 메모리 사용량	3~4배 작음	Google Cloud 블로그 (인증됨)
ScaNN 색인 빌드 시간	8배 더 빠름	Google Cloud 블로그 (인증됨)
코드 실행 제한 시간	최대 30초	Google Cloud 문서 (인증됨)
코드 실행 파일 I/O	지원되지 않음	Google Cloud 문서 (인증됨)
온도=0 동작	결정론적 출력	커뮤니티 확인 완료

추가 리소스

상담사 간 (A2A) 프로토콜:

• A2A는 에이전트 검색 및 통신을 표준화합니다.
• /.well-known/agent-card.json에 게재되는 상담사 카드
• 자율 에이전트 협업을 위한 새로운 표준

ScaNN 연구:

• 12년간의 Google 연구를 기반으로 함
• 수십억 규모의 Google 검색, YouTube 지원
• 정식 버전 출시: 2024년 10월
• 수백만에서 수십억 개의 벡터에 적합한 최초의 PostgreSQL 벡터 색인

11. 챌린지 모드: 주체성 기술 레벨업

작동하는 자율 공급망을 구축했습니다. 더 나아가 볼까요? 이러한 챌린지에서는 학습한 패턴을 새로운 문제에 적용합니다.

챌린지 1: 이미지 기반 검색 (멀티모달 임베딩)

현재 흐름: Vision Agent가 항목을 계산하고 → 텍스트 쿼리를 생성하고 → Supplier Agent가 텍스트를 삽입하고 → AlloyDB를 검색합니다.

챌린지: 텍스트를 완전히 우회하여 잘린 이미지를 공급업체 상담사에게 직접 전송합니다.

힌트:

1. Vision 에이전트의 코드 실행은 선반 이미지에서 개별 항목을 자를 수 있습니다.
2. Vertex AI의 multimodalembedding@001 모델은 이미지를 직접 삽입할 수 있습니다.
3. 텍스트 대신 이미지 바이트를 허용하도록 inventory.py 수정
4. '허용: image/jpeg 또는 text'를 나타내도록 A2A 기술 설명을 업데이트합니다.

중요한 이유: 시각적 검색은 외관이 복잡한 부분 (색상 변화, 손상, 포장 차이)에서 더 정확합니다.

과제 2: 관측 가능성 - 투명성을 통한 신뢰

현재 상태: 시스템은 작동하지만 '내부'를 볼 수 없음

챌린지: AlloyDB의 쿼리 로그를 검사하여 벡터 검색이 실행되고 있음을 증명합니다.

단계:

• 쿼리 통계는 AlloyDB에서 기본적으로 사용 설정되어 있습니다. 확인하려면 다음을 실행합니다.

gcloud alloydb instances describe INSTANCE_NAME \
  --cluster=CLUSTER_NAME \
  --region=us-central1 \
  --format="value(queryInsightsConfig.queryPlansPerMinute)"

• UI를 통해 공급업체 검색 실행
• 실제로 실행된 SQL을 확인합니다.

gcloud logging read \
  'resource.type="alloydb.googleapis.com/Instance" AND textPayload:"ORDER BY part_embedding"' \
  --limit 5 \
  --format=json

예상 출력: 실행 시간이 포함된 정확한 ORDER BY part_embedding <=> $1::vector LIMIT 1 쿼리가 표시됩니다.

중요한 이유: 관측 가능성은 신뢰를 구축합니다. 이해관계자가 '이 에이전트는 어떻게 결정을 내리나요?'라고 물으면 출력뿐만 아니라 쿼리 계획도 보여줄 수 있습니다.

과제 3: 멀티 에이전트 구성

챌린지: 창고 위치와 상품 무게를 기준으로 배송비를 계산하는 세 번째 에이전트 (물류 에이전트)를 추가합니다.

아키텍처:

• Vision Agent 출력: 상품 수
• 공급업체 에이전트 출력: 공급업체 위치
• 물류 에이전트 (신규) 입력: 목적지, 무게 → 출력: 배송비 + 예상 도착 시간

도움말: A2A 프로토콜을 사용하면 간단합니다. calculate_shipping 기술이 있는 새 에이전트 카드를 만드세요. Control Tower에서 자동으로 검색합니다.

학습 중인 패턴: 이는 에이전트 중심 아키텍처의 핵심입니다. 즉, 작은 구성 가능한 전문가로 빌드된 복잡한 시스템입니다.

12. 결론

생성형 AI에서 에이전트 AI로 전환되었습니다.

개발된 기능:

• 비전: '추측'을 코드 실행 (API 키를 통한 Gemini 3 Flash)으로 대체했습니다.
• 메모리: '느린 검색'이 AlloyDB ScaNN (GCP를 통해)으로 대체되었습니다.
• 조치: 'API 통합'이 A2A 프로토콜로 대체되었습니다.

하이브리드 아키텍처의 이점:

이 Codelab에서는 다음과 같은 하이브리드 접근 방식을 보여주었습니다.

• Vision Agent: Gemini API (API 키) 사용 - 간단하고 무료 등급 제공, GCP 결제 불필요
• 공급업체 에이전트: GCP (Vertex AI + AlloyDB) 사용 - 엔터프라이즈급, 규정 준수 지원

이것이 자율 경제의 아키텍처입니다. 코드는 계속 사용할 수 있습니다.

다음 단계

• Gemini API 키 받기 (무료 등급 사용 가능)
• Gemini API 문서 살펴보기
• AlloyDB AI 문서 확인하기
• Gemini 코드 실행 살펴보기