项目概述

Haystack 是一个端到端的 LLM（大型语言模型）框架，允许开发者构建由 LLMs、Transformer 模型和向量搜索等技术支持的应用。无论是执行检索增强生成（RAG）、文档搜索、问答还是答案生成，Haystack 都能将最先进的嵌入模型和 LLMs 编排成流水线，构建完整的 NLP 应用。资料来源：README.md:1

Haystack 由 deepset 公司开发和维护，是一个开源项目，支持生产级别的 AI 应用构建。该框架的设计理念是提供对上下文工程的完全控制，让开发者能够精确管理信息的检索、排序、过滤、组合、结构化和路由过程。资料来源：README.md:40-42

核心特性

Haystack 框架具有以下核心特性，使其成为构建 LLM 应用的理想选择：

为上下文工程而构建

Haystack 允许设计灵活的系统，开发者可以明确控制信息在到达模型之前的处理方式。通过定义流水线和代理工作流，可以精确控制检索、内存、工具和路由的行为。资料来源：README.md:40-45

生产级别支持

框架经过生产环境验证，被众多知名企业和机构采用，包括 Apple、Meta、Databricks、NVIDIA、Intel 等科技巨头，以及欧盟委员会等公共部门机构。资料来源：README.md:97-104

技术架构

整体架构

graph TD
    A[用户应用] --> B[Haystack Pipeline]
    B --> C[检索组件]
    B --> D[LLM 组件]
    B --> E[Agent 组件]
    C --> F[向量数据库]
    D --> G[外部 LLM API]
    E --> H[工具调用]
    F --> I[文档存储]
    G --> J[模型输出]
    H --> K[执行结果]

组件架构

Haystack 的组件架构设计支持多种集成方式，主要包括以下几类：

安装与部署

pip 安装

获取 Haystack 最简单的方式是通过 pip 安装：

pip install haystack-ai

对于想尝试最新功能的用户，可以安装预发布版本：

pip install --pre haystack-ai

资料来源：README.md:23-29

Docker 部署

Haystack 提供官方 Docker 镜像，支持多平台架构。镜像通过 BuildKit 构建，使用 bake 进行流程编排。

构建自定义镜像的命令如下：

docker buildx bake base

如需使用特定分支或标签构建：

HAYSTACK_VERSION=mybranch_or_tag BASE_IMAGE_TAG_SUFFIX=latest docker buildx bake base --no-cache

资料来源：docker/README.md:1-45

文档系统

文档网站结构

Haystack 的文档网站基于 Docusaurus 3 构建，托管在 https://docs.haystack.deepset.ai。文档系统采用版本化管理，支持多版本并行维护。资料来源：docs-website/README.md:1-15

graph LR
    A[docs/] -->|主要文档| B[guides/]
    A --> C[concepts/]
    A --> D[pipeline-components/]
    E[reference/] -->|自动生成| F[API 文档]
    G[versioned_docs/] -->|版本快照| H[历史版本]

文档目录结构

资料来源：docs-website/README.md:24-40

llms.txt 生成

文档网站支持生成 llms.txt 文件，方便 AI 工具消费文档内容。该功能由 docusaurus-plugin-generate-llms-txt 插件实现。资料来源：docs-website/README.md:83-98

API 参考

Haystack 使用 haystack-pydoc-tools 从代码文档字符串生成 Markdown 格式的 API 参考文档。所有 API 文档更新都先在 unstable docs 版本中发布，在新版本发布时才会合并到 stable docs 版本。资料来源：pydoc/README.md:1-18

API 文档工作流

graph LR
    A[代码文档字符串] -->|GitHub Actions| B[docusaurus_sync.yml]
    B --> C[API Markdown 生成]
    C --> D[unstable docs]
    D -->|版本发布| E[stable docs]

如需为新模块生成 API 页面，需在 pydoc 目录中创建 .yml 配置文件来指定生成规则。资料来源：pydoc/README.md:14-18

CI/CD 与自动化

持续集成

Haystack 项目维护严格的 CI/CD 流程，包括：

资料来源：README.md:5-16

文档版本管理

文档版本发布与 Haystack 版本发布完全自动化，通过以下工作流实现：

贡献者无需手动创建或管理版本，版本化流程完全自动化。资料来源：docs-website/README.md:64-72

导航系统

导航高亮机制

