API Grounding

Di AI generatif, grounding merupakan kemampuan untuk menghubungkan output model dengan sumber informasi yang dapat diverifikasi. Jika Anda memberi model akses ke sumber data tertentu, grounding akan mengaitkan outputnya ke data ini dan mengurangi peluang pembuatan konten yang dikarang-karang.

Dengan Vertex AI, Anda dapat melakukan grounding pada output model dengan cara berikut:

  • Grounding dengan Google Penelusuran - melakukan grounding pada model dengan data web yang tersedia secara publik.
  • Grounding dengan Google Maps - melakukan grounding pada model dengan data geospasial dari Google Maps.
  • Grounding ke data Anda - melakukan grounding pada model dengan data Anda dari Agent Search sebagai penyimpanan data.

Untuk mengetahui informasi selengkapnya tentang grounding, lihat Ringkasan grounding.

Model yang didukung

Daftar parameter

Lihat contoh untuk mengetahui detail penerapan.

googleSearch

Lakukan grounding pada respons dengan data web yang tersedia secara publik dari Google Penelusuran.

googleMaps

Lakukan grounding pada respons dengan data geospasial yang tersedia secara publik dari Google Maps.

Input API mencakup parameter berikut:

Parameter input

enable_widget

Wajib: boolean

Flag yang dapat ditetapkan ke true atau false. Nilai true akan menampilkan token menggunakan respons API yang dapat Anda gunakan dengan antarmuka pengguna widget konteks Google Maps.

Struktur respons API mencakup parameter berikut:

Parameter respons

grounding_metadata

Wajib: Object

Kolom utama yang berisi informasi grounding.
  • grounding_support: Sub-kolom yang menunjukkan tingkat dukungan grounding.
  • grounding_chunks.maps: Sub-kolom yang berisi sumber tempat yang digunakan untuk membuat respons yang di-grounding.
    • place_answer_sources.review_snippets: Sub-kolom dalam grounding_chunks.maps yang muncul saat jawaban tempat digunakan untuk menjawab kueri. Jawaban tempat memberikan informasi kontekstual yang lebih mendalam tentang tempat tertentu menggunakan data, seperti ulasan pengguna. Jawaban tempat didukung oleh daftar sumber seperti ulasan pengguna.

Atribut

Sumber ulasan tempat atau pengguna memiliki atribut berikut:

Atribut

title

Wajib: Object

Judul sumber.

uri

Wajib: string

URI yang menautkan ke sumber.

place_id

Wajib: string

ID unik untuk tempat.

review_id

Wajib: string

ID unik untuk ulasan.

retrieval

Lakukan grounding pada respons dengan data pribadi dari Agent Search sebagai penyimpanan data. Menentukan alat pengambilan yang dapat dipanggil model untuk mengakses pengetahuan eksternal.

Parameter

vertexAiSearch

Wajib: VertexAISearch

Lakukan grounding dengan sumber data Agent Search.

VertexAISearch

Parameter

datastore

Wajib: string

ID resource penyimpanan data yang sepenuhnya memenuhi syarat dari Agent Search, dalam format berikut: projects/{project}/locations/{location}/collections/default_collection/dataStores/{datastore}

Contoh

Bagian ini memberikan contoh untuk melakukan grounding pada respons terhadap data web publik menggunakan Google Penelusuran dan melakukan grounding pada respons terhadap data pribadi menggunakan Agent Search.

Melakukan grounding pada respons terhadap data web publik menggunakan Google Penelusuran

Lakukan grounding pada respons dengan data publik Google Penelusuran. Sertakan alat google_search_retrieval dalam permintaan. Tidak diperlukan parameter tambahan.

Python

Menginstal

pip install --upgrade google-genai

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan Gen AI SDK dengan Vertex AI: 

# 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(
                    # Optional: Domains to exclude from results
                    exclude_domains=["domain.com", "domain2.com"]
                )
            )
        ],
    ),
)

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

Go

Pelajari cara menginstal atau mengupdate Go.

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan Gen AI SDK dengan Vertex AI: 

# 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: genai.RoleUser},
	}
	config := &genai.GenerateContentConfig{
		Tools: []*genai.Tool{
			{GoogleSearch: &genai.GoogleSearch{ExcludeDomains: []string{"example.com", "example.org"}}},
		},
	}

	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

Pelajari cara menginstal atau mengupdate Java.

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan Gen AI SDK dengan Vertex AI: 

# 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 content 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();
    }
  }
}

Node.js

Menginstal

npm install @google/genai

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan Gen AI SDK dengan Vertex AI: 

# 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
 

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateGoogleSearch(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: 'When is the next total solar eclipse in the United States?',
    config: {
      tools: [
        {
          googleSearch: {},
        },
      ],
    },
  });

  console.log(response.text);

  // Example response:
  //    'The next total solar eclipse in United States will occur on ...'

  return response.text;
}

Melakukan grounding pada respons terhadap data pribadi menggunakan Agent Search

Lakukan grounding pada respons dengan data dari penyimpanan data Agent Search. Untuk mengetahui informasi selengkapnya, lihat Agent Search.

Sebelum melakukan grounding pada respons dengan data pribadi, buat penyimpanan data dan aplikasi penelusuran.

PERINGATAN: Untuk saat ini, antarmuka "grounding" ini tidak mendukung "mode potongan" Agent Search.

Gen AI SDK untuk Python

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...'

Langkah berikutnya

Untuk dokumentasi mendetail, lihat hal berikut: