跳至主要內容

網頁搜尋

在 litellm 中使用網路搜尋

功能詳細資訊
支援的端點- /chat/completions
- /responses
- /images/generations（僅限 Gemini 圖像模型）
支援的提供者openai、xai、vertex_ai、anthropic、gemini、perplexity
LiteLLM 成本追蹤✅ 支援
LiteLLM 版本v1.71.0+

使用的是哪個搜尋引擎？​

每個提供者都使用自己的搜尋後端：

提供者搜尋引擎備註
OpenAI (gpt-5-search-api、gpt-4o-search-preview、gpt-4o-mini-search-preview)OpenAI 的內部搜尋即時網路資料
xAI (grok-3)xAI 的搜尋 + X/Twitter即時社群媒體資料
Google AI/Vertex (gemini-2.0-flash)Google 搜尋使用實際的 Google 搜尋結果
Anthropic (claude-3-5-sonnet)Anthropic 的網路搜尋即時網路資料
PerplexityPerplexity 的搜尋引擎AI 驅動的搜尋與推理
重要：只有搜尋模型支援 web_search_options

對於 OpenAI，只有專用搜尋模型支援 web_search_options 參數：

  • gpt-4o-search-preview
  • gpt-4o-mini-search-preview
  • gpt-5-search-api

像 gpt-5.6-terra 和 gpt-5.6-luna 這類一般模型不支援 web_search_options

web_search_options 參數為選用

搜尋模型（如 gpt-4o-search-preview）即使沒有 web_search_options 參數，也會自動搜尋網路。

當您需要以下功能時，請使用 web_search_options：

  • 調整 search_context_size（"low"、"medium"、"high"）
  • 為在地化結果指定 user_location
資訊

Anthropic 網路搜尋模型：支援網路搜尋的 Claude 模型：claude-3-5-sonnet-latest、claude-3-5-sonnet-20241022、claude-3-5-haiku-latest、claude-3-5-haiku-20241022、claude-3-7-sonnet-20250219

OpenAI 網路搜尋：兩種方式​

OpenAI 依端點與模型提供兩種不同的網路搜尋使用方式：

方式端點模型啟用方式
搜尋模型/chat/completionsgpt-5-search-api、gpt-4o-search-preview、gpt-4o-mini-search-preview傳入 web_search_options 參數
網路搜尋工具/responsesgpt-5、gpt-4.1、gpt-4o，以及其他一般模型傳入 web_search_preview 工具
搜尋模型會自動搜尋

像 gpt-5-search-api 這類搜尋模型，即使沒有 web_search_options 參數，也會自動搜尋網路。使用 web_search_options 設定 search_context_size（"low"、"medium"、"high"），或指定 user_location 以取得在地化結果。

/chat/completions（litellm.completion）​

快速開始​

from litellm import completion

response = completion(
    model="openai/gpt-5-search-api",
    messages=[
        {
            "role": "user",
            "content": "What was a positive news story from today?",
        }
    ],
    web_search_options={
        "search_context_size": "medium"  # Options: "low", "medium", "high"
    }
)

搜尋內容大小​

OpenAI（使用 web_search_options）

from litellm import completion

# Customize search context size
response = completion(
    model="openai/gpt-5-search-api",
    messages=[
        {
            "role": "user",
            "content": "What was a positive news story from today?",
        }
    ],
    web_search_options={
        "search_context_size": "low"  # Options: "low", "medium" (default), "high"
    }
)

xAI（使用 web_search_options）

xAI 不再在自己的 /chat/completions 上執行網頁搜尋，因此當設定 web_search_options 時，LiteLLM 會將請求傳送至 xAI 的 Responses API，並使用 web_search 工具，然後將結果轉換回 chat completion。xAI 不支援 search_context_size，因此會被捨棄

from litellm import completion

response = completion(
    model="xai/grok-3",
    messages=[
        {
            "role": "user",
            "content": "What was a positive news story from today?",
        }
    ],
    web_search_options={}  # search_context_size is ignored for xAI
)