文档网站的导航系统采用智能高亮机制，确保用户在浏览不同文档类别时获得正确的导航状态。系统通过以下规则防止跨高亮：

graph TD
    A[当前页面路径] --> B{检查路径前缀}
    B -->|docs/| C{当前插件}
    B -->|reference/| D{当前插件}
    C -->|DEFAULT_PLUGIN_ID| E[高亮 Docs]
    C -->|reference| F[不高亮]
    D -->|reference| G[高亮 API Reference]
    D -->|DEFAULT_PLUGIN_ID| H[不高亮]

关键路径前缀定义如下：

const REFERENCE_PATH_PREFIX = '/reference/';
const DOCS_PATH_PREFIX = '/docs/';

资料来源：docs-website/src/theme/NavbarItem/DocNavbarItem/index.js:1-50

搜索功能

搜索系统架构

文档网站实现了自定义搜索系统，支持按类型筛选和分组展示结果。资料来源：docs-website/src/theme/SearchBar.js:1-80

搜索结果处理流程：

graph TD
    A[搜索查询] --> B[文档分组]
    B --> C[计算相关性得分]
    C --> D[按得分排序]
    D --> E[生成摘要片段]
    E --> F[返回结果列表]

社区与贡献

贡献渠道

Haystack 欢迎社区贡献，包括但不限于：

资料来源：README.md:111-121

用户案例

Haystack 被广泛应用于各行业：

资料来源：README.md:97-104

相关资源

环境要求

资料来源：README.md

安装方式

Haystack 提供多种安装方式，满足不同场景需求。

使用 pip 安装（推荐）

# 安装稳定版本
pip install haystack-ai

# 安装预发布版本（包含最新功能）
pip install --pre haystack-ai

资料来源：README.md:1

使用 Docker

Haystack 提供预配置的 Docker 镜像，适合快速部署和开发环境隔离：

# 构建基础镜像
docker buildx bake base

# 使用自定义版本构建
HAYSTACK_VERSION=mybranch_or_tag BASE_IMAGE_TAG_SUFFIX=latest docker buildx bake base --no-cache

Docker 镜像包含预装的 Python 环境和 Haystack，可直接作为基础镜像使用。

资料来源：docker/README.md:1

项目结构概览

haystack/
├── docs-website/          # Docusaurus 文档网站
│   ├── docs/             # 主文档（指南、教程、概念）
│   ├── reference/        # API 参考（自动生成）
│   └── src/              # React 组件
├── docker/               # Docker 配置
├── examples/            # 示例代码（已迁移至独立仓库）
└── pydoc/               # API 文档生成配置

资料来源：docs-website/README.md

创建第一个应用

基本组件架构

graph TD
    A[用户查询] --> B[Pipeline]
    B --> C[Retriever 检索器]
    B --> D[Prompt 模板]
    C --> E[Document Store 文档库]
    D --> F[LLM 大语言模型]
    E --> G[检索结果]
    G --> D
    F --> H[最终答案]

核心组件说明

文档网站本地开发

如果你需要为 Haystack 文档做贡献或自定义文档站点：

环境准备

# 克隆仓库
git clone https://github.com/deepset-ai/haystack.git
cd haystack/docs-website

# 安装依赖
npm install

启动开发服务器

npm start
# 文档网站地址: http://localhost:3000

生产环境检查

npm run build && npm run serve

资料来源：docs-website/README.md

常见任务参考

资料来源：docs-website/README.md

下一步

• 查看完整安装文档了解更多安装选项
• 阅读 "What is Haystack?" 了解核心概念
• 访问 Cookbook 获取高级用例和示例代码
• 示例代码已迁移至 haystack-cookbook 仓库

资料来源：examples/README.md, README.md

版本管理

Haystack 文档版本与代码版本同步发布，完全自动化管理：

graph LR
    A[代码提交] --> B[GitHub Workflow]
    B --> C[API 参考同步]
    B --> D[版本化文档生成]
    C --> E[Unstable Docs]
    D --> E
    E --> F[发布时同步到 Stable]

自动化工作流包括：

• promote_unstable_docs.yml - 发布时自动触发
• minor_version_release.yml - 创建新版本目录

资料来源：docs-website/README.md

技术栈

资料来源：pydoc/README.md

概述

Haystack 2.x 是一个专为上下文工程设计的开源框架，其核心目标是帮助开发者构建灵活的系统，实现对信息检索、排序、过滤、组合、结构化和路由的精确控制。资料来源：README.md:1-5

