بافت نشانی وب

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

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

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

مثال زیر نشان می‌دهد که چگونه دو دستور پخت از وب‌سایت‌های مختلف را مقایسه کنید.

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

url1 = "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"
url2 = "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",
    tools=[{"type": "url_context"}]
)

# Print the model's text response and its source annotations
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("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "url_citation":
                            print(f"  - {annotation.title}: {annotation.url}")

جاوا اسکریپت

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
    tools: [{ type: "url_context" }]
  });

  // Print the model's text response and its source annotations
  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("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'url_citation') {
                console.log(`  - ${annotation.title}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

await main();

رفتن

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

    url1 := "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"
    url2 := "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(
                fmt.Sprintf("Compare the ingredients and cooking times from the recipes at %s and %s", url1, url2),
            ),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.URLContext{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // Print the model's text response and its source annotations
    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                    if len(contentBlock.TextContent.Annotations) > 0 {
                        fmt.Println("\nSources:")
                        for _, annotation := range contentBlock.TextContent.Annotations {
                            if annotation.URLCitation != nil {
                                fmt.Printf("  - %s: %s\n", annotation.URLCitation.GetTitle(), annotation.URLCitation.GetURL())
                            }
                        }
                    }
                }
            }
        }
    }
}

REST

# Specifies the API revision to avoid breaking changes when they become default
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": "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
      "tools": [{"type": "url_context"}]
  }'

روش کار

ابزار «زمینه نشانی وب» از فرایند بازیابی دو مرحله‌ای برای توازن سرعت، هزینه، و دسترسی به داده‌های جدید استفاده می‌کند. وقتی نشانی وبی ارائه می‌کنید، ابزار ابتدا تلاش می‌کند محتوا را از حافظه نهان نمایه‌سازی داخلی واکشی کند. این کار به‌عنوان حافظه نهان بسیار بهینه‌سازی‌شده عمل می‌کند. اگر نشانی وبی در نمایه دردسترس نباشد (برای مثال، اگر صفحه بسیار جدید باشد)، ابزار به‌طور خودکار به واکشی زنده برمی‌گردد. این کار مستقیماً به نشانی وب دسترسی پیدا می‌کند تا محتوای آن را به‌صورت هم‌زمان بازیابی کند.

می‌توانید ابزار زمینه‌ای نشانی وب را با ابزارهای دیگر ترکیب کنید تا گردش‌های کاری قدرتمندتری ایجاد کنید.

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

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

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
    tools=[
        {"type": "url_context"},
        {"type": "google_search"}
    ]
)

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)

جاوا اسکریپت

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
    tools: [
      { type: "url_context" },
      { type: "google_search" }
    ]
  });

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

await main();

رفتن

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

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute."),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.URLContext{}),
                interactions.NewTool(interactions.GoogleSearch{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                }
            }
        }
    }
}

REST

# Specifies the API revision to avoid breaking changes when they become default
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": "Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
      "tools": [
          {"type": "url_context"},
          {"type": "google_search"}
      ]
  }'

درحال درک پاسخ

وقتی مدل از ابزار بافت نشانی وب استفاده می‌کند، پاسخ نوشتاری آن شامل url_citation گزارمان‌های درون‌خطی در بلوک محتوای نوشتاری است. هر گل‌نویسی یک بخش از نوشتار پاسخ (ازطریق start_index و end_index) را به نشانی وب منبعی که از آن استخراج شده است پیوند می‌دهد. این روش اصلی برای نمایش استنادها در برنامه شما است — برای نحوه استخراج آن‌ها، مثال اصلی بالا را ببینید.

پاسخ همچنین شامل یک مرحله url_context_result با فراداده درباره هر تلاش بازیابی نشانی وب (وضعیت، نشانی وب بازیابی‌شده) است. این ویژگی عمدتاً برای اشکال‌زدایی مفید است.

بررسی‌های ایمنی

سیستم بررسی محتوای نشانی‌های وب را انجام می‌دهد تا تأیید کند استانداردهای ایمنی را رعایت می‌کنند. اگر نشانی وبی در این بررسی ناموفق باشد، مرحله مربوطه url_context_result status از "unsafe" را نشان خواهد داد.

تعداد داده‌واحد

محتوای بازیابی‌شده از نشانی‌های وبی که در پیام‌واره‌تان مشخص می‌کنید به‌عنوان بخشی از نشانه‌های ورودی محاسبه می‌شود. تعداد نشان‌ها را می‌توانید در usage شیء تعامل ببینید. مثال زیر را درنظر بگیرید:

'usage': {
  'output_tokens': 45,
  'input_tokens': 27,
  'input_tokens_details': [{'modality': 'TEXT', 'token_count': 27}],
  'thoughts_tokens': 31,
  'tool_use_input_tokens': 10309,
  'tool_use_input_tokens_details': [{'modality': 'TEXT', 'token_count': 10309}],
  'total_tokens': 10412
}

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

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

مدل بافت نشانی وب
Gemini 3.8 Flash ✔️
Gemini 3.6 Flash ✔️
Gemini 3.5 Flash-Lite ✔️
پیش‌نمایش Gemini 3.1 Pro ✔️
Gemini 3.1 Flash-Lite ✔️
پیش‌نمایش Gemini 3 Flash ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️

روال‌های مطلوب

  • نشانی‌های وب خاص ارائه دهید: برای بهترین نتایج، نشانی‌های وب مستقیم به محتوایی که می‌خواهید مدل تجزیه‌وتحلیل کند ارائه دهید. این مدل فقط محتوای نشانی‌های وبی را که ارائه می‌کنید بازیابی می‌کند، نه محتوای پیوندهای تودرتو.
  • بررسی دسترسی‌پذیری: مطمئن شوید نشانی‌های وبی که ارائه می‌کنید به صفحه‌هایی که نیاز به ورود به سیستم دارند یا پشت دیوار پرداخت هستند منتهی نمی‌شوند.
  • از نشانی وب کامل استفاده کنید: نشانی وب کامل را به‌همراه پروتکل ارائه دهید (برای نمونه، https://www.google.com به‌جای google.com).

محدودیت‌ها

  • محدودیت درخواست: این ابزار می‌تواند تا ۲۰ نشانی وب را در هر درخواست پردازش کند.
  • اندازه محتوای نشانی وب: حداکثر اندازه برای محتوای بازیابی‌شده از یک نشانی وب ۳۴ مگابایت است.
  • دسترسی عمومی: نشانی‌های وب باید به‌صورت عمومی در وب دردسترس باشند. از نشانی‌های میزبان محلی (برای نمونه، میزبان محلی، 127.0.0.1)، شبکه‌های خصوصی، و خدمات تونل‌سازی (برای نمونه، ngrok،‏ pinggy) پشتیبانی نمی‌شود.

انواع محتوای پشتیبانی‌شده و پشتیبانی‌نشده

این ابزار می‌تواند محتوا را از نشانی‌های وب با انواع محتوای زیر استخراج کند:

  • نوشتار (text/html،‏ application/json،‏ text/plain،‏ text/xml،‏ text/css،‏ text/javascript،‏ text/csv،‏ text/rtf)
  • تصویر (image/png،‏ image/jpeg،‏ image/bmp،‏ image/webp)
  • PDF (application/pdf)

از انواع محتوای زیر پشتیبانی نمی‌شود:

  • محتوای تحت دیوار پرداخت
  • ویدیوهای YouTube (برای آشنایی با نحوه پردازش نشانی‌های وب YouTube، به درک ویدیو مراجعه کنید)
  • فایل‌های Google Workspace مثل اسناد Google یا صفحه‌گسترده‌ها
  • فایل‌های صوتی و تصویری