tavily-best-practices

Tavily

Tavily 是一個專為 LLM 設計的搜尋 API，讓 AI 應用程式能夠存取即時的網路資料。

安裝

Python：

pip install tavily-python

JavaScript：

npm install @tavily/core

完整 SDK 參考請見 references/sdk.md。

客戶端初始化

from tavily import TavilyClient

# 使用 TAVILY_API_KEY 環境變數（建議）
client = TavilyClient()

# 搭配專案追蹤（用於用量管理）
client = TavilyClient(project_id="your-project-id")

# 非同步客戶端，用於平行查詢
from tavily import AsyncTavilyClient
async_client = AsyncTavilyClient()

選擇正確的方法

適用於自訂代理/工作流程：

需求	方法
網路搜尋結果	search()
特定 URL 的內容	extract()
整個網站的內容	crawl()
從網站發現 URL	map()

適用於開箱即用的研究：

需求	方法
端到端研究搭配 AI 綜合分析	research()

快速參考

search() - 網路搜尋

response = client.search(
    query="quantum computing breakthroughs",  # 保持在 400 字元以內
    max_results=10,
    search_depth="advanced"
)
print(response)

主要參數：query、max_results、search_depth（ultra-fast/fast/basic/advanced）、include_domains、exclude_domains、time_range

完整搜尋參考請見 references/search.md。

extract() - URL 內容擷取

# 簡單的一步擷取
response = client.extract(
    urls=["https://docs.example.com"],
    extract_depth="advanced"
)
print(response)

主要參數：urls（最多 20 個）、extract_depth、query、chunks_per_source（1-5）

完整擷取參考請見 references/extract.md。

crawl() - 全站擷取

response = client.crawl(
    url="https://docs.example.com",
    instructions="Find API documentation pages",  # 語意焦點
    extract_depth="advanced"
)
print(response)

主要參數：url、max_depth、max_breadth、limit、instructions、chunks_per_source、select_paths、exclude_paths

完整爬蟲參考請見 references/crawl.md。

map() - URL 發現

response = client.map(
    url="https://docs.example.com"
)
print(response)

research() - AI 驅動的研究

import time

# 用於全面的多主題研究
result = client.research(
    input="Analyze competitive landscape for X in SMB market",
    model="pro"  # 或 "mini" 用於聚焦查詢，"auto" 用於不確定時
)
request_id = result["request_id"]

# 輪詢直到完成
response = client.get_research(request_id)
while response["status"] not in ["completed", "failed"]:
    time.sleep(10)
    response = client.get_research(request_id)

print(response["content"])  # 研究報告

主要參數：input、model（"mini"/"pro"/"auto"）、stream、output_schema、citation_format

完整研究參考請見 references/research.md。

詳細指南

如需完整的參數、回應欄位、模式與範例：

• references/sdk.md - Python 與 JavaScript SDK 參考、非同步模式、Hybrid RAG
• references/search.md - 查詢最佳化、搜尋深度選擇、網域過濾、非同步模式、後過濾
• references/extract.md - 一步與兩步擷取、查詢/區塊定位、進階模式
• references/crawl.md - Crawl 與 Map 比較、語意焦點指令、使用案例、Map-then-Extract 模式
• references/research.md - 提示詞最佳實務、模型選擇、串流、結構化輸出綱要
• references/integrations.md - LangChain、LlamaIndex、CrewAI、Vercel AI SDK 與框架整合