Haystack Tavily 集成完全指南网页搜索、URL 内容提取与 Agent 工具【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystackTavily 是专为 LLM 应用优化的 AI 搜索与网页提取 API。本文围绕tavily-haystack集成包系统讲解 Haystack 生态中的三大 Tavily 组件TavilyFetcher基于 Tavily Extract API 抓取并解析指定 URL、TavilyWebSearch基于 Tavily Search API 执行网页搜索以及TavilyWebSearchTool把搜索能力封装为可被 Agent 调用的工具。读完本文你将掌握这三个组件的初始化参数、同步/异步调用方式、管线编排、Agent 集成以及资源生命周期管理并能在 RAG 与检索增强型 Agent 应用中直接落地。本文以 docs-website/reference/integrations-api/tavily.md 为骨架并对照配套用户指南TavilyFetcher、TavilyWebSearch、TavilyWebSearchTool与 Haystack 核心源码展开。安装与前置条件Tavily 集成以独立包tavily-haystack发布使用前需要安装pip install tavily-haystack使用任何 Tavily 组件都需要 API Key。你需要先在 Tavily 官网注册账号获取 API KeyTavily 是面向 LLM 应用的 AI 搜索与提取 API官网对开发者提供免费额度。推荐通过环境变量注入Haystack 的Secret机制会在运行时解析它from haystack.utils import Secret # 默认方式从环境变量 TAVILY_API_KEY 读取 api_key Secret.from_env_var(TAVILY_API_KEY) # 显式方式直接传入 token注意TokenSecret 不可序列化 api_key Secret.from_token(your-api-key)Secret类定义于 haystack/utils/auth.py其from_env_var方法haystack/utils/auth.py支持传入单个或多个环境变量名按顺序取第一个已设置的并可通过strict参数控制未设置时是否抛异常。三个 Tavily 组件的api_key参数默认值均为Secret.from_env_var(TAVILY_API_KEY)。一、TavilyFetcher从指定 URL 提取网页内容模块路径haystack_integrations.components.fetchers.tavily.tavily_fetcherTavilyFetcher封装了 Tavily Extract API用于从一个或多个指定 URL抓取并解析网页内容生成 HaystackDocument。它与网页搜索的本质区别是搜索通过查询词发现URL而TavilyFetcher直接提取你已拥有的 URL 内容。此外PDF 格式的 URL 同样受支持这使它非常适合作为文档采集indexing环节的数据获取步骤。初始化参数TavilyFetcher( api_key: Secret Secret.from_env_var(TAVILY_API_KEY), *, extract_depth: Literal[basic, advanced] basic, include_images: bool False, extract_params: dict[str, Any] | None None )参数类型默认值说明api_keySecretTAVILY_API_KEY环境变量Tavily API Keyextract_depthbasic/advancedbasicbasic速度快、成本低advanced返回更多数据含表格延迟与成本更高include_imagesboolFalse为True时提取到的图片 URL 会写入每个 Document 的meta[images]extract_paramsdict[str, Any] \| NoneNone透传给 Tavily Extract API 的额外参数如format、include_favicon、query、chunks_per_source等可用选项以 Tavily Extract API 参考文档为准run 方法run( urls: list[str], extract_params: dict[str, Any] | None None ) - dict[str, Any]urls待提取内容的 URL 列表每次请求最多 20 个 URLextract_params单次运行时的提取参数覆盖。注意其语义是完全替换而非合并——一旦传入初始化时的extract_params将整体失效。返回值为一个字典documentsDocument列表每个 Document 的content为提取到的页面正文meta中包含url字段若include_imagesTrue还包含images字段meta请求级元数据包含response_time响应耗时、usage用量信息、request_id请求 ID以及failed_results未能处理的 URL 列表可用于诊断失败项。独立使用from haystack_integrations.components.fetchers.tavily import TavilyFetcher fetcher TavilyFetcher(extract_depthbasic) result fetcher.run(urls[https://docs.haystack.deepset.ai/docs/intro]) documents result[documents] meta result[meta] for doc in documents: print(f{doc.meta.get(url)}: {len(doc.content or )} chars) print(failed:, meta.get(failed_results))在索引管线中使用TavilyFetcher最常见的定位是索引管线或查询管线的数据获取步骤。下面是一个完整示例抓取文档页 → 按句子切分 → 写入InMemoryDocumentStorefrom haystack import Pipeline from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.components.preprocessors import DocumentSplitter from haystack.components.writers import DocumentWriter from haystack_integrations.components.fetchers.tavily import TavilyFetcher document_store InMemoryDocumentStore() fetcher TavilyFetcher(extract_depthbasic) splitter DocumentSplitter(split_bysentence, split_length5) writer DocumentWriter(document_storedocument_store) indexing_pipeline Pipeline() indexing_pipeline.add_component(fetcher, fetcher) indexing_pipeline.add_component(splitter, splitter) indexing_pipeline.add_component(writer, writer) indexing_pipeline.connect(fetcher.documents, splitter.documents) indexing_pipeline.connect(splitter.documents, writer.documents) indexing_pipeline.run( data{ fetcher: { urls: [https://docs.haystack.deepset.ai/docs/intro], }, }, )TavilyFetcher与TavilyWebSearch是互补关系搜索负责从查询发现 URL提取器负责从已知 URL 取全文二者可以串联——先用搜索找到相关页面再用提取器抓取全文送入索引。异步执行与生命周期管理TavilyFetcher支持异步执行import asyncio from haystack_integrations.components.fetchers.tavily import TavilyFetcher fetcher TavilyFetcher() async def fetch(): result await fetcher.run_async( urls[https://docs.haystack.deepset.ai/docs/intro], ) return result[documents] documents asyncio.run(fetch())底层 Tavily 客户端采用惰性初始化同步客户端与异步客户端分别由warm_up()与warm_up_async()创建首次调用时自动触发。如果希望规避首次调用的冷启动延迟可以显式调用warm_up()预热。与之对应的资源释放方法为close()关闭同步客户端与close_async()关闭异步客户端。warm_up/close的幂等调用模式与 Haystack 其他组件保持一致可安全地在管线的 warm-up 阶段统一预热。二、TavilyWebSearch面向 LLM 的网页搜索模块路径haystack_integrations.components.websearch.tavily.tavily_websearchTavilyWebSearch封装 Tavily Search API根据查询词搜索网页并把结果整理为结构化的 HaystackDocument含内容与来源链接。Tavily 返回的是干净、去噪的相关片段非常契合 RAG 管线检索—增强—生成的检索环节。初始化参数TavilyWebSearch( api_key: Secret Secret.from_env_var(TAVILY_API_KEY), top_k: int | None 10, search_params: dict[str, Any] | None None, )参数类型默认值说明api_keySecretTAVILY_API_KEY环境变量Tavily API Keytop_kint \| None10返回的最大结果数search_paramsdict[str, Any] \| NoneNone透传给 Tavily Search API 的额外参数。受支持的键包括search_depth搜索深度、include_answer是否附带直接答案、include_raw_content是否包含原始内容、include_domains限定搜索的域名白名单、exclude_domains排除的域名黑名单等完整选项以 Tavily API 参考文档为准run 方法run( query: str, search_params: dict[str, Any] | None None ) - dict[str, Any]query搜索查询词字符串search_params单次运行的搜索参数覆盖语义同样是完全替换初始化时的search_params。返回值documentsDocument列表包含搜索结果内容content及相关元数据links搜索结果的 URL 字符串列表便于直接引用来源。异步版本run_async签名与返回值完全一致适用于asyncio场景。同样提供warm_up()/warm_up_async()/close()/close_async()生命周期方法。独立使用from haystack_integrations.components.websearch.tavily import TavilyWebSearch from haystack.utils import Secret web_search TavilyWebSearch( api_keySecret.from_env_var(TAVILY_API_KEY), top_k5, ) query What is Haystack by deepset? response web_search.run(queryquery) for doc in response[documents]: print(doc.content)在 RAG 管线中使用TavilyWebSearch的典型位置是ChatPromptBuilder之前或索引管线的开头。下面是一个完整的联网 RAG 示例搜索 → 组装提示 → 生成回答from haystack import Pipeline from haystack.utils import Secret from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder from haystack.components.generators.chat import OpenAIChatGenerator from haystack_integrations.components.websearch.tavily import TavilyWebSearch from haystack.dataclasses import ChatMessage web_search TavilyWebSearch( api_keySecret.from_env_var(TAVILY_API_KEY), top_k3, ) prompt_template [ ChatMessage.from_system(You are a helpful assistant.), ChatMessage.from_user( Given the information below:\n {% for document in documents %}{{ document.content }}\n{% endfor %}\n Answer the following question: {{ query }}.\nAnswer:, ), ] prompt_builder ChatPromptBuilder( templateprompt_template, required_variables{query, documents}, ) llm OpenAIChatGenerator( api_keySecret.from_env_var(OPENAI_API_KEY), ) pipe Pipeline() pipe.add_component(search, web_search) pipe.add_component(prompt_builder, prompt_builder) pipe.add_component(llm, llm) pipe.connect(search.documents, prompt_builder.documents) pipe.connect(prompt_builder.prompt, llm.messages) query What is Haystack by deepset? result pipe.run(data{search: {query: query}, prompt_builder: {query: query}}) print(result[llm][replies][0].text)三、TavilyWebSearchTool把搜索交给 Agent模块路径haystack_integrations.tools.tavily.websearch_toolTavilyWebSearchTool继承自 Haystack 的ComponentTool定义于 haystack/tools/component_tool.py它把TavilyWebSearch组件包装成可供 LLM 调用的工具并将结果格式化为带来源引用的字符串每个结果包含标题、精确 URL 与内容片段方便 LLM 直接引用出处。工作原理从组件 run 签名自动生成工具 Schema从源码看ComponentTool会自动读取组件的输入 socket源自run方法签名与类型注解用 Pydantic 动态构建 LLM 兼容的 JSON Schema见 haystack/tools/component_tool.py并在被调用时把 LLM 传入的参数按 socket 类型转换后转发给组件haystack/tools/component_tool.py。因此TavilyWebSearchTool的工具参数天然就是TavilyWebSearch.run()的参数LLM 可以传入query并按需传入search_params覆盖初始化时设定的参数。若组件支持异步__haystack_supports_async__为真ComponentTool还会注册对应的异步调用器使 Agent 能够异步调用该工具。初始化参数所有参数均为 keyword-onlyTavilyWebSearchTool( *, api_key: Secret | None None, top_k: int | None None, search_params: dict[str, Any] | None None, name: str web_search, description: str _DEFAULT_DESCRIPTION )参数类型默认值说明api_keySecret \| NoneNoneTavily API Key。未设置时由内部TavilyWebSearch读取TAVILY_API_KEY环境变量top_kint \| NoneNone返回的最大结果数。未设置时采用TavilyWebSearch的默认值search_paramsdict[str, Any] \| NoneNone透传给 Tavily Search API 的额外参数支持键同上search_depth、include_answer、include_raw_content、include_domains、exclude_domains等namestrweb_search暴露给 LLM 的工具名称descriptionstr内置默认描述暴露给 LLM 的工具描述帮助模型判断何时调用独立调用from haystack_integrations.tools.tavily import TavilyWebSearchTool tool TavilyWebSearchTool(top_k3) result tool.invoke(queryWhat is Haystack by deepset?) for document in result[documents]: print(document.meta[title], -, document.meta[url])输出示例搜索结果会随时间变化GitHub - deepset-ai/haystack: Open-source AI orchestration framework ... - https://github.com/deepset-ai/haystack deepset - Wikipedia - https://en.wikipedia.org/wiki/Deepset Haystack | Haystack - https://haystack.deepset.ai与 Agent 结合TavilyWebSearchTool最常见的用法是作为Agent的工具Agent定义于 haystack/components/agents/agent.py在推理循环中判断需要实时信息时会自动调用该工具搜索网页并把结果纳入上下文继续生成from haystack.components.agents import Agent from haystack.components.generators.chat import OpenAIChatGenerator from haystack.dataclasses import ChatMessage from haystack_integrations.tools.tavily import TavilyWebSearchTool web_search TavilyWebSearchTool(top_k5, search_params{search_depth: advanced}) agent Agent( chat_generatorOpenAIChatGenerator(modelgpt-5-mini), tools[web_search], ) result agent.run(messages[ChatMessage.from_user(What is Haystack by deepset?)]) print(result[last_message].text)由于工具参数派生自组件run方法Agent 可以让 LLM 在调用时动态传入query甚至用search_params覆盖初始化参数例如临时加深搜索深度。序列化支持TavilyWebSearchTool实现了标准的 Haystack 序列化协议to_dict() - dict[str, Any]把工具序列化为字典。从ComponentTool的实现看haystack/tools/component_tool.py序列化结果会包含被包裹组件的完整序列化数据component_to_dict、name、description、parameters、以及可选的inputs_from_state/outputs_to_state/outputs_to_string便于整条管线/Agent 配置持久化from_dict(data: dict[str, Any]) - TavilyWebSearchTool从字典反序列化返回TavilyWebSearchTool实例。反序列化时会先就地还原内部组件haystack/tools/component_tool.py确保工具与其依赖的组件一起被正确恢复。四、实战案例基于 Tavily 的 Deep Research AgentTavily 组件在 Haystack 生态中的一个典型高级用法是Deep Research Agent深度研究代理属于实验性 Agent Pack其完整说明见 docs-website/docs/pipeline-components/agents-1/agent-pack/deep-research-agent.mdx给它一个问题它会自主检索多个网页来源并产出带引用的结构化 Markdown 研究报告。安装时需一并安装其运行时依赖pip install agent-pack-haystack tavily-haystack trafilatura pypdf arrow并设置OPENAI_API_KEY与TAVILY_API_KEY环境变量。其核心架构中每个子研究者sub-researcher默认使用TavilyWebSearchTool(top_k10)作为web_search工具read_url工具则通过PipelineTool封装了一条抓取 → 按 MIME 类型路由 → HTML/PDF 转文本 → 摘要的管线。这正是前文三个 Tavily 组件的协同场景TavilyWebSearchTool负责发现相关页面URL 提取链路负责获取全文PDF 亦可解析最终只有压缩后的带引用摘要进入主 Agent 的上下文从而控制上下文规模、保证报告质量。from haystack.dataclasses import ChatMessage from haystack_integrations.agent_pack import create_deep_research_agent agent create_deep_research_agent() result agent.run(messages[ChatMessage.from_user(your research question)]) print(result[report])五、最佳实践与常见注意点综合前述 API 语义与源码实现使用 Tavily 集成时建议注意以下几点API Key 优先走环境变量。三个组件默认都从TAVILY_API_KEY读取密钥配合Secret.from_env_var可避免密钥硬编码若使用Secret.from_token直接传 token需注意TokenSecret不可序列化见 haystack/utils/auth.py这会影响管线的持久化/反序列化。run()的参数覆盖是完全替换。TavilyFetcher.run的extract_params与TavilyWebSearch.run的search_params一旦传入会整体替换初始化时设置的字典而不是合并。若需要合并语义请在调用前自行把初始化参数与运行参数合并后再传入。注意单请求 URL 上限。TavilyFetcher.run的urls每次请求最多 20 个 URL批量抓取时需分批调用或循环处理。善用meta中的失败信息。TavilyFetcher返回的meta[failed_results]会列出无法处理的 URL索引任务结束后务必检查该字段避免静默丢数据。控制成本与延迟。extract_depthbasic速度快、成本低适合大多数页面advanced能提取更多数据含表格仅在确实需要时使用。显式预热以消除冷启动。底层客户端惰性创建若对首轮调用延迟敏感可在管线 warm-up 阶段显式调用warm_up()/warm_up_async()。在 Agent 场景善用search_params精化搜索。include_domains/exclude_domains可约束搜索来源域search_depth可权衡速度与召回这些都能显著影响 RAG 与 Agent 的检索质量。三个组件互为补充、覆盖了搜索发现—内容提取—Agent 调用的完整链路是构建联网 RAG、语义检索与检索型 Agent 应用的高效基础件。相关参考文档可继续查阅 docs-website/reference/integrations-api/tavily.md 及各组件用户指南。【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考