URL context

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

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

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

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

پایتون

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

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

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

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

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

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

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

پایتون

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

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

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-flash-preview",
    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-flash-preview: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 استفاده می‌کند، پاسخ شامل یک شیء url_context_metadata می‌شود. این شیء، URLهایی را که مدل محتوا را از آنها بازیابی کرده و وضعیت هر تلاش بازیابی را فهرست می‌کند که برای تأیید و اشکال‌زدایی مفید است.

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

{
  "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"
          }
        ]
      }
    }
}

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

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

The system performs a content moderation check on the URL to confirm they meet safety standards. If the URL you provided fails this check, you will get an url_retrieval_status of URL_RETRIEVAL_STATUS_UNSAFE .

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

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

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

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

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

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

محدودیت‌ها

  • فراخوانی تابع: استفاده از ابزار (متن URL، اتصال به زمین با جستجوی گوگل و غیره) با فراخوانی تابع در حال حاضر پشتیبانی نمی‌شود.
  • محدودیت درخواست: این ابزار می‌تواند تا ۲۰ آدرس اینترنتی (URL) را در هر درخواست پردازش کند.
  • اندازه محتوای URL: حداکثر اندازه برای محتوای بازیابی شده از یک URL واحد ۳۴ مگابایت است.

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

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

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

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

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

قدم بعدی چیست؟