הכלי 'הוספת הקשר לכתובת 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-2.5-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-2.5-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-2.5-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 עם כלים אחרים כדי ליצור תהליכי עבודה יעילים יותר.
עיגון בנתונים באמצעות חיפוש
אם מפעילים גם את ההגדרה 'הקשר של כתובת ה-URL' וגם את ההגדרה הצגת תוצאות מחיפוש Google, המודל יכול להשתמש ביכולות החיפוש שלו כדי למצוא מידע רלוונטי באינטרנט, ואז להשתמש בכלי 'הקשר של כתובת ה-URL' כדי לקבל הבנה מעמיקה יותר של הדפים שהוא מוצא. הגישה הזו יעילה במיוחד להנחיות שדורשות חיפוש רחב וניתוח מעמיק של דפים ספציפיים.
Python
from google import genai
from google.genai.types import Tool, GenerateContentConfig, GoogleSearch, UrlContext
client = genai.Client()
model_id = "gemini-2.5-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-2.5-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-2.5-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"
}
]
}
}
}
לפרטים מלאים על האובייקט הזה , אפשר לעיין בUrlContextMetadata
API reference.
בדיקות בטיחות
המערכת מבצעת בדיקה של ניהול תוכן בכתובת ה-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
}
המחיר לכל טוקן תלוי במודל שבו משתמשים. פרטים נוספים זמינים בדף התמחור.
מודלים נתמכים
- gemini-2.5-pro
- gemini-2.5-flash
- gemini-2.5-flash-lite
- gemini-live-2.5-flash-preview
- gemini-2.0-flash-live-001
שיטות מומלצות
- מספקים כתובות URL ספציפיות: כדי לקבל את התוצאות הטובות ביותר, כדאי לספק כתובות URL ישירות לתוכן שרוצים שהמודל ינתח. המודל יאחזר תוכן רק מכתובות ה-URL שתספקו, ולא מקישורים מוטמעים.
- בודקים את הנגישות: מוודאים שכתובות ה-URL שציינתם לא מובילות לדפים שנדרשת בהם התחברות או שהם נמצאים מאחורי חומת תשלום.
- שימוש בכתובת ה-URL המלאה: צריך לציין את כתובת ה-URL המלאה, כולל הפרוטוקול (למשל, https://www.google.com ולא רק google.com).
מגבלות
- תמחור: תוכן שאוחזר מכתובות URL נספר כאסימוני קלט. מגבלת הקצב והתמחור מבוססים על המודל שבו נעשה שימוש. פרטים נוספים זמינים בדפים מגבלות קצב ותמחור.
- מגבלת בקשות: הכלי יכול לעבד עד 20 כתובות URL לכל בקשה.
- גודל התוכן של כתובת URL: הגודל המקסימלי של תוכן שאוחזר מכתובת URL יחידה הוא 34MB.
סוגי תוכן נתמכים ולא נתמכים
הכלי יכול לחלץ תוכן מכתובות 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
- קובצי וידאו ואודיו
המאמרים הבאים
- אפשר לעיין בספר המתכונים של הקשר כתובת ה-URL כדי לראות דוגמאות נוספות.