سياق عنوان URL

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

يوفّر سياق عناوين URL المزايا التالية:

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

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

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

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

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

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

  • gemini-4-argon
  • ‫gemini-3.8-flash (والإصدارات الأقدم gemini-3.7-flash وgemini-3.6-flash وgemini-3.5-flash)
  • ‫gemini-3.5-flash-lite (والإصدار الأقدم gemini-3.1-flash-lite)

يتيح أيضًا نموذج gemini-3.1-pro-preview ونموذج Gemini 2.5 للاستخدام العام (اللذان تم إيقافهما نهائيًا) هذه الإمكانية.

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

يمكنك الاطّلاع على اللغات المتاحة لنماذج 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: [.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 Search. باستخدام هذه الإعدادات، يمكنك كتابة طلبات مع عناوين URL محدّدة أو بدونها.

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

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

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

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

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

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

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


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: [
      .urlContext(),
      .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 لكل طلب: الحد الأقصى لعدد عناوين URL لكل طلب هو 20 عنوانًا.

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

  • حداثة المحتوى: لا تجلب الأداة النُسخ المباشرة من صفحات الويب، لذا قد تظهر بعض المشاكل في حداثة المحتوى أو قد تكون المعلومات قديمة.

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

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

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

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

  • المحتوى غير المتاح للجميع لا يتوافق ما يلي: المحتوى المدفوع، والمحتوى الذي يتطلب تسجيل دخول المستخدم، والشبكات الخاصة، وعناوين المضيف المحلي (مثل 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 | Agent Platform Gemini API (formerly Vertex AI).