Framework IA Haystack

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

Haystack est le framework d'orchestration IA open source de deepset pour créer des applications LLM de niveau production. Avec plus de 18 k étoiles GitHub, il offre une architecture flexible basée sur des pipelines qui assemble 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 afin que vous puissiez vous concentrer sur la logique de l'application.

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

Tous les exemples s’exécutent sur des serveurs GPU loués via la place de marché CLORE.AI.

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

Aperçu

Propriété	Détails
Projet	deepset-ai/haystack
Licence	Apache 2.0
Étoiles GitHub	18 k+
Version	v2.x (haystack-ai)
Cas d'utilisation principal	RAG, recherche sémantique, questions-réponses sur documents, flux de travail d'agents
Prise en charge du GPU	Facultatif — requis pour les embeddings locaux / LLM locaux
Difficulté	Moyen
Exposition de l'API	Hayhooks (basé sur FastAPI, REST)
Intégrations clés	Ollama, OpenAI, Anthropic, HuggingFace, Elasticsearch, Pinecone, Weaviate, Qdrant

Ce que vous pouvez créer

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

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

• Traitement de documents — analyser des PDF, du HTML, des documents Word ; découper, nettoyer et indexer le contenu

• Flux de travail d'agents — raisonnement en plusieurs étapes avec utilisation d'outils (recherche web, calculatrices, API)

• Services d'API REST — exposer n'importe quel pipeline Haystack comme point de terminaison via Hayhooks

Exigences

Configuration matérielle requise

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.03–0.07/hr
Embeddings locaux + petit LLM (7B)	RTX 3090	24 Go	16 Go	50 Go	0,07–0,21 $/h
LLM local (13B–34B)	RTX 4090	24 Go	32 Go	80 Go	0,14–0,42 $/h
Grand LLM local (70B, quantifié)	A100 80 Go	80 Go	64 Go	150 Go	bare metal

Pour la plupart des cas d'utilisation RAG, un RTX 3090 à 0,07–0,21 $/h est le juste milieu — 24 Go de VRAM gèrent simultanément les embeddings sentence-transformers + un LLM local 7B–13B.

Prérequis logiciels

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

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

• Python 3.10+ (dans le conteneur)

• CUDA 11.8 ou 12.x

Démarrage rapide

1. Louez un serveur Clore.ai

Dans le Marketplace Clore.ai, filtrez selon :

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

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

• Image: nvidia/cuda:12.8.1-devel-ubuntu22.04 ou pytorch/pytorch:2.11.0-cuda12.8-cudnn9-runtime

Notez l'IP publique du serveur et le port SSH à partir de Mes commandes.

2. Connectez-vous et vérifiez 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 pilote, la version de CUDA

3. Construisez l'image Docker de Haystack

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

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

cat > Dockerfile << 'EOF'
FROM nvidia/cuda:12.8.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 comme version 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

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

4. Exécutez Haystack avec Hayhooks

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

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

# Exécuter Hayhooks avec accès au 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érifiez qu'il fonctionne
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 exposera comme point de terminaison :

cat > /workspace/haystack-pipelines/rag_pipeline.yml << 'EOF'
# Pipeline RAG utilisant Ollama pour le LLM + des 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étecte automatiquement et expose 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	Jeton Hugging Face pour les modèles à accès restreint	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 de cache pour les modèles HF	/workspace/hf-cache

Exécuter avec la 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")

# Lancer l'indexation
from pathlib import Path
indexing_pipeline.run({"converter": {"sources": list(Path("/data/documents").glob("*.pdf"))}})

