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)

Notez que l'index utilisé pour extraire les données n'est pas forcément à jour. Certaines informations peuvent donc être obsolètes.

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

Pour en savoir plus sur cet objet, consultez la documentation de référence de l'API UrlContextMetadata.

Récupération en direct

L'outil de contexte d'URL récupère les versions en direct des pages Web pour que vos informations restent à jour.

Pour récupérer efficacement le contenu des pages Web, l'outil de contexte d'URL utilise un processus en deux étapes conçu pour équilibrer la vitesse, le coût et l'accès aux informations les plus récentes :

  1. Récupération du contenu indexé : il s'agit de la première étape. Lorsque vous fournissez une URL, l'outil tente d'abord d'extraire le contenu de l'index Web étendu et hautement optimisé de Google. Cette méthode permet d'accéder rapidement à une vaste collection de pages Web explorées.

  2. Récupération en direct de secours : il s'agit de la deuxième étape. Si le contenu d'une URL donnée n'est pas disponible dans l'index (par exemple, si la page est très récente et n'est pas encore indexée), l'outil effectue automatiquement une récupération en direct. Ce mécanisme de secours peut accéder directement à l'URL et récupérer la dernière version du contenu en temps réel.

Contrôles de sécurité

Le système effectue une vérification de la modération du contenu sur l'URL pour confirmer qu'elle respecte les normes de sécurité. Si l'URL que vous avez fournie échoue à ce test, vous obtenez un url_retrieval_status de URL_RETRIEVAL_STATUS_UNSAFE.

Nombre de jetons

Le nombre de jetons d'entrée inclut le contenu récupéré à partir des URL que vous spécifiez dans votre requête. À partir de la sortie du modèle, vous pouvez voir le nombre de jetons pour votre requête et l'utilisation des outils dans l'objet usage_metadata. Voici un exemple de résultat :

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

Le prix par jeton dépend du modèle que vous utilisez. Pour en savoir plus, consultez Coût de création et de déploiement de modèles d'IA dans Vertex AI.

Types de contenus compatibles et non compatibles

L'outil de contexte d'URL peut extraire du contenu à partir d'URL avec les types de contenu suivants :

Contenu Type
Texte text/html
application/json
text/plain
text/xml
text/css
text/javascript
text/csv
text/rtf
Image image/png
image/jpeg
image/bmp
image/webp
PDF application/pdf

L'outil de contexte d'URL n'est pas compatible avec les types de contenu suivants :

  • Contenu soumis à un paywall
  • Vidéos YouTube (pour en savoir plus, consultez Compréhension des vidéos).
  • Fichiers Google Workspace, comme Google Docs ou Google Sheets
  • Fichiers vidéo et audio

Limites

  • L'outil de contexte d'URL consomme jusqu'à 20 URL par requête pour l'analyse.
  • 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.