框架的主要特性包括：

• 上下文工程导向：设计灵活的系统，显式控制信息如何被检索、排序、过滤、组合、结构化和路由
• RAG 和 Agents 支持：构建生产级别的检索增强生成系统和智能代理
• 模块化架构：通过组件和管道实现高度可定制的工作流
• 多源集成：支持与各种 LLM 提供商、向量数据库和文档处理工具的集成

资料来源：README.md:1-5

核心组件

Haystack 的架构围绕三个主要概念展开：组件（Components）、管道（Pipelines）和数据类（Data Classes）。

graph TD
    A[Haystack 应用] --> B[管道 Pipeline]
    B --> C[组件 Components]
    C --> D[数据类 Data Classes]
    E[LLM 提供商] --> B
    F[向量数据库] --> B
    G[文档源] --> B

组件（Components）

组件是 Haystack 管道中的基本构建块。每个组件负责执行特定的 NLP 任务，如文档检索、文本生成、文本嵌入等。

组件类型分类：

管道（Pipelines）

管道是连接和组织组件的核心机制。管道定义了数据在组件之间的流动方式，使得复杂的 NLP 工作流得以实现。

管道类型：

1. 搜索管道（Search Pipeline）：用于文档检索和问答场景
2. 索引管道（Indexing Pipeline）：用于处理和存储文档
3. 代理管道（Agent Pipeline）：用于构建对话代理和工作流自动化

管道配置特点：

• 支持条件路由：根据条件选择不同的处理路径
• 并行执行：多个组件可同时处理数据
• 动态输入/输出：组件可接收多个输入并产生多个输出
• 可序列化：管道配置可保存为 YAML 文件

资料来源：README.md:1-5

数据类（Data Classes）

Haystack 使用标准化的数据类来表示文档、响应和元数据。这些数据类确保组件之间的数据传递具有一致性和类型安全性。

核心数据类：

资料来源：README.md:1-5

文档处理流程

Haystack 支持完整的文档处理流程，从原始文档输入到最终答案输出：

graph LR
    A[文档输入] --> B[文档转换器]
    B --> C[文档存储]
    C --> D[检索器]
    D --> E[读取器]
    E --> F[答案输出]
    
    G[用户查询] --> D

索引阶段

1. 文档加载：从各种来源加载文档（PDF、HTML、Markdown 等）
2. 文档转换：将文档分割成适合处理的块
3. 向量化：使用嵌入模型将文本转换为向量表示
4. 存储：将文档和向量存储到向量数据库

检索阶段

1. 查询处理：将用户问题转换为向量表示
2. 相似度搜索：在向量数据库中查找最相关的文档
3. 结果排序：可选地使用排序器优化结果顺序

回答阶段

1. 上下文构建：将检索到的文档组合成上下文
2. 答案生成：使用 LLM 基于上下文生成答案
3. 后处理：格式化输出结果

资料来源：README.md:1-5

代理系统

Haystack 的代理系统允许构建能够自主决策和执行复杂任务对话式 AI 应用。

代理核心功能：

• 工具调用：代理可以调用多种工具完成特定任务
• 对话记忆：维护对话历史以支持多轮对话
• 路由决策：根据上下文选择下一步行动
• 函数调用：与外部 API 和服务交互

graph TD
    A[用户输入] --> B[代理 Agent]
    B --> C{决策}
    C -->|调用工具| D[工具执行]
    D --> E[结果处理]
    E --> B
    C -->|生成回复| F[最终响应]
    E --> F

资料来源：README.md:1-5

版本管理

Haystack 文档支持多版本管理，包括：

开发者可以通过文档网站的版本选择器访问不同版本的文档。资料来源：docs-website/src/pages/versions.js:1-40

快速入门

安装 Haystack 最简单的方式是通过 pip：

pip install haystack-ai

如需安装预发布版本以体验最新功能：

pip install --pre haystack-ai

资料来源：README.md:1-5

文档资源

Haystack 提供完整的文档资源支持：

资料来源：README.md:1-5

相关仓库

Haystack 生态系统包括多个相关仓库：

示例代码已移至 haystack-cookbook 仓库。资料来源：examples/README.md:1-5

总结

Haystack 的核心概念围绕组件、管道和数据类三个主要构建块展开。通过这些抽象，开发者可以灵活地构建复杂的 LLM 应用，实现从简单的问答系统到复杂的多代理工作流。框架的模块化设计使得每个组件都可以独立使用或组合使用，满足不同场景的需求。

