Haystack : guide complet pour agents IA

Introduction

Haystack est un framework open-source développé par deepset pour construire des applications NLP avancées : pipelines de recherche documentaire, systèmes RAG (Retrieval-Augmented Generation) et agents IA capables de raisonner sur des corpus de données. Contrairement aux frameworks généralistes comme LangChain, Haystack adopte une approche pipeline-first : chaque flux de traitement est modélisé comme un graphe orienté de composants réutilisables. Ce guide vous explique l'architecture de Haystack, ses cas d'usage, et comment l'utiliser en Python pour construire vos premiers pipelines intelligents.

---

Résumé rapide

• Créé par : deepset (startup allemande spécialisée NLP)
• Approche : pipeline-first — les flux de données sont des graphes de composants
• Points forts : RAG, recherche documentaire, Q&A sur corpus, agents IA
• Langage : Python (3.9+)
• Licence : Apache 2.0 (open-source)
• Intégrations : OpenAI, HuggingFace, Elasticsearch, Weaviate, Pinecone, Chroma, et bien d'autres

---

Qu'est-ce que Haystack ?

Origine et équipe

Haystack a été lancé en 2020 par deepset, une startup berlinoise dont la mission est de rendre les technologies NLP accessibles aux entreprises. Le framework est né d'un constat simple : construire un moteur de questions-réponses sur des documents internes nécessite d'assembler de nombreuses briques (chargement, découpage, embedding, indexation, retrieval, génération) de façon cohérente et maintenable.

Philosophie pipeline-first

La grande originalité de Haystack réside dans sa vision déclarative du traitement de l'information. Plutôt que d'écrire du code procédural qui enchaîne des appels de fonctions, vous définissez un pipeline : un graphe orienté acyclique (DAG) où chaque nœud est un composant (un DocumentStore, un Retriever, un Generator, etc.) et chaque arête représente le flux de données entre ces composants.

Cette approche offre plusieurs avantages concrets :

• Lisibilité : le pipeline documente visuellement l'architecture de votre application
• Réutilisabilité : chaque composant est indépendant, testable séparément et interchangeable
• Débogage : il est facile d'inspecter les sorties à chaque étape
• Sérialisation : les pipelines peuvent être exportés en YAML et rechargés sans code

Haystack v1 vs Haystack v2

La version 2 (sortie en 2024) est une réécriture majeure. Elle unifie l'API, simplifie la création de composants personnalisés via des décorateurs Python, et améliore la gestion des types de données entre nœuds. Ce guide couvre Haystack v2.

Écosystème

Haystack s'intègre nativement avec les principaux fournisseurs de LLM (OpenAI, Anthropic, Cohere, HuggingFace) et les bases de données vectorielles les plus répandues (Elasticsearch, OpenSearch, Weaviate, Pinecone, Chroma, Qdrant). La communauté publie également des intégrations tierces (haystack-ai sur PyPI) qui étendent encore l'écosystème.

---

Architecture, composants et agents

Les briques fondamentales

Un pipeline Haystack v2 est composé de composants (Component). Chaque composant est une classe Python décorée avec @component qui déclare ses entrées et sorties via des annotations de type. Les principaux types de composants sont :

Composant	Rôle
DocumentStore	Stockage et indexation des documents
Retriever	Récupération des documents pertinents
Embedder	Calcul des embeddings (texte → vecteur)
Generator	Appel au LLM pour générer une réponse
PromptBuilder	Construction dynamique du prompt
DocumentWriter	Écriture des documents dans le store

Créer un pipeline simple

Voici un exemple minimal d'un pipeline de questions-réponses :

from haystack import Pipeline
from haystack.components.builders import PromptBuilder
from haystack.components.generators import OpenAIGenerator
from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack import Document

# 1. Préparer le document store
store = InMemoryDocumentStore()
store.write_documents([
    Document(content="LangGraph est un framework pour agents IA basé sur LangChain."),
    Document(content="Haystack est spécialisé dans le NLP et le RAG."),
    Document(content="CrewAI permet de créer des équipes d'agents autonomes."),
])

# 2. Définir le template de prompt
template = """
Contexte :
{% for doc in documents %}
  {{ doc.content }}
{% endfor %}

Question : {{ question }}
Réponse :
"""

# 3. Assembler le pipeline
pipe = Pipeline()
pipe.add_component("retriever", InMemoryBM25Retriever(document_store=store))
pipe.add_component("prompt_builder", PromptBuilder(template=template))
pipe.add_component("llm", OpenAIGenerator(model="gpt-4o-mini"))

