Haystack AI 框架

在 Clore.ai 上部署 deepset 的 Haystack——在经济实惠的 GPU 基础设施上构建生产级 RAG 流水线、语义搜索和 LLM 智能体工作流。

Haystack 是 deepset 的开源 AI 编排框架，用于构建生产级 LLM 应用。凭借 1.8 万以上的 GitHub 星标，它提供了一个灵活的 基于流水线的架构 它将文档存储、检索器、阅读器、生成器和代理连接在一起——全部使用简洁、可组合的 Python。无论你需要针对私有文档的 RAG、语义搜索，还是多步骤代理工作流，Haystack 都会处理底层基础设施，让你专注于应用逻辑。

在 Clore.ai 上，当你需要通过 Hugging Face Transformers 或 sentence-transformers 进行本地模型推理时，Haystack 尤其出色。如果你完全依赖外部 API（OpenAI、Anthropic），它可以在仅 CPU 的实例上运行——但对于嵌入生成和本地 LLM，GPU 能显著降低延迟。

所有示例都运行在通过以下方式租用的 GPU 服务器上： CLORE.AI 市场.

本指南涵盖 Haystack v2.x (haystack-ai 包）。v2 API 与 v1（farm-haystack）有很大不同。如果你已有现成的 v1 流水线，请参阅 迁移指南.

概览

属性	详情
项目	deepset-ai/haystack
许可证	Apache 2.0
GitHub Stars	1.8 万以上
版本	v2.x（haystack-ai)
主要用途	RAG、语义搜索、文档问答、代理工作流
GPU 支持	可选——本地嵌入 / 本地 LLM 需要
难度	中等
API 服务	Hayhooks（基于 FastAPI，REST）
关键集成	Ollama、OpenAI、Anthropic、HuggingFace、Elasticsearch、Pinecone、Weaviate、Qdrant

你可以构建什么

• RAG 流水线 ——摄取文档、生成嵌入、检索上下文、回答问题

• 语义搜索 ——按语义而不是关键词查询文档

• 文档处理 ——解析 PDF、HTML、Word 文档；拆分、清洗并索引内容

• 代理工作流 ——结合工具使用的多步骤推理（网页搜索、计算器、API）

• REST API 服务 ——通过 Hayhooks 将任意 Haystack 流水线暴露为端点

需求

硬件要求

使用场景	GPU	显存	内存	磁盘	Clore.ai 价格
仅 API 模式 （OpenAI/Anthropic）	无 / CPU	—	4 GB	20 GB	约 $0.01–0.05/小时
本地嵌入 （sentence-transformers）	RTX 3060	8 GB	16 GB	30 GB	$0.03–0.07/小时
本地嵌入 + 小型 LLM （7B）	RTX 3090	24 GB	16 GB	50 GB	$0.07–0.21/小时
本地 LLM （13B–34B）	RTX 4090	24 GB	32 GB	80 GB	$0.14–0.42/小时
大型本地 LLM （70B，量化）	A100 80GB	80 GB	64 GB	150 GB	裸机

对于大多数 RAG 用例， RTX 3090 是最佳选择，价格为 $0.07–0.21/小时——24 GB VRAM 可同时处理 sentence-transformer 嵌入 + 7B–13B 的本地 LLM。

软件要求

• Docker（Clore.ai 服务器上已预装）

• NVIDIA 驱动 + CUDA（Clore.ai GPU 服务器上已预装）

• Python 3.10+（在容器内）

• CUDA 11.8 或 12.x

快速开始

1. 租用一台 Clore.ai 服务器

在 Clore.ai 市场中，筛选：

• 显存：嵌入任务至少 8 GB，本地 LLM 至少 24 GB

• Docker：已启用（大多数列表中默认开启）

• 镜像: nvidia/cuda:12.8.1-devel-ubuntu22.04 或 pytorch/pytorch:2.11.0-cuda12.8-cudnn9-runtime

