بافت نشانی وب

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

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

  • استخراج داده: اطلاعات خاصی مانند قیمت‌ها، نام‌ها، یا یافته‌های کلیدی را از چندین نشانی وب استخراج کنید.
  • مقایسه اسناد: گزارش‌ها، مقاله‌ها، یا فایل‌های 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)
                }
            }
        }
    }
}

استراحت

# 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 4 Argon ✔️
‫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).

محدودیت‌ها

  • محدودیت درخواست: این ابزار می‌تواند تا ۲۰ نشانی وب را در هر درخواست پردازش کند.
  • اندازه محتوای نشانی وب: حداکثر اندازه محتوای بازیابی‌شده از یک نشانی وب ۳۴ مگابایت است.
  • دسترسی عمومی: نشانی‌های وب باید به‌صورت عمومی در وب دردسترس باشند. نشانی‌های Localhost (مثلاً localhost،‏ 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» یا صفحه‌گسترده‌ها
  • فایل‌های صوتی و تصویری