URL context

باستخدام أداة سياق عنوان URL، يمكنك تزويد Gemini بعناوين URL كسياق إضافي لطلبك. يمكن للنموذج بعد ذلك استرداد المحتوى من عناوين URL واستخدام هذا المحتوى لتحديد ردّه وتشكيله.

هذه الأداة مفيدة للمهام التالية:

  • استخراج نقاط البيانات الرئيسية أو النقاط الأساسية من المقالات
  • مقارنة المعلومات في روابط متعددة
  • تجميع البيانات من عدة مصادر
  • الإجابة عن الأسئلة استنادًا إلى محتوى صفحة أو صفحات معيّنة
  • تحليل المحتوى لأغراض محدّدة (مثل كتابة وصف وظيفي أو إنشاء أسئلة اختبارية)

يوضّح هذا الدليل كيفية استخدام أداة سياق عنوان URL في Gemini API.

استخدام سياق عنوان URL

يمكنك استخدام أداة سياق عنوان URL بطريقتَين رئيسيتين، إما بمفردها أو مع التثبيت باستخدام "بحث Google".

سياق عنوان URL فقط

يمكنك تقديم عناوين URL محدّدة تريد أن يحلّلها النموذج مباشرةً في طلبك.

أمثلة على الطلبات:

Summarize this document: YOUR_URLs

Extract the key features from the product description on this page: YOUR_URLs

الربط بنتائج البحث من Google + سياق عنوان URL

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

أمثلة على الطلبات:

Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.

Recommend 3 books for beginners to read to learn more about the latest YOUR_subject.

أمثلة على الرموز البرمجية التي تتضمّن سياق عنوان URL فقط

Python

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

client = genai.Client()
model_id = "gemini-2.5-flash-preview-05-20"

url_context_tool = Tool(
    url_context = types.UrlContext
)

response = client.models.generate_content(
    model=model_id,
    contents="Compare recipes from YOUR_URL1 and YOUR_URL2",
    config=GenerateContentConfig(
        tools=[url_context_tool],
        response_modalities=["TEXT"],
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)
# get URLs retrieved for context
print(response.candidates[0].url_context_metadata)

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash-preview-05-20",
    contents: [
        "Compare recipes from YOUR_URL1 and YOUR_URL2",
    ],
    config: {
      tools: [{urlContext: {}}],
    },
  });
  console.log(response.text);
  // To get URLs retrieved for context
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-preview-05-20:generateContent?key=$GOOGLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "contents": [
          {
              "parts": [
                  {"text": "Compare recipes from YOUR_URL1 and YOUR_URL2"}
              ]
          }
      ],
      "tools": [
          {
              "url_context": {}
          }
      ]
  }' > result.json

cat result.json

Python

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

client = genai.Client()
model_id = "gemini-2.5-flash-preview-05-20"

tools = []
tools.append(Tool(url_context=types.UrlContext))
tools.append(Tool(google_search=types.GoogleSearch))

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,
        response_modalities=["TEXT"],
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)
# get URLs retrieved for context
print(response.candidates[0].url_context_metadata)

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash-preview-05-20",
    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();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-preview-05-20:generateContent?key=$GOOGLE_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

لمزيد من التفاصيل حول ميزة "الربط بموضوع البحث" في "بحث Google"، اطّلِع على صفحة نظرة عامة.

الردّ السياقي

سيستند ردّ النموذج إلى المحتوى الذي استرداده من عناوين URL. إذا استرجع النموذج محتوى من عناوين URL، سيتضمّن الردّ url_context_metadata. قد يبدو هذا الردّ مماثلاً لردّ مما يلي (تم حذف أجزاء من الردّ لتبسيطه):

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata":
      {
          "url_metadata":
          [
            {
              "retrieved_url": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/1234567890abcdef",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/abcdef1234567890",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "YOUR_URL",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/fedcba0987654321",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            }
          ]
        }
    }
}

النماذج المتوافقة

القيود

  • ستستهلك الأداة ما يصل إلى 20 عنوان URL لكل طلب تحليل.
  • للحصول على أفضل النتائج خلال المرحلة التجريبية، استخدِم الأداة على صفحات الويب العادية بدلاً من محتوى الوسائط المتعددة، مثل فيديوهات YouTube.
  • وخلال المرحلة التجريبية، يمكن استخدام الأداة مجانًا. ستتوفّر ميزة الفوترة لاحقًا.

  • يتضمّن الإصدار التجريبي الحصص التالية:

    • ‫1,500 طلب بحث في اليوم لكل مشروع للطلبات المقدَّمة من خلال Gemini API
    • ‫100 طلب بحث في اليوم لكل مستخدم في Google AI Studio