记下服务器的公网 IP 和 SSH 端口，来自 我的订单.

2. 连接并验证 GPU

ssh root@<clore-server-ip> -p <port>

# 验证 GPU 可用
nvidia-smi

# 预期输出会显示你的 GPU、驱动版本、CUDA 版本

3. 构建 Haystack Docker 镜像

Haystack v2 推荐使用 pip 安装。创建一个自定义 Dockerfile：

mkdir -p /workspace/haystack-app && cd /workspace/haystack-app

cat > Dockerfile << 'EOF'
FROM nvidia/cuda:12.8.1-devel-ubuntu22.04

# 避免交互式提示
ENV DEBIAN_FRONTEND=noninteractive
ENV PYTHONUNBUFFERED=1

# 安装 Python 和系统依赖
RUN apt-get update && apt-get install -y \
    python3.11 \
    python3-pip \
    python3.11-dev \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# 将 python3.11 设为默认
RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1
RUN update-alternatives --install /usr/bin/python python python3.11 1

# 安装 Haystack v2 和核心依赖
RUN pip install --no-cache-dir \
    haystack-ai \
    hayhooks \
    sentence-transformers \
    transformers \\
    torch \
    accelerate \\
    fastapi \
    uvicorn

# 安装可选集成
RUN pip install --no-cache-dir \
    ollama-haystack \
    haystack-experimental

WORKDIR /app

# Hayhooks 的默认端口
EXPOSE 1416

CMD ["hayhooks", "run", "--host", "0.0.0.0", "--port", "1416"]
EOF

# 构建镜像
docker build -t haystack-clore:latest .

4. 使用 Hayhooks 运行 Haystack

Hayhooks 会自动将任何 Haystack 流水线转换为 REST API：

# 为你的流水线创建一个目录
mkdir -p /workspace/haystack-pipelines

# 使用 GPU 访问运行 Hayhooks
docker run -d \\
  --name haystack \
  --gpus all \\
  -p 1416:1416 \
  -v /workspace/haystack-pipelines:/app/pipelines \
  -e OPENAI_API_KEY=${OPENAI_API_KEY:-""} \
  -e HF_TOKEN=${HF_TOKEN:-""} \
  haystack-clore:latest

# 检查它是否正在运行
curl http://localhost:1416/status

预期响应：

{"status": "ok", "pipelines": []}

5. 创建你的第一个 RAG 流水线

编写一个流水线 YAML，Hayhooks 会将其作为端点提供：

cat > /workspace/haystack-pipelines/rag_pipeline.yml << 'EOF'
# 使用 Ollama 作为 LLM + 本地嵌入进行检索的 RAG 流水线
components:
  embedder:
    type: haystack.components.embedders.SentenceTransformersTextEmbedder
    init_parameters:
      model: BAAI/bge-small-en-v1.5

  retriever:
    type: haystack.components.retrievers.in_memory.InMemoryEmbeddingRetriever
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.in_memory.InMemoryDocumentStore

  prompt_builder:
    type: haystack.components.builders.PromptBuilder
    init_parameters:
      template: |
        根据下面的上下文回答问题。
        Context: {% for doc in documents %}{{ doc.content }}{% endfor %}
        Question: {{ question }}

  llm:
    type: haystack_integrations.components.generators.ollama.OllamaGenerator
    init_parameters:
      model: llama3
      url: http://host.docker.internal:11434

connections:
  - sender: embedder.embedding
    receiver: retriever.query_embedding
  - sender: retriever.documents
    receiver: prompt_builder.documents
  - sender: prompt_builder.prompt
    receiver: llm.prompt

inputs:
  query:
    - embedder.text
    - prompt_builder.question

outputs:
  answer: llm.replies
EOF

Hayhooks 会自动发现并提供这个流水线。测试一下：

# 列出已部署的流水线
curl http://localhost:1416/pipelines

# 查询 RAG 流水线
curl -X POST http://localhost:1416/rag_pipeline/run \
  -H "Content-Type: application/json" \\
  -d '{"query": "What is Haystack?"}'

