Haystack：生产级 RAG 与智能体编排框架完整中文翻译

一、官方信息表

二、官方图

三、项目背景与定位

Haystack 是一个开源的 AI 编排框架，专门用于在 Python 中构建生产可用的 LLM 应用。你可以用它设计模块化的流水线（Pipeline）和智能体工作流，对检索、路由、记忆和生成进行显式控制；构建可扩展的 RAG 系统、多模态应用、语义搜索、问答系统和自主智能体——整套架构透明可见，让你既能放心实验、深度定制，又能自信部署上线。

和一些「把提示词写死在链里」的框架不同，Haystack 的核心设计理念是上下文工程：在信息到达模型之前，它如何被检索、排序、过滤、组合、结构化和路由，每一步都由你显式定义，整条流水线透明、可追踪、可评估。这也是它敢称自己为「生产级」的原因——线上 RAG 系统的效果调优，本质上就是在调这条流水线里每一步的输入输出，而不是反复猜提示词该怎么写。

Haystack 由德国 deepset 公司主导开发，采用开源许可证，PyPI 包名为 haystack-ai（注意不是老的 haystack）。它在 2023 年从早期的 1.x 版本重写为现在的 2.x 架构：组件化、流水线即代码、支持异步和流式输出，2.x 也是当前 main 分支的版本。无论你的目标是做一个内部知识库问答、一个带语义搜索的文档站，还是一个能调工具、能查资料、能写代码的自主智能体，Haystack 都把它拆成可以独立测试、独立替换、独立评估的组件，让「从 demo 到生产」这条路尽量短。

四、环境要求与安装

Haystack 是纯 Python 框架，只要有一个受支持的 Python 环境即可。

最简单的安装方式是 pip：

pip install haystack-ai

想尝鲜最新的预发布特性，可以装 nightly 包：

pip install --pre haystack-ai

除了 pip，Haystack 还支持多种安装方式，包括官方提供的 Docker 镜像——把整条流水线连同依赖打进容器，避免本地 Python 环境冲突。完整的安装指南（包含 Python 版本要求、虚拟环境创建、按组件安装可选依赖等）请查阅官方安装文档。建议在干净的虚拟环境里安装，尤其是需要额外编译依赖（如本地向量库）时。

五、核心特性（Features 逐条翻译）

下面把 README 的 Features 一节逐条翻译。

5.1 为生产而生的智能体

Haystack 的智能体支持生命周期钩子（lifecycle hooks）：before_llm、before_tool、on_exit 等，你可以用它们实现护栏（guardrails）和自定义逻辑——比如在调用模型前先做输入校验、在调用工具前检查权限、在退出时记录日志；同时开箱即用地追踪 step_count（步数）、token_usage（token 消耗）和工具调用记录，方便监控与成本控制。想快速上手可以直接用官方 Agent Pack 里现成的智能体——比如深度研究智能体、高级 RAG 智能体；也可以用 SkillToolset 给自己的智能体做渐进式技能发现，让技能描述只在需要时才进入上下文，避免把一大堆工具描述一次性塞进上下文窗口造成浪费。

5.2 为上下文工程而设计

你可以用显式控制来设计灵活系统：信息在到达模型之前如何被检索、排序、过滤、组合、结构化和路由，全部由你定义。流水线和智能体工作流里的检索、记忆、工具、生成都是透明、可追踪的——这正是生产环境调优 RAG 质量所需要的。换句话说，Haystack 把「上下文」当成一等公民：不是把所有东西一股脑塞进提示词，而是像搭流水线一样精心设计哪些信息、以什么顺序、在什么时候进入模型视野。

5.3 原生异步支持

同一条 Pipeline 既可以同步运行，也可以异步运行，并能逐 token 流式输出——前端可以边生成边显示，不用等整段回答写完；Agent 还能并发调用多个工具，比如同时查两个数据库再汇总结果，减少串行等待。这对高并发线上服务和需要实时流式回答的聊天界面都非常友好，也是从 2.x 重写后重点强化的能力。

5.4 模块化、可定制

