Google Arama temeli

Google Arama ile bağlama uydurma özelliği, Gemini modelini anlık web içeriğine bağlar ve tüm kullanılabilir dillerde çalışır. Bu sayede Gemini, daha doğru yanıtlar verebilir ve bilgi sınırının ötesinde doğrulanabilir kaynaklardan alıntı yapabilir.

Temellendirme, aşağıdakileri yapabilen uygulamalar oluşturmanıza yardımcı olur:

  • Doğruluk oranını artırın: Yanıtları gerçek dünyadaki bilgilere dayandırarak model halüsinasyonlarını azaltın.
  • Anlık bilgilere erişme: Güncel olaylar ve konularla ilgili soruları yanıtlayın.
  • Alıntılar sağlayın: Modelin iddialarının kaynaklarını göstererek kullanıcıların güvenini kazanın.

Python

from google import genai
from google.genai import types

# Configure the client
client = genai.Client()

# Define the grounding tool
grounding_tool = types.Tool(
    google_search=types.GoogleSearch()
)

# Configure generation settings
config = types.GenerateContentConfig(
    tools=[grounding_tool]
)

# Make the request
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Who won the euro 2024?",
    config=config,
)

# Print the grounded response
print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

// Configure the client
const ai = new GoogleGenAI();

// Define the grounding tool
const groundingTool = {
  googleSearch: {},
};

// Configure generation settings
const config = {
  tools: [groundingTool],
};

// Make the request
const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: "Who won the euro 2024?",
  config,
});

// Print the grounded response
console.log(response.text);

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {"text": "Who won the euro 2024?"}
        ]
      }
    ],
    "tools": [
      {
        "google_search": {}
      }
    ]
  }'

Arama aracı not defterini deneyerek daha fazla bilgi edinebilirsiniz.

Google Arama ile temellendirmenin işleyiş şekli

google_search aracını etkinleştirdiğinizde model, bilgi arama, işleme ve alıntılama iş akışının tamamını otomatik olarak yönetir.

grounding-overview

  1. Kullanıcı İstemi: Uygulamanız, google_search aracı etkinken Gemini API'ye bir kullanıcı isteği gönderir.
  2. İstem analizi: Model, istemi analiz eder ve Google Arama'nın cevabı iyileştirip iyileştiremeyeceğini belirler.
  3. Google Arama: Gerekirse model otomatik olarak bir veya daha fazla arama sorgusu oluşturur ve bunları yürütür.
  4. Arama Sonuçlarını İşleme: Model, arama sonuçlarını işler, bilgileri sentezleyerek bir yanıt oluşturur.
  5. Temellendirilmiş Yanıt: API, arama sonuçlarına dayalı nihai ve kullanıcı dostu bir yanıt döndürür. Bu yanıt, modelin metin yanıtını ve arama sorguları, web sonuçları ve alıntıları içeren groundingMetadata öğesini içerir.

Topraklama yanıtını anlama

Bir yanıt başarıyla temellendirildiğinde yanıtta bir groundingMetadata alanı bulunur. Bu yapılandırılmış veriler, iddiaları doğrulamak ve uygulamanızda zengin bir alıntı deneyimi oluşturmak için gereklidir.

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title."
          }
        ],
        "role": "model"
      },
      "groundingMetadata": {
        "webSearchQueries": [
          "UEFA Euro 2024 winner",
          "who won euro 2024"
        ],
        "searchEntryPoint": {
          "renderedContent": "<!-- HTML and CSS for the search widget -->"
        },
        "groundingChunks": [
          {"web": {"uri": "https://vertexaisearch.cloud.google.com.....", "title": "aljazeera.com"}},
          {"web": {"uri": "https://vertexaisearch.cloud.google.com.....", "title": "uefa.com"}}
        ],
        "groundingSupports": [
          {
            "segment": {"startIndex": 0, "endIndex": 85, "text": "Spain won Euro 2024, defeatin..."},
            "groundingChunkIndices": [0]
          },
          {
            "segment": {"startIndex": 86, "endIndex": 210, "text": "This victory marks Spain's..."},
            "groundingChunkIndices": [0, 1]
          }
        ]
      }
    }
  ]
}

