زمینه سازی با جستجوی گوگل

اتصال به گوگل سرچ، مدل Gemini را به محتوای وبِ بلادرنگ و در دسترس عموم متصل می‌کند. این امر به مدل اجازه می‌دهد تا پاسخ‌های دقیق‌تر و به‌روزتری ارائه دهد و فراتر از محدودیت دانش خود، به منابع قابل تأیید استناد کند.

اتصال به زمین با جستجوی گوگل مزایای زیر را دارد:

  • افزایش دقت واقعی : با مبنا قرار دادن پاسخ‌ها بر اساس اطلاعات دنیای واقعی، توهمات مدل‌سازی را کاهش دهید.
  • دسترسی به اطلاعات در لحظه : به سوالات مربوط به رویدادها و موضوعات اخیر پاسخ دهید.
  • ارائه منابع : با نشان دادن منابع ادعاهای مدل، اعتماد کاربر را جلب کنید یا به کاربران اجازه دهید سایت‌های مرتبط را مرور کنند.
  • انجام وظایف پیچیده‌تر : بازیابی مصنوعات و تصاویر، ویدیوها یا سایر رسانه‌های مرتبط برای کمک به وظایف استدلالی.
  • بهبود پاسخ‌های مختص منطقه یا زبان : یافتن اطلاعات مختص منطقه یا کمک به ترجمه دقیق محتوا.

مدل‌های پشتیبانی‌شده

  • gemini-2.5-pro
  • gemini-2.5-flash
  • gemini-2.5-flash-lite
  • gemini-2.0-flash-001 (و نام مستعار به‌روزرسانی‌شده خودکار آن gemini-2.0-flash )
  • gemini-2.0-flash-live-preview-04-09

زبان‌های پشتیبانی‌شده

زبان‌های پشتیبانی‌شده برای مدل‌های Gemini را ببینید.

مدل را با جستجوی گوگل پایه گذاری کنید

برای مشاهده محتوا و کد مخصوص ارائه‌دهنده در این صفحه، روی ارائه‌دهنده API Gemini خود کلیک کنید.

وقتی نمونه‌ی GenerativeModel را ایجاد می‌کنید، GoogleSearch به عنوان tool ارائه دهید که مدل بتواند از آن برای تولید پاسخ خود استفاده کند.

سویفت


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


import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_ai/firebase_ai.dart';
import 'firebase_options.dart';

// Initialize FirebaseApp
await Firebase.initializeApp(
  options: DefaultFirebaseOptions.currentPlatform,
);

// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
final model = FirebaseAI.googleAI().generativeModel(
  model: 'GEMINI_MODEL_NAME',
  // Provide Google Search as a tool that the model can use to generate its response
  tools: [
    Tool.googleSearch(),
  ],
);

