# Haystack KI-Framework

Haystack ist deepsets Open-Source-AI-Orchestrierungsframework zum Erstellen produktionsreifer LLM-Anwendungen. Mit über 18.000 GitHub-Sternen bietet es eine flexible **pipeline-basierte Architektur** die Dokumentenspeicher, Retriever, Reader, Generatoren und Agents miteinander verbindet – alles in sauberem, komponierbarem Python. Ob Sie RAG über private Dokumente, semantische Suche oder mehrstufige Agenten-Workflows benötigen, Haystack übernimmt die Infrastruktur, damit Sie sich auf die Anwendungslogik konzentrieren können.

Auf Clore.ai überzeugt Haystack, wenn Sie eine GPU für lokale Modellausführung über Hugging Face Transformers oder sentence-transformers benötigen. Wenn Sie ausschließlich auf externe APIs (OpenAI, Anthropic) angewiesen sind, können Sie es auf CPU-only-Instanzen betreiben – aber für Embedding-Generierung und lokale LLMs reduziert eine GPU die Latenz dramatisch.

{% hint style="success" %}
Alle Beispiele laufen auf GPU-Servern, die über die [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

{% hint style="info" %}
Dieser Leitfaden behandelt **Haystack v2.x** (`haystack-ai` Paket). Die v2-API unterscheidet sich deutlich von v1 (`farm-haystack`). Wenn Sie vorhandene v1-Pipelines haben, siehe die [Migrationsanleitung](https://docs.haystack.deepset.ai/docs/migration).
{% endhint %}

## Überblick

| Eigenschaft                 | Details                                                                           |
| --------------------------- | --------------------------------------------------------------------------------- |
| **Projekt**                 | [deepset-ai/haystack](https://github.com/deepset-ai/haystack)                     |
| **Lizenz**                  | Apache 2.0                                                                        |
| **GitHub-Sterne**           | 18K+                                                                              |
| **Version**                 | v2.x (`haystack-ai`)                                                              |
| **Primärer Anwendungsfall** | RAG, semantische Suche, Dokumenten-QA, Agenten-Workflows                          |
| **GPU-Unterstützung**       | Optional — erforderlich für lokale Embeddings / lokale LLMs                       |
| **Schwierigkeitsgrad**      | Mittel                                                                            |
| **API-Serving**             | Hayhooks (FastAPI-basiert, REST)                                                  |
| **Wichtige Integrationen**  | Ollama, OpenAI, Anthropic, HuggingFace, Elasticsearch, Pinecone, Weaviate, Qdrant |

### Was Sie bauen können

* **RAG-Pipelines** — Dokumente einlesen, Embeddings erzeugen, Kontext abrufen, Fragen beantworten
* **Semantische Suche** — Dokumente nach Bedeutung, nicht nach Schlüsselwörtern abfragen
* **Dokumentenverarbeitung** — PDFs, HTML, Word-Dokumente parsen; Inhalte aufteilen, bereinigen und indexieren
* **Agenten-Workflows** — mehrstufiges Schließen mit Werkzeugnutzung (Websuche, Taschenrechner, APIs)
* **REST-API-Services** — jede Haystack-Pipeline über Hayhooks als Endpoint bereitstellen

## Anforderungen

### Hardware-Anforderungen

| Einsatzgebiet                                 | GPU         | VRAM  | RAM   | Festplatte | Clore.ai-Preis      |
| --------------------------------------------- | ----------- | ----- | ----- | ---------- | ------------------- |
| **Nur API-Modus** (OpenAI/Anthropic)          | Keine / CPU | —     | 4 GB  | 20 GB      | \~$0.01–0.05/Stunde |
| **Lokale Embeddings** (sentence-transformers) | RTX 3060    | 8 GB  | 16 GB | 30 GB      | \~$0.10–0.15/Stunde |
| **Lokale Embeddings + kleines LLM** (7B)      | RTX 3090    | 24 GB | 16 GB | 50 GB      | \~$0.20–0.25/Stunde |
| **Lokales LLM** (13B–34B)                     | RTX 4090    | 24 GB | 32 GB | 80 GB      | \~$0.35–0.50/Stunde |
| **Großes lokales LLM** (70B, quantisiert)     | A100 80GB   | 80 GB | 64 GB | 150 GB     | \~$1.10–1.50/Stunde |

{% hint style="info" %}
Für die meisten RAG-Anwendungsfälle ist ein **RTX 3090** bei \~ $0.20/Stunde der Sweet Spot — 24 GB VRAM bewältigen sentence-transformer-Embeddings + ein 7B–13B lokales LLM gleichzeitig.
{% endhint %}

### Softwareanforderungen

* Docker (vorinstalliert auf Clore.ai-Servern)
* NVIDIA-Treiber + CUDA (vorinstalliert auf Clore.ai-GPU-Servern)
* Python 3.10+ (innerhalb des Containers)
* CUDA 11.8 oder 12.x

## Schnellstart

### 1. Mieten Sie einen Clore.ai-Server

Im [Clore.ai-Marktplatz](https://clore.ai/marketplace), filtern nach:

* **VRAM**: ≥ 8 GB für Embedding-Workloads, ≥ 24 GB für lokale LLMs
* **Docker**: Aktiviert (Standard bei den meisten Angeboten)
* **Image**: `nvidia/cuda:12.1-devel-ubuntu22.04` oder `pytorch/pytorch:2.2.0-cuda12.1-cudnn8-runtime`

Notieren Sie die öffentliche IP und den SSH-Port des Servers aus **Meine Bestellungen**.

### 2. Verbinden und GPU überprüfen

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

# GPU-Verfügbarkeit prüfen
nvidia-smi

# Erwartete Ausgabe zeigt Ihre GPU, Treiberversion, CUDA-Version
```

### 3. Erstellen Sie das Haystack-Docker-Image

Haystack v2 empfiehlt die Installation via pip. Erstellen Sie eine benutzerdefinierte Dockerfile:

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

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

# Interaktive Eingaben vermeiden
ENV DEBIAN_FRONTEND=noninteractive
ENV PYTHONUNBUFFERED=1

# Python und Systemabhängigkeiten installieren
RUN apt-get update && apt-get install -y \
    python3.11 \
    python3-pip \
    python3.11-dev \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Setze python3.11 als Standard
RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1
RUN update-alternatives --install /usr/bin/python python python3.11 1

# Installiere Haystack v2 und Kernabhängigkeiten
RUN pip install --no-cache-dir \
    haystack-ai \
    hayhooks \
    sentence-transformers \
    transformers \
    torch \
    accelerate \
    fastapi \
    uvicorn

# Optionale Integrationen installieren
RUN pip install --no-cache-dir \
    ollama-haystack \
    haystack-experimental

WORKDIR /app

# Standardport für Hayhooks
EXPOSE 1416

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

# Image bauen
docker build -t haystack-clore:latest .
```

### 4. Haystack mit Hayhooks ausführen

[Hayhooks](https://github.com/deepset-ai/hayhooks) wandelt jede Haystack-Pipeline automatisch in eine REST-API um:

```bash
# Erstellen Sie ein Verzeichnis für Ihre Pipelines
mkdir -p /workspace/haystack-pipelines

# Hayhooks mit GPU-Zugriff ausführen
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

# Prüfen, ob es läuft
curl http://localhost:1416/status
```

Erwartete Antwort:

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

### 5. Erstellen Sie Ihre erste RAG-Pipeline

Schreiben Sie ein Pipeline-YAML, das Hayhooks als Endpoint bereitstellt:

```bash
cat > /workspace/haystack-pipelines/rag_pipeline.yml << 'EOF'
# RAG-Pipeline, die Ollama für LLM + lokale Embeddings für Retrieval verwendet
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: |
        Beantworte die Frage basierend auf dem untenstehenden Kontext.
        Kontext: {% for doc in documents %}{{ doc.content }}{% endfor %}
        Frage: {{ 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 entdeckt und bedient diese Pipeline automatisch. Testen Sie sie:

```bash
# Aufgelistete Pipelines anzeigen
curl http://localhost:1416/pipelines

# Die RAG-Pipeline abfragen
curl -X POST http://localhost:1416/rag_pipeline/run \
  -H "Content-Type: application/json" \
  -d '{"query": "What is Haystack?"}'
```

## Konfiguration

### Umgebungsvariablen

| Variable                     | Beschreibung                              | Beispiel              |
| ---------------------------- | ----------------------------------------- | --------------------- |
| `OPENAI_API_KEY`             | OpenAI-API-Schlüssel für GPT-Modelle      | `sk-...`              |
| `ANTHROPIC_API_KEY`          | Anthropic-API-Schlüssel für Claude        | `sk-ant-...`          |
| `HF_TOKEN`                   | Hugging Face-Token für geschützte Modelle | `hf_...`              |
| `HAYSTACK_TELEMETRY_ENABLED` | Verwendungstelemetrie deaktivieren        | `false`               |
| `CUDA_VISIBLE_DEVICES`       | Bestimmte GPU auswählen                   | `0`                   |
| `TRANSFORMERS_CACHE`         | Cache-Pfad für HF-Modelle                 | `/workspace/hf-cache` |

### Mit vollständiger Konfiguration ausführen

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

### Dokumenten-Ingestions-Pipeline

Erstellen Sie eine separate Indexierungs-Pipeline zum Ingestieren von Dokumenten:

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

# Dokumentenspeicher initialisieren
document_store = InMemoryDocumentStore()

# Indexierungs-Pipeline erstellen
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))

# Komponenten verbinden
indexing_pipeline.connect("converter", "cleaner")
indexing_pipeline.connect("cleaner", "splitter")
indexing_pipeline.connect("splitter", "embedder")
indexing_pipeline.connect("embedder", "writer")

# Indexierung ausführen
from pathlib import Path
indexing_pipeline.run({"converter": {"sources": list(Path("/data/documents").glob("*.pdf"))}})

print(f"Indexed {document_store.count_documents()} document chunks")
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
```

### Verwendung von Vektor-Datenbanken (Produktion)

Für Produktions-Workloads ersetzen Sie den In-Memory-Store durch eine persistente Vektor-Datenbank:

```bash
# Qdrant zusammen mit Haystack starten
docker network create haystack-net

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

# Qdrant-Integration im Haystack-Container installieren
# Zur Dockerfile hinzufügen:  RUN pip install qdrant-haystack
# Verwenden Sie dann QdrantDocumentStore anstelle von InMemoryDocumentStore
```

## GPU-Beschleunigung

Haystack nutzt GPU-Beschleunigung in zwei Hauptszenarien:

### 1. Embedding-Generierung (Sentence Transformers)

GPU ist sehr nützlich beim Einbetten großer Dokumentensammlungen:

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

# GPU-Verfügbarkeit prüfen
device = "cuda" if torch.cuda.is_available() else "cpu"
print(f"Using device: {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 erstellen
embedder = SentenceTransformersDocumentEmbedder(
    model="BAAI/bge-base-en-v1.5"
)
embedder.warm_up()

# Benchmark
docs = [Document(content=f"Sample document {i} with some text content.") for i in range(100)]

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

print(f"Embedded 100 documents in {elapsed:.2f}s ({100/elapsed:.0f} docs/sec)")
EOF

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

### 2. Lokale LLM-Inferenz (Hugging Face Transformers)

Zum Ausführen von LLMs direkt in Haystack ohne Ollama:

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

# Verwendet automatisch die GPU, wenn verfügbar
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="Answer this question: {{ 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": "What is 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. Kombination mit Ollama (empfohlener Ansatz)

Für die beste Kombination aus Einfachheit und Leistung: Führen Sie Ollama für LLM-Inferenz und Haystack für Orchestrierung aus:

```bash
# Schritt 1: Ollama starten (siehe Ollama-Anleitung)
docker run -d \
  --name ollama \
  --gpus all \
  -p 11434:11434 \
  -v /workspace/ollama:/root/.ollama \
  ollama/ollama

# Schritt 2: Ein Coding-/Chat-Modell herunterladen
docker exec ollama ollama pull llama3
docker exec ollama ollama pull nomic-embed-text  # Für Embeddings via Ollama

# Schritt 3: Haystack starten und auf Ollama verweisen
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
```

Überwachen Sie die GPU-Auslastung über beide Container hinweg:

```bash
watch -n 2 nvidia-smi
```

## Tipps & bewährte Methoden

### Wählen Sie das richtige Embedding-Modell

| Modell                         | VRAM     | Geschwindigkeit | Qualität      | Am besten geeignet für      |
| ------------------------------ | -------- | --------------- | ------------- | --------------------------- |
| `BAAI/bge-small-en-v1.5`       | \~0,5 GB | Am schnellsten  | Gut           | Durchsatzstarke Indexierung |
| `BAAI/bge-base-en-v1.5`        | \~1 GB   | Schnell         | Besser        | Allgemeines RAG             |
| `BAAI/bge-large-en-v1.5`       | \~2 GB   | Mittel          | Am besten     | Höchste Genauigkeit         |
| `nomic-ai/nomic-embed-text-v1` | \~1.5 GB | Schnell         | Ausgezeichnet | Lange Dokumente             |

### Tipps zum Pipeline-Design

* **Dokumente sinnvoll aufteilen** — 200–400 Wortabschnitte mit 10–15% Überlappung funktionieren für die meisten RAG-Anwendungsfälle gut
* **Embeddings cachen** — persistieren Sie Ihren Dokumentenspeicher auf der Festplatte; erneutes Einbetten ist teuer
* **Verwenden Sie `warm_up()`** — rufen Sie `component.warm_up()` vor dem Produktionseinsatz auf, um Modelle in den GPU-Speicher zu laden
* **Batch-Indexierung** — verarbeiten Sie Dokumente in Chargen von 32–64 für optimale GPU-Auslastung
* **Mit Metadaten filtern** — nutzen Sie Haystacks Metadatenfilterung, um die Retrieval-Scope einzuschränken (z. B. nach Datum, Quelle, Kategorie)

### Kostenoptimierung

```bash
# Verwenden Sie Spot-ähnliche Preise auf Clore.ai — wählen Sie Server mit geringeren $/Std.
# Für Entwicklung/Test: RTX 3060 (~$0.10/Std.) ist ausreichend für Embeddings
# Für Produktions-Embedding: RTX 3090 (~$0.20/Std.) — 24 GB bewältigen große Batches
# Für lokales LLM + Embedding: A100 40GB (~$0.60/Std.) — Reserven für gleichzeitige Nutzer

# Ressourcenverbrauch überwachen
docker stats haystack
nvidia-smi dmon -s u -d 5  # GPU-Auslastung alle 5 Sekunden
```

### Hayhooks für externen Zugriff sichern

```bash
# Option 1: SSH-Tunnel (einfachste, für persönliche Nutzung)
# Von Ihrer lokalen Maschine:
ssh -L 1416:localhost:1416 root@<clore-ip> -p <clore-ssh-port>
# Dann lokal auf http://localhost:1416 zugreifen

# Option 2: Basis-Auth via nginx-Reverse-Proxy hinzufügen
docker run -d \
  --name nginx-proxy \
  -p 80:80 \
  -v /workspace/nginx.conf:/etc/nginx/conf.d/default.conf \
  nginx:alpine
```

## Fehlerbehebung

| Problem                               | Wahrscheinliche Ursache       | Lösung                                                                                                    |
| ------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------- |
| `ModuleNotFoundError: haystack`       | Paket nicht installiert       | Docker-Image neu bauen; prüfen Sie `pip install haystack-ai` erfolgreich                                  |
| `CUDA out of memory`                  | Embedding-Modell zu groß      | Verwenden Sie `bge-small-en-v1.5` oder verringern Sie die Batch-Größe                                     |
| Hayhooks gibt 404 für Pipeline zurück | YAML-Datei nicht gefunden     | Prüfen Sie das Volume-Mount; die Pipeline-Datei muss sich in `/app/pipelines/`                            |
| Langsame Embeddings auf CPU           | GPU nicht erkannt             | Überprüfen Sie `--gpus all` Flag; prüfen Sie `torch.cuda.is_available()`                                  |
| Ollama-Verbindung abgelehnt           | Falscher Hostname             | Verwenden Sie `--add-host=host.docker.internal:host-gateway`; URL auf `http://host.docker.internal:11434` |
| HuggingFace-Download schlägt fehl     | Token fehlt oder Rate-Limit   | Setze `HF_TOKEN` env-Var; stellen Sie sicher, dass das Modell nicht geschützt ist                         |
| Pipeline-YAML-Parse-Fehler            | Ungültige Syntax              | Validieren Sie das YAML; verwenden Sie `python3 -c "import yaml; yaml.safe_load(open('pipeline.yml'))"`   |
| Container beendet sich sofort         | Startfehler                   | Überprüfen Sie `docker logs haystack`; stellen Sie sicher, dass CMD in der Dockerfile korrekt ist         |
| Port 1416 extern nicht erreichbar     | Firewall / Port-Weiterleitung | Port in den Clore.ai-Bestelloptionen freigeben; prüfen Sie die offenen Ports des Servers                  |

### Debug-Befehle

```bash
# Container-Logs prüfen
docker logs haystack --tail 50 -f

# Hayhooks-API testen
curl http://localhost:1416/status
curl http://localhost:1416/pipelines

# Interaktive Python-Debug-Session
docker exec -it haystack python3

# GPU im Container prüfen
docker exec haystack python3 -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

# Installierte Pakete prüfen
docker exec haystack pip show haystack-ai hayhooks
```

## Weiterführende Lektüre

* [Haystack-Dokumentation](https://docs.haystack.deepset.ai/) — offizielle v2-Dokumentation
* [Hayhooks GitHub](https://github.com/deepset-ai/hayhooks) — REST-API-Serving für Pipelines
* [Haystack Cookbook](https://haystack.deepset.ai/cookbook) — End-to-End-Tutorials (RAG, Agents, Search)
* [deepset-ai/haystack auf GitHub](https://github.com/deepset-ai/haystack) — Quellcode, Issues, Releases
* [Haystack-Integrationen](https://haystack.deepset.ai/integrations) — vollständige Liste der unterstützten Vektor-Stores, LLMs und Tools
* [Ollama auf Clore.ai](https://docs.clore.ai/guides/guides_v2-de/sprachmodelle/ollama) — Haystack mit Ollama für lokale LLM-Inferenz kombinieren
* [vLLM auf Clore.ai](https://docs.clore.ai/guides/guides_v2-de/sprachmodelle/vllm) — hochdurchsatzfähiges LLM-Serving-Backend für Haystack
* [GPU-Vergleichsanleitung](https://docs.clore.ai/guides/guides_v2-de/erste-schritte/gpu-comparison) — wählen Sie die richtige Clore.ai-GPU für Ihre Arbeitslast
* [CLORE.AI Marketplace](https://clore.ai/marketplace) — GPU-Server mieten