結論先說
- 光在提示詞裏貼網址不會自動抓網頁,必須顯式掛載
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 條評論
還沒有評論,來搶沙發~