您可以使用网址上下文工具为 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 搜索进行接地，请参阅概览页面。
适用于企业的 Web 接地（含网址上下文）
如果您有特定的合规性需求，或者您所在的行业受到监管（例如健康、金融或公共部门），则可以为 Enterprise 版启用网址上下文和 Web Grounding。企业版 Web Grounding 中使用的网络索引比标准“依托 Google 搜索进行接地”索引更有限，因为它使用的是 Google 搜索中可用的部分内容。
如需详细了解 Web Grounding for Enterprise，请参阅 Web Grounding for Enterprise 页面。
情境化回答
模型的回答将基于其从网址中检索到的内容。如果模型从网址中检索到了内容，回答中将包含 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 视频等多媒体内容上使用。