【LangChain】langchain_tavily 库：提供 LangChain 与 Tavily 搜索 API 的集成-CSDN博客

本文链接：https://blog.csdn.net/u013172930/article/details/147980268

langchain_tavily 是一个 LangChain 的官方集成包，用于将 Tavily 的搜索和内容提取功能与 LangChain 的生态系统无缝连接。Tavily 是一个专为大型语言模型（LLM）和 AI 代理设计的搜索引擎，旨在提供实时、准确、事实性的搜索结果，特别适合检索增强生成（RAG）等 AI 工作流。通过 langchain_tavily，开发者可以轻松在 LangChain 应用中集成 Tavily 的搜索和提取工具，增强代理或链的实时信息检索和内容分析能力。

以下是对 langchain_tavily 库的详细介绍，涵盖其定义、功能、安装与配置、核心组件、使用方式、代码示例、应用场景、优化建议、注意事项以及与 LangChain 生态的结合。

1. 什么是 `langchain_tavily`？

langchain_tavily 是一个 Python 包，提供 LangChain 与 Tavily 搜索 API 的集成，包含以下核心功能：

TavilySearch：用于执行实时网络搜索，返回结构化搜索结果。
TavilyExtract：用于从指定网页提取和分析内容。
代理集成：支持将 Tavily 工具绑定到 LangChain 代理，实现动态搜索和内容处理。

Tavily 的搜索 API 针对 AI 代理进行了优化，相比传统搜索 API（如 Google、SerpAPI），它具有以下优势：

语义搜索：基于自然语言处理（NLP），理解查询的上下文，提供更相关的结果。
结构化输出：返回 JSON 格式的搜索结果，包含 URL、内容片段、相关性评分等，便于 LLM 处理。
多源整合：从多个可信来源提取信息，减少无关内容。
实时性：提供最新的网络信息，适合动态查询。
RAG 优化：为检索增强生成（RAG）设计，确保结果适合 LLM 上下文。

langchain_tavily 将这些功能封装为 LangChain 工具，方便开发者在链、代理或自定义工作流中使用。

2. 功能与特点

langchain_tavily 提供以下主要功能：

实时搜索：
- 使用 TavilySearch 工具查询网络，获取最新的信息。
- 支持自定义搜索参数，如最大结果数、主题（general、news、finance）、搜索深度等。
内容提取：
- 使用 TavilyExtract 工具从指定 URL 提取结构化内容。
- 适合分析网页、提取关键信息。
代理支持：
- 集成到 LangChain 代理（如 AgentExecutor），实现动态工具调用。
- 支持 OpenAI 的函数调用（Function Calling）或其他模型的工具调用能力。
结构化输出：
- 搜索和提取结果以 JSON 格式返回，包含标题、URL、内容、评分等字段。
易于集成：
- 与 LangChain 的链、提示模板、回调等模块无缝协作。
- 支持 LangSmith 进行调试和性能分析。
可定制性：
- 支持过滤结果（如按日期、域名）、调整搜索深度（basic 或 advanced）、包含图片等。

特点：

AI 优化：专为 LLM 和 RAG 设计，减少无关信息，提高结果质量。
高性能：搜索结果通常在秒级返回，适合实时应用。
可扩展：支持复杂查询和多工具工作流。
社区支持：作为 LangChain 官方推荐的搜索工具，拥有活跃的社区和文档。

3. 安装与配置

安装

安装 langchain_tavily 需要以下依赖：

pip install -qU langchain langchain-openai langchain-tavily tavily-python

langchain：LangChain 核心库。
langchain-openai：支持 OpenAI 模型的集成（可选，取决于使用的 LLM）。
langchain-tavily：Tavily 工具的 LangChain 集成。
tavily-python：Tavily 的官方 Python 客户端。

配置 API 密钥

Tavily 需要 API 密钥进行身份验证：

设置环境变量：

import os
import getpass

if not os.environ.get("TAVILY_API_KEY"):
    os.environ["TAVILY_API_KEY"] = getpass.getpass("请输入 Tavily API 密钥：")

或在 .env 文件中配置：

TAVILY_API_KEY=your-tavily-api-key

