Diese Seite wurde von der Cloud Translation API übersetzt.

URL-Kontext

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

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

Wichtige Datenpunkte oder Gesprächsthemen aus Artikeln extrahieren
Informationen aus mehreren Links vergleichen
Daten aus mehreren Quellen zusammenführen
Fragen basierend auf dem Inhalt einer bestimmten Seite oder mehrerer Seiten beantworten
Inhalte für bestimmte Zwecke analysieren (z. B. zum Verfassen einer Stellenbeschreibung oder zum Erstellen von Testfragen)

Der Index, der zum Abrufen von Daten verwendet wird, ist möglicherweise nicht auf dem neuesten Stand. Einige Informationen sind daher möglicherweise veraltet.

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

Unterstützte Modelle

Die folgenden Modelle unterstützen den URL-Kontext:

URL-Kontext verwenden

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

Nur URL-Kontext

Sie können bestimmte URLs angeben, die das Modell direkt in Ihrem Prompt 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 den URL-Kontext als auch die Funktion „Mit der Google Suche fundieren“ aktivieren und Prompts mit oder ohne URLs verwenden. Das Modell sucht möglicherweise zuerst nach relevanten Informationen und verwendet dann das Tool „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 Web Grounding für Enterprise aktivieren, wenn Sie bestimmte Compliance-Anforderungen haben oder in einer regulierten Branche wie dem Gesundheitswesen, der Finanzbranche oder dem öffentlichen Sektor tätig sind. Der Webindex, der für die Fundierung mit dem Web 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 nutzt.

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 von den URLs abgerufen hat. Wenn das Modell Inhalte von URLs abgerufen hat, enthält die Antwort url_context_metadata. Eine solche Antwort könnte so aussehen (aus Gründen der Übersichtlichkeit wurden Teile der Antwort 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 API-Referenz für UrlContextMetadata.

Live-Abruf

Das Tool „URL-Kontext“ ruft Live-Versionen von Webseiten ab, um Ihre Informationen auf dem neuesten Stand zu halten.

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

Abrufen indexierter Inhalte: Dies ist die erste Phase. Wenn Sie eine URL angeben, versucht das Tool zuerst, die Inhalte aus dem umfangreichen und hochgradig optimierten Webindex von Googleabzurufen. Diese Methode bietet schnellen Zugriff auf eine riesige Sammlung gecrawlter Webseiten.
Live-Abruf-Fallback: Dies ist die zweite Phase. 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), wird automatisch ein Live-Abruf durchgeführt. Dieser Fallback-Mechanismus kann direkt auf die URL zugreifen und die aktuelle Version des Inhalts in Echtzeit abrufen.

Sicherheitschecks

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

Tokenanzahl

Die Anzahl der Eingabetokens umfasst Inhalte, die von den URLs abgerufen werden, die Sie in Ihrem Prompt angeben. In der Modellausgabe sehen Sie die Anzahl der Tokens für Ihren Prompt und die Tool-Nutzung im usage_metadata-Objekt. Hier sehen Sie eine Beispielausgabe:

'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

Mit dem URL-Kontexttool können Inhalte aus URLs mit den folgenden Inhaltstypen extrahiert werden:

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 „URL-Kontext“ unterstützt die folgenden Inhaltstypen nicht:

Paywall-Inhalte
YouTube-Videos (Weitere Informationen)
Google Workspace-Dateien wie Google-Dokumente oder Google-Tabellen
Video- und Audiodateien

Beschränkungen

Das Tool für den URL-Kontext verarbeitet bis zu 20 URLs pro Anfrage.
Die besten Ergebnisse in der Testphase erzielen Sie, wenn Sie das Tool auf Standardwebseiten anstelle von Multimedia-Inhalten wie YouTube-Videos verwenden.

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

Sicherheitschecks

Tokenanzahl

Unterstützte und nicht unterstützte Inhaltstypen

Beschränkungen

URL-Kontext