이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Vertex AI에서 Google 지도로 그라운딩

이 페이지에서는 Vertex AI의 Google 지도 기반 그라운딩이 지리 공간적 컨텍스트를 제공하여 생성형 AI 애플리케이션을 개선하는 방법을 설명합니다.

개요

Vertex AI의 Google 지도로 그라운딩은 Gemini 모델을 Google 지도의 지리정보 데이터와 연결하는 미리보기 서비스입니다. Google 지도는 비즈니스, 랜드마크, 관심 장소 등 수백만 개의 위치에 관한 정보에 액세스할 수 있습니다. 이 데이터를 통해 2억 5천만 개 이상의 장소에 관한 정보에 액세스하여 모델의 대답을 그라운딩할 수 있으므로 AI 애플리케이션과 에이전트가 현지 데이터와 지리정보 컨텍스트를 제공할 수 있습니다.

Google 지도를 사용한 그라운딩의 용도

Google 지도를 사용한 그라운딩은 다음과 같은 다양한 애플리케이션에 사용할 수 있습니다.

채팅 기반 상담사
장소 정보 요약
콘텐츠 번역
'근처에 공원이 있나요?'와 같은 근처 장소에 관한 질문에 답변할 수 있는 대화형 어시스턴트
'걸어서 갈 수 있는 거리에 있는 공원과 가족 친화적인 식당에 대해 자세히 알려줘'와 같은 장소에 대한 맞춤 설명

이는 부동산, 여행, 모빌리티, 소셜 애플리케이션과 같은 업종에 유용할 수 있습니다.

Google 지도를 사용한 그라운딩에 관한 기술 지원은 maps-grounding-feedback-external@google.com으로 이메일을 보내세요.

지원되는 모델

이 섹션에는 Google 지도에서 그라운딩을 지원하는 모델이 나와 있습니다.

Gemini 2.5 Flash-Lite
Live API 네이티브 오디오를 사용한 Gemini 2.5 Flash (프리뷰)
Live API를 사용한 Gemini 2.0 Flash (프리뷰)
Gemini 2.5 Pro
Gemini 2.5 Flash
Gemini 2.0 Flash

Gemini 모델에 대한 자세한 내용은 Gemini 모델을 참고하세요.

Google 지도를 사용한 그라운딩으로 모델의 대답 그라운딩

이 코드 샘플은 Google 지도와 함께 그라운딩을 사용하여 모델의 응답을 그라운딩하는 방법을 보여줍니다.

위도 및 경도 좌표를 사용하여 특정 지리적 위치에 맞게 검색 결과를 맞춤설정할 수 있습니다. 자세한 내용은 그라운딩 API를 참고하세요.

콘솔

Vertex AI Studio에서 Google 지도로 그라운딩 기능을 사용하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Vertex AI Studio 페이지로 이동합니다.
Vertex AI Studio로 이동
자유 형식 탭을 클릭합니다.
측면 패널에서 모델 대답 그라운딩 전환 버튼을 클릭합니다.
맞춤설정을 클릭하고 Google 지도를 소스로 설정합니다.
텍스트 상자에 프롬프트를 입력하고 제출을 클릭합니다.

프롬프트 응답이 Google 지도에 반영됩니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

LOCATION: 요청을 처리하는 리전
PROJECT_ID: 프로젝트 ID
MODEL_ID: 멀티모달 모델의 모델 ID입니다.
TEXT: 프롬프트에 포함할 텍스트 안내입니다.
LATITUDE: 위치의 위도입니다. 예를 들어 위도 37.7749는 샌프란시스코를 나타냅니다. Google 지도와 같은 서비스나 기타 지오코딩 도구를 사용하여 위도 및 경도 좌표를 얻을 수 있습니다.
LONGITUDE: 위치의 경도입니다. 예를 들어 경도 -122.4194는 샌프란시스코를 나타냅니다.

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": {}
  }],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {
        "latitude": LATITUDE,
        "longitude": LONGITUDE
      }
    }
  },
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content

