سياق عنوان URL

تتيح لك أداة سياق عنوان URL تقديم سياق إضافي للنموذج في شكل عناوين URL. ويمكن للنموذج الوصول إلى المحتوى من عناوين URL هذه لتقديم ردّ محسّن ومستند إلى معلومات دقيقة.

تقدّم أداة سياق عنوان URL المزايا التالية:

  • استخراج البيانات: يمكنك تقديم معلومات محدّدة، مثل الأسعار أو الأسماء أو النتائج الرئيسية من مقالة أو عناوين URL متعدّدة.

  • مقارنة المعلومات: يمكنك تحليل تقارير أو مقالات أو ملفات PDF متعدّدة لتحديد الاختلافات وتتبُّع المؤشرات.

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

  • تحليل الرموز البرمجية والمحتوى الفني: يمكنك تقديم عناوين URL لمستودع GitHub أو مستندات فنية لشرح الرموز البرمجية أو إنشاء تعليمات الإعداد أو الإجابة عن الأسئلة.

يُرجى مراجعة أفضل الممارسات و القيود عند استخدام أداة سياق عنوان URL.

النماذج المتاحة

  • gemini-3.1-pro-preview
  • gemini-3-flash-preview
  • gemini-3.1-flash-lite-preview
  • gemini-2.5-pro
  • gemini-2.5-flash
  • gemini-2.5-flash-lite

اللغات المتاحة

يمكنك الاطّلاع على اللغات المتاحة لنماذج Gemini.

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

يمكنك استخدام أداة سياق عنوان URL بطريقتَين رئيسيتَين:

أداة سياق عنوان URL فقط

انقر على موفّر Gemini API لعرض المحتوى والرموز البرمجية الخاصة بالموفّر على هذه الصفحة.

عند إنشاء مثيل GenerativeModel، قدِّم UrlContext كأداة. بعد ذلك، قدِّم عناوين URL المحدّدة التي تريد أن يصل إليها النموذج ويحلّلها مباشرةً في طلبك.

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

Swift


import FirebaseAILogic

// Initialize the Gemini Developer API backend service
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Create a `GenerativeModel` instance with a model that supports your use case
let model = ai.generativeModel(
    modelName: "GEMINI_MODEL_NAME",
    // Enable the URL context tool.
    tools: [Tool.urlContext()]
)

// Specify one or more URLs for the tool to access.
let url1 = "FIRST_RECIPE_URL"
let url2 = "SECOND_RECIPE_URL"

// Provide the URLs in the prompt sent in the request.
let prompt = "Compare the ingredients and cooking times from the recipes at \(url1) and \(url2)"

// Get and handle the model's response.
let response = try await model.generateContent(prompt)
print(response.text ?? "No text in response.")

Kotlin


// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
val model = Firebase.ai(backend = GenerativeBackend.googleAI()).generativeModel(
    modelName = "GEMINI_MODEL_NAME",
    // Enable the URL context tool.
    tools = listOf(Tool.urlContext())
)

// Specify one or more URLs for the tool to access.
val url1 = "FIRST_RECIPE_URL"
val url2 = "SECOND_RECIPE_URL"

// Provide the URLs in the prompt sent in the request.
val prompt = "Compare the ingredients and cooking times from the recipes at $url1 and $url2"

// Get and handle the model's response.
val response = model.generateContent(prompt)
print(response.text)

Java


// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
                .generativeModel("GEMINI_MODEL_NAME",
                        null,
                        null,
                        // Enable the URL context tool.
                        List.of(Tool.urlContext(new UrlContext())));

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

// Specify one or more URLs for the tool to access.
String url1 = "FIRST_RECIPE_URL";
String url2 = "SECOND_RECIPE_URL";

// Provide the URLs in the prompt sent in the request.
String prompt = "Compare the ingredients and cooking times from the recipes at " + url1 + " and " + url2 + "";

