Qwen Web Search

為 Qwen 請求啟用網路搜尋，並正確處理搜尋引擎與引用結果。

Qwen Web Search 讓支援該能力的 Qwen 模型存取網路資訊，並在回應允許時回傳來源引用。它適合天氣、新聞、產品更新和其他需要近期資訊的任務。

Qwen 搜尋可能透過 Chat 擴展欄位、Responses 內建工具或模型原生搜尋框架提供。三者的啟用方式和引用結構不同，應按目前模型詳情選擇。

搜尋入口需要模型明確支援

不要根據 Qwen 系列名稱推斷 enable_search、Responses Web Search 或搜尋引擎選擇均可用。請在模型廣場確認模型與協議。

透過 Chat 啟用搜尋

舊版文件記錄的 Qwen Chat 主路徑使用 enable_search：

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": "今天杭州天氣怎麼樣？請給出來源。"
      }
    ],
    "enable_search": true
  }'

enable_search 是模型或通路擴展欄位，不是所有 Chat 模型的共用參數。如果 SDK 類型沒有該欄位，可使用原始 HTTP 請求或 SDK 提供的擴展參數能力，並以實際模型文件為準。

透過 Responses 使用內建搜尋

目前模型支援 Responses Web Search 時，可以使用內建工具結構：

curl 'https://api.agtcloud.cn/v1/responses' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "tools": [
      {
        "type": "web_search_preview"
      }
    ],
    "input": "今天杭州天氣怎麼樣？請給出來源。"
  }'

Responses 結果可能包含 web_search_call、文字 Output Item 和 url_citation。完整結構見 Responses Reference。

搜尋引擎或 Provider 選擇

Qwen 原生搜尋框架可能支援選擇不同搜尋 Provider。該設定屬於具體模型、Agent 框架或通路能力，不是 AGTCloud Chat 的統一欄位。

當目前模型文件明確提供 Provider 選項時：

使用預設 Provider 可以減少設定並保留伺服器端降級能力。
指定 Provider 適合對來源範圍、檢索品質或合規邊界有明確要求的情境。
Provider 憑證和權限應儲存在伺服器端，不放入 Prompt 或瀏覽器程式碼。
Provider 不可用時是否自動切換，以目前工具實現為準，用戶端仍需處理失敗。

不要把舊版文件中的搜尋引擎名稱和預設順序寫成長期平台承諾。

讀取回答和引用

不同入口可能回傳：

入口	回答	引用
Chat 擴展	`choices[].message.content`	回應提供的 Annotation、連結或編號來源
Responses	Message Output Item	`annotations` 中的 `url_citation`
原生搜尋框架	框架生成的回答	編號來源清單或 Provider 回傳的來源物件

如果回答文字使用 [1]、[2] 等編號，用戶端還必須取得與編號對應的來源 URL，不能只顯示沒有目標連結的編號。

{
  "answer": "杭州今天預計有陣雨。[1]",
  "sources": [
    {
      "index": 1,
      "title": "來源標題",
      "url": "https://example.com/weather"
    }
  ]
}

該範例表示應用內部可以整理成的顯示資料，不是 AGTCloud API 的固定回應 Schema。

原生搜尋與自訂函式

內建 Web Search 面向公開網路資訊。需要查詢企業內部搜尋、訂單或私有知識庫時，應使用 Tool Calling 呼叫你自己的受控服務。

自訂工具回傳的文字不自動獲得可信 Citation。應用應同時回傳來源中繼資料，並在最終介面中保持回答與來源的對應關係。

失敗與降級

現象	處理方式
`enable_search` 被拒絕	確認模型和通路是否支援擴展欄位，或選擇已登記的 Responses 入口
搜尋沒有觸發	檢查問題是否需要近期資訊，同時確認啟用欄位實際送達上游
編號沒有來源 URL	不顯示為可點擊引用，提示本次回應缺少完整來源資訊
Provider 不可用	按目前工具規則切換或在有限次數內重試，不無限迴圈不同 Provider
搜尋結果相互衝突	顯示來源和日期，不讓模型替應用隱藏重要分歧

上線前檢查

目前模型明確支援 enable_search 或選擇的 Responses 工具。
模型擴展欄位沒有被 SDK 靜默丟棄。
Chat、Responses 和原生搜尋結果使用獨立解析器。
引用編號能夠映射到真實標題和 URL。
Provider 設定和憑證不會進入用戶端 Prompt。
無結果、搜尋失敗和來源缺失都有明確降級。

Chat 公共欄位見 Chat Completions Reference，請求失敗時參閱錯誤與疑難排解。