pipe.connect("retriever", "prompt_builder.documents")
pipe.connect("prompt_builder", "llm")

# 4. Exécuter
result = pipe.run({
    "retriever": {"query": "Quel framework est spécialisé en RAG ?"},
    "prompt_builder": {"question": "Quel framework est spécialisé en RAG ?"}
})

print(result["llm"]["replies"][0])

Haystack et les agents IA

Haystack v2 introduit un support natif des agents IA via le composant Agent. Un agent Haystack peut utiliser des outils (Tool) pour interagir avec son environnement : appeler une API, interroger une base de données, exécuter du code Python, etc.

from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.tools import Tool

def rechercher_docs(query: str) -> str:
    """Recherche dans la base documentaire."""
    # Logique de recherche ici
    return f"Résultats pour : {query}"

tool = Tool(
    name="rechercher_docs",
    description="Recherche des informations dans la base de documents.",
    function=rechercher_docs,
    parameters={
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"]
    }
)

agent = Agent(
    chat_generator=OpenAIChatGenerator(model="gpt-4o"),
    tools=[tool],
    system_prompt="Tu es un assistant expert en frameworks IA. Utilise l'outil de recherche si nécessaire."
)

result = agent.run(messages=[{"role": "user", "content": "Quels frameworks supportent le RAG ?"}])
print(result["messages"][-1].content)

Comparaison avec LangChain et LangGraph

Si vous venez de LangChain, la différence principale est conceptuelle. LangChain favorise une composition impérative (vous chaînez des objets via le pipe operator |), tandis que Haystack impose une définition explicite du graphe. LangGraph, lui, est optimisé pour les workflows multi-agents avec gestion d'état — Haystack reste plus adapté aux pipelines de traitement documentaire.

Critère	Haystack	LangChain	LangGraph
Approche	Pipeline DAG	Chaînes impératives	Graphe d'état
Point fort	RAG / NLP	Polyvalence	Multi-agents
Courbe d'apprentissage	Modérée	Douce	Élevée
Sérialisation YAML	Native	Partielle	Non

Pour une comparaison complète, consultez le comparatif des meilleurs frameworks agents IA.

Quand choisir Haystack ?

Haystack est le meilleur choix quand :

• Votre projet est centré sur la recherche documentaire : Q&A sur PDF, contrats, documentation technique
• Vous avez besoin de RAG production-ready : Haystack inclut des composants optimisés pour les pipelines hybrides (dense + sparse retrieval)
• Vous voulez sérialiser vos pipelines en YAML pour les versionner et les déployer via CI/CD
• Votre équipe est familière avec le paradigme dataflow (type Apache Beam ou Airflow)

En revanche, si vous construisez des workflows multi-agents complexes avec coordination entre agents, LangGraph ou AutoGen seront plus adaptés. Explorez également les outils pour agents IA compatibles avec Haystack pour enrichir vos pipelines.

---

Exemple concret : pipeline RAG complet

Voici un pipeline RAG complet couvrant les quatre étapes clés : ingestion, embedding, retrieval et génération.

from haystack import Pipeline, Document
from haystack.components.converters import TextFileToDocument
from haystack.components.preprocessors import DocumentSplitter
from haystack.components.embedders import OpenAIDocumentEmbedder, OpenAITextEmbedder
from haystack.components.writers import DocumentWriter
from haystack.components.retrievers import InMemoryEmbeddingRetriever
from haystack.components.builders import PromptBuilder
from haystack.components.generators import OpenAIGenerator
from haystack.document_stores.in_memory import InMemoryDocumentStore

store = InMemoryDocumentStore()

# --- Pipeline d'indexation ---
indexing = Pipeline()
indexing.add_component("splitter", DocumentSplitter(split_by="sentence", split_length=5))
indexing.add_component("embedder", OpenAIDocumentEmbedder(model="text-embedding-3-small"))
indexing.add_component("writer", DocumentWriter(document_store=store))

indexing.connect("splitter", "embedder")
indexing.connect("embedder", "writer")

# Indexer des documents
docs = [
    Document(content="Haystack est développé par deepset depuis 2020."),
    Document(content="La version 2 de Haystack introduit une API unifiée pour les composants."),
    Document(content="Haystack supporte Elasticsearch, Weaviate, Pinecone et Chroma."),
]
indexing.run({"splitter": {"documents": docs}})

