Fitur Grounding with Google Search di Gemini API dan AI Studio dapat digunakan untuk meningkatkan akurasi dan keaktualan respons dari model. Selain respons yang lebih faktual, saat Referensi dengan Google Penelusuran diaktifkan, Gemini API akan menampilkan sumber referensi (link pendukung inline) dan Saran Google Penelusuran beserta konten respons. Saran Penelusuran mengarahkan pengguna ke hasil penelusuran yang sesuai dengan respons yang berdasar.
Panduan ini akan membantu Anda memulai Perujukan dengan Google Penelusuran menggunakan salah satu Gemini API SDK atau REST API.
Mengonfigurasi Grounding Penelusuran
Mulai Gemini 2.0, Google Penelusuran tersedia sebagai alat. Artinya, model dapat memutuskan kapan harus menggunakan Google Penelusuran. Contoh berikut menunjukkan cara mengonfigurasi Penelusuran sebagai alat.
from google import genai
from google.genai.types import Tool, GenerateContentConfig, GoogleSearch
client = genai.Client()
model_id = "gemini-2.0-flash"
google_search_tool = Tool(
google_search = GoogleSearch()
)
response = client.models.generate_content(
model=model_id,
contents="When is the next total solar eclipse in the United States?",
config=GenerateContentConfig(
tools=[google_search_tool],
response_modalities=["TEXT"],
)
)
for each in response.candidates[0].content.parts:
print(each.text)
# Example response:
# The next total solar eclipse visible in the contiguous United States will be on ...
# To get grounding metadata as web content.
print(response.candidates[0].grounding_metadata.search_entry_point.rendered_content)
Fungsi Penelusuran sebagai alat juga memungkinkan penelusuran multi-giliran dan kueri multi-alat (misalnya, menggabungkan Grounding dengan Google Penelusuran dan eksekusi kode).
Penelusuran sebagai alat memungkinkan perintah dan alur kerja kompleks yang memerlukan perencanaan, pemikiran, dan pemikiran:
- Dasar untuk meningkatkan faktualitas dan keaktualan serta memberikan jawaban yang lebih akurat
- Mengambil artefak dari web untuk melakukan analisis lebih lanjut
- Menemukan gambar, video, atau media lain yang relevan untuk membantu tugas pemikiran atau pembuatan multimodal
- Coding, pemecahan masalah teknis, dan tugas khusus lainnya
- Menemukan informasi khusus wilayah atau membantu menerjemahkan konten secara akurat
- Menemukan situs yang relevan untuk penjelajahan lebih lanjut
Perujukan dengan Google Penelusuran berfungsi dengan semua bahasa yang tersedia saat melakukan perintah teks. Pada tingkat berbayar Gemini Developer API, Anda bisa mendapatkan 1.500 kueri Grounding dengan Google Penelusuran per hari secara gratis, dengan kueri tambahan yang ditagih dengan tarif standar $35 per 1.000 kueri.
Anda dapat mempelajari lebih lanjut dengan mencoba notebook Alat penelusuran.
Saran Google Penelusuran
Untuk menggunakan Grounding dengan Google Penelusuran, Anda harus menampilkan Saran Google Penelusuran, yang merupakan kueri yang disarankan dan disertakan dalam metadata respons yang di-grounding. Untuk mempelajari persyaratan tampilan lebih lanjut, lihat Menggunakan Saran Google Penelusuran.
Pengambilan Google Penelusuran
Pengambilan dinamis
Beberapa kueri cenderung mendapatkan manfaat lebih besar dari Perujukan dengan Google Penelusuran daripada kueri lainnya. Fitur pengambilan dinamis memberi Anda kontrol tambahan terkait waktu penggunaan Perujukan dengan Google Penelusuran.
Jika mode pengambilan dinamis tidak ditentukan, Pembumian dengan Google Penelusuran akan selalu dipicu. Jika mode disetel ke dinamis, model akan memutuskan kapan harus menggunakan pembumian berdasarkan nilai minimum yang dapat Anda konfigurasi. Nilai minimum adalah nilai floating point dalam rentang [0,1] dan default-nya adalah 0,3. Jika nilai nilai minimum adalah 0, respons selalu didasarkan pada Google Penelusuran; jika nilainya 1, respons tidak pernah didasarkan pada Google Penelusuran.
Cara kerja pengambilan dinamis
Anda dapat menggunakan pengambilan dinamis dalam permintaan untuk memilih kapan akan mengaktifkan Perujukan dengan Google Penelusuran. Hal ini berguna jika perintah tidak memerlukan jawaban yang didasarkan pada Google Penelusuran dan model dapat memberikan jawaban berdasarkan pengetahuannya sendiri tanpa dasar. Hal ini membantu Anda mengelola latensi, kualitas, dan biaya secara lebih efektif.
Sebelum memanggil konfigurasi pengambilan dinamis dalam permintaan, pahami terminologi berikut:
Skor prediksi: Saat Anda meminta jawaban yang berdasar, Gemini akan menetapkan skor prediksi ke perintah. Skor prediksi adalah nilai floating point dalam rentang [0,1]. Nilainya bergantung pada apakah perintah dapat memanfaatkan perujukan jawaban dengan informasi terbaru dari Google Penelusuran. Dengan demikian, jika perintah memerlukan jawaban yang didasarkan pada fakta terbaru di web, perintah tersebut memiliki skor prediksi yang lebih tinggi. Perintah yang jawabannya dihasilkan model memiliki skor prediksi yang lebih rendah.
Berikut adalah contoh beberapa perintah dan skor prediksinya.
Perintah Skor prediksi Komentar "Tulis puisi tentang peony" 0,13 Model dapat mengandalkan pengetahuannya dan jawabannya tidak memerlukan perujukan. "Sarankan mainan untuk anak berusia 2 tahun" 0,36 Model dapat mengandalkan pengetahuannya dan jawabannya tidak memerlukan perujukan. "Bisakah Anda memberikan resep guacamole bergaya Asia?" 0.55 Google Penelusuran dapat memberikan jawaban yang berdasar, tetapi dasar tidak mutlak diperlukan; pengetahuan model mungkin sudah memadai. "Apa itu Agent Builder? How is grounding billed in Agent Builder?" 0,72 Memerlukan Google Penelusuran untuk menghasilkan jawaban yang berdasar. "Siapa yang memenangkan grand prix F1 terbaru?" 0,97 Memerlukan Google Penelusuran untuk menghasilkan jawaban yang berdasar. Batas: Dalam permintaan API, Anda dapat menentukan konfigurasi pengambilan dinamis dengan batas. Batas adalah nilai floating point dalam rentang [0,1] dan default-nya adalah 0,3. Jika nilai nilai minimumnya nol, respons akan selalu dihubungkan dengan Google Penelusuran. Untuk semua nilai batas lainnya, hal berikut berlaku:
- Jika skor prediksi lebih besar dari atau sama dengan nilai minimum, jawaban akan didasarkan pada Google Penelusuran. Batas yang lebih rendah menyiratkan bahwa lebih banyak perintah memiliki respons yang dibuat menggunakan Perujukan dengan Google Penelusuran.
- Jika skor prediksi kurang dari nilai minimum, model mungkin masih membuat jawaban, tetapi tidak didasarkan pada Google Penelusuran.
Untuk mempelajari cara menetapkan nilai minimum pengambilan dinamis menggunakan SDK atau REST API, lihat contoh kode yang sesuai.
Untuk menemukan nilai minimum yang sesuai dengan kebutuhan bisnis Anda, Anda dapat membuat kumpulan kueri perwakilan yang diperkirakan akan Anda temui. Kemudian, Anda dapat mengurutkan kueri sesuai dengan skor prediksi dalam respons dan memilih nilai minimum yang baik untuk kasus penggunaan Anda.
Respons yang berdasar
Jika perintah Anda berhasil dihubungkan ke Google Penelusuran, respons akan menyertakan
groundingMetadata. Respons yang di-ground mungkin terlihat seperti ini
(bagian respons telah dihilangkan agar singkat):
{
"candidates": [
{
"content": {
"parts": [
{
"text": "Carlos Alcaraz won the Gentlemen's Singles title at the 2024 Wimbledon Championships. He defeated Novak Djokovic in the final, winning his second consecutive Wimbledon title and fourth Grand Slam title overall. \n"
}
],
"role": "model"
},
...
"groundingMetadata": {
"searchEntryPoint": {
"renderedContent": "\u003cstyle\u003e\n.container {\n align-items: center;\n border-radius: 8px;\n display: flex;\n font-family: Google Sans, Roboto, sans-serif;\n font-size: 14px;\n line-height: 20px;\n padding: 8px 12px;\n}\n.chip {\n display: inline-block;\n border: solid 1px;\n border-radius: 16px;\n min-width: 14px;\n padding: 5px 16px;\n text-align: center;\n user-select: none;\n margin: 0 8px;\n -webkit-tap-highlight-color: transparent;\n}\n.carousel {\n overflow: auto;\n scrollbar-width: none;\n white-space: nowrap;\n margin-right: -12px;\n}\n.headline {\n display: flex;\n margin-right: 4px;\n}\n.gradient-container {\n position: relative;\n}\n.gradient {\n position: absolute;\n transform: translate(3px, -9px);\n height: 36px;\n width: 9px;\n}\n@media (prefers-color-scheme: light) {\n .container {\n background-color: #fafafa;\n box-shadow: 0 0 0 1px #0000000f;\n }\n .headline-label {\n color: #1f1f1f;\n }\n .chip {\n background-color: #ffffff;\n border-color: #d2d2d2;\n color: #5e5e5e;\n text-decoration: none;\n }\n .chip:hover {\n background-color: #f2f2f2;\n }\n .chip:focus {\n background-color: #f2f2f2;\n }\n .chip:active {\n background-color: #d8d8d8;\n border-color: #b6b6b6;\n }\n .logo-dark {\n display: none;\n }\n .gradient {\n background: linear-gradient(90deg, #fafafa 15%, #fafafa00 100%);\n }\n}\n@media (prefers-color-scheme: dark) {\n .container {\n background-color: #1f1f1f;\n box-shadow: 0 0 0 1px #ffffff26;\n }\n .headline-label {\n color: #fff;\n }\n .chip {\n background-color: #2c2c2c;\n border-color: #3c4043;\n color: #fff;\n text-decoration: none;\n }\n .chip:hover {\n background-color: #353536;\n }\n .chip:focus {\n background-color: #353536;\n }\n .chip:active {\n background-color: #464849;\n border-color: #53575b;\n }\n .logo-light {\n display: none;\n }\n .gradient {\n background: linear-gradient(90deg, #1f1f1f 15%, #1f1f1f00 100%);\n }\n}\n\u003c/style\u003e\n\u003cdiv class=\"container\"\u003e\n \u003cdiv class=\"headline\"\u003e\n \u003csvg class=\"logo-light\" width=\"18\" height=\"18\" viewBox=\"9 9 35 35\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"\u003e\n \u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M42.8622 27.0064C42.8622 25.7839 42.7525 24.6084 42.5487 23.4799H26.3109V30.1568H35.5897C35.1821 32.3041 33.9596 34.1222 32.1258 35.3448V39.6864H37.7213C40.9814 36.677 42.8622 32.2571 42.8622 27.0064V27.0064Z\" fill=\"#4285F4\"/\u003e\n \u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M26.3109 43.8555C30.9659 43.8555 34.8687 42.3195 37.7213 39.6863L32.1258 35.3447C30.5898 36.3792 28.6306 37.0061 26.3109 37.0061C21.8282 37.0061 18.0195 33.9811 16.6559 29.906H10.9194V34.3573C13.7563 39.9841 19.5712 43.8555 26.3109 43.8555V43.8555Z\" fill=\"#34A853\"/\u003e\n \u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M16.6559 29.8904C16.3111 28.8559 16.1074 27.7588 16.1074 26.6146C16.1074 25.4704 16.3111 24.3733 16.6559 23.3388V18.8875H10.9194C9.74388 21.2072 9.06992 23.8247 9.06992 26.6146C9.06992 29.4045 9.74388 32.022 10.9194 34.3417L15.3864 30.8621L16.6559 29.8904V29.8904Z\" fill=\"#FBBC05\"/\u003e\n \u003cpath fill-rule=\"evenodd\" clip-rule=\"evenodd\" d=\"M26.3109 16.2386C28.85 16.2386 31.107 17.1164 32.9095 18.8091L37.8466 13.8719C34.853 11.082 30.9659 9.3736 26.3109 9.3736C19.5712 9.3736 13.7563 13.245 10.9194 18.8875L16.6559 23.3388C18.0195 19.2636 21.8282 16.2386 26.3109 16.2386V16.2386Z\" fill=\"#EA4335\"/\u003e\n \u003c/svg\u003e\n \u003csvg class=\"logo-dark\" width=\"18\" height=\"18\" viewBox=\"0 0 48 48\" xmlns=\"http://www.w3.org/2000/svg\"\u003e\n \u003ccircle cx=\"24\" cy=\"23\" fill=\"#FFF\" r=\"22\"/\u003e\n \u003cpath d=\"M33.76 34.26c2.75-2.56 4.49-6.37 4.49-11.26 0-.89-.08-1.84-.29-3H24.01v5.99h8.03c-.4 2.02-1.5 3.56-3.07 4.56v.75l3.91 2.97h.88z\" fill=\"#4285F4\"/\u003e\n \u003cpath d=\"M15.58 25.77A8.845 8.845 0 0 0 24 31.86c1.92 0 3.62-.46 4.97-1.31l4.79 3.71C31.14 36.7 27.65 38 24 38c-5.93 0-11.01-3.4-13.45-8.36l.17-1.01 4.06-2.85h.8z\" fill=\"#34A853\"/\u003e\n \u003cpath d=\"M15.59 20.21a8.864 8.864 0 0 0 0 5.58l-5.03 3.86c-.98-2-1.53-4.25-1.53-6.64 0-2.39.55-4.64 1.53-6.64l1-.22 3.81 2.98.22 1.08z\" fill=\"#FBBC05\"/\u003e\n \u003cpath d=\"M24 14.14c2.11 0 4.02.75 5.52 1.98l4.36-4.36C31.22 9.43 27.81 8 24 8c-5.93 0-11.01 3.4-13.45 8.36l5.03 3.85A8.86 8.86 0 0 1 24 14.14z\" fill=\"#EA4335\"/\u003e\n \u003c/svg\u003e\n \u003cdiv class=\"gradient-container\"\u003e\u003cdiv class=\"gradient\"\u003e\u003c/div\u003e\u003c/div\u003e\n \u003c/div\u003e\n \u003cdiv class=\"carousel\"\u003e\n \u003ca class=\"chip\" href=\"https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4x8Epe-gzpwRBvp7o3RZh2m1ygq1EHktn0OWCtvTXjad4bb1zSuqfJd6OEuZZ9_SXZ_P2SvCpJM7NaFfQfiZs6064MeqXego0vSbV9LlAZoxTdbxWK1hFeqTG6kA13YJf7Fbu1SqBYM0cFM4zo0G_sD9NKYWcOCQMvDLDEJFhjrC9DM_QobBIAMq-gWN95G5tvt6_z6EuPN8QY=\"\u003ewho won wimbledon 2024\u003c/a\u003e\n \u003c/div\u003e\n\u003c/div\u003e\n"
},
"groundingChunks": [
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4whET1ta3sDETZvcicd8FeNe4z0VuduVsxrT677KQRp2rYghXI0VpfYbIMVI3THcTuMwggRCbFXS_wVvW0UmGzMe9h2fyrkvsnQPJyikJasNIbjJLPX0StM4Bd694-ZVle56MmRA4YiUvwSqad1w6O2opmWnw==",
"title": "wikipedia.org"
}
},
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4wR1M-9-yMPUr_KdHlnoAmQ8ZX90DtQ_vDYTjtP2oR5RH4tRP04uqKPLmesvo64BBkPeYLC2EpVDxv9ngO3S1fs2xh-e78fY4m0GAtgNlahUkm_tBm_sih5kFPc7ill9u2uwesNGUkwrQlmP2mfWNU5lMMr23HGktr6t0sV0QYlzQq7odVoBxYWlQ_sqWFH",
"title": "wikipedia.org"
}
},
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4wsDmROzbP-tmt8GdwCW_pqISTZ4IRbBuoaMyaHfcQg8WW-yKRQQvMDTPAuLxJh-8_U8_iw_6JKFbQ8M9oVYtaFdWFK4gOtL4RrC9Jyqc5BNpuxp6uLEKgL5-9TggtNvO97PyCfziDFXPsxylwI1HcfQdrz3Jy7ZdOL4XM-S5rC0lF2S3VWW0IEAEtS7WX861meBYVjIuuF_mIr3spYPqWLhbAY2Spj-4_ba8DjRvmevIFUhRuESTKvBfmpxNSM",
"title": "cbssports.com"
}
},
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4yzjLkorHiUKjhOPkWaZ9b4cO-cLG-02vlEl6xTBjMUjyhK04qSIclAa7heR41JQ6AAVXmNdS3WDrLOV4Wli-iezyzW8QPQ4vgnmO_egdsuxhcGk3-Fp8-yfqNLvgXFwY5mPo6QRhvplOFv0_x9mAcka18QuAXtj0SPvJfZhUEgYLCtCrucDS5XFc5HmRBcG1tqFdKSE1ihnp8KLdaWMhrUQI21hHS9",
"title": "jagranjosh.com"
}
},
{
"web": {
"uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/AWhgh4y9L4oeNGWCatFz63b9PpP3ys-Wi_zwnkUT5ji9lY7gPUJQcsmmE87q88GSdZqzcx5nZG9usot5FYk2yK-FAGvCRE6JsUQJB_W11_kJU2HVV1BTPiZ4SAgm8XDFIxpCZXnXmEx5HUfRqQm_zav7CvS2qjA2x3__qLME6Jy7R5oza1C5_aqjQu422le9CaigThS5bvJoMo-ZGcXdBUCj2CqoXNVjMA==",
"title": "apnews.com"
}
}
],
"groundingSupports": [
{
"segment": {
"endIndex": 85,
"text": "Carlos Alcaraz won the Gentlemen's Singles title at the 2024 Wimbledon Championships."
},
"groundingChunkIndices": [
0,
1,
2,
3
],
"confidenceScores": [
0.97380733,
0.97380733,
0.97380733,
0.97380733
]
},
{
"segment": {
"startIndex": 86,
"endIndex": 210,
"text": "He defeated Novak Djokovic in the final, winning his second consecutive Wimbledon title and fourth Grand Slam title overall."
},
"groundingChunkIndices": [
1,
0,
4
],
"confidenceScores": [
0.96145374,
0.96145374,
0.96145374
]
}
],
"webSearchQueries": [
"who won wimbledon 2024"
]
}
}
],
...
}
Jika respons tidak menyertakan groundingMetadata, artinya respons
tidak berhasil didasarkan. Ada beberapa alasan hal ini dapat terjadi,
termasuk relevansi sumber yang rendah atau informasi yang tidak lengkap dalam
respons model.
Saat hasil yang di-grounding dihasilkan, metadata akan berisi URI yang mengalihkan
ke penayang konten yang digunakan untuk menghasilkan hasil yang di-grounding.
URI ini berisi subdomain vertexaisearch, seperti dalam contoh yang terpotong ini:
https://vertexaisearch.cloud.google.com/grounding-api-redirect/.... Metadata
juga berisi domain penayang. URI yang diberikan tetap dapat diakses selama 30 hari setelah hasil yang di-grounding dihasilkan.
Kolom renderedContent dalam searchEntryPoint adalah kode yang disediakan untuk
menerapkan Saran Penelusuran Google. Lihat
Menggunakan Saran Google Penelusuran
untuk mempelajari lebih lanjut.