تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

تقدّم ميزة "الاستناد إلى بحث Google" المزايا التالية:

زيادة الدقة الوقائعية: الحدّ من الهلوسات التي تصدر عن النموذج من خلال استناد الردود إلى معلومات من العالم الحقيقي
الوصول إلى معلومات في الوقت الفعلي: الإجابة عن أسئلة حول الأحداث والمواضيع الحديثة
توفير اقتباسات: يمكنك تعزيز ثقة المستخدمين أو السماح لهم بتصفّح المواقع الإلكترونية ذات الصلة من خلال عرض مصادر ادعاءات النموذج.
إكمال مهام أكثر تعقيدًا: استرداد العناصر والصور أو الفيديوهات أو الوسائط الأخرى ذات الصلة للمساعدة في مهام الاستدلال
تحسين الردود الخاصة بمنطقة أو لغة معيّنة: يمكنك العثور على معلومات خاصة بمنطقة معيّنة أو المساعدة في ترجمة المحتوى بدقة.

يُرجى العِلم أنّ ميزة "الاستناد إلى مصادر" في "بحث Google" متاحة على أجهزة iOS والإصدارات الأحدث وAndroid والويب. ستتوفّر هذه الميزة في إصدارات Flutter وUnity القادمة.

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

gemini-2.5-pro
gemini-2.5-flash
gemini-2.5-flash-lite-preview-06-17
‫gemini-2.0-flash-001 (والاسم المستعار gemini-2.0-flash الذي يتم تعديله تلقائيًا)
gemini-2.0-flash-live-preview-04-09

اللغات المتاحة

اطّلِع على اللغات المتاحة لنماذج Gemini.

تأسيس النموذج على "بحث Google"

انقر على مزوّد Gemini API لعرض المحتوى والرمز الخاصين بالمزوّد على هذه الصفحة.

عند إنشاء مثيل GenerativeModel، قدِّم GoogleSearch كـ tool يمكن للنموذج استخدامه لإنشاء الردّ.

Swift


import FirebaseAI

// Initialize the Gemini Developer API backend service
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Create a `GenerativeModel` instance with a model that supports your use case
let model = ai.generativeModel(
    modelName: "GEMINI_MODEL_NAME",
    // Provide Google Search as a tool that the model can use to generate its response
    tools: [Tool.googleSearch()]
)

let response = try await model.generateContent("Who won the euro 2024?")
print(response.text ?? "No text in response.")

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result

Kotlin


// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
val model = Firebase.ai(backend = GenerativeBackend.googleAI()).generativeModel(
    modelName = "GEMINI_MODEL_NAME",
    // Provide Google Search as a tool that the model can use to generate its response
    tools = listOf(Tool.GoogleSearch())
)

val response = model.generateContent("Who won the euro 2024?")
print(response.text)

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result

Java


// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
                .generativeModel("GEMINI_MODEL_NAME",
                        null,
                        null,
                        // Provide Google Search as a tool that the model can use to generate its response
                        List.of(Tool.GoogleSearch()));

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

ListenableFuture response = model.generateContent("Who won the euro 2024?");
  Futures.addCallback(response, new FutureCallback() {
      @Override
      public void onSuccess(GenerateContentResponse result) {
          String resultText = result.getText();
          System.out.println(resultText);
      }

      @Override
      public void onFailure(Throwable t) {
          t.printStackTrace();
      }
  }, executor);

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result

Web


import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance with a model that supports your use case
const model = getGenerativeModel(
  ai,
  {
    model: "GEMINI_MODEL_NAME",
    // Provide Google Search as a tool that the model can use to generate its response
    tools: [{ googleSearch: {} }]
  }
);

const result = await model.generateContent("Who won the euro 2024?");

console.log(result.response.text());

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result

Dart

سيتوفّر الدعم لـ Flutter في الإصدار التالي.

Unity

سيتوفّر الدعم في الإصدار التالي من Unity.

تعرَّف على كيفية اختيار نموذج اختياري مناسبَين لحالة الاستخدام والتطبيق.

للحصول على أفضل النتائج، استخدِم درجة حرارة 1.0 (وهي القيمة التلقائية لجميع الطُرز 2.5). تعرَّف على كيفية ضبط درجة الحرارة في إعدادات النموذج.

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

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

