Perujukan dengan Google Penelusuran

Halaman ini menjelaskan cara melakukan grounding respons Gemini menggunakan hasil dari mesin telusur Google, yang menggunakan data web yang tersedia secara publik. Selain itu, Saran Penelusuran yang disertakan dalam respons Anda juga dijelaskan.

Jika Anda ingin menghubungkan model dengan informasi global, rentang potensi topik yang luas, atau informasi terbaru di Internet, gunakan Grounding dengan Google Penelusuran.

Untuk mempelajari lebih lanjut perujukan model di Vertex AI, lihat Ringkasan perujukan.

Model yang didukung

Bagian ini mencantumkan model yang mendukung perujukan dengan Penelusuran.

Bahasa yang didukung

Untuk mengetahui daftar bahasa yang didukung, lihat Bahasa.

Gunakan petunjuk berikut untuk men-grounding model dengan data web yang tersedia secara publik.

Pertimbangan

  • Untuk menggunakan Grounding dengan Google Penelusuran, Anda harus mengaktifkan Saran Penelusuran Google. Untuk mengetahui informasi selengkapnya, lihat Menggunakan saran Google Penelusuran.

  • Untuk hasil yang ideal, gunakan suhu 1.0. Untuk mempelajari lebih lanjut cara menyetel konfigurasi ini, lihat isi permintaan Gemini API dari referensi model.

  • Perujukan dengan Google Penelusuran memiliki batas satu juta kueri per hari. Jika Anda memerlukan kueri lainnya, hubungi Google Cloud dukungan untuk mendapatkan bantuan.

Hasil penelusuran dapat disesuaikan untuk lokasi geografis tertentu dari pengguna akhir dengan menggunakan koordinat lintang dan bujur. Untuk mengetahui informasi selengkapnya, lihat API Perujukan.

Konsol

Untuk menggunakan Perujukan dengan Google Penelusuran dengan Vertex AI Studio, ikuti langkah-langkah berikut:

  1. Di konsol Google Cloud , buka halaman Vertex AI Studio.

    Buka Vertex AI Studio

  2. Klik tab Freeform.
  3. Di panel samping, klik tombol Respons model dasar.
  4. Klik Sesuaikan dan tetapkan Grounding dengan Google Penelusuran sebagai sumber.
  5. Masukkan perintah Anda di kotak teks, lalu klik Kirim.

Respons perintah Anda kini menggunakan Grounding dengan Google Penelusuran.

Python

Instal

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

Instal

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;
}

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • LOCATION: Region untuk memproses permintaan. Untuk menggunakan endpoint global, kecualikan lokasi dari nama endpoint dan konfigurasi lokasi resource ke global.
  • PROJECT_ID: Project ID Anda.
  • MODEL_ID: ID model multimodal.
  • TEXT: Petunjuk teks yang akan disertakan dalam perintah.
  • EXCLUDE_DOMAINS: Opsional: Daftar domain yang tidak akan digunakan untuk perujukan.
  • LATITUDE: Opsional: Lintang lokasi pengguna akhir. Misalnya, garis lintang 37.7749 mewakili San Francisco. Anda dapat memperoleh koordinat lintang dan bujur menggunakan layanan seperti Google Maps atau alat geocoding lainnya.
  • LONGITUDE: Opsional: Bujur lokasi pengguna akhir. Misalnya, garis bujur -122.4194 mewakili San Francisco.

Metode HTTP dan URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

Meminta isi JSON: 

