Tavily Python SDK

Tavily Python 封装库使您能够轻松地与 Tavily API 进行交互，直接从您的 Python 程序中使用我们提供的完整搜索、提取、爬取、地图和研究功能。您可以轻松地将智能搜索、内容提取和研究能力集成到您的应用程序中，充分利用 Tavily 的强大功能。

安装

pip install tavily-python

Tavily 搜索

搜索功能允许您根据给定的查询在网络上进行搜索。

使用方法

以下是一些代码示例，展示了如何与我们的搜索 API 进行交互。这些代码的不同步骤和组件将在下面的 API 方法部分中更详细地说明。

获取并打印完整的搜索 API 响应

from tavily import TavilyClient

# 第一步：实例化 TavilyClient
tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")

# 第二步：执行一个简单的搜索查询
response = tavily_client.search("谁是莱昂内尔·梅西？")

# 第三步：完成了！您已经成功进行了 Tavily 搜索！
print(response)

使用精确匹配查找特定名称或短语

from tavily import TavilyClient

client = TavilyClient(api_key="tvly-YOUR_API_KEY")

# 使用 exact_match=True 仅返回包含引号内确切短语的结果
response = client.search(
    query='"约翰·史密斯" Acme 公司 CEO',
    exact_match=True
)
print(response)

这等同于直接查询我们的 REST API。

为 RAG 应用程序生成上下文

from tavily import TavilyClient

# 第一步：实例化 TavilyClient
tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")

# 第二步：执行上下文搜索查询
context = tavily_client.get_search_context(query="燃烧人节洪水期间发生了什么？")

# 第三步：完成了！您现在拥有可以直接输入到 RAG 应用程序中的上下文字符串
print(context)

这就是如何通过一行代码为您的 RAG 应用程序生成精确且基于事实的上下文。

快速回答问题

from tavily import TavilyClient

# 第一步：实例化 TavilyClient
tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")

# 第二步：执行问答搜索查询
answer = tavily_client.qna_search(query="谁是莱昂内尔·梅西？")

# 第三步：完成了！您的问题已经得到了解答！
print(answer)

这就是如何通过一行代码获得准确而简洁的答案，非常适合用于大语言模型！

Tavily 提取

从一个或多个指定的 URL 中提取网页内容。

使用方法

以下是一些代码示例，展示了如何与我们的提取 API 进行交互。这些代码的每个步骤和组件都将在下面的 API 方法部分中更详细地解释。

使用 Tavily 提取 API 从多个 URL 提取原始内容

from tavily import TavilyClient

# 第一步：实例化 TavilyClient
tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")

# 第二步：定义要提取内容的 URL 列表
urls = [
    "https://zh.wikipedia.org/wiki/人工智能",
    "https://zh.wikipedia.org/wiki/机器学习",
    "https://zh.wikipedia.org/wiki/数据科学",
    "https://zh.wikipedia.org/wiki/量子计算",
    "https://zh.wikipedia.org/wiki/气候变化"
] # 您可以同时提供最多 20 个 URL

# 第三步：执行提取请求
response = tavily_client.extract(urls=urls, include_images=True)

# 第四步：打印提取的原始内容
for result in response["results"]:
    print(f"URL: {result['url']}")
    print(f"原始内容: {result['raw_content']}")
    print(f"图片: {result['images']}\n")

# 请注意，无法提取的 URL 将存储在 response["failed_results"] 中

Tavily 爬取

爬取功能允许您从一个基础 URL 开始遍历网站的内容。

注意：目前爬取功能仅限受邀用户使用。如需更多信息，请访问 crawl.tavily.com。

使用方法

以下是一些代码示例，展示了如何与我们的爬取 API 进行交互。这些代码的每个步骤和组件都将在下面的 API 方法部分中更详细地解释。

使用指令爬取一个网站

from tavily import TavilyClient

# 第一步：实例化 TavilyClient
tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")

# 第二步：定义起始 URL
start_url = "https://zh.wikipedia.org/wiki/柠檬"

# 第三步：执行爬取请求，并指示仅显示关于柑橘类水果的页面
response = tavily_client.crawl(
    url=start_url,
    max_depth=3,
    limit=50,
    instructions="查找所有关于柑橘类水果的页面"
)

# 第四步：打印符合查询的页面
for result in response["results"]:
    print(f"URL: {result['url']}")
    print(f"摘要: {result['raw_content'][:200]}...\n")

Tavily 地图

地图功能允许您从一个基础 URL 开始发现并可视化网站的结构。

使用方法

以下是一些代码示例，展示了如何与我们的地图 API 进行交互。这些代码的每个步骤和组件都将在下面的 API 方法部分中更详细地解释。

使用指令绘制网站地图

from tavily import TavilyClient

# 第一步：实例化 TavilyClient
tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")

# 第二步：定义起始 URL
start_url = "https://zh.wikipedia.org/wiki/柠檬"

# 第三步：执行地图请求，并设置参数以专注于特定页面
response = tavily_client.map(
    url=start_url,
    max_depth=2,
    limit=30,
    instructions="查找关于柑橘类水果的页面"
)

# 第四步：打印站点结构
for result in response["results"]:
    print(f"URL: {result['url']}")

Tavily 研究

研究功能允许您针对任何主题创建全面的研究报告，自动收集资料、分析并生成结构化的输出。

使用方法

以下是一些代码示例，展示了如何与我们的研究 API 进行交互。这些代码的每个步骤和组件都将在下面的 API 方法部分中更详细地解释。

创建研究任务并获取结果

