URL context

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

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

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

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

پایتون 

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

client = genai.Client()
model_id = "gemini-2.5-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-2.5-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-2.5-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

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

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

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

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

پایتون 

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

client = genai.Client()
model_id = "gemini-2.5-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-2.5-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-2.5-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 استفاده می کند، پاسخ شامل یک شی 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"
          }
        ]
      }
    }
}

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

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

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

شمارش توکن

محتوای بازیابی شده از URL هایی که در درخواست خود مشخص می کنید به عنوان بخشی از نشانه های ورودی محاسبه می شود. می‌توانید تعداد توکن‌ها را برای استفاده از ابزار و درخواست خود در شی 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 کامل استفاده کنید : نشانی اینترنتی کامل، از جمله پروتکل را ارائه دهید (به عنوان مثال، https://www.google.com به جای google.com).

محدودیت ها

  • قیمت گذاری : محتوای بازیابی شده از URL ها به عنوان نشانه های ورودی حساب می شود. محدودیت نرخ و قیمت بر اساس مدل استفاده شده است. برای جزئیات به صفحات محدودیت نرخ و قیمت مراجعه کنید.
  • محدودیت درخواست : این ابزار می تواند تا 20 URL را در هر درخواست پردازش کند.
  • اندازه محتوای URL : حداکثر اندازه برای محتوای بازیابی شده از یک URL واحد 34 مگابایت است.

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

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

  • متن (متن/html، برنامه/json، متن/ساده، متن/xml، متن/css، متن/جاوا اسکریپت، متن/csv، متن/rtf)
  • تصویر (تصویر/png، تصویر/jpeg، تصویر/bmp، تصویر/webp)
  • PDF (برنامه/pdf)

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

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

بعدش چی