Gemini API, groundingMetadata ile aşağıdaki bilgileri döndürür:

  • webSearchQueries : Kullanılan arama sorgularının dizisi. Bu, hata ayıklama ve modelin akıl yürütme sürecini anlama için yararlıdır.
  • searchEntryPoint : Gerekli arama önerilerini oluşturmak için HTML ve CSS'yi içerir. Kullanımla ilgili tüm şartlar Hizmet Şartları'nda açıklanmıştır.
  • groundingChunks : Web kaynaklarını (uri ve title) içeren nesne dizisi.
  • groundingSupports : text model yanıtını groundingChunks'deki kaynaklara bağlayan parça dizisi. Her bir parça, bir metin segment'ü (startIndex ve endIndex tarafından tanımlanır) bir veya daha fazla groundingChunkIndices'a bağlar. Bu, satır içi alıntı oluşturmanın anahtarıdır.

Google Arama ile temellendirme, yanıtları hem herkese açık web verilerine hem de sağladığınız belirli URL'lere dayandırmak için URL bağlam aracı ile birlikte de kullanılabilir.

Satır içi alıntılarla kaynaklara atıf yapma

API, kaynaklara kullanıcı arayüzünüzde nasıl yer vereceğiniz konusunda tam kontrol sahibi olmanızı sağlayan yapılandırılmış alıntı verileri döndürür. Modelin beyanlarını doğrudan kaynaklarına bağlamak için groundingSupports ve groundingChunks alanlarını kullanabilirsiniz. Satır içi, tıklanabilir alıntılar içeren bir yanıt oluşturmak için meta verileri işlemeyle ilgili yaygın bir kalıp aşağıda verilmiştir.

Python

def add_citations(response):
    text = response.text
    supports = response.candidates[0].grounding_metadata.grounding_supports
    chunks = response.candidates[0].grounding_metadata.grounding_chunks

    # Sort supports by end_index in descending order to avoid shifting issues when inserting.
    sorted_supports = sorted(supports, key=lambda s: s.segment.end_index, reverse=True)

    for support in sorted_supports:
        end_index = support.segment.end_index
        if support.grounding_chunk_indices:
            # Create citation string like [1](link1)[2](link2)
            citation_links = []
            for i in support.grounding_chunk_indices:
                if i < len(chunks):
                    uri = chunks[i].web.uri
                    citation_links.append(f"[{i + 1}]({uri})")

            citation_string = ", ".join(citation_links)
            text = text[:end_index] + citation_string + text[end_index:]

    return text

# Assuming response with grounding metadata
text_with_citations = add_citations(response)
print(text_with_citations)

JavaScript

function addCitations(response) {
    let text = response.text;
    const supports = response.candidates[0]?.groundingMetadata?.groundingSupports;
    const chunks = response.candidates[0]?.groundingMetadata?.groundingChunks;

    // Sort supports by end_index in descending order to avoid shifting issues when inserting.
    const sortedSupports = [...supports].sort(
        (a, b) => (b.segment?.endIndex ?? 0) - (a.segment?.endIndex ?? 0),
    );

    for (const support of sortedSupports) {
        const endIndex = support.segment?.endIndex;
        if (endIndex === undefined || !support.groundingChunkIndices?.length) {
        continue;
        }

        const citationLinks = support.groundingChunkIndices
        .map(i => {
            const uri = chunks[i]?.web?.uri;
            if (uri) {
            return `[${i + 1}](${uri})`;
            }
            return null;
        })
        .filter(Boolean);

        if (citationLinks.length > 0) {
        const citationString = citationLinks.join(", ");
        text = text.slice(0, endIndex) + citationString + text.slice(endIndex);
        }
    }

    return text;
}

