Gemini API ve AI Studio'daki Google Arama ile Temel Bilgilendirme özelliği, modelden gelen yanıtların doğruluğunu ve güncelliğini iyileştirmek için kullanılabilir. Google Arama ile temellendirme özelliği etkinleştirildiğinde Gemini API, daha gerçekçi yanıtların yanı sıra yanıt içeriğiyle birlikte temellendirme kaynaklarını (satır içi destekleyici bağlantılar) ve Google Arama Önerileri'ni döndürür. Arama Önerileri, kullanıcıları gerekçeli yanıta karşılık gelen arama sonuçlarına yönlendirir.
Bu kılavuz, Gemini API SDK'larından birini veya REST API'yi kullanarak Google Arama ile temellendirme özelliğini kullanmaya başlamanıza yardımcı olacaktır.
Arama temellendirmesini yapılandırma
Google Arama, Gemini 2.0'dan itibaren bir araç olarak kullanılabilir. Bu, modelin Google Arama'yı ne zaman kullanacağına karar verebileceği anlamına gelir. Aşağıdaki örnekte, Arama'nın araç olarak nasıl yapılandırılacağı gösterilmektedir.
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)
Araç olarak arama işlevi, çok turlu aramaları ve çok araçlı sorguları (ör. temellendirmeyi Google Arama ve kod yürütme ile birleştirme) da etkinleştirir.
Arama aracı olarak planlama, akıl yürütme ve düşünme gerektiren karmaşık istemler ve iş akışları sağlar:
- Gerçeklik ve güncelliği artırmak ve daha doğru yanıtlar sunmak için temellendirme
- Daha ayrıntılı analiz yapmak için web'den yapıları alma
- Çoklu duyusal akıl yürütme veya üretme görevlerine yardımcı olacak alakalı resimler, videolar veya başka medyalar bulma
- Kodlama, teknik sorun giderme ve diğer özel görevler
- Bölgeye özgü bilgileri bulma veya içeriğin doğru şekilde çevrilmesine yardımcı olma
- Daha fazla göz atabileceğiniz alakalı web sitelerini bulma
Google Arama ile temellendirme özelliği, metin istemleri yaparken tüm mevcut dillerde çalışır. Gemini Developer API'nin ücretli katmanında, Google Arama ile Temel Bilgiler sorgusunu günde 1.500 kez ücretsiz olarak alabilirsiniz. Ek sorgular ise 1.000 sorgu başına standart 35 ABD doları ücret karşılığında faturalandırılır.
Arama aracı not defterini deneyerek daha fazla bilgi edinebilirsiniz.
Google Arama Önerileri
Google Arama ile temellendirmeyi kullanmak için, temellendirilmiş yanıtın meta verilerine eklenen önerilen sorgular olan Google Arama Önerileri'ni görüntülemeniz gerekir. Görüntüleme koşulları hakkında daha fazla bilgi edinmek için Google Arama Önerileri'ni kullanma başlıklı makaleyi inceleyin.
Google Arama'dan veri alma
Dinamik getirme
Bazı sorguların Google Arama ile Temel Bilgiler özelliğinden diğerlerinden daha fazla yararlanması muhtemeldir. Dinamik getirme özelliği, Google Arama ile Temel Bilgiler'i ne zaman kullanacağınız konusunda size ek kontrol sağlar.
Dinamik alma modu belirtilmezse Google Arama ile Temel Bilgiler her zaman tetiklenir. Mod dinamik olarak ayarlanmışsa model, yapılandırabileceğiniz bir eşiğe göre topraklamayı ne zaman kullanacağına karar verir. Eşik, [0,1] aralığındaki bir kayan nokta değeridir ve varsayılan olarak 0,3'tür. Eşik değeri 0 ise yanıt her zaman Google Arama'ya dayanır; 1 ise hiçbir zaman dayanmamaktadır.
Dinamik getirmenin işleyiş şekli
Google Arama ile temellendirmeyi ne zaman etkinleştireceğinizi seçmek için isteğinizde dinamik getirmeyi kullanabilirsiniz. Bu, istem Google Arama'ya dayalı bir yanıt gerektirmediğinde ve model, temellendirme olmadan kendi bilgisine dayalı bir yanıt sağlayabildiğinde kullanışlıdır. Bu sayede gecikmeyi, kaliteyi ve maliyeti daha etkili bir şekilde yönetebilirsiniz.
İsteğinizde dinamik getirme yapılandırmasını çağırmadan önce aşağıdaki terminolojiyi anlayın:
Tahmin puanı: Gemini, gerekçeli bir yanıt istediğinizde istem için bir tahmin puanı atar. Tahmin puanı, [0,1] aralığındaki bir kayan nokta değeridir. Değeri, istemin yanıtı Google Arama'daki en güncel bilgilerle temellendirmekten yararlanıp yararlanamayacağına bağlıdır. Bu nedenle, bir istem web'deki en güncel bilgilere dayalı bir yanıt gerektiriyorsa tahmin puanı daha yüksek olur. Model tarafından oluşturulan bir yanıtın yeterli olduğu istemlerin tahmin puanı daha düşüktür.
Aşağıda bazı istemler ve bunların tahmin puanları verilmiştir.
İstem Tahmin puanı Yorum "Şakayık hakkında şiir yaz" 0,13 Model, bilgisine güvenebilir ve yanıtın gerekçelendirilmesi gerekmez. "2 yaşındaki bir çocuk için oyuncak önerin" 0,36 Model, bilgisine güvenebilir ve yanıtın gerekçelendirilmesi gerekmez. "Asya esintili bir guakamole tarifi verebilir misiniz?" 0,55 Google Arama, temellendirilmiş bir yanıt verebilir ancak temellendirme kesinlikle gerekli değildir. Model bilgisi yeterli olabilir. "Agent Builder nedir? Temellendirme, Agent Builder'da nasıl faturalandırılır?" 0,72 Google Arama'nın sağlam temelli bir yanıt oluşturmasını gerektirir. "Son F1 Grand Prix'ini kim kazandı?" 0,97 Google Arama'nın sağlam temelli bir yanıt oluşturmasını gerektirir. Eşik: API isteğinizde, eşik içeren dinamik bir alma yapılandırması belirtebilirsiniz. Eşik, [0,1] aralığındaki bir kayan nokta değeridir ve varsayılan olarak 0,3'tür. Eşik değeri sıfır ise yanıt her zaman Google Arama'ya dayanır. Diğer tüm eşik değerleri için aşağıdakiler geçerlidir:
- Tahmin puanı eşiğin üzerindeyse veya eşiğe eşitse yanıt, Google Arama'ya dayanır. Daha düşük bir eşik, daha fazla istemde Google Arama ile Temel Bilgilendirme özelliği kullanılarak oluşturulan yanıtlar olduğu anlamına gelir.
- Tahmin puanı eşiğin altındaysa model yine de yanıt oluşturabilir ancak bu yanıt Google Arama'ya dayalı değildir.
Dinamik getirme eşiğini SDK veya REST API kullanarak nasıl ayarlayacağınızı öğrenmek için ilgili kod örneğine bakın.
İşletmenizin ihtiyaçlarına uygun iyi bir eşik bulmak için karşılaşmayı beklediğiniz temsili bir sorgu grubu oluşturabilirsiniz. Ardından sorguları yanıttaki tahmin puanına göre sıralayabilir ve kullanım alanınız için uygun bir eşik seçebilirsiniz.
Gerçekçi bir yanıt
İsteminiz Google Arama'da başarıyla temellendirilirse yanıtta groundingMetadata yer alır. Gerçeklere dayalı bir yanıt şu şekilde görünebilir (kısaltmak amacıyla yanıtın bazı bölümleri çıkarılmıştır):
{
"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"
]
}
}
],
...
}
Yanıtta groundingMetadata yoksa yanıtın dayanak olarak başarılı bir şekilde sunulmadığı anlamına gelir. Bu durumun yaşanmasının, kaynakla alakanın düşük olması veya model yanıtındaki bilgilerin eksik olması gibi çeşitli nedenleri vardır.
Yerleşik bir sonuç oluşturulduğunda meta veriler, yerleşik sonucu oluşturmak için kullanılan içeriğin yayıncılarına yönlendiren URI'ler içerir.
Bu URI'ler, kısaltılmış örnekte gösterildiği gibi vertexaisearch alt alanını içerir:
https://vertexaisearch.cloud.google.com/grounding-api-redirect/.... Meta veriler, yayıncıların alanlarını da içerir. Sağlanan URI'lere, temellendirilmiş sonuç oluşturulduktan sonraki 30 gün boyunca erişilebilir.
searchEntryPoint içindeki renderedContent alanı, Google Arama Önerileri'ni uygulamak için sağlanan koddur. Daha fazla bilgi edinmek için Google Arama Önerileri'ni kullanma başlıklı makaleyi inceleyin.