企业官网建设流程全解析

在 Haystack 中使用 LinkupWebSearch 组件：为 RAG 与 Agent 工作流接入 Linkup 搜索 API

【免费下载链接】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

Haystack 的LinkupWebSearch是linkup-haystack集成包提供的网络搜索组件，它封装了 Linkup Search API，将一次 Web 查询转换为结构化的 HaystackDocument列表与来源 URL 列表，可直接插入 RAG 流水线或作为 Agent 的工具使用。本文基于 Haystack 官方参考文档，结合组件用户指南与仓库源码，系统讲解该组件的初始化参数、run/run_async调用方式、depth三档搜索策略的取舍，以及它在典型 RAG 流水线中的接入方法。读完本文，你将能够独立完成LinkupWebSearch的安装、配置、单组件调用与流水线集成，并理解其与 HaystackSecret密钥机制、warm_up预热机制的配合方式。

组件概览：它是什么，能做什么

LinkupWebSearch是一个基于 Linkup Search API 的网络搜索组件。Linkup 是一个专为 LLM 应用优化的 Web 搜索 API，使用它需要先在 linkup.so 获取 API key。该组件位于haystack_integrations.components.websearch.linkup.linkup_websearch模块，作用是把用户的查询字符串发送给 Linkup，并把返回结果组织成两种输出：

• documents：搜索结果列表，每个结果是一个 HaystackDocument，其content为 Linkup 返回的文本内容，meta中携带结果的标题（title）与 URL；
• links：结果来源 URL 的字符串列表。

在流水线中的典型摆放位置有两种：一是放在ChatPromptBuilder之前，让搜索结果直接注入提示模板；二是放在索引流水线（indexing pipeline）的开头，把抓取到的网页内容作为待索引的原始资料。

组件层面的关键约束一览：

安装与密钥配置

LinkupWebSearch不在 Haystack 核心库中，需要单独安装集成包：

pip install linkup-haystack

密钥推荐通过环境变量管理。组件默认从LINKUP_API_KEY环境变量读取 key：

from haystack_integrations.components.websearch.linkup import LinkupWebSearch from haystack.utils import Secret websearch = LinkupWebSearch( api_key=Secret.from_env_var("LINKUP_API_KEY"), top_k=5, )

这里用到的Secret.from_env_var来自 Haystack 核心库的 haystack/utils/auth.py。Secret是一个抽象密封类，提供两种构造方式：

• Secret.from_env_var("LINKUP_API_KEY")：从环境变量读取密钥，支持传入多个候选环境变量并按顺序解析，strict=True时若均未设置会抛出异常；
• Secret.from_token("...")：直接以字符串形式注入 token，注意 token 型 Secret 不可序列化。

采用环境变量的好处是密钥不会写进代码或序列化后的流水线 YAML/JSON 中，且Secret本身实现了to_dict/from_dict，可以在流水线序列化与反序列化时保持安全。

初始化参数详解

__init__的完整签名如下：

__init__( api_key: Secret = Secret.from_env_var("LINKUP_API_KEY"), top_k: int | None = 10, depth: Literal["fast", "standard", "deep"] = "standard", search_params: dict[str, Any] | None = None, ) -> None

api_key

类型为Secret，默认值是Secret.from_env_var("LINKUP_API_KEY")。也就是说，只要设置了LINKUP_API_KEY环境变量，甚至可以不传api_key直接实例化组件。

top_k

类型为int | None，默认10，表示最多返回的结果条数，直接映射到 Linkup API 的max_results参数。传None时表示不限制（交由 API 默认行为决定）。

depth

类型为Literal["fast", "standard", "deep"]，默认"standard"，控制搜索深度，是在延迟与全面性之间做取舍的关键参数：

• "fast"（beta）：仅支持基于关键词的查询，响应时间在亚秒级（sub-second），适合对延迟极度敏感的场景；
• "standard"：单次搜索流程，是默认选项，兼顾速度与质量；
• "deep"：运行一个更强大的 agentic 工作流，搜索更深入、耗时更长，适合对结果质量要求高的复杂查询。

search_params

类型为dict[str, Any] | None，默认None，用于向 Linkup 搜索 API 透传额外参数，官方支持的键包括：

运行期覆盖（override）语义

top_k、depth、search_params三个参数都可以在调用run()时按单次查询覆盖。特别要注意：传给run()的search_params字典会整体替换初始化时设置的search_params，而不是与它合并。如果你在初始化时配置了include_domains，又在某次run()中只传了from_date，那么这次请求将不再携带include_domains。

调用方式：warm_up、run 与 run_async

warm_up：预热客户端

warm_up() -> None

warm_up()用于初始化 Linkup 客户端。底层客户端采用懒加载策略，即在第一次搜索时才创建，这会导致首次调用存在冷启动延迟。你可以显式调用warm_up()提前完成客户端初始化，把冷启动开销转移到请求到来之前（例如在流水线构建完成后、正式运行前统一预热）。

run：同步搜索

run( query: str, top_k: int | None = None, depth: Literal["fast", "standard", "deep"] | None = None, search_params: dict[str, Any] | None = None, ) -> dict[str, Any]

参数说明：

