پایه‌مندسازی با «جستجوی Google»

«پایه‌گذاری با جستجوی Google» مدل Gemini را به محتوای وب هم‌زمان متصل می‌کند و با همه زبان‌های دردسترس کار می‌کند. این کار به Gemini امکان می‌دهد پاسخ‌های دقیق‌تری ارائه دهد و منابع قابل‌تأیید را فراتر از تاریخ قطع اطلاعات خود ذکر کند.

«پایه‌گذاری» به شما کمک می‌کند برنامه‌هایی بسازید که بتوانند:

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

Python

from google import genai

client = genai.Client()

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

print(interaction.output_text)

JavaScript

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

const client = new GoogleGenAI({});

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

console.log(interaction.output_text);

جاوا

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Who won the euro 2024?"))
        .tools(Arrays.asList(GoogleSearch.builder().build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

رفتن

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Who won the euro 2024?"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.GoogleSearch{}),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(resp.Interaction.GetOutputText())
}

REST

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.8-flash",
    "input": "Who won the euro 2024?",
    "tools": [{"type": "google_search"}]
  }'

نحوه عملکرد پایه‌مندسازی با «جستجوی Google»

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

نمای کلی پایه‌مندسازی

  1. پیام‌واره کاربر: برنامه شما پیام‌واره کاربر را به Gemini API با ابزار google_search فعال ارسال می‌کند.
  2. تجزیه‌وتحلیل پیام‌واره: مدل پیام‌واره را تجزیه‌وتحلیل می‌کند و تعیین می‌کند که آیا «جستجوی Google» می‌تواند پاسخ را بهبود دهد یا نه.
  3. جستجوی Google: درصورت نیاز، مدل به‌طور خودکار یک یا چند پُرسمان جستجو تولید می‌کند و آن‌ها را اجرا می‌کند.
  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) را به نشانی وب منبع پیوند می‌دهد. این کلید ساختن استنادهای درون‌خطی است.

از «پایه‌گذاری با جستجوی Google» می‌توان در ترکیب با ابزار بافت نشانی وب نیز استفاده کرد تا پاسخ‌ها را هم در داده‌های وب عمومی و هم در نشانی‌های وب خاصی که ارائه می‌کنید پایه‌گذاری کند.

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

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

Python

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}\"")

JavaScript

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}"`);
            }
          }
        }
      }
    }
  }
}

جاوا

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.GoogleSearch;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.URLCitation;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Who won the euro 2024?"))
        .tools(Arrays.asList(GoogleSearch.builder().build()))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

if (interaction.steps().isPresent()) {
  for (Step step : interaction.steps().get()) {
    if (step instanceof ModelOutputStep) {
      ModelOutputStep outputStep = (ModelOutputStep) step;
      if (outputStep.content().isPresent()) {
        for (Content contentBlock : outputStep.content().get()) {
          if (contentBlock instanceof TextContent) {
            TextContent textContent = (TextContent) contentBlock;
            String text = textContent.text().orElse("");
            System.out.println(text);
            if (textContent.annotations().isPresent()
                && !textContent.annotations().get().isEmpty()) {
              System.out.println("\nCitations:");
              for (Annotation annotation : textContent.annotations().get()) {
                if (annotation instanceof URLCitation) {
                  URLCitation citation = (URLCitation) annotation;
                  int start = citation.startIndex().orElse(0);
                  int end = citation.endIndex().orElse(0);
                  String citedText =
                      (start >= 0 && end <= text.length() && start <= end)
                          ? text.substring(start, end)
                          : "";
                  System.out.printf(
                      "  [%s](%s)%n", citation.title().orElse(""), citation.url().orElse(""));
                  System.out.printf("    Cited text: \"%s\"%n", citedText);
                }
              }
            }
          }
        }
      }
    }
  }
}

