Haystack × Parallel 集成参考ParallelChatGenerator 与 ParallelWebSearch 组件详解【免费下载链接】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 仓库中 Parallel 集成 API 参考文档version-2.19 归档版 与其内容完全一致系统讲解 Parallel 集成包提供的两个核心组件ParallelChatGenerator内置实时网络研究的聊天生成器和ParallelWebSearch返回 HaystackDocument的网页搜索组件。读完本文你将掌握这两个组件的完整参数配置、研究层级research tier选择、会话续接session_id机制以及它们与 Haystack 核心数据类和序列化体系的关系。概览Parallel 集成在 Haystack 中的位置Parallel 集成向 Haystack 提供了两个互补的能力ParallelChatGenerator继承自 Haystack 核心的OpenAIResponsesChatGenerator通过 Parallel Responses APIPOST /v1/responses与 OpenAI Responses API 兼容完成对话。每个回答都基于实时网络研究live web research生成并附带引用citationsreasoning.effort参数用于选择研究层级low约 5–10 秒、medium约 15–20 秒默认、high约 30–60 秒。ParallelWebSearch封装 Parallel Search API 的搜索组件把查询结果转化为带内容和链接的结构化Document列表并返回把相关联的多次搜索串联起来的会话标识session identifier。从源码结构看这两个组件位于独立的haystack_integrations包haystack_integrations.components.generators.parallel.chat与haystack_integrations.components.websearch.parallel模块而非核心haystack包。但它们深度复用核心包的既有设施——生成器的父类、Secret密钥封装、ChatMessage/Document数据类这一点后文将逐一给出仓库内证据。版本适用性说明该 API 参考在仓库中自 version-2.19 起一直保留且与最新参考版docs-website/reference/integrations-api/parallel.md逐字相同可视为该集成在 2.19 至当前版本线之间的稳定 API 契约。ParallelChatGenerator内置网络研究的聊天生成器定位与设计要点ParallelChatGenerator继承自OpenAIResponsesChatGenerator该类在核心包中的定义见 openai_responses.py。选择这个父类意味着输入输出统一使用 Haystack 的 ChatMessage 格式继承 OpenAI Responses 客户端的连接、重试与流式行为只需通过覆盖默认值适配 Parallel 的服务端特性完整支持to_dict()序列化可嵌入Pipeline并以 YAML 形式保存与加载。由于单次调用会执行实时研究该组件有两处针对场景的默认值调整timeout默认 120 秒而不是从 OpenAI 客户端继承的 30 秒确保high层级约 30–60 秒能从容完成max_retries保持为 3刻意压低重试次数——因为每一次重试都会触发一次完整的网络研究调用重试成本高。另外虽然 Web grounding 是内置能力但tools、temperature、top_p等采样参数仍会被接受用于 SDK 兼容性——它们会被 API 静默忽略组件在检测到这些参数时会发出警告。快速上手from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.parallel import ParallelChatGenerator messages [ChatMessage.from_user(What did Parallel Web Systems announce this year?)] client ParallelChatGenerator(generation_kwargs{reasoning: {effort: low}}) response client.run(messages) print(response)示例中通过generation_kwargs传入{reasoning: {effort: low}}选择低层级研究以获得更快响应省略该参数时使用默认的medium层级。完整参数参考__init____init__( *, api_key: Secret Secret.from_env_var(PARALLEL_API_KEY), model: str parallel, api_base_url: str | None https://api.parallel.ai/v1, streaming_callback: StreamingCallbackT | None None, generation_kwargs: dict[str, Any] | None None, timeout: float | None 120.0, extra_headers: dict[str, Any] | None None, max_retries: int | None 3, http_client_kwargs: dict[str, Any] | None None ) - None参数类型默认值说明api_keySecretSecret.from_env_var(PARALLEL_API_KEY)Parallel API 密钥modelstrparallel使用的 Parallel Responses API 模型api_base_urlstr \| Nonehttps://api.parallel.ai/v1Parallel API 基础 URLstreaming_callbackStreamingCallbackT \| NoneNone流式接收新 token 时的回调函数generation_kwargsdict[str, Any] \| NoneNone直接透传给 Parallel Responses API 的额外参数如reasoning{effort: low}选择研究层级或text结构化输出timeoutfloat \| None120.0API 调用超时秒。默认 120 秒为high研究层级约 30–60 秒留出余量传None则回退到 OpenAI 客户端默认OPENAI_TIMEOUT环境变量或 30 秒这对多数研究类调用来说太短extra_headersdict[str, Any] \| NoneNone附加到请求的 HTTP 头max_retriesint \| None3内部错误后重试联系 Parallel 的最大次数。刻意设低因为每次重试都运行一次完整研究传None回退到 OpenAI 客户端默认OPENAI_MAX_RETRIES环境变量或 5http_client_kwargsdict[str, Any] \| NoneNone用于配置自定义httpx.Client/httpx.AsyncClient的关键字参数字典模型支持范围由类属性声明SUPPORTED_MODELS: list[str] [parallel]即当前组件仅支持名为parallel的 Parallel Responses API 模型其他取值以官方文档为准原文档指向 Parallel 官方 Responses API 快速入门可在 Parallel 官方站点查阅。序列化to_dictto_dict() - dict[str, Any]将组件序列化为字典供Pipeline.dumps()/YAML 持久化使用。值得注意的是核心包的反序列化安全模块 把haystack_integrations列入默认信任模块白名单DEFAULT_ALLOWED_MODULES因此在默认安全模式下包含ParallelChatGenerator的流水线 YAML 可以被Pipeline.load()正常还原无需额外扩展allowed_modules。密钥部分可序列化性也来自核心包Secret 提供两种实现——Secret.from_env_var(...)生成的EnvVarSecret可序列化只记录环境变量名而Secret.from_token(...)生成的TokenSecret不可序列化其to_dict会抛ValueError。因此若要把含ParallelChatGenerator的流水线落盘应使用默认的环境变量密钥形式PARALLEL_API_KEY这与文档中所有示例的写法一致。ParallelWebSearch返回 Haystack Document 的网页搜索组件定位ParallelWebSearch封装 Parallel Search API把网络搜索结果转化为 LLM 优化过的摘要片段excerpts以带内容与链接的结构化Document返回同时返回把相关搜索串联起来的会话标识。使用前需要一个 Parallel API key。快速上手含 session_id 续接from haystack_integrations.components.websearch.parallel import ParallelWebSearch from haystack.utils import Secret websearch ParallelWebSearch( api_keySecret.from_env_var(PARALLEL_API_KEY), top_k5, ) result websearch.run(queryWhat is Haystack by deepset?) documents result[documents] links result[links] # Pass the session back on follow-up searches that are part of the same task # to get better contextual results. follow_up websearch.run( queryWho maintains Haystack?, search_params{session_id: result[session_id]}, )这个示例覆盖了该组件两个最重要的实战要点输出三件套documentsDocument列表、linksURL 列表、session_id会话标识会话续接把第一次搜索返回的session_id通过search_params回传给后续搜索API 会在同一任务语境下给出更有上下文的结果。完整参数参考__init____init__( *, api_key: Secret Secret.from_env_var(PARALLEL_API_KEY), top_k: int | None 10, search_params: dict[str, Any] | None None, timeout: float 30.0 ) - None参数类型默认值说明api_keySecretSecret.from_env_var(PARALLEL_API_KEY)Parallel API keytop_kint \| None10返回结果的最大数量映射到 API 的advanced_settings.max_results参数search_paramsdict[str, Any] \| NoneNone透传给 Parallel Search API 的额外参数见下表timeoutfloat30.0请求超时秒search_params支持的键对应 Parallel Search API 参考键说明objective自然语言形式的搜索目标缺省时默认使用 querymodeturbo、fast、basic或advanced按延迟与质量递增排序API 默认advancedmax_chars_total结果总字符数上限session_id把多次搜索链接为同一任务无论是否传入API 实际使用的标识都会通过session_id输出回传client_model客户端模型信息advanced_settings嵌套配置source_policy域名与日期过滤、fetch_policy、excerpt_settings、location、max_results生命周期方法warm_up 与 close组件提供同步/异步两套 HTTP 客户端的初始化与释放接口首次使用时会自动初始化也可以显式调用以规避冷启动延迟warm_up() - None # 初始化同步 HTTP 客户端 warm_up_async() - None # 在服务事件循环上初始化异步 HTTP 客户端 close() - None # 释放同步 HTTP 客户端 close_async() - None # 释放异步 HTTP 客户端在服务端长驻进程如 FastAPI 应用中建议在应用启动钩子里显式调用warm_up()在关闭钩子里调用close()把连接建立成本移出首请求。run 与 run_asyncrun(query: str, search_params: dict[str, Any] | None None) - dict[str, Any] run_async(query: str, search_params: dict[str, Any] | None None) - dict[str, Any]query(str)搜索查询字符串。search_params(dict[str, Any] \| None)单次运行级别对搜索参数的覆盖一旦提供将完全替换而非合并初始化时的search_params。返回值dict[str, Any]documents包含搜索结果摘要片段的 Document 列表可直接流入下游的DocumentJoiner、排序器或DocumentWriterlinks搜索结果中的 URL 列表session_id本次搜索的会话标识——若传入了search_params[session_id]则原样回显否则由 API 生成。将其传给同一任务的后续搜索以维持上下文。run_async是run的异步对应物参数与返回值完全相同适用于异步流水线如配合Pipeline.run_async中避免阻塞事件循环的场景。与 Haystack 核心的衔接点源码佐证以下事实均可在核心仓库中直接核验父类真实存在OpenAIResponsesChatGenerator定义于 haystack/components/generators/chat/openai_responses.py。ParallelChatGenerator继承它因此其ChatMessage协议、Responses 风格请求构造与流式回调机制与 OpenAI Responses 生成器同源仅覆盖了默认超时、重试与端点。密钥封装两个组件的api_key参数类型Secret定义于 haystack/utils/auth.pyfrom_env_var支持单个或多个候选环境变量名解析时返回第一个已设置的变量值且可被序列化——这正是示例中Secret.from_env_var(PARALLEL_API_KEY)可安全落盘的原因。输出数据类ParallelWebSearch返回的documents元素是核心包的 Document 数据类字段content、meta、id等与文档存储、排序器、检索器完全兼容无需适配层即可接入既有 RAG 流水线。安全加载serialization_security.py 的默认白名单包含haystack_integrations意味着保存后的流水线 YAML 在默认安全模式下即可反序列化这两个组件。前提条件与限制依赖安装两个组件均来自haystack_integrations集成包而非核心haystack包需要安装 Parallel 集成对应的发行包后才能import haystack_integrations.components.generators.parallel/import haystack_integrations.components.websearch.parallel。环境变量两个组件默认从PARALLEL_API_KEY环境变量读取密钥若显式传入Secret.from_token(...)则该流水线不可序列化TokenSecret.to_dict会抛异常见 auth.py。被忽略的参数ParallelChatGenerator虽接受tools、temperature、top_p等参数以维持 SDK 兼容但 API 会静默忽略它们组件会打印警告——不要指望通过这些参数控制 Parallel 的采样行为真正可调的是generation_kwargs中的reasoning研究层级与text结构化输出。超时预算ParallelChatGenerator默认 120 秒超时必须配合所选层级使用——high层级约需 30–60 秒ParallelWebSearch默认超时仅 30 秒长查询或advanced模式较慢时可显式调大。版本契约本文依据的 API 参考自 version-2.19 起与最新版逐字一致可用 归档版 与 最新版 对照适用于 2.19 及以上版本线若使用的 Haystack 主版本更早请以对应版本的 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），仅供参考
