Contesto URL

Puoi utilizzare lo strumento di contesto URL per fornire a Gemini URL come contesto aggiuntivo per il prompt. Il modello può quindi recuperare i contenuti dagli URL e utilizzarli per informare e modellare la sua risposta.

Questo strumento è utile per attività come le seguenti:

  • Estrazione di punti dati chiave o spunti di discussione dagli articoli
  • Confrontare le informazioni in più link
  • Sintetizzare i dati di più fonti
  • Rispondere a domande in base ai contenuti di una o più pagine specifiche
  • Analizzare i contenuti per scopi specifici (ad esempio scrivere una descrizione di lavoro o creare domande per un test)

Questa guida spiega come utilizzare lo strumento di contesto URL nell'API Gemini in Vertex AI.

Modelli supportati

I seguenti modelli supportano il contesto URL:

Utilizzare il contesto dell'URL

Puoi utilizzare lo strumento di contesto dell'URL in due modi principali: da solo o in combinazione con il Grounding con la Ricerca Google.

Solo contesto URL

Puoi fornire URL specifici che vuoi che il modello analizzi direttamente nel prompt:

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

Grounding con la Ricerca Google con contesto URL

Puoi anche attivare sia il contesto dell'URL sia il grounding con la Ricerca Google, utilizzando prompt con o senza URL. Il modello potrebbe prima cercare informazioni pertinenti e poi utilizzare lo strumento di contesto dell'URL per leggere i contenuti dei risultati di ricerca per una comprensione più approfondita.

Questa funzionalità è sperimentale e disponibile nella versione API v1beta1.

Prompt di esempio:

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

Per maggiori dettagli su Grounding con la Ricerca Google, consulta la pagina Panoramica.

Grounding web per aziende con contesto URL

Puoi attivare sia il contesto URL sia il grounding web per Enterprise se hai esigenze di conformità specifiche o se operi in un settore regolamentato come sanità, finanza o settore pubblico. L'indice web utilizzato in Web Grounding for Enterprise è più limitato rispetto all'indice standard di Grounding con la Ricerca Google, in quanto utilizza un sottoinsieme di ciò che è disponibile nella Ricerca Google.

Per maggiori dettagli su Grounding web per aziende, consulta la pagina Grounding web per aziende.

Risposta contestuale

La risposta del modello si baserà sui contenuti recuperati dagli URL. Se il modello ha recuperato contenuti dagli URL, la risposta includerà url_context_metadata. Una risposta di questo tipo potrebbe avere un aspetto simile al seguente (alcune parti della risposta sono state omesse per brevità):

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

Limitazioni

  • Lo strumento utilizzerà fino a 20 URL per richiesta per l'analisi.
  • Lo strumento non recupera le versioni live delle pagine web, pertanto potrebbero esserci problemi di aggiornamento o informazioni potenzialmente obsolete.
  • Per ottenere risultati ottimali durante la fase sperimentale, utilizza lo strumento su pagine web standard anziché su contenuti multimediali come i video di YouTube.