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

הכלי 'הוספת הקשר באמצעות כתובת URL' מאפשר לספק למודלים הקשר נוסף בצורה של כתובות URL. כשמצרפים כתובות URL לבקשה, המודל ניגש לתוכן מהדפים האלה (כל עוד כתובת ה-URL לא שייכת לסוג שמופיע בקטע המגבלות) כדי לשפר את התשובה שלו.

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

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

בדוגמה הבאה אפשר לראות איך משווים בין שני מתכונים מאתרים שונים.

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

url1 = "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"
url2 = "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",
    tools=[{"type": "url_context"}]
)

# Print the model's text response and its source annotations
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "url_citation":
                            print(f"  - {annotation.title}: {annotation.url}")

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "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: [{ type: "url_context" }]
  });

  // Print the model's text response and its source annotations
  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'url_citation') {
                console.log(`  - ${annotation.title}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

await main();

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    url1 := "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"
    url2 := "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(
                fmt.Sprintf("Compare the ingredients and cooking times from the recipes at %s and %s", url1, url2),
            ),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.URLContext{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // Print the model's text response and its source annotations
    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                    if len(contentBlock.TextContent.Annotations) > 0 {
                        fmt.Println("\nSources:")
                        for _, annotation := range contentBlock.TextContent.Annotations {
                            if annotation.URLCitation != nil {
                                fmt.Printf("  - %s: %s\n", annotation.URLCitation.GetTitle(), annotation.URLCitation.GetURL())
                            }
                        }
                    }
                }
            }
        }
    }
}

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "model": "gemini-3.8-flash",
      "input": "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": [{"type": "url_context"}]
  }'

איך זה עובד

הכלי 'URL Context' משתמש בתהליך אחזור דו-שלבי כדי לאזן בין מהירות, עלות וגישה לנתונים עדכניים. כשמספקים כתובת URL, הכלי מנסה קודם לאחזר את התוכן ממטמון אינדקס פנימי. הוא פועל כמטמון שעבר אופטימיזציה גבוהה. אם כתובת URL לא זמינה באינדקס (למשל, אם מדובר בדף חדש מאוד), הכלי יבצע אוטומטית אחזור של הגרסה הפעילה. הכלי ניגש ישירות לכתובת ה-URL כדי לאחזר את התוכן שלה בזמן אמת.

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

מודלים של Gemini 3 תומכים בשילוב של כלים מובנים (כמו URL Context) עם כלים בהתאמה אישית (הפעלת פונקציות). מידע נוסף זמין בדף שילובים של כלים.

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

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="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=[
        {"type": "url_context"},
        {"type": "google_search"}
    ]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.8-flash",
    input: "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: [
      { type: "url_context" },
      { type: "google_search" }
    ]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') console.log(contentBlock.text);
      }
    }
  }
}

await main();

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("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: []interactions.Tool{
                interactions.NewTool(interactions.URLContext{}),
                interactions.NewTool(interactions.GoogleSearch{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                }
            }
        }
    }
}

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "model": "gemini-3.8-flash",
      "input": "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": [
          {"type": "url_context"},
          {"type": "google_search"}
      ]
  }'

הסבר על התשובה

כשהמודל משתמש בכלי להקשר של כתובת URL, תשובת הטקסט שלו כוללת הערות מוטבעות url_citation בבלוק התוכן של הטקסט. כל הערה מקשרת קטע של טקסט התשובה (באמצעות start_index ו-end_index) לכתובת ה-URL של המקור שממנו הוא נלקח. זו הדרך העיקרית להצגת ציטוטים באפליקציה שלכם. בדוגמה הראשית שלמעלה מוסבר איך לחלץ אותם.

התשובה כוללת גם שלב url_context_result עם מטא-נתונים על כל ניסיון לאחזור כתובת URL (סטטוס, כתובת URL שאוחזרה). האפשרות הזו שימושית בעיקר לניפוי באגים.

בדיקות בטיחות

המערכת מבצעת בדיקה של ניהול תוכן בכתובות URL כדי לוודא שהן עומדות בתקני הבטיחות. אם כתובת URL נכשלת בבדיקה הזו, בשלב url_context_result המתאים יופיע status עם הערך "unsafe".

כמות טוקנים

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

'usage': {
  'output_tokens': 45,
  'input_tokens': 27,
  'input_tokens_details': [{'modality': 'TEXT', 'token_count': 27}],
  'thoughts_tokens': 31,
  'tool_use_input_tokens': 10309,
  'tool_use_input_tokens_details': [{'modality': 'TEXT', 'token_count': 10309}],
  'total_tokens': 10412
}

המחיר לטוקן תלוי במודל שבו משתמשים. פרטים נוספים זמינים בדף התמחור.

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

מודל URL Context
‫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 Preview ✔️
‫Gemini 3.1 Flash-Lite ✔️
תצוגה מקדימה של Gemini 3 Flash ✔️
‫Gemini 2.5 Pro ✔️
‫Gemini 2.5 Flash ✔️
‫Gemini 2.5 Flash-Lite ✔️

שיטות מומלצות

  • צריך לספק כתובות URL ספציפיות: כדי לקבל את התוצאות הטובות ביותר, צריך לספק כתובות URL ישירות לתוכן שרוצים שהמודל ינתח. המודל יאחזר תוכן רק מכתובות ה-URL שתספקו, ולא מקישורים מוטמעים.
  • בודקים את הנגישות: מוודאים שכתובות ה-URL שציינתם לא מובילות לדפים שנדרשת בהם כניסה או שמוגנים על ידי חומת תשלום.
  • שימוש בכתובת ה-URL המלאה: צריך לציין את כתובת ה-URL המלאה, כולל הפרוטוקול (לדוגמה, https://www.google.com ולא רק google.com).

מגבלות

  • מגבלת בקשות: הכלי יכול לעבד עד 20 כתובות URL לכל בקשה.
  • גודל התוכן של כתובת URL: הגודל המקסימלי של תוכן שאוחזר מכתובת URL יחידה הוא 34MB.
  • נגישות לכולם: כתובות ה-URL צריכות להיות נגישות לכולם באינטרנט. אין תמיכה בכתובות localhost (לדוגמה, localhost,‏ 127.0.0.1), ברשתות פרטיות ובשירותי מנהור (לדוגמה, ngrok,‏ pinggy).

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

הכלי יכול לחלץ תוכן מכתובות 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
  • קובצי וידאו ואודיו