Haystack 3.x 开源 AI 编排框架实战指南用 Python 构建生产级 RAG 与 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/haystackHaystack 是 deepset 团队开源的 AI 编排框架Apache-2.0 协议用于在 Python 中构建生产就绪的 LLM 应用。它以组件 流水线 Agent为核心理念让开发者对检索retrieval、路由routing、记忆memory与生成generation拥有显式控制本文将从安装、核心特性、源码机制到首个 RAG 与 Agent 应用带你完整掌握这一框架的使用方法。读完本文你将能够搭建可扩展的 RAG 系统、多模态应用、语义搜索与自主 Agent 工作流并理解其底层的组件契约、生命周期钩子与遥测机制。项目定位与整体架构Haystack 是一个开源 AI 编排框架核心理念是透明架构检索、排序、过滤、组合、结构化与路由都在信息到达模型之前被显式控制流水线与 Agent 工作流中的每一步都清晰可追溯README.md。从仓库结构看Haystack 3.x 的核心分层非常清晰核心层haystack/core包含组件契约component装饰器、Pipeline 图执行引擎、序列化与错误处理数据层haystack/dataclassesDocument、ChatMessage、Answer等核心数据结构组件层haystack/components检索器、生成器、嵌入器、转换器、Agent 等 100 内置组件工具层haystack/toolsTool、Toolset、ComponentTool、PipelineTool等工具抽象钩子层haystack/hooksAgent 生命周期钩子预算控制、上下文压缩、人工介入、工具结果卸载等。当前仓库对应版本为3.2.0-rc0见 VERSION.txt包名为haystack-ai要求 Python 3.10pyproject.toml。安装 Haystack基础安装最简单的安装方式是通过 pippip install haystack-ai若想抢先体验最新特性可以安装 nightly 预发布版本pip install --pre haystack-ai其他包管理器根据官方安装文档docs-website/docs/overview/installation.mdx还支持以下方式# 使用 uv uv pip install haystack-ai # 或作为项目依赖添加 uv add haystack-ai # 使用 conda conda install conda-forge::haystack-ai可选依赖与 DockerHaystack 采用轻量安装策略默认只安装核心依赖部分组件依赖的可选包不会自动安装。如果使用了未安装可选依赖的功能会抛出类似ImportError: Haystack failed to import the optional dependency pypdf. Run pip install pypdf.的提示按提示安装即可。从 pyproject.toml 的依赖声明可以看到核心依赖包括openai、pydantic、Jinja2、networkx用于流水线图、httpx、numpy等而pypdf、pdfminer.six、trafilatura、python-docx等属于测试/可选环境。此外仓库提供了 Docker 构建支持docker/Dockerfile.base 与 docker/docker-bake.hcl 中定义了基础镜像的多平台构建配置适合在容器化环境中部署。核心特性与源码级解读为生产而生的 AgentAgent 是 Haystack 3.x 的重头戏。在 haystack/components/agents/agent.py 中Agent被实现为一个标准的 Haystack 组件component由 LLM 驱动、可调用工具并持续处理消息直到满足退出条件。Agent.__init__的关键参数包括参数默认值说明chat_generator必填聊天生成器实例必须支持工具调用toolsNoneTool和/或Toolset列表或单个Toolsetsystem_prompt/user_promptNone系统/用户提示词支持字符串模板或 Jinja2 消息模板required_variables*提示词中必须提供的变量*表示全部必填None表示全部可选exit_conditions[text]退出条件可包含text生成无工具调用的消息即返回或工具名执行完指定工具即返回state_schemaNone定义运行时状态的字典工具可通过inputs_from_state/outputs_to_state读写状态max_agent_steps100最大步数一步 一次 chat-generator 调用 该次请求的所有工具调用raise_on_tool_invocation_failureFalse工具调用失败是否抛异常为False时失败会转为聊天消息回传给 LLMtool_concurrency_limit4并行执行工具调用的上限设为1可禁用并行hooksNone钩子点 → 钩子列表的映射见下文生命周期钩子agent.run()的返回结果中内置了生产级监控字段agent.pymessages本次运行交换的全部消息last_message最后一条消息step_count实际运行的步数token_usage每次 LLM 调用的 token 用量聚合从各消息的meta[usage]累加而来tool_call_counts每个工具被调用的次数映射exit_reason退出原因包括text、length、content_filter、满足退出条件的工具名、max_agent_steps或钩子通过stop_run状态键提供的自定义原因——该字段非常适合配合ConditionalRouter做下游路由。生命周期钩子HooksAgent 支持通过钩子扩展行为用于护栏guardrails与自定义逻辑。钩子点定义在 haystack/hooks/protocol.pyHookPoint Literal[before_run, before_llm, before_tool, after_tool, on_exit, after_run]各钩子点的语义依据 agent.py 与 haystack/hooks 目录下的实现before_run每次运行开始后、首次 LLM 调用前执行一次适合改写初始消息或初始化状态before_llm每次 chat-generator 调用前执行是上下文压缩、预算检查等高频钩子的挂载点before_tool模型请求工具调用后、工具执行前执行人工审批Human-in-the-Loop钩子挂在这里after_tool工具执行后执行工具结果卸载钩子挂在这里on_exitAgent 退出时执行适合强制校验例如必须保存结果after_run整个运行结束后执行。仓库中已内置多种开箱即用的钩子实现Token 预算控制haystack/hooks/budget/hooks.py 中的TokenBudgetHook在before_llm检查 Agent 状态中累计的 token 用量可设置max_total_tokens上下文压缩haystack/hooks/compaction 目录提供滑动窗口压缩SlidingWindowCompactor、摘要压缩SummarizationCompactor与工具结果裁剪ToolResultPruningCompactor人工介入haystack/hooks/human_in_the_loop/hooks.py 的确认钩子在before_tool对待执行的工具调用施加人工确认策略工具结果卸载haystack/hooks/tool_result_offloading/hooks.py 在after_tool将大段工具结果写入外部存储让下一次 LLM 调用只看到引用。钩子函数遵循统一签名def my_hook(state: State) - None并通过 haystack/hooks/from_function.py 的FunctionHook包装为可序列化的Hook支持同步与异步async_function双实现。技能渐进发现SkillToolset 与 SearchableToolsetREADME 提到可以通过SkillToolset实现技能描述按需进入上下文。在 haystack/tools/searchable_toolset.py 中SearchableToolset正是这一机制的实现它继承Toolset为大量工具自动生成一个引导bootstrap搜索工具让 Agent 先用关键词检索工具名/描述每个工具的Document(contentf{tool.name} {tool.description})被索引进内存文档存储再决定调用哪些工具从而避免把全部技能描述塞进上下文。上下文工程Context EngineeringREADME 强调 Haystack Built for context engineering在信息到达模型之前你可以显式控制信息如何被检索、排序、过滤、组合、结构化与路由。这一设计体现在组件生态上——haystack/components 下按职责划分了检索器retrievers、排序器rankers、路由器routers、连接器joiners、预处理器preprocessors、构建器builders等 20 余个类别配合 Pipeline 的循环loops、分支branches与条件逻辑conditional logic可以精确控制上下文在流水线中的流动方式。原生异步支持同一个Pipeline既可以同步运行也可以异步运行并支持逐 token 流式输出streamingAgent支持并发工具调用默认tool_concurrency_limit4。同步接口是run()异步接口是run_async()这在 haystack/core/pipeline/base.py 与 agent.py 的run/run_async双实现中均有体现。模块化与可定制组件契约Haystack 的组件契约定义在 haystack/core/component/component.py这是整个框架扩展性的根基任何类只要被component装饰即可被 Pipeline 使用__init__只接收基础 Python 类型对象、函数等需序列化为字符串且必须保持轻量——重型状态模型、后端应放在warm_up()中延迟加载组件可声明输入/输出 socketPipeline 据此进行类型检查与连接校验组件通过to_dict()/from_dict()实现序列化配合 haystack/core/serialization.py 的default_to_dict/default_from_dict即可支持流水线保存与加载。顶层入口 haystack/init.py 直接导出了Pipeline、component、Document、ChatMessage、Answer等最常用的 API。模型与厂商无关Haystack 通过统一接口集成 OpenAI、Mistral、Anthropic、Cohere、Hugging Face、Google、Azure OpenAI、AWS Bedrock 以及本地模型切换模型或基础设施组件时无需重写系统。这得益于统一的ChatGenerator协议与 haystack/utils/secret 管理 等抽象层——例如在快速上手示例中OpenAI、Hugging Face、Anthropic、Bedrock、Gemini 的接入代码结构完全一致。可扩展生态一致的组件接口让社区和第三方可以轻松扩展 Haystack。集成代码托管在独立的 haystack-core-integrations 仓库本仓库不包含同时 haystack/testing/sample_components 中提供了 17 个示例组件可作为自定义组件的参考实现。快速上手构建第一个 RAG 流水线下面基于官方快速入门docs-website/docs/overview/get-started.mdx演示如何用 10 分钟构建一个检索增强生成RAG应用。from haystack import Pipeline, Document from haystack.components.generators.chat import OpenAIChatGenerator from haystack.components.retrievers import InMemoryBM25Retriever from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.components.builders import ChatPromptBuilder from haystack.utils import Secret from haystack.dataclasses import ChatMessage # 1. 准备内存文档存储并写入文档 document_store InMemoryDocumentStore() document_store.write_documents( [ Document(contentMy name is Jean and I live in Paris.), Document(contentMy name is Mark and I live in Berlin.), Document(contentMy name is Giorgio and I live in Rome.), ], ) # 2. 定义提示模板Jinja2 语法 prompt_template [ ChatMessage.from_system( Given these documents, answer the question. Documents: {% for doc in documents %} {{ doc.content }} {% endfor %} , ), ChatMessage.from_user({{question}}), ] # 3. 组装组件 retriever InMemoryBM25Retriever(document_storedocument_store) prompt_builder ChatPromptBuilder(templateprompt_template, required_variables*) llm OpenAIChatGenerator( api_keySecret.from_env_var(OPENAI_API_KEY), modelgpt-4o-mini, ) # 4. 构建流水线并连接组件 rag_pipeline Pipeline() rag_pipeline.add_component(retriever, retriever) rag_pipeline.add_component(prompt_builder, prompt_builder) rag_pipeline.add_component(llm, llm) rag_pipeline.connect(retriever, prompt_builder.documents) rag_pipeline.connect(prompt_builder, llm) # 5. 运行 question Who lives in Paris? results rag_pipeline.run( { retriever: {query: question}, prompt_builder: {question: question}, }, ) print(results[llm][replies])这段代码展示了 Haystack 的三个核心模式组件即插即用InMemoryDocumentStore、InMemoryBM25Retriever、ChatPromptBuilder、OpenAIChatGenerator都是独立组件通过Pipeline.add_component注册、connect连接显式数据流connect(retriever, prompt_builder.documents)精确指定了检索结果流向提示构建器的documents输入密钥管理Secret.from_env_var(OPENAI_API_KEY)从环境变量读取 API Key避免硬编码。切换模型供应商也非常简单把OpenAIChatGenerator换成HuggingFaceAPIChatGeneratorpip install huggingface-api-haystack、AnthropicChatGeneratorpip install anthropic-haystack、AmazonBedrockChatGeneratorpip install amazon-bedrock-haystack或GoogleGenAIChatGeneratorpip install google-genai-haystack流水线结构完全不变详见 get-started.mdx 中的多供应商 Tabs 示例。构建第一个工具调用 Agent接下来构建一个能联网搜索并回答问题的 Agentfrom haystack.components.agents import Agent from haystack.components.generators.chat import OpenAIChatGenerator from haystack.dataclasses import ChatMessage from haystack.tools import ComponentTool from haystack_integrations.components.websearch.serperdev import SerperDevWebSearch from haystack.utils import Secret # 将 Web 搜索组件包装为工具 search_tool ComponentTool(componentSerperDevWebSearch()) agent Agent( chat_generatorOpenAIChatGenerator( api_keySecret.from_env_var(OPENAI_API_KEY), modelgpt-4o-mini, ), tools[search_tool], system_promptYou are a helpful assistant that can search the web for information., ) result agent.run(messages[ChatMessage.from_user(What is Haystack AI?)]) print(result[last_message].text)要点说明需要先执行pip install serperdev-haystack并设置SERPERDEV_API_KEY环境变量ComponentTool可以把任意 Haystack 组件包装成 Agent 可调用的工具haystack/tools/component_tool.py这是组件即工具的关键桥梁除了ComponentToolhaystack/tools 还提供tool装饰器从普通函数创建工具、PipelineTool把整个流水线变成工具和Toolset工具分组完整的工具抽象层次可参考 haystack/tools/toolset.py。用钩子为 Agent 加上护栏与成本控制将 Agent 部署到生产环境时token 成本与上下文失控是首要问题。借助内置的TokenBudgetHook可以做到按预算停机from haystack.components.agents import Agent from haystack.hooks.budget.hooks import TokenBudgetHook agent Agent( chat_generator..., tools[...], hooks{before_llm: [TokenBudgetHook(max_total_tokens100_000)]}, )自定义钩子同样简单——只需定义一个接收State参数的函数from haystack.hooks.from_function import hook hook def require_save(state) - None: if not state.data[saved]: raise RuntimeError(The agent must save the result before exiting.) agent Agent( chat_generator..., tools[...], hooks{on_exit: [require_save]}, )钩子可以直接变更State数据来影响运行流程例如通过stop_run键强制提前退出从而实现预算控制、人工审批、上下文压缩、工具结果卸载等生产级能力相关实现均可在 haystack/hooks 目录下找到。部署与运维REST API 与 MCP 服务README 特别推荐了 Hayhooks它可以把流水线和 Agent 包装成带自定义逻辑的REST API或MCP server对外暴露并支持 OpenAI 兼容的 chat completion 端点可配合 open-webui 等聊天界面使用。遥测与隐私Haystack 会收集匿名的组件使用统计每次组件初始化时发送一次事件用于了解哪些组件对社区最有价值。具体机制在 haystack/telemetry/_telemetry.py 中实现默认启用HAYSTACK_TELEMETRY_ENABLED未设置或为true/1时创建Telemetry实例事件通过 PostHog 发送每次运行流水线至少间隔 60 秒才发送一次MIN_SECONDS_BETWEEN_EVENTS 60用户 ID 保存在~/.haystack/config.yaml中首次运行自动生成即使遥测发送失败也不会影响业务所有异常均被捕获并降级为 debug 日志Never let telemetry break things。关闭遥测设置环境变量HAYSTACK_TELEMETRY_ENABLEDfalse即可例如export HAYSTACK_TELEMETRY_ENABLEDfalse企业级支持如需团队级支持与部署保障deepset 提供Haystack Enterprise Starter企业级模板、云端与本地部署指南与Haystack Enterprise Platform带可观测性、协作、治理与访问控制的托管/自托管平台相关内容在 README 的 Haystack Enterprise 一节中有详细介绍这里不展开。社区与贡献Haystack 的贡献指南见仓库根目录的 CONTRIBUTING.md贡献方式包括贡献主项目本仓库在 haystack-core-integrations 仓库贡献集成在 docs-website 目录贡献文档。releasenotes/notes 目录保存了全部变更说明release notes可作为了解功能演进的一手资料AGENTS.md 与 CLAUDE.md 则为 AI 编码代理提供了仓库协作约定。总结Haystack 3.x 的核心价值可以概括为三点透明可控组件 Pipeline 的显式数据流设计让检索、路由、记忆、生成每一步都可观察、可调试、可替换生产就绪Agent 生命周期钩子、step_count/token_usage/tool_call_counts内置监控、原生异步、流式输出覆盖了从原型到上线的完整路径生态开放统一组件契约 多模型供应商接入 可扩展的工具/工具集抽象Tool、ComponentTool、PipelineTool、Toolset、SearchableToolset让团队可以按需组合最合适的模型与基础设施。想深入掌握推荐依次阅读仓库内的 组件契约定义、Pipeline 实现、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/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Haystack 3.x 开源 AI 编排框架实战指南：用 Python 构建生产级 RAG 与 Agent 应用
Haystack 3.x 开源 AI 编排框架实战指南用 Python 构建生产级 RAG 与 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/haystackHaystack 是 deepset 团队开源的 AI 编排框架Apache-2.0 协议用于在 Python 中构建生产就绪的 LLM 应用。它以组件 流水线 Agent为核心理念让开发者对检索retrieval、路由routing、记忆memory与生成generation拥有显式控制本文将从安装、核心特性、源码机制到首个 RAG 与 Agent 应用带你完整掌握这一框架的使用方法。读完本文你将能够搭建可扩展的 RAG 系统、多模态应用、语义搜索与自主 Agent 工作流并理解其底层的组件契约、生命周期钩子与遥测机制。项目定位与整体架构Haystack 是一个开源 AI 编排框架核心理念是透明架构检索、排序、过滤、组合、结构化与路由都在信息到达模型之前被显式控制流水线与 Agent 工作流中的每一步都清晰可追溯README.md。从仓库结构看Haystack 3.x 的核心分层非常清晰核心层haystack/core包含组件契约component装饰器、Pipeline 图执行引擎、序列化与错误处理数据层haystack/dataclassesDocument、ChatMessage、Answer等核心数据结构组件层haystack/components检索器、生成器、嵌入器、转换器、Agent 等 100 内置组件工具层haystack/toolsTool、Toolset、ComponentTool、PipelineTool等工具抽象钩子层haystack/hooksAgent 生命周期钩子预算控制、上下文压缩、人工介入、工具结果卸载等。当前仓库对应版本为3.2.0-rc0见 VERSION.txt包名为haystack-ai要求 Python 3.10pyproject.toml。安装 Haystack基础安装最简单的安装方式是通过 pippip install haystack-ai若想抢先体验最新特性可以安装 nightly 预发布版本pip install --pre haystack-ai其他包管理器根据官方安装文档docs-website/docs/overview/installation.mdx还支持以下方式# 使用 uv uv pip install haystack-ai # 或作为项目依赖添加 uv add haystack-ai # 使用 conda conda install conda-forge::haystack-ai可选依赖与 DockerHaystack 采用轻量安装策略默认只安装核心依赖部分组件依赖的可选包不会自动安装。如果使用了未安装可选依赖的功能会抛出类似ImportError: Haystack failed to import the optional dependency pypdf. Run pip install pypdf.的提示按提示安装即可。从 pyproject.toml 的依赖声明可以看到核心依赖包括openai、pydantic、Jinja2、networkx用于流水线图、httpx、numpy等而pypdf、pdfminer.six、trafilatura、python-docx等属于测试/可选环境。此外仓库提供了 Docker 构建支持docker/Dockerfile.base 与 docker/docker-bake.hcl 中定义了基础镜像的多平台构建配置适合在容器化环境中部署。核心特性与源码级解读为生产而生的 AgentAgent 是 Haystack 3.x 的重头戏。在 haystack/components/agents/agent.py 中Agent被实现为一个标准的 Haystack 组件component由 LLM 驱动、可调用工具并持续处理消息直到满足退出条件。Agent.__init__的关键参数包括参数默认值说明chat_generator必填聊天生成器实例必须支持工具调用toolsNoneTool和/或Toolset列表或单个Toolsetsystem_prompt/user_promptNone系统/用户提示词支持字符串模板或 Jinja2 消息模板required_variables*提示词中必须提供的变量*表示全部必填None表示全部可选exit_conditions[text]退出条件可包含text生成无工具调用的消息即返回或工具名执行完指定工具即返回state_schemaNone定义运行时状态的字典工具可通过inputs_from_state/outputs_to_state读写状态max_agent_steps100最大步数一步 一次 chat-generator 调用 该次请求的所有工具调用raise_on_tool_invocation_failureFalse工具调用失败是否抛异常为False时失败会转为聊天消息回传给 LLMtool_concurrency_limit4并行执行工具调用的上限设为1可禁用并行hooksNone钩子点 → 钩子列表的映射见下文生命周期钩子agent.run()的返回结果中内置了生产级监控字段agent.pymessages本次运行交换的全部消息last_message最后一条消息step_count实际运行的步数token_usage每次 LLM 调用的 token 用量聚合从各消息的meta[usage]累加而来tool_call_counts每个工具被调用的次数映射exit_reason退出原因包括text、length、content_filter、满足退出条件的工具名、max_agent_steps或钩子通过stop_run状态键提供的自定义原因——该字段非常适合配合ConditionalRouter做下游路由。生命周期钩子HooksAgent 支持通过钩子扩展行为用于护栏guardrails与自定义逻辑。钩子点定义在 haystack/hooks/protocol.pyHookPoint Literal[before_run, before_llm, before_tool, after_tool, on_exit, after_run]各钩子点的语义依据 agent.py 与 haystack/hooks 目录下的实现before_run每次运行开始后、首次 LLM 调用前执行一次适合改写初始消息或初始化状态before_llm每次 chat-generator 调用前执行是上下文压缩、预算检查等高频钩子的挂载点before_tool模型请求工具调用后、工具执行前执行人工审批Human-in-the-Loop钩子挂在这里after_tool工具执行后执行工具结果卸载钩子挂在这里on_exitAgent 退出时执行适合强制校验例如必须保存结果after_run整个运行结束后执行。仓库中已内置多种开箱即用的钩子实现Token 预算控制haystack/hooks/budget/hooks.py 中的TokenBudgetHook在before_llm检查 Agent 状态中累计的 token 用量可设置max_total_tokens上下文压缩haystack/hooks/compaction 目录提供滑动窗口压缩SlidingWindowCompactor、摘要压缩SummarizationCompactor与工具结果裁剪ToolResultPruningCompactor人工介入haystack/hooks/human_in_the_loop/hooks.py 的确认钩子在before_tool对待执行的工具调用施加人工确认策略工具结果卸载haystack/hooks/tool_result_offloading/hooks.py 在after_tool将大段工具结果写入外部存储让下一次 LLM 调用只看到引用。钩子函数遵循统一签名def my_hook(state: State) - None并通过 haystack/hooks/from_function.py 的FunctionHook包装为可序列化的Hook支持同步与异步async_function双实现。技能渐进发现SkillToolset 与 SearchableToolsetREADME 提到可以通过SkillToolset实现技能描述按需进入上下文。在 haystack/tools/searchable_toolset.py 中SearchableToolset正是这一机制的实现它继承Toolset为大量工具自动生成一个引导bootstrap搜索工具让 Agent 先用关键词检索工具名/描述每个工具的Document(contentf{tool.name} {tool.description})被索引进内存文档存储再决定调用哪些工具从而避免把全部技能描述塞进上下文。上下文工程Context EngineeringREADME 强调 Haystack Built for context engineering在信息到达模型之前你可以显式控制信息如何被检索、排序、过滤、组合、结构化与路由。这一设计体现在组件生态上——haystack/components 下按职责划分了检索器retrievers、排序器rankers、路由器routers、连接器joiners、预处理器preprocessors、构建器builders等 20 余个类别配合 Pipeline 的循环loops、分支branches与条件逻辑conditional logic可以精确控制上下文在流水线中的流动方式。原生异步支持同一个Pipeline既可以同步运行也可以异步运行并支持逐 token 流式输出streamingAgent支持并发工具调用默认tool_concurrency_limit4。同步接口是run()异步接口是run_async()这在 haystack/core/pipeline/base.py 与 agent.py 的run/run_async双实现中均有体现。模块化与可定制组件契约Haystack 的组件契约定义在 haystack/core/component/component.py这是整个框架扩展性的根基任何类只要被component装饰即可被 Pipeline 使用__init__只接收基础 Python 类型对象、函数等需序列化为字符串且必须保持轻量——重型状态模型、后端应放在warm_up()中延迟加载组件可声明输入/输出 socketPipeline 据此进行类型检查与连接校验组件通过to_dict()/from_dict()实现序列化配合 haystack/core/serialization.py 的default_to_dict/default_from_dict即可支持流水线保存与加载。顶层入口 haystack/init.py 直接导出了Pipeline、component、Document、ChatMessage、Answer等最常用的 API。模型与厂商无关Haystack 通过统一接口集成 OpenAI、Mistral、Anthropic、Cohere、Hugging Face、Google、Azure OpenAI、AWS Bedrock 以及本地模型切换模型或基础设施组件时无需重写系统。这得益于统一的ChatGenerator协议与 haystack/utils/secret 管理 等抽象层——例如在快速上手示例中OpenAI、Hugging Face、Anthropic、Bedrock、Gemini 的接入代码结构完全一致。可扩展生态一致的组件接口让社区和第三方可以轻松扩展 Haystack。集成代码托管在独立的 haystack-core-integrations 仓库本仓库不包含同时 haystack/testing/sample_components 中提供了 17 个示例组件可作为自定义组件的参考实现。快速上手构建第一个 RAG 流水线下面基于官方快速入门docs-website/docs/overview/get-started.mdx演示如何用 10 分钟构建一个检索增强生成RAG应用。from haystack import Pipeline, Document from haystack.components.generators.chat import OpenAIChatGenerator from haystack.components.retrievers import InMemoryBM25Retriever from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.components.builders import ChatPromptBuilder from haystack.utils import Secret from haystack.dataclasses import ChatMessage # 1. 准备内存文档存储并写入文档 document_store InMemoryDocumentStore() document_store.write_documents( [ Document(contentMy name is Jean and I live in Paris.), Document(contentMy name is Mark and I live in Berlin.), Document(contentMy name is Giorgio and I live in Rome.), ], ) # 2. 定义提示模板Jinja2 语法 prompt_template [ ChatMessage.from_system( Given these documents, answer the question. Documents: {% for doc in documents %} {{ doc.content }} {% endfor %} , ), ChatMessage.from_user({{question}}), ] # 3. 组装组件 retriever InMemoryBM25Retriever(document_storedocument_store) prompt_builder ChatPromptBuilder(templateprompt_template, required_variables*) llm OpenAIChatGenerator( api_keySecret.from_env_var(OPENAI_API_KEY), modelgpt-4o-mini, ) # 4. 构建流水线并连接组件 rag_pipeline Pipeline() rag_pipeline.add_component(retriever, retriever) rag_pipeline.add_component(prompt_builder, prompt_builder) rag_pipeline.add_component(llm, llm) rag_pipeline.connect(retriever, prompt_builder.documents) rag_pipeline.connect(prompt_builder, llm) # 5. 运行 question Who lives in Paris? results rag_pipeline.run( { retriever: {query: question}, prompt_builder: {question: question}, }, ) print(results[llm][replies])这段代码展示了 Haystack 的三个核心模式组件即插即用InMemoryDocumentStore、InMemoryBM25Retriever、ChatPromptBuilder、OpenAIChatGenerator都是独立组件通过Pipeline.add_component注册、connect连接显式数据流connect(retriever, prompt_builder.documents)精确指定了检索结果流向提示构建器的documents输入密钥管理Secret.from_env_var(OPENAI_API_KEY)从环境变量读取 API Key避免硬编码。切换模型供应商也非常简单把OpenAIChatGenerator换成HuggingFaceAPIChatGeneratorpip install huggingface-api-haystack、AnthropicChatGeneratorpip install anthropic-haystack、AmazonBedrockChatGeneratorpip install amazon-bedrock-haystack或GoogleGenAIChatGeneratorpip install google-genai-haystack流水线结构完全不变详见 get-started.mdx 中的多供应商 Tabs 示例。构建第一个工具调用 Agent接下来构建一个能联网搜索并回答问题的 Agentfrom haystack.components.agents import Agent from haystack.components.generators.chat import OpenAIChatGenerator from haystack.dataclasses import ChatMessage from haystack.tools import ComponentTool from haystack_integrations.components.websearch.serperdev import SerperDevWebSearch from haystack.utils import Secret # 将 Web 搜索组件包装为工具 search_tool ComponentTool(componentSerperDevWebSearch()) agent Agent( chat_generatorOpenAIChatGenerator( api_keySecret.from_env_var(OPENAI_API_KEY), modelgpt-4o-mini, ), tools[search_tool], system_promptYou are a helpful assistant that can search the web for information., ) result agent.run(messages[ChatMessage.from_user(What is Haystack AI?)]) print(result[last_message].text)要点说明需要先执行pip install serperdev-haystack并设置SERPERDEV_API_KEY环境变量ComponentTool可以把任意 Haystack 组件包装成 Agent 可调用的工具haystack/tools/component_tool.py这是组件即工具的关键桥梁除了ComponentToolhaystack/tools 还提供tool装饰器从普通函数创建工具、PipelineTool把整个流水线变成工具和Toolset工具分组完整的工具抽象层次可参考 haystack/tools/toolset.py。用钩子为 Agent 加上护栏与成本控制将 Agent 部署到生产环境时token 成本与上下文失控是首要问题。借助内置的TokenBudgetHook可以做到按预算停机from haystack.components.agents import Agent from haystack.hooks.budget.hooks import TokenBudgetHook agent Agent( chat_generator..., tools[...], hooks{before_llm: [TokenBudgetHook(max_total_tokens100_000)]}, )自定义钩子同样简单——只需定义一个接收State参数的函数from haystack.hooks.from_function import hook hook def require_save(state) - None: if not state.data[saved]: raise RuntimeError(The agent must save the result before exiting.) agent Agent( chat_generator..., tools[...], hooks{on_exit: [require_save]}, )钩子可以直接变更State数据来影响运行流程例如通过stop_run键强制提前退出从而实现预算控制、人工审批、上下文压缩、工具结果卸载等生产级能力相关实现均可在 haystack/hooks 目录下找到。部署与运维REST API 与 MCP 服务README 特别推荐了 Hayhooks它可以把流水线和 Agent 包装成带自定义逻辑的REST API或MCP server对外暴露并支持 OpenAI 兼容的 chat completion 端点可配合 open-webui 等聊天界面使用。遥测与隐私Haystack 会收集匿名的组件使用统计每次组件初始化时发送一次事件用于了解哪些组件对社区最有价值。具体机制在 haystack/telemetry/_telemetry.py 中实现默认启用HAYSTACK_TELEMETRY_ENABLED未设置或为true/1时创建Telemetry实例事件通过 PostHog 发送每次运行流水线至少间隔 60 秒才发送一次MIN_SECONDS_BETWEEN_EVENTS 60用户 ID 保存在~/.haystack/config.yaml中首次运行自动生成即使遥测发送失败也不会影响业务所有异常均被捕获并降级为 debug 日志Never let telemetry break things。关闭遥测设置环境变量HAYSTACK_TELEMETRY_ENABLEDfalse即可例如export HAYSTACK_TELEMETRY_ENABLEDfalse企业级支持如需团队级支持与部署保障deepset 提供Haystack Enterprise Starter企业级模板、云端与本地部署指南与Haystack Enterprise Platform带可观测性、协作、治理与访问控制的托管/自托管平台相关内容在 README 的 Haystack Enterprise 一节中有详细介绍这里不展开。社区与贡献Haystack 的贡献指南见仓库根目录的 CONTRIBUTING.md贡献方式包括贡献主项目本仓库在 haystack-core-integrations 仓库贡献集成在 docs-website 目录贡献文档。releasenotes/notes 目录保存了全部变更说明release notes可作为了解功能演进的一手资料AGENTS.md 与 CLAUDE.md 则为 AI 编码代理提供了仓库协作约定。总结Haystack 3.x 的核心价值可以概括为三点透明可控组件 Pipeline 的显式数据流设计让检索、路由、记忆、生成每一步都可观察、可调试、可替换生产就绪Agent 生命周期钩子、step_count/token_usage/tool_call_counts内置监控、原生异步、流式输出覆盖了从原型到上线的完整路径生态开放统一组件契约 多模型供应商接入 可扩展的工具/工具集抽象Tool、ComponentTool、PipelineTool、Toolset、SearchableToolset让团队可以按需组合最合适的模型与基础设施。想深入掌握推荐依次阅读仓库内的 组件契约定义、Pipeline 实现、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/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考