سياق عنوان URL

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

تكون أداة "سياق عنوان URL" مفيدة في مهام مثل ما يلي:

  • استخراج البيانات: يمكنك استخراج معلومات محدّدة، مثل الأسعار أو الأسماء أو النتائج الرئيسية، من عناوين URL متعددة.
  • مقارنة المستندات: يمكنك تحليل تقارير أو مقالات أو ملفات PDF متعددة لـ تحديد الاختلافات وتتبُّع المؤشرات.
  • تجميع المحتوى وإنشاؤه: يمكنك دمج المعلومات من عدة عناوين URL مصدر لإنشاء ملخّصات أو منشورات مدوّنة أو تقارير دقيقة.
  • تحليل الرموز البرمجية والمستندات: يمكنك الإشارة إلى مستودع GitHub أو مستندات فنية لشرح الرموز البرمجية أو إنشاء تعليمات الإعداد أو الإجابة عن الأسئلة.

يوضّح المثال التالي كيفية مقارنة وصفتَين من موقعَين إلكترونيَين مختلفَين.

Python

# This will only work for SDK newer than 2.0.0
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.5-flash",
    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}")

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

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

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "model": "gemini-3.5-flash",
      "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" عملية استرداد من خطوتَين لتحقيق التوازن بين السرعة والتكلفة والوصول إلى البيانات الحديثة. عند تقديم عنوان URL، تحاول الأداة أولاً جلب المحتوى من ذاكرة تخزين مؤقت لفهرس داخلي. وتعمل هذه الذاكرة كذاكرة تخزين مؤقت محسّنة إلى حد كبير. إذا لم يكن عنوان URL متاحًا في الفهرس (على سبيل المثال، إذا كانت صفحة جديدة جدًا)، تعود الأداة تلقائيًا إلى إجراء عملية جلب مباشرة. ويؤدي ذلك إلى الوصول مباشرةً إلى عنوان URL لاسترداد محتواه في الوقت الفعلي.

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

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

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

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

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

Javascript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

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

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "model": "gemini-3.5-flash",
      "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
‫Gemini 3.5 Flash ✔️
‫Gemini 3.1 Pro Preview ✔️
‫Gemini 3.1 Flash-Lite ✔️
‫Gemini 3 Flash Preview ✔️
‫Gemini 2.5 Pro ✔️
‫Gemini 2.5 Flash ✔️
‫Gemini 2.5 Flash-Lite ✔️

أفضل الممارسات

  • توفير عناوين URL محدّدة: للحصول على أفضل النتائج، ننصحك بتوفير عناوين URL مباشرةً للمحتوى الذي تريد أن يحلّله النموذج. لن يستردّ النموذج سوى المحتوى من عناوين URL التي تقدّمها، وليس أي محتوى من الروابط المضمّنة.
  • التحقّق من إمكانية الوصول: تأكَّد من أنّ عناوين URL التي تقدّمها لا تؤدي إلى صفحات تتطلّب تسجيل الدخول أو تكون محجوبة بنظام حظر الاشتراك غير المدفوع.
  • استخدام عنوان URL الكامل: ننصحك بتوفير عنوان URL الكامل، بما في ذلك البروتوكول (مثل https://www.google.com بدلاً من google.com فقط).

القيود

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

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

يمكن للأداة استخراج المحتوى من عناوين 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 أو جداول البيانات
  • ملفات الفيديو والصوت