이 페이지에서는 Vertex AI Studio에서 Google 지도와 함께 그라운딩 기능을 사용하여 지리공간 컨텍스트를 제공함으로써 생성형 AI 애플리케이션을 향상시키는 방법을 설명합니다.
개요
Vertex AI Studio의 Google 지도 그라운딩은 Gemini 모델을 Google 지도의 지리공간 데이터와 연결하는 서비스입니다. Google 지도는 전 세계 수백만 개의 위치 정보(기업, 랜드마크, 관심 지점 포함)에 액세스할 수 있습니다. 이 데이터는 2억 5천만 개 이상의 장소 정보를 제공하여, 모델의 응답을 그라운딩하고, AI 애플리케이션과 에이전트가 지역 데이터와 지리공간 컨텍스트를 제공할 수 있도록 합니다.
또한 그라운딩은 Google 지도, Google 검색, 사용자의 데이터 소스와 동시에 사용 설정할 수도 있습니다.
Google 지도 그라운딩 활용
Google 지도 그라운딩은 다음과 같은 다양한 애플리케이션에서 활용할 수 있습니다.
- 주변 장소에 대한 질문(예: '근처에 공원이 있나요?')에 답할 수 있는 대화형 어시스턴트
- 장소에 대한 맞춤형 설명 제공(예: '걸어서 갈 수 있는 거리에 있는 공원과 가족에 어울리는 식당에 대해 알려줄 수 있나요?')
이러한 기능은 부동산, 여행, 모빌리티, 소셜 앱과 같은 사용 사례에 특히 유용합니다.
지원되는 모델
다음은 Google 지도 기반 그라운딩을 지원하는 모델 목록입니다.
- Gemini 2.5 Flash-Lite
- Gemini 2.5 Flash with Live API native audio(프리뷰)
- Gemini 2.0 Flash with Live API(프리뷰)
- Gemini 2.5 Pro
- Gemini 2.5 Flash
- Gemini 2.0 Flash
Gemini 모델에 대한 자세한 내용은 Gemini 모델을 참조하세요.
Google 지도 그라운딩을 사용하여 모델 응답 그라운딩
이 코드 샘플은 Google 지도 그라운딩을 사용해 모델 응답에 실제 근거를 제공하는 방법을 보여줍니다.
검색 결과는 위도와 경도 좌표를 사용하여 특정 지리적 위치에 맞게 맞춤설정할 수 있습니다. 자세한 내용은 Grounding API를 참조하세요.
콘솔
Vertex AI Studio에서 Google 지도 그라운딩을 사용하려면 다음 단계를 따르세요.
Google Cloud 콘솔에서 Vertex AI Studio 페이지로 이동합니다.
패널에서 모델 설정을 확장하고 Grounding: Google 전환 버튼을 클릭합니다.
Google 지도를 선택합니다.
적용을 클릭합니다.
입력란에 프롬프트를 입력한 후 제출을 클릭합니다.
Python
이 샘플을 사용해 보기 전에 Vertex AI 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 Vertex AI Python API 참고 문서를 참조하세요.
Vertex AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
이렇게 하면 Google 지도를 기반으로 프롬프트 응답이 그라운딩됩니다.
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
from google import genai
from google.genai.types import (
GenerateContentConfig,
GoogleMaps,
HttpOptions,
Tool,
)
client = genai.Client(http_options=HttpOptions(api_version="v1"))
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="Where can I get the best espresso near me?",
config=GenerateContentConfig(
tools=[
# Use Google Maps Tool
Tool(google_maps=GoogleMaps(
enable_widget=False # Optional to enable Maps widget
))
],
tool_config=types.ToolConfig(
retrieval_config = types.RetrievalConfig(
lat_lng = types.LatLng( # Pass coordinates for location-aware grounding
latitude=40.7128,
longitude=-74.006
),
language_code = "en_US", # Optional: localize Maps results
),
),
),
)
print(response.text)
# Example response:
# 'Here are some of the top-rated places to get espresso near you: ...'
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- LOCATION: 요청을 처리하는 리전
- PROJECT_ID: 프로젝트 ID입니다.
- MODEL_ID: 멀티모달 모델의 모델 ID입니다.
- TEXT: 프롬프트에 포함할 텍스트 안내입니다.
- LATITUDE: 해당 위치의 위도입니다. 예를 들어 위도
37.7749는 샌프란시스코를 나타냅니다. 위도와 경도 좌표는 Google 지도 또는 다른 지오코딩 도구를 사용하여 얻을 수 있습니다. - LONGITUDE: 해당 위치의 경도입니다. 예를 들어 경도
-122.4194는 샌프란시스코를 나타냅니다. - ENABLE_WIDGET: 토큰을 반환하고 Google 지도 위젯을 사용 설정할지 여부입니다(기본값
false).
HTTP 메서드 및 URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent
JSON 요청 본문:
{
"contents": [{
"role": "user",
"parts": [{
"text": "TEXT"
}]
}],
"tools": [{
"googleMaps": {
"enableWidget": ENABLE_WIDGET
}
}],
"toolConfig": {
"retrievalConfig": {
"latLng": {
"latitude": LATITUDE,
"longitude": LONGITUDE
},
"languageCode": "en_US"
}
},
"model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
다음과 비슷한 JSON 응답이 표시됩니다.
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"text": "\"The Italian Place\" in Alexandria, VA, is good for children and offers takeout. It has a rating of 4.2 stars based on 411 reviews."
}
]
},
"finishReason": "STOP",
"groundingMetadata": {
"groundingChunks": [
{
"maps": {
"uri": "https://maps.google.com/?cid=9001322937822692826",
"title": "The Italian Place",
"placeId": "places/ChIJOTRDf_qwt4kR2kV_WYUf63w"
}
"maps": {
"uri": "https://maps.google.com/?cid=9001322937822692826",
"title": "Hank's Pasta Bar",
"placeId": "places/MMVtPzn9FGcevML89",
"placeAnswerSources": {
"reviewSnippets": [
{
"id": "places/ChIJOTRDf_qwt4kR2kV_WYUf63w",
"title": "Google Maps Review",
"uri": "https://maps.google.com/?cid=9001322937822692826"
},
]
}
}
},
...
],
"groundingSupports": [
{
"segment": {
"endIndex": 79,
"text": "\"The Italian Place\" in Alexandria, VA, is good for children and offers takeout."
},
"groundingChunkIndices": [
0
]
},
],
"googleMapsWidgetContextToken": "widgetcontent/..."
}
}
],
...
}
응답 이해하기
Google 지도 소스는 groundingChunks 내의 groundingMetadata에 포함되어 반환됩니다. 소스는 장소와 사용자 리뷰 모두에 대해 반환되며, 이는 Google 지도 그라운딩 결과를 생성하는 데 사용됩니다.
아래 코드 샘플은 응답에서 장소 소스와 장소 답변 소스가 어떻게 표시되는지를 보여줍니다.
"groundingChunks": [
{
"maps": {
"uri": "{Link to Maps Content}",
"title": "{Name of Maps Place}",
"placeId": "{Place ID}",
"placeAnswerSources":
"reviewSnippets" : [
{
"reviewId": "{Review ID}",
"googleMapsUri": "{Link to Maps Content}"
"title": "{Title of review}"
},
]
},
}
}
}
],
서비스 사용 요구사항
이 섹션에서는 Google 지도 그라운딩에 대한 서비스 사용 요구사항을 설명합니다.
사용자에게 Google 지도 소스 사용 알림
각 Google 지도 그라운딩 결과와 함께 groundingChunks에 소스가 수신됩니다. Vertex AI Studio에서 Google 지도 그라운딩 결과를 표시할 때는 연결된 Google 지도 소스를 명시해야 합니다. 구체적인 요구사항은 다음과 같습니다.
- Google 지도 소스는 해당 소스를 뒷받침하는 생성된 콘텐츠 직후에 따라와야 합니다. 이렇게 생성된 콘텐츠를 Google 지도 그라운딩 결과라고도 합니다.
- Google 지도 소스는 단일 사용자 상호작용 내에서 확인 가능해야 합니다.
Google 지도 소스를 Google 지도 링크와 함께 표시
groundingChunks와 grounding_chunks.maps.placeAnswerSources.reviewSnippets 내의 각 소스에 대해 다음 요구사항에 따라 링크 미리보기를 생성해야 합니다.
- 각 소스는 Google 지도에서 제공한 것임을 명시하고 Google 지도의 텍스트 저작자 표시 지침을 따라야 합니다.
- 응답에 포함된 소스 제목을 표시해야 합니다.
- 응답에 제공된
uri또는googleMapsUri를 사용하여 소스에 연결해야 합니다.
아래 이미지는 소스와 그 Google 지도 링크를 표시하기 위한 최소 요구사항을 보여줍니다.
또한 소스 보기 영역은 접을 수 있습니다.
선택사항: 링크 미리보기를 다음과 같은 추가 콘텐츠로 보강할 수 있습니다.
- Google 지도 텍스트 저작자 표시 앞에 Google 지도 파비콘을 삽입합니다.
- 소스 URL에서 제공되는 사진(예:
og:image)을 표시합니다.
일부 Google 지도 데이터 제공업체 및 해당 라이선스 조건에 대한 자세한 내용은 Google 지도 및 Google 어스 법적 고지를 참조하세요.
Google 지도 저작자 표시 요구사항
Google 지도의 텍스트 저작자 소스를 표시할 때는 다음 가이드라인을 따라야 합니다.
Google 지도 텍스트를 어떤 방식으로도 수정하지 마세요.
- Google 지도의 대소문자를 변경하지 마세요.
- Google 지도를 여러 줄로 나누어 표시하지 마세요.
- Google 지도를 다른 언어로 현지화하지 마세요.
- 브라우저가 Google 지도를 번역하지 못하도록 HTML 속성
translate="no"를 사용해야 합니다.
다음 표에 설명된 대로 Google 지도 텍스트 스타일을 지정해야 합니다.
| 속성 | 스타일 |
|---|---|
| 글꼴 모음 | Roboto. 글꼴 로드는 선택사항입니다. |
| 대체 글꼴 모음 | 제품에서 이미 사용 중인 sans serif 본문 글꼴 또는 'Sans-Serif'를 지정해 기본 시스템 글꼴을 호출합니다. |
| 글꼴 스타일 | 보통 |
| 글꼴 두께 | 400 |
| 글꼴 색상 | 흰색, 검정(#1F1F1F) 또는 회색(#5E5E5E). 배경 대비를 고려해 접근성 비율(4.5:1)을 유지해야 합니다. |
| 글꼴 크기 | 최소 글꼴 크기: 12sp 최대 글꼴 크기: 16sp sp에 대해 자세히 알아보려면 Material Design 웹사이트의 글꼴 크기 단위를 참조하세요. |
| 문자 간격 | 보통 |
예시 CSS
다음 CSS는 흰색 또는 밝은 배경에서 Google 지도 텍스트를 적절한 타이포그래픽 스타일과 색상으로 렌더링합니다.
@import url('https://fonts.googleapis.com/css2?family=Roboto&display=swap');
.GMP-attribution {
font-family: Roboto, Sans-Serif;
font-style: normal;
font-weight: 400;
font-size: 1rem;
letter-spacing: normal;
white-space: nowrap;
color: #5e5e5e;
}
컨텍스트 토큰, 장소 ID, 리뷰 ID
Google 지도 데이터에는 컨텍스트 토큰, 장소 ID, 리뷰 ID가 포함됩니다. 다음 응답 데이터를 캐시, 저장, 내보내기할 수 있습니다.
googleMapsWidgetContextTokenplaceIdreviewId
Google 지도 그라운딩 약관에 명시된 캐싱 제한사항은 적용되지 않습니다.
제한 지역
Google 지도 그라운딩은 안전하고 신뢰할 수 있는 플랫폼을 유지하기 위해 특정 콘텐츠 및 활동에 제한을 둡니다. 사용자는 다음과 같은 제한 지역에서 Google 지도 그라운딩을 제공하는 애플리케이션을 배포하거나 마케팅할 수 없습니다.
- 중국
- 크리미아
- 쿠바
- 도네츠크 인민공화국
- 이란
- 루한스크 인민공화국
- 북한
- 시리아
- 베트남
장소 속성
이 섹션에서는 위치를 설명하는 데 사용되고, Google 지도 그라운딩이 응답을 생성할 때 활용되는 장소 속성을 보여줍니다. 이러한 속성은 Google 지도 그라운딩이 어떤 유형의 질문에 답할 수 있는지를 결정하는 데 사용됩니다.
샘플 장소 속성
아래는 모델이 응답을 생성하는 데 사용할 수 있는 장소에 관한 속성을 알파벳순으로 샘플링한 예시입니다.
- 주소
- 매장 밖 수령
- 체크카드
- 거리
- 무료 주차장
- 라이브 음악
- 어린이 메뉴
- 영업시간
- 결제 옵션(예: 현금 또는 신용카드)
- 장소 답변
- 반려동물 동반 가능
- 맥주 제공
- 채식 음식 제공
- 휠체어 이용 가능
- Wi-Fi
장소 답변은 Google 지도 그라운딩이 사용자 리뷰에서 파생된 정보를 기반으로 생성한 응답을 의미합니다.
장소 속성 사용 예시
아래 예시는 다양한 유형의 장소에 대한 질문에서 장소 속성을 어떻게 활용하는지를 보여줍니다. Google 지도 그라운딩은 이러한 속성을 사용해 사용자의 의도를 파악하고, Google 지도에 연계된 장소 데이터를 기반으로 관련 답변을 제공합니다.
가족 저녁 식사 계획하기: 'The Italian Place'는 아이들에게 좋은가요? 테이크아웃도 가능한가요? 평점은 어떻게 되나요?와 같이 물을 수 있습니다.
이러한 질문에 대한 답변은 식당이 가족 외식에 적합한지, 편리한 서비스를 제공하는지를 판단하는 데 도움이 됩니다.
친구의 접근성 확인: 휠체어 이용 가능한 입구가 있는 음식점이 필요합니다.와 같이 물을 수 있습니다.
이 요청에 대한 답변은 해당 장소가 특정 접근성 요구사항을 충족하는지 여부를 확인하는 데 도움이 됩니다.
야식 장소 찾기: 'Burger Joint'가 지금 영업 중인가요? 저녁 식사 가능한가요? 금요일 영업시간은 어떻게 되나요?와 같이 물을 수 있습니다.
이러한 질문에 대한 답변은 특정 시간대에 특정 식사를 제공하는 영업 중인 식당을 찾는 데 도움이 됩니다.
고객과 커피 미팅하기: 'Cafe Central'에 Wi-Fi가 있나요? 커피를 제공하나요? 가격대는 어떤가요? 신용카드를 받나요?와 같이 물을 수 있습니다.
이러한 질문에 대한 답변은 카페의 편의시설, 제공 메뉴, 결제 옵션을 기준으로 비즈니스 미팅 장소로 적합한지 평가하는 데 도움이 됩니다.
Google 지도 그라운딩 결과의 정보는 실제 도로 상황과 다를 수 있습니다.
선택사항: Google 지도 컨텍스트 위젯
컨텍스트 위젯은 Google 지도 GA 이전 제공 기능으로, 다른 Google 지도 콘텐츠를 지원하거나 보완하기 위해 사용되는 시각적 컨테이너입니다. Google 지도 컨텍스트 위젯을 사용하면 Google 지도 그라운딩을 애플리케이션에 통합하여, 대화형 LLM 기반 채팅 경험을 만들 수 있습니다.
이 컨텍스트 위젯은 Vertex AI API 응답에 포함된 컨텍스트 토큰인 googleMapsWidgetContextToken을 사용하여 렌더링됩니다. 이 토큰을 활용하면 시각적 콘텐츠를 렌더링할 수 있습니다.
컨텍스트 위젯은 시나리오에 따라 다음과 같은 기능을 제공합니다.
Google 지도 프롬프트를 사용해 답변을 생성하는 경우, 사용자 리뷰와 사진(사용자 제작 콘텐츠(UGC))을 표시합니다.
Vertex AI가 텍스트 응답만 생성하는 경우 지도 시각화 및 데이터로 결과를 보강합니다.
컨텍스트 위젯에 대한 자세한 내용은 지도 그라운딩 위젯을 참조하세요.
Google 지도 컨텍스트 위젯 렌더링
Google 지도 컨텍스트 위젯을 렌더링하고 사용하려면 위젯이 표시되는 페이지에서 Google Maps JavaScript API의 알파 버전을 사용해야 합니다. 자세한 내용은 Maps JavaScript API 로드를 참조하세요.
다음 코드 샘플은 컨텍스트 위젯을 사용하는 방법을 보여줍니다.
컨텍스트 위젯을 만듭니다.
<body> <gmp-place-contextual id="widget"></gmp-place-contextual> </body>Google 지도와 연동된 응답에는 해당 응답에 맞는
googleMapsWidgetContextToken이 포함됩니다. 이 토큰은 컨텍스트 위젯을 렌더링하는 데 사용되고 생성된 응답과 가까운 위치에 배치됩니다.컨텍스트 토큰을 업데이트하려면
widget.contextToken property를 설정합니다."googleMapsWidgetContextToken": "widgetcontent/AcBXPQdpWQWbap9H-OH8sEKmOXxmEKAYvff0tvthhneMQC3VrqWCjpnPBl4-Id98FGiA_S_t8aeAeJj0T6JkWFX56Bil8oBSR0W8JH3C_RSYLbTjxKdpxc9yNn6JcZTtolIRZon9xi6WpNGuSyjcIxWu2S0hwpasNOpUlWrG1RxVCB4WD1fsz_pwR236mG36lMxevXTQ_JnfdYNuQwQ4Lc3vn...<snip>... Ts5VJE_b3IC5eE_6wez0nh61r7foTUZpP7BXMwxR-7Wyfcj6x1v6mIWsFGr1o0p_HSAMNqWPg-aFVnkPLhAkOR6MaNZOfezTva-gxHlu7z_haFvYxcUE1qfNVQ",function updateWidget(contextToken) { let widget = document.querySelector('#widget'); widget.contextToken = contextToken; }선택사항: 목록 레이아웃을 지정합니다. 유효한 값은 다음과 같습니다.
- 컴팩트 레이아웃:
<gmp-place-contextual-list-config layout="compact"> - 세로 레이아웃:
<gmp-place-contextual-list-config layout="vertical">
이 코드 샘플은 목록 레이아웃을 컴팩트로 변경하는 방법을 보여줍니다.
<gmp-place-contextual id="widget"> <gmp-place-contextual-list-config layout="compact"> </gmp-place-contextual-list-config> </gmp-place-contextual>- 컴팩트 레이아웃:
선택사항: 지도 모드를 변경합니다. 유효한 값은 다음과 같습니다.
- 2D 로드맵 지도:
map-mode="roadmap" - 3D 하이브리드 지도:
map-mode="hybrid" - 지도 없음:
map-mode="none"
이 코드 샘플은 지도 모드를 2D 지도 모드로 변경하는 방법을 보여줍니다.
<gmp-place-contextual id="widget"> <gmp-place-contextual-list-config map-mode="roadmap"> </gmp-place-contextual-list-config> </gmp-place-contextual>- 2D 로드맵 지도:
다음 단계
- Gemini 모델을 자체 데이터에 그라운딩하는 방법은 데이터로 그라운딩을 참조하세요.
- 책임감 있는 AI 권장사항 및 Vertex AI의 안전 필터에 대해 자세히 알아보려면 책임감 있는 AI를 참조하세요.