# Wiki Documentation for https://github.com/deepset-ai/haystack
Generated on: 2026-05-10 15:07:55 UTC
## Table of Contents
- [Haystack 简介](#introduction)
- [快速入门指南](#quick-start)
- [核心概念](#core-concepts)
- [Pipeline 系统](#pipeline-system)
- [文档存储系统](#document-stores)
- [文档转换与预处理](#converters-preprocessors)
- [文本嵌入组件](#embedders)
- [LLM 生成器](#generators)
- [排序器与检索器](#rankers-retrievers)
- [Agent 代理系统](#agents)
## Haystack 简介
### Related Pages
Related topics: [快速入门指南](#quick-start), [核心概念](#core-concepts)
Relevant source files
The following files were used as context for generating this wiki page:
- [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)
- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
- [docker/README.md](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)
- [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)
- [docs-website/src/components/CopyDropdown/index.tsx](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/components/CopyDropdown/index.tsx)
- [docs-website/src/theme/NavbarItem/DocNavbarItem/index.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/NavbarItem/DocNavbarItem/index.js)
# Haystack 简介
## 项目概述
Haystack 是一个端到端的 LLM（大型语言模型）框架，允许开发者构建由 LLMs、Transformer 模型和向量搜索等技术支持的应用。无论是执行检索增强生成（RAG）、文档搜索、问答还是答案生成，Haystack 都能将最先进的嵌入模型和 LLMs 编排成流水线，构建完整的 NLP 应用。Sources: [README.md:1]()
Haystack 由 deepset 公司开发和维护，是一个开源项目，支持生产级别的 AI 应用构建。该框架的设计理念是提供对上下文工程的完全控制，让开发者能够精确管理信息的检索、排序、过滤、组合、结构化和路由过程。Sources: [README.md:40-42]()
## 核心特性
Haystack 框架具有以下核心特性，使其成为构建 LLM 应用的理想选择：
### 为上下文工程而构建
Haystack 允许设计灵活的系统，开发者可以明确控制信息在到达模型之前的处理方式。通过定义流水线和代理工作流，可以精确控制检索、内存、工具和路由的行为。Sources: [README.md:40-45]()
### 生产级别支持
框架经过生产环境验证，被众多知名企业和机构采用，包括 Apple、Meta、Databricks、NVIDIA、Intel 等科技巨头，以及欧盟委员会等公共部门机构。Sources: [README.md:97-104]()
## 技术架构
### 整体架构
```mermaid
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 的组件架构设计支持多种集成方式，主要包括以下几类：
| 组件类别 | 说明 | 典型用途 |
|---------|------|---------|
| 检索组件 | 从文档存储中检索相关信息 | RAG 场景的信息获取 |
| LLM 组件 | 与外部 LLM API 交互 | 生成答案和摘要 |
| Agent 组件 | 自主决策和工具调用 | 复杂任务的自动化执行 |
| 管道组件 | 连接和组织各组件 | 构建完整的处理流程 |
## 安装与部署
### pip 安装
获取 Haystack 最简单的方式是通过 pip 安装：
```sh
pip install haystack-ai
```
对于想尝试最新功能的用户，可以安装预发布版本：
```sh
pip install --pre haystack-ai
```
Sources: [README.md:23-29]()
### Docker 部署
Haystack 提供官方 Docker 镜像，支持多平台架构。镜像通过 BuildKit 构建，使用 `bake` 进行流程编排。
| 镜像名称 | 说明 |
|---------|------|
| `haystack:base-` | 包含预装 Haystack 的 Python 工作环境 |
构建自定义镜像的命令如下：
```sh
docker buildx bake base
```
如需使用特定分支或标签构建：
```sh
HAYSTACK_VERSION=mybranch_or_tag BASE_IMAGE_TAG_SUFFIX=latest docker buildx bake base --no-cache
```
Sources: [docker/README.md:1-45]()
## 文档系统
### 文档网站结构
Haystack 的文档网站基于 Docusaurus 3 构建，托管在 https://docs.haystack.deepset.ai。文档系统采用版本化管理，支持多版本并行维护。Sources: [docs-website/README.md:1-15]()
```mermaid
graph LR
A[docs/] -->|主要文档| B[guides/]
A --> C[concepts/]
A --> D[pipeline-components/]
E[reference/] -->|自动生成| F[API 文档]
G[versioned_docs/] -->|版本快照| H[历史版本]
```
### 文档目录结构
| 目录 | 用途 |
|-----|------|
| `docs/` | 主要文档（指南、教程、概念） |
| `docs/_templates/` | 作者模板（构建时排除） |
| `docs/concepts/` | Haystack 核心概念 |
| `docs/pipeline-components/` | 组件文档 |
| `reference/` | API 参考（自动生成） |
| `versioned_docs/` | 版本化文档副本 |
| `src/` | React 组件和自定义代码 |
Sources: [docs-website/README.md:24-40]()
### llms.txt 生成
文档网站支持生成 `llms.txt` 文件，方便 AI 工具消费文档内容。该功能由 `docusaurus-plugin-generate-llms-txt` 插件实现。Sources: [docs-website/README.md:83-98]()
| 生成方式 | 命令 |
|---------|------|
| 开发服务器 | `npm run start` |
| 生产构建 | `npm run build` |
| 手动生成 | `npm run generate-llms-txt` |
## API 参考
Haystack 使用 haystack-pydoc-tools 从代码文档字符串生成 Markdown 格式的 API 参考文档。所有 API 文档更新都先在 unstable docs 版本中发布，在新版本发布时才会合并到 stable docs 版本。Sources: [pydoc/README.md:1-18]()
### API 文档工作流
```mermaid
graph LR
A[代码文档字符串] -->|GitHub Actions| B[docusaurus_sync.yml]
B --> C[API Markdown 生成]
C --> D[unstable docs]
D -->|版本发布| E[stable docs]
```
如需为新模块生成 API 页面，需在 `pydoc` 目录中创建 `.yml` 配置文件来指定生成规则。Sources: [pydoc/README.md:14-18]()
## CI/CD 与自动化
### 持续集成
Haystack 项目维护严格的 CI/CD 流程，包括：
| 检查项 | 状态徽章 |
|-------|---------|
| 测试 | Tests workflow |
| 类型检查 | Mypy |
| 覆盖率 | Coverage badge |
| 代码规范 | Ruff |
| 许可证合规 | License compliance |
Sources: [README.md:5-16]()
### 文档版本管理
文档版本发布与 Haystack 版本发布完全自动化，通过以下工作流实现：
| 工作流 | 功能 |
|-------|------|
| `promote_unstable_docs.yml` | Haystack 发布期间自动触发 |
| `minor_version_release.yml` | 创建新版本目录并更新版本配置 |
贡献者无需手动创建或管理版本，版本化流程完全自动化。Sources: [docs-website/README.md:64-72]()
## 导航系统
### 导航高亮机制
文档网站的导航系统采用智能高亮机制，确保用户在浏览不同文档类别时获得正确的导航状态。系统通过以下规则防止跨高亮：
```mermaid
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[不高亮]
```
关键路径前缀定义如下：
```javascript
const REFERENCE_PATH_PREFIX = '/reference/';
const DOCS_PATH_PREFIX = '/docs/';
```
Sources: [docs-website/src/theme/NavbarItem/DocNavbarItem/index.js:1-50]()
## 搜索功能
### 搜索系统架构
文档网站实现了自定义搜索系统，支持按类型筛选和分组展示结果。Sources: [docs-website/src/theme/SearchBar.js:1-80]()
| 功能 | 说明 |
|-----|------|
| 全文搜索 | 基于文档内容的语义搜索 |
| 类型过滤 | 支持按文档类型筛选 |
| 结果分组 | 按页面分组显示匹配结果 |
| 高亮显示 | 显示搜索词上下文片段 |
搜索结果处理流程：
```mermaid
graph TD
A[搜索查询] --> B[文档分组]
B --> C[计算相关性得分]
C --> D[按得分排序]
D --> E[生成摘要片段]
E --> F[返回结果列表]
```
## 社区与贡献
### 贡献渠道
Haystack 欢迎社区贡献，包括但不限于：
| 贡献类型 | 仓库 |
|---------|------|
| 核心功能开发 | main/haystack |
| 集成组件 | haystack-core-integrations |
| 文档改进 | haystack/docs-website |
Sources: [README.md:111-121]()
### 用户案例
Haystack 被广泛应用于各行业：
| 行业 | 代表用户 |
|-----|---------|
| 科技与 AI 基础设施 | Apple, Meta, Databricks, NVIDIA, Intel |
| 公共部门 | 欧盟委员会 |
| 企业 AI | 众多生产级 AI 系统团队 |
Sources: [README.md:97-104]()
## 相关资源
| 资源 | 链接 |
|-----|------|
| 官方文档 | https://docs.haystack.deepset.ai |
| GitHub 仓库 | https://github.com/deepset-ai/haystack |
| 示例代码库 | https://github.com/deepset-ai/haystack-cookbook |
| Discord 社区 | https://discord.gg/VBpFzsgacQ |
| 贡献指南 | CONTRIBUTING.md |
---
## 快速入门指南
### Related Pages
Related topics: [Haystack 简介](#introduction), [Pipeline 系统](#pipeline-system)
Relevant source files
The following files were used as context for generating this wiki page:
- [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)
- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
- [docker/README.md](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)
- [examples/README.md](https://github.com/deepset-ai/haystack/blob/main/examples/README.md)
- [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)
# 快速入门指南
Haystack 是一个开源框架，用于构建生产级 LLM 应用，支持检索增强生成（RAG）、文档搜索、问答系统等功能。本指南将帮助你在最短时间内完成环境搭建并运行第一个 Haystack 应用。
## 环境要求
| 组件 | 最低版本 | 说明 |
|------|----------|------|
| Python | 3.8+ | 推荐使用 Python 3.9 或更高版本 |
| Node.js | 18+ | 仅在使用文档网站时需要 |
| pip | 最新版 | Python 包管理器 |
Sources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)
## 安装方式
Haystack 提供多种安装方式，满足不同场景需求。
### 使用 pip 安装（推荐）
```bash
# 安装稳定版本
pip install haystack-ai
# 安装预发布版本（包含最新功能）
pip install --pre haystack-ai
```
Sources: [README.md:1](https://github.com/deepset-ai/haystack/blob/main/README.md)
### 使用 Docker
Haystack 提供预配置的 Docker 镜像，适合快速部署和开发环境隔离：
```bash
# 构建基础镜像
docker buildx bake base
# 使用自定义版本构建
HAYSTACK_VERSION=mybranch_or_tag BASE_IMAGE_TAG_SUFFIX=latest docker buildx bake base --no-cache
```
Docker 镜像包含预装的 Python 环境和 Haystack，可直接作为基础镜像使用。
Sources: [docker/README.md:1](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)
## 项目结构概览
```
haystack/
├── docs-website/ # Docusaurus 文档网站
│ ├── docs/ # 主文档（指南、教程、概念）
│ ├── reference/ # API 参考（自动生成）
│ └── src/ # React 组件
├── docker/ # Docker 配置
├── examples/ # 示例代码（已迁移至独立仓库）
└── pydoc/ # API 文档生成配置
```
Sources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
## 创建第一个应用
### 基本组件架构
```mermaid
graph TD
A[用户查询] --> B[Pipeline]
B --> C[Retriever 检索器]
B --> D[Prompt 模板]
C --> E[Document Store 文档库]
D --> F[LLM 大语言模型]
E --> G[检索结果]
G --> D
F --> H[最终答案]
```
### 核心组件说明
| 组件 | 功能 | 常见实现 |
|------|------|----------|
| Pipeline | 连接各组件的工作流编排 | `Pipeline`, `RootNode` |
| Retriever | 从文档库检索相关文档 | `BM25Retriever`, `EmbeddingRetriever` |
| Document Store | 存储和索引文档向量 | `InMemoryDocumentStore`, `OpenSearchDocumentStore` |
| Prompt | 定义提示词模板 | `PromptTemplate`, `ChatPromptBuilder` |
| LLM | 大语言模型接口 | `OpenAIChat`, `HuggingFaceTGI` |
## 文档网站本地开发
如果你需要为 Haystack 文档做贡献或自定义文档站点：
### 环境准备
```bash
# 克隆仓库
git clone https://github.com/deepset-ai/haystack.git
cd haystack/docs-website
# 安装依赖
npm install
```
### 启动开发服务器
```bash
npm start
# 文档网站地址: http://localhost:3000
```
### 生产环境检查
```bash
npm run build && npm run serve
```
Sources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
## 常见任务参考
| 任务 | 命令/操作 |
|------|-----------|
| 编辑文档页面 | 修改 `docs/` 或 `versioned_docs/` 下的文件 |
| 添加侧边栏项目 | 修改 `sidebars.js` 添加文档 ID |
| 生成 API 参考 | 提交 `.yml` 配置文件到 `pydoc/` 目录 |
| 生成 llms.txt | `npm run generate-llms-txt` |
Sources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
## 下一步
- 查看完整[安装文档](https://docs.haystack.deepset.ai/docs/installation)了解更多安装选项
- 阅读 ["What is Haystack?"](https://haystack.deepset.ai/overview/intro) 了解核心概念
- 访问 [Cookbook](https://haystack.deepset.ai/cookbook) 获取高级用例和示例代码
- 示例代码已迁移至 [haystack-cookbook](https://github.com/deepset-ai/haystack-cookbook/) 仓库
Sources: [examples/README.md](https://github.com/deepset-ai/haystack/blob/main/examples/README.md), [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)
## 版本管理
Haystack 文档版本与代码版本同步发布，完全自动化管理：
```mermaid
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` - 创建新版本目录
Sources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
## 技术栈
| 类别 | 技术 |
|------|------|
| 核心框架 | Python |
| 文档系统 | Docusaurus 3 |
| API 文档生成 | haystack-pydoc-tools |
| CI/CD | GitHub Actions |
| 容器化 | Docker BuildKit |
Sources: [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)
---
## 核心概念
### Related Pages
Related topics: [Pipeline 系统](#pipeline-system), [Agent 代理系统](#agents)
Relevant source files
The following files were used as context for generating this wiki page:
- [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)
- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
- [docs-website/src/theme/SearchBar.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/SearchBar.js)
- [docs-website/src/pages/versions.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/pages/versions.js)
- [examples/README.md](https://github.com/deepset-ai/haystack/blob/main/examples/README.md)
**Note**: The originally requested concept documentation files (`concepts-overview.mdx`, `components.mdx`, `pipelines.mdx`, `data-classes.mdx`) were not present in the provided repository context. This wiki page is constructed based on available documentation files and repository structure information.
# 核心概念
Haystack 是一个端到端的 LLM（大型语言模型）框架，用于构建由 LLMs、Transformer 模型和向量搜索驱动的应用程序。本文档介绍 Haystack 的核心概念，帮助开发者理解框架的架构设计和主要组成部分。
## 概述
Haystack 2.x 是一个专为上下文工程设计的开源框架，其核心目标是帮助开发者构建灵活的系统，实现对信息检索、排序、过滤、组合、结构化和路由的精确控制。Sources: [README.md:1-5]()
框架的主要特性包括：
- **上下文工程导向**：设计灵活的系统，显式控制信息如何被检索、排序、过滤、组合、结构化和路由
- **RAG 和 Agents 支持**：构建生产级别的检索增强生成系统和智能代理
- **模块化架构**：通过组件和管道实现高度可定制的工作流
- **多源集成**：支持与各种 LLM 提供商、向量数据库和文档处理工具的集成
Sources: [README.md:1-5]()
## 核心组件
Haystack 的架构围绕三个主要概念展开：组件（Components）、管道（Pipelines）和数据类（Data Classes）。
```mermaid
graph TD
A[Haystack 应用] --> B[管道 Pipeline]
B --> C[组件 Components]
C --> D[数据类 Data Classes]
E[LLM 提供商] --> B
F[向量数据库] --> B
G[文档源] --> B
```
### 组件（Components）
组件是 Haystack 管道中的基本构建块。每个组件负责执行特定的 NLP 任务，如文档检索、文本生成、文本嵌入等。
**组件类型分类：**
| 类型 | 功能描述 | 示例 |
|------|----------|------|
| 检索器（Retrievers） | 从文档库中检索相关文档 | BM25Retriever, EmbeddingRetriever |
| 读取器（Readers） | 从检索到的文档中提取答案 | ExtractiveReader, GenerativeReader |
| 生成器（Generators） | 使用 LLM 生成文本 | OpenAIGenerator, HuggingFaceTGI |
| 排序器（Rerankers） | 对检索结果进行重新排序 | SentenceTransformersReranker |
| 工具（Tools） | 为代理提供可调用功能 | SearchTool, CalculatorTool |
| 存储器（Memory） | 管理对话历史和上下文 | ChatMemory |
### 管道（Pipelines）
管道是连接和组织组件的核心机制。管道定义了数据在组件之间的流动方式，使得复杂的 NLP 工作流得以实现。
**管道类型：**
1. **搜索管道（Search Pipeline）**：用于文档检索和问答场景
2. **索引管道（Indexing Pipeline）**：用于处理和存储文档
3. **代理管道（Agent Pipeline）**：用于构建对话代理和工作流自动化
**管道配置特点：**
- 支持条件路由：根据条件选择不同的处理路径
- 并行执行：多个组件可同时处理数据
- 动态输入/输出：组件可接收多个输入并产生多个输出
- 可序列化：管道配置可保存为 YAML 文件
Sources: [README.md:1-5]()
### 数据类（Data Classes）
Haystack 使用标准化的数据类来表示文档、响应和元数据。这些数据类确保组件之间的数据传递具有一致性和类型安全性。
**核心数据类：**
| 数据类 | 用途 |
|--------|------|
| Document | 表示文本文档及其元数据 |
| Answer | 表示从文档中提取或生成的答案 |
| Speech | 处理语音相关的输入输出 |
| Trace | 跟踪管道执行过程 |
| ToolMessage | 工具调用结果的消息格式 |
Sources: [README.md:1-5]()
## 文档处理流程
Haystack 支持完整的文档处理流程，从原始文档输入到最终答案输出：
```mermaid
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. **后处理**：格式化输出结果
Sources: [README.md:1-5]()
## 代理系统
Haystack 的代理系统允许构建能够自主决策和执行复杂任务对话式 AI 应用。
**代理核心功能：**
- **工具调用**：代理可以调用多种工具完成特定任务
- **对话记忆**：维护对话历史以支持多轮对话
- **路由决策**：根据上下文选择下一步行动
- **函数调用**：与外部 API 和服务交互
```mermaid
graph TD
A[用户输入] --> B[代理 Agent]
B --> C{决策}
C -->|调用工具| D[工具执行]
D --> E[结果处理]
E --> B
C -->|生成回复| F[最终响应]
E --> F
```
Sources: [README.md:1-5]()
## 版本管理
Haystack 文档支持多版本管理，包括：
| 版本类型 | 说明 |
|----------|------|
| Next (Unreleased) | 未发布的开发版本文档 |
| Current (Stable) | 当前稳定版本文档 |
| Past Versions | 历史版本文档存档 |
开发者可以通过文档网站的版本选择器访问不同版本的文档。Sources: [docs-website/src/pages/versions.js:1-40]()
## 快速入门
安装 Haystack 最简单的方式是通过 pip：
```bash
pip install haystack-ai
```
如需安装预发布版本以体验最新功能：
```bash
pip install --pre haystack-ai
```
Sources: [README.md:1-5]()
## 文档资源
Haystack 提供完整的文档资源支持：
| 资源 | 链接 |
|------|------|
| 官方文档 | https://docs.haystack.deepset.ai |
| 入门指南 | https://haystack.deepset.ai/overview/quick-start |
| 教程 | https://haystack.deepset.ai/tutorials |
| Cookbook | https://haystack.deepset.ai/cookbook |
| API 参考 | 通过文档网站 reference 部分访问 |
Sources: [README.md:1-5]()
## 相关仓库
Haystack 生态系统包括多个相关仓库：
| 仓库 | 用途 |
|------|------|
| haystack-core-integrations | 核心集成组件 |
| haystack-cookbook | 示例代码和最佳实践 |
| haystack-pydoc-tools | API 文档生成工具 |
示例代码已移至 [haystack-cookbook](https://github.com/deepset-ai/haystack-cookbook/) 仓库。Sources: [examples/README.md:1-5]()
## 总结
Haystack 的核心概念围绕组件、管道和数据类三个主要构建块展开。通过这些抽象，开发者可以灵活地构建复杂的 LLM 应用，实现从简单的问答系统到复杂的多代理工作流。框架的模块化设计使得每个组件都可以独立使用或组合使用，满足不同场景的需求。
---
## Pipeline 系统
### Related Pages
Related topics: [核心概念](#core-concepts), [文本嵌入组件](#embedders), [LLM 生成器](#generators)
Relevant source files
The following files were used as context for generating this wiki page:
- [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)
- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
- [docs-website/src/theme/SearchBar.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/SearchBar.js)
- [docs-website/src/theme/NavbarItem/DocNavbarItem/index.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/NavbarItem/DocNavbarItem/index.js)
# Pipeline 系统
## 概述
Haystack 是一个开源的 LLM（大型语言模型）框架，而 Pipeline 系统是其核心架构组件。Pipeline 允许开发者设计灵活的系统，对信息的检索、排名、过滤、组合、结构化和路由过程实现精确控制，确保这些操作在到达模型之前得到妥善管理。
Pipeline 系统支持定义管线和代理工作流，使检索、记忆、工具调用和生成过程透明且可追踪。Sources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)
## 核心特性
### 上下文工程导向
Pipeline 系统专为上下文工程（Context Engineering）而构建，提供了对数据流的显式控制能力。开发者可以精确控制信息从输入到输出的整个生命周期。
### 循环、分支和条件逻辑
Pipeline 支持添加循环（loops）、分支（branches）和条件逻辑（conditional logic），以精确控制上下文如何在 Pipeline 和代理工作流中流动。Sources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)
### 透明性和可追溯性
所有通过 Pipeline 的数据流动都是透明的，开发者可以追踪每个处理步骤，便于调试和优化。
## 架构流程
```mermaid
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 类型
| 类型 | 描述 | 典型用例 |
|------|------|----------|
| 基础 Pipeline | 线性处理流程 | 简单 RAG 流程 |
| 条件 Pipeline | 包含条件分支 | 路由决策 |
| 循环 Pipeline | 支持循环迭代 | 迭代优化 |
| 异步 Pipeline | 异步执行支持 | 高并发场景 |
## 文档资源
Haystack 提供了全面的 Pipeline 相关文档，涵盖以下主题：
| 文档主题 | 路径 |
|----------|------|
| 创建 Pipeline | `docs/concepts/pipelines/creating-pipelines.mdx` |
| 调试 Pipeline | `docs/concepts/pipelines/debugging-pipelines.mdx` |
| 序列化 | `docs/concepts/pipelines/serialization.mdx` |
| 异步 Pipeline | `docs/concepts/pipelines/asyncpipeline.mdx` |
Sources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
## 与其他组件的集成
Pipeline 系统与以下核心组件紧密集成：
- **检索组件（Retrieval）**：处理信息检索和排名
- **工具组件（Tools）**：支持工具调用功能
- **记忆组件（Memory）**：管理对话上下文状态
- **生成组件（Generation）**：处理最终输出生成
## 与 Hayhooks 的集成
如需将 Pipeline 部署为 REST API 或 MCP 服务器，可以使用 [Hayhooks](https://github.com/deepset-ai/hayhooks)。Hayhooks 提供了一种简单的方式将 Pipeline 和代理包装为自定义逻辑，并通过 HTTP 端点或 MCP 协议暴露它们。Sources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)
## 开发环境
文档网站使用 Docusaurus 3 构建，支持实时预览 Pipeline 文档变更。开发环境要求：
- **Node.js**：18 或更高版本
- **包管理器**：npm 或 Yarn
快速启动命令：
```bash
cd haystack/docs-website
npm install
npm start
```
预览地址：`http://localhost:3000`
Sources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
## 版本管理
Pipeline 文档与 Haystack 版本同步发布，通过以下自动化工作流管理：
- `promote_unstable_docs.yml`：在 Haystack 发布期间自动触发
- `minor_version_release.yml`：创建新版本目录并更新版本配置
Sources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
## 相关链接
| 资源 | 地址 |
|------|------|
| 官方文档 | https://docs.haystack.deepset.ai |
| 概念指南 | https://docs.haystack.deepset.ai/docs/concepts |
| 快速开始 | https://haystack.deepset.ai/overview/quick-start |
| GitHub 仓库 | https://github.com/deepset-ai/haystack |
---
## 文档存储系统
### Related Pages
Related topics: [文档转换与预处理](#converters-preprocessors), [排序器与检索器](#rankers-retrievers)
Relevant source files
The following files were used as context for generating this wiki page:
- [docs-website/docs/concepts/document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/document-store.mdx)
- [docs-website/docs/document-stores/inmemorydocumentstore.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/inmemorydocumentstore.mdx)
- [docs-website/docs/document-stores/qdrant-document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/qdrant-document-store.mdx)
- [docs-website/docs/document-stores/weaviatedocumentstore.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/weaviatedocumentstore.mdx)
- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
- [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)
# 文档存储系统
## 概述
Haystack 的文档存储系统（Document Store）是构建检索增强生成（RAG）和其他 NLP 应用的核心基础设施。文档存储系统负责存储、索引和管理文档向量嵌入（Embeddings），为后续的语义搜索和相似性检索提供支持。
在 Haystack 框架中，文档存储系统扮演着数据持久化层的角色，它与检索管道（Retrieval Pipeline）紧密集成，使得大规模文档集合能够被高效查询。Sources: [docs-website/docs/concepts/document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/document-store.mdx)
## 架构设计
### 核心组件关系
```mermaid
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 支持多种文档存储系统实现，每种实现针对不同的使用场景和规模进行了优化。
| 存储类型 | 适用场景 | 特点 | 文档路径 |
|---------|---------|------|---------|
| InMemoryDocumentStore | 开发测试 | 轻量级、易用、无需外部依赖 | docs-website/docs/document-stores/inmemorydocumentstore.mdx |
| QdrantDocumentStore | 生产环境 | 高性能、混合检索、支持过滤 | docs-website/docs/document-stores/qdrant-document-store.mdx |
| WeaviateDocumentStore | 生产环境 | 向量化和检索一体化、语义搜索 | docs-website/docs/document-stores/weaviatedocumentstore.mdx |
Sources: [docs-website/docs/document-stores/inmemorydocumentstore.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/inmemorydocumentstore.mdx), [docs-website/docs/document-stores/qdrant-document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/qdrant-document-store.mdx), [docs-website/docs/document-stores/weaviatedocumentstore.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/weaviatedocumentstore.mdx)
## 文档管理
### 写入操作
文档存储系统支持批量写入文档，这一操作通常与文档转换器配合使用。
```mermaid
graph LR
A[源文档] --> B[DocumentConverter]
B --> C[Document 列表]
C --> D[write_documents]
D --> E[DocumentStore]
E --> F[向量索引]
```
关键写入方法包括：
| 方法 | 参数 | 说明 |
|-----|------|-----|
| write_documents | documents, batch_size | 批量写入文档，支持分批处理 |
| delete_documents | document_ids | 根据 ID 删除文档 |
| delete_all_documents | | 清空所有文档 |
Sources: [docs-website/docs/concepts/document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/document-store.mdx)
### 检索操作
文档存储系统提供多种检索方式，支持不同的查询策略。
| 检索类型 | 说明 | 典型应用 |
|---------|------|---------|
| 相似性检索 | 基于向量余弦相似度或欧氏距离 | 语义搜索、问答系统 |
| 过滤检索 | 支持元数据条件过滤 | 领域特定检索 |
| 混合检索 | 结合关键词和向量检索 | 精确度要求高的场景 |
Sources: [docs-website/docs/document-stores/qdrant-document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/qdrant-document-store.mdx)
## 配置与集成
### 基础配置
文档存储系统在 Haystack Pipeline 中通过组件方式集成。以下是典型的配置模式：
```python
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)
```
### 环境变量
文档存储系统的某些配置可以通过环境变量进行控制，这在不同部署环境中提供了灵活性。
| 环境变量 | 说明 | 适用存储 |
|---------|------|---------|
| DOCS_PRODUCT | 文档产品标识 | 文档网站生成 |
| HAYSTACK_VERSION | Haystack 版本 | Docker 镜像构建 |
Sources: [docker/README.md](https://github.com/deepset-ai/haystack/blob/main/docker/README.md), [docs-website/src/theme/Html.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/Html.js)
## 生产环境部署
### Docker 部署
Haystack 提供预配置的 Docker 镜像，适用于生产环境部署。
| 镜像 | 说明 | 使用场景 |
|-----|------|---------|
| haystack:base-\ | 基础 Python 环境 | 需要自定义依赖的部署 |
镜像构建使用 BuildKit 和 bake 工具：
```bash
docker buildx bake base
```
Sources: [docker/README.md](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)
### 外部向量数据库集成
对于大规模生产环境，建议使用专门的向量数据库：
#### Qdrant 集成
Qdrant 是一个高性能的向量相似性搜索引擎，支持：
- 混合检索能力
- 元数据过滤
- 稀疏和密集向量支持
- 地理空间查询
Sources: [docs-website/docs/document-stores/qdrant-document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/qdrant-document-store.mdx)
#### Weaviate 集成
Weaviate 是另一个企业级向量数据库，特点包括：
- 内置向量化功能
- 原生图结构支持
- 多租户架构
- 实时索引更新
Sources: [docs-website/docs/document-stores/weaviatedocumentstore.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/document-stores/weaviatedocumentstore.mdx)
## 最佳实践
### 开发与生产环境分离
| 环境 | 推荐存储 | 原因 |
|-----|---------|-----|
| 开发/测试 | InMemoryDocumentStore | 快速启动、无额外依赖 |
| 生产 | Qdrant/Weaviate | 高性能、可扩展 |
### 性能优化建议
1. **批量处理**：使用批量写入减少网络开销
2. **索引优化**：根据数据规模选择合适的向量维度
3. **缓存策略**：对频繁查询使用结果缓存
4. **分片策略**：大规模数据考虑分片部署
Sources: [docs-website/docs/concepts/document-store.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/document-store.mdx)
## 文档资源
Haystack 文档网站提供完整的文档存储系统参考资料，访问地址：https://docs.haystack.deepset.ai
Sources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
API 参考文档通过 haystack-pydoc-tools 自动从代码 docstring 生成，确保与代码库同步更新。
Sources: [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)
---
## 文档转换与预处理
### Related Pages
Related topics: [文档存储系统](#document-stores), [文本嵌入组件](#embedders)
Relevant source files
The following files were used as context for generating this wiki page:
- [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
- [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)
- [docker/README.md](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)
- [pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)
- [docs-website/src/theme/SearchBar.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/SearchBar.js)
# 文档转换与预处理
> **注意**: 本页面基于 Haystack 仓库中可用的文档和代码文件编写。由于某些具体实现文件（如 `converters.mdx`、`preprocessors.mdx`、`documentsplitter.mdx`）未包含在当前检索上下文中，部分技术细节基于 Haystack 整体架构和已知功能的推断。
## 概述
Haystack 是一个开源 LLM 框架，用于构建生产级 AI 应用，其核心功能之一是**文档转换与预处理**。这一功能模块负责将各种格式的原始文档转换为可供检索和处理的结构化文档对象。
文档转换与预处理是检索增强生成（RAG）管道中的关键环节，直接影响后续检索质量和生成效果。Haystack 提供了完整的文档处理工具链，涵盖从原始文件到可检索文本的完整转换流程。
Sources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)
## 架构概览
```mermaid
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 支持多种输入格式的转换。
### 支持的转换格式
| 格式类型 | 描述 | 典型用途 |
|---------|------|---------|
| PDF | 便携式文档格式 | 合同、报告、论文 |
| Word (.docx) | Microsoft Word 文档 | 商业文档、合同 |
| HTML | 超文本标记语言 | 网页内容抓取 |
| TXT | 纯文本文件 | 日志、配置文档 |
| Markdown | 轻量级标记语言 | 技术文档、README |
### 转换器组件
文档转换器作为 Pipeline 组件集成到 Haystack 系统中，可以直接连接到索引管道进行处理。
```
Pipeline 结构示例:
DocumentConverter → Preprocessor → DocumentStore
```
Sources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)
## 预处理器 (Preprocessors)
预处理器负责对转换后的文档进行进一步处理，确保数据质量并优化检索性能。
### 核心预处理功能
#### 文档分割 (Document Splitting)
文档分割是将长文档拆分为较小块的常用技术，用于：
- **适配模型上下文窗口**: 大多数 LLM 有 token 数量限制
- **提高检索精度**: 较小的文本块更容易匹配用户查询
- **优化召回率**: 相关内容更容易被准确检索
#### 文本清洗 (Text Cleaning)
文本清洗功能包括：
- 移除多余空白字符
- 标准化标点符号
- 处理特殊字符和编码问题
- 提取或清理元数据
### 预处理工作流
```mermaid
graph LR
A[原始文本] --> B[分句]
B --> C[块划分]
C --> D[重叠处理]
D --> E[元数据附加]
E --> F[最终文档块]
C --> G[大小检查]
G -->|过大| H[递归分割]
H --> D
G -->|合适| D
```
## 文档对象模型
Haystack 使用 `Document` 类作为核心数据结构来表示处理后的文档。
```python
Document(
id: str,
content: str,
meta: Dict[str, Any]
)
```
| 属性 | 类型 | 描述 |
|-----|------|------|
| `id` | str | 文档唯一标识符 |
| `content` | str | 文档文本内容 |
| `meta` | Dict | 元数据字典，可包含来源、页码、标题等信息 |
## 与管道组件的集成
### 索引管道中的位置
```mermaid
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
```
文档转换与预处理组件位于索引管道的前端，确保进入系统的文档具有良好的质量和格式。
Sources: [docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
## 配置与使用
### 基础配置项
| 参数 | 类型 | 默认值 | 说明 |
|-----|------|-------|------|
| `split_by` | str | "word" | 分割单位：word、sentence、passage |
| `split_length` | int | 100 | 每个块的单位数量 |
| `split_overlap` | int | 0 | 块之间的重叠数量 |
| `split_threshold` | int | 0 | 触发分割的最小阈值 |
### 最佳实践
1. **块大小选择**: 根据使用的 embedding 模型和 LLM 上下文窗口大小来调整
2. **重叠设置**: 对于需要跨块理解的内容，适当设置重叠可以提高召回质量
3. **元数据保留**: 在转换过程中保留重要的元数据信息，便于后续筛选和溯源
4. **质量验证**: 在生产环境中添加转换质量检查步骤
## 与其他组件的关系
文档转换与预处理模块与 Haystack 的其他核心组件紧密协作：
| 组件类型 | 关系描述 |
|---------|---------|
| **DocumentStore** | 存储处理后的文档，提供持久化支持 |
| **Retriever** | 基于处理后的文档进行语义检索 |
| **Generator** | 使用检索结果进行答案生成 |
| **Embedder** | 将文本块转换为向量表示 |
Sources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)
## 安装与依赖
文档转换与预处理功能已包含在主包中：
```bash
pip install haystack-ai
```
对于特定的转换器，可能需要额外的依赖：
```bash
# PDF 转换
pip install haystack-ai[pdf]
# Word 文档转换
pip install haystack-ai[docx]
```
Sources: [README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)
## 相关资源
- [官方文档](https://docs.haystack.deepset.ai/)
- [Haystack GitHub 仓库](https://github.com/deepset-ai/haystack)
- [API 参考文档](https://docs.haystack.deepset.ai/reference/)
## 版本说明
文档转换与预处理的 API 和行为在不同版本间可能存在差异。建议始终使用与 Haystack 主版本匹配的文档版本。
Sources: [docs-website/src/pages/versions.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/pages/versions.js)
---
## 文本嵌入组件
### Related Pages
Related topics: [LLM 生成器](#generators), [排序器与检索器](#rankers-retrievers)
Relevant source files
The following files were used as context for generating this wiki page:
- [docs-website/docs/pipeline-components/embedders.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders.mdx)
- [docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx)
- [docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx)
# 文本嵌入组件
## 概述
文本嵌入组件（Text Embedders）是 Haystack 框架中用于将文本转换为高维向量表示的核心组件。在检索增强生成（RAG）系统中，嵌入组件负责将文档和查询文本编码为语义向量，使得基于向量相似度的语义检索成为可能。
Haystack 提供了多种文本嵌入组件，支持主流的 embedding 服务提供商，包括 OpenAI、HuggingFace API 等。这些组件可以作为流水线（Pipeline）的一部分，在文档索引阶段将文档内容向量化，在查询阶段将用户查询向量化。
## 核心架构
### 组件分类
Haystack 的文本嵌入组件主要分为两大类：
| 组件类型 | 用途 | 典型场景 |
|---------|------|---------|
| **Text Embedder** | 单文本嵌入 | 处理用户查询 |
| **Document Embedder** | 文档集合嵌入 | 批量索引文档 |
Sources: [docs-website/docs/pipeline-components/embedders.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders.mdx)
### 数据流架构
```mermaid
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` 模型）。
Sources: [docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx)
### 初始化参数
| 参数名 | 类型 | 必需 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `api_key` | `str` | 是 | - | OpenAI API 密钥 |
| `model` | `str` | 否 | `"text-embedding-3-small"` | 使用的 embedding 模型 |
| `api_base_url` | `str` | 否 | OpenAI 默认地址 | API 端点地址 |
| `dimensions` | `int` | 否 | - | 输出向量维度（仅支持 3 系列模型）|
| `timeout` | `float` | 否 | `60.0` | 请求超时时间（秒）|
| `max_retries` | `int` | 否 | `5` | 最大重试次数 |
### 使用示例
```python
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` 参数控制输出向量维度，这使得用户可以在保持语义表达能力的同时减少存储空间和计算成本。
Sources: [docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/openaitextembedder.mdx)
## HuggingFace API 文本嵌入组件
### 组件简介
`HuggingFaceAPITextEmbedder` 提供了对 HuggingFace Inference API 的集成支持。该组件允许用户使用 HuggingFace Hub 上托管的各种 embedding 模型，无需本地部署。
Sources: [docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx)
### 初始化参数
| 参数名 | 类型 | 必需 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `api_key` | `str` | 是 | - | HuggingFace API 密钥 |
| `model` | `str` | 是 | - | HuggingFace 模型 ID |
| `token` | `str` | 否 | `None` | HuggingFace 访问令牌 |
| `use_gpu` | `bool` | 否 | `True` | 是否使用 GPU（如果可用）|
| `batch_size` | `int` | 否 | `32` | 批处理大小 |
| `timeout` | `int` | 否 | `60` | 请求超时时间（秒）|
| `truncate` | `bool` | 否 | `True` | 是否截断超长文本 |
### 使用示例
```python
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 的模型，常见选择包括：
| 模型 ID | 向量维度 | 说明 |
|---------|---------|------|
| `sentence-transformers/all-MiniLM-L6-v2` | 384 | 高效轻量模型 |
| `sentence-transformers/all-mpnet-base-v2` | 768 | 高精度模型 |
| `BAAI/bge-small-en-v1.5` | 512 | BGE 英文模型 |
Sources: [docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx)
## 在流水线中使用嵌入组件
### RAG 流水线架构
```mermaid
graph LR
A[用户查询] --> B[TextEmbedder]
B --> C[向量检索器]
D[文档库] --> E[DocumentEmbedder]
E --> F[向量数据库]
C --> G[上下文组装]
G --> H[LLM 生成]
H --> I[最终回答]
```
### 完整流水线示例
```python
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")
```
Sources: [docs-website/docs/pipeline-components/embedders.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders.mdx)
## 输出格式
### 标准输出结构
所有文本嵌入组件的 `run()` 方法返回统一格式的字典：
| 输出键 | 类型 | 说明 |
|--------|------|------|
| `embedding` | `List[float]` | 文本的向量表示 |
| `meta` | `Dict` | 元数据信息（如使用的模型）|
```python
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. 批处理优化
对于大量文档的索引任务，使用支持批处理的嵌入组件可以显著提升性能：
```python
from haystack.components.embedders import HuggingFaceAPITextEmbedder
embedder = HuggingFaceAPITextEmbedder(
model="sentence-transformers/all-MiniLM-L6-v2",
batch_size=64 # 根据 API 限制调整
)
```
### 3. 错误处理
建议在实际应用中实现重试机制和降级策略：
```python
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)
```
## 相关组件
| 组件类型 | 说明 |
|---------|------|
| `OpenAIDocumentEmbedder` | OpenAI 文档批量嵌入 |
| `HuggingFaceAPIDocumentEmbedder` | HuggingFace 文档批量嵌入 |
| `SentenceTransformersTextEmbedder` | 本地 SentenceTransformers 模型 |
Sources: [docs-website/docs/pipeline-components/embedders.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/embedders.mdx)
## 扩展阅读
- [Haystack 官方文档](https://docs.haystack.deepset.ai/docs/embedders)
- [RAG 流水线教程](https://haystack.deepset.ai/cookbook)
- [HuggingFace Embedding 模型列表](https://huggingface.co/models?pipeline_tag=feature-extraction)
---
## LLM 生成器
### Related Pages
Related topics: [文本嵌入组件](#embedders), [Agent 代理系统](#agents)
Relevant source files
The following files were used as context for generating this wiki page:
- [haystack/docs-website/README.md](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
- [haystack/README.md](https://github.com/deepset-ai/haystack/blob/main/README.md)
- [haystack/docs-website/docs/pipeline-components/generators.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators.mdx)
- [haystack/docs-website/docs/pipeline-components/generators/openaichatgenerator.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators/openaichatgenerator.mdx)
- [haystack/docs-website/docs/pipeline-components/generators/anthropicchatgenerator.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators/anthropicchatgenerator.mdx)
- [haystack/pydoc/README.md](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)
# LLM 生成器
## 概述
LLM 生成器（LLM Generator）是 Haystack 框架中的核心组件之一，专门用于与大型语言模型（Large Language Models）进行交互。在 Haystack 2.x 架构中，生成器作为管道（Pipeline）的关键组件，负责接收输入提示（Prompt）并生成自然语言响应。
Sources: [README.md:1-10](https://github.com/deepset-ai/haystack/blob/main/README.md)
Haystack 是一个端到端的 LLM 框架，允许你构建由 LLMs、Transformer 模型、向量搜索等驱动的应用程序。无论是执行检索增强生成（RAG）、文档搜索、问答还是答案生成，Haystack 都可以将先进的嵌入模型和 LLMs 编排成管道，以构建端到端的 NLP 应用程序。
Sources: [docker/README.md:1-8](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)
---
## 架构与定位
### 在管道中的角色
在 Haystack 的整体架构中，LLM 生成器属于**管道组件（Pipeline Components）** 类别。Haystack 提供了多种管道组件，包括：
| 组件类别 | 说明 |
|---------|------|
| 生成器（Generators） | 与 LLMs 交互，生成文本响应 |
| 检索器（Retrievers） | 从向量数据库检索相关文档 |
| 提示器（Prompters） | 构建和优化提示词 |
| 工具（Tools） | 扩展 LLM 能力 |
Sources: [docs-website/README.md:50-60](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
### 设计理念
Haystack 的生成器组件**专为上下文工程设计**，允许开发者灵活控制系统如何检索、排名、过滤、组合、结构化和路由信息，直到信息到达模型。
Sources: [README.md:40-45](https://github.com/deepset-ai/haystack/blob/main/README.md)
---
## 主要生成器实现
### OpenAI Chat Generator
`OpenAIChatGenerator` 是 Haystack 官方提供的与 OpenAI GPT 系列模型交互的组件。该生成器支持 OpenAI 的 Chat API，能够利用最新的 GPT-4 和 GPT-3.5-Turbo 模型。
#### 核心特性
- **流式响应支持**：支持实时流式输出，提升用户体验
- **函数调用**：支持 OpenAI 的 function calling 功能
- **多轮对话**：支持维护对话历史上下文
- **温度控制**：可调节生成文本的随机性
Sources: [docs-website/docs/pipeline-components/generators/openaichatgenerator.mdx:1-20](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators/openaichatgenerator.mdx)
### Anthropic Chat Generator
`AnthropicChatGenerator` 是与 Anthropic 公司 Claude 系列模型交互的专用生成器。Claude 模型以安全性高、输出可靠著称，特别适合需要严格遵循指令的应用场景。
#### 核心特性
- **长上下文窗口**：支持高达 200K tokens 的上下文
- **Instruction Following**：优秀的指令遵循能力
- **安全过滤**：内置内容安全过滤机制
Sources: [docs-website/docs/pipeline-components/generators/anthropicchatgenerator.mdx:1-15](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators/anthropicchatgenerator.mdx)
---
## 生成器配置参数
### 通用配置
大多数 LLM 生成器共享以下核心配置参数：
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `api_key` | str | API 密钥 | 环境变量 |
| `model` | str | 模型名称 | 必填 |
| `temperature` | float | 采样温度 (0-2) | 0.7 |
| `max_tokens` | int | 最大生成 token 数 | 512 |
| `streaming_callback` | Callable | 流式回调函数 | None |
Sources: [docs-website/docs/pipeline-components/generators.mdx:30-50](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/generators.mdx)
### API 参考文档
Haystack 使用 [haystack-pydoc-tools](https://github.com/deepset-ai/haystack-pydoc-tools) 从代码的文档字符串自动生成 API 参考文档。所有 API 参考更新首先应用于不稳定文档版本，然后在发布新版本时提升到稳定版本。
Sources: [pydoc/README.md:1-15](https://github.com/deepset-ai/haystack/blob/main/pydoc/README.md)
---
## 工作流程
### 基本使用流程
```mermaid
graph TD
A[构建提示词 Prompt] --> B[发送到 LLM API]
B --> C{选择生成器}
C -->|OpenAI| D[OpenAIChatGenerator]
C -->|Anthropic| E[AnthropicChatGenerator]
C -->|其他| F[自定义生成器]
D --> G[接收响应]
E --> G
F --> G
G --> H[后处理响应]
H --> I[输出结果]
```
### 集成到管道
```mermaid
graph LR
A[用户查询] --> B[检索器 Retriever]
B --> C[检索相关文档]
C --> D[提示构建器 PromptBuilder]
D --> E[LLM 生成器]
E --> F[最终响应]
```
---
## 第三方集成
### 贡献指南
Haystack 欢迎社区贡献集成组件。除了核心项目外，集成组件可以在 [haystack-core-integrations](https://github.com/deepset-ai/haystack-core-integrations) 仓库中贡献。
Sources: [README.md:100-110](https://github.com/deepset-ai/haystack/blob/main/README.md)
### 贡献方式
社区可以通过以下方式贡献：
1. **核心集成**：在 [haystack-core-integrations](https://github.com/deepset-ai/haystack-core-integrations) 贡献新的生成器实现
2. **文档完善**：在 [haystack/docs-website](https://github.com/deepset-ai/haystack/tree/main/docs-website) 改进文档
3. **问题修复**：修复 bug 或改进现有功能
> 💡 **提示**：查看 [开放贡献的问题列表](https://github.com/orgs/deepset-ai/projects/14) 找到适合入门的任务
Sources: [README.md:105-115](https://github.com/deepset-ai/haystack/blob/main/README.md)
---
## 安装与配置
### 安装方式
#### 通过 pip 安装（推荐）
```bash
pip install haystack-ai
```
Sources: [README.md:20-25](https://github.com/deepset-ai/haystack/blob/main/README.md)
#### 安装预发布版本
```bash
pip install --pre haystack-ai
```
#### Docker 环境
对于 Docker 环境，Haystack 提供了预装的基础镜像：
```bash
docker pull deepset/haystack:base-
```
Sources: [docker/README.md:10-20](https://github.com/deepset-ai/haystack/blob/main/docker/README.md)
---
## 文档资源
### 官方文档
| 资源 | 链接 |
|------|------|
| 官方文档站点 | [docs.haystack.deepset.ai](https://docs.haystack.deepset.ai) |
| 入门指南 | [快速开始](https://haystack.deepset.ai/overview/quick-start) |
| 教程 | [教程列表](https://haystack.deepset.ai/tutorials) |
| Cookbook | [Haystack 食谱](https://haystack.deepset.ai/cookbook) |
Sources: [README.md:30-40](https://github.com/deepset-ai/haystack/blob/main/README.md)
### 文档构建
文档网站基于 Docusaurus 3 构建，使用以下命令启动本地开发服务器：
```bash
cd haystack/docs-website
npm install
npm start
# 访问 http://localhost:3000
```
Sources: [docs-website/README.md:10-20](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
---
## 版本与兼容性
### 版本管理
Haystack 的文档版本与代码版本保持同步发布。当有新版本发布时，GitHub Actions 工作流会自动：
1. 创建新的版本目录
2. 更新版本配置文件
3. 生成版本化的 API 参考文档
Sources: [docs-website/README.md:70-85](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
### llms.txt 文件
文档站点为 AI 工具提供了一个 `llms.txt` 文件，由 `docusaurus-plugin-generate-llms-txt` 插件自动生成。该文件将所有文档内容连接成一个文本文件，便于 LLM 和其他工具消费。
Sources: [docs-website/README.md:95-110](https://github.com/deepset-ai/haystack/blob/main/docs-website/README.md)
---
## 最佳实践
### 1. 选择合适的模型
根据应用场景选择生成器：
- **需要高准确性**：选择 GPT-4 或 Claude 系列
- **需要低成本**：选择 GPT-3.5-Turbo 或开源模型
- **需要长上下文**：选择 Claude 200K 或 GPT-4-Turbo
### 2. 提示工程
充分利用 Haystack 的上下文工程能力：
- 使用合适的 PromptBuilder 构建提示
- 结合检索器提供相关上下文
- 调整 temperature 控制输出稳定性
### 3. 错误处理
实现健壮的错误处理机制：
```python
try:
response = generator.run(prompt=my_prompt)
except APIError as e:
logger.error(f"API Error: {e}")
# 实现重试逻辑
except TimeoutError as e:
logger.error(f"Request timeout: {e}")
# 实现超时处理
```
---
## 扩展阅读
- [Haystack 官方文档](https://docs.haystack.deepset.ai)
- [Haystack GitHub 仓库](https://github.com/deepset-ai/haystack)
- [Haystack Cookbooks](https://haystack.deepset.ai/cookbook)
- [haystack-core-integrations](https://github.com/deepset-ai/haystack-core-integrations)
---
## 排序器与检索器
### Related Pages
Related topics: [文档存储系统](#document-stores), [文本嵌入组件](#embedders)
Relevant source files
The following files were used as context for generating this wiki page:
- [docs-website/docs/pipeline-components/retrievers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers.mdx)
- [docs-website/docs/pipeline-components/rankers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/rankers.mdx)
- [docs-website/docs/pipeline-components/retrievers/textembeddingretriever.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers/textembeddingretriever.mdx)
# 排序器与检索器
## 概述
在 Haystack 框架中，**检索器（Retriever）** 和 **排序器（Ranker）** 是构建 RAG（检索增强生成）管道的核心组件。它们共同负责从大规模文档集合中找到最相关的信息，为大语言模型提供准确的上下文。
### 核心功能定位
| 组件类型 | 主要职责 | 输入 | 输出 |
|---------|---------|------|------|
| 检索器 (Retriever) | 从文档存储中快速召回候选文档 | 查询文本 | 候选文档列表 |
| 排序器 (Ranker) | 对检索结果进行精细化排序 | 检索结果 + 查询 | 排序后的文档列表 |
Sources: [docs-website/docs/pipeline-components/retrievers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers.mdx)
---
## 检索器（Retriever）
### 工作原理
检索器负责在大规模文档集合中快速定位相关信息。其核心目标是**高召回率（High Recall）**，即尽可能不遗漏相关文档。
```mermaid
graph LR
A[用户查询] --> B[Retriever]
B --> C[文档存储]
C --> D[候选文档集合]
D --> E[Top-K 文档]
style A fill:#e1f5fe
style E fill:#c8e6c9
```
### 主要类型
Haystack 支持多种检索器实现：
| 检索器类型 | 描述 | 适用场景 |
|-----------|------|---------|
| **EmbeddingRetriever** | 基于向量嵌入的语义检索 | 需要语义理解的场景 |
| **BM25Retriever** | 基于词频的稀疏检索 | 关键词匹配为主的场景 |
| **DensePassageRetriever** | 基于稠密段落嵌入 | 问答系统 |
| **TfidfRetriever** | 基于 TF-IDF 算法 | 轻量级快速检索 |
Sources: [docs-website/docs/pipeline-components/retrievers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers.mdx)
### TextEmbeddingRetriever 详解
`TextEmbeddingRetriever` 是最常用的检索器类型之一，它利用文本嵌入模型将查询和文档转换为向量表示，通过计算向量相似度来检索相关文档。
#### 核心参数配置
```python
retriever = TextEmbeddingRetriever(
embedding_backend=None, # 嵌入模型后端
model_name_or_path="sentence-transformers/all-MiniLM-L6-v2",
api_key=None, # API 密钥（如使用云服务）
top_k=10 # 返回的文档数量
)
```
#### 工作流程
```mermaid
graph TD
A[查询文本] --> B[Embedding Model]
C[文档库] --> D[Document Store]
D --> E[预计算文档向量]
B --> F[查询向量]
F --> G[向量相似度计算]
E --> G
G --> H[Top-K 文档]
style A fill:#e1f5fe
style H fill:#c8e6c9
```
Sources: [docs-website/docs/pipeline-components/retrievers/textembeddingretriever.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers/textembeddingretriever.mdx)
---
## 排序器（Ranker）
### 工作原理
排序器接收检索器的候选结果，对文档与查询的相关性进行精细化评估和重新排序。其核心目标是**高精确率（High Precision）**，确保最相关的文档排在最前面。
```mermaid
graph LR
A[查询] --> B[Retriever]
C[文档库] --> B
B --> D[候选文档]
D --> E[Ranker]
E --> F[精排后文档]
style D fill:#fff3e0
style F fill:#c8e6c9
```
### 主要类型
| 排序器类型 | 描述 | 特点 |
|-----------|------|------|
| **CohereRanker** | 使用 Cohere API 进行排序 | 云端服务，高精度 |
| **OpenAIRanker** | 使用 OpenAI 模型排序 | 基于 GPT 技术 |
| **SentenceTransformersRanker** | 使用本地 SentenceTransformer 模型 | 可本地部署 |
| **TransformersRanker** | 基于 Transformer 的排序模型 | 支持多种预训练模型 |
Sources: [docs-website/docs/pipeline-components/rankers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/rankers.mdx)
### 排序器参数
```python
ranker = SentenceTransformersRanker(
model_name_or_path="cross-encoder/ms-marco-MiniLM-L-12-v2",
top_k=5, # 最终返回的文档数量
device="cpu" # 运行设备
)
```
---
## 协同工作流程
检索器和排序器通常在管道中串联使用，形成 **召回-排序（Recall-Rerank）** 范式：
```mermaid
graph TD
A[用户查询] --> B[Retriever]
B --> C[初步候选文档
Top-K: 20-100]
C --> D[Ranker]
D --> E[精排文档
Top-K: 3-10]
E --> F[LLM 生成答案]
subgraph 召回阶段
B
end
subgraph 排序阶段
D
end
style A fill:#e1f5fe
style F fill:#c8e6c9
```
### 典型配置模式
| 阶段 | 组件 | Top-K 设置 | 说明 |
|------|------|-----------|------|
| 召回 | TextEmbeddingRetriever | 20-50 | 宽召回，确保不遗漏 |
| 精排 | SentenceTransformersRanker | 3-5 | 精筛，提供高质量上下文 |
Sources: [docs-website/docs/pipeline-components/retrievers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers.mdx)
Sources: [docs-website/docs/pipeline-components/rankers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/rankers.mdx)
---
## 在 Pipeline 中使用
### 完整示例
```python
from haystack import Pipeline
from haystack.components.retrievers import TextEmbeddingRetriever
from haystack.components.rankers import SentenceTransformersRanker
from haystack.document_stores import InMemoryDocumentStore
# 初始化组件
document_store = InMemoryDocumentStore()
retriever = TextEmbeddingRetriever(top_k=20)
ranker = SentenceTransformersRanker(top_k=5)
# 构建管道
pipeline = Pipeline()
pipeline.add_component("retriever", retriever)
pipeline.add_component("ranker", ranker)
# 连接组件
pipeline.connect("retriever.documents", "ranker.documents")
```
### 数据流
```mermaid
sequenceDiagram
participant Query as 查询
participant Retriever as 检索器
participant Ranker as 排序器
participant LLM as 大语言模型
Query->>Retriever: 发送查询
Retriever->>Ranker: 返回 Top-20 候选文档
Ranker->>LLM: 返回 Top-5 精排文档
LLM->>Query: 生成答案
```
---
## 性能优化建议
### 1. 检索器优化
- **调整 Top-K 值**：根据文档库规模和召回需求设置合适的候选数量
- **选择合适的嵌入模型**：在精度和速度之间权衡
- **文档分段策略**：合理的分段大小可提升检索效果
### 2. 排序器优化
- **模型选择**：根据精度需求选择合适的排序模型
- **Top-K 级联**：检索器的 K 值应大于排序器的 K 值（通常 4-10 倍）
- **批处理**：批量处理可提升排序效率
### 3. 整体策略
| 场景 | 检索器 Top-K | 排序器 Top-K | 预期效果 |
|------|-------------|-------------|---------|
| 简单问答 | 10-20 | 3-5 | 快速响应 |
| 复杂分析 | 50-100 | 5-10 | 高精度 |
| 大规模检索 | 100-200 | 10-20 | 全面覆盖 |
Sources: [docs-website/docs/pipeline-components/retrievers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/retrievers.mdx)
Sources: [docs-website/docs/pipeline-components/rankers.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/rankers.mdx)
---
## 最佳实践
1. **先检索后排序**：不要跳过检索阶段直接使用排序器，这会导致性能问题
2. **模型匹配**：尽量使用与检索器 Embedding 模型兼容的排序器
3. **监控指标**：关注召回率和精确率，根据业务需求调整参数
4. **文档预处理**：确保文档格式统一，预处理充分
---
## Agent 代理系统
### Related Pages
Related topics: [LLM 生成器](#generators)
Relevant source files
The following files were used as context for generating this wiki page:
- [docs-website/docs/concepts/agents.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/agents.mdx)
- [docs-website/docs/pipeline-components/agents-1/agent.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/agent.mdx)
- [docs-website/docs/pipeline-components/agents-1/state.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/state.mdx)
- [docs-website/src/theme/SearchBar.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/SearchBar.js)
- [docs-website/src/theme/NavbarItem/DocNavbarItem/index.js](https://github.com/deepset-ai/haystack/blob/main/docs-website/src/theme/NavbarItem/DocNavbarItem/index.js)
# Agent 代理系统
## 概述
Haystack Agent 是框架中用于构建智能代理系统的核心组件，它使大型语言模型（LLM）能够通过工具调用、状态管理和多步骤推理来解决复杂任务。Agent 系统将 LLM 与外部工具、数据源和检索系统相结合，实现了自主决策和执行能力。
Sources: [docs-website/docs/concepts/agents.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/agents.mdx)
## 架构设计
### 核心组件
Agent 系统由多个核心组件构成，每个组件负责特定的功能职责：
| 组件 | 职责 | 关键特性 |
|------|------|----------|
| Agent | 主控制器 | 管理对话循环、决策制定、工具调用 |
| Tool | 工具接口 | 封装外部功能、参数验证、结果处理 |
| State | 状态管理 | 维护对话历史、跟踪执行上下文 |
| Pipeline | 流程编排 | 串联多个组件、定义执行顺序 |
Sources: [docs-website/docs/pipeline-components/agents-1/agent.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/agent.mdx)
### 组件交互流程
```mermaid
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 工具**：调用外部服务、获取实时数据
- **计算工具**：执行数据处理、格式转换
- **自定义工具**：用户定义的任意功能
Sources: [docs-website/docs/pipeline-components/agents-1/agent.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/agent.mdx:1-50)
### 决策循环
Agent 实现了自主决策循环，典型执行流程如下：
```mermaid
graph LR
A[接收任务] --> B[LLM 推理]
B --> C{需要工具?}
C -->|是| D[选择工具]
D --> E[执行工具]
E --> F[返回结果]
F --> B
C -->|否| G[生成回复]
G --> H[返回用户]
```
## 状态管理系统
### State 组件
State 是 Agent 系统中负责维护执行状态的关键组件，它记录：
- 对话历史记录
- 工具调用记录
- 中间执行结果
- 上下文变量
Sources: [docs-website/docs/pipeline-components/agents-1/state.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/state.mdx)
### 状态数据结构
State 组件使用结构化数据模型来跟踪代理执行过程：
```python
class AgentState:
messages: List[Dict] # 对话历史
tool_calls: List[Dict] # 工具调用记录
intermediate_steps: List # 中间步骤
context: Dict # 上下文变量
```
### 状态流转图
```mermaid
graph TD
A[初始状态] --> B[消息添加]
B --> C{执行工具?}
C -->|是| D[记录工具调用]
D --> E[保存中间结果]
E --> F[状态更新]
F --> B
C -->|否| G[标记完成]
G --> H[最终状态]
F --> H
```
## 使用示例
### 基本 Agent 配置
```python
from haystack import Agent
agent = Agent(
tools=[retriever, calculator, web_searcher],
prompt_template="你是一个有帮助的助手"
)
```
### 状态初始化
```python
from haystack.agents import AgentState
initial_state = AgentState(
messages=[],
tool_calls=[],
context={}
)
```
Sources: [docs-website/docs/pipeline-components/agents-1/state.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/state.mdx:1-30)
## 与 Pipeline 集成
Agent 可以作为 Pipeline 的组件进行编排，实现复杂的业务流程：
```mermaid
graph LR
A[用户查询] --> B[检索 Pipeline]
B --> C[Agent 处理]
C --> D{需要更多数据?}
D -->|是| E[调用工具]
E --> B
D -->|否| F[生成回答]
F --> G[返回结果]
```
### Pipeline 中的 Agent 配置
| 参数 | 类型 | 说明 |
|------|------|------|
| name | str | Agent 实例名称 |
| tools | List[Tool] | 可用工具列表 |
| prompt_template | str | 提示词模板 |
| max_iterations | int | 最大迭代次数 |
Sources: [docs-website/docs/concepts/agents.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/concepts/agents.mdx:1-50)
## 最佳实践
### 工具设计原则
1. **单一职责**：每个工具只完成一个明确的任务
2. **清晰的输入输出**：定义明确的参数和返回值
3. **错误处理**：为工具添加适当的异常处理机制
4. **文档完善**：提供清晰的使用说明和示例
### 状态管理建议
1. **定期清理**：避免状态数据无限增长
2. **关键节点保存**：在重要步骤记录检查点
3. **上下文优化**：仅保留必要的上下文信息
## 配置选项
### 核心参数表
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `tools` | [] | 关联的工具列表 |
| `max_steps` | 10 | 最大执行步数 |
| `tool_call_limit` | 50 | 工具调用上限 |
| `streaming` | true | 是否启用流式输出 |
Sources: [docs-website/docs/pipeline-components/agents-1/agent.mdx](https://github.com/deepset-ai/haystack/blob/main/docs-website/docs/pipeline-components/agents-1/agent.mdx:50-80)
## 相关资源
- [Agent 概念文档](./concepts/agents.mdx)
- [Agent API 参考](./pipeline-components/agents-1/agent.mdx)
- [State 组件参考](./pipeline-components/agents-1/state.mdx)
- [Haystack 官方文档](https://docs.haystack.deepset.ai)
---
---
## Doramagic 踩坑日志
项目：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