Tavily 搜索工具

信息

Tavily 是专为 AI 应用设计的搜索工具。

快速开始

pip install -U langchain-tavily

import os
os.environ["TAVILY_API_KEY"] = "your-api-key"

---

TavilySearch（搜索）

用于执行搜索查询，获取网页搜索结果。

初始化

from langchain_tavily import TavilySearch

search = TavilySearch(max_results=5, topic="general")

参数速查

参数	类型	默认值	说明
max_results	int	5	返回结果数量
topic	str	"general"	搜索类型：general / news / finance
include_answer	bool	False	是否包含答案
include_raw_content	bool	False	是否包含原始 HTML
include_images	bool	False	是否包含图片
search_depth	str	"basic"	搜索深度：basic / advanced
time_range	str	None	时间范围：day / week / month / year
include_domains	List[str]	None	限定域名（最多300个）
exclude_domains	List[str]	None	排除域名（最多150个）

调用方式

# 直接调用
result = search.invoke({"query": "Python asyncio 教程"})

# 返回结构
{
    'query': 'Python asyncio 教程',
    'answer': '简短答案...'，  # 需要 include_answer=True
    'results': [
        {
            'url': 'https://...',
            'title': '标题',
            'content': '摘要内容...',
            'score': 0.95,  # 相关度得分
            'raw_content': '...'  # 需要 include_raw_content=True
        },
        ...
    ],
    'response_time': 1.2
}

Agent 中使用

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

agent = create_agent(
    model=ChatOpenAI(model="gpt-4o"),
    tools=[search],
    system_prompt="你是研究助手，用搜索工具查找最新信息"
)

response = agent.invoke({"messages": [{"role": "user", "content": "什么是 RAG？"}]})

---

TavilyExtract（内容提取）

从指定 URL 提取完整内容。

初始化

from langchain_tavily import TavilyExtract

extract = TavilyExtract(extract_depth="basic")

参数

参数	类型	默认值	说明
extract_depth	str	"basic"	提取深度：basic / advanced
include_images	bool	False	是否包含图片信息

调用方式

result = extract.invoke({
    "urls": ["https://zh.wikipedia.org/wiki/Python"]
})

# 返回结构
{
    'results': [
        {
            'url': 'https://zh.wikipedia.org/wiki/Python',
            'raw_content': '完整页面内容...',
            'images': ['url1.jpg', ...]  # 需要 include_images=True
        }
    ],
    'failed_results': [],  # 提取失败的 URL
    'response_time': 0.8
}

---

TavilyMap（网站结构探测）

获取网站所有内部链接，了解站点结构。

初始化

from langchain_tavily import TavilyMap

m = TavilyMap()

调用方式

result = m.invoke({
    "url": "https://docs.python.org/3/",
    "instructions": "找出所有文档页面"
})

# 返回结构
{
    'base_url': 'https://docs.python.org/3/',
    'results': [
        'https://docs.python.org/3/',
        'https://docs.python.org/3/library/',
        'https://docs.python.org/3/tutorial/',
        ...
    ],
    'request_id': 'req_xxx',
    'response_time': 2.1
}

---

TavilyCrawl（网页爬取）

从 URL 提取完整内容，功能类似 Extract 但更适合批量爬取。

初始化

from langchain_tavily import TavilyCrawl

c = TavilyCrawl()

调用方式

result = c.invoke({
    "url": "https://example.com",
    "instructions": "提取所有博客文章"
})

# 返回结构
{
    'base_url': 'https://example.com',
    'results': [
        {
            'url': 'https://example.com/blog/1',
            'raw_content': '文章内容...'
        },
        {
            'url': 'https://example.com/blog/2',
            'raw_content': '文章内容...'
        }
    ],
    'response_time': 5.2,
    'request_id': 'req_xxx'
}

---

TavilyResearch（AI 研究）

创建完整的研究报告任务。

初始化

from langchain_tavily import TavilyResearch

research = TavilyResearch(
    model="auto",  # mini / pro / auto
    citation_format="numbered"  # numbered / mla / apa / chicago
)

参数

参数	类型	默认值	说明
input	str	必填	研究主题
model	str	"auto"	模型选择：mini / pro / auto
output_schema	dict	None	输出结构定义
stream	bool	False	是否流式输出
citation_format	str	"numbered"	引用格式

调用方式

# 创建研究任务
result = research.invoke({
    "input": "2024年AI大模型发展趋势",
    "model": "mini"
})

# 返回（异步任务）
{
    'request_id': 'test-xxx',
    'created_at': '2024-01-01T00:00:00Z',
    'status': 'pending',  # pending / completed / failed
    'input': '2024年AI大模型发展趋势',
    'model': 'mini'
}

# 获取结果（用 request_id）
from langchain_tavily import TavilyGetResearch
get_result = TavilyGetResearch()

final = get_result.invoke({"request_id": "test-xxx"})
# 返回
{
    'status': 'completed',
    'content': '完整研究报告...',
    'sources': [{'title': '来源1', 'url': 'https://...'}, ...]
}

---

工具对比

工具	用途	典型场景
TavilySearch	搜索	查找问题答案、获取最新信息
TavilyExtract	提取单页	获取特定页面内容
TavilyMap	探测结构	了解网站有哪些页面
TavilyCrawl	批量爬取	批量获取页面内容
TavilyResearch	研究报告	生成完整调研报告

---

常见问题

Q: API Key 如何获取？ A: 访问 https://app.tavily.com/sign-in 注册账号后获取

Q: 免费额度是多少？ A: Tavily 提供免费 tier，具体额度查看官网

Q: 如何选择 topic？

• general: 通用搜索
• news: 新闻搜索
• finance: 金融相关

Q: search_depth 有什么区别？

• basic: 快速返回结果
• advanced: 更深入搜索，结果更全面但耗时更长