检索、索引、工具调用、记忆、评估都有内置组件，你也可以自己写组件——只要实现统一的 run 接口，就能像积木一样插进任何流水线。流水线里可以加循环、分支和条件逻辑，精确控制上下文如何在流水线和智能体工作流里流动，比如「检索结果为空时自动转网络搜索」「分数低于阈值时换模型重试」这类策略都可以显式搭出来。

5.5 模型与厂商无关

原生集成 OpenAI、Mistral、Anthropic、Cohere、Hugging Face、Google、Azure OpenAI、AWS Bedrock、本地模型等众多供应商；换模型或换基础设施组件时，不用重写整个系统。社区生态里还有 llama-cpp、Ollama、vLLM、LiteLLM、OpenRouter 等本地与聚合路由集成，文档存储侧覆盖 Elasticsearch、OpenSearch、Pinecone、Qdrant、Weaviate、Chroma、FAISS、pgvector、MongoDB Atlas、Snowflake 等几乎所有主流向量库。这意味着你今天用 OpenAI 开发、明天想切到本地 Llama、后天想把向量库从 Pinecone 换成 pgvector，都只需要改组件构造参数，流水线逻辑一行不用动。

5.6 可扩展的生态系统

所有自定义组件都遵循统一接口，社区和第三方可以很方便地扩展 Haystack。官方维护的 haystack-core-integrations 仓库收录了上百个现成集成，按类型分为文档存储（Document Store）、生成器（Generator）、嵌入器（Embedder）、重排器（Ranker）、转换器（Converter）、工具（Tool）、追踪器（Tracer）、评估器（Evaluator）、记忆（Memory）等。

部署小提示：官方推荐用 Hayhooks 把流水线和智能体包装成 REST API 或 MCP 服务器暴露出去——它支持自定义逻辑、HTTP 端点、OpenAI 兼容的聊天补全接口，并且能直接对接 open-webui 这类聊天界面。

六、使用方法

6.1 新手入门路径

如果你是第一次接触 Haystack，官方建议按这个顺序学习：先读「什么是 Haystack？」建立整体概念，再跟着「快速上手指南」在几分钟内搭出第一个 LLM 应用，然后继续看教程。想找更高级用例或找点灵感，直接翻官方的 Cookbook 菜谱——里面有从简单问答到多模态、智能体、评估的完整示例。

6.2 核心组件都有哪些

Haystack 应用的基本单位是「组件 + 流水线」：DocumentStore 是知识库，负责存文档和向量；Embedder 把文本转成向量入库；Retriever 根据问题从库里检索相关片段；Ranker 对检索结果做二次精排；Generator（接 OpenAI、Anthropic 或本地模型）基于检索到的上下文生成最终回答；Router 根据条件把请求分流到不同分支；Evaluator 给流水线输出打分。把这些组件按顺序接进一条 Pipeline，就得到一个 RAG 系统；需要更复杂的分支时在流水线里加条件路由；需要自主决策时，用 Agent 挂上工具让它自己决定下一步查什么。举个典型 RAG 例子：用户提问进来 → Retriever 从 DocumentStore 召回 10 条相关片段 → Ranker 精排出最相关的 3 条 → Generator 把这 3 段上下文连同问题一起交给大模型 → 输出带出处的回答。整条链上每一步都可以单独换模型、单独评估、单独埋点。

6.3 企业版与托管平台

官方提供两层商业化支持：Haystack Enterprise Starter 给你专家支持、企业级模板、云和本地部署指南，适合想快速落地但需要官方兜底的团队；Haystack Enterprise Platform 则是一个完整托管平台，帮你构建、测试、部署和运维 Haystack 流水线，内置可观测性、协作、治理和访问控制，提供托管云服务或自部署两种形态，适合有合规要求、需要多团队协作运营的大型组织。

七、遥测与隐私

Haystack 会收集匿名的流水线组件使用统计：每次组件被初始化时上报一个事件，官方据此了解哪些组件在社区里最常用、该优先维护哪些集成。上报内容不包含你的文档、查询或 API Key，你可以随时选择退出（opt out），具体说明和关闭方法见官方遥测文档。

八、社区与贡献

如果你有功能需求或 bug 报告，直接在 GitHub 开 Issue，官方团队会定期查看并快速响应。想讨论话题或咨询怎么把 Haystack 用到自己项目里，可以在 GitHub Discussions 或 Discord 频道 发帖，官方也在 X（Twitter） 和 Stack Overflow 上答疑。