• query（str）：搜索查询字符串，必填；
• top_k（int | None）：单次运行覆盖的最大结果数，不传则使用初始化时的top_k；
• depth（Literal['fast', 'standard', 'deep'] | None）：单次运行覆盖的搜索深度，不传则使用初始化时的depth；
• search_params（dict[str, Any] | None）：单次运行覆盖的搜索参数，提供即整体替换初始化时的配置。

返回值为一个字典，包含两个键：

• documents：包含搜索结果内容的Document列表；
• links：搜索结果 URL 列表。

最小可用示例：

from haystack_integrations.components.websearch.linkup import LinkupWebSearch from haystack.utils import Secret websearch = LinkupWebSearch( api_key=Secret.from_env_var("LINKUP_API_KEY"), top_k=5, ) result = websearch.run(query="What is Haystack by deepset?") documents = result["documents"] links = result["links"]

run_async：异步搜索

run_async( query: str, top_k: int | None = None, depth: Literal["fast", "standard", "deep"] | None = None, search_params: dict[str, Any] | None = None, ) -> dict[str, Any]

run_async是run的异步版本，签名与返回结构完全一致，适合在异步应用（如基于asyncio的 Web 服务或 Agent 运行时）中调用，避免阻塞事件循环。在并发执行多条搜索或需要高吞吐的在线服务中，优先使用异步调用。

实战一：单组件使用

将组件独立使用，遍历返回的文档，打印每个结果的 URL 与内容：

from haystack_integrations.components.websearch.linkup import LinkupWebSearch from haystack.utils import Secret web_search = LinkupWebSearch( api_key=Secret.from_env_var("LINKUP_API_KEY"), top_k=5, depth="standard", ) query = "What is Haystack by deepset?" response = web_search.run(query=query) for doc in response["documents"]: print(doc.meta["url"]) print(doc.content)

这段代码展示了两个关键事实：

1. 结果Document的meta中包含url字段（以及标题），可以直接用于溯源展示；
2. 组件输出是标准的 HaystackDocument对象，因此天然可以接入任何下游消费Document的组件（如文档存储、提示构建器等）。

实战二：接入 RAG 流水线

LinkupWebSearch最常见的用法是作为 RAG 流水线的检索前端：先用它搜索网页拿到实时资料，再把资料注入提示模板交给 LLM 生成回答。完整示例：

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.linkup import LinkupWebSearch from haystack.dataclasses import ChatMessage web_search = LinkupWebSearch( api_key=Secret.from_env_var("LINKUP_API_KEY"), top_k=3, ) 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( template=prompt_template, required_variables={"query", "documents"}, ) llm = OpenAIChatGenerator( api_key=Secret.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)

这条流水线的数据流为：search.documents→prompt_builder.documents→prompt_builder.prompt→llm.messages。ChatPromptBuilder使用 Jinja2 模板遍历documents变量，把每条搜索结果的content拼进提示词；query同时作为search与prompt_builder的输入，通过pipe.run(data=...)传入。

由于该组件的位置在流水线早期且输出为标准Document，你还可以基于它扩展出更复杂的拓扑，例如：

• 在search与prompt_builder之间插入DocumentJoiner或MetadataRouter，对搜索结果做合并或路由；
• 将documents写入文档存储，构成"实时搜索 + 持久化索引"的混合索引流水线；
• 把LinkupWebSearch包装为工具（Tool），交给 Agent 在推理过程中自主决定何时调用外部搜索。

在 Agent 工作流中的应用要点

从组件输出结构看，documents携带内容、links携带来源 URL，这种"内容 + 溯源"的组合非常适合 Agent 场景：

• Agent 调用搜索工具后，可将documents内容作为上下文证据，把links作为引用来源一并返回给用户，满足可溯源要求；
• depth="deep"的 agentic 搜索工作流本身就会执行多步检索推理，适合 Agent 处理开放式、多跳问题；对确定性高的关键词查询则用"fast"降低延迟；
• search_params中的include_domains/exclude_domains可约束 Agent 的搜索范围，例如只允许检索指定权威站点，减少低质量信息进入上下文。

常见问题与注意事项

• 图片结果没有文本：开启include_images后，返回的图片结果Document的content为空，下游处理时需注意判空，避免向 LLM 注入空内容。
• search_params的覆盖语义：run()中传入的search_params整体替换而非合并初始化配置，混用两处配置时务必确认预期行为。
• 冷启动：首次调用会触发客户端懒加载，生产环境建议在服务启动阶段显式调用warm_up()。
• 密钥安全：优先使用LINKUP_API_KEY环境变量配合Secret.from_env_var；Secret.from_token传入的 token 不可序列化，不应写入持久化配置。
• depth="fast"为 beta 能力：文档明确标注其仅支持关键词查询，复杂语义查询请使用"standard"或"deep"。

参考路径

• 组件参考文档：docs-website/reference/integrations-api/linkup.md
• 组件用户指南（含流水线示例）：docs-website/docs/pipeline-components/websearch/linkupwebsearch.mdx
• WebSearch 组件家族总览：docs-website/docs/pipeline-components/websearch.mdx
• Secret密钥封装源码：haystack/utils/auth.py

【免费下载链接】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