URL-Kontext

Mit dem Tool für URL-Kontext können Sie Gemini URLs als zusätzlichen Kontext für Ihren Prompt zur Verfügung stellen. Das Modell kann dann Inhalte aus den URLs abrufen und diese Inhalte verwenden, um seine Antwort zu gestalten.

Dieses Tool ist für Aufgaben wie die folgenden nützlich:

Wichtige Datenpunkte oder Diskussionspunkte aus Artikeln extrahieren
Informationen aus mehreren Links vergleichen
Daten aus verschiedenen Quellen zusammenführen
Fragen basierend auf dem Inhalt einer bestimmten Seite oder mehrerer Seiten beantworten
Inhalte für bestimmte Zwecke analysieren (z. B. eine Stellenbeschreibung verfassen oder Testfragen erstellen)

Beachten Sie, dass der zum Abrufen von Daten verwendete Index möglicherweise nicht auf dem neuesten Stand ist. Einige Informationen sind daher möglicherweise veraltet.

In dieser Anleitung wird beschrieben, wie Sie das Tool für URL-Kontext in der Gemini API in Vertex AI verwenden.

Unterstützte Modelle

Die folgenden Modelle unterstützen URL-Kontext:

URL-Kontext verwenden

Sie können das Tool für URL-Kontext auf zwei Arten verwenden: allein oder in Verbindung mit der Fundierung mit der Google Suche.

Nur URL-Kontext

Sie können in Ihrem Prompt bestimmte URLs angeben, die das Modell analysieren soll:

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

Fundierung mit der Google Suche mit URL-Kontext

Sie können auch sowohl URL-Kontext als auch Fundierung mit der Google Suche aktivieren und Prompts mit oder ohne URLs verwenden. Das Modell sucht möglicherweise zuerst nach relevanten Informationen und verwendet dann das Tool für URL-Kontext, um den Inhalt der Suchergebnisse besser zu verstehen.

Diese Funktion ist experimentell und in der API-Version v1beta1 verfügbar.

Beispiele für Prompts:

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

Weitere Informationen zur Fundierung mit der Google Suche finden Sie auf der Übersichtsseite.

Webfundierung für Unternehmen mit URL-Kontext

Sie können sowohl URL-Kontext als auch Webfundierung für Unternehmen aktivieren, wenn Sie bestimmte Compliance-Anforderungen haben oder in einer regulierten Branche wie dem Gesundheitswesen, dem Finanzsektor oder dem öffentlichen Sektor tätig sind. Der Webindex, der bei der Webfundierung für Unternehmen verwendet wird, ist eingeschränkter als der Standardindex für die Fundierung mit der Google Suche, da er eine Teilmenge der in der Google Suche verfügbaren Inhalte verwendet.

Weitere Informationen zur Webfundierung für Unternehmen finden Sie auf der Seite Webfundierung für Unternehmen.

Kontextbezogene Antwort

Die Antwort des Modells basiert auf den Inhalten, die es aus den URLs abgerufen hat. Wenn das Modell Inhalte aus URLs abgerufen hat, enthält die Antwort url_context_metadata. Eine solche Antwort könnte so aussehen (Teile der Antwort wurden aus Gründen der Übersichtlichkeit weggelassen):

{
  "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">
            },
          ]
        }
    }
  ]
}

Weitere Informationen zu diesem Objekt finden Sie in der UrlContextMetadata API-Referenz.

Live-Abruf

Das Tool für URL-Kontext ruft Live-Versionen von Webseiten ab, damit Ihre Informationen auf dem neuesten Stand sind.

Um Webseiteninhalte effizient abzurufen, verwendet das Tool für URL-Kontext einen zweistufigen Prozess, der Geschwindigkeit, Kosten und Zugriff auf die aktuellsten Informationen in Einklang bringen soll:

Abruf indexierter Inhalte: Dies ist die erste Stufe. Wenn Sie eine URL angeben, versucht das Tool zuerst, die Inhalte aus dem Google's umfangreichen und hochoptimierten Webindex von abzurufen. Diese Methode bietet schnellen Zugriff auf eine große Sammlung gecrawlter Webseiten.
Fallback auf Live-Abruf: Dies ist die zweite Stufe. Wenn die Inhalte für eine bestimmte URL nicht im Index verfügbar sind (z. B. wenn die Seite sehr neu und noch nicht indexiert ist), führt das Tool automatisch einen Live-Abruf durch. Dieser Fallback-Mechanismus kann direkt auf die URL zugreifen und die neueste Version der Inhalte in Echtzeit abrufen.

Sicherheitsprüfungen

Das System führt eine Inhaltsmoderationsprüfung für die URL durch, um zu bestätigen, dass sie den Sicherheitsstandards entspricht. Wenn die von Ihnen angegebene URL diese Prüfung nicht besteht, erhalten Sie für url_retrieval_status den Wert URL_RETRIEVAL_STATUS_UNSAFE.

Tokenanzahl

Die Anzahl der Eingabetokens umfasst Inhalte, die aus den URLs abgerufen wurden, die Sie in Ihrem Prompt angeben. In der Modellausgabe sehen Sie die Tokenanzahl für Ihren Prompt und die Toolnutzung im Objekt usage_metadata. Hier ein Beispiel für eine Ausgabe:

'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
  }

Der Preis pro Token hängt vom verwendeten Modell ab. Weitere Informationen finden Sie unter Kosten für das Erstellen und Bereitstellen von KI-Modellen in Vertex AI.

Unterstützte und nicht unterstützte Inhaltstypen

Das Tool für URL-Kontext kann Inhalte aus URLs mit den folgenden Inhaltstypen extrahieren:

Inhalt	Typ
Text	`text/html` `application/json` `text/plain` `text/xml` `text/css` `text/javascript` `text/csv` `text/rtf`
Bild	`image/png` `image/jpeg` `image/bmp` `image/webp`
PDF	`application/pdf`

Das Tool für URL-Kontext unterstützt die folgenden Inhaltstypen nicht:

Paywall-Inhalte
YouTube-Videos (weitere Informationen finden Sie unter Video Understanding.)
Google Workspace-Dateien wie Google Docs oder Google Sheets
Video- und Audiodateien

Beschränkungen

Das Tool für URL-Kontext verarbeitet bis zu 20 URLs pro Anfrage zur Analyse.
Um in der Testphase optimale Ergebnisse zu erzielen, verwenden Sie das Tool für Standardwebseiten und nicht für Multimedia-Inhalte wie YouTube-Videos.

URL-Kontext Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Unterstützte Modelle

URL-Kontext verwenden

Nur URL-Kontext

Python

JavaScript

REST

Fundierung mit der Google Suche mit URL-Kontext

Python

JavaScript

REST

Webfundierung für Unternehmen mit URL-Kontext

Kontextbezogene Antwort

Live-Abruf

Sicherheitsprüfungen

Tokenanzahl

Unterstützte und nicht unterstützte Inhaltstypen

Beschränkungen

URL-Kontext