概述

Haystack 是一个开源的 LLM（大型语言模型）框架，而 Pipeline 系统是其核心架构组件。Pipeline 允许开发者设计灵活的系统，对信息的检索、排名、过滤、组合、结构化和路由过程实现精确控制，确保这些操作在到达模型之前得到妥善管理。

Pipeline 系统支持定义管线和代理工作流，使检索、记忆、工具调用和生成过程透明且可追踪。资料来源：README.md

核心特性

上下文工程导向

Pipeline 系统专为上下文工程（Context Engineering）而构建，提供了对数据流的显式控制能力。开发者可以精确控制信息从输入到输出的整个生命周期。

循环、分支和条件逻辑

Pipeline 支持添加循环（loops）、分支（branches）和条件逻辑（conditional logic），以精确控制上下文如何在 Pipeline 和代理工作流中流动。资料来源：README.md

透明性和可追溯性

所有通过 Pipeline 的数据流动都是透明的，开发者可以追踪每个处理步骤，便于调试和优化。

架构流程

graph TD
    A[用户输入] --> B[Pipeline 入口]
    B --> C{路由决策}
    C -->|检索路径| D[检索组件]
    C -->|工具调用| E[工具组件]
    C -->|生成路径| F[生成组件]
    D --> G[结果处理]
    E --> G
    F --> G
    G --> H{条件判断}
    H -->|继续| B
    H -->|结束| I[最终输出]

Pipeline 类型

文档资源

Haystack 提供了全面的 Pipeline 相关文档，涵盖以下主题：

资料来源：docs-website/README.md

与其他组件的集成

Pipeline 系统与以下核心组件紧密集成：

• 检索组件（Retrieval）：处理信息检索和排名
• 工具组件（Tools）：支持工具调用功能
• 记忆组件（Memory）：管理对话上下文状态
• 生成组件（Generation）：处理最终输出生成

与 Hayhooks 的集成

如需将 Pipeline 部署为 REST API 或 MCP 服务器，可以使用 Hayhooks。Hayhooks 提供了一种简单的方式将 Pipeline 和代理包装为自定义逻辑，并通过 HTTP 端点或 MCP 协议暴露它们。资料来源：README.md

开发环境

文档网站使用 Docusaurus 3 构建，支持实时预览 Pipeline 文档变更。开发环境要求：

• Node.js：18 或更高版本
• 包管理器：npm 或 Yarn

快速启动命令：

cd haystack/docs-website
npm install
npm start

预览地址：http://localhost:3000

资料来源：docs-website/README.md

版本管理

Pipeline 文档与 Haystack 版本同步发布，通过以下自动化工作流管理：

• promote_unstable_docs.yml：在 Haystack 发布期间自动触发
• minor_version_release.yml：创建新版本目录并更新版本配置

资料来源：docs-website/README.md

相关链接

概述

Haystack 的文档存储系统（Document Store）是构建检索增强生成（RAG）和其他 NLP 应用的核心基础设施。文档存储系统负责存储、索引和管理文档向量嵌入（Embeddings），为后续的语义搜索和相似性检索提供支持。

在 Haystack 框架中，文档存储系统扮演着数据持久化层的角色，它与检索管道（Retrieval Pipeline）紧密集成，使得大规模文档集合能够被高效查询。资料来源：docs-website/docs/concepts/document-store.mdx

架构设计

核心组件关系

graph TD
    A[文档输入] --> B[文档转换器 DocumentConverter]
    B --> C[Document 对象]
    C --> D[文档存储系统 DocumentStore]
    D --> E[向量数据库]
    F[查询请求] --> G[向量化器 Embedder]
    G --> H[查询向量]
    H --> D
    D --> I[相似性检索]
    I --> J[检索结果]

文档存储系统类型

Haystack 支持多种文档存储系统实现，每种实现针对不同的使用场景和规模进行了优化。

资料来源：docs-website/docs/document-stores/inmemorydocumentstore.mdx, docs-website/docs/document-stores/qdrant-document-store.mdx, docs-website/docs/document-stores/weaviatedocumentstore.mdx

文档管理

写入操作

文档存储系统支持批量写入文档，这一操作通常与文档转换器配合使用。

