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 fundamentar 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)

Tenha em atenção que o índice usado para extrair dados pode não estar necessariamente atualizado, pelo que algumas informações podem estar desatualizadas.

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

Validaçã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 base 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 dos URLs, a resposta inclui url_context_metadata. Uma resposta deste tipo pode ter um aspeto semelhante ao seguinte (algumas partes da resposta foram omitidas para 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">
            },
          ]
        }
    }
  ]
}

Para mais informações acerca deste objeto, consulte a referência da API UrlContextMetadata.

Obtenção em direto

A ferramenta de contexto do URL obtém versões em direto das páginas Web para manter as suas informações atualizadas.

Para obter de forma eficiente o conteúdo das páginas Web, a ferramenta de contexto de URL usa um processo de duas fases concebido para equilibrar a velocidade, o custo e o acesso às informações mais atuais:

  1. Obtenção de conteúdo indexado: esta é a primeira fase. Quando fornece um URL, a ferramenta tenta primeiro obter o conteúdo do índice Web extenso e altamente otimizado do Google. GoogleEste método oferece acesso rápido a uma vasta coleção de páginas Web rastreadas.

  2. Recuperação alternativa de obtenção em direto: esta é a segunda fase. Se o conteúdo de um determinado URL não estiver disponível no índice (por exemplo, se a página for muito recente e ainda não tiver sido indexada), a ferramenta faz automaticamente uma obtenção em direto. Este mecanismo de alternativa pode aceder diretamente ao URL e obter a versão mais recente do conteúdo em tempo real.

Verificações de segurança

O sistema realiza uma verificação de moderação de conteúdo no URL para confirmar que o URL cumpre as normas de segurança. Se o URL que indicou falhar nesta verificação, recebe um url_retrieval_status de URL_RETRIEVAL_STATUS_UNSAFE.

Contagem de tokens

A contagem de tokens de entrada inclui conteúdo obtido a partir dos URLs que especifica no comando. A partir do resultado do modelo, pode ver a contagem de tokens para a utilização de comandos e ferramentas no objeto usage_metadata. Segue-se um exemplo de resultado:

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

O preço por token depende do modelo que usa. Para mais informações, consulte o artigo Custo da criação e implementação de modelos de IA na Vertex AI.

Tipos de conteúdo suportados e não suportados

A ferramenta de contexto de URL pode extrair conteúdo de URLs com os seguintes tipos de conteúdo:

Conteúdo Tipo
Texto text/html
application/json
text/plain
text/xml
text/css
text/javascript
text/csv
text/rtf
Imagem image/png
image/jpeg
image/bmp
image/webp
PDF application/pdf

A ferramenta de contexto de URL não suporta os seguintes tipos de conteúdo:

  • Conteúdo acessível por paywall
  • Vídeos do YouTube (para mais informações, consulte o artigo Compreensão de vídeos)
  • Ficheiros do Google Workspace, como o Google Docs ou o Google Sheets
  • Ficheiros de vídeo e áudio

Limitações

  • A ferramenta de contexto de URL consome até 20 URLs por pedido para análise.
  • 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.