2026.04.12 / 동준상.넥스트플랫폼
(AWS SAA, AWS AIF, GCP GenAI Leader)
AI Cloud Hands-on Lab: Building an Image Recognition App with Gemini on Vertex AI
핵심 요약 (Executive Summary)
이번 포스트는 Google Cloud의 AI 플랫폼인 Vertex AI를 활용하여 Gemini 기반 이미지 인식 애플리케이션을 구축하는 과정을 살펴보고, 이 과정에 포함된 핵심 기술 요소를 분석하는 실습 가이드입니다.
- 이번 실습 프로젝트의 핵심: 사전 학습된(pre-trained) Gemini 모델을 사용하여 이미지와 텍스트 입력을 결합한 멀티모달(multimodal) 추론을 수행
- 학습자는 Vertex AI SDK를 통해 모델에 연결하고, 자원 고갈(Quota exhaustion) 상황에 대비한 재시도 로직을 구현하며, 최종적으로 이미지 콘텐츠에 대한 텍스트 기반 답변을 추출하는 프로세스를 체험
1. 프로젝트 개요 및 목적
Vertex AI(generative AI)는 구글의 대규모 생성형 AI 모델에 대한 접근을 제공하여 사용자가 모델을 테스트, 튜닝 및 배포할 수 있도록 지원합니다. 본 프로젝트의 주요 목적은 다음과 같습니다.
- Vertex AI SDK 연결: Google Cloud AI 서비스와의 통신 채널 구축.
- Gemini 모델 로드: 처음부터 모델을 구축하지 않고 사전 학습된 강력한 Gemini 모델 활용.
- 멀티모달 입력 처리: 이미지와 텍스트 질문을 동시에 모델에 전달하여 복합적인 맥락 이해.
- 결과 추출 및 해석: 모델이 생성한 텍스트 응답을 처리하고 소프트웨어 프로젝트에 통합하는 핵심 개념 파악.
2. 기술적 구현 상세
2.1 클라이언트 구성 및 모델 호출
애플리케이션은 google.genai 라이브러리를 사용하여 Vertex AI 클라이언트를 생성합니다. 주요 메소드인 generate_content는 다음과 같은 파라미터를 입력받아 실행됩니다.
- 모델 ID (Model ID): 사용할 특정 Gemini 모델 지정.
- 콘텐츠 (Contents):
- 텍스트 프롬프트: 이미지에 대해 묻고 싶은 질문 (예: “이 이미지에는 무엇이 표시되어 있습니까?”).
- 이미지 파트 (Part.from_uri): 분석할 이미지의 Cloud Storage URI 및 MIME 유형(
image/jpeg).
2.2 오류 처리 및 재시도 로직 (Retry Logic)
높은 수요로 인한 자원 고갈(HTTP 429 오류)에 대비하여 안정적인 서비스 운영을 위한 지수 백오프(Exponential Backoff) 기반의 재시도 메커니즘이 포함되어 있습니다.
| 구성 요소 | 설정값 | 설명 |
| MAX_RETRIES | 3 | 최대 재시도 횟수 |
| INITIAL_DELAY | 2초 | 첫 번째 재시도 전 대기 시간 |
| 대상 오류 | 429 / RESOURCE_EXHAUSTED | 할당량 초과 시 발생하는 구체적인 클라이언트 오류 |
| 최종 상태 확인 | finally 블록 | 모든 시도 실패 시 프로세스 종료 상태 확인 |
소스 코드: genai.py
import time
from google import genai
from google.genai.types import HttpOptions, Part
from google.genai.errors import ClientError
client = genai.Client(http_options=HttpOptions(api_version="v1"))
# Configuration for retry logic
MAX_RETRIES = 3
INITIAL_DELAY = 2
for attempt in range(MAX_RETRIES + 1):
try:
response = client.models.generate_content(
model="model-id",
contents=[
"What is shown in this image?",
Part.from_uri(
file_uri="https://storage.googleapis.com/cloud-samples-data/generative-ai/image/scones.jpg",
mime_type="image/jpeg",
),
],
)
# Save output to a txt file
with open("output.txt", "w", encoding="utf-8") as file:
file.write(response.text)
print(response.text)
break
except ClientError as e:
if "429" in str(e) or "RESOURCE_EXHAUSTED" in str(e):
if attempt < MAX_RETRIES:
delay = INITIAL_DELAY * (2 ** attempt)
print(f"Warning: Resource exhausted (429). Retrying in {delay} seconds... (Attempt {attempt + 1}/{MAX_RETRIES})")
time.sleep(delay)
else:
print("I am currently experiencing high demand due to quota exhaustion. Please wait for a while and try again.")
finally:
# Verify if the process concluded without a response object being created
if 'response' not in locals() and attempt == MAX_RETRIES:
print("Final Status: Process terminated unsuccessfully.")분석 대상 이미지
3. 환경 설정 및 실행 단계
애플리케이션을 실행하기 위해 필요한 환경 변수 설정과 실행 프로세스는 다음과 같습니다.
3.1 필수 환경 변수
터미널에서 다음 변수를 설정하여 SDK가 올바른 프로젝트와 지역을 참조하도록 합니다.
| 환경 변수명 | 목적 |
GOOGLE_CLOUD_PROJECT | 연결할 Google Cloud 프로젝트 ID 지정 |
GOOGLE_CLOUD_LOCATION | 서비스가 배포될 리전(Region) 설정 |
GOOGLE_GENAI_USE_VERTEXAI | Vertex AI 엔드포인트 사용 여부 활성화 (True) |
3.2 실행 프로세스
- 코드 작성:
genai.py파일에 Python SDK 기반 로직 구현. - 환경 변수 내보내기(Export): 상기 표의 변수들을 시스템에 등록.
- 스크립트 실행:
python3 /genai.py명령어를 통해 모델 호출 및 결과 확인.
결론
- 이미지 및 텍스트의 통합 이해: Gemini 모델은 텍스트 프롬프트의 맥락을 사용하여 이미지의 콘텐츠를 설명할 수 있고, 단순한 사물 인식을 넘어 이미지 내의 상황 추론 가능
- 확장성: 제공된 코드 구조 내에서 이미지 URI와 프롬프트 질문을 변경하여 다양한 이미지 인식 시나리오를 실험하고 확장 가능
- 안정성 확보: 클라우드 기반 AI API를 사용할 때 발생할 수 있는 할당량 제한 문제를 재시도 로직을 통해 기술적으로 보완함으로써 애플리케이션의 견고함 제고 가능