配置

环境变量

变量	描述	示例
OPENAI_API_KEY	用于 GPT 模型的 OpenAI API 密钥	sk-...
ANTHROPIC_API_KEY	用于 Claude 的 Anthropic API 密钥	sk-ant-...
HF_TOKEN	用于受限模型的 Hugging Face 令牌	hf_...
HAYSTACK_TELEMETRY_ENABLED	禁用使用情况遥测	false
CUDA_VISIBLE_DEVICES	选择特定 GPU	0
TRANSFORMERS_CACHE	HF 模型缓存路径	/workspace/hf-cache

使用完整配置运行

docker run -d \\
  --name haystack \
  --gpus '"device=0"' \
  -p 1416:1416 \
  -v /workspace/haystack-pipelines:/app/pipelines \
  -v /workspace/hf-cache:/root/.cache/huggingface \
  -e OPENAI_API_KEY="your-key-here" \
  -e HF_TOKEN="your-hf-token" \
  -e HAYSTACK_TELEMETRY_ENABLED=false \
  -e CUDA_VISIBLE_DEVICES=0 \
  --restart unless-stopped \
  haystack-clore:latest

文档摄取流水线

构建一个单独的索引流水线来摄取文档：

cat > /workspace/index_documents.py << 'EOF'
import haystack
from haystack import Pipeline
from haystack.components.converters import PyPDFToDocument, TextFileToDocument
from haystack.components.preprocessors import DocumentSplitter, DocumentCleaner
from haystack.components.embedders import SentenceTransformersDocumentEmbedder
from haystack.components.writers import DocumentWriter
from haystack.document_stores.in_memory import InMemoryDocumentStore

# 初始化文档存储
document_store = InMemoryDocumentStore()

# 构建索引流水线
indexing_pipeline = Pipeline()
indexing_pipeline.add_component("converter", PyPDFToDocument())
indexing_pipeline.add_component("cleaner", DocumentCleaner())
indexing_pipeline.add_component("splitter", DocumentSplitter(
    split_by="word",
    split_length=200,
    split_overlap=20
))
indexing_pipeline.add_component("embedder", SentenceTransformersDocumentEmbedder(
    model="BAAI/bge-small-en-v1.5"
))
indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_store))

# 连接组件
indexing_pipeline.connect("converter", "cleaner")
indexing_pipeline.connect("cleaner", "splitter")
indexing_pipeline.connect("splitter", "embedder")
indexing_pipeline.connect("embedder", "writer")

# 运行索引
from pathlib import Path
indexing_pipeline.run({"converter": {"sources": list(Path("/data/documents").glob("*.pdf"))}})

print(f"已索引 {document_store.count_documents()} 个文档块")
EOF

docker run --rm \\
  --gpus all \\
  -v /workspace:/workspace \
  -v /your/documents:/data/documents \
  -v /workspace/hf-cache:/root/.cache/huggingface \
  haystack-clore:latest \
  python3 /workspace/index_documents.py

使用向量数据库（生产环境）

对于生产工作负载，请用持久化向量数据库替换内存存储：

# 在 Haystack 旁边启动 Qdrant
docker network create haystack-net

docker run -d \\
  --name qdrant \
  --network haystack-net \
  -p 6333:6333 \
  -v /workspace/qdrant-data:/qdrant/storage \
  qdrant/qdrant

# 在 Haystack 容器中安装 Qdrant 集成
# 添加到 Dockerfile：RUN pip install qdrant-haystack
# 然后使用 QdrantDocumentStore 替代 InMemoryDocumentStore

GPU 加速

Haystack 主要在两种场景下使用 GPU 加速：

1. 嵌入生成（Sentence Transformers）

GPU 对于为大型文档集合生成嵌入非常有帮助：

cat > /workspace/benchmark_embeddings.py << 'EOF'
import time
import torch
from haystack.components.embedders import SentenceTransformersDocumentEmbedder
from haystack import Document

