بافت نشانی وب

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

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

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

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

from google import genai
from google.genai.types import Tool, GenerateContentConfig

client = genai.Client()
model_id = "gemini-3.8-flash"

tools = [
  {"url_context": {}},
]

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

response = client.models.generate_content(
    model=model_id,
    contents=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",
    config=GenerateContentConfig(
        tools=tools,
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)

# For verification, you can inspect the metadata to see which URLs the model retrieved
print(response.candidates[0].url_context_metadata)

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.8-flash",
    contents: [
        "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/",
    ],
    config: {
      tools: [{urlContext: {}}],
    },
  });
  console.log(response.text);

  // For verification, you can inspect the metadata to see which URLs the model retrieved
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "contents": [
          {
              "parts": [
                  {"text": "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": [
          {
              "url_context": {}
          }
      ]
  }' > result.json

cat result.json

روش کار

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

ترکیب با ابزارهای دیگر

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

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

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

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

from google import genai
from google.genai.types import Tool, GenerateContentConfig, GoogleSearch, UrlContext

client = genai.Client()
model_id = "gemini-3.8-flash"

tools = [
      {"url_context": {}},
      {"google_search": {}}
  ]

response = client.models.generate_content(
    model=model_id,
    contents="Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
    config=GenerateContentConfig(
        tools=tools,
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)
# get URLs retrieved for context
print(response.candidates[0].url_context_metadata)

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.8-flash",
    contents: [
        "Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
    ],
    config: {
      tools: [
        {urlContext: {}},
        {googleSearch: {}}
        ],
    },
  });
  console.log(response.text);
  // To get URLs retrieved for context
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "contents": [
          {
              "parts": [
                  {"text": "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": [
          {
              "url_context": {}
          },
          {
              "google_search": {}
          }
      ]
  }' > result.json

cat result.json

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

وقتی مدل از ابزار بافت نشانی وب استفاده می‌کند، پاسخ شامل یک شیء url_context_metadata است. این شیء نشانی‌های وبی را که مدل از آن‌ها محتوا بازیابی کرده است فهرست می‌کند و وضعیت هر تلاش بازیابی را نشان می‌دهد که برای درستی‌سنجی و اشکال‌زدایی مفید است.

در زیر نمونه‌ای از آن بخش از پاسخ آورده شده است (بخش‌هایی از پاسخ برای اختصار حذف شده است):

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata": {
        "url_metadata": [
          {
            "retrieved_url": "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592",
            "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
          },
          {
            "retrieved_url": "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
            "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
          }
        ]
      }
    }
  ]
}

برای جزئیات کامل درباره این شیء، مرجع میانای برنامه‌سازی کاربردی UrlContextMetadata را ببینید.

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

سیستم بررسی محتوای نشانی وب را برای تأیید اینکه استانداردهای ایمنی را رعایت می‌کند انجام می‌دهد. اگر نشانی وبی که ارائه کرده‌اید در این بررسی ناموفق باشد، url_retrieval_status URL_RETRIEVAL_STATUS_UNSAFE دریافت خواهید کرد.

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

محتوای بازیابی‌شده از نشانی‌های وبی که در پیام‌واره‌تان مشخص می‌کنید به‌عنوان بخشی از نشانه‌های ورودی محاسبه می‌شود. می‌توانید تعداد نشانه‌های پیام‌واره و استفاده از ابزارها را در usage_metadata موضوع برونداد مدل ببینید. برونداد نمونه در زیر آمده است:

'usage_metadata': {
  'candidates_token_count': 45,
  'prompt_token_count': 27,
  'prompt_tokens_details': [{'modality': <MediaModality.TEXT: 'TEXT'>,
    'token_count': 27}],
  'thoughts_token_count': 31,
  'tool_use_prompt_token_count': 10309,
  'tool_use_prompt_tokens_details': [{'modality': <MediaModality.TEXT: 'TEXT'>,
    'token_count': 10309}],
  'total_token_count': 10412
  }

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

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

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

• نشانی‌های وب خاصی را ارائه دهید: برای بهترین نتایج، نشانی‌های وب مستقیم به محتوایی که می‌خواهید مدل تجزیه‌وتحلیل کند ارائه دهید. مدل فقط محتوا را از نشانی‌های وبی که ارائه می‌دهید بازیابی می‌کند، نه محتوای پیوندهای تودرتو.
• بررسی دسترسی‌پذیری: مطمئن شوید نشانی‌های وبی که ارائه می‌کنید به صفحه‌هایی که نیاز به ورود به سیستم دارند یا پشت دیوار پرداخت هستند منتهی نمی‌شوند.
• از نشانی وب کامل استفاده کنید: نشانی وب کامل را به‌همراه پروتکل ارائه دهید (برای مثال، 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» یا صفحه‌گسترده‌ها
• فایل‌های صوتی و ویدیویی

قدم بعدی چیست

• برای مثال‌های بیشتر، کتاب راهنمای بافت نشانی وب را کاوش کنید.