總覽

功能	支援
支援的提供者	perplexity, tavily, parallel_ai, exa_ai, brave, google_pse, dataforseo, firecrawl, searxng, linkup, duckduckgo, searchapi, serper, you_com, apiserpent, agentcore, nimble, bing_grounding
成本追蹤	✅
記錄	✅
負載平衡	❌

提示

LiteLLM 遵循 Search API 的 Perplexity API 請求/回應

資訊

自 LiteLLM v1.78.7+ 起支援

LiteLLM Python SDK 用法

快速開始

Basic Search

from litellm import search
import os

os.environ["PERPLEXITYAI_API_KEY"] = "pplx-..."

response = search(
    query="latest AI developments in 2024",
    search_provider="perplexity",
    max_results=5
)

# Access search results
for result in response.results:
    print(f"{result.title}: {result.url}")
    print(f"Snippet: {result.snippet}\n")

若要使用 Parallel AI Search，請設定 PARALLEL_API_KEY 並傳入 search_provider="parallel_ai"。

非同步用法

Async Search

from litellm import asearch
import os, asyncio

os.environ["PERPLEXITYAI_API_KEY"] = "pplx-..."

async def search_async(): 
    response = await asearch(
        query="machine learning research papers",
        search_provider="perplexity",
        max_results=10,
        search_domain_filter=["arxiv.org", "nature.com"]
    )
    
    # Access search results
    for result in response.results:
        print(f"{result.title}: {result.url}")
        print(f"Snippet: {result.snippet}")

asyncio.run(search_async())

選用參數

Search with Options

response = search(
    query="AI developments",
    search_provider="perplexity",
    # Unified parameters (work across all providers)
    max_results=10,                         # Maximum number of results (1-20)
    search_domain_filter=["arxiv.org"],     # Filter to specific domains
    country="US",                           # Country code filter
    max_tokens_per_page=1024                # Max tokens per page
)

LiteLLM AI Gateway 用法

LiteLLM 提供與 Perplexity API 相容的 /search 端點供搜尋請求使用。

設定

將以下內容加入您的 litellm proxy config.yaml

config.yaml

model_list:
  - model_name: gpt-5.6-terra
    litellm_params:
      model: gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY

search_tools:
  - search_tool_name: perplexity-search
    litellm_params:
      search_provider: perplexity
      api_key: os.environ/PERPLEXITYAI_API_KEY
  
  - search_tool_name: tavily-search
    litellm_params:
      search_provider: tavily
      api_key: os.environ/TAVILY_API_KEY

  - search_tool_name: parallel-search
    litellm_params:
      search_provider: parallel_ai
      api_key: os.environ/PARALLEL_API_KEY

啟動 litellm

litellm --config /path/to/config.yaml

# RUNNING on http://0.0.0.0:4000

測試請求

選項 1：URL 中的搜尋工具名稱（建議 - 保持 body 與 Perplexity 相容）

cURL Request

curl http://0.0.0.0:4000/v1/search/perplexity-search \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest AI developments 2024",
    "max_results": 5,
    "search_domain_filter": ["arxiv.org", "nature.com"],
    "country": "US"
  }'

選項 2：body 中的搜尋工具名稱

cURL Request with search_tool_name in body

curl http://0.0.0.0:4000/v1/search \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search_tool_name": "perplexity-search",
    "query": "latest AI developments 2024",
    "max_results": 5
  }'

負載平衡

讓多個搜尋工具使用相同的 search_tool_name 以在它們之間進行負載平衡。每個請求會隨機選取一個符合條件的工具。router_settings.routing_strategy 不適用於搜尋工具，因此像 least-busy 或 latency-based-routing 這類策略，對哪個提供者提供搜尋請求沒有影響

config.yaml with load balancing

search_tools:
  - search_tool_name: my-search
    litellm_params:
      search_provider: perplexity
      api_key: os.environ/PERPLEXITYAI_API_KEY
  
  - search_tool_name: my-search
    litellm_params:
      search_provider: tavily
      api_key: os.environ/TAVILY_API_KEY
  
  - search_tool_name: my-search
    litellm_params:
      search_provider: exa_ai
      api_key: os.environ/EXA_API_KEY

  - search_tool_name: my-search
    litellm_params:
      search_provider: brave
      api_key: os.environ/BRAVE_API_KEY

使用負載平衡進行測試：

curl http://0.0.0.0:4000/v1/search/my-search \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI developments",
    "max_results": 10
  }'

限制搜尋工具存取

在 key 或 team 的 object_permission 底下設定 search_tools，以限制其可呼叫的搜尋工具。允許清單適用於 /search、/v1/search、/search/{search_tool_name}、網頁搜尋攔截、搜尋工具之間的路由備援，以及 /search_tools/list

Grant a team one search tool

curl http://0.0.0.0:4000/team/new \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_alias": "research",
    "object_permission": {"search_tools": ["tavily-search"]}
  }'

預設情況下，空白或缺少的 search_tools 清單會允許所有搜尋工具。若要讓所有搜尋工具都採取 opt-in，請開啟 search_tool_deny_by_default：

config.yaml

general_settings:
  search_tool_deny_by_default: true

此設定預設為 false。啟用後，請求的搜尋工具必須列在請求所解析到之每個身分的 object_permission.search_tools 中

呼叫端	需要的授權
沒有 team 的虛擬 key	該 key
有 team 的虛擬 key	該 key 及其 team
沒有虛擬 key 的 team 成員（JWT 或 lite login session）	請求所解析到的 team
沒有虛擬 key 或 team 的使用者	該使用者

