Sur cette page : fractures fréquentes · table installation & passerelle · câblage reproductible · paramètres réutilisables · FAQ & périmètre
Ce guide n’est pas la fiche LiteLLM Proxy derrière OpenClaw (routage multi-modèles amont) ni le playbook nœuds d’outils LangGraph (graphe avec checkpoints). Il reste dans les pipelines Python Haystack, le DocumentStore et les composants séquentiels, tout en réutilisant le contrat passerelle : Bearer fichier, corrélation et moindre privilège. Pour les quotas RAG locaux et les embeddings, croisez la matrice chunk / embedding ; pour l’arbitrage coût global, la matrice multi-modèles et la télémétrie GenAI complètent le tableau de bord.
Où la chaîne casse sans garde-fous
1. JSON d’outil flou. Les agents émettent des arguments peu typés ; sans validation JSON Schema, les requêtes mal formées atteignent la passerelle, consomment des jetons et salissent les journaux d’audit.
2. Queue vectorielle lente. Une requête sur index saturé dépasse le budget interactif ; sans échéance ni fuse, tout le pipeline attend et l’utilisateur impute la faute au modèle.
3. Tempête de retries. Copier une politique HTTP générique sur le retriever répète un travail coûteux : il faut des gabarits distincts pour les appels passerelle et pour la recherche documentaire.
Table installation & passerelle (mémo opérable)
| Couche | Installer ou exécuter | Notes Haystack 2.x |
|---|---|---|
| Python | python -m venv .venv puis pip install haystack-ai et dépendances embedder / client vectoriel. |
Épingler requirements.txt ; placer les modèles d’embedding sur disque pour éviter les téléchargements à chaud. |
| Magasin documentaire | Dev : magasin embarqué ou fichier ; préprod : conteneur ou TCP loopback sur le même hôte. | Persister les volumes sur le Mac distant pour survivre aux reboot ; noter les chemins dans le runbook. |
| Passerelle OpenClaw | openclaw gateway listen sur 127.0.0.1:PORT avec --token-file issu du tableau de bord. |
Outils uniquement ; accès depuis le portable via tunnel SSH. Réutiliser Authorization et X-Correlation-Id sur tous les composants. |
| Santé | openclaw doctor --json ; curl authentifié sur /health. |
Aligner les sondes sur le démarrage du pipeline pour rejeter jetons ou ports avant d’enfiler des documents. |
Câblage reproductible en six gestes
1. Figer l’arborescence. Répertoires schemas/tools/, pipelines/, tokens/ ignorés par Git ; noter si le pipeline est async ou sync pour choisir la bonne primitive de timeout.
2. Lier les outils à OpenClaw. Client HTTP mince vers http://127.0.0.1:PORT, Bearer lu depuis fichier d’environnement, X-Correlation-Id depuis les métadonnées Haystack ou UUID par requête.
3. Valider avec JSON Schema. Avant tout POST, jsonschema.validate ou modèle Pydantic aligné sur le schéma versionné du dashboard ; erreur structurée locale sans toucher la passerelle.
4. Timeout retriever et fuse. Encapsuler l’appel avec asyncio.wait_for ou deadline threadée ; compter les dépassements consécutifs ; après deux franchissements dans une fenêtre glissante, retrieval_skipped=true, zéro document, motif court pour le générateur.
5. Gabarit retry sur la passerelle seule. Exponentiel avec jitter, trois tentatives max, liste explicite pour 429 et erreurs de connectivité, aucun retry automatique sur 401 ; pas de boucle retriever tant que le fuse est ouvert — attendre le refroidissement.
6. Résumés d’échec remontés. Cartographier erreurs HTTP et événements fuse vers un JSON : stage, code, correlation_id, schema_id optionnel, hint ; transmettre au composant de réponse pour avouer une dégradation contrôlée plutôt que d’halluciner des sources.
Journaliser chaque enveloppe à côté des identifiants d’exécution Haystack afin que le support relie journaux passerelle et latences retrieval. Lorsque le fuse se referme, émettre une ligne info unique pour signaler la reprise sans changement silencieux d’état.
# Esquisse : valider puis appeler (conceptuel)
# jsonschema.validate(instance=payload, schema=TOOL_SCHEMA)
# resp = session.post(gateway_url, json=payload, timeout=(2, 8))
# retries uniquement dans gateway_session_retry_policy, pas autour du vector searchParamètres « copier-coller » pour runbooks
- SLA retriever : 450 ms en dev, 900 ms si index froid ; fuse après deux dépassements consécutifs.
- HTTP outils passerelle : connect 2 s, read 8 s, base backoff 250 ms avec jitter plein.
- Clés enveloppe :
stage,code,correlation_id,hint; jamais de prompts ni corps de documents bruts.
FAQ : frontières de pile
Haystack doit-il parler à LiteLLM directement ? Non pour ce guide : gardez LiteLLM dans la fiche proxy multi-modèles ; ici l’accent reste composants Haystack plus OpenClaw pour les outils gouvernés.
Quand préférer LangGraph ? Si vous avez besoin de checkpoints natifs et d’agents ramifiés, suivez le guide LangGraph ; Haystack excelle quand le RAG reste linéaire et testable.
Inférence sans RAG ? Pour du trafic « modèle seul » compatible OpenAI, voir vLLM façon OpenAI ; réservez schémas et fuse aux charges riches en documents.
Pages publiques sans connexion : comparez les paliers sur la page tarifs, parcourez les SKU sur la page d’achat, puis le centre d’aide et l’index du blog technique.