ListenableFuture response = model.generateContent(prompt);
  Futures.addCallback(response, new FutureCallback() {
      @Override
      public void onSuccess(GenerateContentResponse result) {
          String resultText = result.getText();
          System.out.println(resultText);
      }

      @Override
      public void onFailure(Throwable t) {
          t.printStackTrace();
      }
  }, executor);

Web


import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance with a model that supports your use case
const model = getGenerativeModel(
  ai,
  {
    model: "GEMINI_MODEL_NAME",
    // Enable the URL context tool.
    tools: [{ urlContext: {} }]
  }
);

// Specify one or more URLs for the tool to access.
const url1 = "FIRST_RECIPE_URL"
const url2 = "SECOND_RECIPE_URL"

// Provide the URLs in the prompt sent in the request.
const prompt = `Compare the ingredients and cooking times from the recipes at ${url1} and ${url2}`

// Get and handle the model's response.
const result = await model.generateContent(prompt);
console.log(result.response.text());

Dart


import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_ai/firebase_ai.dart';
import 'firebase_options.dart';

// Initialize FirebaseApp
await Firebase.initializeApp(
  options: DefaultFirebaseOptions.currentPlatform,
);

// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
final model = FirebaseAI.googleAI().generativeModel(
  model: 'GEMINI_MODEL_NAME',
  // Enable the URL context tool.
  tools: [
    Tool.urlContext(),
  ],
);

// Specify one or more URLs for the tool to access.
final url1 = "FIRST_RECIPE_URL";
final url2 = "SECOND_RECIPE_URL";

// Provide the URLs in the prompt sent in the request.
final prompt = "Compare the ingredients and cooking times from the recipes at $url1 and $url2";

// Get and handle the model's response.
final response = await model.generateContent([Content.text(prompt)]);
print(response.text);

Unity


using Firebase;
using Firebase.AI;

// Initialize the Gemini Developer API backend service
var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// Create a `GenerativeModel` instance with a model that supports your use case
var model = ai.GetGenerativeModel(
  modelName: "GEMINI_MODEL_NAME",
  // Enable the URL context tool.
  tools: new[] { new Tool(new UrlContext()) }
);

// Specify one or more URLs for the tool to access.
var url1 = "FIRST_RECIPE_URL";
var url2 = "SECOND_RECIPE_URL";

// Provide the URLs in the prompt sent in the request.
var prompt = $"Compare the ingredients and cooking times from the recipes at {url1} and {url2}";

// Get and handle the model's response.
var response = await model.GenerateContentAsync(prompt);
UnityEngine.Debug.Log(response.Text ?? "No text in response.");

كيفية اختيار نموذج

انقر على موفّر Gemini API لعرض المحتوى والرموز البرمجية الخاصة بالموفّر على هذه الصفحة.

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

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

وفي ما يلي بعض حالات الاستخدام:

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

    مثال على طلب:
    Give me a three day event schedule based on YOUR_URL. Also what do I need to pack according to the weather?

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

    مثال على طلب:
    Recommend 3 beginner-level books to learn about the latest YOUR_SUBJECT.

يوضّح المثال التالي كيفية تفعيل كلتا الأداتَين واستخدامهما: سياق عنوان URL وتحديد المصدر من خلال "بحث Google":


import FirebaseAILogic

// Initialize the Gemini Developer API backend service
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Create a `GenerativeModel` instance with a model that supports your use case
let model = ai.generativeModel(
    modelName: "GEMINI_MODEL_NAME",
    // Enable both the URL context tool and Google Search tool.
    tools: [
      Tool.urlContex(),
      Tool.googleSearch()
    ]
)

// Specify one or more URLs for the tool to access.
let url = "YOUR_URL"

// Provide the URLs in the prompt sent in the request.
// If the model can't generate a response using its own knowledge or the content in the specified URL,
// then the model will use the grounding with Google Search tool.
let prompt = "Give me a three day event schedule based on \(url). Also what do I need to pack according to the weather?"

// Get and handle the model's response.
let response = try await model.generateContent(prompt)
print(response.text ?? "No text in response.")

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result


// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
val model = Firebase.ai(backend = GenerativeBackend.googleAI()).generativeModel(
    modelName = "GEMINI_MODEL_NAME",
    // Enable both the URL context tool and Google Search tool.
    tools = listOf(Tool.urlContext(), Tool.googleSearch())
)

// Specify one or more URLs for the tool to access.
val url = "YOUR_URL"

// Provide the URLs in the prompt sent in the request.
// If the model can't generate a response using its own knowledge or the content in the specified URL,
// then the model will use the grounding with Google Search tool.
val prompt = "Give me a three day event schedule based on $url. Also what do I need to pack according to the weather?"

// Get and handle the model's response.
val response = model.generateContent(prompt)
print(response.text)

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result


// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
                .generativeModel("GEMINI_MODEL_NAME",
                        null,
                        null,
                        // Enable both the URL context tool and Google Search tool.
                        List.of(Tool.urlContext(new UrlContext()), Tool.googleSearch(new GoogleSearch())));

// Use the GenerativeModelFutures Java compatibility layer which offers
// support for ListenableFuture and Publisher APIs
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

// Specify one or more URLs for the tool to access.
String url = "YOUR_URL";

// Provide the URLs in the prompt sent in the request.
// If the model can't generate a response using its own knowledge or the content in the specified URL,
// then the model will use the grounding with Google Search tool.
String prompt = "Give me a three day event schedule based on " + url + ". Also what do I need to pack according to the weather?";

ListenableFuture response = model.generateContent(prompt);
  Futures.addCallback(response, new FutureCallback() {
      @Override
      public void onSuccess(GenerateContentResponse result) {
          String resultText = result.getText();
          System.out.println(resultText);
      }

      @Override
      public void onFailure(Throwable t) {
          t.printStackTrace();
      }
  }, executor);

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result


import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance with a model that supports your use case
const model = getGenerativeModel(
  ai,
  {
    model: "GEMINI_MODEL_NAME",
    // Enable both the URL context tool and Google Search tool.
    tools: [{ urlContext: {} }, { googleSearch: {} }],
  }
);

// Specify one or more URLs for the tool to access.
const url = "YOUR_URL"

// Provide the URLs in the prompt sent in the request.
// If the model can't generate a response using its own knowledge or the content in the specified URL,
// then the model will use the grounding with Google Search tool.
const prompt = `Give me a three day event schedule based on ${url}. Also what do I need to pack according to the weather?`

// Get and handle the model's response.
const result = await model.generateContent(prompt);
console.log(result.response.text());

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result


import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_ai/firebase_ai.dart';
import 'firebase_options.dart';

// Initialize FirebaseApp
await Firebase.initializeApp(
  options: DefaultFirebaseOptions.currentPlatform,
);

// Initialize the Gemini Developer API backend service
// Create a `GenerativeModel` instance with a model that supports your use case
final model = FirebaseAI.googleAI().generativeModel(
  model: 'GEMINI_MODEL_NAME',
  // Enable both the URL context tool and Google Search tool.
  tools: [
    Tool.urlContext(),
    Tool.googleSearch(),
  ],
);

// Specify one or more URLs for the tool to access.
final url = "YOUR_URL";

// Provide the URLs in the prompt sent in the request.
// If the model can't generate a response using its own knowledge or the content in the specified URL,
// then the model will use the grounding with Google Search tool.
final prompt = "Give me a three day event schedule based on $url. Also what do I need to pack according to the weather?";

final response = await model.generateContent([Content.text(prompt)]);
print(response.text);

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result


using Firebase;
using Firebase.AI;

// Initialize the Gemini Developer API backend service
var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// Create a `GenerativeModel` instance with a model that supports your use case
var model = ai.GetGenerativeModel(
  modelName: "GEMINI_MODEL_NAME",
  // Enable both the URL context tool and Google Search tool.
  tools: new[] { new Tool(new GoogleSearch()), new Tool(new UrlContext()) }
);

// Specify one or more URLs for the tool to access.
var url = "YOUR_URL";

