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

作者：彬彬侠
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 需要以下依赖：

1. 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 密钥进行身份验证：

注册 Tavily 账户并获取 API 密钥：https://tavily.com。

• 设置环境变量：
  1. import os
  2. import getpass
  4. ifnot os.environ.get("TAVILY_API_KEY"):
  5.     os.environ["TAVILY_API_KEY"]= getpass.getpass("请输入 Tavily API 密钥：")

  复制代码
  或在 .env 文件中配置：
  1. TAVILY_API_KEY=your-tavily-api-key

  复制代码

可选：LangSmith 集成

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

1. os.environ["LANGCHAIN_TRACING_V2"]="true"
2. 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

1. from langchain_tavily import TavilySearch
3. # 初始化搜索工具
4. tool = TavilySearch(
5.     max_results=3,
6.     topic="general",
7.     search_depth="basic")# 执行搜索
8. result = tool.invoke("量子计算的最新进展")print(result)

复制代码

输出（示例）：

1. {"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

1. from langchain_tavily import TavilyExtract
3. # 初始化提取工具
4. extract_tool = TavilyExtract()# 提取网页内容
5. result = extract_tool.invoke({"urls":["https://example.com/quantum-news"]})print(result)

复制代码

输出（示例）：

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

复制代码

(3) 集成到代理

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

1. from langchain_openai import ChatOpenAI
2. from langchain_tavily import TavilySearch, TavilyExtract
3. from langchain.agents import create_openai_tools_agent, AgentExecutor
4. from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
5. from langchain_core.callbacks import StdOutCallbackHandler
6. import datetime
8. # 初始化 LLM
9. llm = ChatOpenAI(model="gpt-4o", temperature=0, api_key="your-openai-key")# 初始化工具
10. search_tool = TavilySearch(max_results=5, topic="general")
11. extract_tool = TavilyExtract()
12. tools =[search_tool, extract_tool]# 设置提示模板
13. today = datetime.datetime.today().strftime("%D")
14. prompt = ChatPromptTemplate.from_messages([("system",f"""You are a research assistant. Use tools to search and extract information. Today is {today}."""),
15.     MessagesPlaceholder(variable_name="messages"),
16.     MessagesPlaceholder(variable_name="agent_scratchpad")])# 创建代理
17. agent = create_openai_tools_agent(llm=llm, tools=tools, prompt=prompt)
18. agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)# 执行任务
19. response = agent_executor.invoke({"messages":[{"role":"user","content":"研究量子计算的最新进展并总结其对网络安全的潜在影响"}]}, config={"callbacks":[StdOutCallbackHandler()]})print(response["output"])

复制代码

输出（示例）：