Anthropic（使用 web_search_options）

from litellm import completion

# Customize search context size for Anthropic
response = completion(
    model="anthropic/claude-sonnet-5",
    messages=[
        {
            "role": "user",
            "content": "What was a positive news story from today?",
        }
    ],
    web_search_options={
        "search_context_size": "medium",  # Options: "low", "medium" (default), "high"
        "user_location": {
            "type": "approximate",
            "approximate": {
                "city": "San Francisco",
            },
        }
    }
)

VertexAI/Gemini（使用 web_search_options）

from litellm import completion

# Customize search context size for Gemini
response = completion(
    model="gemini-3.8-flash",
    messages=[
        {
            "role": "user",
            "content": "What was a positive news story from today?",
        }
    ],
    web_search_options={
        "search_context_size": "low"  # Options: "low", "medium" (default), "high"
    }
)

Gemini 圖片生成（在 /images/generations 上使用 web_search_options）

from litellm import image_generation

response = image_generation(
    model="gemini/gemini-3.1-flash-image-preview",
    prompt="Generate an image of the latest iPhone design",
    web_search_options={},
)

可與 vertex_ai/gemini-3.1-flash-image-preview 及其他 Gemini 圖像模型搭配使用。請參閱 Vertex AI Image Generation 與 Google AI Studio Image Generation。

/responses（litellm.responses）​

使用 web_search_preview 工具搭配 gpt-5.6-terra、gpt-5.6-luna 等模型。

資訊

像 gpt-5-search-api 和 gpt-4o-search-preview 這類專用搜尋模型不支援 /responses 端點。請改搭配 /chat/completions + web_search_options 使用（見上文）。

快速開始​

from litellm import responses

response = responses(
    model="openai/gpt-5.6-terra",
    input="What is the capital of France?",
    tools=[{
        "type": "web_search_preview"  # enables web search with default medium context size
    }]
)

搜尋內容大小​

from litellm import responses

# Customize search context size
response = responses(
    model="openai/gpt-5.6-terra",
    input="What is the capital of France?",
    tools=[{
        "type": "web_search_preview",
        "search_context_size": "low"  # Options: "low", "medium" (default), "high"
    }]
)

在 config.yaml 中設定網路搜尋​

您可以直接在 proxy 設定檔中設定預設的網路搜尋選項：

model_list:
  # Enable web search by default for all requests to this model
  - model_name: grok-3
    litellm_params:
      model: xai/grok-3
      api_key: os.environ/XAI_API_KEY
      web_search_options: {}  # Enables web search with default settings

進階​

您可以將 LiteLLM 的 router 設定為可選擇性地捨棄不支援 WebSearch 的模型，例如

  - model_name: gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
  - model_name: gpt-5.6-terra
    litellm_params:
      model: azure/gpt-5.6-terra
      api_base: "x.openai.azure.com/"
      api_version: 2025-03-01-preview
    model_info:
      supports_web_search: False <---- KEY CHANGE!

在此範例中，LiteLLM 仍會將 LLM 請求路由到兩個部署，但對於 WebSearch，則只會路由到 OpenAI。

**注意：**當 web_search_options 在設定中有指定時，它會套用至該模型的所有請求。使用者仍可在 API 請求中傳入 web_search_options 來覆寫這些設定。

使用 litellm.supports_web_search(model="model_name") -> 若模型可執行網路搜尋，則回傳 True

# Check OpenAI models
assert litellm.supports_web_search(model="openai/gpt-5-search-api") == True
assert litellm.supports_web_search(model="openai/gpt-4o-search-preview") == True

# Check xAI models
assert litellm.supports_web_search(model="xai/grok-3") == True

# Check Anthropic models
assert litellm.supports_web_search(model="anthropic/claude-sonnet-5") == True

# Check VertexAI models
assert litellm.supports_web_search(model="gemini-3.8-flash") == True