graph LR
    A[源文档] --> B[DocumentConverter]
    B --> C[Document 列表]
    C --> D[write_documents]
    D --> E[DocumentStore]
    E --> F[向量索引]

关键写入方法包括：

资料来源：docs-website/docs/concepts/document-store.mdx

检索操作

文档存储系统提供多种检索方式，支持不同的查询策略。

资料来源：docs-website/docs/document-stores/qdrant-document-store.mdx

配置与集成

基础配置

文档存储系统在 Haystack Pipeline 中通过组件方式集成。以下是典型的配置模式：

from haystack import Pipeline
from haystack.document_stores import InMemoryDocumentStore

# 初始化文档存储
document_store = InMemoryDocumentStore(
    embedding_dim=768,
    return_embedding=True
)

# 创建管道
pipeline = Pipeline()
pipeline.add_component("document_store", document_store)

环境变量

文档存储系统的某些配置可以通过环境变量进行控制，这在不同部署环境中提供了灵活性。

资料来源：docker/README.md, docs-website/src/theme/Html.js

生产环境部署

Docker 部署

Haystack 提供预配置的 Docker 镜像，适用于生产环境部署。

镜像构建使用 BuildKit 和 bake 工具：

docker buildx bake base

资料来源：docker/README.md

外部向量数据库集成

对于大规模生产环境，建议使用专门的向量数据库：

#### Qdrant 集成

Qdrant 是一个高性能的向量相似性搜索引擎，支持：

• 混合检索能力
• 元数据过滤
• 稀疏和密集向量支持
• 地理空间查询

资料来源：docs-website/docs/document-stores/qdrant-document-store.mdx

#### Weaviate 集成

Weaviate 是另一个企业级向量数据库，特点包括：

• 内置向量化功能
• 原生图结构支持
• 多租户架构
• 实时索引更新

资料来源：docs-website/docs/document-stores/weaviatedocumentstore.mdx

最佳实践

开发与生产环境分离

性能优化建议

1. 批量处理：使用批量写入减少网络开销
2. 索引优化：根据数据规模选择合适的向量维度
3. 缓存策略：对频繁查询使用结果缓存
4. 分片策略：大规模数据考虑分片部署

资料来源：docs-website/docs/concepts/document-store.mdx

文档资源

Haystack 文档网站提供完整的文档存储系统参考资料，访问地址：https://docs.haystack.deepset.ai

资料来源：docs-website/README.md

API 参考文档通过 haystack-pydoc-tools 自动从代码 docstring 生成，确保与代码库同步更新。

资料来源：pydoc/README.md

概述

Haystack 是一个开源 LLM 框架，用于构建生产级 AI 应用，其核心功能之一是文档转换与预处理。这一功能模块负责将各种格式的原始文档转换为可供检索和处理的结构化文档对象。

文档转换与预处理是检索增强生成（RAG）管道中的关键环节，直接影响后续检索质量和生成效果。Haystack 提供了完整的文档处理工具链，涵盖从原始文件到可检索文本的完整转换流程。

资料来源：README.md

架构概览

graph TD
    A[原始文档] --> B[文档转换器]
    B --> C[文档对象 Document]
    C --> D[预处理器]
    D --> E[清洗后的文档]
    E --> F[向量化]
    F --> G[向量存储]
    
    B1[PDF] --> B
    B2[Word] --> B
    B3[HTML] --> B
    B4[TXT] --> B
    B5[Markdown] --> B
    
    D1[文本清洗] --> D
    D2[文档分割] --> D
    D3[元数据提取] --> D

文档转换器 (Converters)

文档转换器是将各种格式的原始文件转换为 Haystack Document 对象的组件。Haystack 支持多种输入格式的转换。

支持的转换格式

转换器组件

文档转换器作为 Pipeline 组件集成到 Haystack 系统中，可以直接连接到索引管道进行处理。

Pipeline 结构示例:
DocumentConverter → Preprocessor → DocumentStore

资料来源：README.md

预处理器 (Preprocessors)

预处理器负责对转换后的文档进行进一步处理，确保数据质量并优化检索性能。

核心预处理功能

#### 文档分割 (Document Splitting)

文档分割是将长文档拆分为较小块的常用技术，用于：

• 适配模型上下文窗口: 大多数 LLM 有 token 数量限制
• 提高检索精度: 较小的文本块更容易匹配用户查询
• 优化召回率: 相关内容更容易被准确检索