# --- Pipeline de requête ---
template = """
Réponds à la question en te basant uniquement sur le contexte suivant.

Contexte :
{% for doc in documents %}
  {{ doc.content }}
{% endfor %}

Question : {{ question }}
"""

querying = Pipeline()
querying.add_component("embedder", OpenAITextEmbedder(model="text-embedding-3-small"))
querying.add_component("retriever", InMemoryEmbeddingRetriever(document_store=store, top_k=3))
querying.add_component("prompt_builder", PromptBuilder(template=template))
querying.add_component("llm", OpenAIGenerator(model="gpt-4o-mini"))

querying.connect("embedder.embedding", "retriever.query_embedding")
querying.connect("retriever", "prompt_builder.documents")
querying.connect("prompt_builder", "llm")

# Interroger
question = "Depuis quand Haystack existe-t-il ?"
result = querying.run({
    "embedder": {"text": question},
    "prompt_builder": {"question": question}
})

print(result["llm"]["replies"][0])
# → "Haystack est développé par deepset depuis 2020."

Ce pipeline sépare clairement la phase d'indexation (offline, exécutée une seule fois) de la phase de requête (online, exécutée à chaque demande utilisateur), ce qui est la bonne architecture pour un système RAG en production.

---

Bonnes pratiques

Séparez indexation et requête : ne mélangez jamais les deux dans le même pipeline. L'indexation est un processus batch ; la requête doit être rapide et sans effets de bord.

Utilisez la sérialisation YAML : exportez vos pipelines avec pipeline.to_dict() et stockez-les dans votre dépôt Git. Cela facilite le versionnement et les revues de code.

Chunking adaptatif : le DocumentSplitter offre plusieurs stratégies (word, sentence, passage). Testez différentes tailles de chunks — 256 à 512 tokens est souvent un bon point de départ pour le RAG.

Retrieval hybride : combinez un InMemoryEmbeddingRetriever (dense) avec un InMemoryBM25Retriever (sparse) via un DocumentJoiner pour améliorer le rappel sur des requêtes courtes ou avec des termes rares.

Gérez vos clés API via les variables d'environnement : Haystack lit automatiquement OPENAI_API_KEY, COHERE_API_KEY, etc. Ne les codez jamais en dur dans vos scripts.

Testez chaque composant isolément avant d'assembler le pipeline. La nature modulaire de Haystack le rend particulièrement adapté aux tests unitaires.

---

Questions fréquentes

Haystack est-il adapté à la production ? Oui. deepset utilise Haystack en production chez ses clients enterprise et propose deepset Cloud comme offre managée. Le framework est stable et activement maintenu, avec des releases régulières.

Quelle est la différence entre Haystack v1 et v2 ? Haystack v2 est une réécriture complète avec une API unifiée. Les composants v1 ne sont pas compatibles directement avec v2. La migration nécessite d'adapter les définitions de composants au nouveau décorateur @component et au système de connexions explicites.

Peut-on utiliser Haystack sans OpenAI ? Absolument. Haystack supporte HuggingFace (modèles locaux via transformers), Ollama (inférence locale), Cohere, Anthropic et de nombreux autres fournisseurs. C'est l'un de ses points forts pour les projets nécessitant la souveraineté des données.

Haystack gère-t-il plusieurs agents en parallèle ? Le composant Agent gère un agent unique. Pour des architectures multi-agents, Haystack peut être combiné avec d'autres frameworks ou vous pouvez orchestrer plusieurs pipelines depuis votre code applicatif. Les workflows multi-agents complexes restent le domaine de prédilection de LangGraph.

Comment déployer un pipeline Haystack en API REST ? Haystack s'intègre facilement avec FastAPI. Il suffit de charger votre pipeline au démarrage de l'application et d'exposer un endpoint qui appelle pipeline.run() avec les paramètres de la requête HTTP.

---

Articles liés

Pour approfondir votre compréhension de l'écosystème des frameworks agents IA, Haystack s'inscrit parmi un ensemble d'outils complémentaires. Si vous débutez, commencez par notre panorama des frameworks agents IA pour situer Haystack dans le paysage global. Pour choisir entre Haystack, LangChain, LangGraph ou CrewAI selon votre cas d'usage, consultez le comparatif des meilleurs frameworks agents IA.

• Panorama des frameworks agents IA
• LangChain : guide complet
• Comparatif : quel framework choisir ?
• Comprendre les agents IA
• Outils pour agents IA