可选：LangSmith 集成

为启用最佳调试和监控，建议配置 LangSmith：

os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = getpass.getpass("请输入 LangSmith API 密钥：")

4. 核心组件

langchain_tavily 提供了两个主要工具：

(1) TavilySearch

功能：执行实时网络搜索，返回结构化结果。
参数：
- max_results（int）：最大返回结果数，默认 5。
- topic（str）：搜索主题，可选 “general”、“news”、“finance”，默认 “general”。
- search_depth（str）：搜索深度，可选 “basic” 或 “advanced”。
- include_images（bool）：是否包含图片。
- include_answer（bool）：是否包含对查询的直接回答（若支持）。
- include_domains（List[str]）：限制搜索的域名。
- exclude_domains（List[str]）：排除的域名。
- time_range（str）：时间过滤，如 “day”、“week”。
输出：JSON 格式，包含：
- query：查询字符串。
- results：列表，每个结果包含 title、url、content、score 等。
- response_time：搜索耗时。

(2) TavilyExtract

功能：从指定 URL 提取内容并返回结构化数据。
参数：
- urls（List[str]）：要提取的网页 URL。
- depth（str）：提取深度（“basic” 或 “advanced”）。
输出：JSON 格式，包含提取的文本、元数据等。

(3) 代理集成

Tavily 工具可绑定到 LangChain 代理（如 create_openai_tools_agent），通过 AgentExecutor 动态调用。

5. 使用方式与代码示例

(1) 单独使用 TavilySearch

from langchain_tavily import TavilySearch

# 初始化搜索工具
tool = TavilySearch(
    max_results=3,
    topic="general",
    search_depth="basic"
)

# 执行搜索
result = tool.invoke("量子计算的最新进展")
print(result)

输出（示例）：

{
  "query": "量子计算的最新进展",
  "results": [
    {
      "title": "Quantum Computing Breakthroughs in 2025",
      "url": "https://example.com/quantum-news",
      "content": "Recent advances in quantum computing include...",
      "score": 0.95
    },
    ...
  ],
  "response_time": 1.5
}

(2) 使用 TavilyExtract

from langchain_tavily import TavilyExtract

# 初始化提取工具
extract_tool = TavilyExtract()

# 提取网页内容
result = extract_tool.invoke({"urls": ["https://example.com/quantum-news"]})
print(result)

输出（示例）：

[
  {
    "url": "https://example.com/quantum-news",
    "content": "Full text of the webpage...",
    "metadata": {"title": "Quantum News", "author": "John Doe"}
  }
]

(3) 集成到代理

以下是一个结合 TavilySearch 和 TavilyExtract 的代理示例：

from langchain_openai import ChatOpenAI
from langchain_tavily import TavilySearch, TavilyExtract
from langchain.agents import create_openai_tools_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.callbacks import StdOutCallbackHandler
import datetime

# 初始化 LLM
llm = ChatOpenAI(model="gpt-4o", temperature=0, api_key="your-openai-key")

# 初始化工具
search_tool = TavilySearch(max_results=5, topic="general")
extract_tool = TavilyExtract()
tools = [search_tool, extract_tool]

# 设置提示模板
today = datetime.datetime.today().strftime("%D")
prompt = ChatPromptTemplate.from_messages([
    ("system", f"""You are a research assistant. Use tools to search and extract information. Today is {today}."""),
    MessagesPlaceholder(variable_name="messages"),
    MessagesPlaceholder(variable_name="agent_scratchpad")
])