// Provide the URLs in the prompt sent in the request.
// If the model can't generate a response using its own knowledge or the content in the specified URL,
// then the model will use the grounding with Google Search tool.
var prompt = $"Give me a three day event schedule based on {url}. Also what do I need to pack according to the weather?";

// Get and handle the model's response.
var response = await model.GenerateContentAsync(prompt);
UnityEngine.Debug.Log(response.Text ?? "No text in response.");

// Make sure to comply with the "Grounding with Google Search" usage requirements,
// which includes how you use and display the grounded result

كيفية اختيار نموذج

طريقة عمل أداة سياق عنوان URL

تستخدم أداة سياق عنوان URL عملية استرداد من خطوتَين لتحقيق التوازن بين السرعة والتكلفة والوصول إلى البيانات الجديدة.

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

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

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

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

  • التحقّق من إمكانية الوصول: تأكَّد من أنّ عناوين URL التي تقدّمها لا تؤدي إلى صفحات تتطلّب تسجيل الدخول أو تكون محجوبة بمقابل مادي.

  • استخدام عنوان URL الكامل: قدِّم عنوان URL الكامل، بما في ذلك البروتوكول (على سبيل المثال، https://www.example.com بدلاً من example.com فقط).

فهم الردّ

سيستند ردّ النموذج إلى المحتوى الذي استردّه من عناوين URL.

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

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata":
      {
          "url_metadata":
          [
            {
              "retrieved_url": "https://www.example.com",
              "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
            },
            {
              "retrieved_url": "https://www.example.org",
              "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
            },
          ]
        }
    }
  ]
}

عمليات فحص الأمان

يُجري النظام فحصًا للإشراف على المحتوى على عنوان URL للتأكّد من استيفائه لمعايير الأمان. إذا لم يستوفِ عنوان URL الذي قدّمته هذا الفحص، سيظهر لك url_retrieval_status بقيمة URL_RETRIEVAL_STATUS_UNSAFE.

القيود

في ما يلي بعض القيود المفروضة على أداة سياق عنوان URL:

  • الدمج مع ميزة "طلب تنفيذ وظيفة": لا يمكن استخدام أداة سياق عنوان URL في طلب يستخدم أيضًا ميزة "طلب تنفيذ وظيفة".

  • الحدّ الأقصى لعناوين URL لكل طلب: الحدّ الأقصى لعدد عناوين URL لكل طلب هو 20 عنوان URL.

  • الحدّ الأقصى لحجم محتوى عنوان URL: الحدّ الأقصى لحجم المحتوى الذي يتم استرداده من عنوان URL واحد هو 34 ميغابايت.

  • الجدّة: لا تجلب الأداة الإصدارات المباشرة من صفحات الويب، لذا قد تحدث بعض المشاكل في الجدّة أو قد تكون المعلومات غير حديثة.

  • إمكانية الوصول إلى عنوان URL للجميع: يجب أن يكون الوصول إلى عناوين URL المقدَّمة متاحًا للجميع على الويب. لا تتوافق الأداة مع المحتوى المحجوب بمقابل مادي والمحتوى الذي يتطلّب تسجيل دخول المستخدم والشبكات الخاصة وعناوين localhost (مثل 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 (يمكنك بدلاً من ذلك الاطّلاع على تحليل الفيديوهات)

  • ملفات الفيديو والملفات الصوتية (يمكنك بدلاً من ذلك الاطّلاع على تحليل الفيديوهات أو تحليل الصوت)

  • ملفات Google Workspace، مثل "مستندات Google" أو جداول البيانات

  • (إذا كنت تستخدم Vertex AI Gemini API) Cloud Storage عناوين URL
    لا تتوافق هذه الأنواع من عناوين URL مع Gemini Developer API بغض النظر عن طريقة الوصول إليها.

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

التسعير ورموز الأدوات المميزة

يُحتسب المحتوى الذي يتم استرداده من عناوين 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 في مستندات موفّر Gemini API الذي اخترته: Gemini Developer API | Vertex AI Gemini API.