URLs de contexte

Vous pouvez utiliser l'outil de contexte d'URL pour fournir à Gemini des URL comme contexte supplémentaire pour votre requête. Le modèle peut ensuite récupérer le contenu des URL et l'utiliser pour informer et façonner sa réponse.

Cet outil est utile pour les tâches suivantes :

  • Extraire les points de données ou les points de discussion clés des articles
  • Comparer des informations provenant de plusieurs liens
  • Synthétiser des données provenant de plusieurs sources
  • Répondre à des questions basées sur le contenu d'une ou plusieurs pages spécifiques
  • Analyser du contenu à des fins spécifiques (par exemple, rédiger une description de poste ou créer des questions de test)

Ce guide explique comment utiliser l'outil de contexte d'URL dans l'API Gemini dans Vertex AI.

Modèles compatibles

Les modèles suivants sont compatibles avec le contexte d'URL :

Utiliser le contexte de l'URL

Vous pouvez utiliser l'outil de contexte d'URL de deux manières principales : seul ou en association avec Ancrage avec la recherche Google.

Contexte d'URL uniquement

Vous pouvez fournir des URL spécifiques que vous souhaitez que le modèle analyse directement dans votre requête :

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

Ancrage avec la recherche Google avec contexte d'URL

Vous pouvez également activer le contexte d'URL et l'ancrage avec la recherche Google, en utilisant des requêtes avec ou sans URL. Le modèle peut d'abord rechercher des informations pertinentes, puis utiliser l'outil de contexte d'URL pour lire le contenu des résultats de recherche et obtenir ainsi une compréhension plus approfondie.

Cette fonctionnalité est expérimentale et disponible dans la version v1beta1 de l'API.

Exemples de requêtes :

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

Pour en savoir plus sur l'ancrage avec la recherche Google, consultez la page de présentation.

Ancrage Web pour les entreprises avec contexte d'URL

Vous pouvez activer le contexte d'URL et l'ancrage Web pour Enterprise si vous avez des besoins de conformité spécifiques ou si vous travaillez dans un secteur réglementé comme la santé, la finance ou le secteur public. L'index Web utilisé dans l'ancrage Web pour Enterprise est plus limité que l'index standard de l'ancrage avec la recherche Google, car il utilise un sous-ensemble de ce qui est disponible dans la recherche Google.

Pour en savoir plus sur l'ancrage Web pour Enterprise, consultez la page Ancrage Web pour Enterprise.

Réponse contextuelle

La réponse du modèle sera basée sur le contenu qu'il a récupéré à partir des URL. Si le modèle a récupéré du contenu à partir d'URL, la réponse inclura url_context_metadata. Une telle réponse peut ressembler à ce qui suit (certaines parties de la réponse ont été omises par souci de concision) :

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

Limites

  • L'outil consomme jusqu'à 20 URL par requête pour l'analyse.
  • L'outil ne récupère pas les versions en direct des pages Web. Il peut donc y avoir des problèmes de fraîcheur ou des informations potentiellement obsolètes.
  • Pour obtenir les meilleurs résultats pendant la phase expérimentale, utilisez l'outil sur des pages Web standards plutôt que sur des contenus multimédias tels que des vidéos YouTube.