אתם יכולים להשתמש בכלי "הקשר של כתובת URL" כדי לספק ל-Gemini כתובות URL כהקשר נוסף להנחיה שלכם. המודל יכול לאחזר תוכן מכתובות ה-URL ולהשתמש בתוכן הזה כדי להעשיר את התשובה שלו ולעצב אותה.
הכלי הזה שימושי למשימות כמו:
- חילוץ נקודות נתונים או נקודות לדיון ממאמרים
- השוואת מידע מכמה קישורים
- סינתזה של נתונים מכמה מקורות
- לענות על שאלות על סמך התוכן של דף או דפים ספציפיים
- ניתוח תוכן למטרות ספציפיות (כמו כתיבת תיאור משרה או יצירת שאלות למבחן)
חשוב לדעת שהאינדקס שמשמש לשליפת הנתונים לא בהכרח עדכני, ולכן יכול להיות שחלק מהמידע יהיה מיושן.
במדריך הזה מוסבר איך להשתמש בכלי "הקשר של כתובת URL" ב-Gemini API.
מודלים נתמכים
המודלים הבאים תומכים ב-URL Context:
לחצו כדי להרחיב את רשימת המודלים הנתמכים
- Gemini Robotics ER 2
- Gemini 4 Hydrogen
- Gemini 4 Carbon לסייבר
- Gemini 4 Carbon
- Gemini 4 Argon Cyber Permissive
- Gemini 4 Argon
- Gemini 3.8 Flash
- Gemini 3.7 Flash
- Gemini 3.6 Flash
- Gemini 3.5 Flash-Lite
- Gemini 3.5 Flash
- Gemini 3.1 Pro
- Gemini 3.1 Flash-Lite
- Gemini 3 Flash
- Gemini 2.5 Pro
- Gemini 2.5 Flash-Lite
- Gemini 2.5 Flash
שימוש בהקשר של כתובת URL
יש שתי דרכים עיקריות להשתמש בכלי URL Context: בפני עצמו או בשילוב עם עיגון באמצעות חיפוש Google.
רק הקשר של כתובת URL
אתם יכולים לציין בהנחיה כתובות URL ספציפיות שאתם רוצים שהמודל ינתח ישירות:
Summarize this document: YOUR_URLs
Extract the key features from the product description on this page: YOUR_URLs
Python
GenerateContent API
from google import genai from google.genai.types import Tool, GenerateContentConfig, HttpOptions, UrlContext client = genai.Client(http_options=HttpOptions(api_version="v1")) model_id = "gemini-3.5-flash" url_context_tool = Tool( url_context = UrlContext ) response = client.models.generate_content( model=model_id, contents="Compare recipes from YOUR_URL1 and YOUR_URL2", config=GenerateContentConfig( tools=[url_context_tool], response_modalities=["TEXT"], ) ) for each in response.candidates[0].content.parts: print(each.text) # get URLs retrieved for context print(response.candidates[0].url_context_metadata)
Interactions API
from google import genai client = genai.Client( enterprise=True, project="GOOGLE_CLOUD_PROJECT", location="global", ) interaction = client.interactions.create( model="gemini-3.8-flash", input="Compare recipes from YOUR_URL1 and YOUR_URL2", tools=[{"type": "url_context"}], ) print(interaction.output_text) # Get URLs retrieved for context for step in interaction.steps: if step.type == "url_context_result": for res in step.result: print(f"URL: {res.url} (Status: {res.status})")
JavaScript
GenerateContent API
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ vertexai: true, project: process.env.GOOGLE_CLOUD_PROJECT, location: process.env.GOOGLE_CLOUD_LOCATION, apiVersion: 'v1', }); async function main() { const response = await ai.models.generateContent({ model: "gemini-3.5-flash", contents: [ "Compare recipes from YOUR_URL1 and YOUR_URL2", ], config: { tools: [{urlContext: {}}], }, }); console.log(response.text); // To get URLs retrieved for context console.log(response.candidates[0].urlContextMetadata) } await main();
Interactions API
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ enterprise: true, project: process.env.GOOGLE_CLOUD_PROJECT, location: process.env.GOOGLE_CLOUD_LOCATION, }); async function main() { const interaction = await ai.interactions.create({ model: "gemini-3.8-flash", input: "Compare recipes from YOUR_URL1 and YOUR_URL2", tools: [{ type: "url_context" }], }); console.log(interaction.output_text); for (const step of interaction.steps) { if (step.type === "url_context_result") { console.log(step.result); } } } await main();
REST
GenerateContent API
לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:
- GOOGLE_CLOUD_PROJECT: מזהה הפרויקט.
- YOUR_URL1: כתובת ה-URL הראשונה שממנה מאחזרים את ההקשר.
- YOUR_URL2: כתובת ה-URL השנייה שממנה מאחזרים את ההקשר.
ה-method של ה-HTTP וכתובת ה-URL:
POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent
גוף בקשת JSON:
{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Compare recipes from YOUR_URL1 and YOUR_URL2"
}
]
}
],
"tools": [
{
"url_context": {}
}
]
}
כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:
curl
שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent"
PowerShell
שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent" | Select-Object -Expand Content
Interactions API
לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:
- GOOGLE_CLOUD_PROJECT: מזהה הפרויקט.
- YOUR_URL1: כתובת ה-URL הראשונה שממנה מאחזרים את ההקשר.
- YOUR_URL2: כתובת ה-URL השנייה שממנה מאחזרים את ההקשר.
ה-method של ה-HTTP וכתובת ה-URL:
POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions
גוף בקשת JSON:
{
"model": "gemini-3.8-flash",
"input": [
{
"type": "user_input",
"content": [
{
"type": "text",
"text": "Compare recipes from YOUR_URL1 and YOUR_URL2"
}
]
}
],
"tools": [
{
"type": "url_context"
}
]
}
כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:
curl
שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions"
PowerShell
שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions" | Select-Object -Expand Content
עיגון באמצעות חיפוש Google עם הקשר של כתובת URL
אתם יכולים גם להפעיל את URL Context וגם את "עיגון באמצעות חיפוש Google", ולהשתמש בהנחיות עם או בלי כתובות URL. המודל יכול קודם לחפש מידע רלוונטי ואז להשתמש בכלי URL Context כדי לקרוא את התוכן של תוצאות החיפוש ולהבין אותו לעומק.
התכונה הזו היא ניסיונית וזמינה ב-API בגרסה v1beta1.
פרומפטים לדוגמה:
Give me a three day event schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.
Recommend 3 books for beginners to read to learn more about the latest YOUR_SUBJECT.
Python
GenerateContent API
from google import genai from google.genai.types import Tool, GenerateContentConfig, HttpOptions, UrlContext, GoogleSearch client = genai.Client(http_options=HttpOptions(api_version="v1beta1")) model_id = "gemini-3.5-flash" tools = [] tools.append(Tool(url_context=UrlContext)) tools.append(Tool(google_search=GoogleSearch)) 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, response_modalities=["TEXT"], ) ) for each in response.candidates[0].content.parts: print(each.text) # get URLs retrieved for context print(response.candidates[0].url_context_metadata)
Interactions API
from google import genai client = genai.Client( enterprise=True, project="GOOGLE_CLOUD_PROJECT", location="global", ) interaction = client.interactions.create( model="gemini-3.8-flash", input="Give me a three day event schedule based on YOUR_URL. Also let me know what needs to be taken care of considering weather and commute.", tools=[ {"type": "url_context"}, {"type": "google_search"}, ], ) print(interaction.output_text) # Get URLs retrieved for context for step in interaction.steps: if step.type == "url_context_result": for res in step.result: print(f"URL: {res.url} (Status: {res.status})")
JavaScript
GenerateContent API
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ vertexai: true, project: process.env.GOOGLE_CLOUD_PROJECT, location: process.env.GOOGLE_CLOUD_LOCATION, apiVersion: 'v1beta1', }); async function main() { const response = await ai.models.generateContent({ model: "gemini-3.5-flash", contents: [ "Give me a three day event 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();
Interactions API
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ enterprise: true, project: process.env.GOOGLE_CLOUD_PROJECT, location: process.env.GOOGLE_CLOUD_LOCATION, }); async function main() { const interaction = await ai.interactions.create({ model: "gemini-3.8-flash", input: "Give me a three day event schedule based on YOUR_URL. Also let me know what needs to be taken care of considering weather and commute.", tools: [ { type: "url_context" }, { type: "google_search" }, ], }); console.log(interaction.output_text); for (const step of interaction.steps) { if (step.type === "url_context_result") { console.log(step.result); } } } await main();
REST
GenerateContent API
לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:
- GOOGLE_CLOUD_PROJECT: מזהה הפרויקט.
- YOUR_URL: כתובת ה-URL שממנה מאחזרים את ההקשר.
ה-method של ה-HTTP וכתובת ה-URL:
POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent
גוף בקשת JSON:
{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Give me a three day event schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute."
}
]
}
],
"tools": [
{
"url_context": {}
},
{
"google_search": {}
}
]
}
כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:
curl
שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent"
PowerShell
שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent" | Select-Object -Expand Content
Interactions API
לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:
- GOOGLE_CLOUD_PROJECT: מזהה הפרויקט.
- YOUR_URL: כתובת ה-URL שממנה מאחזרים את ההקשר.
ה-method של ה-HTTP וכתובת ה-URL:
POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions
גוף בקשת JSON:
{
"model": "gemini-3.8-flash",
"input": [
{
"type": "user_input",
"content": [
{
"type": "text",
"text": "Give me a three day event schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute."
}
]
}
],
"tools": [
{
"type": "url_context"
},
{
"type": "google_search"
}
]
}
כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:
curl
שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions"
PowerShell
שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions" | Select-Object -Expand Content
מידע נוסף על עיגון באמצעות חיפוש Google זמין בדף סקירה כללית.
עיגון בנתונים מהאינטרנט לארגונים עם הקשר של כתובת URL
אם יש לכם צרכים ספציפיים של תאימות או שאתם פועלים בתחום מפוקח כמו בריאות, פיננסים או המגזר הציבורי, אתם יכולים להפעיל גם את URL Context וגם את Web Grounding for Enterprise. אינדקס האינטרנט שמשמש לעיגון ב-Web Grounding for Enterprise מוגבל יותר מאינדקס החיפוש הרגיל של "עיגון באמצעות חיפוש Google", כי הוא משתמש בקבוצת משנה של מה שזמין בחיפוש Google.
למידע נוסף על Web Grounding for Enterprise, קראו את המאמר Web Grounding for Enterprise.
תשובה לפי ההקשר
התשובה של המודל מבוססת על התוכן שהוא אחזר מכתובות ה-URL. אם המודל אחזר תוכן מכתובות URL, התשובה תכלול את url_context_metadata. התגובה עשויה להיראות כך (חלקים מהתגובה הושמטו כדי לקצר):
{
"candidates": [
{
"content": {
"parts": [
{
"text": "... \n"
}
],
"role": "model"
},
...
"url_context_metadata":
{
"url_metadata":
[
{
"retrieved_url": "https://cloud.google.com/gemini-enterprise-agent-platform/models/capabilities/code-execution",
"url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
},
{
"retrieved_url": "https://cloud.google.com/gemini-enterprise-agent-platform/models/grounding/grounding-with-google-search",
"url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
},
]
}
}
]
}
למידע נוסף על האובייקט הזה, קראו את מאמרי העזרה של ה-API של UrlContextMetadata.
אחזור בזמן אמת
הכלי "הקשר של כתובת URL" מאחזר גרסאות פעילות של דפי אינטרנט כדי שהמידע יהיה עדכני.
כדי לאחזר ביעילות תוכן של דפי אינטרנט, הכלי URL Context משתמש בתהליך דו-שלבי שנועד לאזן בין מהירות, עלות וגישה למידע העדכני ביותר:
אחזור תוכן שנוסף לאינדקס: זה השלב הראשון. כשמזינים כתובת URL, הכלי מנסה קודם לאחזר את התוכן מאינדקס האינטרנט הנרחב והמשופר של Google. השיטה הזו מאפשרת גישה מהירה לאוסף עצום של דפי אינטרנט שנסרקו.
אחזור חלופי בזמן אמת: זהו השלב השני. אם התוכן של כתובת URL מסוימת לא זמין באינדקס (לדוגמה, אם הדף חדש מאוד ועדיין לא נוסף לאינדקס), הכלי מבצע באופן אוטומטי אחזור של הדף הפעיל. מנגנון הגיבוי הזה יכול לגשת ישירות לכתובת ה-URL ולאחזר את הגרסה העדכנית של התוכן בזמן אמת.
בדיקות אבטחה
המערכת מבצעת בדיקת ניהול תוכן בכתובת ה-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
}
המחיר לכל אסימון תלוי במודל שבו אתם משתמשים. עלות הפיתוח והפריסה של מודלים של AI ב-Gemini Enterprise Agent Platform
סוגי תוכן נתמכים ולא נתמכים
הכלי "הקשר של כתובת URL" יכול לחלץ תוכן מכתובות URL עם סוגי התוכן הבאים:
| תוכן | סוג |
|---|---|
| טקסט | text/htmlapplication/jsontext/plaintext/xmltext/csstext/javascripttext/csvtext/rtf |
| תמונה | image/pngimage/jpegimage/bmpimage/webp |
application/pdf |
הכלי "הקשר של כתובת URL" לא תומך בסוגי התוכן הבאים:
- תוכן שזמין רק לאחר תשלום
- סרטונים ב-YouTube (מידע נוסף זמין במאמר הבנת סרטונים)
- קבצים של Google Workspace, כמו Google Docs או Google Sheets
- קובצי וידאו ואודיו
מגבלות
- הכלי "הקשר של כתובת URL" מנתח עד 20 כתובות URL בכל בקשה.
- כדי לקבל את התוצאות הטובות ביותר בשלב הניסוי, מומלץ להשתמש בכלי בדפי אינטרנט רגילים ולא בתוכן מולטימדיה כמו סרטונים ב-YouTube.