final response = await model.generateContent([Content.text("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

وحدت


using Firebase;
using Firebase.AI;

// Initialize the Gemini Developer API backend service
var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// Create a `GenerativeModel` instance with a model that supports your use case
var model = ai.GetGenerativeModel(
  modelName: "GEMINI_MODEL_NAME",
  // Provide Google Search as a tool that the model can use to generate its response
  tools: new[] { new Tool(new GoogleSearch()) }
);

var response = await model.GenerateContentAsync("Who won the euro 2024?");
UnityEngine.Debug.Log(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

یاد بگیرید که چگونه یک مدل را انتخاب کنیدمناسب برای مورد استفاده و برنامه شما.

برای نتایج ایده‌آل، از دمای 1.0 استفاده کنید (که پیش‌فرض برای همه مدل‌های ۲.۵ است). یاد بگیرید که چگونه دما را در پیکربندی مدل تنظیم کنید.

نحوه اتصال به زمین با جستجوی گوگل

وقتی از ابزار GoogleSearch استفاده می‌کنید، این مدل کل گردش کار جستجو، پردازش و استناد به اطلاعات را به طور خودکار انجام می‌دهد.

روند کار مدل به شرح زیر است:

  1. دریافت اعلان : برنامه شما با فعال بودن ابزار GoogleSearch اعلانی را به مدل Gemini ارسال می‌کند.
  2. تحلیل درخواست : مدل، درخواست را تحلیل می‌کند و تعیین می‌کند که آیا جستجوی گوگل می‌تواند پاسخ خود را بهبود بخشد یا خیر.
  3. ارسال پرس‌وجوها به جستجوی گوگل : در صورت نیاز، مدل به‌طور خودکار یک یا چند پرس‌وجوی جستجو تولید کرده و آنها را اجرا می‌کند.
  4. پردازش نتایج جستجو : مدل، نتایج جستجوی گوگل را پردازش کرده و پاسخی برای درخواست اولیه تدوین می‌کند.
  5. بازگرداندن یک "نتیجه پایه" : مدل یک پاسخ نهایی و کاربرپسند را که مبتنی بر نتایج جستجوی گوگل است، برمی‌گرداند. این پاسخ شامل پاسخ متنی مدل و groundingMetadata با پرس‌وجوهای جستجو، نتایج وب و منابع است.

توجه داشته باشید که ارائه جستجوی گوگل به عنوان ابزاری برای مدل، مدل را ملزم نمی‌کند که همیشه از ابزار جستجوی گوگل برای تولید پاسخ خود استفاده کند. در این موارد، پاسخ حاوی شیء groundingMetadata نخواهد بود و بنابراین یک "نتیجه پایه" محسوب نمی‌شود .

نموداری که نشان می‌دهد چگونه اتصال به زمین با جستجوی گوگل شامل تعامل مدل با جستجوی گوگل می‌شود

نتیجه‌ی قطعی را درک کنید

اگر مدل، پاسخ خود را بر اساس نتایج جستجوی گوگل ارائه دهد، آنگاه پاسخ شامل یک شیء groundingMetadata است که حاوی داده‌های ساختاریافته‌ای است که برای تأیید ادعاها و ایجاد یک تجربه غنی از منبع در برنامه شما ضروری است.

شیء groundingMetadata در یک "نتیجه مبتنی بر" شامل اطلاعات زیر است:

  • webSearchQueries : آرایه‌ای از کوئری‌های جستجو که به جستجوی گوگل ارسال می‌شوند. این اطلاعات برای اشکال‌زدایی و درک فرآیند استدلال مدل مفید است.

  • searchEntryPoint : شامل HTML و CSS برای ارائه "پیشنهادات جستجوی گوگل" مورد نیاز است. شما ملزم به رعایت الزامات استفاده از "ارتباط با جستجوی گوگل" برای ارائه دهنده API انتخابی خود هستید: Gemini Developer API یا Vertex AI Gemini API (به بخش شرایط خدمات در شرایط خاص خدمات مراجعه کنید). نحوه استفاده و نمایش یک نتیجه مبتنی بر ارتباط را بعداً در این صفحه بیاموزید.

  • groundingChunks : آرایه‌ای از اشیاء شامل منابع وب ( uri و title ).

  • groundingSupports : آرایه‌ای از تکه‌ها برای اتصال text پاسخ مدل به منابع موجود در groundingChunks . هر تکه یک segment متنی (تعریف شده توسط startIndex و endIndex ) را به یک یا چند groundingChunkIndices پیوند می‌دهد. این فیلد به شما در ساخت لینک‌های منبع درون‌خطی کمک می‌کند. نحوه استفاده و نمایش یک نتیجه grounded را بعداً در این صفحه بیاموزید.

در اینجا یک پاسخ نمونه که شامل یک شیء 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]
          }
        ]
      }
    }
  ]
}

استفاده و نمایش یک نتیجه‌ی مبتنی بر شواهد

اگر مدل از ابزار جستجوی گوگل برای تولید پاسخ استفاده کند، یک شیء groundingMetadata در پاسخ ارائه خواهد داد.

برای نمایش پیشنهادات جستجوی گوگل و نمایش منابع لازم است .

نمایش این اطلاعات، فراتر از رعایت الزامات استفاده از ابزار جستجوی گوگل، به شما و کاربران نهایی‌تان کمک می‌کند تا پاسخ‌ها را اعتبارسنجی کنید و راه‌هایی برای یادگیری بیشتر اضافه می‌کند.

(الزامی) نمایش پیشنهادات جستجوی گوگل

اگر پاسخی حاوی «پیشنهادات جستجوی گوگل» باشد، شما ملزم به رعایت الزامات استفاده از «مطابقت با جستجوی گوگل» هستید، که شامل نحوه نمایش پیشنهادات جستجوی گوگل نیز می‌شود.

