haystack

Haystack 专家技能

Haystack（由 deepset 推出）是一个面向生产环境的框架，用于构建搜索和 NLP 流水线。其核心抽象是 Pipeline——由带类型的组件构成、具有显式连接的有向无环图。与 LangChain 的 LCEL（管道运算符）或 LlamaIndex 的查询引擎不同，Haystack 流水线会通过 add_component 和 connect 预先声明，因此 DAG 可经过验证，也便于调试。

核心范式

from haystack import Pipeline
from haystack.components.embedders import SentenceTransformersTextEmbedder
from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
from haystack.components.builders import PromptBuilder
from haystack.components.generators import OpenAIGenerator
from haystack.document_stores.in_memory import InMemoryDocumentStore

# Build a pipeline
document_store = InMemoryDocumentStore()
pipeline = Pipeline()
pipeline.add_component("embedder", SentenceTransformersTextEmbedder())
pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
pipeline.add_component("prompt_builder", PromptBuilder(template="Answer using: {{documents}}\n\nQuestion: {{question}}"))
pipeline.add_component("generator", OpenAIGenerator())

# Connect components
pipeline.connect("embedder.embedding", "retriever.query_embedding")
pipeline.connect("retriever.documents", "prompt_builder.documents")
pipeline.connect("prompt_builder", "generator")

# Run
result = pipeline.run({"embedder": {"text": "What is Haystack?"}, "prompt_builder": {"question": "What is Haystack?"}})

核心原则

1. 流水线是经过验证的 DAG。 使用 add_component + connect。流水线验证会在执行前捕获错误——开发时应充分利用这一点。
2. 组件带有类型。 每个组件都有输入／输出槽位。连接必须匹配类型，从而避免运行时错误。
3. PromptBuilder 使用 Jinja2。 模板是 Jinja2 字符串，而不是 f-string。{{documents}}、{{query}}、{{question}} 是变量占位符。
4. 索引和查询是独立的流水线。 一条流水线负责加载／清理／嵌入／写入文档。另一条负责检索／生成答案。它们共享 DocumentStore。
5. 评估也可以使用流水线。 添加评估器组件，以衡量忠实度、相关性或自定义指标。

从哪里开始

你已有……	从这里开始
什么都没有——正在了解 Haystack	构建一个基础的索引 + 查询流水线
要编入索引的文档	构建索引流水线（转换器、分块器、嵌入器、写入器）
搜索用例	构建查询流水线（嵌入器、检索器、提示词、生成器）
生产部署	添加 Hayhooks + 评估流水线

快速参考

任务	方法	参考
构建索引流水线	add_component -> connect -> run	references/pipeline-design.md
构建查询流水线	retriever -> prompt_builder -> generator	references/pipeline-design.md
选择文档存储	InMemory（开发）、Elasticsearch/Pinecone（生产）	references/document-stores.md
嵌入检索	SentenceTransformersTextEmbedder + EmbeddingRetriever	references/retrievers.md
混合检索	并行使用 BM25 + Embedding、DocumentJoiner	references/retrievers.md
提示词模板	在 PromptBuilder 中使用 Jinja2	references/pipeline-design.md
评估	DeepEvalEvaluator、SASEvaluator	references/evaluation.md
部署	Hayhooks REST API	references/deployment.md

框架选择指南

场景	推荐使用	原因
搜索／NLP 流水线	Haystack	Pipeline DAG 模型最成熟，适合以检索为主的工作负载
文档查询／RAG	LlamaIndex	数据摄取是其首要构建模块
链／Agent 组合	LangChain	LCEL 管道运算符适用于通用链构建
编译式提示词程序	DSPy	会针对指标自动优化提示词
基于角色的多 Agent	CrewAI	更高层次的 Agent 抽象

参考文件

参考	适用场景	文件
流水线设计	构建索引和查询流水线时	references/pipeline-design.md
文档存储	选择和配置存储时	references/document-stores.md
检索器	嵌入、BM25、混合检索时	references/retrievers.md
验证审查	研究验证所有 API 声明时	references/validation-audit.md
文件转换器	多格式索引、YAML 序列化、组件类型	references/file-converters.md
评估	指标、评估器、流水线评估	references/evaluation.md
部署	Hayhooks、容器化、生产环境	references/deployment.md
常见问题与故障排除	常见错误及修复方法	references/faq-and-troubleshooting.md

模板

模板	使用场景	文件
索引流水线	加载、拆分、嵌入并写入存储	templates/indexing-pipeline.py
查询流水线	检索、提示并生成答案	templates/query-pipeline.py
混合 RAG	并行执行 BM25 和嵌入	templates/hybrid-rag.py

故障排除

症状	可能原因	解决方法	参考
流水线运行出错	组件连接不匹配	检查组件输入／输出插槽类型	references/pipeline-design.md
未检索到文档	文档存储为空	先运行索引流水线	references/pipeline-design.md
提示词未渲染	Jinja2 模板中的变量名称错误	检查 {{variables}} 是否与流水线输入匹配	references/pipeline-design.md
检索速度慢	使用了全量扫描，而非 ANN	配置近似最近邻索引	references/retrievers.md
嵌入不匹配	索引和查询使用了不同的模型	在两个流水线中使用相同的模型	references/retrievers.md
Hayhooks 未启动	端口冲突或缺少配置	检查端口，运行 --help 查看选项	references/deployment.md