{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "TEXT"
    }]
  }],
  "tools": [{
    "googleSearch": {
      "exclude_domains": [ "domain.com", "domain2.com" ]
    }
  }],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {
        "latitude": LATITUDE,
        "longitude": LONGITUDE
      }
    }
  },
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "The weather in Chicago this weekend, will be partly cloudy. The temperature will be between 49°F (9°C) and 55°F (13°C) on Saturday and between 51°F (11°C) and 56°F (13°C) on Sunday. There is a slight chance of rain on both days.\n"
          }
        ]
      },
      "finishReason": "STOP",
      "groundingMetadata": {
        "webSearchQueries": [
          "weather in Chicago this weekend"
        ],
        "searchEntryPoint": {
          "renderedContent": "..."
        },
        "groundingChunks": [
          {
            "web": {
              "uri": "https://www.google.com/search?q=weather+in+Chicago,+IL",
              "title": "Weather information for locality: Chicago, administrative_area: IL",
              "domain": "google.com"
            }
          },
          {
            "web": {
              "uri": "...",
              "title": "weatherbug.com",
              "domain": "weatherbug.com"
            }
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 85,
              "endIndex": 214,
              "text": "The temperature will be between 49°F (9°C) and 55°F (13°C) on Saturday and between 51°F (11°C) and 56°F (13°C) on Sunday."
            },
            "groundingChunkIndices": [
              0
            ],
            "confidenceScores": [
              0.8662828
            ]
          },
          {
            "segment": {
              "startIndex": 215,
              "endIndex": 261,
              "text": "There is a slight chance of rain on both days."
            },
            "groundingChunkIndices": [
              1,
              0
            ],
            "confidenceScores": [
              0.62836814,
              0.6488607
            ]
          }
        ],
        "retrievalMetadata": {}
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 98,
    "totalTokenCount": 108,
    "trafficType": "ON_DEMAND",
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 10
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 98
      }
    ]
  },
  "modelVersion": "gemini-2.0-flash",
  "createTime": "2025-05-19T14:42:55.000643Z",
  "responseId": "b0MraIMFoqnf-Q-D66G4BQ"
}

Memahami respons Anda

Jika perintah model Anda berhasil menggunakan Perujukan dengan Google Penelusuran dari Vertex AI Studio atau dari API, respons akan menyertakan metadata dengan link sumber (URL web). Namun, ada beberapa alasan mengapa metadata ini mungkin tidak diberikan, dan respons perintah tidak akan memiliki rujukan. Alasan ini mencakup relevansi sumber yang rendah atau informasi yang tidak lengkap dalam respons model.

Dukungan perujukan

Menampilkan dukungan perujukan diperlukan karena membantu Anda memvalidasi respons dari penayang dan menambahkan cara untuk mempelajari lebih lanjut.

Dukungan perujukan untuk respons dari sumber web harus ditampilkan baik secara inline maupun secara gabungan. Misalnya, lihat gambar berikut sebagai saran tentang cara melakukannya.

Contoh dukungan perujukan

Penggunaan opsi mesin telusur alternatif

Saat menggunakan Grounding dengan Google Penelusuran, Aplikasi Pelanggan dapat:

  • Menawarkan opsi mesin telusur alternatif,
  • Menjadikan mesin telusur lain sebagai opsi default,
  • Menampilkan saran penelusuran atau hasil penelusuran mereka sendiri atau pihak ketiga selama: semua hasil non-Google harus ditampilkan secara terpisah dari Hasil yang Sesuai dan Saran Penelusuran Google, serta ditampilkan dengan cara yang tidak membingungkan pengguna atau menyarankan bahwa hasil tersebut berasal dari Google.

Manfaat

Perintah dan alur kerja kompleks berikut yang memerlukan perencanaan, penalaran, dan pemikiran dapat dilakukan saat Anda menggunakan Grounding dengan Google Penelusuran sebagai alat:

  • Anda dapat melakukan perujukan untuk membantu memastikan respons didasarkan pada informasi terbaru dan paling akurat.
  • Anda dapat mengambil artefak dari web untuk melakukan analisis.
  • Anda dapat menemukan gambar, video, atau media lain yang relevan untuk membantu penalaran multimodal atau pembuatan tugas.
  • Anda dapat melakukan coding, pemecahan masalah teknis, dan tugas khusus lainnya.
  • Anda dapat menemukan informasi khusus wilayah, atau membantu menerjemahkan konten secara akurat.
  • Anda dapat menemukan situs yang relevan untuk dijelajahi.

Menggunakan Saran Google Penelusuran

Saat Anda menggunakan Perujukan dengan Google Penelusuran, dan Anda menerima Saran Penelusuran dalam respons Anda, Anda harus menampilkan Saran Penelusuran dalam produksi dan di aplikasi Anda.

Secara khusus, Anda harus menampilkan kueri penelusuran yang disertakan dalam metadata respons yang memiliki rujukan. Responsnya mencakup:

  • "content": Respons yang dihasilkan LLM.
  • "webSearchQueries": Kueri yang akan digunakan untuk Saran Penelusuran.

