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

הכלי "הקשר של כתובת URL" מאפשר לכם לספק למודלים הקשר נוסף בצורה של כתובות URL. כשאתם כוללים כתובות URL בבקשה, המודל ניגש לתוכן מהדפים האלה (כל עוד זה לא סוג של כתובת URL שמפורט בקטע המגבלות) כדי לשפר את התשובה שלו.

הכלי 'הקשר של כתובת URL' שימושי למשימות כמו:

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

בדוגמה הבאה אפשר לראות איך משווים בין שני מתכונים משני אתרים שונים.

Python

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

client = genai.Client()
model_id = "gemini-3.8-flash"

tools = [
  {"url_context": {}},
]

url1 = "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"
url2 = "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"

response = client.models.generate_content(
    model=model_id,
    contents=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",
    config=GenerateContentConfig(
        tools=tools,
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)

# For verification, you can inspect the metadata to see which URLs the model retrieved
print(response.candidates[0].url_context_metadata)

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.8-flash",
    contents: [
        "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
    ],
    config: {
      tools: [{urlContext: {}}],
    },
  });
  console.log(response.text);

  // For verification, you can inspect the metadata to see which URLs the model retrieved
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "contents": [
          {
              "parts": [
                  {"text": "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"}
              ]
          }
      ],
      "tools": [
          {
              "url_context": {}
          }
      ]
  }' > result.json

cat result.json

איך זה עובד

הכלי 'הקשר כתובת ה-URL' משתמש בתהליך אחזור דו-שלבי כדי לאזן בין מהירות, עלות וגישה לנתונים עדכניים. כשמזינים כתובת URL, הכלי מנסה קודם לאחזר את התוכן מהמטמון לאינדקס הפנימי. הוא פועל כמטמון שעבר אופטימיזציה גבוהה. אם כתובת URL לא זמינה באינדקס (למשל, אם מדובר בדף חדש מאוד), הכלי יבצע באופן אוטומטי אחזור של הגרסה הפעילה. הפעולה הזו ניגשת ישירות לכתובת ה-URL כדי לאחזר את התוכן שלה בזמן אמת.

אפשר לשלב את הכלי להקשר של כתובת URL עם כלים אחרים כדי ליצור תהליכי עבודה יעילים יותר.

מודלים של Gemini 3 תומכים בשילוב של כלים מובנים (כמו URL Context) עם כלים בהתאמה אישית (קריאה להפעלת פונקציות). מידע נוסף זמין בדף שילובים של כלים.

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

Python

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

client = genai.Client()
model_id = "gemini-3.8-flash"

tools = [
      {"url_context": {}},
      {"google_search": {}}
  ]

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,
    )
)

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({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.8-flash",
    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-3.8-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_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

הבנת התשובה

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

זוהי דוגמה לחלק הזה של התשובה (השמטנו חלקים מהתשובה כדי שהיא תהיה קצרה יותר):

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata": {
        "url_metadata": [
          {
            "retrieved_url": "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592",
            "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
          },
          {
            "retrieved_url": "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
            "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
          }
        ]
      }
    }
  ]
}

לפרטים מלאים על האובייקט הזה , אפשר לעיין במאמרי העזרה של ה-API של UrlContextMetadata.

בדיקות בטיחות

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

כמות טוקנים

התוכן שנשלף מכתובות ה-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 Context
‫Gemini 4 Argon ✔️
Gemini 3.8 Flash ✔️
‫Gemini 3.6 Flash ✔️
‫Gemini 3.5 Flash-Lite ✔️
Gemini 3.1 Pro Preview ✔️
‫Gemini 3.1 Flash-Lite ✔️
Gemini 3 Flash Preview ✔️
‫Gemini 2.5 Pro ✔️
‫Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️

שיטות מומלצות

  • לספק כתובות URL ספציפיות: כדי לקבל את התוצאות הכי טובות, ספקו כתובות URL ישירות לתוכן שאתם רוצים שהמודל ינתח. המודל יאחזר תוכן רק מכתובות ה-URL שתספקו, ולא מקישורים מוטמעים.
  • בודקים את הנגישות: מוודאים שכתובות ה-URL שציינתם לא מובילות לדפים שנדרשת בהם כניסה או שמוגנים על ידי חומת תשלום.
  • משתמשים בכתובת ה-URL המלאה: צריך לציין את כתובת ה-URL המלאה, כולל הפרוטוקול (למשל, https://www.google.com במקום רק google.com).

מגבלות

  • מגבלת בקשות: הכלי יכול לעבד עד 20 כתובות URL לכל בקשה.
  • גודל התוכן של כתובת ה-URL: הגודל המקסימלי של תוכן שאוחזר מכתובת URL אחת הוא 34MB.
  • נגישות לכולם: כתובות ה-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 (בקטע הבנת סרטונים מוסבר איך לעבד כתובות URL של YouTube)
  • קבצים של Google Workspace, כמו מסמכים או גיליונות אלקטרוניים של Google
  • קובצי וידאו ואודיו

המאמרים הבאים