缺少權限記錄、null 清單，以及空白清單都不會授予任何權限。只有當請求沒有虛擬 key 也沒有 team 時，使用者的個人授權才會生效，因此它們永遠不會擴大或縮小 key 或 team 的請求。如果某個 key 指定了無法載入的 team，請求會遭拒絕，而不是被視為沒有 team 的 key。被拒絕的請求會在呼叫任何搜尋提供者之前回傳 403，並附帶 key_search_tool_access_denied、team_search_tool_access_denied 或 user_search_tool_access_denied，而 /search_tools/list 只會回傳呼叫端可呼叫的工具

對於 team key，請在兩個物件上都授予該工具：

Team and key both grant the search tool

curl -X POST 'http://localhost:4000/team/new' \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"team_alias": "research", "object_permission": {"search_tools": ["tavily-search"]}}'

curl -X POST 'http://localhost:4000/key/generate' \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"team_id": "<team_id from above>", "object_permission": {"search_tools": ["tavily-search"]}}'

master key 和 dashboard 登入 session 不受限制。使用自己的虛擬 key 呼叫的 proxy 管理員會像其他任何 key 一樣受到限制。若沒有註冊的搜尋工具，對網頁搜尋攔截的處理會停止為每個受限呼叫端回退到預設提供者，因為沒有可供授權清單列出的工具名稱。現有的空白清單 key 和 team 只要此設定一開啟就會失去搜尋存取權

將旗標改回 false 會恢復先前的行為，也就是空白或未設定的清單表示不受限制。若非空白的 search_tools 清單沒有包含所要求的工具，仍會遭到拒絕

請求/回應格式

資訊

LiteLLM 遵循 Perplexity Search API 規格。

請參閱 Perplexity Search 官方文件 以取得完整詳細資訊。

請求範例

Search Request

{
  "query": "latest AI developments 2024",
  "max_results": 10,
  "search_domain_filter": ["arxiv.org", "nature.com"],
  "country": "US",
  "max_tokens_per_page": 1024
}

請求參數

參數	類型	必填	說明
query	string 或 array	是	搜尋查詢。可以是單一字串或字串陣列
search_provider	string	是（SDK）	要使用的搜尋提供者："perplexity"、"tavily"、"parallel_ai"、"exa_ai"、"brave"、"google_pse"、"dataforseo"、"firecrawl"、"searxng"、"linkup"、"duckduckgo"、"searchapi"、"serper"，或 "you_com" 或 "apiserpent" 或 "agentcore" 或 "bing_grounding"
search_tool_name	string	是（Proxy）	在 config.yaml 中設定的搜尋工具名稱
max_results	integer	否	要回傳的最大結果數量（1-20）。預設值：10
search_domain_filter	array	否	用於篩選結果的網域清單（最多 20 個網域）
max_tokens_per_page	integer	否	每頁要處理的最大 token 數。預設值：1024
country	string	否	國家代碼篩選器（例如 "US"、"GB"、"DE"）

查詢格式範例：

# Single query
query = "AI developments"

# Multiple queries
query = ["AI developments", "machine learning trends"]

回應格式

回應遵循 Perplexity 的搜尋格式，結構如下：

Search Response

{
  "object": "search",
  "results": [
    {
      "title": "Latest Advances in Artificial Intelligence",
      "url": "https://arxiv.org/paper/example",
      "snippet": "This paper discusses recent developments in AI...",
      "date": "2024-01-15"
    },
    {
      "title": "Machine Learning Breakthroughs",
      "url": "https://nature.com/articles/ml-breakthrough",
      "snippet": "Researchers have achieved new milestones...",
      "date": "2024-01-10"
    }
  ]
}

回應欄位

欄位	類型	說明
object	string	搜尋回應一律為 "search"
results	array	搜尋結果清單
results[].title	string	搜尋結果標題
results[].url	string	搜尋結果 URL
results[].snippet	string	結果中的文字片段
results[].date	string	選用的發佈或最後更新日期

支援的提供者

提供者	環境變數	search_provider 值
Perplexity AI	PERPLEXITYAI_API_KEY	perplexity
Tavily	TAVILY_API_KEY	tavily
Exa AI	EXA_API_KEY	exa_ai
Brave Search	BRAVE_API_KEY	brave
Parallel AI	PARALLEL_AI_API_KEY	parallel_ai
Google PSE	GOOGLE_PSE_API_KEY, GOOGLE_PSE_ENGINE_ID	google_pse
DataForSEO	DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD	dataforseo
Firecrawl	FIRECRAWL_API_KEY	firecrawl
SearXNG	SEARXNG_API_BASE（必填）	searxng
Linkup	LINKUP_API_KEY	linkup
Serper	SERPER_API_KEY	serper
DuckDuckGo	DUCKDUCKGO_API_BASE	duckduckgo
SearchAPI.io	SEARCHAPI_API_KEY	searchapi
You.com	YOUCOM_API_KEY （選用 — 無金鑰免費方案可省略）	you_com
APISerpent	APISERPENT_API_KEY	apiserpent
Bedrock AgentCore	AGENTCORE_GATEWAY_URL（必填）、AWS 憑證或 AGENTCORE_GATEWAY_TOKEN	agentcore
Nimble	NIMBLE_API_KEY	nimble
Grounding with Bing (Microsoft Foundry)	BING_GROUNDING_PROJECT_ENDPOINT、BING_GROUNDING_MODEL（必填）、api_key 或 BING_GROUNDING_TOKEN 或 azure-identity	bing_grounding

請參閱各個提供者的文件，以取得詳細的設定說明與提供者專屬參數。