贡献方面官方非常开放——哪怕只是改个错别字也算有意义的改进，不要求你是 Haystack 专家。贡献入口有三个：给主项目提交 PR、在 haystack-core-integrations 仓库贡献新集成、或者在 docs-website 里改进文档。官方还维护了一份「开放贡献 Issue 列表」，新手可以从那里挑容易上手的任务开始。

九、常见问题（FAQ）

问：Haystack 和 LangChain 有什么区别？ Haystack 更强调生产级可控性——流水线结构显式、组件可追踪、内置评估与监控；LangChain 偏向快速拼装各种调用链。两者都能做 RAG，Haystack 在企业落地场景（如官方列出的 Airbus、Netflix、Comcast）中用得更多。

问：本地模型能用吗？ 可以。生态里有 llama-cpp、Ollama、vLLM、Transformers 等集成，不需要绑死 OpenAI。

问：Haystack 支持 MCP 吗？ 支持。官方集成仓库里有 mcp-haystack 工具组件，可以把 MCP server 上的工具挂进智能体；反过来用 Hayhooks 也能把自己的流水线暴露成 MCP server 给别的客户端调用。

问：怎么把流水线变成线上 API？ 用官方 Hayhooks 把流水线包成 REST API 或 MCP 服务器，支持 OpenAI 兼容接口，可直接对接 open-webui。

问：Haystack 1.x 和 2.x 有什么区别？ 2023 年发布的 2.x 是完全重写版：组件接口更统一、原生支持异步与流式、流水线即代码、默认包名改为 haystack-ai；老的 1.x（Pipeline + DocumentStore 老接口）已不再是 main 分支。新用户直接用 2.x。

问：默认会上报什么数据？ 只上报匿名的组件初始化事件，用于统计组件使用热度；可随时按文档说明 opt out。

问：Haystack 里「流水线」和「智能体」是什么关系？ 流水线是固定的 DAG：组件按你定义的顺序和分支跑，适合可控的 RAG；智能体是动态的：模型自己决定下一步调哪个工具，适合开放式任务。两者可以混用，比如在流水线的某一步里嵌一个智能体。

问：怎么做效果评估？ 官方内置了 Evaluator 组件，生态里还有 RAGAS、DeepEval 等专门的评估集成，可以在流水线跑完后自动打分，回归测试用。

问：怎么追踪线上运行？ 生态里有 Langfuse、Datadog、OpenTelemetry、Weave 等 Tracer 集成，把流水线每一步的输入输出和 token 消耗导出到你自己的可观测平台。

问：文档里的图片和 PDF 怎么解析？ 官方集成了 Apache Tika、Unstructured、Docling、Azure Document Intelligence、PaddleOCR、LibreOffice、Gotenberg 等一堆 Converter 组件，PDF、Word、网页、图片都能转成纯文本再进流水线。

问：想贡献代码从哪里开始？ 三条路：贡献主项目、贡献 haystack-core-integrations 里的集成、或者贡献文档网站；官方维护了一份「开放贡献 Issue 列表」，新手从 typo 修复开始也欢迎。

问：哪些大公司在用 Haystack？ 技术与 AI 基础设施领域有 Apple、Meta、Databricks、NVIDIA、Intel；公共部门有欧盟委员会、德国联邦研究技术与航天部；企业与工业场景有 Airbus、汉莎航空工业解决方案、英飞凌、乐高、Comcast、埃森哲；知识与内容平台有 Netflix、ZEIT Online、乐天、牛津大学出版社。如果你也在用 Haystack，官方欢迎开 PR 或填表分享你的故事。

十、跳转链接

• 官网：haystack.deepset.ai
• 官方文档：docs.haystack.deepset.ai
• GitHub 仓库：deepset-ai/haystack
• PyPI：haystack-ai
• 快速上手：Quick Start
• 教程：Tutorials
• Cookbook：haystack.deepset.ai/cookbook
• 核心集成：haystack-core-integrations
• Agent Pack：agent_pack
• 部署工具 Hayhooks：deepset-ai/hayhooks
• 企业版：Haystack Enterprise
• 社区 Discord：Discord
• GitHub Issues：issues