Une application qui répond à des questions à partir de tes propres documents comporte plusieurs étapes : transformer la question en vecteur, trouver des fragments, les ordonner, construire un prompt, appeler le modèle. Écrite directement, c'est une fonction de cent lignes où changer une étape demande de lire le tout.
Haystack découpe cela en composants reliés dans un graphe. Chaque étape est sa propre classe avec des entrées et sorties déclarées, et les connexions entre elles sont énoncées explicitement. L'effet est que remplacer le modèle d'embedding ou ajouter un filtre touche un seul endroit plutôt que toute la fonction.
Composant et pipeline
Un composant est une classe décorée qui déclare des types de sortie, avec une méthode qui fait le travail.
pip install haystack-ai sentence-transformers-haystackfrom haystack import Pipeline
from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersTextEmbedder
from haystack.components.builders import ChatPromptBuilder
from haystack.components.generators.chat import OpenAIChatGenerator
pipeline = Pipeline()
pipeline.add_component("embedder", SentenceTransformersTextEmbedder())
pipeline.add_component("retriever", retriever)
pipeline.add_component("prompt", ChatPromptBuilder(template=template))
pipeline.add_component("model", OpenAIChatGenerator(model="gpt-5-mini"))
pipeline.connect("embedder.embedding", "retriever.query_embedding")
pipeline.connect("retriever.documents", "prompt.documents")
pipeline.connect("prompt.prompt", "model.messages")
result = pipeline.run({"embedder": {"text": "how do I download an invoice copy"}})Une chose dans cet exemple a changé avec la troisième version, de juillet 2026. Les composants construits sur sentence-transformers sont sortis du cœur vers un paquet séparé, avec trente autres, donc ils demandent maintenant une installation séparée et un autre chemin d'import. Le code écrit pour la deuxième version échoue exactement là, avec une erreur de module manquant.
Les connexions sont explicites et c'est le cœur de cette approche. Tu vois ce qui alimente quoi, et brancher une sortie sur une entrée d'un type incompatible échoue à la construction du pipeline plutôt qu'à la première exécution.
Cela distingue le framework des bibliothèques où le flux de données est implicite et découle de l'ordre des appels. Là, la lisibilité dépend de la discipline de l'auteur ; ici, elle découle de la structure.
Le prix de cette explicité se voit tout de suite : plus de lignes pour le cas le plus simple. Sur un pipeline de trois étapes, une simple fonction serait plus courte, et l'avantage n'apparaît qu'à dix.
Branches et boucles
La deuxième version du framework a ajouté la prise en charge de graphes avec des branches et des cycles, ce qui élargit ce qu'on peut exprimer.
Une branche dirige une requête sur un chemin différent selon son type. Une question de documentation va à la recherche, une question sur l'état d'une commande à une interface de programmation, et une question hors périmètre à un refus avant que quoi que ce soit de coûteux ne s'exécute.
Un cycle répète une étape jusqu'à ce qu'une condition soit remplie. L'usage typique affine une réponse qui a échoué à un contrôle : le modèle génère, un composant d'évaluation vérifie, et en cas d'échec le prompt retourne au modèle avec une note sur ce qui n'allait pas.
Fais attention à un point ici. Un cycle sans plafond d'itérations peut tourner indéfiniment, brûlant des tokens sans jamais finir. Le plafond se fixe à la définition et relève du bon sens plutôt que d'une option.
Configuration dans un fichier
Un pipeline se sérialise dans un fichier et se charge depuis un fichier, ce qui a des conséquences au-delà de la commodité.
components:
embedder:
type: haystack_integrations.components.embedders.sentence_transformers.sentence_transformers_text_embedder.SentenceTransformersTextEmbedder
init_parameters:
model: intfloat/multilingual-e5-base
model:
type: haystack.components.generators.chat.OpenAIChatGenerator
init_parameters:
model: gpt-5-mini
connections:
- sender: embedder.embedding
receiver: retriever.query_embeddingCela te permet de changer un modèle ou des paramètres sans déployer une nouvelle version de l'application, ce qui aide pendant le réglage. Cela te permet aussi de garder des variantes de pipeline différentes par environnement dans des fichiers plutôt que dans des conditions dispersées dans le code.
Le piège est le même que pour toute configuration hors du code. Le comportement du système dépend alors d'un fichier dont les changements ne passent par aucune relecture et ne s'accompagnent d'aucun test. Un compromis raisonnable garde ces fichiers dans le dépôt et traite leurs changements exactement comme des changements de code.
Agents
Les versions récentes ajoutent un composant agent qui s'insère dans un pipeline à côté des autres. Cela signifie qu'un même flux peut contenir une étape déterministe et une étape où le modèle décide lui-même de l'ordre des actions.
Cet arrangement est pratique, car il correspond à l'allure de la plupart des applications. Récupérer des fragments, filtrer selon les permissions et formater une réponse doivent se faire à l'identique à chaque fois. Décider s'il faut recourir à un outil supplémentaire, et lequel, demande un jugement sur le contenu.
Tout confier au modèle gaspillerait de l'argent, car certaines étapes n'ont besoin d'aucun jugement et chaque appel coûte. Tout écrire comme un pipeline déterministe ne marchera pas, car certaines décisions dépendent du contenu de la requête.
La règle pratique : les étapes qui doivent s'exécuter à l'identique restent des composants, et un agent va là où un jugement est nécessaire. C'est le même principe qu'avec LangGraph et d'autres solutions fondées sur des graphes.
Indexer des documents
Le pipeline de réponse n'est que la moitié du système. L'autre moitié prépare les documents, et elle décide de la qualité plus que tout ce qui se trouve du côté de la réponse.
indexing = Pipeline()
indexing.add_component("converter", PyPDFToDocument())
indexing.add_component("cleaner", DocumentCleaner())
indexing.add_component("splitter", DocumentSplitter(split_by="sentence", split_length=5))
indexing.add_component("embedder", SentenceTransformersDocumentEmbedder())
indexing.add_component("writer", DocumentWriter(document_store=store))
indexing.connect("converter", "cleaner")
indexing.connect("cleaner", "splitter")
indexing.connect("splitter", "embedder")
indexing.connect("embedder", "writer")L'étape de nettoyage retire les en-têtes et pieds de page répétés ainsi que les lignes vides. Cela paraît mineur, et sur des documents qui portent des numéros de page dans chaque fragment, cela peut baisser nettement la précision, car le modèle d'embedding traite ce bruit comme une partie du contenu.
L'étape de découpage compte le plus et mérite d'être expérimentée. Le découpage par phrases avec chevauchement convient à la prose continue, tandis que la documentation technique s'en sort mieux découpée par titres, car une section est l'unité naturelle d'une réponse.
Consigne le titre de la section et l'URL de la source dans les métadonnées. Sans eux, une réponse ne peut pas indiquer son origine et un utilisateur ne peut pas la vérifier.
La dernière chose concerne les identifiants. Construits à partir de l'URL de la source et du numéro du fragment, ils permettent de réindexer un document sans créer de doublons, ce qui, pour une documentation qui change chaque semaine, est une condition et non un confort.
Évaluation de la qualité
Le framework fournit des composants d'évaluation qui se branchent dans un pipeline comme n'importe quel autre.
Les mesures sont celles traitées dans l'article sur Ragas : si une réponse repose sur le contexte, si les fragments récupérés sont pertinents, si la réponse traite la question. Les brancher dans le pipeline te permet de mesurer ces choses sur un ensemble de cas après chaque changement.
La valeur de cet arrangement est que l'évaluation utilise le même pipeline que la production. Avec un outil séparé, il y a toujours un risque de mesurer autre chose que ce qui tourne réellement, parce que la configuration a dérivé.
L'approche opposée note de l'extérieur, sans brancher de composants dans le pipeline. TruLens instrumente l'application et calcule la même triade de mesures sous licence MIT, ce qui peut être décisif, car certains outils de cette catégorie portent des licences qui restreignent la redistribution commerciale. La bibliothèque est issue de Truera, racheté par Snowflake, donc beaucoup d'exemples de la documentation supposent les services de cet éditeur, bien qu'elle s'exécute en local et n'exige aucun compte.
Fais pourtant attention au coût. L'évaluation par un modèle juge implique des appels supplémentaires, donc un ensemble complet à chaque changement de code est financièrement irréaliste. Une répartition raisonnable lance souvent un petit ensemble et l'ensemble complet avant une version.
Composants personnalisés
L'ensemble intégré couvre les étapes typiques, et ce qui est propre à ton domaine, tu l'écris toi-même. C'est plus simple qu'il n'y paraît.
from haystack import component
from typing import List
@component
class PermissionFilter:
@component.output_types(documents=List[Document])
def run(self, documents: List[Document], user_id: str):
allowed = [d for d in documents if d.meta["owner"] == user_id]
return {"documents": allowed}Un décorateur et une déclaration de type de sortie sont tout ce dont un composant a besoin pour se brancher dans un pipeline comme n'importe quel autre. La vérification de types à la construction le couvre exactement comme elle couvre les composants intégrés.
Cet exemple précis mérite réflexion quel que soit le framework. Filtrer par propriétaire après la récupération plutôt que dans la requête à la base de données est plus lent et moins sûr, car la base renvoie alors les fragments des autres et le tamisage se fait plus tard. Le filtre appartient à la requête, et un composant comme celui ci-dessus est une garde au cas où quelqu'un l'omettrait.
Le deuxième usage typique couvre les transformations propres au format de tes documents : extraire des champs d'une structure, normaliser des noms, attacher du contexte issu d'un système externe. De telles étapes ont rarement des versions toutes prêtes, car elles dépendent de l'allure de tes données.
Le troisième est l'intégration d'un service sans composant disponible. Envelopper un appel d'interface dans un composant prend une douzaine de lignes, et le gain est que tu le manipules exactement comme le reste du pipeline.
Haystack face aux alternatives
| Option | Point fort | Point faible | À choisir quand |
|---|---|---|---|
| Haystack | Connexions explicites, vérification de types, configuration en fichier | Plus de code sur les cas simples | Recherche de documents en production |
| LangChain | Plus grand ensemble d'intégrations, démarrage rapide | Plus d'abstraction, moins d'explicité | Projet qui combine beaucoup de sources |
| LlamaIndex | Accent sur l'indexation de documents | Couche d'agents moins élaborée | Travail avec de grands ensembles de documents |
| Ton propre code | Contrôle total, aucune abstraction | Tu écris et maintiens tout | Flux simple en deux étapes |
La dernière ligne est injustement négligée. Un flux composé d'un appel d'embedding, d'une requête à la base et d'un appel au modèle, c'est trente lignes que tout le monde peut lire. Un framework commence à être rentable avec les branches, le remplacement de composants et un besoin d'évaluation.
Choisir parmi les trois premières lignes dépend de ce que tu valorises. Les connexions explicites et la vérification de types à la construction sont l'avantage de la première, et comptent sur un pipeline que quelqu'un lira dans six mois. Le nombre d'intégrations toutes prêtes est celui de la deuxième, et compte quand on connecte beaucoup de sources.
Il vaut la peine de nommer ce qui se perd dans de telles comparaisons. La qualité d'un système qui répond à partir de documents se décide par la manière dont les documents sont découpés, le modèle d'embedding choisi et l'existence de filtres, pas par le framework. Ces trois éléments passent d'une bibliothèque à l'autre sans changement, donc le travail qu'on y consacre ne périt pas lors d'une migration, alors que le travail consacré à apprendre un framework, si.
La conclusion pratique est de commencer par l'option la plus simple et de mesurer la pertinence sur tes propres questions. Ce n'est qu'une fois que tu sais où se situe le problème qu'il faut se tourner vers un outil qui donne plus de contrôle, car autrement tu ajoutes de la complexité sans savoir si cela corrige quoi que ce soit.
Déploiement en production
Un pipeline lancé depuis un script convient aux essais. Un déploiement qui sert du trafic demande plusieurs décisions.
La première concerne le démarrage. Un pipeline créé à chaque requête charge le modèle d'embedding à chaque fois, ce qui, avec un modèle local, représente plusieurs secondes. Un pipeline construit une fois au démarrage de l'application et conservé supprime ce coût.
La deuxième est la concurrence. Les composants qui utilisent un modèle local ne gèrent pas toujours bien de nombreuses requêtes simultanées, donc à plus fort trafic la récupération et la génération méritent d'être séparées en services distincts, avec le modèle hébergé sur un serveur conçu pour la concurrence.
La troisième est la gestion des erreurs. Une base vectorielle indisponible ou une limite de débit chez un fournisseur de modèles casse le pipeline, donc décide de ce que voit l'utilisateur : un message sur un problème temporaire, ou une réponse sans contexte clairement marquée comme incomplète.
La quatrième est les traces. Un pipeline de six composants est transparent à la construction et opaque pendant le diagnostic, sauf si tu enregistres ce qui est passé par quelle étape. Brancher un outil d'observabilité comme Langfuse transforme « pourquoi cette réponse est mauvaise » d'une conjecture en vérification.
Erreurs courantes
La première est de construire un pipeline pour une tâche qui tient en un appel. Trois composants pour quelque chose qui tient en dix lignes ajoutent de la complexité sans bénéfice.
La deuxième est un cycle sans plafond d'itérations. Une boucle qui affine une réponse jusqu'à ce qu'elle satisfasse peut ne jamais satisfaire, et la consommation de tokens croît linéairement avec les tentatives.
La troisième est une configuration dans un fichier hors du dépôt. Le comportement du système dépend alors de quelque chose que personne ne relit et qui n'a pas d'historique de changements.
La quatrième est de sauter l'évaluation. Changer le modèle d'embedding ou le template de prompt améliore généralement certains cas et en casse d'autres, et sans jeu de test seule la première moitié est visible.
La cinquième est de ne mesurer que la qualité de la réponse. Sans métriques de récupération, tu ne peux pas savoir s'il faut corriger le prompt ou le découpage des documents, et ce sont des travaux complètement différents.
La sixième est de considérer les composants intégrés comme la seule option. Un composant personnalisé est une classe décorée avec deux méthodes, donc ajouter une étape propre à ton domaine représente un quart d'heure de travail.
FAQ
En quoi Haystack diffère-t-il de LangChain ?
Il met l'accent sur l'explicité : les connexions entre composants sont déclarées directement, et les incompatibilités de types apparaissent à la construction du pipeline. LangChain possède bien plus d'intégrations toutes prêtes et démarre plus vite, au prix de plus d'abstraction à apprendre.
Haystack ne sert-il qu'à la recherche ?
Non, même si c'est son point le plus fort. Les versions récentes ont un composant agent qui s'insère dans un pipeline à côté des autres, donc un même flux peut combiner des étapes déterministes avec des étapes où le modèle décide lui-même.
La configuration doit-elle vivre dans un fichier ?
Non, un pipeline peut être construit entièrement dans le code. Un fichier aide pour le réglage sans déploiement et pour des variantes par environnement, et il a sa place dans le dépôt pour que les changements passent par une relecture.
Comment fonctionne-t-il avec les bases vectorielles ?
Via des composants de document store disponibles pour les options populaires, dont Qdrant et Chroma. Changer de base revient alors à remplacer un composant sans toucher au reste du pipeline.
Quand ne vaut-il pas la peine d'y recourir ?
Sur un flux de deux ou trois étapes sans branches. Trente lignes de code sont alors plus claires qu'un pipeline de composants, et le framework commence à être rentable avec les branches et le besoin de remplacer des parties sans perturber le reste.
La documentation se trouve sur le site du projet, et le code source dans le dépôt GitHub.