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

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

הכלי הזה שימושי למשימות כמו:

  • שליפת נקודות נתונים חשובות או נקודות לדיון ממאמרים
  • השוואת מידע מכמה קישורים
  • סינתזה של נתונים מכמה מקורות
  • מענה על שאלות על סמך התוכן של דף או דפים ספציפיים
  • ניתוח תוכן למטרות ספציפיות (כמו כתיבת תיאור משרה או יצירת שאלות למבחן)

חשוב לדעת שהאינדקס שמשמש לשליפת נתונים לא תמיד מעודכן, ולכן יכול להיות שחלק מהמידע לא יהיה עדכני.

במדריך הזה מוסבר איך להשתמש בכלי להוספת הקשר מכתובת URL ב-Gemini API.

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

המודלים הבאים תומכים ב-URL Context:

כדי להרחיב את רשימת המודלים הנתמכים, לוחצים כאן

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

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

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

אתם יכולים לציין כתובות URL ספציפיות שאתם רוצים שהמודל ינתח ישירות בהנחיה:

Summarize this document: YOUR_URLs

Extract the key features from the product description on this page: YOUR_URLs

Python

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)

JavaScript

# 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();

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent \
  -d '{
      "contents": [
          {
              "role": "user",
              "parts": [
                  {"text": "Compare recipes from YOUR_URL1 and YOUR_URL2"}
              ]
          }
      ],
      "tools": [
          {
              "url_context": {}
          }
      ]
  }' > result.json

cat result.json

עיגון באמצעות חיפוש Google עם URL Context

אתם יכולים גם להפעיל את שתי התכונות, 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

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)

JavaScript

# 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();

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent \
  -d '{
      "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": {}
          }
      ]
  }' > result.json

cat result.json

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

עיגון בנתונים מהאינטרנט לארגונים עם הקשר של כתובת URL

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

פרטים נוספים על עיגון בנתונים מהאינטרנט זמינים בדף עיגון בנתונים מהאינטרנט.

תשובה בהקשר

התשובה של המודל מבוססת על התוכן שהוא אחזר מכתובות ה-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' משתמש בתהליך דו-שלבי שנועד לאזן בין מהירות, עלות וגישה למידע העדכני ביותר:

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

  2. מעבר למדיה חלופית בטעינה בזמן אמת: זה השלב השני. אם התוכן של כתובת 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/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

כלי ההקשר של כתובת ה-URL לא תומך בסוגי התוכן הבאים:

  • תוכן שזמין רק לאחר תשלום
  • סרטונים ב-YouTube (מידע נוסף זמין במאמר הבנת סרטונים)
  • קבצים של Google Workspace, כמו Google Docs או Google Sheets
  • קובצי וידאו ואודיו

מגבלות

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