> 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-fr/plateformes-et-agents-ia/haystack.md).

# Framework IA Haystack

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.

{% hint style="success" %}
Tous les exemples s'exécutent sur des serveurs GPU loués via le [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

{% hint style="info" %}
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](https://docs.haystack.deepset.ai/docs/migration).
{% endhint %}

## Aperçu

| Propriété                       | Détails                                                                           |
| ------------------------------- | --------------------------------------------------------------------------------- |
| **Projet**                      | [deepset-ai/haystack](https://github.com/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 |

{% hint style="info" %}
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.
{% endhint %}

### 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](https://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

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

```bash
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](https://github.com/deepset-ai/hayhooks) transforme automatiquement n'importe quel pipeline Haystack en une API REST :

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

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

### 5. Créez votre premier pipeline RAG

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

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

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

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

### Pipeline d'ingestion de documents

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

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

# 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 :

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

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

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

# 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 :

```bash
# É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 :

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

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

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

```bash
# 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](https://docs.haystack.deepset.ai/) — docs officielles v2
* [Hayhooks GitHub](https://github.com/deepset-ai/hayhooks) — exposition d'API REST pour les pipelines
* [Haystack Cookbook](https://haystack.deepset.ai/cookbook) — tutoriels de bout en bout (RAG, agents, recherche)
* [deepset-ai/haystack sur GitHub](https://github.com/deepset-ai/haystack) — source, issues, releases
* [Intégrations Haystack](https://haystack.deepset.ai/integrations) — liste complète des magasins de vecteurs, LLMs et outils supportés
* [Ollama sur Clore.ai](/guides/guides_v2-fr/modeles-de-langage/ollama.md) — associer Haystack avec Ollama pour l'inférence locale de LLM
* [vLLM sur Clore.ai](/guides/guides_v2-fr/modeles-de-langage/vllm.md) — backend de service LLM à haut débit pour Haystack
* [Guide de comparaison GPU](/guides/guides_v2-fr/prise-en-main/gpu-comparison.md) — choisissez le GPU Clore.ai adapté à votre charge
* [CLORE.AI Marketplace](https://clore.ai/marketplace) — louer des serveurs 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:

```
GET https://docs.clore.ai/guides/guides_v2-fr/plateformes-et-agents-ia/haystack.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.