# 检查 GPU 是否可用
device = "cuda" if torch.cuda.is_available() else "cpu"
print(f"使用设备：{device}")
if device == "cuda":
    print(f"GPU: {torch.cuda.get_device_name(0)}")
    print(f"VRAM: {torch.cuda.get_device_properties(0).total_memory / 1e9:.1f} GB")

# 创建 embedder
embedder = SentenceTransformersDocumentEmbedder(
    model="BAAI/bge-base-en-v1.5"
)
embedder.warm_up()

# 基准测试
docs = [Document(content=f"示例文档 {i}，包含一些文本内容。") for i in range(100)]

start = time.time()
result = embedder.run(documents=docs)
elapsed = time.time() - start

print(f"100 个文档嵌入耗时 {elapsed:.2f} 秒（{100/elapsed:.0f} 文档/秒）")
EOF

docker run --rm --gpus all \
  -v /workspace:/workspace \
  haystack-clore:latest \
  python3 /workspace/benchmark_embeddings.py

2. 本地 LLM 推理（Hugging Face Transformers）

对于无需 Ollama、直接在 Haystack 中运行 LLM：

cat > /workspace/local_llm_pipeline.py << 'EOF'
from haystack import Pipeline
from haystack.components.builders import PromptBuilder
from haystack.components.generators.hugging_face import HuggingFaceLocalGenerator

# 可用时自动使用 GPU
generator = HuggingFaceLocalGenerator(
    model="mistralai/Mistral-7B-Instruct-v0.2",
    task="text-generation",
    generation_kwargs={
        "max_new_tokens": 512,
        "temperature": 0.7,
        "do_sample": True,
    }
)

prompt_builder = PromptBuilder(template="回答这个问题：{{ question }}")

pipeline = Pipeline()
pipeline.add_component("prompt_builder", prompt_builder)
pipeline.add_component("llm", generator)
pipeline.connect("prompt_builder.prompt", "llm.prompt")

result = pipeline.run({"prompt_builder": {"question": "什么是 RAG？"}})
print(result["llm"]["replies"][0])
EOF

docker run --rm --gpus all \
  -v /workspace:/workspace \
  -e HF_TOKEN="your-hf-token" \
  haystack-clore:latest \
  python3 /workspace/local_llm_pipeline.py

3. 与 Ollama 搭配（推荐方案）

为了兼顾易用性和性能，建议使用 Ollama 进行 LLM 推理，使用 Haystack 进行编排：

# 第 1 步：启动 Ollama（参见 Ollama 指南）
docker run -d \\
  --name ollama \
  --gpus all \\
  -p 11434:11434 \
  -v /workspace/ollama:/root/.ollama \
  ollama/ollama

# 第 2 步：拉取一个代码/聊天模型
docker exec ollama ollama pull llama3
docker exec ollama ollama pull nomic-embed-text  # 通过 Ollama 进行嵌入

# 第 3 步：启动指向 Ollama 的 Haystack
docker run -d \\
  --name haystack \
  --gpus '"device=0"' \
  -p 1416:1416 \
  --add-host=host.docker.internal:host-gateway \
  -v /workspace/haystack-pipelines:/app/pipelines \
  haystack-clore:latest

监控两个容器的 GPU 使用情况：

watch -n 2 nvidia-smi

提示与最佳实践

选择合适的嵌入模型

模型	显存	速度	质量	最适合
BAAI/bge-small-en-v1.5	约 0.5 GB	最快	好	高吞吐量索引
BAAI/bge-base-en-v1.5	约 1 GB	快	更好	通用 RAG
BAAI/bge-large-en-v1.5	约 2 GB	中等	最佳	最高准确率
nomic-ai/nomic-embed-text-v1	约 1.5 GB	快	优秀	长文档

流水线设计技巧

• 明智地拆分文档 ——200–400 词的块，重叠 10–15%，适用于大多数 RAG 用例

