结论先说
- 光在提示词里贴网址不会自动抓网页,必须显式挂载
url_context工具:未挂工具时模型只能看见那串 URL 字符;挂上Tool(url_context=UrlContext())后,Google 云端才会在推理前实时拉取页面正文与表格。 - 单次请求最多可传 20 个公开网址,单链接体积上限约 34 MB:除普通 HTML 网页外,还支持公开直链的在线 PDF、JSON、XML、纯文本与常见静态图片,但不支持付费墙页面和私密登录页。
- 务必检查返回体里的
url_context_metadata状态码:遇到目标网站反爬拦截时接口未必直接抛 HTTP 异常,读取url_retrieval_status确认是SUCCESS才能排除模型「没抓到网页却硬答」的风险。 - 它和 Google Search 接地是互补关系且支持同时开启:手头已有明确目标网址用
url_context;不知道网址在哪用google_search;两者同开则能「先全网搜索找线索,再点进目标页精读全文」。 - 谷歌开发账号与主力编程订阅入口:前往 Google AI Studio 创建密钥测试网页直读需准备个人谷歌账号,缺号可查看本站 谷歌账号购买说明(含即买即发的 谷歌邮箱成品号),跨平台主力编程会员总览见 AI 会员充值中心。

图:本站根据 Google Gemini API 文档:URL context 整理的示意图
本文根据 Google Gemini API 官方文档《URL context》《Grounding with Google Search》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Google 官方网站。
适用于谁
- 做竞品参数对比、技术文档问答或新闻摘要时,不想自己维护 BeautifulSoup / Playwright 爬虫洗标签的开发者;
- 曾经在普通提示词里直接贴了一条网址,结果发现大模型根本没打开网页、全靠网址英文单词瞎猜内容的人;
- 分不清什么时候该开
url_context(网页直读),什么时候该开google_search(联网搜索接地)的团队。
一、Python 代码示例:开启 url_context 并校验抓取状态
先确保本机已安装官方 google-genai SDK(初始化配置见 Gemini API Python 调用教程)。调用时无需单独把网址拆成特殊字段,直接把公开 https:// 链接写进 contents 文本里,并在 tools 声明启用 url_context 即可:
python
from google import genai
from google.genai import types
client = genai.Client()
url_a = "https://ai.google.dev/gemini-api/docs/pricing"
url_b = "https://ai.google.dev/gemini-api/docs/tokens"
response = client.models.generate_content(
model="gemini-2.5-flash",
contents=f"请对比阅读 {url_a} 和 {url_b},用表格列出音频与视频的 Token 折算规则。",
config=types.GenerateContentConfig(
tools=[types.Tool(url_context=types.UrlContext())]
),
)
print(response.text)
# 生产环境必查:核实每个链接是否真正抓取成功
meta = response.candidates[0].url_context_metadata
if meta and meta.url_metadata:
for item in meta.url_metadata:
print(item.retrieved_url, "->", item.url_retrieval_status)
在生产代码中,强烈建议对 url_retrieval_status 做断言:只有状态为 URL_RETRIEVAL_STATUS_SUCCESS 时才把结果呈现给业务端;若返回失败或不安全拦截状态,应及时在日志告警或切换本地解析兜底。
二、url_context 与 Google Search 联网搜索接地怎么选
很多开发者会把这两个官方内置工具混为一谈,实际上它们的职责和计费方式完全不同(联网搜索的参数与免费请求数详解见 Gemini API 联网搜索怎么调):
| 选型场景 | 推荐开启工具 | 原因说明 |
|---|---|---|
| 用户贴了 2 篇公开财报 PDF 直链要求核对差异 | 仅开 url_context | 目标地址明确,直读全文不漏表格细节,且不消耗每日搜索请求配额 |
| 用户问「本周最新发布的某框架安全漏洞公告是什么」 | 仅开 google_search | 事前不知道公告 URL,需靠搜索引擎召回最新报道摘要 |
| 用户问「找出某开源库最新 Release 页面并核对破坏性变更」 | 同时挂载两个工具 | tools=[Tool(url_context=UrlContext()), Tool(google_search=GoogleSearch())],先搜出准确链接再深读正文 |
在计费方面(各模型单价见 Gemini API 价格说明),url_context 拉取回来的网页正文和 PDF 内容会折算成 Token 计入当次请求的输入用量(可在 usage_metadata 中查看工具提示词开销)。因此不要在一个请求里塞入十几个长达上百页的在线手册直链,若是反复追问同一份超大本地文档,改走 Gemini API Files API 上传与缓存 会划算得多。
谷歌开发账号与研发工具订阅提示:登录 Google AI Studio 调试 URL Context 与联网工具需要合规个人谷歌账号,若无现成账号可在本站选购带两步验证的 谷歌邮箱成品号(说明见 谷歌账号购买页);日常写数据抽取后端与前端页面,还可搭配免境外卡开通的 Claude Code 或 ChatGPT Plus。

