Gemini 中文指南
获取 API 密钥 ↗

URL 上下文

↓ 下载 Markdown

URL 上下文工具允许您以 URL 的形式为模型提供附加上下文。通过在请求中包含 URL,模型将访问这些页面中的内容(只要它不是列表中列出的 URL 类型) 限制部分)以告知并加强其响应。

URL 上下文工具对于以下任务非常有用:

  • 提取数据:从多个 URL 中提取特定信息,例如价格、名称或主要发现。

  • 比较文档:分析多个报告、文章或 PDF 以识别差异并跟踪趋势。

  • 合成和创建内容:组合来自多个源 URL 的信息以生成准确的摘要、博客文章或报告。

  • 分析代码和文档:指向 GitHub 存储库或技术文档来解释代码、生成设置说明或回答问题。

以下示例显示如何比较来自不同网站的两个食谱。

python
  from google import genai
  from google.genai.types import Tool, GenerateContentConfig

  client = genai.Client()
  model_id = "gemini-4-hydrogen"

  tools = [
    {"url_context": {}},
  ]

  url1 = "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"
  url2 = "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"

  response = client.models.generate_content(
      model=model_id,
         contents=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",
      config=GenerateContentConfig(
          tools=tools,
      )
  )

  for each in response.candidates[0].content.parts:
      print(each.text)

  # For verification, you can inspect the metadata to see which URLs the model retrieved
  print(response.candidates[0].url_context_metadata)

它是如何运作的 #

URL 上下文工具使用两步检索过程来平衡速度、成本和对新数据的访问。当您提供 URL 时,该工具首先尝试从内部索引缓存中获取内容。这充当高度优化的缓存。如果索引中没有可用的 URL(例如,如果它是一个非常新的页面),该工具会自动回退以执行实时获取。这会直接访问 URL 以实时检索其内容。

您可以将 URL 上下文工具与其他工具结合起来创建更强大的工作流程。

Gemini 3型号 支持将内置工具(如 URL 上下文)与自定义工具(函数调用)相结合。了解更多信息 工具组合 页。

当 URL 上下文和 使用 Google 搜索提供事实依据 启用后,模型可以使用其搜索功能在线查找相关信息,然后使用 URL 上下文工具更深入地了解它找到的页面。对于需要对特定页面进行广泛搜索和深入分析的提示,此方法非常有效。

python
  from google import genai
  from google.genai.types import Tool, GenerateContentConfig, GoogleSearch, UrlContext

  client = genai.Client()
  model_id = "gemini-4-hydrogen"

  tools = [
        {"url_context": {}},
        {"google_search": {}}
    ]

  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 be taken care of considering weather and commute.",
      config=GenerateContentConfig(
          tools=tools,
      )
  )

  for each in response.candidates[0].content.parts:
      print(each.text)
  # get URLs retrieved for context
  print(response.candidates[0].url_context_metadata)

了解响应 #

当模型使用 URL 上下文工具时,响应包括 url_context_metadata 对象。该对象列出了模型从中检索内容的 URL 以及每次检索尝试的状态,这对于验证和调试非常有用。

以下是该部分响应的示例(为简洁起见,省略了部分响应):

json
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata": {
        "url_metadata": [
          {
            "retrieved_url": "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592",
            "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
          },
          {
            "retrieved_url": "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
            "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
          }
        ]
      }
    }
  ]
}

有关此对象的完整详细信息,请参阅 UrlContextMetadata API参考.

安全检查 #

系统对 URL 执行内容审核检查,以确认它们符合安全标准。如果您提供的 URL 未通过此检查,您将得到一个 url_retrieval_status 的 URL_RETRIEVAL_STATUS_UNSAFE.

token数 #

从您在提示中指定的 URL 检索到的内容将计为输入 token 的一部分。您可以在以下位置查看提示和工具使用情况的 token 计数: usage_metadata 模型输出的对象。以下是示例输出:

代码
'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 的价格取决于所使用的型号,请参阅 定价 页面了解详细信息。

支持的模型 #

最佳实践 #

  • 提供具体网址:为了获得最佳结果,请提供您希望模型分析的内容的直接 URL。该模型将仅检索您提供的 URL 中的内容,而不检索嵌套链接中的任何内容。

  • 检查可访问性:验证您提供的网址不会指向需要登录或位于付费专区后面的页面。

  • 使用完整的 URL:提供完整的 URL,包括协议(例如,https://www.google.com 而不仅仅是 google.com)。

限制 #

  • 请求限制:该工具每个请求最多可以处理 20 URL。

  • URL 内容大小:从单个 URL 检索的内容的最大大小为 34MB。

  • 公共可访问性:URL 必须可在网络上公开访问。不支持本地主机地址(例如 localhost、127.0.0.1)、专用网络和隧道服务(例如 ngrok、pinggy)。

支持和不支持的内容类型 #

该工具可以从具有以下内容类型的 URL 中提取内容:

  • 文本(文本/html、应用程序/json、文本/纯文本、文本/xml、文本/css、文本/javascript、文本/csv、文本/rtf)

  • 图片(图片/png、图片/jpeg、图片/bmp、图片/webp)

  • PDF(申请表/pdf)

以下内容类型是 不 支持:

  • 付费内容

  • YouTube 视频(参见 视频理解 了解如何处理 YouTube URL)

  • Google 工作区文件,例如 Google 文档或电子表格

  • 视频和音频文件

后续步骤 #

搜索标题、API 名称或正文内容