다음과 비슷한 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",
              "text": "**About:**\n\n* **Type:** Italian Restaurant\n* **Address:** 621 Wythe St, Alexandria, VA 22314, USA\n* **Open Now:** Yes\n* **Rating:** 4.2 (411 reviews)\n* **Price Level:** Moderate\n* **Phone:** (571) 777-8981\n* **Summary:** Down-to-earth, counter-serve stop offering Italian sandwiches, coffee & market goods.\n* **Additional Summary:** Relaxed Italian eatery known for sandwiches and pizza along with gourmet food items and gelato.\n* **Offers Takeout:** Yes\n* **Offers Delivery:** Yes\n* **Offers Dine-in:** Yes\n* **Good for Children:** Yes\n* **Has Restroom:** Yes\n* **Outdoor Seating:** Yes\n* **Live Music:** No\n* **Menu for Children:** No\n* **Serves Dessert:** Yes\n* **Serves Coffee:** Yes\n* **Good for Watching Sports:** No\n* **Serves Lunch:** Yes\n* **Serves Dinner:** Yes\n* **Serves Beer:** Yes\n* **Serves Vegetarian Food:** Yes\n\n**Opening Hours (local time):**\n\n* Monday: 11:00 AM – 7:00 PM\n* Tuesday: 10:00 AM – 7:00 PM\n* Wednesday: 11:00 AM – 7:00 PM\n* Thursday: 11:00 AM – 7:00 PM\n* Friday: 11:00 AM – 7:00 PM\n* Saturday: 11:00 AM – 7:00 PM\n* Sunday: 12:00 – 7:00 PM\n\n**Parking options:**\n\n* **Free parking lot:** Yes\n* **Free street parking:** Yes\n* **Valet parking:** No\n\n**Accessibility:**\n\n* **Wheelchair accessible parking:** Yes\n* **Wheelchair accessible restroom:** Yes\n\n**Payment options:**\n\n* **Credit Card:** Yes\n* **Debit Card:** Yes\n* **Cash Only:** No\n* **NFC:** Yes\n\n**Distance & Travel Time:**\n\n* 384.6 kilometers\n* 4.2 hours",
              "placeId": "places/ChIJOTRDf_qwt4kR2kV_WYUf63w"
            }
          },
          ...
        ],
        "groundingSupports": [
          {
            "segment": {
              "endIndex": 79,
              "text": "\"The Italian Place\" in Alexandria, VA, is good for children and offers takeout."
            },
            "groundingChunkIndices": [
              0
            ]
          },
          {
            "segment": {
              "startIndex": 80,
              "endIndex": 130,
              "text": "It has a rating of 4.2 stars based on 411 reviews."
            },
            "groundingChunkIndices": [
              0
            ]
          }
        ],
        "googleMapsWidgetContextToken": "widgetcontent/..."
      }
    }
  ],
  ...
}

컨텍스트 위젯은 다른 Google 지도 콘텐츠를 지원하거나 보완하는 데 사용되는 시각적 컨테이너인 Google 지도 사전 공개 제품입니다. Google 지도 컨텍스트 위젯을 사용하면 Google 지도와의 그라운딩을 애플리케이션에 통합하여 대화형 LLM 기반 채팅 환경을 만들 수 있습니다. 컨텍스트 위젯은 Vertex AI API 응답에서 반환되고 시각적 콘텐츠를 렌더링하는 데 사용할 수 있는 컨텍스트 토큰 googleMapsWidgetContextToken을 사용하여 렌더링됩니다.

상황별 위젯은 시나리오에 따라 다양한 기능을 제공합니다.

Google 지도 프롬프트가 답변 생성에 사용되는 시나리오에서 주관적인 사용자 제작 콘텐츠 (UGC)를 표시합니다.
Vertex AI가 텍스트 응답만 생성하는 경우 지도 시각화 및 데이터로 결과를 보강하는 데 도움이 됩니다.