图:本站根据 Google Gemini API 文档:URL context 限制与排错 整理的示意图
三、哪些链接不能直读:四类常见限制与替代做法
按官方文档边界,遇到以下四类 URL 时不要硬传 url_context:
- 需要登录态、Cookie 或付费订阅墙的页面:如企业内部飞书/Notion 私有链接、付费财经报刊、内网
localhost接口,Google 云端抓取器没有你的账号权限,必须在你自己的服务端认证读取后再把纯文本发给模型。 - YouTube 视频链接:
url_context专门针对图文网页与文档,不负责解析在线视频流;分析公开 YouTube 视频请直接用Part.from_uri(file_uri="https://www.youtube.com/watch?v=...", mime_type="video/*")走原生视频理解通道。 - Google Docs / Sheets 在线协作链接:私有或分享态云端硬盘文档不支持用该工具直抓,应先导出为 PDF 或通过 Google Drive API 读取文本后传入。
- 纯前端重度渲染或强反爬拦截页面:部分单页应用(SPA)首屏 HTML 为空壳,或配置了严格防火墙拦截云端抓取 UA,此时
url_retrieval_status会返回失败,需在业务侧改用合规无头浏览器渲染后提取正文。
常见问题
问:我在提示词里放了 5 个链接,但只想让模型读前 2 个,怎么控制?
答:启用 url_context 后,模型会根据你的指令意图从 contents 里挑选需要访问的 URL。为避免误抓产生多余输入 Token,最稳妥的做法是把不需要抓取的参考网址先从本轮提示词剔除,或只保留那 2 个目标 URL。
问:直读在线 PDF 直链和先下载再传 Files API 有什么区别?
答:只问一次的小体积公开 PDF 用 url_context 最省代码;但如果你要对同一份百页 PDF 连续追问十几个问题,每次用 url_context 都会重新拉取并重复收取整份文档的输入 Token,此时上传到 Files API 配合上下文缓存能大幅降本提速。
问:url_context 支持在 OpenAI 兼容端点里直接用吗?
答:它是 Gemini 原生工具特性,通过官方 google-genai SDK 的 generate_content 或 Interactions API 传入配置最完整且能直接拿到 url_context_metadata 状态明细,建议优先走原生 SDK 调用。
问:国内没有外币卡怎么买谷歌账号或开通 Claude、ChatGPT 会员配合开发,能开发票吗?
答:可前往本站 谷歌账号购买页、Claude Code 充值页 或 AI 会员充值总览 自助办理,支持支付宝、微信支付及 AlipayHK 结算,会员充值提供无需交出密码的卡密自助兑换,企业用户可申请开具国内增值税发票;实时价格与售后保障(掉订阅按剩余天数折退,封号不在质保范围)以页面展示为准。
相关教程
- Gemini API 联网搜索(Grounding with Google Search)怎么调
- Gemini API Python 调用教程:安装 google-genai SDK 与多轮对话
- Gemini API Files API 怎么用:上传长视频、音频、大 PDF 给模型分析
- Gemini API 价格:各模型每百万 tokens 多少钱、免费层和付费层差在哪
参考资料
- Google Gemini API 官方文档:URL context — https://ai.google.dev/gemini-api/docs/url-context
- Google Gemini API 官方文档:Grounding with Google Search — https://ai.google.dev/gemini-api/docs/google-search
- Google Gemini API 官方文档:Gemini Developer API Pricing — https://ai.google.dev/gemini-api/docs/pricing
0 条评论
还没有评论,来抢沙发~