• 缓存嵌入 ——将文档存储持久化到磁盘；重新嵌入的成本很高

• 使用 warm_up() ——调用 component.warm_up() 在生产使用前，以便将模型加载到 GPU 内存中

• 批量索引 ——以 32–64 的批次处理文档，以获得最佳 GPU 利用率

• 使用元数据过滤 ——使用 Haystack 的元数据过滤来限定检索范围（例如按日期、来源、类别）

成本优化

# 在 Clore.ai 上使用类似现货的定价——选择每小时费用更低的服务器
# 开发/测试：RTX 3060（$0.03–0.07/小时）足以用于嵌入
# 生产环境嵌入：RTX 3090（$0.07–0.21/小时）——24 GB 可处理大批次
# 本地 LLM + 嵌入：A100 40GB（[裸机](https://clore.ai/bare-metal)）——为并发用户提供余量

# 监控资源使用情况
docker stats haystack
nvidia-smi dmon -s u -d 5  # 每 5 秒查看一次 GPU 利用率

为外部访问保护 Hayhooks

# 方案 1：SSH 隧道（最简单，适合个人使用）
# 从你的本地机器：
ssh -L 1416:localhost:1416 root@<clore-ip> -p <clore-ssh-port>
# 然后在本地访问 http://localhost:1416

# 方案 2：通过 nginx 反向代理添加基本认证
docker run -d \\
  --name nginx-proxy \
  -p 80:80 \
  -v /workspace/nginx.conf:/etc/nginx/conf.d/default.conf \
  nginx:alpine

故障排查

问题	可能原因	解决方案
ModuleNotFoundError: haystack	未安装包	重建 Docker 镜像；检查 pip install haystack-ai 成功
CUDA 内存不足	嵌入模型过大	使用 bge-small-en-v1.5 或减小批量大小
Hayhooks 在管道上返回 404	未找到 YAML 文件	检查卷挂载；管道文件必须位于 /app/pipelines/
CPU 上嵌入速度慢	未检测到 GPU	验证 --gpus all 标志；检查 torch.cuda.is_available()
Ollama 拒绝连接	主机名错误	使用 --add-host=host.docker.internal:host-gateway；将 URL 设置为 http://host.docker.internal:11434
HuggingFace 下载失败	缺少令牌或达到速率限制	设置 HF_TOKEN 环境变量；确保模型未受门控
管道 YAML 解析错误	无效语法	验证 YAML；使用 python3 -c "import yaml; yaml.safe_load(open('pipeline.yml'))"
容器立即退出	启动错误	查看 docker logs haystack；确保 Dockerfile 的 CMD 正确
端口 1416 无法从外部访问	防火墙 / 端口转发	在 Clore.ai 订单设置中暴露端口；检查服务器开放的端口

调试命令

# 查看容器日志
docker logs haystack --tail 50 -f

# 测试 Hayhooks API
curl http://localhost:1416/status
curl http://localhost:1416/pipelines

# 交互式 Python 调试会话
docker exec -it haystack python3

# 检查容器内的 GPU
docker exec haystack python3 -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

# 检查已安装的软件包
docker exec haystack pip show haystack-ai hayhooks

延伸阅读

• Haystack 文档 — 官方 v2 文档

• Hayhooks GitHub — 面向管道的 REST API 服务

• Haystack 食谱 — 端到端教程（RAG、代理、搜索）

• GitHub 上的 deepset-ai/haystack — 源码、问题、发布版本

• Haystack 集成 — 支持的向量存储、LLM 和工具完整列表

• Clore.ai 上的 Ollama — 将 Haystack 与 Ollama 配合用于本地 LLM 推理

• Clore.ai 上的 vLLM — 面向 Haystack 的高吞吐量 LLM 服务后端

• GPU 比较指南 — 为你的工作负载选择合适的 Clore.ai GPU

• CLORE.AI 市场 — 租用 GPU 服务器