您可以使用網址背景資訊工具,在提示中提供網址,做為 Gemini 的額外背景資訊。模型就能從網址擷取內容,並根據這些內容生成回覆。
這項工具適用於下列工作:
- 從文章中擷取重要資料點或談話要點
- 比較多個連結的資訊
- 彙整多個來源的資料
- 根據特定網頁的內容回答問題
- 分析內容以達成特定目的 (例如撰寫工作說明或建立測驗問題)
請注意,用於擷取資料的索引不一定是最新的,因此部分資訊可能已過時。
本指南說明如何在 Gemini API 使用網址脈絡工具。
支援的模型
下列模型支援網址背景資訊:
按一下即可展開支援的模型
- Gemini Robotics ER 2
- Gemini 4 Neon
- Gemini 4 Hydrogen
- Gemini 4 Carbon for cyber
- Gemini 4 Carbon
- Gemini 4 Argon Cyber Permissive
- Gemini 4 Argon
- Gemini 3.8 Flash
- Gemini 3.7 Flash
- Gemini 3.6 Flash
- Gemini 3.5 Flash-Lite
- Gemini 3.5 Flash
- Gemini 3.1 Pro
- Gemini 3.1 Flash-Lite
- Gemini 3 Flash
- Gemini 2.5 Pro
- Gemini 2.5 Flash-Lite
- Gemini 2.5 Flash
使用網址背景資訊
網址背景資訊工具主要有兩種使用方式:單獨使用,或搭配以 Google 搜尋建立基準功能。
僅限網址背景資訊
您可以在提示中直接提供要讓模型分析的特定網址:
Summarize this document: YOUR_URLs
Extract the key features from the product description on this page: YOUR_URLs
Python
GenerateContent API
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)
Interactions API
from google import genai client = genai.Client( enterprise=True, project="GOOGLE_CLOUD_PROJECT", location="global", ) interaction = client.interactions.create( model="gemini-3.8-flash", input="Compare recipes from YOUR_URL1 and YOUR_URL2", tools=[{"type": "url_context"}], ) print(interaction.output_text) # Get URLs retrieved for context for step in interaction.steps: if step.type == "url_context_result": for res in step.result: print(f"URL: {res.url} (Status: {res.status})")
JavaScript
GenerateContent API
# 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();
Interactions API
# 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({ enterprise: true, project: process.env.GOOGLE_CLOUD_PROJECT, location: process.env.GOOGLE_CLOUD_LOCATION, }); async function main() { const interaction = await ai.interactions.create({ model: "gemini-3.8-flash", input: "Compare recipes from YOUR_URL1 and YOUR_URL2", tools: [{ type: "url_context" }], }); console.log(interaction.output_text); for (const step of interaction.steps) { if (step.type === "url_context_result") { console.log(step.result); } } } await main();
REST
GenerateContent API
使用任何要求資料之前,請先修改下列項目的值:
- GOOGLE_CLOUD_PROJECT:您的專案 ID。
- YOUR_URL1:第一個要擷取背景資訊的網址。
- YOUR_URL2:要從中擷取內容的第二個網址。
HTTP 方法和網址:
POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent
JSON 要求內文:
{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Compare recipes from YOUR_URL1 and YOUR_URL2"
}
]
}
],
"tools": [
{
"url_context": {}
}
]
}
如要傳送要求,請選擇以下其中一個選項:
curl
將要求主體儲存在名為 request.json 的檔案中,然後執行下列指令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent"
PowerShell
將要求主體儲存在名為 request.json 的檔案中,然後執行下列指令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent" | Select-Object -Expand Content
Interactions API
使用任何要求資料之前,請先修改下列項目的值:
- GOOGLE_CLOUD_PROJECT:您的專案 ID。
- YOUR_URL1:第一個要擷取背景資訊的網址。
- YOUR_URL2:要從中擷取內容的第二個網址。
HTTP 方法和網址:
POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions
JSON 要求內文:
{
"model": "gemini-3.8-flash",
"input": [
{
"type": "user_input",
"content": [
{
"type": "text",
"text": "Compare recipes from YOUR_URL1 and YOUR_URL2"
}
]
}
],
"tools": [
{
"type": "url_context"
}
]
}
如要傳送要求,請選擇以下其中一個選項:
curl
將要求主體儲存在名為 request.json 的檔案中,然後執行下列指令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions"
PowerShell
將要求主體儲存在名為 request.json 的檔案中,然後執行下列指令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions" | Select-Object -Expand Content
以 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
GenerateContent API
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)
Interactions API
from google import genai client = genai.Client( enterprise=True, project="GOOGLE_CLOUD_PROJECT", location="global", ) interaction = client.interactions.create( model="gemini-3.8-flash", input="Give me a three day event schedule based on YOUR_URL. Also let me know what needs to be taken care of considering weather and commute.", tools=[ {"type": "url_context"}, {"type": "google_search"}, ], ) print(interaction.output_text) # Get URLs retrieved for context for step in interaction.steps: if step.type == "url_context_result": for res in step.result: print(f"URL: {res.url} (Status: {res.status})")
JavaScript
GenerateContent API
# 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();
Interactions API
# 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({ enterprise: true, project: process.env.GOOGLE_CLOUD_PROJECT, location: process.env.GOOGLE_CLOUD_LOCATION, }); async function main() { const interaction = await ai.interactions.create({ model: "gemini-3.8-flash", input: "Give me a three day event schedule based on YOUR_URL. Also let me know what needs to be taken care of considering weather and commute.", tools: [ { type: "url_context" }, { type: "google_search" }, ], }); console.log(interaction.output_text); for (const step of interaction.steps) { if (step.type === "url_context_result") { console.log(step.result); } } } await main();
REST
GenerateContent API
使用任何要求資料之前,請先修改下列項目的值:
- GOOGLE_CLOUD_PROJECT:您的專案 ID。
- YOUR_URL:要擷取內容的網址。
HTTP 方法和網址:
POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent
JSON 要求內文:
{
"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": {}
}
]
}
如要傳送要求,請選擇以下其中一個選項:
curl
將要求主體儲存在名為 request.json 的檔案中,然後執行下列指令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent"
PowerShell
將要求主體儲存在名為 request.json 的檔案中,然後執行下列指令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent" | Select-Object -Expand Content
Interactions API
使用任何要求資料之前,請先修改下列項目的值:
- GOOGLE_CLOUD_PROJECT:您的專案 ID。
- YOUR_URL:要擷取內容的網址。
HTTP 方法和網址:
POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions
JSON 要求內文:
{
"model": "gemini-3.8-flash",
"input": [
{
"type": "user_input",
"content": [
{
"type": "text",
"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": [
{
"type": "url_context"
},
{
"type": "google_search"
}
]
}
如要傳送要求,請選擇以下其中一個選項:
curl
將要求主體儲存在名為 request.json 的檔案中,然後執行下列指令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions"
PowerShell
將要求主體儲存在名為 request.json 的檔案中,然後執行下列指令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions" | Select-Object -Expand Content
如要進一步瞭解「以 Google 搜尋強化事實基礎」功能,請參閱總覽頁面。
以企業適用的網路內容建立基準 (含網址背景資訊)
如果您有特定的法規遵循需求,或屬於受監管的產業 (例如醫療、金融或公部門),可以同時啟用網址背景資訊和 Enterprise 網路基準。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 參考資料。
即時擷取
網址內容工具會擷取網頁的即時版本,確保資訊符合現況。
為有效擷取網頁內容,網址背景資訊工具會採用兩階段程序,在速度、成本和最新資訊存取權之間取得平衡:
檢索已建立索引的內容:這是第一階段。提供網址後,這項工具會先嘗試從 Google龐大且高度最佳化的網頁索引中擷取內容。這個方法可快速存取大量檢索到的網頁。
即時擷取備用廣告:這是第二階段。如果索引中沒有特定網址的內容 (例如網頁是新建立的,尚未建立索引),這項工具會自動執行即時擷取。這個備用機制可以直接存取網址,並即時擷取最新版本的內容。
安全檢查
系統會對網址執行內容審核檢查,確認網址符合安全標準。如果提供的網址未通過這項檢查,系統會傳回 URL_RETRIEVAL_STATUS_UNSAFE 的 url_retrieval_status。
符記數量
輸入詞元數量包含從提示詞中指定網址擷取的內容。在模型輸出內容中,您可以在 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/htmlapplication/jsontext/plaintext/xmltext/csstext/javascripttext/csvtext/rtf |
| 圖片 | image/pngimage/jpegimage/bmpimage/webp |
application/pdf |
網址背景資訊工具不支援下列內容類型:
- 付費牆內容
- YouTube 影片 (詳情請參閱「影片理解」)。
- Google Workspace 檔案,例如 Google 文件或 Google 試算表
- 影片和音訊檔案
限制
- 網址背景資訊工具每次要求最多可分析 20 個網址。
- 在實驗階段,請在標準網頁上使用這項工具,而非 YouTube 影片等媒體內容,以獲得最佳效果。