# Check Google AI Studio models
assert litellm.supports_web_search(model="gemini/gemini-3.8-flash") == True

網路搜尋成本追蹤​

LiteLLM 會根據各提供者的計費模式自動追蹤網路搜尋成本。此成本會加在標準的 token 計價之上。

提供者計費單位運作方式
Gemini 3.x (3-flash、3-pro、3.1-*)每次搜尋查詢每個內部搜尋查詢都會單獨計費。一個 prompt 可能會觸發多個查詢。
Gemini 2.x (2.0-flash、2.5-flash、2.5-pro)每個 grounded prompt只要 API 呼叫使用 grounding，就按次收取固定費用，不論內部執行了多少查詢。
OpenAI (gpt-4o-search、gpt-5-search)每個搜尋內容大小費用會依 search_context_size（low、medium、high）而變動。
Anthropic（支援網路搜尋的 Claude）每次搜尋請求每次呼叫網路搜尋工具的固定費用。
Perplexity (sonar、sonar-pro)每個搜尋內容大小費用會依 search_context_size 而變動。

定價設定​

網路搜尋成本是在 model_prices_and_context_window.json 中使用兩個欄位定義：

  • search_context_cost_per_query：每個可計費單位的成本（每個搜尋內容大小層級）。
  • web_search_billing_unit (在 Gemini 模型上)："per_query"（每個搜尋查詢分開計費）或 "per_prompt"（預設；每次使用搜尋的 API 呼叫收取固定費用）。
{
    "gemini/gemini-3.8-flash": {
        "web_search_billing_unit": "per_query",
        "search_context_cost_per_query": {
            "search_context_size_low": 0.014,
            "search_context_size_medium": 0.014,
            "search_context_size_high": 0.014
        }
    },
    "gemini/gemini-2.5-flash": {
        "search_context_cost_per_query": {
            "search_context_size_low": 0.035,
            "search_context_size_medium": 0.035,
            "search_context_size_high": 0.035
        }
    }
}
資訊

沒有 web_search_billing_unit 的模型預設會使用 "per_prompt"：每次使用網頁搜尋的 API 呼叫收取一筆固定費用，不論模型執行了多少內部查詢。

您可以使用 model_info 在 proxy 設定中覆寫這些值：

model_list:
  - model_name: gemini-3.8-flash
    litellm_params:
      model: gemini/gemini-3.8-flash
    model_info:
      web_search_billing_unit: per_query
      search_context_cost_per_query:
        search_context_size_low: 0.014
        search_context_size_medium: 0.014
        search_context_size_high: 0.014

LiteLLM 如何追蹤搜尋用量​

web search 請求數量會儲存在 usage.prompt_tokens_details.web_search_requests 中。LiteLLM 會從各提供者的回應中擷取這個資訊：

  • Gemini：從回應中的 groundingMetadata.webSearchQueries 擷取。對於 Gemini 2.x，會限制為 1（依提示計費）。
  • OpenAI：直接在使用量中繼資料中回報。
  • Anthropic：透過 server_tool_use.web_search_requests 回報。
  • xAI：回報於 usage.server_side_tool_usage_details.web_search_calls，而非 web_search_requests。num_sources_used 不會被讀取。當 xAI 回傳 usage.cost 時，LiteLLM 會將其作為回應成本，這其中已包含搜尋費用
response = litellm.completion(
    model="gemini/gemini-3.8-flash",
    messages=[{"role": "user", "content": "Latest tech news?"}],
    web_search_options={"search_context_size": "medium"},
)

# Check web search usage
print(response.usage.prompt_tokens_details.web_search_requests)  # e.g., 3

# Get total cost (includes token cost + web search cost)
cost = litellm.completion_cost(completion_response=response)
print(f"Total cost: ${cost}")
LiteLLM Enterprise
為正式環境打造的 SSO/SAML、稽核記錄、支出追蹤、多團隊管理與防護欄。
深入瞭解 →