Misalnya, dalam cuplikan kode berikut, Gemini merespons perintah berbasis Penelusuran, yang menanyakan tentang jenis tanaman tropis.

"predictions": [
  {
    "content": "Monstera is a type of vine that thrives in bright indirect light…",
    "groundingMetadata": {
      "webSearchQueries": ["What's a monstera?"],
    }
  }
]

Anda dapat mengambil output ini, dan menampilkannya menggunakan Saran Penelusuran.

Persyaratan untuk Saran Penelusuran

Berikut ini diperlukan untuk Saran Penelusuran:

Persyaratan Deskripsi
Anjuran
  • Saat mematuhi persyaratan tampilan, Saran Penelusuran ditampilkan persis seperti yang diberikan tanpa perubahan apa pun.
  • Saat berinteraksi dengan Saran Penelusuran, Anda akan langsung diarahkan ke halaman hasil Penelusuran (SRP).
Larangan
  • Sertakan layar atau langkah tambahan apa pun antara ketukan pengguna dan tampilan SRP.
  • Menampilkan hasil atau saran penelusuran lainnya di samping Saran Penelusuran atau respons LLM dengan grounding terkait.

Persyaratan tampilan

Berikut adalah persyaratan tampilan:

  • Tampilkan Saran Penelusuran persis seperti yang diberikan, dan jangan lakukan modifikasi apa pun pada warna, font, atau tampilan. Pastikan Saran Penelusuran dirender seperti yang ditentukan dalam mockup berikut seperti mode terang dan gelap:

  • Setiap kali respons berbasis rujukan ditampilkan, Saran Penelusuran yang sesuai harus tetap terlihat.
  • Untuk branding, Anda harus mematuhi pedoman Google secara ketat terkait penggunaan fitur merek Google oleh pihak ketiga di Selamat datang di Pusat Referensi Merek kami.
  • Saat Anda menggunakan perujukan dengan Penelusuran, chip Saran Penelusuran akan ditampilkan. Kolom yang berisi chip Saran Penelusuran harus memiliki lebar yang sama dengan respons dengan grounding dari LLM.

Perilaku saat diketuk

Saat pengguna mengetuk chip, mereka akan langsung diarahkan ke halaman hasil Penelusuran (SRP) untuk istilah penelusuran yang ditampilkan di chip. SRP dapat dibuka di dalam browser dalam aplikasi atau di aplikasi browser terpisah. Anda tidak boleh meminimalkan, menghapus, atau menghalangi tampilan SRP dengan cara apa pun. Mockup animasi berikut menggambarkan interaksi ketuk untuk membuka SRP.

Contoh aplikasi/desktop

Kode untuk menerapkan Saran Penelusuran

Saat Anda menggunakan API untuk memberi landasan pada respons penelusuran, respons model akan memberikan gaya HTML dan CSS yang sesuai di kolom renderedContent, yang Anda terapkan untuk menampilkan Saran Penelusuran di aplikasi Anda.

Selain itu, Saran Penelusuran sebelumnya disebut sebagai Titik Entri Penelusuran. Meskipun Anda mungkin menemukan referensi ke Titik Entri Penelusuran di beberapa kolom API, kedua istilah tersebut merujuk pada Saran Penelusuran saat ini yang Anda terima dalam respons API.

Perubahan penagihan dengan Gemini 3

Saat Anda menggunakan Grounding dengan Google Penelusuran di model Gemini 3, penagihan dilakukan untuk setiap kueri penelusuran yang dibuat oleh Gemini dan dikirim ke Penelusuran. Satu perintah dapat menghasilkan satu atau beberapa kueri penelusuran.

Contoh

Contoh ini menunjukkan contoh perintah pengguna dan kueri penelusuran yang mungkin dikenai biaya.

  • Perintah pengguna: Ceritakan kehidupan Albert Einstein.
  • Gemini mungkin membuat kueri penelusuran berikut:
    • Kelahiran Albert Einstein dan pendidikan awal
    • Teori relativitas Albert Einstein
    • Kehidupan Albert Einstein di Amerika Serikat

Dalam contoh ini, ketiga kueri penelusuran ini dikenai biaya.

Langkah berikutnya