سياق عنوان URL

تتيح لك أداة سياق عناوين URL تقديم سياق إضافي للنماذج في شكل عناوين 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-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

آلية العمل

تستخدم أداة "سياق عناوين URL" عملية استرجاع من خطوتَين لتحقيق التوازن بين السرعة والتكلفة والوصول إلى البيانات الحديثة. عند تقديم عنوان URL، تحاول الأداة أولاً جلب المحتوى من ذاكرة تخزين مؤقت للفهرس الداخلي. ويعمل ذلك كذاكرة تخزين مؤقت محسّنة للغاية. إذا لم يكن عنوان URL متاحًا في الفهرس (على سبيل المثال، إذا كانت الصفحة جديدة جدًا)، ستعود الأداة تلقائيًا إلى إجراء جلب مباشر. يؤدي ذلك إلى الوصول مباشرةً إلى عنوان URL لاسترداد محتواه في الوقت الفعلي.

الدمج مع أدوات أخرى

يمكنك دمج أداة سياق عنوان URL مع أدوات أخرى لإنشاء مسارات عمل أكثر فعالية.

تتيح نماذج Gemini 3 الجمع بين الأدوات المضمّنة (مثل "سياق عناوين URL") والأدوات المخصّصة (استدعاء الدوال). يمكنك الاطّلاع على مزيد من المعلومات في صفحة مجموعات الأدوات.

تحديد المصدر من خلال "بحث Google"

عند تفعيل كلّ من سياق عناوين URL وتحديد المصدر من خلال "بحث Search"، يمكن للنموذج استخدام إمكانات البحث للعثور على معلومات ذات صلة على الإنترنت، ثم استخدام أداة سياق عناوين URL للتعمّق في فهم الصفحات التي يعثر عليها. هذا الأسلوب فعّال مع الطلبات التي تتطلّب بحثًا واسع النطاق وتحليلاً معمّقًا لصفحات معيّنة.

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، يتضمّن الردّ عنصر 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.

عمليات التحقّق من الأمان

يُجري النظام عملية تحقّق من الإشراف على المحتوى في عنوان URL للتأكّد من استيفائه معايير الأمان. إذا لم ينجح عنوان 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 التي تقدّمها لا تؤدي إلى صفحات تتطلّب تسجيل الدخول أو تقع خلف حاجز دفع.
• استخدام عنوان URL الكامل: قدِّم عنوان URL الكامل، بما في ذلك البروتوكول (مثلاً، https://www.google.com بدلاً من google.com فقط).

القيود

• الحدّ الأقصى للطلبات: يمكن للأداة معالجة ما يصل إلى 20 عنوان URL لكل طلب.
• حجم محتوى عنوان URL: الحد الأقصى لحجم المحتوى الذي يتم استرداده من عنوان URL واحد هو 34 ميغابايت.
• إمكانية الوصول إلى الجميع: يجب أن تكون عناوين URL متاحة للجميع على الويب. لا يمكن استخدام عناوين المضيف المحلي (مثل localhost و127.0.0.1) والشبكات الخاصة وخدمات الاتصال النفقي (مثل ngrok وpinggy).

أنواع المحتوى المتوافقة وغير المتوافقة

يمكن للأداة استخراج المحتوى من عناوين URL التي تتضمّن أنواع المحتوى التالية:

• النصوص (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 (راجِع مقالة فهم الفيديو لمعرفة كيفية معالجة عناوين URL الخاصة بفيديوهات على YouTube)
• ملفات Google Workspace، مثل "مستندات Google" أو جداول البيانات
• ملفات الفيديو والصوت

الخطوات التالية

• يمكنك الاطّلاع على دليل سياق عناوين URL لمزيد من الأمثلة.