Grok Web Search

Grok Web Search 讓支援該能力的 Grok 模型存取近期網頁內容並回傳帶來源的回答。AGTCloud 的舊資料記錄了 Chat 相容入口和 Grok 原生 Responses 工具兩種表達；客戶應根據目前模型詳情選擇實際可用入口。

不要根據模型名稱推測搜尋能力

同一系列的不同模型或通路可能具有不同工具能力。請在模型廣場確認模型和協議，範例中的 MODEL_ID 不代表任意 Grok 模型。

透過 Chat 相容入口啟用搜尋

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "尋找今天與商業航天有關的重要新聞，並列出來源。"
      }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'

Chat 回應通常從 choices[].message 讀取。引用可能以 Annotation、來源連結或文字形式回傳，用戶端應根據實際回應分支處理，不能自行補造結構化 Citation。

理解 Grok 原生工具結構

Grok 原生 Responses 風格透過 tools 宣告搜尋工具：

{
  "model": "MODEL_ID",
  "input": [
    {
      "role": "user",
      "content": "尋找今天與商業航天有關的重要新聞，並列出來源。"
    }
  ],
  "tools": [
    {
      "type": "web_search"
    }
  ]
}

只有當目前模型詳情明確提供該入口時才使用原生結構。不要把它與 AGTCloud Responses Reference 中的工具類型直接視為相同協議。

限制或排除網域

原生工具在支援時可以限制搜尋範圍：

{
  "tools": [
    {
      "type": "web_search",
      "filters": {
        "allowed_domains": ["example.com"]
      }
    }
  ]
}

allowed_domains 只允許指定網域。
excluded_domains 排除指定網域。
兩者不要在同一請求中同時設定。
網域數量和格式限制以目前模型文件為準。

限定網域有助於控制來源範圍，但不會自動保證網頁內容正確、最新或適合目前業務。

搜尋中的圖片理解

部分 Grok 搜尋工具允許在搜尋過程中分析網頁圖片。只有目前模型和工具明確支援時，才新增相應選項：

{
  "tools": [
    {
      "type": "web_search",
      "enable_image_understanding": true
    }
  ]
}

啟用圖片理解可能改變請求用量、延遲和回傳內容。應用仍應驗證圖片來源，不要把網頁圖片中的文字或指令直接當作可信業務輸入。

讀取引用

Grok 搜尋回答可能在回應提供時包含 Citation 或 Sources。用戶端應：

讀取最終回答文字；
讀取回應實際提供的來源陣列或引用物件；
儲存標題、URL 和與回答本文的關聯；
在介面中顯示可點擊來源；
沒有引用時明確提示，而不是從回答文字猜測 URL。

Chat 與 Grok 原生 Responses 的引用位置不同。使用 Chat 時檢視 Chat Completions Reference；使用原生入口時按目前模型文件解析。

Web Search 與自訂函式

Web Search 由模型或伺服器端搜尋工具存取公開網路。自訂函式由你的應用執行，適合內部資料、受控搜尋服務和需要業務授權的操作。

不要因為模型已經開啟 Web Search，就允許搜尋結果直接建構資料庫查詢、Shell 命令或外部寫請求。需要業務工具時，按照 Tool Calling 建立獨立驗證和權限流程。

失敗與降級

現象	處理方式
搜尋未觸發	確認模型、入口和啟用欄位，必要時讓問題明確要求近期資訊
網域過濾無結果	提示使用者擴大範圍，不靜默移除業務要求的白名單
沒有引用	顯示回答時明確來源不可用，不生成虛假 Citation
圖片理解失敗	退回網頁文字搜尋或提示目前內容無法分析
搜尋服務暫時不可用	在有限次數內重試，或降級為不含即時資訊的回答並清楚標注

上線前檢查

目前模型明確支援選擇的搜尋入口。
Chat 與原生 Responses 使用獨立請求和回應解析器。
網域允許清單與排除清單不會同時傳送。
圖片理解只在目標模型支援時啟用。
引用缺失、搜尋失敗和無結果都有明確狀態。
搜尋內容不會繞過工具權限或觸發高風險操作。

請求失敗時參閱錯誤與疑難排解，切換協議前閱讀協議選擇。

本頁目錄