網址背景資訊

您可以使用網址背景資訊工具，為 Gemini 提供網址，做為提示的額外背景資訊。模型接著會從網址擷取內容，並根據這些內容提供回覆。

這項工具適用於下列工作：

  • 從文章中擷取重要資料點或對話重點
  • 比較多個連結中的資訊
  • 整合多個來源的資料
  • 根據特定網頁的內容回答問題
  • 分析特定用途的內容 (例如撰寫職務說明或建立測驗問題)

請注意，用於提取資料的索引可能不是最新版本，因此部分資訊可能已過時。

本指南說明如何使用 Vertex AI 中 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-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

以 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-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

如要進一步瞭解「以 Google 搜尋建立基準」功能，請參閱總覽頁面。

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

如果您有特定的法規遵循需求，或屬於受監管的產業 (例如醫療、金融或公共部門)，可以同時啟用企業版適用的網址脈絡和網頁基礎功能。企業版網頁基準功能使用的網頁索引，比標準的 Google 搜尋基準索引更有限，因為這項功能只會使用 Google 搜尋上的一小部分內容。

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

符合情境的回覆

模型會根據從網址擷取的內容回覆。如果模型從網址擷取內容，回覆中會包含 url_context_metadata。這類回應可能如下所示 (為簡潔起見，部分回應已省略)：

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

如要進一步瞭解這個物件，請參閱 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
  }

每個權杖的價格取決於您使用的模型。詳情請參閱「在 Vertex AI 中建構及部署 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 文件或 Google 試算表等 Google Workspace 檔案
  • 影片和音訊檔案

限制

  • 網址背景資訊工具每次要求最多可分析 20 個網址。
  • 在實驗階段，建議您使用標準網頁上的工具，而非 YouTube 影片等多媒體內容，以獲得最佳效果。