رفتن

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(
            interactions.CreateModelInteraction{
                Model: interactions.Model("gemini-3.8-flash"),
                Input: interactions.NewInteractionsInput("Who won the euro 2024?"),
                Tools: []interactions.Tool{
                    interactions.NewTool(interactions.GoogleSearch{}),
                },
            },
        ),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range resp.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, content := range step.ModelOutputStep.Content {
                if content.TextContent != nil {
                    text := content.TextContent.Text
                    fmt.Println(text)
                    if len(content.TextContent.Annotations) > 0 {
                        fmt.Println("\nCitations:")
                        for _, annotation := range content.TextContent.Annotations {
                            if annotation.URLCitation != nil {
                                c := annotation.URLCitation
                                start := 0
                                if c.StartIndex != nil {
                                    start = *c.StartIndex
                                }
                                end := 0
                                if c.EndIndex != nil {
                                    end = *c.EndIndex
                                }
                                citedText := ""
                                if start >= 0 && end <= len(text) && start <= end {
                                    citedText = text[start:end]
                                }
                                title := ""
                                if c.Title != nil {
                                    title = *c.Title
                                }
                                url := ""
                                if c.URL != nil {
                                    url = *c.URL
                                }
                                fmt.Printf("  [%s](%s)\n", title, url)
                                fmt.Printf("    Cited text: %q\n", 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."

قیمت‌گذاری

وقتی از «پایه‌گذاری با جستجوی Google» با Gemini 3 و مدل‌های جدیدتر استفاده می‌کنید، هزینه پروژه شما برای هر پُرسمان جستجویی که مدل تصمیم می‌گیرد اجرا کند محاسبه می‌شود. این مدل صورت‌حساب براساس پُرسمان شامل ۵٬۰۰۰ درخواست جستجوی رایگان در ماه است که بین همه مدل‌های Gemini 3 و جدیدتر به‌اشتراک گذاشته می‌شود، و سپس هزینه آن ۱۴ دلار برای هر ۱٬۰۰۰ درخواست جستجو است.

برای مثال، اگر مدل تصمیم بگیرد برای پاسخ دادن به یک پیام‌واره واحد، چندین پُرسمان جستجو اجرا کند (برای نمونه، جستجوی "UEFA Euro 2024 winner" و "Spain vs England Euro 2024 final score" در همان فراخوانی API)، این به‌عنوان دو استفاده صورت‌حساب‌پذیر از ابزار برای آن درخواست محاسبه می‌شود. برای اهداف صورت‌حساب، پُرسمان‌های جستجوی وب خالی را هنگام شمارش پُرسمان‌های یکتا نادیده می‌گیریم.

وقتی از «پایه جستجو» با Gemini 2.5 یا مدل‌های قدیمی‌تر استفاده می‌کنید، هزینه پروژه شما براساس هر پیام‌واره محاسبه می‌شود.

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

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

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

مدل پایه‌مندسازی با «جستجوی Google»
Gemini 3.8 Flash ✔️
Gemini 3.6 Flash ✔️
Gemini 3.5 Flash-Lite ✔️
پیش‌نمایش تصویر Gemini 3.1 Flash ✔️
پیش‌نمایش Gemini 3.1 Pro ✔️
پیش‌نمایش تصویر Gemini 3 Pro ✔️
پیش‌نمایش Gemini 3 Flash ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️
Gemini 2.0 Flash ✔️

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

می‌توانید از «پایه با جستجوی Google» با ابزارهای دیگر مثل اجرای کد، زمینه نشانی وب، و پایه با Google Maps (پشتیبانی‌شده در Gemini 3.5 Flash-Lite و مدل‌های جدیدتر) برای تقویت موارد استفاده پیچیده‌تر استفاده کنید. مدل‌های Gemini 3 همچنین از ترکیب این ابزارهای داخلی با ابزارهای سفارشی (فراخوانی تابع) پشتیبانی می‌کنند. در صفحه ترکیب‌های ابزار بیشتر بدانید.

قدم بعدی چیست