網址背景資訊

您可以使用網址脈絡工具，為提示提供網址，做為 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 搜尋強化事實基礎」，請參閱總覽頁面。

以企業適用的網路內容建立基準 (含網址情境)

如果您有特定的法規遵循需求，或屬於醫療、金融或公部門等受監管產業，可以同時啟用 Enterprise 的網址脈絡和網路基礎功能。企業版網頁基礎功能使用的網頁索引，比標準的 Google 搜尋基礎功能索引更受限，因為前者只會使用 Google 搜尋提供的部分內容。

如要進一步瞭解「以企業適用的網路內容建立基準」，請參閱「以企業適用的網路內容建立基準」頁面。

符合情境的回覆

模型會根據從網址擷取的內容生成回覆。如果模型從網址擷取內容，回覆中會包含 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廣泛且經過高度最佳化的網路索引擷取內容。這個方法可快速存取大量已檢索的網頁。

  2. 即時擷取備援：這是第二階段。如果特定網址的內容未收錄在索引中 (例如網頁剛發布，尚未建立索引)，這項工具會自動執行即時擷取。這項備援機制可直接存取網址，並即時擷取最新版本的內容。

安全檢查

系統會對網址執行內容審核檢查，確認網址符合安全標準。如果提供的網址未通過這項檢查，您會收到 url_retrieval_status 的 URL_RETRIEVAL_STATUS_UNSAFE。

符記數量

輸入詞元數包括從您在提示中指定的網址擷取的內容。在模型輸出內容中，您可以在 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
  }

每個權杖的價格取決於您使用的模型。詳情請參閱「在 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 影片等多媒體內容) 進行測試，以獲得最佳結果。