Python tavily 库：Tavily 搜索 API 交互工具

2.4 注意事项

• 确保网络连接稳定，API 调用依赖互联网。
• 免费账户提供每月 1,000 次 API 信用，超出需升级付费计划。
• Windows 用户可能需安装 pip 和 Python 环境，推荐使用虚拟环境。

3. 核心功能

tavily 库封装了 Tavily API 的多种功能，适用于搜索、问答和内容处理。以下是主要功能：

1. 搜索（Search）：执行 Web 搜索，返回结构化的结果（如标题、URL、内容片段）。支持基本（basic）和高级（advanced）搜索深度。可定制域名过滤、结果数量等。
2. 问答（Q&A Search）：直接返回查询的简洁答案，适合 LLM 集成。示例：查询'谁是 Lionel Messi？'返回简短的事实性回答。
3. 内容提取（Extract）：从指定 URL 提取清洗后的 HTML 内容，支持批量提取（最多 20 个 URL）。可包括图像和描述。
4. 网站爬取（Crawl）：从起始 URL 开始爬取，提取相关页面内容。支持最大深度和结果限制，带指导指令（如'仅提取柑橘类水果页面'）。
5. 站点映射（Map）：分析网站结构，返回页面 URL 列表。适合探索网站导航或内容组织。
6. 混合 RAG（Hybrid RAG）：结合 Web 搜索和数据库检索（如 MongoDB），用于增强生成。需 Cohere API 密钥和 MongoDB 配置。

表 1：tavily 核心功能

4. 使用方法与示例

以下是 tavily 库的主要使用场景和代码示例。

4.1 基本搜索

执行简单的 Web 搜索，返回结构化结果。

示例：

from tavily import TavilyClient
# 初始化客户端
client = TavilyClient(api_key="tvly-YOUR_API_KEY")
# 执行搜索
response = client.search("Python 3.12 新特性")
print(response)

输出（简化）：

{"query":"Python 3.12 新特性","results":[{"title":"What's New In Python 3.12","url":"https://docs.python.org/3/whatsnew/3.12.html","content":"Python 3.12 introduces new syntax for type annotations..."}],"response_time":1.67}

说明：

• search 方法返回字典，包含查询、结果和响应时间。
• 可通过 search_depth="advanced" 提高结果质量。

4.2 问答搜索

直接获取查询的简洁答案。

示例：

answer = client.qna_search(query="谁是 Lionel Messi？")
print(answer)

输出：

Lionel Messi 是阿根廷职业足球运动员，广泛认为是足球史上最伟大的球员之一。

说明：

• qna_search 适合需要快速答案的场景，如聊天机器人。
• 答案由 Tavily 的 LLM 基于搜索结果生成。

4.3 内容提取

从指定 URL 提取内容。

示例：

urls = ["https://en.wikipedia.org/wiki/Artificial_intelligence", "https://en.wikipedia.org/wiki/Machine_learning"]
response = client.extract(urls, include_images=True)
for result in response["results"]:
    print(f"URL: {result['url']}")
    print(f"内容：{result['raw_content'][:200]}...")

说明：

• 支持最多 20 个 URL，include_images=True 返回图像 URL 和描述。
• extract_depth 可设为 basic 或 advanced。

4.4 网站爬取

从起始 URL 爬取相关页面。

示例：

response = client.crawl(
    url="https://wikipedia.org/wiki/Lemon",
    max_depth=3,
    limit=50,
    instructions="仅提取关于柑橘类水果的页面"
)
for result in response["results"]:
    print(f"URL: {result['url']}")
    print(f"片段：{result['raw_content'][:200]}...")

说明：

• instructions 参数指导爬取内容，增强相关性。
• max_depth 控制爬取层级，limit 限制结果数量。

4.5 站点映射

分析网站结构。

示例：

response = client.map(
    url="https://docs.tavily.com",
    max_depth=2,
    instructions="查找 Python SDK 相关页面"
)
for url in response["results"]:
    print(url)

说明：

• 返回站点内的 URL 列表，适合分析网站导航。

4.6 异步客户端

使用 AsyncTavilyClient 进行异步操作。

示例：

import asyncio
from tavily import AsyncTavilyClient

async def main():
    client = AsyncTavilyClient(api_key="tvly-YOUR_API_KEY")
    response = await client.search("Python 异步编程")
    print(response)

asyncio.run(main())

说明：

• 异步客户端适合高并发场景，如 Web 爬虫。
• 接口与同步客户端相同，仅方法需 await。

4.7 集成 LangChain

与 LangChain 结合，增强 AI 代理。

示例：

from langchain_community.retrievers import TavilySearchAPIRetriever
retriever = TavilySearchAPIRetriever(k=3, api_key="tvly-YOUR_API_KEY")
results = retriever.invoke("Python 3.12 新特性")
print(results)

说明：

• 需要安装 langchain-community 和 tavily-python。
• 适合构建 RAG 应用。