from tavily import TavilyClient

# 第一步：实例化 TavilyClient
tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")

# 步骤 2. 创建研究任务
response = tavily_client.research(
    input="研究人工智能的最新进展",
    model="pro",
    citation_format="apa"
)

# 步骤 3. 获取研究结果
request_id = response["request_id"]
result = tavily_client.get_research(request_id)

# 步骤 4. 打印研究报告
print(f"状态: {result['status']}")
print(f"内容: {result['content']}")
print(f"来源: 找到 {len(result['sources'])} 个来源")

流式输出研究结果

from tavily import TavilyClient

# 步骤 1. 实例化 Tavily 客户端
tavily_client = TavilyClient(api_key="tvly-您的 API 密钥")

# 步骤 2. 创建流式研究任务
stream = tavily_client.research(
    input="研究人工智能的最新进展",
    model="pro",
    stream=True
)

# 步骤 3. 处理实时到达的数据流
for chunk in stream:
    print(chunk.decode('utf-8'))

高级用法：自定义会话/客户端注入

对于通过 API 网关代理 Tavily 流量的企业环境（例如用于集中式身份验证、日志记录或策略执行），您可以传递预先配置好的 HTTP 会话，而不是 Tavily API 密钥。

同步（自定义 requests.Session）

import requests
from tavily import TavilyClient

# 使用网关的身份验证信息预配置会话
session = requests.Session()
session.headers["Authorization"] = "Bearer 您的网关令牌"
session.headers["X-Subscription-Key"] = "您的订阅密钥"

# 无需 Tavily API 密钥——身份验证由会话处理
client = TavilyClient(
    session=session,
    api_base_url="https://您的网关.com/tavily",
)

response = client.search("最新的 AI 研究")

异步（自定义 httpx.AsyncClient）

import httpx
from tavily import AsyncTavilyClient

# 使用网关的身份验证信息预配置异步客户端
custom_client = httpx.AsyncClient(
    headers={"Authorization": "Bearer 您的网关令牌"},
    base_url="https://您的网关.com/tavily",
)

client = AsyncTavilyClient(client=custom_client)

response = await client.search("最新的 AI 研究")

关键行为：

• 如果提供了自定义会话或客户端，则 api_key 是可选的。
• 自定义会话头优先于 SDK 的默认设置（例如，您的 Authorization 不会被覆盖）。
• 自定义会话代理优先于 SDK 的代理设置。
• SDK 不会关闭外部提供的会话——会话的生命周期由您管理。

文档

有关如何使用不同端点及其参数的完整指南，请访问我们的 Python API 参考文档。

费用

Tavily 对个人用户免费，每月最多可使用 1,000 个积分。 请参阅我们文档中的 积分与定价，以了解每次 API 请求所需的积分数量。

许可证

本项目根据 MIT 许可证条款授权。

联系方式

如果您在使用 Tavily 时遇到问题，请发送邮件至 support@tavily.com。我们将竭诚为您提供帮助。

如果您想及时了解 Tavily 的最新消息和发布信息，请访问我们的 开发者社区，了解更多！

Tavily Python SDK 快速上手指南

Tavily Python SDK 是一个专为 AI 应用设计的搜索与内容提取工具，支持智能搜索、RAG 上下文生成、网页内容提取及深度研究等功能。本指南将帮助你快速集成 Tavily API。

环境准备

• Python 版本：建议 Python 3.8 或更高版本。
• API Key：你需要一个 Tavily API Key。请前往 Tavily 官网 注册账号并获取密钥（格式通常为 tvly-...）。
• 网络环境：确保你的开发环境可以访问 Tavily API 服务器。

安装步骤

使用 pip 进行安装。如果你在中国大陆地区遇到下载速度慢的问题，可以使用国内镜像源加速：

# 标准安装
pip install tavily-python

# 使用国内镜像源安装（推荐）
pip install tavily-python -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

1. 初始化客户端

首先导入库并使用你的 API Key 初始化客户端。

from tavily import TavilyClient

# 替换为你的真实 API Key
tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")

2. 执行基础搜索

这是最常用的功能，用于根据查询语句搜索网络信息。

# 执行搜索
response = tavily_client.search("Who is Leo Messi?")

# 打印完整响应
print(response)

3. 为 RAG 应用生成上下文

如果你正在构建检索增强生成（RAG）应用，可以直接获取优化后的上下文字符串，无需额外处理。

# 获取适合 LLM 输入的上下文字符串
context = tavily_client.get_search_context(query="What happened during the Burning Man floods?")

print(context)

4. 获取直接答案 (Q&A)

如果你只需要一个简洁、准确的答案而不是搜索结果列表，可以使用 qna_search。

# 获取直接答案
answer = tavily_client.qna_search(query="Who is Leo Messi?")

print(answer)

5. 提取网页内容

从指定 URL 列表中提取原始内容，支持批量处理（最多同时20个URL）。

urls = [
    "https://en.wikipedia.org/wiki/Artificial_intelligence",
    "https://en.wikipedia.org/wiki/Machine_learning"
]

# 提取内容
response = tavily_client.extract(urls=urls, include_images=True)

# 遍历结果
for result in response["results"]:
    print(f"URL: {result['url']}")
    print(f"Content: {result['raw_content'][:200]}...") # 仅打印前200字符示例

---

提示：Tavily 还提供高级功能如网站爬取（Crawl）、站点地图映射（Map）和深度研究报告（Research），具体用法请参考官方文档或查看 SDK 中的高级示例代码。个人用户每月可免费使用 1,000 积分。