Tavily 搜索

使用 Tavily API 进行网页搜索——专为 AI 智能体和 RAG 应用优化。

快速开始

前提条件

设置您的 Tavily API 密钥：

export TAVILY_API_KEY="tvly-your-api-key"

或者直接在 Python 客户端中传入 API 密钥。

基础搜索

from tavily import TavilyClient

client = TavilyClient(api_key="tvly-your-api-key")
response = client.search("Latest AI developments")

for result in response['results']:
    print(f"Title: {result['title']}")
    print(f"URL: {result['url']}")
    print(f"Content: {result['content'][:200]}...")

问答搜索（获取直接答案）

answer = client.qna_search(query="Who won the 2024 US Presidential Election?")
print(answer)

上下文搜索（适用于 RAG 应用）

context = client.get_search_context(
    query="Climate change effects on agriculture",
    max_tokens=4000
)
# 可直接将 context 用于大语言模型提示词中

搜索参数

常用参数

高级参数

响应格式

标准搜索响应

{
  "query": "search query",
  "results": [
    {
      "title": "Result Title",
      "url": "https://example.com/article",
      "content": "Snippet or full content...",
      "score": 0.95,
      "raw_content": "Full page content (if requested)..."
    }
  ],
  "answer": "AI-generated answer (if requested)",
  "images": ["image_url1", "image_url2"],
  "response_time": 1.23
}

错误处理

常见错误

from tavily import TavilyClient
from tavily.exceptions import TavilyError, RateLimitError, InvalidAPIKeyError

client = TavilyClient(api_key="your-api-key")

try:
    response = client.search("query")
except InvalidAPIKeyError:
    print("Invalid API key. Check your TAVILY_API_KEY.")
except RateLimitError:
    print("Rate limit exceeded. Please wait before retrying.")
except TavilyError as e:
    print(f"Tavily error: {e}")

最佳实践

1. 在 RAG 场景中使用上下文搜索

对于检索增强生成（RAG），请优先使用 get_search_context() 而非标准搜索：

context = client.get_search_context(
    query=user_query,
    max_tokens=4000,  # 适配您所用大语言模型的上下文窗口长度
    search_depth="comprehensive"
)

# 用于构造提示词
prompt = f"""Based on the following context:
{context}

Answer this question: {user_query}"""

2. 处理速率限制

Tavily 设有调用频率限制。建议实现指数退避重试机制：

import time
from tavily.exceptions import RateLimitError

def search_with_retry(client, query, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.search(query)
        except RateLimitError:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # 指数退避
                print(f"Rate limited. Waiting {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise

3. 对搜索结果进行过滤

使用域名过滤器提升结果质量：

# 仅在可信新闻源中搜索
response = client.search(
    query="breaking news",
    include_domains=["bbc.com", "reuters.com", "apnews.com"],
    time_range="day"  # 仅返回最新一天的新闻
)

4. 对事实性问题使用问答模式

针对事实类问题，推荐使用 Q&A 模式以获得直接答案：

# 适用于：“Who won the 2024 election?”
answer = client.qna_search("Who won the 2024 US Presidential Election?")

# 适用于：“What is the capital of France?”
answer = client.qna_search("Capital of France")

其他资源

• Tavily 文档: https://docs.tavily.com
• Python SDK: https://github.com/tavily-ai/tavily-python
• JavaScript SDK: https://github.com/tavily-ai/tavily-js
• API 参考文档: https://docs.tavily.com/documentation/api-reference

技能维护

该技能需要满足以下条件：

• 已设置环境变量 TAVILY_API_KEY
• 已安装 tavily-python 包（执行 pip install tavily-python）

如遇问题或需了解更新信息，请查阅 Tavily 官方文档或 GitHub 仓库。