> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-zh/ai-ping-tai-yu-zhi-neng-ti/haystack.md).

# 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 能显著降低延迟。

{% hint style="success" %}
所有示例都运行在通过以下方式租用的 GPU 服务器上： [CLORE.AI 市场](https://clore.ai/marketplace).
{% endhint %}

{% hint style="info" %}
本指南涵盖 **Haystack v2.x** (`haystack-ai` 包）。v2 API 与 v1（`farm-haystack`）有很大不同。如果你已有现成的 v1 流水线，请参阅 [迁移指南](https://docs.haystack.deepset.ai/docs/migration).
{% endhint %}

## 概览

| 属性               | 详情                                                                         |
| ---------------- | -------------------------------------------------------------------------- |
| **项目**           | [deepset-ai/haystack](https://github.com/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 | [裸机](https://clore.ai/bare-metal) |

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

### 软件要求

* Docker（Clore.ai 服务器上已预装）
* NVIDIA 驱动 + CUDA（Clore.ai GPU 服务器上已预装）
* Python 3.10+（在容器内）
* CUDA 11.8 或 12.x

## 快速开始

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

在 [Clore.ai 市场](https://clore.ai/marketplace)中，筛选：

* **显存**：嵌入任务至少 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

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

# 验证 GPU 可用
nvidia-smi

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

### 3. 构建 Haystack Docker 镜像

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

```bash
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](https://github.com/deepset-ai/hayhooks) 会自动将任何 Haystack 流水线转换为 REST API：

```bash
# 为你的流水线创建一个目录
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
```

预期响应：

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

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

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

```bash
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 会自动发现并提供这个流水线。测试一下：

```bash
# 列出已部署的流水线
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` |

### 使用完整配置运行

```bash
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
```

### 文档摄取流水线

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

```bash
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
```

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

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

```bash
# 在 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 对于为大型文档集合生成嵌入非常有帮助：

```bash
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：

```bash
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 进行编排：

```bash
# 第 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 使用情况：

```bash
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 的元数据过滤来限定检索范围（例如按日期、来源、类别）

### 成本优化

```bash
# 在 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

```bash
# 方案 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 订单设置中暴露端口；检查服务器开放的端口                                                                 |

### 调试命令

```bash
# 查看容器日志
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 文档](https://docs.haystack.deepset.ai/) — 官方 v2 文档
* [Hayhooks GitHub](https://github.com/deepset-ai/hayhooks) — 面向管道的 REST API 服务
* [Haystack 食谱](https://haystack.deepset.ai/cookbook) — 端到端教程（RAG、代理、搜索）
* [GitHub 上的 deepset-ai/haystack](https://github.com/deepset-ai/haystack) — 源码、问题、发布版本
* [Haystack 集成](https://haystack.deepset.ai/integrations) — 支持的向量存储、LLM 和工具完整列表
* [Clore.ai 上的 Ollama](/guides/guides_v2-zh/yu-yan-mo-xing/ollama.md) — 将 Haystack 与 Ollama 配合用于本地 LLM 推理
* [Clore.ai 上的 vLLM](/guides/guides_v2-zh/yu-yan-mo-xing/vllm.md) — 面向 Haystack 的高吞吐量 LLM 服务后端
* [GPU 比较指南](/guides/guides_v2-zh/ru-men-zhi-nan/gpu-comparison.md) — 为你的工作负载选择合适的 Clore.ai GPU
* [CLORE.AI 市场](https://clore.ai/marketplace) — 租用 GPU 服务器


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/ai-ping-tai-yu-zhi-neng-ti/haystack.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.