网址上下文

您可以使用网址上下文工具向 Gemini 提供网址，作为提示的额外上下文。然后，模型可以从网址检索内容，并使用该内容来提供回答和确定回答的形式。

此工具适用于以下任务：

  • 从文章中提取关键数据点或要点
  • 比较多个链接中的信息
  • 综合来自多个来源的数据
  • 根据特定网页的内容回答问题
  • 分析内容以实现特定目的（例如撰写职位说明或创建测试问题）

请注意，用于提取数据的索引可能不是最新的，因此某些信息可能已过时。

本指南介绍了如何在 Gemini API 中使用网址上下文工具。

支持的模型

以下模型提供对网址上下文的支持：

点击即可展开支持的模型

使用网址上下文

您可以通过两种主要方式使用网址上下文工具：单独使用或与依托 Google 搜索进行接地搭配使用。

仅限网址上下文

您可以在提示中直接提供要让模型分析的具体网址：

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-3.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_ENTERPRISE=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-3.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-3.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

依托 Google 搜索进行接地（含网址上下文）

您还可以同时启用网址上下文和“依托 Google 搜索进行接地”，使用包含或不包含网址的提示。模型可能会先搜索相关信息，然后使用网址上下文工具读取搜索结果的内容，以便更深入地了解相关信息。

此功能为实验性功能，可在 API 版本 v1beta1 中使用。

示例提示：

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-3.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_ENTERPRISE=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-3.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-3.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

如需详细了解如何“依托 Google 搜索进行接地”，请参阅概览页面。

适用于企业的 Web 接地（含网址上下文）

如果您有特定的合规性需求，或者您所在的行业受监管（例如健康、金融或公共部门），则可以同时启用网址上下文和适用于企业的 Web 接地。适用于企业的 Web 接地中使用的 Web 索引比标准“依托 Google 搜索进行接地”索引更有限，因为它使用了 Google 搜索中可用的部分内容。

如需详细了解适用于企业的 Web 接地，请参阅适用于企业的 Web 接地页面。

情境化回答

模型的回答基于其从网址检索到的内容。如果模型从网址检索到了内容，回答将包含 url_context_metadata。此类回答可能如下所示（为简洁起见，省略了部分回答）：

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata":
      {
          "url_metadata":
          [
            {
              "retrieved_url": "https://cloud.google.com/gemini-enterprise-agent-platform/models/capabilities/code-execution",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "https://cloud.google.com/gemini-enterprise-agent-platform/models/grounding/grounding-with-google-search",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
          ]
        }
    }
  ]
}

如需详细了解此对象，请参阅 UrlContextMetadata API 参考文档。

实时提取

网址上下文工具会提取网页的实时版本，以确保您的信息是最新的。

为了高效检索网页内容，网址上下文工具使用两阶段流程，旨在平衡速度、费用和对最新信息的访问权限：

  1. 检索已编入索引的内容：这是第一阶段。当您提供 网址时，该工具首先尝试从 Google的 广泛且高度优化的 Web 索引中提取内容。此方法可快速访问大量已抓取的网页。

  2. 实时提取回退：这是第二阶段。如果索引中没有给定网址的内容（例如，如果网页非常新且尚未编入索引），该工具会自动执行实时提取。此回退机制可以直接访问网址，并实时检索最新版本的内容。

安全检查

系统会对网址执行内容审核检查，以确认该网址符合安全标准。如果您提供的网址未通过此检查，您将获得 url_retrieval_status 的 URL_RETRIEVAL_STATUS_UNSAFE。

Token 计数

输入 token 计数包括从您在提示中指定的网址检索到的内容。从模型输出中，您可以在 usage_metadata 对象中看到提示和工具使用情况的 token 计数。以下是输出示例：

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

每个 token 的价格取决于您使用的模型。如需了解详情，请参阅 Gemini Enterprise Agent Platform中构建和部署 AI 模型的费用。

支持和不支持的内容类型

网址上下文工具可以从具有以下内容类型的网址中提取内容：

内容 类型
文本 text/html
application/json
text/plain
text/xml
text/css
text/javascript
text/csv
text/rtf
图片 image/png
image/jpeg
image/bmp
image/webp
PDF application/pdf

网址上下文工具不支持以下内容类型：

  • 付费内容
  • YouTube 视频（如需了解详情，请参阅视频 理解。）
  • Google Workspace 文件，例如 Google 文档或 Google 表格
  • 视频和音频文件

限制

  • 网址上下文工具每次请求最多使用 20 个网址进行分析。
  • 为了在实验阶段获得最佳效果，请在标准网页上使用该工具，而不是在 YouTube 视频等多媒体内容上使用。