Grounding API

생성형 AI에서 그라운딩은 모델 출력을 확인 가능한 정보 소스에 연결하는 기능입니다. 모델에 특정 데이터 소스에 대한 액세스 권한을 제공하면 그라운딩에서 이러한 데이터에 대한 출력을 테더링하므로 콘텐츠가 조작될 가능성이 줄어듭니다.

Vertex AI를 사용하면 다음과 같은 방법으로 모델 출력을 그라운딩할 수 있습니다.

  • Google 검색으로 그라운딩 - 공개적으로 사용 가능한 웹 데이터로 모델을 그라운딩합니다.
  • Google 지도로 그라운딩 - Google 지도의 지리 공간 데이터로 모델을 그라운딩합니다.
  • 데이터에 그라운딩 - Vertex AI Search의 데이터를 데이터 스토어로 사용하여 모델을 그라운딩합니다.

그라운딩에 관한 자세한 내용은 그라운딩 개요를 참조하세요.

지원되는 모델

파라미터 목록

구현 세부정보는 예시를 참조하세요.

googleSearch

Google 검색의 공개 웹 데이터를 사용하여 응답을 그라운딩합니다.

googleMaps

Google 지도에서 공개적으로 사용 가능한 지리 공간 데이터를 사용하여 응답을 그라운딩합니다.

API 입력에는 다음 파라미터가 포함됩니다.

입력 파라미터

enable_widget

필수: boolean

true 또는 false로 설정할 수 있는 플래그입니다. true 값은 Google 지도 컨텍스트 위젯 사용자 인터페이스와 함께 사용할 수 있는 API 응답을 사용하여 토큰을 반환합니다.

API 응답 구조에는 다음 파라미터가 포함됩니다.

응답 파라미터

grounding_metadata

필수: Object

그라운딩 정보를 포함하는 기본 필드입니다.
  • grounding_support: 그라운딩 지원 수준을 나타내는 하위 필드입니다.
  • grounding_chunks.maps: 그라운딩된 응답을 생성하는 데 사용된 장소 소스를 포함하는 하위 필드입니다.
    • place_answer_sources.review_snippets: 장소 답변이 쿼리에 답변하는 데 사용될 때 표시되는 grounding_chunks.maps 내의 하위 필드입니다. 장소 답변은 사용자 리뷰와 같은 데이터를 사용하여 특정 장소에 관한 심층적인 맥락 정보를 제공합니다. 장소 답변은 사용자 리뷰와 같은 소스 목록을 기반으로 합니다.

속성

장소 또는 사용자 리뷰 소스에는 다음과 같은 속성이 있습니다.

속성

title

필수: Object

소스의 제목입니다.

uri

필수: string

소스에 연결되는 URI입니다.

place_id

필수: string

장소의 고유 식별자입니다.

review_id

필수: string

리뷰의 고유 식별자입니다.

retrieval

Vertex AI Search의 비공개 데이터를 데이터 스토어로 사용하여 응답을 그라운딩합니다. 모델이 호출하여 외부 지식에 액세스할 수 있는 검색 도구를 정의합니다.

매개변수

vertexAiSearch

필수: VertexAISearch

Vertex AI Search 데이터 소스로 그라운딩합니다.

VertexAISearch

매개변수

datastore

필수: string

Vertex AI Search의 정규화된 데이터 스토어 리소스 ID이며, projects/{project}/locations/{location}/collections/default_collection/dataStores/{datastore} 형식입니다.

예시

이 섹션에서는 Google 검색을 사용하여 공개 웹 데이터에 대한 응답을 그라운딩하고 Vertex AI Search를 사용하여 비공개 데이터에 대한 응답을 그라운딩하는 예시를 제공합니다.

Google 검색을 사용하여 공개 웹 데이터에 대한 응답 그라운딩

Google 검색 공개 데이터를 사용하여 응답을 그라운딩합니다. 요청에 google_search_retrieval 도구를 포함합니다. 추가 파라미터는 필요하지 않습니다.

Python

설치

pip install --upgrade google-genai

자세한 내용은 SDK 참고 문서를 참조하세요.

Vertex AI에서 생성형 AI SDK를 사용하도록 환경 변수를 설정합니다. 

# 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,
    GoogleSearch,
    HttpOptions,
    Tool,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="When is the next total solar eclipse in the United States?",
    config=GenerateContentConfig(
        tools=[
            # Use Google Search Tool
            Tool(google_search=GoogleSearch())
        ],
    ),
)

print(response.text)
# Example response:
# 'The next total solar eclipse in the United States will occur on ...'

Go

Go를 설치하거나 업데이트하는 방법을 알아보세요.

자세한 내용은 SDK 참고 문서를 참조하세요.

Vertex AI에서 생성형 AI SDK를 사용하도록 환경 변수를 설정합니다. 

# 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
 

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithGoogleSearch shows how to generate text using Google Search.
func generateWithGoogleSearch(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "When is the next total solar eclipse in the United States?"},
		},
			Role: "user"},
	}
	config := &genai.GenerateContentConfig{
		Tools: []*genai.Tool{
			{GoogleSearch: &genai.GoogleSearch{}},
		},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// The next total solar eclipse in the United States will occur on March 30, 2033, but it will only ...

	return nil
}

Java

Java를 설치하거나 업데이트하는 방법을 알아보세요.

자세한 내용은 SDK 참고 문서를 참조하세요.

Vertex AI에서 생성형 AI SDK를 사용하도록 환경 변수를 설정합니다. 

# 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
 


import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.GoogleSearch;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Tool;

public class ToolsGoogleSearchWithText {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    generateContent(modelId);
  }

  // Generates text with Google Search tool
  public static String generateContent(String modelId) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      // Create a GenerateContentConfig and set Google Search tool
      GenerateContentConfig contentConfig =
          GenerateContentConfig.builder()
              .tools(Tool.builder().googleSearch(GoogleSearch.builder().build()).build())
              .build();

      GenerateContentResponse response =
          client.models.generateContent(
              modelId, "When is the next total solar eclipse in the United States?", contentConfig);

      System.out.print(response.text());
      // Example response:
      // The next total solar eclipse in the United States will occur on...
      return response.text();
    }
  }
}

Vertex AI Search를 사용한 비공개 데이터에 대한 기본 응답

Vertex AI Search 데이터 스토어의 데이터로 응답을 그라운딩합니다. 자세한 내용은 AI 애플리케이션을 참조하세요.

비공개 데이터로 응답을 그라운딩하기 전에 데이터 스토어와 검색 앱을 만듭니다.

경고: 당분간 이 '그라운딩' 인터페이스는 Vertex AI Search '청크 모드'를 지원하지 않습니다.

Python용 Gen AI SDK

from google import genai
from google.genai.types import (
    GenerateContentConfig,
    HttpOptions,
    Retrieval,
    Tool,
    VertexAISearch,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))

# Load Data Store ID from Vertex AI Search
# datastore = "projects/111111111111/locations/global/collections/default_collection/dataStores/data-store-id"

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="How do I make an appointment to renew my driver's license?",
    config=GenerateContentConfig(
        tools=[
            # Use Vertex AI Search Tool
            Tool(
                retrieval=Retrieval(
                    vertex_ai_search=VertexAISearch(
                        datastore=datastore,
                    )
                )
            )
        ],
    ),
)

print(response.text)
# Example response:
# 'The process for making an appointment to renew your driver's license varies depending on your location. To provide you with the most accurate instructions...'

다음 단계

자세한 문서는 다음을 참조하세요.