print(f"Chunks de documents indexés : {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

Utilisation de bases de données vectorielles (production)

Pour les charges de production, remplacez le stockage en mémoire par une base de données vectorielle persistante :

# Lancer Qdrant en parallèle 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
# Utilisez ensuite 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 générer des embeddings pour 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"Périphérique utilisé : {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} Go")

# Créer l'encodeur
embedder = SentenceTransformersDocumentEmbedder(
    model="BAAI/bge-base-en-v1.5"
)
embedder.warm_up()

# Benchmark
docs = [Document(content=f"Document exemple {i} avec du contenu textuel.") for i in range(100)]

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

print(f"100 documents encodés en {elapsed:.2f}s ({100/elapsed:.0f} docs/s)")
EOF

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

2. Inférence locale de LLM (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="Répondez à cette 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": "Qu'est-ce que le 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. Associez avec Ollama (approche recommandée)

Pour la meilleure combinaison de simplicité et de performance, utilisez 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 : Récupérer un modèle de code/de conversation
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

Surveillez l'utilisation du GPU dans les deux conteneurs :

watch -n 2 nvidia-smi

Conseils et bonnes pratiques

Choisissez 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 maximale
nomic-ai/nomic-embed-text-v1	~1,5 Go	Rapide	Excellente	Documents longs

Conseils de conception de pipeline

• Découpez les documents judicieusement — des segments de 200 à 400 mots avec 10 à 15 % de chevauchement conviennent bien à la plupart des cas d'utilisation RAG

• Mettre en cache les embeddings — persistez votre magasin de documents sur disque ; la ré-indexation des embeddings est coûteuse

• Utilisez warm_up() — appelez component.warm_up() avant une 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 des métadonnées — utilisez le filtrage des métadonnées de Haystack pour délimiter la récupération (par ex. par date, source, catégorie)

Optimisation des coûts

# Utilisez une tarification de type spot sur Clore.ai — choisissez des serveurs avec un coût horaire plus bas
# Pour le développement/test : RTX 3060 (0,03–0,07 $/h) suffit pour l'embedding
# Pour l'embedding en production : RTX 3090 (0,07–0,21 $/h) — 24 Go gèrent de grands lots
# Pour LLM local + embedding : A100 40 Go ([bare metal](https://clore.ai/bare-metal)) — marge de manœuvre pour des utilisateurs simultanés

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

Sécuriser Hayhooks pour un accès externe

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

# Option 2 : ajouter une authentification de base via un proxy inverse 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é	Reconstruisez l'image Docker ; vérifiez pip install haystack-ai réussi
Mémoire CUDA insuffisante	Modèle d'embedding trop volumineux	Utilisez bge-small-en-v1.5 ou réduisez la taille du lot
Hayhooks renvoie une erreur 404 sur le pipeline	Fichier YAML introuvable	Vérifiez le montage du volume ; le fichier du pipeline doit se trouver dans /app/pipelines/
Embedding lent sur le CPU	GPU non détecté	Vérifiez --gpus all option ; vérifiez torch.cuda.is_available()
Connexion refusée par Ollama	Nom d'hôte incorrect	Utilisez --add-host=host.docker.internal:host-gateway; définissez l'URL sur http://host.docker.internal:11434
Le téléchargement depuis HuggingFace échoue	Jeton manquant ou limite de débit	Définissez HF_TOKEN variable d'environnement ; assurez-vous que le modèle n'est pas restreint
Erreur d'analyse du YAML du pipeline	Syntaxe invalide	Validez le YAML ; utilisez python3 -c "import yaml; yaml.safe_load(open('pipeline.yml'))"
Le conteneur se ferme immédiatement	Erreur de démarrage	Vérifiez docker logs haystack; assurez-vous que la commande CMD du Dockerfile est correcte
Le port 1416 n'est pas accessible de 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 journaux 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

Pour aller plus loin

• Documentation Haystack — documentation officielle v2

• GitHub de Hayhooks — diffusion d'API REST pour les pipelines

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

• deepset-ai/haystack sur GitHub — source, problèmes, versions

• Intégrations Haystack — liste complète des magasins vectoriels, des LLM et des outils pris en charge

• Ollama sur Clore.ai — associez Haystack à Ollama pour l'inférence locale des LLM

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

• Guide de comparaison des GPU — choisissez le bon GPU Clore.ai pour votre charge de travail

• la place de marché CLORE.AI — louez des serveurs GPU