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

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

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

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

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

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

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

המודלים הבאים תומכים בהקשר של כתובת URL:

שימוש בהקשר של כתובת 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-2.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_VERTEXAI=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-2.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-2.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' ו'הארקה באמצעות חיפוש Google' באמצעות הנחיות עם או בלי כתובות URL. יכול להיות שהמודל יחפש קודם מידע רלוונטי ואז ישתמש בכלי 'הוספת הקשר לכתובת URL' כדי לקרוא את התוכן של תוצאות החיפוש ולהבין אותו לעומק.

התכונה הזו היא ניסיונית וזמינה בגרסת 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-2.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_VERTEXAI=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-2.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-2.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 זמינים בדף סקירה כללית.

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

אתם יכולים להפעיל גם את ההקשר של כתובת ה-URL וגם את ההצמדה לאינטרנט ב-Enterprise אם יש לכם צרכים ספציפיים של תאימות או אם אתם פועלים בתעשייה מפוקחת כמו בריאות, פיננסים או המגזר הציבורי. האינדקס של האינטרנט שמשמש לעיגון נתונים באינטרנט ב-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/vertex-ai/generative-ai/docs/multimodal/code-execution",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "https://cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-search",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
          ]
        }
    }
  ]
}

מידע נוסף על האובייקט הזה מופיע במאמר UrlContextMetadata הפניית API.

אחזור בזמן אמת

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

כדי לאחזר ביעילות את התוכן של דף אינטרנט, הכלי 'הקשר של כתובת URL' משתמש בתהליך דו-שלבי שנועד לאזן בין מהירות, עלות וגישה למידע העדכני ביותר:

  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 ב-Vertex AI.

סוגי תוכן נתמכים ולא נתמכים

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