Cadre IA Haystack

Déployez Haystack de deepset sur Clore.ai — construisez des pipelines RAG de production, la recherche sémantique et des flux de travail d'agents LLM sur une infrastructure GPU abordable.

Haystack est le framework d'orchestration IA open-source de deepset pour construire des applications LLM prêtes pour la production. Avec plus de 18K étoiles sur GitHub, il offre une architecture flexible basée sur des pipelines qui connecte des magasins de documents, des récupérateurs, des lecteurs, des générateurs et des agents — le tout en Python propre et composable. Que vous ayez besoin de RAG sur des documents privés, de recherche sémantique ou de workflows d'agents en plusieurs étapes, Haystack gère la plomberie pour que vous puissiez vous concentrer sur la logique applicative.

Sur Clore.ai, Haystack brille lorsque vous avez besoin d'un GPU pour l'inférence locale de modèles via Hugging Face Transformers ou sentence-transformers. Si vous dépendez uniquement d'API externes (OpenAI, Anthropic), vous pouvez l'exécuter sur des instances CPU seulement — mais pour la génération d'embeddings et les LLM locaux, un GPU réduit considérablement la latence.

Tous les exemples s'exécutent sur des serveurs GPU loués via le CLORE.AI Marketplace.

Ce guide couvre Haystack v2.x (package haystack-ai L'API v2 diffère significativement de la v1 (farm-haystack). Si vous avez des pipelines v1 existants, consultez le guide de migration.

Aperçu

Propriété	Détails
Projet	deepset-ai/haystack
Licence	Apache 2.0
Étoiles GitHub	18K+
Version	v2.x (package haystack-ai)
Cas d'utilisation principal	RAG, recherche sémantique, QA sur documents, workflows d'agents
Support GPU	Optionnel — requis pour les embeddings locaux / LLM locaux
Difficulté	Moyen
Exposition d'API	Hayhooks (basé sur FastAPI, REST)
Intégrations clés	Ollama, OpenAI, Anthropic, HuggingFace, Elasticsearch, Pinecone, Weaviate, Qdrant

Ce que vous pouvez construire

• Pipelines RAG — ingérer des documents, générer des embeddings, récupérer du contexte, répondre aux questions

• Recherche sémantique — interroger des documents par sens, pas par mots-clés

• Traitement de documents — analyser des PDF, HTML, documents Word ; scinder, nettoyer et indexer le contenu

• Workflows d'agents — raisonnement multi-étapes avec utilisation d'outils (recherche web, calculatrices, API)

• Services API REST — exposer n'importe quel pipeline Haystack comme un endpoint via Hayhooks

Exigences

Exigences matérielles

Cas d'utilisation	GPU	VRAM	RAM	Disque	Prix Clore.ai
Mode API uniquement (OpenAI/Anthropic)	Aucun / CPU	—	4 Go	20 Go	~0,01–0,05 $/h
Embeddings locaux (sentence-transformers)	RTX 3060	8 Go	16 Go	30 Go	~0,10–0,15 $/h
Embeddings locaux + petit LLM (7B)	RTX 3090	24 Go	16 Go	50 Go	~0,20–0,25 $/h
LLM local (13B–34B)	RTX 4090	24 Go	32 Go	80 Go	~0,35–0,50 $/h
Grand LLM local (70B, quantifié)	A100 80GB	80 Go	64 Go	150 Go	~1,10–1,50 $/h

Pour la plupart des cas RAG, un RTX 3090 à ~0,20 $/h est le compromis idéal — 24 Go de VRAM gèrent à la fois les embeddings sentence-transformer et un LLM local 7B–13B simultanément.

Exigences logicielles

• Docker (préinstallé sur les serveurs Clore.ai)

• Pilotes NVIDIA + CUDA (préinstallés sur les serveurs GPU Clore.ai)

• Python 3.10+ (à l'intérieur du conteneur)

• CUDA 11.8 ou 12.x

Démarrage rapide

1. Louer un serveur Clore.ai

Dans le Clore.ai Marketplace, filtrez par :

• VRAM: ≥ 8 Go pour les charges d'embedding, ≥ 24 Go pour les LLM locaux

• Docker: Activé (par défaut sur la plupart des annonces)

• Image: nvidia/cuda:12.1-devel-ubuntu22.04 ou pytorch/pytorch:2.2.0-cuda12.1-cudnn8-runtime

Notez l'IP publique du serveur et le port SSH depuis Mes commandes.

2. Se connecter et vérifier le GPU

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

# Vérifier que le GPU est disponible
nvidia-smi

# La sortie attendue affiche votre GPU, la version du driver, la version CUDA

3. Construire l'image Docker Haystack

Haystack v2 recommande l'installation via pip. Créez un Dockerfile personnalisé :

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

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

# Éviter les invites interactives
ENV DEBIAN_FRONTEND=noninteractive
ENV PYTHONUNBUFFERED=1

# Installer Python et les dépendances système
RUN apt-get update && apt-get install -y \
    python3.11 \
    python3-pip \
    python3.11-dev \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Définir python3.11 par défaut
RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1
RUN update-alternatives --install /usr/bin/python python python3.11 1

# Installer Haystack v2 et les dépendances principales
RUN pip install --no-cache-dir \
    haystack-ai \
    hayhooks \
    sentence-transformers \
    transformers \
    torch \
    accelerate \
    fastapi \
    uvicorn

# Installer les intégrations optionnelles
RUN pip install --no-cache-dir \
    ollama-haystack \
    haystack-experimental

WORKDIR /app

# Port par défaut pour Hayhooks
EXPOSE 1416

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

# Construire l'image
docker build -t haystack-clore:latest .

4. Exécuter Haystack avec Hayhooks

Hayhooks transforme automatiquement n'importe quel pipeline Haystack en une API REST :

# Créer un répertoire pour vos pipelines
mkdir -p /workspace/haystack-pipelines

# Exécuter Hayhooks avec accès GPU
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

# Vérifier que c'est en cours d'exécution
curl http://localhost:1416/status

Réponse attendue :

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

5. Créez votre premier pipeline RAG

Écrivez un YAML de pipeline que Hayhooks servira comme endpoint :

cat > /workspace/haystack-pipelines/rag_pipeline.yml << 'EOF'
# Pipeline RAG utilisant Ollama pour le LLM + embeddings locaux pour la récupération
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: |
        Répondez à la question en vous basant sur le contexte ci-dessous.
        Contexte : {% 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 découvre et sert automatiquement ce pipeline. Testez-le :

# Lister les pipelines déployés
curl http://localhost:1416/pipelines

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

Configuration

Variables d'environnement

Variable	Description	Exemple
OPENAI_API_KEY	Clé API OpenAI pour les modèles GPT	sk-...
ANTHROPIC_API_KEY	Clé API Anthropic pour Claude	sk-ant-...
HF_TOKEN	Token Hugging Face pour modèles protégés	hf_...
HAYSTACK_TELEMETRY_ENABLED	Désactiver la télémétrie d'utilisation	false
CUDA_VISIBLE_DEVICES	Sélectionner un GPU spécifique	0
TRANSFORMERS_CACHE	Chemin du cache pour les modèles HF	/workspace/hf-cache

Exécuter avec configuration complète

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

Pipeline d'ingestion de documents

Construisez un pipeline d'indexation séparé pour ingérer des documents :

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

# Initialiser le magasin de documents
document_store = InMemoryDocumentStore()

# Construire le pipeline d'indexation
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))

# Connecter les composants
indexing_pipeline.connect("converter", "cleaner")
indexing_pipeline.connect("cleaner", "splitter")
indexing_pipeline.connect("splitter", "embedder")
indexing_pipeline.connect("embedder", "writer")

# Exécuter l'indexation
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

Utilisation de bases de vecteurs (production)

Pour des charges en production, remplacez le magasin en mémoire par une base de vecteurs persistante :

# Lancer Qdrant aux côtés de Haystack
docker network create haystack-net

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

# Installer l'intégration Qdrant dans le conteneur Haystack
# Ajouter au Dockerfile : RUN pip install qdrant-haystack
# Puis utiliser QdrantDocumentStore au lieu de InMemoryDocumentStore

Accélération GPU

Haystack utilise l'accélération GPU dans deux scénarios principaux :

1. Génération d'embeddings (Sentence Transformers)

Le GPU est très bénéfique pour embedder de grandes collections de documents :

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

# Vérifier la disponibilité du GPU
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")

# Créer l'embedder
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. Inférence de LLM local (Hugging Face Transformers)

Pour exécuter des LLM directement dans Haystack sans Ollama :

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

# Utilise automatiquement le GPU lorsqu'il est disponible
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. Associer avec Ollama (approche recommandée)

Pour la meilleure combinaison de facilité et de performance, exécutez Ollama pour l'inférence LLM et Haystack pour l'orchestration :

# Étape 1 : Démarrer Ollama (voir le guide Ollama)
docker run -d \
  --name ollama \
  --gpus all \
  -p 11434:11434 \
  -v /workspace/ollama:/root/.ollama \
  ollama/ollama

# Étape 2 : Pull d'un modèle de code/chat
docker exec ollama ollama pull llama3
docker exec ollama ollama pull nomic-embed-text  # Pour les embeddings via Ollama

# Étape 3 : Démarrer Haystack en pointant vers Ollama
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

Surveiller l'utilisation GPU entre les deux conteneurs :

watch -n 2 nvidia-smi

Conseils et bonnes pratiques

Choisir le bon modèle d'embedding

Modèle	VRAM	Vitesse	Qualité	Idéal pour
BAAI/bge-small-en-v1.5	~0,5 Go	Le plus rapide	Bon	Indexation à haut débit
BAAI/bge-base-en-v1.5	~1 Go	Rapide	Meilleur	RAG général
BAAI/bge-large-en-v1.5	~2 Go	Moyen	Meilleur	Précision la plus élevée
nomic-ai/nomic-embed-text-v1	~1,5 Go	Rapide	Excellent	Documents longs

Conseils de conception de pipeline

• Scindez les documents judicieusement — des morceaux de 200–400 mots avec un chevauchement de 10–15% fonctionnent bien pour la plupart des cas RAG

• Mettre en cache les embeddings — persistez votre magasin de documents sur disque ; ré-embedder est coûteux

• Utilisez warm_up() — appelez component.warm_up() avant l'utilisation en production pour charger les modèles en mémoire GPU

• Indexation par lots — traitez les documents par lots de 32–64 pour une utilisation optimale du GPU

• Filtrer avec les métadonnées — utilisez le filtrage par métadonnées de Haystack pour restreindre la récupération (par ex. par date, source, catégorie)

Optimisation des coûts

# Utilisez les tarifs style spot sur Clore.ai — choisissez des serveurs avec un $/h inférieur
# Pour le développement/test : RTX 3060 (~0,10 $/h) suffit pour l'embedding
# Pour l'embedding en production : RTX 3090 (~0,20 $/h) — 24 Go gèrent de grands lots
# Pour LLM local + embedding : A100 40GB (~0,60 $/h) — marge pour utilisateurs concurrents

# Surveiller l'utilisation des ressources
docker stats haystack
nvidia-smi dmon -s u -d 5  # Utilisation GPU toutes les 5 secondes

Sécuriser Hayhooks pour un accès externe

# Option 1 : Tunnel SSH (le plus simple, pour usage personnel)
# Depuis votre machine locale :
ssh -L 1416:localhost:1416 root@<clore-ip> -p <clore-ssh-port>
# Puis accéder à http://localhost:1416 localement

# Option 2 : Ajouter une authentification basique via un reverse proxy nginx
docker run -d \
  --name nginx-proxy \
  -p 80:80 \
  -v /workspace/nginx.conf:/etc/nginx/conf.d/default.conf \
  nginx:alpine

Dépannage

Problème	Cause probable	Solution
ModuleNotFoundError: haystack	Package non installé	Reconstruire l'image Docker ; vérifier pip install haystack-ai réussi
CUDA out of memory	Modèle d'embedding trop volumineux	Utilisez bge-small-en-v1.5 ou réduire la taille de lot
Hayhooks renvoie 404 sur le pipeline	Fichier YAML introuvable	Vérifiez le montage du volume ; le fichier de pipeline doit être dans /app/pipelines/
Embedding lent sur CPU	GPU non détecté	Vérifier --gpus all option ; vérifier torch.cuda.is_available()
Connexion Ollama refusée	Nom d'hôte incorrect	Utilisez --add-host=host.docker.internal:host-gateway; définir l'URL sur http://host.docker.internal:11434
Échec du téléchargement HuggingFace	Token manquant ou limite de taux	Définir HF_TOKEN var env ; assurez-vous que le modèle n'est pas protégé
Erreur d'analyse YAML du pipeline	Syntaxe invalide	Validez le YAML ; utilisez python3 -c "import yaml; yaml.safe_load(open('pipeline.yml'))"
Le conteneur se termine immédiatement	Erreur de démarrage	Vérifiez docker logs haystack; assurez-vous que la CMD du Dockerfile est correcte
Le port 1416 non joignable depuis l'extérieur	Pare-feu / redirection de port	Exposez le port dans les paramètres de commande Clore.ai ; vérifiez les ports ouverts du serveur

Commandes de débogage

# Vérifier les logs du conteneur
docker logs haystack --tail 50 -f

# Tester l'API Hayhooks
curl http://localhost:1416/status
curl http://localhost:1416/pipelines

# Session de débogage Python interactive
docker exec -it haystack python3

# Vérifier le GPU à l'intérieur du conteneur
docker exec haystack python3 -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

# Vérifier les paquets installés
docker exec haystack pip show haystack-ai hayhooks

Lectures complémentaires

• Documentation Haystack — docs officielles v2

• Hayhooks GitHub — exposition d'API REST pour les pipelines

• Haystack Cookbook — tutoriels de bout en bout (RAG, agents, recherche)

• deepset-ai/haystack sur GitHub — source, issues, releases

• Intégrations Haystack — liste complète des magasins de vecteurs, LLMs et outils supportés

• Ollama sur Clore.ai — associer Haystack avec Ollama pour l'inférence locale de LLM

• vLLM sur Clore.ai — backend de service LLM à haut débit pour Haystack

• Guide de comparaison GPU — choisissez le GPU Clore.ai adapté à votre charge

• CLORE.AI Marketplace — louer des serveurs GPU