# 创建代理
agent = create_openai_tools_agent(llm=llm, tools=tools, prompt=prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

# 执行任务
response = agent_executor.invoke({
    "messages": [{"role": "user", "content": "研究量子计算的最新进展并总结其对网络安全的潜在影响"}]
}, config={"callbacks": [StdOutCallbackHandler()]})

print(response["output"])

输出（示例）：

[AgentExecutor] 正在执行...
[Tool: TavilySearch] 输入：量子计算的最新进展
[Tool Output] 搜索结果包括...
[Tool: TavilyExtract] 输入：https://example.com/quantum-news
[Tool Output] 提取内容...
[Final Answer] 量子计算的最新进展包括... 对网络安全的影响可能涉及加密算法的破解...

6. 应用场景

langchain_tavily 适用于以下场景：

实时问答：
- 回答需要最新信息的查询，如“2025 年量子计算进展”。
- 示例：结合 TavilySearch 获取实时数据。
研究与分析：
- 提取网页内容进行深入分析。
- 示例：使用 TavilyExtract 分析学术文章。
智能代理：
- 构建能搜索和提取信息的虚拟助手。
- 示例：处理复杂查询，如“总结某领域的最新趋势”。
RAG 应用：
- 为 LLM 提供实时上下文，减少幻觉（hallucination）。
- 示例：结合向量存储和 TavilySearch 构建增强型问答系统。
内容生成：
- 生成基于最新信息的报告或文章。
- 示例：自动化生成行业动态摘要。
聊天机器人：
- 增强对话能力，回答动态问题。
- 示例：实时查询天气、新闻等。

7. 优化建议

(1) 提高搜索质量

优化查询：
- 使用语义清晰的查询，避免模糊表述。
- 示例：将“量子计算”改为“2025 年量子计算最新技术进展”。
调整参数：
- 设置 max_results 控制结果数量（建议 3-5）。
- 使用 search_depth="advanced" 获取更深入的结果。
- 指定 topic（如 “news”）聚焦特定领域。

过滤结果：

使用 include_domains 或 exclude_domains 限制来源。

search_tool = TavilySearch(include_domains=["arxiv.org", "nature.com"])

(2) 提高性能

缓存结果：

使用 LangChain 的缓存机制存储高频查询结果。

from langchain.globals import set_llm_cache
from langchain.cache import SQLiteCache
set_llm_cache(SQLiteCache(database_path="cache.db"))

异步调用：
- 使用 ainvoke 或 abatch 支持高并发。
```
result = await agent_executor.ainvoke(input)
```

批量处理：

批量执行多个查询，减少 API 调用。

results = agent_executor.batch([{"messages": [{"content": "q1"}]}, {"messages": [{"content": "q2"}]}])

(3) 错误处理

API 错误：

处理 Tavily API 的潜在错误（如密钥无效、配额超限）。

try:
    result = search_tool.invoke("query")
except Exception as e:
    print(f"搜索错误：{e}")
    result = fallback_search.invoke("query")

回退机制：

配置回退工具（如 DuckDuckGoSearch）。

from langchain_community.tools import DuckDuckGoSearchRun
search_tool_with_fallback = search_tool.with_fallbacks([DuckDuckGoSearchRun()])

验证输出：

检查搜索结果是否为空或不相关。

if not result["results"]:
    print("无相关结果")
    return fallback_result

(4) 监控与调试

LangSmith 集成：

记录搜索和提取的执行轨迹。

from langsmith import Client
config = {"callbacks": [Client(api_key="your-langsmith-key")]}
response = agent_executor.invoke(input, config=config)

自定义回调：

监控工具调用和结果。

from langchain_core.callbacks import BaseCallbackHandler
class ToolCallback(BaseCallbackHandler):
    def on_tool_start(self, serialized, input_str, **kwargs):
        print(f"工具 {serialized['name']} 开始，输入：{input_str}")
config = {"callbacks": [ToolCallback()]}

(5) 上下文管理

追加上下文：

将用户历史查询或偏好添加到搜索中。

history = "用户之前的查询：['量子计算是什么？']"
user_query = f"{history} 量子计算的最新进展是什么？"
result = search_tool.invoke(user_query)

结合向量存储：

使用 TavilySearchAPIRetriever 与向量存储（如 DeepLake）结合。

from langchain_community.retrievers import TavilySearchAPIRetriever
retriever = TavilySearchAPIRetriever(k=3)
docs = retriever.invoke("量子计算的最新进展")

8. 注意事项

API 密钥安全：
- 不要将 Tavily API 密钥硬编码到代码中，使用环境变量或密钥管理工具。
- 示例：使用 python-dotenv 加载 .env 文件。
配额限制：
- Tavily 提供每月 1000 次免费 API 调用，超出需付费。
- 监控使用量，避免超限。
模型兼容性：
- 代理集成需要支持工具调用的模型（如 GPT-4、Claude）。
- 避免使用不支持工具调用的模型（如某些开源模型）。
结果相关性：
- 搜索结果可能包含噪声，需后处理或过滤。
- 示例：根据 score 字段筛选高相关性结果。
性能：
- 高级搜索（search_depth="advanced"）可能增加延迟，需权衡。
- 限制 max_results 减少响应大小。
迁移警告：
- 旧版 langchain_community.tools.tavily_search 已废弃，推荐迁移到 langchain-tavily。
- 检查代码是否使用最新包。

9. 与 LangChain 生态的结合

链（Chains）：

将 TavilySearch 集成到 RAG 链，提供实时上下文。

from langchain.chains import RetrievalQA
retriever = TavilySearchAPIRetriever(k=3)
qa_chain = RetrievalQA.from_chain_type(llm, retriever=retriever)

代理（Agents）：
- 使用 AgentExecutor 动态调用 Tavily 工具。
```
agent = create_openai_tools_agent(llm, tools, prompt)
```
工具（Tools）：
- TavilySearch 和 TavilyExtract 可与其他工具（如 Wikipedia）结合。
```
tools = [search_tool, extract_tool, WikipediaTool()]
```
回调（Callbacks）：
- 使用 RunnableConfig 配置回调，监控 Tavily 工具执行。
```
config = {"callbacks": [StdOutCallbackHandler()]}
```
LangSmith：
- 分析搜索和提取的性能。

向量存储：

结合 TavilySearchAPIRetriever 和向量存储（如 DeepLake）增强 RAG。

from langchain_community.vectorstores import DeepLake
vectorstore = DeepLake(dataset_path="hub://user/dataset")

10. 综合示例：构建智能研究代理

以下是一个完整的代理示例，结合 TavilySearch 和 TavilyExtract，用于研究量子计算对网络安全的影响：

from langchain_openai import ChatOpenAI
from langchain_tavily import TavilySearch, TavilyExtract
from langchain.agents import create_openai_tools_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.callbacks import StdOutCallbackHandler
from langchain_core.runnables import RunnableConfig
import datetime
import os
import getpass

# 配置 API 密钥
if not os.environ.get("TAVILY_API_KEY"):
    os.environ["TAVILY_API_KEY"] = getpass.getpass("请输入 Tavily API 密钥：")

# 初始化 LLM
llm = ChatOpenAI(model="gpt-4o", temperature=0, api_key="your-openai-key")

# 初始化工具
search_tool = TavilySearch(
    max_results=3,
    topic="general",
    search_depth="advanced",
    include_domains=["arxiv.org", "nature.com"]
)
extract_tool = TavilyExtract()
tools = [search_tool, extract_tool]

# 设置提示模板
today = datetime.datetime.today().strftime("%D")
prompt = ChatPromptTemplate.from_messages([
    ("system", f"""You are a research assistant. Search the web and extract content to provide accurate answers. Today is {today}."""),
    MessagesPlaceholder(variable_name="messages"),
    MessagesPlaceholder(variable_name="agent_scratchpad")
])

# 创建代理
agent = create_openai_tools_agent(llm=llm, tools=tools, prompt=prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

# 配置 RunnableConfig
config = RunnableConfig(
    callbacks=[StdOutCallbackHandler()],
    max_iterations=5,
    max_execution_time=30.0,
    metadata={"request_id": "req_001"}
)

# 执行任务
response = agent_executor.invoke({
    "messages": [{"role": "user", "content": "研究量子计算的最新进展并总结其对网络安全的潜在影响"}]
}, config=config)

print(response["output"])

输出（示例）：

[AgentExecutor] 正在执行...
[Tool: TavilySearch] 输入：量子计算的最新进展
[Tool Output] 搜索结果包括...
[Tool: TavilyExtract] 输入：https://arxiv.org/abs/2501.12345
[Tool Output] 提取内容...
[Final Answer] 量子计算的最新进展包括超导量子比特的突破... 对网络安全的影响包括后量子加密的需求...