5. 性能分析

研究表明，tavily 库在搜索和内容提取方面表现出色，尤其在以下方面：

• 响应速度：API 响应时间通常在 0.02-2 秒，适合实时应用。
• 准确性：使用先进算法和 NLP 技术，从可信源（如维基百科）提取数据，确保结果可靠。
• 可扩展性：支持高并发请求，免费账户每月 1,000 次信用，付费计划可扩展。

性能测试示例：

import time
from tavily import TavilyClient

client = TavilyClient(api_key="tvly-YOUR_API_KEY")
start = time.time()
response = client.search("Python 3.12 新特性", search_depth="advanced")
print(f"响应时间：{time.time() - start:.2f} 秒")

输出：响应时间：1.67 秒

与替代方案比较：

• 相比 Google 搜索 API，Tavily 更专注 AI 工作流，答案更简洁。
• 相比 requests + BeautifulSoup 爬虫，tavily 提供清洗数据，减少开发工作量。

6. 适用场景

tavily 库适用于以下场景：

1. AI 代理和聊天机器人：使用 qna_search 提供实时问答。示例：构建基于 LLM 的知识问答系统。
2. Web 爬虫：使用 crawl 和 map 收集专题数据。示例：研究柑橘类水果的维基百科页面。
3. 数据分析：使用 extract 从网页提取结构化数据。示例：分析技术文档或新闻。
4. RAG 应用：结合 LangChain 或 LlamaIndex，增强 LLM 的知识库。示例：生成基于最新数据的报告。
5. 自动化研究：集成到 GPT-Researcher 等工具，自动化信息收集。示例：研究市场趋势。

不适用场景：

• 本地数据处理：tavily 依赖 Web 数据，无法处理本地文件。
• 高频批量爬取：免费账户信用有限，需付费计划。

7. 注意事项

1. API 密钥安全：避免硬编码密钥，推荐使用环境变量。
2. 信用限制：免费账户每月 1,000 次信用，超出需升级计划。检查信用使用情况：client.get_usage()（若支持）。
3. 错误处理：处理常见异常，如 MissingAPIKeyError 和 InvalidAPIKeyError。
4. 异步客户端：异步方法需在 asyncio 事件循环中运行。
5. 版本兼容性：确保 Python 3.8+，旧版本可能不支持。检查 tavily-python 版本，确保与 API 兼容。
6. 可读性与维护：避免复杂参数配置，优先使用默认值。示例：client.search("查询", search_depth="basic") 更简单。

示例：

import asyncio

async def main():
    client = AsyncTavilyClient(api_key="tvly-YOUR_API_KEY")
    await client.search("测试")

asyncio.run(main())

示例：

from tavily import TavilyClient, MissingAPIKeyError, InvalidAPIKeyError

try:
    client = TavilyClient(api_key="")
except MissingAPIKeyError:
    print("缺少 API 密钥")

示例：

import os
client = TavilyClient(api_key=os.getenv("TAVILY_API_KEY"))

8. 最佳实践

1. 环境变量管理：将 API 密钥存储在 .env 文件中，使用 python-dotenv 加载。
2. 参数优化：根据需求选择 search_depth（basic 快，advanced 准）。使用 include_domains 和 exclude_domains 过滤结果。
3. 异步优先：高并发场景使用 AsyncTavilyClient，减少阻塞。
4. 错误重试：对网络错误实现重试逻辑，使用 tenacity 等库。
5. 结果处理：检查响应中的 failed_results 和 response_time，确保数据完整。

示例：

response = client.search("测试")
if response["failed_results"]:
    print("失败结果:", response["failed_results"])

示例：

from tenacity import retry, stop_after_attempt, wait_fixed

@retry(stop=stop_after_attempt(3), wait=wait_fixed(2))
async def safe_search(client, query):
    return await client.search(query)

示例：

async def fetch_multiple():
    client = AsyncTavilyClient(api_key="tvly-YOUR_API_KEY")
    tasks = [client.search(q) for q in ["查询 1", "查询 2"]]
    results = await asyncio.gather(*tasks)
    return results

示例：

response = client.search("Python 教程", search_depth="advanced", include_domains=["python.org", "realpython.com"])

示例：

from dotenv import load_dotenv
import os

load_dotenv()
client = TavilyClient(api_key=os.getenv("TAVILY_API_KEY"))

9. 总结表

10. 学习资源

• 官方文档：
  • Tavily Documentation
  • Tavily Python SDK Reference
• GitHub：
  • tavily-ai/tavily-python

11. 总结

tavily 库是 Python 中与 Tavily 搜索 API 交互的强大工具，专为 AI 代理和 LLM 优化，提供搜索、问答、内容提取、爬取和站点映射等功能。其同步和异步客户端支持灵活的集成，适用于聊天机器人、Web 爬虫、RAG 应用和自动化研究。研究表明，tavily 的响应速度和准确性优于传统爬虫方案。