컨텍스트 위젯에 관한 자세한 내용은 지도 그라운딩 위젯을 참고하세요.

Google 지도 컨텍스트 위젯을 렌더링하고 사용하려면 위젯을 표시하는 페이지에서 Google Maps JavaScript API의 알파 버전을 사용하세요. 자세한 내용은 Maps JavaScript API 로드를 참고하세요.

다음 코드 샘플은 컨텍스트 위젯을 사용하는 방법을 보여줍니다.

HTML

컨텍스트 위젯을 만듭니다.

  <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>
```

자바스크립트

컨텍스트 위젯을 만듭니다.

async function createWidget(contextToken) {
  await google.maps.importLibrary('places');
  let widgetContainer = document.querySelector('#wc');  // a div that contains the widget
  const placeContextualElement = new
      google.maps.places.PlaceContextualElement({ contextToken });
  widgetContainer.appendChild(placeContextualElement);
}

Google 지도에 기반한 대답에는 상황별 위젯을 렌더링하는 데 사용되고 생성된 대답과 가까운 위치에 배치되는 해당 googleMapsWidgetContextToken가 있습니다.

컨텍스트 토큰을 업데이트하려면 widget.contextToken 속성을 설정합니다.

  "googleMapsWidgetContextToken": "widgetcontent/AcBXPQdpWQWbap9H-OH8sEKmOXxmEKAYvff0tvthhneMQC3VrqWCjpnPBl4-Id98FGiA_S_t8aeAeJj0T6JkWFX56Bil8oBSR0W8JH3C_RSYLbTjxKdpxc9yNn6JcZTtolIRZon9xi6WpNGuSyjcIxWu2S0hwpasNOpUlWrG1RxVCB4WD1fsz_pwR236mG36lMxevXTQ_JnfdYNuQwQ4Lc3vn...<snip>...
  Ts5VJE_b3IC5eE_6wez0nh61r7foTUZpP7BXMwxR-7Wyfcj6x1v6mIWsFGr1o0p_HSAMNqWPg-aFVnkPLhAkOR6MaNZOfezTva-gxHlu7z_haFvYxcUE1qfNVQ",

  function updateWidget(contextToken) {
    widget.contextToken = contextToken;
  }

선택사항: 목록 레이아웃을 지정합니다. 유효한 값은 다음과 같습니다.
- 소형 레이아웃: layout: google.maps.places.PlaceContextualListLayout.COMPACT
- 세로 레이아웃: layout: google.maps.places.PlaceContextualListLayout.VERTICAL
이 코드 샘플은 목록 레이아웃을 컴팩트 레이아웃으로 변경하는 방법을 보여줍니다.
```
  const widgetConfig = new google.maps.places.PlaceContextualListConfigElement({
    layout: google.maps.places.PlaceContextualListLayout.COMPACT
  });
  widget.appendChild(widgetConfig);
```
선택사항: 지도 모드를 변경합니다. 유효한 값은 다음과 같습니다.
- 2D 로드맵 지도: mapMode: google.maps.places.PlaceContextualListMapMode.ROADMAP
- 3D 하이브리드 지도: mapMode: google.maps.places.PlaceContextualListMapMode.HYBRID
- 지도가 없음: mapMode: google.maps.places.PlaceContextualListMapMode.NONE
이 코드 샘플은 지도 모드를 2D 지도로 변경하는 방법을 보여줍니다.
```
  const widgetConfig = new google.maps.places.PlaceContextualListConfigElement({
    mapMode: google.maps.places.PlaceContextualListMapMode.ROADMAP
  });
  widget.appendChild(widgetConfig);