شیء groundingMetadata شامل "پیشنهادات جستجوی گوگل" است، به طور خاص فیلد searchEntryPoint که دارای یک فیلد renderedContent است که استایل‌بندی HTML و CSS سازگار را ارائه می‌دهد، که برای نمایش پیشنهادات جستجو در برنامه خود باید آن را پیاده‌سازی کنید.

اطلاعات دقیق در مورد الزامات نمایش و رفتار پیشنهادات جستجوی گوگل را در مستندات Google Cloud بررسی کنید. توجه داشته باشید که اگرچه این راهنمایی دقیق در مستندات Vertex AI Gemini API وجود دارد، اما این راهنمایی برای ارائه دهنده Gemini Developer API نیز قابل استفاده است.

نمونه‌های کد را بعداً در این بخش ببینید.

(الزامی) منابع نمایش

شیء groundingMetadata حاوی داده‌های منبع ساختاریافته، به‌ویژه فیلدهای groundingSupports و groundingChunks است. از این اطلاعات برای پیوند مستقیم دستورات مدل به منابع آنها در رابط کاربری خود (به‌صورت درون‌خطی و تجمیعی) استفاده کنید.

نمونه‌های کد را بعداً در این بخش ببینید.

نمونه‌های کد نمونه

این نمونه‌های کد، الگوهای کلی برای استفاده و نمایش نتیجه‌ی مبتنی بر واقعیت ارائه می‌دهند. با این حال، مسئولیت شما این است که مطمئن شوید پیاده‌سازی خاص شما با الزامات انطباق مطابقت دارد.

سویفت

// ...

// 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
  }

  // REQUIRED - display sources
  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 source 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
}

// REQUIRED - display sources
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 source 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
    }

    // REQUIRED - display sources
    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 sources 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
}

// REQUIRED - display sources
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 sources in the UI
  }
}

Dart

// ...

// Get the model's response
final text = response.text;

// Get the grounding metadata
final groundingMetadata = response.candidates.first.groundingMetadata;

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

// REQUIRED - display sources
final groundingChunks = groundingMetadata?.groundingChunks;
if (groundingChunks != null) {
  for (var chunk in groundingChunks) {
    final title = chunk.web?.title;  // for example, "uefa.com"
    final uri = chunk.web?.uri;  // for example, "https://vertexaisearch.cloud.google.com..."
    // TODO(developer): show sources in the UI
  }
}

وحدت

// ...

// Get the model's response
var text = response.Text;

// Get the grounding metadata
var groundingMetadata = response.Candidates.First().GroundingMetadata.Value;

// REQUIRED - display Google Search suggestions
// (renderedContent contains HTML and CSS for the search widget)
if (groundingMetadata.SearchEntryPoint.HasValue) {
    var renderedContent = groundingMetadata.SearchEntryPoint.Value.RenderedContent;
    // TODO(developer): Display Google Search suggestions using a WebView
}

// REQUIRED - display sources
foreach(GroundingChunk chunk in groundingMetadata.GroundingChunks) {
    var title = chunk.Web.Value.Title;  // for example, "uefa.com"
    var uri = chunk.Web.Value.Uri;  // for example, "https://vertexaisearch.cloud.google.com..."
    // TODO(developer): show sources in the UI
}

نتایج زمینی و نظارت بر هوش مصنوعی در کنسول Firebase

اگر نظارت هوش مصنوعی را در کنسول Firebase فعال کرده باشید، پاسخ‌ها در Cloud Logging ذخیره می‌شوند. به طور پیش‌فرض، این داده‌ها دارای دوره نگهداری 30 روزه هستند.

این مسئولیت شماست که اطمینان حاصل کنید این دوره نگهداری، یا هر دوره سفارشی که تعیین می‌کنید، کاملاً با مورد استفاده خاص شما و هرگونه الزامات انطباق اضافی برای ارائه‌دهنده API Gemini انتخابی شما: Gemini Developer API یا Vertex AI Gemini API (به بخش شرایط خدمات در شرایط خاص خدمات مراجعه کنید) همسو باشد. ممکن است لازم باشد دوره نگهداری را در Cloud Logging تنظیم کنید تا این الزامات را برآورده کنید.

قیمت‌گذاری و محدودیت‌ها

حتماً قیمت‌ها، موجودی مدل و محدودیت‌های اتصال به زمین با جستجوی گوگل را در مستندات ارائه‌دهنده‌ی API Gemini انتخابی خود بررسی کنید: Gemini Developer API |Vertex AI Gemini API .