زمینه URL

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

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

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

مثال زیر نحوه مقایسه دو دستور غذا از وب‌سایت‌های مختلف را نشان می‌دهد.

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-flash-preview",
    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}")

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

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    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();

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": "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"}]
  }'

چگونه کار می‌کند؟

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

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

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

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

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

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

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    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)

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

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    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();

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": "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 استفاده می‌کند، پاسخ متنی آن شامل حاشیه‌نویسی‌های درون‌خطی url_citation در بلوک محتوای متن است. هر حاشیه‌نویسی بخشی از متن پاسخ (از طریق start_index و end_index ) را به URL منبعی که از آن مشتق شده است، پیوند می‌دهد. این روش اصلی برای نمایش استنادها در برنامه شماست - برای نحوه استخراج آنها به مثال اصلی بالا مراجعه کنید.

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

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

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

تعداد توکن‌ها

محتوای بازیابی شده از URL هایی که در اعلان خود مشخص می کنید، به عنوان بخشی از توکن های ورودی شمارش می شود. می توانید تعداد توکن ها را در شیء 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
}

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

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

بهترین شیوه‌ها

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

محدودیت‌ها

• فراخوانی تابع: استفاده از ابزار (متن URL، اتصال به زمین با جستجوی گوگل و غیره) با فراخوانی تابع در حال حاضر پشتیبانی نمی‌شود.
• محدودیت درخواست: این ابزار می‌تواند تا ۲۰ آدرس اینترنتی (URL) را در هر درخواست پردازش کند.
• اندازه محتوای URL: حداکثر اندازه برای محتوای بازیابی شده از یک URL واحد ۳۴ مگابایت است.
• دسترسی عمومی: URLها باید به صورت عمومی در وب قابل دسترسی باشند. آدرس‌های میزبان محلی (مثلاً localhost، 127.0.0.1)، شبکه‌های خصوصی و سرویس‌های تونل‌زنی (مثلاً ngrok، pinggy) پشتیبانی نمی‌شوند.
• فقط API Gemini: URL Context فقط در API Gemini در دسترس است، نه از طریق پلتفرم Gemini Enterprise Agent.

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

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

• متن (متن/html، برنامه/json، متن/ساده، متن/xml، متن/css، متن/javascript، متن/csv، متن/rtf)
• تصویر (تصویر/png، تصویر/jpeg، تصویر/bmp، تصویر/webp)
• پی‌دی‌اف (فرمت درخواست/پی‌دی‌اف)

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

• محتوای پولی
• ویدیوهای یوتیوب (برای یادگیری نحوه پردازش URL های یوتیوب به بخش درک ویدیو مراجعه کنید)
• فایل‌های فضای کاری گوگل مانند اسناد گوگل یا صفحات گسترده
• فایل‌های ویدیویی و صوتی