Gemini API URL Context(網頁連結直讀工具)怎麼調:直接傳入網址讓模型抓取核實內容、與搜尋接地的區別

不想自己寫爬蟲洗 HTML,怎麼直接把網址丟給 Gemini API 讓它讀正文?本文詳解 url_context 工具開啟參數、單次 20 個連結上限、抓取狀態核查,以及與 Google Search 聯網接地的選型對比。

NNathaniel bigo··原創首發·AI 輔助撰寫
11 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 其他 帳號

結論先說

  1. 光在提示詞裏貼網址不會自動抓網頁,必須顯式掛載 url_context 工具:未掛工具時模型只能看見那串 URL 字符;掛上 Tool(url_context=UrlContext()) 後,Google 雲端才會在推理前實時拉取頁面正文與表格。
  2. 單次請求最多可傳 20 個公開網址,單鏈接體積上限約 34 MB:除普通 HTML 網頁外,還支持公開直鏈的在線 PDF、JSON、XML、純文本與常見靜態圖片,但不支持付費牆頁面和私密登入頁。
  3. 務必檢查返回體裏的 url_context_metadata 狀態碼:遇到目標網站反爬攔截時接口未必直接拋 HTTP 異常,讀取 url_retrieval_status 確認是 SUCCESS 才能排除模型「沒抓到網頁卻硬答」的風險。
  4. 它和 Google Search 接地是互補關係且支持同時開啟:手頭已有明確目標網址用 url_context;不知道網址在哪用 google_search;兩者同開則能「先全網搜尋找線索,再點進目標頁精讀全文」。
  5. 谷歌開發帳號與主力編程訂閱入口:前往 Google AI Studio 創建密鑰測試網頁直讀需準備個人谷歌帳號,缺號可查看本站 谷歌帳號購買說明(含即買即發的 谷歌電郵成品號),跨平台主力編程會員總覽見 AI 會員充值中心。

URL Context 與聯網搜尋接地對比

圖:本站根據 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。

URL Context 抓取失敗常見原因排查

圖:本站根據 Google Gemini API 文檔:URL context 限制與排錯 整理的示意圖

三、哪些連結不能直讀:四類常見限制與替代做法

