تتيح لك أداة "سياق عنوان URL" تقديم سياق إضافي للنموذج في شكل عناوين URL، ويمكن للنموذج الوصول إلى المحتوى من عناوين URL هذه للاستناد إليه وتحسين رده.
تقدّم ميزة "سياق عنوان URL" المزايا التالية:
استخراج البيانات: قدِّم معلومات محدّدة، مثل الأسعار أو الأسماء أو النتائج الرئيسية من مقالة أو عناوين URL متعددة.
مقارنة المعلومات: يمكنك تحليل تقارير أو مقالات أو ملفات PDF متعددة لتحديد الاختلافات وتتبُّع المؤشرات.
تجميع المحتوى وإنشاؤه: يمكنك الجمع بين المعلومات من عدة عناوين URL مصدر لإنشاء ملخّصات أو مشاركات في مدوّنة أو تقارير أو أسئلة اختبار دقيقة.
تحليل الرموز البرمجية والمحتوى الفني: يمكنك تقديم عناوين URL لمستودع GitHub أو مستندات فنية لشرح الرموز البرمجية أو إنشاء تعليمات الإعداد أو الإجابة عن الأسئلة.
احرص على مراجعة أفضل الممارسات والقيود عند استخدام أداة "السياق حسب عنوان URL".
النماذج المتوافقة
gemini-3-pro-previewgemini-3-flash-previewgemini-2.5-progemini-2.5-flashgemini-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.");
تعرَّف على كيفية اختيار نموذج اختياري مناسبَين لحالة الاستخدام والتطبيق.
سياق عنوان URL مع تحديد المصادر باستخدام "بحث Google"
|
انقر على موفّر Gemini API لعرض المحتوى والرمز الخاصين بالموفّر على هذه الصفحة. |
يمكنك تفعيل كلّ من ميزة "السياق المستند إلى عنوان URL" والاستناد إلى "بحث Google". باستخدام هذا الإعداد، يمكنك كتابة طلبات تتضمّن عناوين URL محدّدة أو لا تتضمّنها.
عند تفعيل ميزة تحديد المصدر مع "بحث Google" أيضًا، قد يستخدم النموذج أولاً<0x0A>محرّك بحث Google للعثور على معلومات ذات صلة، ثم يستخدم أداة سياق عنوان URL<0x0A>لقراءة محتوى نتائج البحث من أجل فهم المعلومات بشكل أكثر<0x0A>تعمّقًا. هذا الأسلوب فعّال مع الطلبات التي تتطلّب بحثًا واسع النطاق وتحليلاً معمّقًا لصفحات معيّنة.
في ما يلي بعض حالات الاستخدام:
يمكنك تقديم عنوان 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":
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 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
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 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
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 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
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 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
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 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
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 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أو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) عناوين URL من النوع Cloud Storage
لا تتوافق هذه الأنواع من عناوين URL مع Gemini Developer API بغض النظر عن طريقة الوصول إليها.المحتوى الذي لا يمكن الوصول إليه بشكل علني لا تتوافق مع هذه الميزة الحالات التالية: المحتوى المحمي بنظام حظر الاشتراك غير المدفوع، والمحتوى الذي يتطلّب تسجيل دخول المستخدم، والشبكات الخاصة، وعناوين المضيف المحلي (مثل
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.