Grounding API

在生成式 AI 領域，建立基準是指將模型輸出內容連結至可驗證的資訊來源。如果讓模型存取特定來源的資料，基準功能就會限制模型要使用這些資料來源生成輸出內容，減少捏造內容的機率。

您可以使用 Vertex AI，透過下列方式建立模型輸出內容的基準：

  • 以 Google 搜尋建立基準：以公開網路資料建立模型基準。
  • 運用 Google 地圖建立基準 - 運用 Google 地圖的地理空間資料建立模型基準。
  • 以您的資料建立基準 - 使用 Vertex AI Search 做為資料儲存庫，以您的資料建立模型基準。

如要進一步瞭解基準建立功能，請參閱基準建立總覽。

支援的模型

參數清單

如需實作詳情，請參閱範例。

googleSearch

根據 Google 搜尋的公開網路資料生成回覆。

googleMaps

根據 Google 地圖的公開地理空間資料，提供回覆內容。

API 輸入內容包含下列參數：

輸入參數

enable_widget

必要條件： boolean

可設為 true 或 false 的旗標。true 值會使用 API 回應傳回權杖，您可以在 Google 地圖情境小工具使用者介面中使用該權杖。

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

地點的專屬 ID。

review_id

必要條件：string

評論的專屬 ID。

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 使用 Gen 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 使用 Gen 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 使用 Gen 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 Applications」。

使用私人資料做為回覆基準前，請先建立資料儲存庫和搜尋應用程式。

警告：目前這個「基礎」介面不支援 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...'

後續步驟

如需詳細說明文件，請參閱下列內容：