按官方文檔邊界,遇到以下四類 URL 時不要硬傳 url_context:

  1. 需要登入態、Cookie 或付費訂閱牆的頁面:如企業內部飛書/Notion 私有連結、付費財經報刊、內網 localhost 接口,Google 雲端抓取器沒有你的帳號權限,必須在你自己的服務端認證讀取後再把純文本發給模型。
  2. YouTube 影片連結:url_context 專門針對圖文網頁與文檔,不負責解析在線影片流;分析公開 YouTube 影片請直接用 Part.from_uri(file_uri="https://www.youtube.com/watch?v=...", mime_type="video/*") 走原生影片理解通道。
  3. Google Docs / Sheets 在線協作連結:私有或分享態雲端硬碟文檔不支持用該工具直抓,應先導出為 PDF 或通過 Google Drive API 讀取文本後傳入。
  4. 純前端重度渲染或強反爬攔截頁面:部分單頁應用(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 結算,會員充值提供無需交出密碼的卡密自助兌換,企業用戶可申請開具國內增值稅發票;實時價格與售後保障(掉訂閱按剩餘天數折退,封號不在質保範圍)以頁面展示為準。

相關教學

參考資料

  • 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

Nathaniel 的更多內容

  1. 01

    獨立開發者用 ChatGPT + Codex 跑通產品全流程:市場驗證、PRD、原型到代碼上線覆盤清單

    單人做獨立產品最容易陷入「閉門寫兩個月代碼上線零用戶」或「AI 寫到一半目錄越改越崩」。本文整理「ChatGPT 負責市場驗證、PRD 與覆盤 + Codex 負責工程實現與測試」的五階段雙軌流程,附起手提示詞與 7 項上線覆盤清單。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成規範文件命名規則、整理混亂目錄樹與合併零散發票抬頭清單腳本

    面對滿桌面的「新建文件夾」「最終版2」和上百張零散電子發票,手工改名抄台帳耗時又容易漏重。本文分享先脫敏取樣、再用 ChatGPT 生成帶預演和回滾日誌的本地 Python 腳本,離線安全完成目錄整理與發票抬頭合併去重的實戰流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外電郵營銷(EDM)受眾分層文案、A/B 主題行測試與防進垃圾箱自檢

    做海外獨立站或出海 SaaS 電郵營銷(EDM),最怕千人一面群發被直接送進垃圾箱。本文結合 Gmail/Yahoo 批量發件人規範,梳理用 ChatGPT 設計受眾分層文案、批量生成 A/B 主題行矩陣並開展發前垃圾詞與合規自檢的實戰提示詞。

    ChatGPT0
  4. 04

    用 ChatGPT 寫 Notion Formula 2.0 公式、Obsidian Dataview 查詢與 Airtable 自動化腳本

    給 Notion 數據庫寫多條件 Formula 2.0 公式、給 Obsidian 寫 Dataview 動態看板,或在 Airtable 裏寫自動化腳本,經常因為一個小括號或類型不匹配報錯半天。本文整理三大工具的通用上下文喂料規範與三套直接可複製的生成提示詞。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 處理複雜 JSON / YAML / XML 字段映射、格式轉換與校驗規則編寫實戰

    對接第三方 API、遷移 Kubernetes 配置或解析政企 XML 報文時,手工對照幾百行嵌套字段既慢又容易漏掉空值與類型邊界。本文整理用 ChatGPT 完成字段映射表梳理、生成確定性轉換腳本以及編寫 JSON Schema / Pydantic / XSD 校驗規則的實戰流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 準備本科/碩士畢業論文答辯:提煉答辯 PPT 結構、模擬導師犀利追問與 3 分鐘自述稿

    畢業論文寫完後,要在 3–5 分鐘內講清研究價值並頂住答辯評委的連環追問並不輕鬆。本文整理在嚴格遵守高校學術規範的前提下,用 ChatGPT 提煉答辯 PPT 結構、打磨 3 分鐘口語自述稿並開展模擬導師犀利追問的排練流程與提示詞。

    ChatGPT0

同模型

  1. 01

    用 Google Takeout 單獨備份導出 NotebookLM 筆記本與 Gemini 記錄:只勾選指定服務不下載整個雲端硬碟的步驟

    想把 NotebookLM 裏的幾十個研究筆記本、來源副本與音頻概覽,連同 Gemini 聊天記錄一起備份到本地,又怕 Google Takeout 把整個雲端硬碟和相冊全打包?本文講清先取消全選、精準勾選兩項服務、解壓目錄查看與跨號遷移的做法。

    Gemini0
  2. 02

    Google Workspace 企業/教育版管理員怎麼在後台給成員開啟 Gemini 應用、NotebookLM 與設定年齡訪問權限

    團隊成員或學校師生登入 Google Workspace 帳號時提示無權使用 Gemini 或打不開 NotebookLM?本文按 Google 管理控制檯官方文檔整理服務開關路徑、組織部門(OU)與群組放行、18 歲年齡訪問權限設定及對話保留合規配置。

    Gemini0
  3. 03

    安卓手機預設助手換成 Gemini 後設鬧鐘、發短訊或控制智能家居失靈怎麼辦:Workspace 與實用程序擴展開啟步驟

    安卓手機把預設語音助手從 Google Assistant 換成 Gemini 後,喊它定鬧鐘、開手電筒、發短訊或開關智能燈全都沒反應?本文按官方幫助中心整理實用程序(Utilities)、Google Home 與 Workspace 關聯應用開啟步驟及鎖屏放行設定。

    Gemini0
  4. 04

    Gemini 寫長代碼或長文檔到一半突然停住、格式截斷怎麼無縫續寫:錨點接續指令與 Canvas 分塊修改技巧

    讓 Gemini 寫幾百行代碼或萬字長文時經常寫到一半突然停住、Markdown 代碼塊沒閉合,直接回「繼續」又重頭抄一遍?本文整理字面錨點續寫指令、代碼塊防亂碼補齊法與 Canvas 局部圈選修改工作流。

    Gemini0
  5. 05

    NotebookLM 中文音頻播客(Audio Overview)高階玩法:用自定義引導詞控制對談深度、受眾水平與重點章節(附模板)

    NotebookLM 生成的中文音頻播客總是泛泛而談、漏掉核心章節或夾雜生僻英文縮寫?本文按官方幫助中心整理來源勾選過濾、四種播客格式搭配與三維自定義引導詞寫法,附 4 套可直接複製的中文控場模板。

    Gemini0
  6. 06

    NotebookLM 添加 YouTube 影片、網頁或掃描版 PDF 提示「無法導入來源」怎麼辦:無字幕、反爬與純圖 PDF 逐項解決

    往 NotebookLM(Gemini Notebook)塞 YouTube 連結、外文網頁或掃描教材時總是亮紅歎號提示無法導入來源?本文按官方幫助中心逐項排查無字幕影片、反爬動態頁與加密純圖 PDF 的替代導入步驟。

    Gemini0

同產品的其他教學

  1. 01

    iPhone 操作按鈕(Action Button)或鎖屏小組件一鍵開啟 ChatGPT / Gemini 實時語音對話配置教學

    每次在 iPhone 上練口語或語音提問都要解鎖、找圖標、再點耳機按鈕太繁瑣?本文整理利用 iPhone 操作按鈕(Action Button)、iOS 18 鎖屏底部控制項、控制中心與背面輕點一鍵直達 ChatGPT 實時語音或 Gemini Live 的完整步驟。

    ChatGPTGemini0
  2. 02

    Firebase Studio(原 Project IDX)是什麼、怎麼用:瀏覽器雲端全棧開發環境搭配 Gemini 智能體實戰

    以前收藏的 Project IDX 網址為什麼跳到了 Firebase Studio?本文按 Google 官方文檔講清它的全棧雲端定位、App Prototyping 原型智能體、Code 視圖切換、.idx/dev.nix 環境定製與免費工作區上限。

    Gemini其他 AI 工具0
  3. 03

    Google Colab 內置 Gemini 編程助手怎麼用:免費雲端 GPU 筆記本自動生成數據分析代碼、修報錯與限額說明

    不用配本地 Python 環境,怎麼在 Google Colab 雲端筆記本里免費用 Gemini 自動寫數據分析代碼、一鍵修復紅字報錯並跑 Data Science Agent?本文整理四大入口用法、Secrets 密鑰管理與免費版限額。

    Gemini其他 AI 工具0
  4. 04

    Gemini API Token 計數(count_tokens)與多模態計費規則:圖片解像度、音頻秒數與影片幀率怎麼折算 Token

    傳一張高清截圖或一段 10 分鐘影片給 Gemini API 到底扣多少 Token?本文按官方文檔拆解 258 圖片切片、每秒 32 音頻與每秒 263 影片折算公式,附 count_tokens 免費預估與降本代碼。

    Gemini0
  5. 05

    Gemini API 回答被安全策略攔截(SAFETY / PROHIBITED_CONTENT)怎麼辦:閾值調節邊界與合規提示詞排查

    調用 Gemini API 翻譯文檔或分析安全日誌時返回空白、報 finish_reason: SAFETY 或 PROHIBITED_CONTENT 怎麼辦?本文詳解四類可調安全閾值代碼寫法、不可關閉的硬性紅線區別與誤報排查步驟。

    Gemini0
  6. 06

    Gemini API 圖像生成與多輪改圖怎麼調:用 google-genai SDK 出圖、局部修改與寬高比控制參數

    怎麼用 Python 代碼調用 Gemini API 生成高清配圖並像聊天一樣連續局部改圖?本文詳解 google-genai SDK 原生生圖代碼、多輪對話改圖、參考圖融合與 aspect_ratio 寬高比配置。

    Gemini0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~