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

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

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

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

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

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

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

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

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

שימוש בהקשר של כתובת 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

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

אתם יכולים גם להפעיל את שתי התכונות, 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 Context וגם את Web Grounding for Enterprise. אינדקס האינטרנט שמשמש לעיגון ב-Web Grounding for 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 Context משתמש בתהליך דו-שלבי שנועד לאזן בין מהירות, עלות וגישה למידע העדכני ביותר:

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

  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.