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

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

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

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

• ارائه استناد: با نشان دادن منابع ادعاهای مدل، اعتماد کاربر را جلب کنید.

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Who won the euro 2024?",
    tools=[{"type": "google_search"}]
)

# Print the model's text response
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Who won the euro 2024?",
    tools: [{ type: "google_search" }]
});

const modelStep = interaction.steps.find(s => s.type === 'model_output');
if (modelStep) {
  for (const contentBlock of modelStep.content) {
    if (contentBlock.type === 'text') console.log(contentBlock.text);
  }
}

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Who won the euro 2024?",
    "tools": [{"type": "google_search"}]
  }'

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

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

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

درک پاسخ اتصال به زمین

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

{
  "steps": [
    {
      "type": "thought",
      "summary": [
        {
          "type": "text",
          "text": "The user is asking for the winner of Euro 2024. I need to search for the result of the Euro 2024 final."
        }
      ],
      "signature": "CoMDAXLI2nynRYojJIy6B1Jh9os2crpWLfB0..."
    },
    {
      "type": "google_search_call",
      "arguments": {
        "queries": ["UEFA Euro 2024 winner"]
      }
    },
    {
      "type": "google_search_result",
      "call_id": "search_001",
      "result": [
        {
          "search_suggestions": "<!-- HTML and CSS for the search widget -->"
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title.",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://www.aljazeera.com/sports/euro-2024-final",
              "title": "aljazeera.com",
              "start_index": 0,
              "end_index": 56
            },
            {
              "type": "url_citation",
              "url": "https://www.uefa.com/euro2024/news/spain-wins-euro-2024",
              "title": "uefa.com",
              "start_index": 57,
              "end_index": 124
            }
          ]
        }
      ]
    }
  ]
}

فیلدهای کلیدی در پاسخ:

• google_search_call : شامل queries جستجویی است که مدل اجرا کرده است.
• google_search_result : شامل search_suggestions ، یک قطعه کد HTML برای رندر کردن پیشنهادات جستجو در رابط کاربری شما است. الزامات کامل استفاده در شرایط خدمات به تفصیل شرح داده شده است.
• text با annotations : پاسخ ترکیبی مدل با استنادهای درون‌خطی. هر حاشیه‌نویسی url_citation یک بخش متنی (که توسط start_index و end_index تعریف می‌شود) را به یک URL منبع پیوند می‌دهد. این کلید ساخت استنادهای درون‌خطی است.

همچنین می‌توان از Grounding with Google Search در ترکیب با ابزار URL context برای Grounding پاسخ‌ها در داده‌های وب عمومی و URLهای خاصی که ارائه می‌دهید، استفاده کرد.

انتساب منابع با استناد درون‌خطی

این API حاشیه‌نویسی‌های درون‌خطی url_citation را روی بلوک محتوای متن برمی‌گرداند و به شما کنترل کاملی بر نحوه نمایش منابع در رابط کاربری‌تان می‌دهد. هر حاشیه‌نویسی شامل start_index و end_index است تا مشخص کند به کدام بخش از متن استناد می‌کند. در اینجا نحوه استخراج و نمایش آنها آمده است.

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nCitations:")
                    for annotation in content_block.annotations:
                        if annotation.type == "url_citation":
                            cited_text = content_block.text[annotation.start_index:annotation.end_index]
                            print(f"  [{annotation.title}]({annotation.url})")
                            print(f"    Cited text: \"{cited_text}\"")

for (const step of interaction.steps) {
  if (step.type === 'model_output') {
    for (const contentBlock of step.content) {
      if (contentBlock.type === 'text') {
        console.log(contentBlock.text);
        if (contentBlock.annotations) {
          console.log("\nCitations:");
          for (const annotation of contentBlock.annotations) {
            if (annotation.type === 'url_citation') {
              const citedText = contentBlock.text.slice(annotation.startIndex, annotation.endIndex);
              console.log(`  [${annotation.title}](${annotation.url})`);
              console.log(`    Cited text: "${citedText}"`);
            }
          }
        }
      }
    }
  }
}

خروجی، متن و به دنبال آن، ارجاعات آن را نشان می‌دهد:

Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title.

Citations:
  [aljazeera.com](https://www.aljazeera.com/sports/euro-2024-final)
    Cited text: "Spain won Euro 2024, defeating England 2-1 in the final."
  [uefa.com](https://www.uefa.com/euro2024/news/spain-wins-euro-2024)
    Cited text: "This victory marks Spain's record fourth European Championship title."

قیمت‌گذاری

وقتی از Grounding with Google Search با Gemini 3 استفاده می‌کنید، پروژه شما برای هر پرس‌وجوی جستجویی که مدل تصمیم به اجرای آن می‌گیرد، هزینه دریافت می‌کند. اگر مدل تصمیم به اجرای چندین پرس‌وجوی جستجو برای پاسخ به یک درخواست واحد (به عنوان مثال، جستجوی "UEFA Euro 2024 winner" و "Spain vs England Euro 2024 final score" در همان فراخوانی API) بگیرد، این به عنوان دو استفاده قابل پرداخت از ابزار برای آن درخواست محسوب می‌شود. برای اهداف صورتحساب، هنگام شمارش پرس‌وجوهای منحصر به فرد، پرس‌وجوهای جستجوی وب خالی را نادیده می‌گیریم. این مدل صورتحساب فقط برای مدل‌های Gemini 3 اعمال می‌شود. وقتی از Grounding search با مدل‌های Gemini 2.5 یا قدیمی‌تر استفاده می‌کنید، پروژه شما برای هر پرس‌وجو هزینه دریافت می‌کند.

برای اطلاعات دقیق در مورد قیمت‌گذاری، به صفحه قیمت‌گذاری Gemini API مراجعه کنید.

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

می‌توانید قابلیت‌های کامل را در صفحه نمای کلی مدل پیدا کنید.

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

شما می‌توانید از Grounding with Google Search به همراه ابزارهای دیگری مانند اجرای کد و زمینه URL برای تقویت موارد استفاده پیچیده‌تر استفاده کنید.

مدل‌های Gemini 3 از ترکیب ابزارهای داخلی (مانند Grounding با جستجوی گوگل) با ابزارهای سفارشی (فراخوانی تابع) پشتیبانی می‌کنند. برای اطلاعات بیشتر به صفحه ترکیب ابزارها مراجعه کنید.

قدم بعدی چیست؟

• درباره سایر ابزارهای موجود، مانند فراخوانی تابع، اطلاعات کسب کنید.
• یاد بگیرید که چگونه با استفاده از ابزار زمینه URL، اعلان‌ها را با URLهای خاص تقویت کنید.