#### 文本清洗 (Text Cleaning)

文本清洗功能包括：

• 移除多余空白字符
• 标准化标点符号
• 处理特殊字符和编码问题
• 提取或清理元数据

预处理工作流

graph LR
    A[原始文本] --> B[分句]
    B --> C[块划分]
    C --> D[重叠处理]
    D --> E[元数据附加]
    E --> F[最终文档块]
    
    C --> G[大小检查]
    G -->|过大| H[递归分割]
    H --> D
    G -->|合适| D

文档对象模型

Haystack 使用 Document 类作为核心数据结构来表示处理后的文档。

Document(
    id: str,
    content: str,
    meta: Dict[str, Any]
)

与管道组件的集成

索引管道中的位置

graph TD
    subgraph 索引管道
        A[文件输入] --> B[Converter]
        B --> C[Preprocessor]
        C --> D[Embedder]
        D --> E[DocumentStore]
    end
    
    subgraph 检索管道
        F[用户查询] --> G[Retriever]
        G --> H[Prompt]
        H --> I[Generator]
        I --> J[答案输出]
    end
    
    E --> G

文档转换与预处理组件位于索引管道的前端，确保进入系统的文档具有良好的质量和格式。

资料来源：docs-website/README.md

配置与使用

基础配置项

最佳实践

1. 块大小选择: 根据使用的 embedding 模型和 LLM 上下文窗口大小来调整
2. 重叠设置: 对于需要跨块理解的内容，适当设置重叠可以提高召回质量
3. 元数据保留: 在转换过程中保留重要的元数据信息，便于后续筛选和溯源
4. 质量验证: 在生产环境中添加转换质量检查步骤

与其他组件的关系

文档转换与预处理模块与 Haystack 的其他核心组件紧密协作：

资料来源：README.md

安装与依赖

文档转换与预处理功能已包含在主包中：

pip install haystack-ai

对于特定的转换器，可能需要额外的依赖：

# PDF 转换
pip install haystack-ai[pdf]

# Word 文档转换
pip install haystack-ai[docx]

资料来源：README.md

相关资源

• 官方文档
• Haystack GitHub 仓库
• API 参考文档

版本说明

文档转换与预处理的 API 和行为在不同版本间可能存在差异。建议始终使用与 Haystack 主版本匹配的文档版本。

资料来源：docs-website/src/pages/versions.js

概述

文本嵌入组件（Text Embedders）是 Haystack 框架中用于将文本转换为高维向量表示的核心组件。在检索增强生成（RAG）系统中，嵌入组件负责将文档和查询文本编码为语义向量，使得基于向量相似度的语义检索成为可能。

Haystack 提供了多种文本嵌入组件，支持主流的 embedding 服务提供商，包括 OpenAI、HuggingFace API 等。这些组件可以作为流水线（Pipeline）的一部分，在文档索引阶段将文档内容向量化，在查询阶段将用户查询向量化。

核心架构

组件分类

Haystack 的文本嵌入组件主要分为两大类：

资料来源：docs-website/docs/pipeline-components/embedders.mdx

数据流架构

graph TD
    A[文本输入] --> B[文本嵌入组件]
    B --> C{Provider 类型}
    C -->|OpenAI| D[OpenAITextEmbedder]
    C -->|HuggingFace| E[HuggingFaceAPITextEmbedder]
    D --> F[嵌入向量输出]
    E --> F
    F --> G[向量存储/检索]

OpenAI 文本嵌入组件

组件简介

OpenAITextEmbedder 是 Haystack 官方提供的 OpenAI embedding 模型集成组件。该组件通过调用 OpenAI 的 embedding API 将文本转换为 1536 维的稠密向量（使用 text-embedding-3-small 模型）或 3072 维向量（使用 text-embedding-3-large 模型）。

资料来源：docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx

初始化参数

使用示例

from haystack.components.embedders import OpenAITextEmbedder

embedder = OpenAITextEmbedder(
    api_key="your-api-key",
    model="text-embedding-3-small",
    dimensions=1024
)

result = embedder.run(text="What is retrieval-augmented generation?")
print(result["embedding"][:5])  # 输出向量前5个维度

维度控制

text-embedding-3 系列模型支持通过 dimensions 参数控制输出向量维度，这使得用户可以在保持语义表达能力的同时减少存储空间和计算成本。

资料来源：docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx

HuggingFace API 文本嵌入组件

组件简介