في ما يلي سير عمل النموذج:

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

يُرجى العِلم أنّ توفير "بحث Google" كأداة للنموذج لا يتطلّب أن يستخدم النموذج أداة "بحث Google" دائمًا لإنشاء الردّ. في هذه الحالات، لن تتضمّن الاستجابة عنصر groundingMetadata، وبالتالي لن تكون "نتيجة مستندة إلى مصادر".

فهم النتيجة المستندة إلى معلومات

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

يتضمّن الكائن groundingMetadata في "نتيجة مستندة إلى معلومات موثوقة" المعلومات التالية:

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

في ما يلي مثال على استجابة تتضمّن عنصر 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]
          }
        ]
      }
    }
  ]
}

استخدام وعرض نتيجة مستندة إلى مصادر

إذا كان النموذج يستخدم أداة "بحث Google" لإنشاء ردّ، سيقدّم groundingMetadata كائنًا في الردّ.

يجب تفعيلها من أجل عرض اقتراحات "بحث Google"، ويُفضّل تفعيلها من أجل عرض الاقتباسات.

بالإضافة إلى الامتثال لمتطلبات استخدام أداة "بحث Google"، يساعد عرض هذه المعلومات أنت والمستخدمين النهائيين في التحقّق من صحة الردود، كما يوفّر طرقًا إضافية للتعلّم.

(مطلوبة) عرض اقتراحات "بحث Google"

إذا كانت الاستجابة تتضمّن "اقتراحات بحث Google"، عليك الالتزام بمتطلبات الاستخدام الخاصة بـ "الاستناد إلى بحث Google"، والتي تشمل طريقة عرض اقتراحات بحث Google.

يحتوي العنصر groundingMetadata على "اقتراحات بحث Google"، وتحديدًا الحقل searchEntryPoint الذي يتضمّن الحقل renderedContent الذي يوفّر تنسيق HTML وCSS متوافقًا، وعليك تنفيذه لعرض اقتراحات البحث في تطبيقك.

راجِع المعلومات التفصيلية حول متطلبات العرض والسلوك لاقتراحات "بحث Google" في مستندات Google Cloud. يُرجى العِلم أنّه على الرغم من أنّ هذه الإرشادات المفصّلة واردة في مستندات Vertex AI Gemini API، إلا أنّها تنطبق أيضًا على مزوّد خدمة Gemini Developer API.

يمكنك الاطّلاع على أمثلة على عيّنات التعليمات البرمجية في وقت لاحق من هذا القسم.

(مُقترَح) عرض الاقتباسات

يحتوي عنصر groundingMetadata على بيانات الاقتباس المنظَّمة، وتحديدًا الحقلَين groundingSupports وgroundingChunks. استخدِم هذه المعلومات لربط عبارات النموذج مباشرةً بمصادرها ضمن واجهة المستخدم (بشكل مضمّن ومجمّع).

يمكنك الاطّلاع على أمثلة على عيّنات التعليمات البرمجية في وقت لاحق من هذا القسم.

أمثلة على عيّنات التعليمات البرمجية

تقدّم عيّنات التعليمات البرمجية هذه أنماطًا عامة لاستخدام النتيجة المستندة إلى معلومات موثوقة وعرضها. ومع ذلك، تقع على عاتقك مسؤولية التأكّد من أنّ طريقة التنفيذ المحدّدة تتوافق مع متطلبات الامتثال.

Swift

// ...

// Get the model's response
let text = response.text

// Get the grounding metadata
if let candidate = response.candidates.first,
   let groundingMetadata = candidate.groundingMetadata {
  // REQUIRED - display Google Search suggestions
  // (renderedContent contains HTML and CSS for the search widget)
  if let renderedContent = groundingMetadata.searchEntryPoint?.renderedContent {
    // TODO(developer): Display Google Search suggestions using a WebView
  }

  // RECOMMENDED - display citations
  let groundingChunks = groundingMetadata.groundingChunks
  for chunk in groundingMetadata.groundingChunks {
    if let web = chunk.web {
      let title = web.title  // for example, "uefa.com"
      let uri = web.uri  // for example, "https://vertexaisearch.cloud.google.com..."
      // TODO(developer): show citation in the UI
    }
  }
}

Kotlin

// ...

// Get the model's response
val text = response.text