const textWithCitations = addCitations(response);
console.log(textWithCitations);

Satır içi alıntıların yer aldığı yeni yanıt şöyle görünür:

Spain won Euro 2024, defeating England 2-1 in the final.[1](https:/...), [2](https:/...), [4](https:/...), [5](https:/...) This victory marks Spain's record-breaking fourth European Championship title.[5]((https:/...), [2](https:/...), [3](https:/...), [4](https:/...)

Fiyatlandırma

Google Arama ile Temel Bilgiler'i kullandığınızda projeniz, google_search aracını içeren API isteği başına faturalandırılır. Model, tek bir istemi yanıtlamak için birden fazla arama sorgusu yürütmeye karar verirse (örneğin, aynı API çağrısında "UEFA Euro 2024 winner" ve "Spain vs England Euro 2024 final score" için arama yaparsa) bu, söz konusu istek için aracın tek bir faturalandırılabilir kullanımı olarak sayılır.

Ayrıntılı fiyatlandırma bilgileri için Gemini API fiyatlandırma sayfasını inceleyin.

Desteklenen Modeller

Deneme ve önizleme modelleri dahil değildir. Bu modellerin özelliklerini modele genel bakış sayfasında bulabilirsiniz.

Model Google Arama ile temellendirme
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.0 Flash ✔️
Gemini 1.5 Pro ✔️
Gemini 1.5 Flash ✔️

Gemini 1.5 modelleriyle topraklama (eski)

Gemini 2.0 ve sonraki sürümler için google_search aracı önerilir. Gemini 1.5 ise google_search_retrieval adlı eski bir aracı destekler. Bu araç, modelin istem için yeni bilgilere ihtiyaç duyduğuna dair güven derecesine göre arama yapıp yapmayacağına karar vermesine olanak tanıyan bir dynamic modu sağlar. Modelin güven düzeyi, belirlediğiniz dynamic_threshold değerinin (0,0 ile 1,0 arasında bir değer) üzerindeyse arama yapar.

Python

# Note: This is a legacy approach for Gemini 1.5 models.
# The 'google_search' tool is recommended for all new development.
import os
from google import genai
from google.genai import types

client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))

retrieval_tool = types.Tool(
    google_search_retrieval=types.GoogleSearchRetrieval(
        dynamic_retrieval_config=types.DynamicRetrievalConfig(
            mode=types.DynamicRetrievalConfigMode.MODE_DYNAMIC,
            dynamic_threshold=0.7 # Only search if confidence > 70%
        )
    )
)

config = types.GenerateContentConfig(
    tools=[retrieval_tool]
)

response = client.models.generate_content(
    model='gemini-1.5-flash',
    contents="Who won the euro 2024?",
    config=config,
)
print(response.text)
if not response.candidates[0].grounding_metadata:
  print("\nModel answered from its own knowledge.")

JavaScript

// Note: This is a legacy approach for Gemini 1.5 models.
// The 'googleSearch' tool is recommended for all new development.
import { GoogleGenAI, DynamicRetrievalConfigMode } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const retrievalTool = {
  googleSearchRetrieval: {
    dynamicRetrievalConfig: {
      mode: DynamicRetrievalConfigMode.MODE_DYNAMIC,
      dynamicThreshold: 0.7, // Only search if confidence > 70%
    },
  },
};

const config = {
  tools: [retrievalTool],
};

const response = await ai.models.generateContent({
  model: "gemini-1.5-flash",
  contents: "Who won the euro 2024?",
  config,
});

console.log(response.text);
if (!response.candidates?.[0]?.groundingMetadata) {
  console.log("\nModel answered from its own knowledge.");
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {"parts": [{"text": "Who won the euro 2024?"}]}
    ],
    "tools": [{
      "google_search_retrieval": {
        "dynamic_retrieval_config": {
          "mode": "MODE_DYNAMIC",
          "dynamic_threshold": 0.7
        }
      }
    }]
  }'

Sırada ne var?