1. [AgentExecutor] 正在执行...
2. [Tool: TavilySearch] 输入：量子计算的最新进展
3. [Tool Output] 搜索结果包括...
4. [Tool: TavilyExtract] 输入：https://example.com/quantum-news
5. [Tool Output] 提取内容...
6. [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 限制来源。
  
  1. search_tool = TavilySearch(include_domains=["arxiv.org","nature.com"])

  复制代码

(2) 提高性能

• 缓存结果：
  
  使用 LangChain 的缓存机制存储高频查询结果。
  
  1. from langchain.globalsimport set_llm_cache
  2. from langchain.cache import SQLiteCache
  3. set_llm_cache(SQLiteCache(database_path="cache.db"))

  复制代码
• 异步调用：
  
  使用 ainvoke 或 abatch 支持高并发。
  
  1. result =await agent_executor.ainvoke(input)

  复制代码
• 批量处理：
  
  批量执行多个查询，减少 API 调用。
  
  1. results = agent_executor.batch([{"messages":[{"content":"q1"}]},{"messages":[{"content":"q2"}]}])

  复制代码

(3) 错误处理

• API 错误：
  
  处理 Tavily API 的潜在错误（如密钥无效、配额超限）。
  
  1. try:
  2.     result = search_tool.invoke("query")except Exception as e:print(f"搜索错误：{e}")
  3.     result = fallback_search.invoke("query")

  复制代码
• 回退机制：
  
  配置回退工具（如 DuckDuckGoSearch）。
  
  1. from langchain_community.tools import DuckDuckGoSearchRun
  2. search_tool_with_fallback = search_tool.with_fallbacks([DuckDuckGoSearchRun()])

  复制代码
• 验证输出：
  
  检查搜索结果是否为空或不相关。
  
  1. ifnot result["results"]:print("无相关结果")return fallback_result

  复制代码

(4) 监控与调试

• LangSmith 集成：
  
  记录搜索和提取的执行轨迹。
  
  1. from langsmith import Client
  2. config ={"callbacks":[Client(api_key="your-langsmith-key")]}
  3. response = agent_executor.invoke(input, config=config)

  复制代码
• 自定义回调：
  
  监控工具调用和结果。
  
  1. from langchain_core.callbacks import BaseCallbackHandler
  2. classToolCallback(BaseCallbackHandler):defon_tool_start(self, serialized, input_str,**kwargs):print(f"工具 {serialized['name']} 开始，输入：{input_str}")
  3. config ={"callbacks":[ToolCallback()]}

  复制代码

(5) 上下文管理

• 追加上下文：
  
  将用户历史查询或偏好添加到搜索中。
  
  1. history ="用户之前的查询：['量子计算是什么？']"
  2. user_query =f"{history} 量子计算的最新进展是什么？"
  3. result = search_tool.invoke(user_query)

  复制代码
• 结合向量存储：
  
  使用 TavilySearchAPIRetriever 与向量存储（如 DeepLake）结合。
  
  1. from langchain_community.retrievers import TavilySearchAPIRetriever
  2. retriever = TavilySearchAPIRetriever(k=3)
  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 链，提供实时上下文。
  
  1. from langchain.chains import RetrievalQA
  2. retriever = TavilySearchAPIRetriever(k=3)
  3. qa_chain = RetrievalQA.from_chain_type(llm, retriever=retriever)

  复制代码
• 代理（Agents）：
  
  使用 AgentExecutor 动态调用 Tavily 工具。
  
  1. agent = create_openai_tools_agent(llm, tools, prompt)

  复制代码
• 工具（Tools）：
  
  TavilySearch 和 TavilyExtract 可与其他工具（如 Wikipedia）结合。
  
  1. tools =[search_tool, extract_tool, WikipediaTool()]

  复制代码
• 回调（Callbacks）：
  
  使用 RunnableConfig 配置回调，监控 Tavily 工具执行。
  
  1. config ={"callbacks":[StdOutCallbackHandler()]}

  复制代码
• LangSmith：
  
  分析搜索和提取的性能。
  
  
  
• 向量存储：
  
  结合 TavilySearchAPIRetriever 和向量存储（如 DeepLake）增强 RAG。
  
  1. from langchain_community.vectorstores import DeepLake
  2. vectorstore = DeepLake(dataset_path="hub://user/dataset")

  复制代码

---

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

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

1. from langchain_openai import ChatOpenAI
2. from langchain_tavily import TavilySearch, TavilyExtract
3. from langchain.agents import create_openai_tools_agent, AgentExecutor
4. from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
5. from langchain_core.callbacks import StdOutCallbackHandler
6. from langchain_core.runnables import RunnableConfig
7. import datetime
8. import os
9. import getpass
11. # 配置 API 密钥ifnot os.environ.get("TAVILY_API_KEY"):
12.     os.environ["TAVILY_API_KEY"]= getpass.getpass("请输入 Tavily API 密钥：")# 初始化 LLM
13. llm = ChatOpenAI(model="gpt-4o", temperature=0, api_key="your-openai-key")# 初始化工具
14. search_tool = TavilySearch(
15.     max_results=3,
16.     topic="general",
17.     search_depth="advanced",
18.     include_domains=["arxiv.org","nature.com"])
19. extract_tool = TavilyExtract()
20. tools =[search_tool, extract_tool]# 设置提示模板
21. today = datetime.datetime.today().strftime("%D")
22. prompt = ChatPromptTemplate.from_messages([("system",f"""You are a research assistant. Search the web and extract content to provide accurate answers. Today is {today}."""),
23.     MessagesPlaceholder(variable_name="messages"),
24.     MessagesPlaceholder(variable_name="agent_scratchpad")])# 创建代理
25. agent = create_openai_tools_agent(llm=llm, tools=tools, prompt=prompt)
26. agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)# 配置 RunnableConfig
27. config = RunnableConfig(
28.     callbacks=[StdOutCallbackHandler()],
29.     max_iterations=5,
30.     max_execution_time=30.0,
31.     metadata={"request_id":"req_001"})# 执行任务
32. response = agent_executor.invoke({"messages":[{"role":"user","content":"研究量子计算的最新进展并总结其对网络安全的潜在影响"}]}, config=config)print(response["output"])

复制代码

输出（示例）：

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

复制代码

---

11. 学习资源

Tavily 官方文档：https://docs.tavily.comLangChain 文档：https://python.langchain.com/docs/integrations/tools/tavily_searchGitHub 仓库：https://github.com/tavily-ai/langchain-tavilyTavily API 参考：https://docs.tavily.com/documentation/api-reference/endpoint/search社区教程：Medium 文章、LangChain 博客、YouTube 视频。

---

12. 总结

定义：langchain_tavily 是 LangChain 与 Tavily 搜索 API 的集成包，提供实时搜索和内容提取工具。

• 核心组件：
  
  TavilySearch：实时网络搜索。TavilyExtract：网页内容提取。代理集成：动态工具调用。
  
  功能：语义搜索、结构化输出、RAG 优化、代理支持。安装与配置：需要 langchain-tavily、tavily-python 和 API 密钥。应用场景：实时问答、研究分析、智能代理、RAG、内容生成、聊天机器人。优化点：搜索质量、性能、错误处理、监控、上下文管理。注意事项：API 密钥安全、配额限制、模型兼容性、结果相关性、性能、迁移警告。
  

原文地址：https://blog.csdn.net/u013172930/article/details/147980268