您可以使用網址背景資訊工具，為 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 搜尋建立基準」功能，請參閱總覽頁面。
符合情境的回覆
模型會根據從網址擷取的內容回覆。如果模型從網址擷取內容，回覆中會包含 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">
},
]
}
}
]
}
限制
- 這項工具每次最多可分析 20 個網址。
- 這項工具不會擷取網頁的即時版本，因此可能會有資訊過時或不夠新的問題。
- 為在實驗階段獲得最佳成效，請在標準網頁上使用這項工具，而非 YouTube 影片等多媒體內容。