Esta página foi traduzida pela API Cloud Translation.

Contexto do URL

Pode usar a ferramenta de contexto de URL para fornecer URLs ao Gemini como contexto adicional para o seu comando. Em seguida, o modelo pode obter conteúdo dos URLs e usar esse conteúdo para informar e moldar a respetiva resposta.

Esta ferramenta é útil para tarefas como as seguintes:

Extrair pontos de dados ou tópicos de debate importantes de artigos
Comparar informações em vários links
Sintetizar dados de várias origens
Responder a perguntas com base no conteúdo de uma página ou de várias páginas específicas
Analisar conteúdo para fins específicos (como escrever uma descrição de um emprego ou criar perguntas de teste)

Este guia explica como usar a ferramenta de contexto de URL na API Gemini no Vertex AI.

Modelos suportados

Os seguintes modelos oferecem suporte para o contexto do URL:

Use o contexto do URL

Pode usar a ferramenta de contexto de URL de duas formas principais: isoladamente ou em conjunto com a fundamentação com a Pesquisa Google.

Apenas contexto do URL

Pode fornecer URLs específicos que quer que o modelo analise diretamente no seu comando:

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

Fundamentação com a Pesquisa Google com contexto de URL

Também pode ativar o contexto do URL e a fundamentação com a Pesquisa Google, usando comandos com ou sem URLs. O modelo pode primeiro pesquisar informações relevantes e, em seguida, usar a ferramenta de contexto do URL para ler o conteúdo dos resultados da pesquisa para uma compreensão mais detalhada.

Esta funcionalidade é experimental e está disponível na versão v1beta1 da API.

Exemplos de comandos:

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

Para mais detalhes sobre a fundamentação com a Pesquisa Google, consulte a página de vista geral.

Fundamentação Web para empresas com contexto de URL

Pode ativar o contexto de URL e a fundamentação na Web para empresas se tiver necessidades de conformidade específicas ou estiver num setor regulamentado como a saúde, as finanças ou o setor público. O índice da Web usado na fundamentação na Web para empresas é mais limitado do que a fundamentação padrão com o índice da Pesquisa Google, uma vez que usa um subconjunto do que está disponível na Pesquisa Google.

Para mais detalhes sobre a fundamentação na Web para empresas, consulte a página Fundamentação na Web para empresas.

Resposta contextual

A resposta do modelo baseia-se no conteúdo que obteve dos URLs. Se o modelo tiver obtido conteúdo de URLs, a resposta inclui url_context_metadata. Uma resposta deste tipo pode ter o seguinte aspeto (algumas partes da resposta foram omitidas para maior brevidade):

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

Limitações

A ferramenta vai consumir até 20 URLs por pedido para análise.
A ferramenta não obtém versões em direto das páginas Web, pelo que podem existir alguns problemas com a atualização ou informações potencialmente desatualizadas.
Para obter os melhores resultados durante a fase experimental, use a ferramenta em páginas Web padrão em vez de conteúdo multimédia, como vídeos do YouTube.

Contexto do URL Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Modelos suportados

Use o contexto do URL

Apenas contexto do URL

Python

JavaScript

REST

Fundamentação com a Pesquisa Google com contexto de URL

Python

JavaScript

REST

Fundamentação Web para empresas com contexto de URL

Resposta contextual

Limitações

Contexto do URL