HuggingFaceAPITextEmbedder 提供了对 HuggingFace Inference API 的集成支持。该组件允许用户使用 HuggingFace Hub 上托管的各种 embedding 模型，无需本地部署。

资料来源：docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx

初始化参数

使用示例

from haystack.components.embedders import HuggingFaceAPITextEmbedder

embedder = HuggingFaceAPITextEmbedder(
    api_key="hf-xxxxx",
    model="sentence-transformers/all-MiniLM-L6-v2"
)

result = embedder.run(text="Building RAG pipelines with Haystack")

支持的模型

该组件支持 HuggingFace Hub 上的所有支持 embedding 的模型，常见选择包括：

资料来源：docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx

在流水线中使用嵌入组件

RAG 流水线架构

graph LR
    A[用户查询] --> B[TextEmbedder]
    B --> C[向量检索器]
    D[文档库] --> E[DocumentEmbedder]
    E --> F[向量数据库]
    C --> G[上下文组装]
    G --> H[LLM 生成]
    H --> I[最终回答]

完整流水线示例

from haystack import Pipeline
from haystack.components.embedders import OpenAITextEmbedder
from haystack.components.retrievers import InMemoryBM25Retriever
from haystack.document_stores import InMemoryDocumentStore

# 初始化组件
document_store = InMemoryDocumentStore()
retriever = InMemoryBM25Retriever(document_store=document_store)
embedder = OpenAITextEmbedder(api_key="your-key")

# 构建查询流水线
pipeline = Pipeline()
pipeline.add_component("embedder", embedder)
pipeline.add_component("retriever", retriever)

# 连接组件
pipeline.connect("embedder.embedding", "retriever.query_embedding")

资料来源：docs-website/docs/pipeline-components/embedders.mdx

输出格式

标准输出结构

所有文本嵌入组件的 run() 方法返回统一格式的字典：

result = embedder.run(text="Hello, Haystack!")
# result = {
#     "embedding": [0.123, -0.456, 0.789, ...],
#     "meta": {"model": "text-embedding-3-small", "usage": {...}}
# }

最佳实践

1. 向量维度选择

• 存储空间敏感场景：选择支持维度缩减的模型（如 text-embedding-3）
• 高精度需求场景：使用高维度模型（如 all-mpnet-base-v2）
• 平衡场景：使用中等维度模型（如 all-MiniLM-L6-v2）

2. 批处理优化

对于大量文档的索引任务，使用支持批处理的嵌入组件可以显著提升性能：

from haystack.components.embedders import HuggingFaceAPITextEmbedder

embedder = HuggingFaceAPITextEmbedder(
    model="sentence-transformers/all-MiniLM-L6-v2",
    batch_size=64  # 根据 API 限制调整
)

3. 错误处理

建议在实际应用中实现重试机制和降级策略：

from haystack.components.embedders import OpenAITextEmbedder
from tenacity import retry, wait_exponential

@retry(wait=wait_exponential(multiplier=1, min=2, max=10))
def embed_with_retry(embedder, text):
    return embedder.run(text=text)

相关组件

资料来源：docs-website/docs/pipeline-components/embedders.mdx

扩展阅读

• Haystack 官方文档
• RAG 流水线教程
• HuggingFace Embedding 模型列表

概述

LLM 生成器（LLM Generator）是 Haystack 框架中的核心组件之一，专门用于与大型语言模型（Large Language Models）进行交互。在 Haystack 2.x 架构中，生成器作为管道（Pipeline）的关键组件，负责接收输入提示（Prompt）并生成自然语言响应。

资料来源：README.md:1-10

Haystack 是一个端到端的 LLM 框架，允许你构建由 LLMs、Transformer 模型、向量搜索等驱动的应用程序。无论是执行检索增强生成（RAG）、文档搜索、问答还是答案生成，Haystack 都可以将先进的嵌入模型和 LLMs 编排成管道，以构建端到端的 NLP 应用程序。

资料来源：docker/README.md:1-8

概述

在 Haystack 框架中，检索器（Retriever） 和 排序器（Ranker） 是构建 RAG（检索增强生成）管道的核心组件。它们共同负责从大规模文档集合中找到最相关的信息，为大语言模型提供准确的上下文。

核心功能定位

资料来源：docs-website/docs/pipeline-components/retrievers.mdx

概述

