1. 소개
개요
오늘날 AI로 빌드하는 것은 어디서부터 시작해야 할까요? 프로토타입을 만들 가치가 있는 아이디어라는 불꽃에서 시작됩니다. Google AI Studio의 빌드 모드는 '바이브 코딩'을 통해 아이디어를 현실로 바꿉니다. Gemini 모델을 활용하면 대화형 코드 생성을 통해 풀 스택 웹 애플리케이션을 설계, 테스트, 배포할 수 있습니다.
이 Codelab에서는 실제 지도 데이터와 생성형 AI를 결합한 대화형 지리 공간 게임인 Block Explorer를 빌드합니다. AI Studio를 사용하여 애플리케이션을 생성하고 Google Maps Platform 및 Gemini API와 통합합니다. 그런 다음 완성된 애플리케이션을 바로 Cloud Run에 배포하여 다른 사용자가 사용해 볼 수 있도록 하는 방법을 알아봅니다.
실습할 내용
- Google AI Studio를 사용하여 대화형 지리 공간 매핑 및 퀴즈 웹 애플리케이션의 프로토타입을 제작합니다.
- AI Studio 작업공간 내에서 직접 Google Maps Platform 데모 키를 사용 설정하고 자동으로 프로비저닝합니다.
- 자연어 프롬프트를 사용하여 동적 주소 지오코딩, 장소 검색, AI 생성 퀴즈를 구현합니다.
- 지도 그라운딩 Lite를 통합하여 퀴즈의 정확성을 높입니다.
- 대화형 미리보기 샌드박스에서 애플리케이션을 테스트하고 반복합니다.
- Google AI Studio UI에서 Cloud Run으로 애플리케이션을 직접 배포합니다.
학습할 내용
- Google AI Studio의 빌드 모드를 사용하여 자연어로 풀 스택 서비스를 빠르게 프로토타입하는 방법
- Google Maps Platform API를 사용하여 지리 공간 데이터로 애플리케이션을 빌드하는 방법
- 실제 지리 공간 컨텍스트로 LLM 프롬프트를 그라운딩하여 동적 퀴즈와 지역 통계를 생성하는 방법
- AI Studio 애플리케이션을 Cloud Run에서 서버리스 컨테이너로 배포하는 방법
다음은 pp의 미리보기입니다.
2. 프로젝트 설정
AI Studio를 실행하기 전에 계정 상태, 사전 요구사항, API 액세스를 확인하세요.
Google 계정 및 등급 정보
- 아직 Google 계정이 없다면 Google 계정을 만드세요.
- 도움말: 가능하면 이 실습에 개인 Google 계정을 사용하세요. 그룹, 회사 또는 학교 계정에서는 실험 기능 또는 클라우드 통합을 사용 중지하는 정책을 시행할 수 있습니다.
- 배포의 결제 세부정보를 검토합니다.
- Google Cloud 스타터 등급: 전체 Google Cloud Cloud Billing 계정을 설정하지 않고도 일부 리전에서 최대 2개의 전체 스택 애플리케이션을 무료로 게시할 수 있습니다.
- 표준 배포: 기존 유료 Google Cloud 프로젝트에 연결하고 스토리지 한도, CPU 리소스, API를 확장합니다.
Google Maps Platform 데모 키
프로토타입 제작을 간소화하기 위해 Google AI Studio는 Google Maps Platform과 기본적으로 통합됩니다. 이를 통해 프로젝트에서 직접 핵심 Google Maps Platform API (예: Maps JavaScript API, Geocoding API, Places API, Routes API)를 사용하여 테스트하고 빌드할 수 있습니다. AI Studio에서 Google Maps Platform 데모 키를 자동으로 생성합니다.
데모 키의 주요 이점:
- 신용카드 또는 결제 설정 불필요: Google Cloud 결제 계정을 구성하지 않고도 즉시 프로토타입을 제작하고 평가할 수 있습니다.
- 넉넉한 프로토타이핑 할당량: 테스트 및 반복을 위해 API당 일일 최대 100개의 무료 요청이 포함됩니다.
- 원활한 내장 통합: 외부 포털로 이동하거나 사용자 인증 정보를 복사하여 붙여넣을 필요가 없습니다. Google AI Studio는 애플리케이션이 Google 지도 플랫폼과 통합되어야 하는 경우를 자동으로 감지하고 사용자를 위해 구성합니다.
3. AI Studio 빌드 모드에서 애플리케이션 셸 만들기
먼저 Google AI Studio를 사용하여 애플리케이션 셸을 만듭니다.
- Google AI Studio 앱 패널로 이동하여 새 앱을 클릭하거나 빌드 탭을 선택합니다.
- 프롬프트 입력 상자에 지리 공간 애플리케이션의 초기 설명을 입력합니다. 프롬프트 추천 아래에 있는 Google Maps Platform 검색 칩을 클릭해도 됩니다.
Build a highly polished, responsive, split-screen application. This application should be called "Block Explorer". It is meant to be a geospatial exploration app. It will use Google Maps Platform.
Key Features & Functionality:
- Split-Screen Layout: On desktop, a 1/3-width left-side editorial control panel and a 2/3-width right-side full-height map.
- Include a search bar where users can type a location such as a city or neighborhood. Submitting should issue a Geocoding request to the Google Geocoding V4 API REST endpoint (https://geocode.googleapis.com/v4/geocode/address/). Then pan the map to the geocoded location.
- Interactive Google Map: Render the Map inside an interactive container allowing users to pan, drag, and zoom freely. Place customized markers representing the currently selected/geocoded location.
- Also include five buttons for presets the users can click on: Buenos Aires, Shibuya, Copacabana, Cologne, and Lima. Clicking on this should geocode the location and pan the map there.
- Make sure to also include a mechanism to clearly show error messages when they occur so users can easily troubleshoot.
- 빌드를 클릭하여 애플리케이션 생성 프로세스를 시작합니다.
AI Studio에서 애플리케이션 코드 생성을 시작합니다. 디자인 테마를 선택하라는 메시지가 표시되면 원하는 스타일을 선택합니다.
Google Maps Platform 사용 설정 및 데모 키 프로비저닝
Google Maps Platform은 사람이 읽을 수 있는 주소 쿼리('시부야' 또는 '부에노스아이레스' 등)를 지리적 좌표 (위도 및 경도)로 변환하여 지도를 중앙에 배치하고 마커를 표시하는 Geocoding API를 제공합니다.
지리공간 의도 (예: Google 지도, 매장 찾기, 지역 탐색 요청)가 포함된 프롬프트를 보내면 AI Studio에서 지리공간 요구사항을 자동으로 감지하고 키 프로비저닝을 지원합니다.
- 컨텍스트 내 활성화 커튼: 'Google Maps Platform 설정'이라는 인라인 카드가 대화 턴에 표시됩니다.
- 약관 동의 및 사용 설정:
- 지도 데모 프로젝트 서비스 약관 (메시지가 표시되면 스타터 등급 추가 서비스 약관)을 검토하고 이에 동의합니다.
- Google 지도 사용 설정을 클릭합니다.
- 자동 키 프로비저닝 및 보안 비밀 삽입: AI Studio는 Google 호스팅 프로젝트 (GHP) 인프라에서 Google Maps Platform 데모 키를 자동으로 프로비저닝하고
GOOGLE_MAPS_PLATFORM_KEY라는 이름으로 프로젝트의 보안 비밀에 직접 삽입합니다. - 인스턴트 라이브 미리보기: 애플리케이션 미리보기 샌드박스가 완전히 작동하는 실시간 대화형 Google 지도로 즉시 새로고침됩니다.
새 위치를 입력하거나 사전 설정된 위치 버튼 중 하나를 선택하여 미리보기 샌드박스에서 애플리케이션을 테스트하세요.
4. Gemini API로 로컬 통계 추가
다음으로 Gemini API를 통합하여 사용자가 지도를 탐색할 때 장소에 관한 풍부한 현지화된 통계를 생성합니다.
- 채팅 창에서 AI 어시스턴트에게 다음 프롬프트를 전송합니다.
Now, let's bring in the AI using the Gemini API.
1. Once geocoding successfully identifies the City and State (e.g., "Miami, Florida"), trigger a call to the Gemini API (using the gemini-3.8-flash model).
2. Use the following prompt template for the AI:
"You are a local tour guide for [City, State]. Give me exactly 3 short, highly engaging, and unusual or surprising fun facts about this place. Keep each fact under 2 sentences. Format the response as a clean HTML unordered list (<ul>) so I can inject it directly."
3. Display these fun facts in a beautiful "Local Insights" banner on the bottom portion of the map screen. Add a subtle loading spinner while the AI is thinking.
4. Make sure to make this handling robust. If an API request fails, display a user-friendly error notification in the UI.
- 미리보기 창에서 위치를 선택하거나 검색하면 Gemini가 생성한 재미있는 사실이 동적으로 표시되는지 확인합니다.
AI Studio에서 애플리케이션을 업데이트하면 화면 하단에 '지역 통계' 섹션이 추가됩니다.
5. AI 생성 퀴즈 빌드
이제 애플리케이션이 위치 좌표와 현지화된 통계를 가져오므로 이러한 기능을 결합하여 선택한 목적지를 기반으로 대화형 퀴즈를 생성합니다.
- 퀴즈 생성 프롬프트를 에이전트에게 보냅니다.
Now let's build the actual game! We will have Gemini generate a 3-question quiz based on the real places we just got information about.
After the local insights are generated, show the user a button to "Test their local knowledge". Once clicked, offer them 3 options to choose from:
- Local cuisine
- Art and culture
- Local history
Once selected, generate a 3-question quiz based on the category and the place. The quiz should be multiple choice. Once the user submits the quiz show them their score and the correct answer.
- 미리보기 창에서 생성된 퀴즈를 플레이하여 상태 관리, 답변 선택, 점수 렌더링을 테스트합니다.
6. Maps Grounding Lite 통합
기본적으로 Gemini는 학습 데이터의 지식을 사용하여 사실과 퀴즈를 생성합니다. 정확도를 개선하고 실시간 공간 데이터를 활용하려면 Grounding Lite를 통합하세요. 이 서비스는 Gemini를 Google Maps Platform의 실시간 데이터와 직접 연결합니다.
- AI Studio에서 다음 프롬프트를 전송합니다.
Add a toggle to make the quiz more difficult. Call this "Hyperlocal mode". When enabled, use the Google Maps Grounding Lite service with the Gemini API to fetch more local data, making the quiz more difficult.
Add information for the user so they know that Hyperlocal Mode is more difficult and how it works.
- 미리보기 창에서 초지역 모드 전환 버튼을 테스트하여 그라운딩된 퀴즈 생성을 확인합니다.
LLM은 특정 영업시간, 최근 개업, 정확한 장소 ID에 대해 할루시네이션을 일으킬 수 있습니다. Maps Grounding Lite는 실제 Google 지도 장소 항목과 저작자 표시를 사용하여 대답을 그라운딩하므로 퀴즈 질문의 사실 정확성이 크게 향상됩니다.
7. Cloud Run에 배포
프로토타입이 완전히 작동하면 AI Studio에서 바로 Cloud Run에 공개 서버리스 컨테이너로 배포합니다.
- Google AI Studio의 오른쪽 상단에서 게시 버튼을 클릭하여 배포 마법사를 시작합니다.
- 시작하기를 클릭하여 Google Cloud 프로젝트를 구성합니다.
- 타겟 Google Cloud 프로젝트 드롭다운이 원하는 배포 프로젝트와 일치하는지 확인합니다.
- AI Studio는 Cloud Run 인스턴스의 고유 서비스 식별자를 자동으로 생성합니다.
- 앱 게시를 클릭합니다.
- 컨테이너 빌드, 등록, 서비스 배포는 백그라운드에서 실행됩니다. 이 과정은 일반적으로 2~4분 내에 완료됩니다.
- 배포가 완료되면 생성된 앱 URL을 복사하고 브라우저 탭에서 라이브 애플리케이션 링크를 방문합니다.
8. 보안 및 프로덕션 권장사항 검토
이 앱을 프로토타입에서 프로덕션 환경으로 전환할 때는 다음 보안 원칙을 염두에 두세요.
1. Google 지도 API 키 제한사항
프로덕션 Google 지도 API 키를 제한되지 않은 상태로 두지 마세요. Google Cloud 콘솔에서 다음 단계를 따르세요.
- API 제한: 특정 API (Maps JavaScript API, Geocoding API, Places API)만 호출할 수 있도록 키를 제한합니다.
- 애플리케이션 제한: HTTP 리퍼러 (예:
https://yourgame.com/*)를 사용하여 키를 제한하여 서드 파티 사이트에서 승인되지 않은 사용을 방지합니다.
2. Gemini API 키 보안
Gemini API 키는 클라이언트 측 JavaScript에 절대 노출되어서는 안 됩니다.
- 프로덕션 아키텍처: 프록시 역할을 하는 경량 백엔드 서비스 (예: Cloud Run 또는 Cloud Functions)를 빌드합니다. 프런트엔드가 백엔드 (
/api/get-fun-facts)를 호출하고 백엔드는 환경 변수 (GEMINI_API_KEY)를 사용하여 Google AI Studio와 안전하게 통신합니다.
9. 리소스 삭제
예상치 못한 요금 청구를 방지하거나 워크스페이스 리소스를 정리하려면 다음 단계를 따르세요.
- Google AI Studio에서 앱 페이지로 이동합니다.
- 그리드 또는 목록에서 애플리케이션을 찾습니다.
- 휴지통 아이콘을 클릭하여 앱 상태를 삭제하고 Cloud Run에서 서비스를 게시 취소합니다.
- 표준 프로젝트를 사용하여 배포했고 모든 리소스를 완전히 종료하려면 Google Cloud 콘솔 프로젝트 설정으로 이동하여 기본 프로젝트를 삭제하세요.
10. 결론
수고하셨습니다 Google AI Studio에서 AI 기반 지리 공간 웹 애플리케이션을 설계, 개발, 배포했습니다. Google Maps Platform API를 사용하여 실제 데이터로 구동되는 대화형 게임을 빌드했습니다.
이 링크를 방문하여 빌더 여정 완료 배지를 받으세요.
여정을 계속하려면 goo.gle/builders에서 다음 실습을 확인하세요.