ההקשר של כתובת ה-URL

הכלי 'הקשר של כתובת URL' מאפשר לכם לספק למודל הקשר נוסף בצורה של כתובות URL. המודל יכול לגשת לתוכן מכתובות ה-URL האלה כדי לשפר את התשובה שלו.

היתרונות של הקשר של כתובת ה-URL:

  • שליפת נתונים: מספקים מידע ספציפי כמו מחירים, שמות או ממצאים מרכזיים ממאמר או מכמה כתובות URL.

  • השוואת מידע: ניתוח של כמה דוחות, מאמרים או קובצי PDF כדי לזהות הבדלים ולעקוב אחרי מגמות.

  • סינתזה ויצירת תוכן: אפשר לשלב מידע מכמה כתובות URL של מקורות כדי ליצור סיכומים מדויקים, פוסטים בבלוג, דוחות או שאלות למבחן.

  • ניתוח קוד ותוכן טכני: אפשר לספק כתובות URL למאגר GitHub או לתיעוד טכני כדי לקבל הסבר על קוד, ליצור הוראות הגדרה או לקבל תשובות לשאלות.

חשוב לעיין בשיטות המומלצות ובמגבלות כשמשתמשים בכלי להצגת הקשר של כתובת URL.

מודלים נתמכים

  • gemini-3-pro-preview
  • gemini-3-flash-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 אחת הוא 34MB.

  • עדכניות: הכלי לא מאחזר גרסאות פעילות של דפי אינטרנט, ולכן יכול להיות שיהיו בעיות בעדכניות או מידע לא עדכני.

  • כתובות 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) כתובות URL מסוג Cloud Storage
    הסוגים האלה של כתובות 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.