Sur cette page : Dépendances et arborescence · Jetons passerelle et restrictions de sortie · Intégration QueryEngine au niveau code · Journaux et inspection doctor
Ce guide s’adresse aux développeurs RAG et agents qui indexent déjà avec LlamaIndex et doivent verrouiller la prod sur un hôte Apple Silicon loué. Il prolonge la matrice Workflows LlamaIndex et réemploie la discipline passerelle du playbook Haystack 2.x, mais reste dans l’arbre de composition QueryEngine et les surfaces Python d’outils. Pour une boucle agentique analogue côté validation JSON, rapprochez-vous du guide PydanticAI qui partage le même vocabulaire fuse et schémas.
Tensions récurrentes. 1. Le modèle propose des noms d’outils hors périmètre ; sans liste blanche appliquée avant le fil, l’audit perd du sens. 2. Les requêtes vectorielles explosent la queue de latence ; sans timeout ni disjoncteur, toute la réponse semble « lente à cause du LLM ». 3. Les erreurs silencieuses incitent à confabuler : il faut une enveloppe compacte que le ResponseSynthesizer lit explicitement.
Dépendances et arborescence
Sur le Mac distant, partez d’un dépôt propre : python -m venv .venv, figez llama-index-core et le client de magasin vectoriel, conservez les embeddings sur le même volume que l’index pour éviter les allers-retours WAN lors des démos. Réservez schemas/tools/ pour les JSON Schema versionnés, src/retrieval/ pour les retrievers décorés, tokens/ en 0600 ignoré par Git, et logs/jsonl/ pour les workers. Documentez dans un tableau unique les ports OpenClaw, reranker local et service d’embedding afin que l’équipe et la CI partagent la même vérité opérable.
Jetons passerelle et restrictions de sortie
Alignez-vous sur OpenClaw 2026.4.x : Node 22 LTS, CLI à jour, puis openclaw gateway listen lié à 127.0.0.1 avec --token-file issu du tableau de bord locataire. Depuis un portable, n’atteignez le port qu’à travers un tunnel SSH. Considérez le Bearer comme une capacité à privilèges minimaux : il n’autorise que les routes d’outils réellement enregistrées, jamais une sortie Internet générique depuis le processus Python.
Appliquez un refus par défaut : seuls la boucle passerelle et le socket base vectorielle sortent du cadre local ; tout HTTP à effets de bord depuis LlamaIndex transite par une classe GatewayToolClient qui injecte Authorization, X-Correlation-Id et vérifie la route contre la liste blanche commitée.
| Préoccupation | Couche passerelle OpenClaw | Couche LlamaIndex QueryEngine |
|---|---|---|
| Politique | Allowlist noms et routes, rotation Bearer, plafonds de taille. | Choix du retriever, filtres métadonnées, prompts de synthèse. |
| Timeouts | Connect et read HTTP pour les corps d’outils. | asyncio.wait_for autour des requêtes vectorielles ; compteur fuse. |
| Retries | Backoff borné sur 429 ou pannes réseau transitoires. |
Zéro ou une relance tant que le fuse est ouvert ; pas de boucle retrieval. |
| Forme d’échec | Codes HTTP et erreurs de validation passerelle. | Drapeaux retrieval_skipped et enveloppes lues par la synthèse. |
Intégration QueryEngine : étapes au niveau code
Enchaînez sept gestes ordonnés pour garder des diffs lisibles en revue.
1. Envelopper le retriever. Sous-classez ou décorez VectorIndexRetriever pour que chaque aretrieve passe sous asyncio.wait_for avec une échéance de l’ordre de 450 ms en développement et 900 ms lorsque l’index est chaud. Sur TimeoutError, renvoyez une liste de nœuds vide et retrieval_skipped=true.
2. Ajouter un compteur fuse. Agrégez les dépassements consécutifs par nom d’index ; après deux franchissements sur une fenêtre glissante de cinq minutes, ouvrez le fuse, ajoutez fuse_opened_at aux métadonnées et bloquez les nouvelles recherches jusqu’au refroidissement.
3. Centraliser le HTTP passerelle. Implémentez GatewayToolClient.post(nom, charge) qui lit URL de base et jeton depuis l’environnement, propage un identifiant de corrélation et rejette tout nom absent de l’allowlist versionnée avant l’envoi réseau.
4. Valider localement. Exécutez jsonschema.validate ou des modèles Pydantic alignés sur schemas/tools/*.json pour faire échouer vite les arguments mal typés sans consommer des tours modèle.
5. Enregistrer les outils LlamaIndex. N’exposez que des FunctionTool enveloppés vers le client passerelle ; ne laissez jamais une session httpx brute accessible au prompt.
6. Assembler le QueryEngine. Combinez retriever fusionné, outils et response_synthesizer dont le gabarit ou les callbacks lisent les métadonnées d’échec comme courte puce, pas comme JSON illisible.
7. Cartographier les erreurs. Traduisez échecs HTTP passerelle et ouvertures de fuse en objet stage, code, correlation_id, hint ; propagez via métadonnées de source_nodes ou dictionnaire parallèle consommé explicitement par l’étape de synthèse.
# Garde conceptuelle : jamais sauter la validation locale
# ALLOWED_TOOLS = {"search_ticket", "post_audit_log"}
# assert tool_name in ALLOWED_TOOLS
# jsonschema.validate(instance=payload, schema=load_schema(tool_name))
# async with asyncio.timeout(0.45): nodes = await retriever.aretrieve(q)Journaux et inspection doctor
Émettez une ligne JSONL par invocation QueryEngine avec identifiant de pipeline, corrélation, millisecondes retrieval, état du fuse et noms d’outils redactés. Faites tourner les fichiers quotidiennement sous logs/jsonl/ pour joindre syslog Mac et journaux passerelle sans extraire les prompts.
Après chaque bump de dépendance, lancez openclaw doctor --json et archivez la sortie près des notes de version. Dans les hooks de déploiement, appelez /health avec le Bearer de production ; échouez le déploiement si latence ou auth divergent de la préproduction.
Repères reproductibles pour runbooks
- Échéance retrieval : 450 ms en dev, 900 ms index chaud ; fuse après deux timeouts consécutifs.
- HTTP outils : connect 2 s, read 8 s ; backoff de base 250 ms avec jitter intégral ; aucun retry sur 401.
- Refroidissement fuse : laissez au moins 120 s avant une sonde retrieval pendant incident.
Lorsque vous passez du tunnel portable à un nœud flotte, colocalisez passerelle, index et embeddings compatibles MLX sur une machine Mac mini M4 afin que les identifiants de corrélation restent exploitables sous charge.
Pages publiques sans connexion : comparez les paliers sur les tarifs, parcourez les SKU sur achat, puis le centre d’aide et l’index du blog technique.