// Get the grounding metadata
val groundingMetadata = response.candidates.firstOrNull()?.groundingMetadata

// REQUIRED - display Google Search suggestions
// (renderedContent contains HTML and CSS for the search widget)
val renderedContent = groundingMetadata?.searchEntryPoint?.renderedContent
if (renderedContent != null) {
    // TODO(developer): Display Google Search suggestions using a WebView
}

// RECOMMENDED - display citations
val groundingChunks = groundingMetadata?.groundingChunks
groundingChunks?.let { chunks ->
  for (chunk in chunks) {
  	val title = chunk.web?.title  // for example, "uefa.com"
	val uri = chunk.web?.uri  // for example, "https://vertexaisearch.cloud.google.com..."
// TODO(developer): show citation in the UI
  }
}

Java

// ...

Futures.addCallback(response, new FutureCallback() {
  @Override
  public void onSuccess(GenerateContentResponse result) {
  // Get the model's response
  String text = result.getText();

  // Get the grounding metadata
  GroundingMetadata groundingMetadata =
  result.getCandidates()[0].getGroundingMetadata();

  if (groundingMetadata != null) {
    // REQUIRED - display Google Search suggestions
  // (renderedContent contains HTML and CSS for the search widget)
    String renderedContent =
  groundingMetadata.getSearchEntryPoint().getRenderedContent();
    if (renderedContent != null) {
      // TODO(developer): Display Google Search suggestions using a WebView
    }

    // RECOMMENDED - display citations
    List chunks = groundingMetadata.getGroundingChunks();
    if (chunks != null) {
      for(GroundingChunk chunk : chunks) {
        WebGroundingChunk web = chunk.getWeb();
        if (web != null) {
          String title = web.getTitle();  // for example, "uefa.com"
          String uri = web.getUri();  // for example, "https://vertexaisearch.cloud.google.com..."
          // TODO(developer): show citation in the UI
        }
      }
    }
  }
  }

  @Override
  public void onFailure(Throwable t) {
  t.printStackTrace();
  }
  }, executor);

Web

// ...

// Get the model's text response
const text = result.response.text();

// Get the grounding metadata
const groundingMetadata = result.response.candidates?.[0]?.groundingMetadata;

// REQUIRED - display Google Search suggestions
// (renderedContent contains HTML and CSS for the search widget)
const renderedContent = groundingMetadata?.searchEntryPoint?.renderedContent;
if (renderedContent) {
  // TODO(developer): render this HTML and CSS in the UI
}

// RECOMMENDED - display citations
const groundingChunks = groundingMetadata?.groundingChunks;
if (groundingChunks) {
  for (const chunk of groundingChunks) {
    const title = chunk.web?.title;  // for example, "uefa.com"
    const uri = chunk.web?.uri;  // for example, "https://vertexaisearch.cloud.google.com..."
    // TODO(developer): show citation in the UI
  }
}

Dart

سيتوفّر الدعم لـ Flutter في الإصدار التالي.

Unity

سيتوفّر الدعم في الإصدار التالي من Unity.

النتائج المستندة إلى مصادر موثوقة ومراقبة الذكاء الاصطناعي في وحدة تحكّم Firebase

إذا فعّلت ميزة مراقبة الذكاء الاصطناعي في Firebase، سيتم تخزين الردود في Cloud Logging. بشكلٍ تلقائي، تبلغ مدة الاحتفاظ بهذه البيانات 30 يومًا.

تتحمّل أنت مسؤولية التأكّد من أنّ فترة الاحتفاظ هذه أو أي فترة مخصّصة تحدّدها تتوافق تمامًا مع حالة الاستخدام المحدّدة وأي متطلبات امتثال إضافية لمزوّد خدمة Gemini API الذي اخترته: Gemini Developer API أو Vertex AI Gemini API (راجِع قسم بنود الخدمة ضمن البنود الخاصة بالخدمة). قد تحتاج إلى تعديل فترة الاحتفاظ بالبيانات في Cloud Logging لتلبية هذه المتطلبات.

الأسعار والحدود

احرص على مراجعة الأسعار ومدى توفّر النماذج والقيود المفروضة على التأسيس باستخدام "بحث Google" في مستندات موفّر Gemini API الذي اخترته: Gemini Developer API | Vertex AI Gemini API.