الأساسيات باستخدام "بحث Google"

تتيح ميزة "تحديد المصدر من خلال بحث Search" ربط نموذج Gemini بمحتوى الويب في الوقت الفعلي، وهي تعمل بجميع اللغات المتاحة. يتيح ذلك لـ Gemini تقديم إجابات أكثر دقة والإشارة إلى مصادر يمكن التحقّق منها بعد تاريخ آخر تحديث للبيانات.

تساعدك ميزة "تحديد المصدر" في إنشاء تطبيقات يمكنها تنفيذ ما يلي:

• زيادة الدقة الوقائعية: تقليل حالات الهلوسة في النموذج من خلال استناد الردود إلى معلومات واقعية
• الوصول إلى المعلومات في الوقت الفعلي: الإجابة عن الأسئلة حول الأحداث والمواضيع الحديثة

• تقديم الاقتباسات: تعزيز ثقة المستخدمين من خلال عرض مصادر ادعاءات النموذج

from google import genai
from google.genai import types

client = genai.Client()

grounding_tool = types.Tool(
    google_search=types.GoogleSearch()
)

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

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

print(response.text)

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

const ai = new GoogleGenAI({});

const groundingTool = {
  googleSearch: {},
};

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

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

console.log(response.text);

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

يمكنك الاطّلاع على مزيد من المعلومات من خلال تجربة دفتر ملاحظات أداة "بحث Google".

طريقة عمل ميزة "تحديد المصدر من خلال بحث Google"

عند تفعيل أداة google_search، يتعامل النموذج تلقائيًا مع سير العمل بالكامل، بما في ذلك البحث عن المعلومات ومعالجتها والاقتباس منها.

1. طلب المستخدم: يرسل تطبيقك طلبًا من المستخدم إلى Gemini API مع تفعيل أداة google_search.
2. تحليل الطلب: يحلّل النموذج الطلب ويحدّد ما إذا كان بإمكان "بحث Google" تحسين الإجابة.
3. بحث Google: إذا لزم الأمر، ينشئ النموذج تلقائيًا طلب بحث واحدًا أو أكثر وينفّذها.
4. معالجة نتائج البحث: يعالج النموذج نتائج البحث ويجمع المعلومات ويصوغ ردًا.
5. الردّ المستند إلى مصادر: تعرض واجهة برمجة التطبيقات ردًا نهائيًا سهل الاستخدام يستند إلى نتائج البحث. يتضمّن هذا الردّ الإجابة النصية للنموذج وgroundingMetadata التي تتضمّن طلبات البحث ونتائج الويب والاقتباسات.

فهم الردّ المستند إلى مصادر

عندما يتم تحديد مصدر الردّ بنجاح، يتضمّن الردّ حقل groundingMetadata. هذه البيانات المنظَّمة ضرورية للتحقّق من الادعاءات وإنشاء تجربة اقتباس غنية في تطبيقك.

{
  "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:

• webSearchQueries : مصفوفة طلبات البحث المستخدَمة تفيد هذه الميزة في تحديد الأخطاء وفهم عملية الاستنتاج التي يتّبعها النموذج.
• searchEntryPoint : يحتوي على HTML وCSS لعرض "اقتراحات البحث" المطلوبة. يتم تفصيل متطلبات الاستخدام الكاملة في بنود الخدمة.
• groundingChunks : مصفوفة من الكائنات التي تحتوي على مصادر الويب (uri وtitle)
• groundingSupports : مصفوفة من الأجزاء لربط text الردّ الذي يقدّمه النموذج بالمصادر في groundingChunks يربط كل جزء segment نصيًا (محدّدًا من خلال startIndex وendIndex) بواحد أو أكثر من groundingChunkIndices. هذا هو المفتاح لإنشاء اقتباسات مضمّنة.

يمكن أيضًا استخدام ميزة "تحديد المصدر من خلال بحث Search" مع أداة "سياق عناوين URL" لتحديد مصادر الردود في كلّ من بيانات الويب العلنية وعناوين URL المحدّدة التي تقدّمها.

الإشارة إلى المصادر باستخدام الاقتباسات المضمّنة

تعرض واجهة برمجة التطبيقات بيانات اقتباس منظَّمة، ما يمنحك تحكّمًا كاملاً في طريقة عرض المصادر في واجهة المستخدم. يمكنك استخدام الحقلَين groundingSupports وgroundingChunks لربط عبارات النموذج مباشرةً بمصادرها. في ما يلي نمط شائع لمعالجة البيانات الوصفية لإنشاء ردّ يتضمّن اقتباسات مضمّنة قابلة للنقر:

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)

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

سيظهر الردّ الجديد الذي يتضمّن اقتباسات مضمّنة على النحو التالي:

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:/...)

الأسعار

عند استخدام ميزة "تحديد المصدر من خلال بحث Google" مع Gemini 3، يتم تحصيل رسوم من مشروعك مقابل كل طلب بحث يقرّر النموذج تنفيذه. إذا قرّر النموذج تنفيذ طلبات بحث متعددة للردّ على طلب واحد (على سبيل المثال، البحث عن "UEFA Euro 2024 winner" و"Spain vs England Euro 2024 final score" ضمن طلب بيانات من واجهة برمجة التطبيقات نفسه)، يتم احتساب ذلك كاستخدامَين قابلَين للفوترة للأداة في هذا الطلب. لأغراض الفوترة، نتجاهل طلبات البحث الفارغة على الويب عند احتساب طلبات البحث الفريدة. ينطبق نموذج الفوترة هذا على نماذج Gemini 3 فقط. عند استخدام ميزة "تحديد المصدر من خلال البحث" مع Gemini 2.5 أو النماذج الأقدم، يتم تحصيل رسوم من مشروعك لكل طلب.

للحصول على معلومات مفصّلة عن الأسعار، يُرجى الاطّلاع على صفحة أسعار Gemini API.

النماذج المتوافقة

يمكنك الاطّلاع على الإمكانات الكاملة في صفحة نظرة عامة على النموذج.

مجموعات الأدوات المتوافقة

يمكنك استخدام ميزة "تحديد المصدر من خلال بحث Google" مع أدوات أخرى، مثل تنفيذ الرموز البرمجية، و سياق عنوان URL، و تحديد المصدر من خلال خرائط Google (المتوفرة في Gemini 3.5 Flash والنماذج الأحدث) لتعزيز حالات الاستخدام الأكثر تعقيدًا. تتيح نماذج Gemini 3 أيضًا الجمع بين هذه الأدوات المضمّنة والأدوات المخصّصة (استدعاء الدوال). مزيد من المعلومات في صفحة مجموعات الأدوات

الخطوات التالية

• جرِّب ميزة "تحديد المصدر من خلال بحث Google" في Gemini API Cookbook.
• تعرَّف على الأدوات الأخرى المتاحة، مثل استدعاء الدوال.
• تعرَّف على كيفية زيادة الطلبات باستخدام عناوين URL محدّدة باستخدام أداة سياق عنوان URL.