Haystack Agent 是框架中用于构建智能代理系统的核心组件，它使大型语言模型（LLM）能够通过工具调用、状态管理和多步骤推理来解决复杂任务。Agent 系统将 LLM 与外部工具、数据源和检索系统相结合，实现了自主决策和执行能力。

资料来源：docs-website/docs/concepts/agents.mdx

架构设计

核心组件

Agent 系统由多个核心组件构成，每个组件负责特定的功能职责：

资料来源：docs-website/docs/pipeline-components/agents-1/agent.mdx

组件交互流程

graph TD
    A[用户输入] --> B[Agent 主控制器]
    B --> C{决策判断}
    C -->|调用工具| D[Tool 执行层]
    C -->|更新状态| E[State 管理层]
    C -->|生成响应| F[最终输出]
    D -->|工具结果| E
    E -->|状态更新| B
    B -->|继续迭代| C

Agent 核心机制

工具调用机制

Agent 通过动态调用外部工具来扩展 LLM 的能力范围。工具可以是：

• 检索工具：连接向量数据库、执行相似性搜索
• API 工具：调用外部服务、获取实时数据
• 计算工具：执行数据处理、格式转换
• 自定义工具：用户定义的任意功能

资料来源：docs-website/docs/pipeline-components/agents-1/agent.mdx

决策循环

Agent 实现了自主决策循环，典型执行流程如下：

graph LR
    A[接收任务] --> B[LLM 推理]
    B --> C{需要工具?}
    C -->|是| D[选择工具]
    D --> E[执行工具]
    E --> F[返回结果]
    F --> B
    C -->|否| G[生成回复]
    G --> H[返回用户]

状态管理系统

State 组件

State 是 Agent 系统中负责维护执行状态的关键组件，它记录：

• 对话历史记录
• 工具调用记录
• 中间执行结果
• 上下文变量

资料来源：docs-website/docs/pipeline-components/agents-1/state.mdx

状态数据结构

State 组件使用结构化数据模型来跟踪代理执行过程：

class AgentState:
    messages: List[Dict]      # 对话历史
    tool_calls: List[Dict]    # 工具调用记录
    intermediate_steps: List  # 中间步骤
    context: Dict             # 上下文变量

状态流转图

graph TD
    A[初始状态] --> B[消息添加]
    B --> C{执行工具?}
    C -->|是| D[记录工具调用]
    D --> E[保存中间结果]
    E --> F[状态更新]
    F --> B
    C -->|否| G[标记完成]
    G --> H[最终状态]
    F --> H

使用示例

基本 Agent 配置

from haystack import Agent

agent = Agent(
    tools=[retriever, calculator, web_searcher],
    prompt_template="你是一个有帮助的助手"
)

状态初始化

from haystack.agents import AgentState

initial_state = AgentState(
    messages=[],
    tool_calls=[],
    context={}
)

资料来源：docs-website/docs/pipeline-components/agents-1/state.mdx

与 Pipeline 集成

Agent 可以作为 Pipeline 的组件进行编排，实现复杂的业务流程：

graph LR
    A[用户查询] --> B[检索 Pipeline]
    B --> C[Agent 处理]
    C --> D{需要更多数据?}
    D -->|是| E[调用工具]
    E --> B
    D -->|否| F[生成回答]
    F --> G[返回结果]

Pipeline 中的 Agent 配置

资料来源：docs-website/docs/concepts/agents.mdx

最佳实践

工具设计原则

1. 单一职责：每个工具只完成一个明确的任务
2. 清晰的输入输出：定义明确的参数和返回值
3. 错误处理：为工具添加适当的异常处理机制
4. 文档完善：提供清晰的使用说明和示例

状态管理建议

1. 定期清理：避免状态数据无限增长
2. 关键节点保存：在重要步骤记录检查点
3. 上下文优化：仅保留必要的上下文信息

配置选项

核心参数表

资料来源：docs-website/docs/pipeline-components/agents-1/agent.mdx

相关资源

• Agent 概念文档
• Agent API 参考
• State 组件参考
• Haystack 官方文档

Pitfall Log / 踩坑日志

项目：deepset-ai/haystack

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:221654678 | https://github.com/deepset-ai/haystack | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | last_activity_observed missing

3. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:221654678 | https://github.com/deepset-ai/haystack | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:221654678 | https://github.com/deepset-ai/haystack | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:221654678 | https://github.com/deepset-ai/haystack | release_recency=unknown