Haystack 中 DDGSWebSearch 集成指南免密钥的多引擎网络搜索组件实战【免费下载链接】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 生态中的DDGSWebSearch网络搜索组件展开介绍如何基于 ddgsDux Distributed Global Search这个免费、无需 API Key 的元搜索引擎库在 Haystack 管道中完成多引擎DuckDuckGo、Google、Bing、Brave、Yahoo、Yandex、Mullvad 等搜索结果采集。读完本文你将掌握DDGSWebSearch的安装方式、全部初始化参数与运行时参数、同步run()与异步run_async()的调用约定并能在 RAG 管道中直接落地使用。本文以 版本 2.18 的 ddgs API 参考 为骨架结合 DDGSWebSearch 组件指南 与 WebSearch 组件索引 中的信息展开。DDGSWebSearch 是什么DDGSWebSearch是 Haystack 的一个网络搜索组件位于haystack_integrations.components.websearch.ddgs模块包名为ddgs-haystack。它接收一个查询字符串调用 ddgs 库在网络上执行搜索并把结果片段以 Haystack 的Document对象返回同时返回一个源 URL 字符串列表。它与 Haystack 生态中其他 WebSearch 组件如 BraveWebSearch、SerperDevWebSearch、TavilyWebSearch、SearchApiWebSearch 等见 WebSearch 组件索引最大的区别在于不需要 API Key也不需要注册任何账号。ddgs 是一个免费的元搜索metasearch库它直接查询公共搜索引擎并聚合结果其后台backend覆盖 DuckDuckGo、Google、Bing、Brave、Yahoo、Yandex、Mullvad 等多个引擎因此组件本身完全免密钥、免账户即可运行。这也是文档将其定位为「free, keyless」的原因。安装要使用DDGSWebSearch需要先安装ddgs-haystack集成包pip install ddgs-haystack安装完成后即可从haystack_integrations命名空间导入组件注意这是集成包路径与核心haystack包分开维护from haystack_integrations.components.websearch.ddgs import DDGSWebSearch初始化参数详解DDGSWebSearch的构造函数签名如下默认值来自 API 参考__init__( top_k: int 10, backend: str auto, region: str us-en, safesearch: str moderate, search_params: dict[str, Any] | None None, ) - None参数类型默认值说明top_kint10最多返回的结果数量。backendstrauto逗号分隔的 ddgs 后端列表例如duckduckgo, google, brave传auto时由 ddgs 自行选择后端。完整后端列表以 ddgs 库文档为准。regionstrus-en搜索的区域/语言环境例如us-en、de-de或wt-wt表示不限定区域。safesearchstrmoderate安全搜索级别取值为on、moderate、off三者之一。search_paramsdict[str, Any] \| NoneNone额外透传给底层DDGS().text()的关键字参数例如page翻页或timelimit时间范围。该字典中的值在冲突时覆盖backend、region、safesearch、top_k的设置。一个带特定后端与区域的初始化示例来自 组件指南web_search DDGSWebSearch( top_k5, backendduckduckgo, brave, regionde-de, safesearchoff, )这里指定只查询 DuckDuckGo 与 Brave 两个后端搜索区域限定为德国德语环境并关闭安全搜索。这样的配置适合对结果地域性和过滤强度有明确要求的场景。warm_up预初始化客户端warm_up() - Nonewarm_up()负责初始化 ddgs 客户端。组件在首次使用时会被自动调用该方法无需手动触发。如果你希望避免首次调用时的冷启动延迟例如在服务预热阶段可以显式调用warm_up()。run执行搜索run()方法签名如下run( query: str, top_k: int | None None, *, backend: str | None None, region: str | None None, safesearch: str | None None, search_params: dict[str, Any] | None None ) - dict[str, list[Document] | list[str]]参数说明参数类型说明querystr搜索查询字符串必填。top_kint \| None可选的单次运行覆盖值不传时使用初始化时的top_k。backendstr \| None可选的单次运行覆盖值不传时使用初始化时的backend。regionstr \| None可选的单次运行覆盖值不传时使用初始化时的region。safesearchstr \| None可选的单次运行覆盖值不传时使用初始化时的safesearch。search_paramsdict[str, Any] \| None可选的单次运行覆盖值。注意传入后是完整替换初始化时的search_params而不是与它合并。返回值返回一个字典包含两个键documentslist[Document]各搜索后端返回的结果文档列表文档内容为搜索结果的片段snippet结果标题与 URL 存放在doc.meta中具体为doc.meta[url]与doc.meta[title]。linkslist[str]各搜索后端返回的 URL 字符串列表。基础用法示例以下示例来自 API 参考from haystack_integrations.components.websearch.ddgs import DDGSWebSearch websearch DDGSWebSearch(top_k5) result websearch.run(queryWhat is Haystack by deepset?) documents result[documents] links result[links]组件指南中给出了更贴近实际的数据访问方式遍历Document读取 meta 中的 URL 与正文内容from haystack_integrations.components.websearch.ddgs import DDGSWebSearch web_search DDGSWebSearch(top_k5) query What is Haystack by deepset? response web_search.run(queryquery) for doc in response[documents]: print(doc.meta[url]) print(doc.content)run_async异步执行run_async()的签名与run()完全一致返回类型也相同run_async( query: str, top_k: int | None None, *, backend: str | None None, region: str | None None, safesearch: str | None None, search_params: dict[str, Any] | None None ) - dict[str, list[Document] | list[str]]需要特别说明的是ddgs 本身没有原生的异步 API因此run_async()的实现方式是把阻塞式搜索放到一个工作线程worker thread中执行从而让调用方获得异步体验。这一点与 Haystack 中那些底层 SDK 原生支持异步的组件如 OpenAI 系列有本质区别——异步只是线程池层面的并发而非真正的非阻塞 IO。从使用角度run_async()的参数与返回值约定和run()完全相同query必填其余参数均为可选的单次运行覆盖值返回同样包含documents与links两个键。如果查询量较大且需要并发执行多次搜索可以优先考虑这个入口。在 RAG 管道中使用DDGSWebSearch最常见的管道位置是在ChatPromptBuilder之前或者位于索引管道indexing pipeline的起始处组件指南 中的位置说明。下面是一个完整的检索增强生成RAG示例用DDGSWebSearch在网络上查找资料将结果注入提示词再由 OpenAI Chat 模型生成回答。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.ddgs import DDGSWebSearch from haystack.dataclasses import ChatMessage web_search DDGSWebSearch(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)该管道的执行流程search组件DDGSWebSearch(top_k3)接收query执行多引擎网络搜索search.documents输出连接到prompt_builder.documents模板中的 Jinja 循环把每个document.content拼进提示词prompt_builder.prompt连接到llm.messagesOpenAIChatGenerator基于注入的搜索结果生成最终回答。注意管道运行时query需要同时提供给search与prompt_builder两个组件因为提示词模板本身也引用了{{ query }}。结合 LinkContentFetcher 获取完整页面由于 ddgs 返回的是**短片段snippet**而非完整网页内容当需要更多上下文时可以在搜索之后追加LinkContentFetcher与一个转换器converter先抓取links指向的真实网页再做后续处理。这也是组件指南给出的推荐扩展路径。使用注意事项best-effort 结果ddgs 是直接查询公共搜索引擎、没有 API 契约的元搜索库因此结果是**尽力而为best-effort**的不同次运行之间结果可能不一致高频使用可能被搜索引擎限流或临时屏蔽如果生产负载需要可预期的速率限制建议改用商业搜索 API 支持的组件例如TavilyWebSearch或SerperDevWebSearch参见 WebSearch 组件索引。这决定了DDGSWebSearch更适合原型验证、个人项目或对结果稳定性要求不高的场景对 SLA 敏感的生产系统应评估商业替代方案。参数优先级与运行期覆盖小结综合初始化与运行两个层面的参数约定可以总结出以下三条规则初始化期backend、region、safesearch、top_k四个参数有默认值auto、us-en、moderate、10search_params默认为None运行期run()/run_async()的所有可选参数都是单次覆盖不传则回落fallback到初始化值冲突优先级search_params中的值最高会覆盖backend、region、safesearch、top_k且运行期传入的search_params是整体替换初始化期的字典而非合并。结语DDGSWebSearch为 Haystack 提供了一条零成本接入网络搜索的路径无需 API Key、无需账户即可通过 ddgs 聚合多个公共搜索引擎的结果并以标准Document对象无缝汇入 RAG 管道。它同时提供了同步run()、异步run_async()、预热warm_up()与灵活的运行期参数覆盖机制配合LinkContentFetcher可进一步扩展为「搜索 抓取 生成」的完整链路。在享受免密钥便利的同时务必记住其结果为 best-effort 特性生产环境需结合商业搜索 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考