```

소스 저작자 표시 요구사항

Google 지도를 통한 그라운딩을 사용하여 제공되는 정보를 직접 참조하는 Vertex AI 생성 콘텐츠를 표시할 때는 대답을 뒷받침하는 데 사용된 Google 지도 소스를 지정해야 합니다.

이 이미지는 모델의 대답을 지원하는 데 사용된 Google 지도 소스를 보여줍니다.

소스가 표시된 대답이 포함된 프롬프트

그라운딩 소스 사용에 대해 최종 사용자에게 알림

사용자에게 다음 사항을 알려야 합니다.

콘텐츠와 가까운 곳에서 LLM 생성 콘텐츠를 지원하는 데 사용된 그라운딩 소스입니다.
그라운딩 소스는 하나의 사용자 상호작용 내에서 볼 수 있어야 합니다.

Google 지도 소스 URL 표시

Google 지도 소스는 groundingChunks 및 groundingSupports 내의 groundingMetadata 내에 반환됩니다. Google 지도 소스는 장소와 응답을 생성하는 데 사용된 사용자 리뷰와 같은 장소 답변 콘텐츠를 지원하기 위해 반환됩니다.

이 코드 샘플은 응답에 장소 소스와 장소 답변 소스를 보여줍니다.

  "groundingChunks": [
            {
              "maps": {
                "uri": "{Link to Maps Content}",
                "title": "{Name of Maps Place}",
                "text": "{Maps content that was sent to the model for this place}"
                "placeId": "{Place ID}",
                "placeAnswerSources":
                                  {
                    "review": "",
                    "authorAttribution": {
                      "displayName": "",
                      "photoUri": ""
                    },
                    "flagContentUri": "",
                    "googleMapsUri": ""
                  },
              },
               "flagContentUri": ""
              }
            }
          }
        ],

LLM에서 참조하는 각 소스에 대해 다음 요구사항에 따라 링크 미리보기가 생성되어야 합니다.

텍스트 저작자 표시 가이드라인에 따라 각 소스의 출처를 Google 지도에 표시합니다.
Open Graph 페이지 제목 (og:title) 또는
형식의 제목을 표시합니다.
[Place Name] - Google Maps
소스 URL을 사용하여 소스 자료로 이동합니다.

groundingChunks에 장소 관련 답변 소스가 있는 경우 다음을 수행해야 합니다.

grounding_chunks.maps.placeAnswerSources.reviewSnippets.googleMapsUri 내에 리뷰 링크를 렌더링합니다.
Open Graph 제목 또는
형식의 제목을 표시합니다.
Google Review of [Place Name] by [Author Name]개
Place Name는 grounding_chunks.maps.title에서 확인할 수 있고 Author Name는 grounding_chunks.maps.placeAnswerSources.reviewSnippets.authorAttribution.displayName에서 확인할 수 있습니다.
선택사항: 다음과 같은 추가 콘텐츠로 링크 미리보기를 개선합니다.
- Google 지도 텍스트 저작자 표시 앞에 삽입된 Google 지도 파비콘 (<link rel="icon" href="https://www.google.com/favicon.ico">)
- 설명(og:description)
- 사진 (og:image)

이 이미지는 장소 링크를 표시하는 최소 요구사항을 보여줍니다.

소스가 표시된 대답이 포함된 프롬프트

소스 보기를 접을 수 있습니다.

대답과 소스가 접힌 프롬프트

이 이미지는 장소의 사진을 보여줍니다. 이는 소스의 속성을 미리 볼 수 있는 선택적 링크입니다.

대답 및 소스가 포함된 프롬프트

금지된 지역

Google 지도에서는 안전하고 신뢰할 수 있는 플랫폼을 유지하기 위해 특정 콘텐츠와 활동을 제한합니다. 금지 지역 목록은 Google Maps Platform 금지 지역을 참고하세요.

장소 속성

이 섹션에는 위치를 설명하고 Google 지도 그라운딩에서 응답을 생성하는 데 사용되는 장소 속성이 나열되어 있습니다. 이러한 속성은 Google 지도 기반 그라운딩이 대답할 수 있는 질문의 유형을 결정하는 데 사용됩니다.

샘플 장소 속성

이 목록은 모델이 응답을 생성하는 데 사용할 수 있는 장소에 관한 속성을 알파벳순으로 샘플링하여 제공합니다.

주소
매장 밖 수령
체크카드
거리
무료 주차장
라이브 음악
어린이 메뉴
영업시간
결제 옵션 (예: 현금 또는 신용카드)
장소 관련 답변
반려동물 동반 가능
맥주 제공
채식 요리 주문 가능
휠체어 이용 가능
Wi-Fi

장소 답변은 사용자 리뷰에서 파생된 정보를 기반으로 Google 지도 그라운딩에서 제공하는 대답입니다. 메타데이터에 제공된 장소 답변의 콘텐츠에 문제가 있는 경우 API 응답의 PlaceAnswerSources 객체 내 flagContentUri 필드의 링크를 사용하여 Google에 신고할 수 있습니다.

장소 속성 사용 예

다음 예에서는 다양한 유형의 장소에 관한 질문에 장소 속성을 사용합니다. Google 지도를 사용한 그라운딩은 속성을 사용하여 의도를 파악한 다음 Google 지도의 장소와 연결된 데이터를 기반으로 관련 답변을 제공합니다.

가족 저녁 식사 계획하기: 'The Italian Place'는 아이들에게 적합한가요? 테이크아웃도 가능한가요? 평점은 얼마인가요?
이러한 질문에 대한 답변은 식당이 가족에게 적합한지, 편리한 서비스를 제공하는지 판단하는 데 도움이 됩니다.
친구의 접근성 확인: 휠체어 이용 가능 입구가 있는 음식점이 필요해.와 같이 요청할 수 있습니다.
이 프롬프트에 대한 대답은 위치가 특정 접근성 요구사항을 충족하는지 확인하는 데 도움이 될 수 있습니다.
야식 장소 찾기: 지금 '버거 맛집'이 문을 열었어? 저녁 식사를 제공하나요? 금요일 영업시간은 어떻게 되나요?
이러한 질문에 대한 답변은 특정 시간에 특정 식사를 제공하는 영업 중인 매장을 찾는 데 도움이 됩니다.
커피를 마시며 고객과 미팅: '카페 센트럴'에 Wi-Fi가 있나요? 커피를 제공하나요? 가격대는 어느 정도이며 신용카드를 받나요?
이러한 질문에 대한 답변은 편의시설, 제공 서비스, 결제 옵션을 기반으로 비즈니스 회의에 적합한 카페를 평가하는 데 도움이 됩니다.

다음 단계

Gemini 모델을 데이터로 그라운딩하는 방법에 관한 자세한 내용은 데이터로 그라운딩을 참고하세요.
책임감 있는 AI 권장사항 및 Vertex AI의 안전 필터에 대해 자세히 알아보려면 책임감 있는 AI를 참조하세요.

Vertex AI에서 Google 지도로 그라운딩

개요

Google 지도를 사용한 그라운딩의 용도

지원되는 모델

Google 지도를 사용한 그라운딩으로 모델의 대답 그라운딩

콘솔

REST

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

선택사항: Google 지도 컨텍스트 위젯

Google 지도 컨텍스트 위젯 렌더링

HTML

자바스크립트

소스 저작자 표시 요구사항

그라운딩 소스 사용에 대해 최종 사용자에게 알림

Google 지도 소스 URL 표시

금지된 지역

장소 속성

샘플 장소 속성

장소 속성 사용 예

다음 단계

Vertex AI에서 Google 지도로 그라운딩 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

개요

Google 지도를 사용한 그라운딩의 용도

지원되는 모델

Google 지도를 사용한 그라운딩으로 모델의 대답 그라운딩

콘솔

REST

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

선택사항: Google 지도 컨텍스트 위젯

Google 지도 컨텍스트 위젯 렌더링

HTML

자바스크립트

소스 저작자 표시 요구사항

그라운딩 소스 사용에 대해 최종 사용자에게 알림

Google 지도 소스 URL 표시

금지된 지역

장소 속성

샘플 장소 속성

장소 속성 사용 예

다음 단계

Vertex AI에서 Google 지도로 그라운딩