Les services IA de DnC

RagRuntime

Bertrand Degoy — 2026-08-09T11:39:30Z

`RagRuntime` est un orchestrateur minimal, stateless, thread‑safe.
Il pilote le pipeline RAG complet, mais délègue toutes les opérations lourdes au daemon Pyro5.
Le design garantit une séparation stricte des responsabilités et une compatibilité totale avec n'importe quel backend d'indexation ou modèle de langage.

RagRuntime — Présentation

RagRuntime est un orchestrateur RAG client‑side.
Il ne contient aucun objet lourd (embedding, index, LLM).
Il délègue toutes les opérations coûteuses au daemon Pyro5.

Il implémente un pipeline strict :

condense_query → retrieve → rerank → synthesize → render → generate

Chaque étape est isolée, testable, et remplaçable.

1. Rôle général

RagRuntime :

normalise l'historique ;
reformule la question via le LLM du daemon ;
interroge le service rag.reader du daemon RAG pour récupérer les passages ;
applique un reranker local (optionnel) ;
construit un contexte RAG structuré selon le mode ;
rend ce contexte dans un format compact ;
génère la réponse finale via le LLM du daemon.

Il est LLM‑agnostique, index‑agnostique, embedding‑agnostique.

2. Structure interne

Composants principaux

condense_query() : réécriture de la question via llm.server.
retrieve() : appel Pyro5 vers rag.reader.
_apply_rerank() : reranker CPU local.
synthesize() : construction du contexte (tree, node, tool, condense).
render() : formatage compact du contexte.
generate() : génération finale via llm.server.

3. Modes de synthèse

Mode	Description
condense	concatène le texte brut
tree_summarize	résumé hiérarchique multi‑niveaux
node_summarize	résumé par chunk
tool	résumé compact pour ReAct

Voir : Les modes de synthèse

Les modes de synthèse

Bertrand Degoy — 2026-07-28T15:02:23Z

Le Moteur RAG de la v200 (RagRuntime) offre différents modes de synthèse des passages extraits de la documentation : "condense", "tree summarize", "node summarize, "tool".
Donnant des résultats très différents, il doivent être choisis en fonction de l'application et de la qualité de la documentation.
La pertinance du Reranker est mise en question.

Résumé de la problématique

Le mode condense produit des réponses plus pertinentes et plus “intelligentes” que les modes stricts (tree summarize, node summarize, tool), notamment lorsqu'il faut répondre à une question sans correspondance documentaire directe. La raison principale est que condense préserve davantage de matière textuelle et laisse au modèle une latitude d'inférence plus large, alors que les modes stricts réduisent fortement la richesse du contexte.

1. Différence de traitement du contexte

condense : concatène les passages et génère un résumé global.
- Préserve les redondances.
- Conserve les signaux faibles.
- Maintient les ambiguïtés utiles.
- Offre un espace d'inférence large.

De plus, ce mode est rapide et économique en token.

tree_summarize / node_summarize / tool : imposent une structure précoce.
- Compression agressive.
- Hiérarchisation ou segmentation.
- Normalisation du contenu.
- Réduction des co‑occurrences latentes.
- Perte d'informations implicites.

2. Impact sur les capacités du modèle

Les modèles modernes exploitent efficacement :

les corrélations faibles,
les ambiguïtés,
les patterns latents,
les fragments d'information dispersés.

Le mode condense leur fournit un contexte riche permettant :

l'inférence,
la reconstruction de sens,
la réponse indirecte à des questions non couvertes explicitement.

Les modes stricts limitent ces mécanismes en réduisant la matière disponible.

3. Cas d'usage des modes stricts

Les modes stricts restent adaptés lorsque :

le contexte est très volumineux (nécessité de structuration),
la tâche exige une réponse déterministe,
l'application impose une traçabilité stricte,
un agent ReAct doit consommer un format compact et non ambigu.

4. Conséquence architecturale

Le mode condense se comporte comme un pré‑RAG génératif :
il agrège et densifie le contexte sans le contraindre, ce qui maximise la capacité du modèle à produire une réponse pertinente même en absence de support documentaire direct.

Recommandation d'usage

Mode par défaut : condense
Contextes très longs : tree_summarize
Analyse par chunk : node_summarize
Agents ReAct : tool

Pertinence du reranker

L'effet du reranker dépend fortement du mode de post‑traitement utilisé.
Dans les modes stricts, il est souvent redondant ou contre‑productif.
Dans le mode condense, il peut être utile, mais pas toujours nécessaire, car ce mode exploite déjà la capacité du modèle à combiner des signaux faibles.

1. Interaction générale entre reranker et modes

Le reranker agit avant la phase de summarization.
Il modifie :

l'ordre des passages,
la sélection des passages (top‑k / top‑n),
la distribution des signaux faibles.

Son impact dépend donc de la manière dont le mode consomme les passages.

2. Effet par mode

Mode condense

Le modèle reçoit un bloc textuel riche.
Le reranker peut améliorer la pertinence en mettant les passages les plus utiles en tête.
Cependant, condense exploite aussi les signaux faibles et les co‑occurrences.
Un reranker trop strict peut réduire la diversité des passages et donc diminuer la capacité d'inférence.

Effet : utile mais non indispensable.
Risque : perte de matière latente si le reranker est trop agressif.

Mode tree_summarize

Ce mode structure le contenu en niveaux hiérarchiques.
Il dépend moins de l'ordre initial des passages.
Le reranker apporte peu de valeur, car la hiérarchie reconstruit déjà une importance relative.

Effet : faible.
Risque : compression excessive si le reranker filtre trop.

Mode node_summarize

Chaque passage est résumé individuellement.
L'ordre n'a presque aucune importance.
Le reranker n'améliore pas la qualité du résumé par passage.
Il peut même réduire la couverture documentaire.

Effet : marginal.
Risque : perte de diversité des chunks.

Mode tool

Format strict, compact, destiné aux agents.
Le reranker peut aider à sélectionner les passages les plus factuels.
Mais l'objectif est le déterminisme, pas l'inférence.

Effet : modéré.
Risque : suppression de passages utiles pour les actions de l'agent.

3. Utilité réelle du reranker

Le reranker est utile lorsque :

le corpus est très bruité,
les chunks sont hétérogènes,
le retriever renvoie trop de passages non pertinents,
la question est très ciblée.

Il est moins utile lorsque :

les chunks sont propres et homogènes,
les modes stricts restructurent déjà le contenu,
le modèle doit combiner des signaux faibles (cas du mode condense).

4. Synthèse

Mode	Utilité du reranker	Commentaire
condense	moyenne	améliore la pertinence mais peut réduire la diversité utile
tree_summarize	faible	la hiérarchie interne remplace le tri
node_summarize	très faible	résumés indépendants, ordre peu important
tool	modérée	utile pour filtrer, mais risque de perte d'information

Recommandation

Le reranker doit être activé uniquement dans les cas où la diversité des passages nuit à la pertinence.
Pour un pipeline moderne, la stratégie optimale est :

condense sans reranker par défaut,
condense avec reranker si le corpus est bruité,
modes stricts sans reranker.

Le Daemon Pyro5

Bertrand Degoy — 2026-07-07T09:30:51Z

Dans une architecture multi‑processus et multi‑utilisateur, on ne peut charger un même modèle dans chaque composant (NSOrchestrator, ReActEngine, workers, tests, scripts).
Pour cette raison, les modèles doivent être servis via un daemon.

Position du problème

Un LLM ou un SLM représente plusieurs gigaoctets en mémoire, et leur rechargement dans chaque processus provoquerait une explosion de la consommation RAM, une fragmentation CUDA, des temps de démarrage prohibitifs et une instabilité générale du système. Le mode daemon résout ce problème en garantissant qu'un modèle n'est chargé en mémoire qu'une seule fois dans un processus dédié, puis partagé entre tous les autres via RPC. Cela permet un fonctionnement réellement concurrent, une gestion propre du streaming token‑par‑token, une isolation des erreurs, et une stabilité mémoire indispensable en production.

Pour cette raison, le LLM et le SLM doivent être servis via un daemon. Les deux modèles sont sollicités par plusieurs utilisateurs, plusieurs sessions et plusieurs moteurs internes, parfois simultanément. Les Thought et les réponses finales de ReAct doivent être générées sans jamais recharger les poids des modèles, sans bloquer les autres processus, et sans dépendre de l'environnement local de chaque composant. En les exécutant tous deux en daemon, l'architecture v200 devient cohérente, déterministe et scalable : un seul chargement, un seul point d'accès, un comportement identique pour tous les clients, et une capacité à monter en charge sans modifier le code des orchestrateurs ou des moteurs internes.

Ce raisonnement vaut également pour les index.

Rôle du daemon

Le daemon Pyro5 est un fournisseur multi-services.

Via ModelsConfigurator, il :

Charge les modèles définis dans models.json, ce qui initialise AppSettings et les modèles globaux (embedding, LLM, SLM).
Charge les services déclarés dans services.json et les instancie dynamiquement.
Enregistre chaque service dans Pyro5 sous un nom stable :
- llm.server
- slm.server
- embedding.server
- rag.reader

Puis : Lance la boucle d'événements Pyro5.

Exemple : chargement d'un index par RagRuntime :

Composants principaux

1. MemoryManager

Arbitre global de la RAM.
Suit les allocations d'objets persistants.
Applique une politique d'éviction (LRU locale).
Fournit un état mémoire complet.
Thread-safe.

2. InDaemonRagReader (service rag.reader)

Module de recherche RAG, interne au daemon. Une architecture qui séparerait le modèle d'embedding et l'index dans des services distincts du daemon conduirait à un grand nombre d'échanges RCP et à des temps de traitement prohibitifs. InDaemonRagReader permet d'éviter cela :

Encode les requêtes via le modèle d'embedding global.
Interroge le backend vectoriel (FAISS, LlamaIndex ...).
Renvoie des RichNode.
Fournit un mode streaming (astream).

Interaction avec le client

Le client utilise InDaemonRagReaderProxy pour contacter le service rag.reader.

Flux typique :

RagRuntime.retrieve() → InDaemonRagReaderProxy("rag.reader").retrieve(theme, query, top_k) → InDaemonRagReader.retrieve() → encode la requête → interroge le backend vectoriel → renvoie des RichNode

Le client ne voit jamais MemoryManager : tout est encapsulé dans le daemon.

Avantages de cette architecture

Un seul daemon → cohérence mémoire.
Plusieurs services → modularité.
MemoryManager central → contrôle RAM industriel.
InDaemonRagReader → moteur RAG unifié.
Structure simple → facile à étendre.

v200 : Introduction, RagRuntime

Bertrand Degoy — 2026-07-04T08:16:29Z

La v200 introduit une architecture RAG entièrement refondue, centrée sur la modularité, la performance et la robustesse. Elle s'appuie sur l'écriture de services dédiés pour les modèles et les index, un daemon Pyro5 pour l'accès rapide aux index en mémoire, et une API interne unifiée permettant d'abstraire totalement les backends.
L'ensemble garantit un moteur RAG "RagRuntime" totalement indépendant de toute bibliothèque (LlamaIndex, LangChain ...) .
Cette version fournit ainsi une base industrielle, stable et extensible pour un pipeline RAG totalement propriétaire.

La v200 constitue une réarchitecture complète du pipeline RAG, conçue pour offrir une modularité stricte, une indépendance vis‑à‑vis de LlamaIndex ou de toute autre bibliothèque, et une performance accrue grâce à un daemon gérant les index en mémoire persistante. Elle introduit une séparation nette des responsabilités, une normalisation des API internes, et un modèle d'exécution cohérent pour tous les types d'index et de modèles.

1. Objectif : Modularité systémique

1.1. Modularité des modèles

La v200 définit des services dédiés pour les modèles :

services/llm/
services/embeddings/

Chaque service expose une API normalisée :

generate()
astream()
embed()

Cette abstraction permet de remplacer un modèle (OpenAI, Ollama, HF, local) sans impact sur le reste du pipeline.

1.2. Modularité des index

Les index sont encapsulés dans des backends interchangeables :

FaissBackend
LlamaIndexBackend
DummyBackend

Tous implémentent une API unifiée :

retrieve(query, top_k)
query(query)
astream(query)
ping()

Cette normalisation garantit que le RAG ne dépend plus du type d'index sous‑jacent.

1.3. Rapidité via daemon Pyro5

La v200 introduit un daemon Pyro5 :

chargé de maintenir les index en mémoire,
exposant une API RPC homogène,
permettant un accès rapide depuis n'importe quel worker.

Le client est minimal :

IndexesManager → IndexService → RemoteIndexBackend

Un mécanisme de **fallback local** assure la continuité de service en cas d'indisponibilité du daemon. ### **1.4. Couche interne de normalisation** Une couche interne (`internal/`) garantit : - la normalisation des résultats des backends, - la conversion des formats hétérogènes en structures standardisées, - la cohérence des données consommées par RagRuntime. Tous les résultats sont convertis en dictionnaires homogènes :

```python { "text": "...", "score": None, "metadata": {} }

2. Objectif : un RAG Engine indépendant d'API externes

2.1. Suppression des dépendances structurelles

La v200 élimine toute dépendance directe à LlamaIndex ( ou autre) dans le moteur RAG.

2.2. un RAG Engine basé sur une API interne stable :

Le moteur RAG (RagRuntime) ne dépend plus :

du type d'index,
du type de modèle,
de LlamaIndex ou FAISS.

Il consomme uniquement l'API unifiée :

retrieve()
query()
astream()

2.3. Normalisation systématique des résultats

Les résultats bruts des backends (souvent des chaînes de caractères) sont systématiquement convertis en objets structurés avant traitement par RagRuntime.

Cela garantit :

la stabilité du pipeline,
la compatibilité avec les hooks,
l'absence d'erreurs liées à des formats hétérogènes.

2.4. Fallback local cohérent

En cas d'indisponibilité du daemon :

IndexService.connect() → RemoteIndexBackend (si daemon disponible) → LocalIndexBackend (si daemon indisponible)

LocalIndexBackend est un proxy thread‑safe, totalement indépendant du type d'index.

Synthèse

La v200 est une architecture RAG :

modulaire, grâce à des services dédiés pour les modèles et les index,
performante, via un daemon Pyro5 servant les index en mémoire,
normalisée, grâce à une API interne unifiée pour tous les backends,
résiliente, via un fallback local automatique,
indépendante de LlamaIndex, grâce à l'encapsulation complète dans LlamaIndexBackend,
stable, grâce à une couche de normalisation systématique pour RagRuntime.

Elle constitue une base industrielle, cohérente, et extensible pour un pipeline RAG moderne.

Politique LRU/MRU

Bertrand Degoy — 2026-06-29T09:04:20Z

Dans l'architecture Pyro5, les index ( et certains modèles ) sont chargés depuis le disque puis conservés en RAM pour être accessibles rapidement par les services distants. Le daemon joue le rôle de processus maître.

Pour les index par exemple, il les expose via IndexServer, et sert de point d'accès unique pour tous les RemoteIndexService.

Comme ces index peuvent être volumineux et que le daemon est conçu pour rester actif longtemps, il doit gérer sa mémoire de manière autonome et efficace. C'est précisément pour cela qu'une politique LRU/MRU est indispensable : elle permet de conserver en RAM les index les plus récemment utilisés (MRU), tout en évinçant automatiquement ceux qui ne sont plus sollicités (LRU).

Cette stratégie garantit que le flowchart Pyro5 fonctionne de manière fluide, sans surcharge mémoire, et que les services distants accèdent toujours aux index pertinents sans rechargement inutile depuis le disque.

Politique LRU/MRU

La politique LRU/MRU (Least Recently Used / Most Recently Used) est un mécanisme de gestion de la mémoire qui permet de décider quel objet doit être évincé lorsque la RAM atteint sa capacité maximale. Elle repose sur un principe simple :

MRU = objets récemment utilisés → à conserver
LRU = objets peu utilisés récemment → candidats à l'éviction

Dans notre système, cette politique est appliquée par le MemoryManager, qui maintient un ordre strict des objets en RAM grâce à un OrderedDict.

MRU — Most Recently Used

Un objet devient MRU lorsqu'il est :

chargé en RAM,
accédé via get(),
marqué via touch().

Le MemoryManager déplace alors la clé à la fin de l'OrderedDict :

[ LRU ... → ... MRU ]

Cela signifie :

cet index est actif,
il doit être conservé en priorité,
il ne doit pas être évincé tant que d'autres objets moins utilisés existent.

LRU — Least Recently Used

L'objet LRU est celui qui :

n'a pas été utilisé depuis le plus longtemps,
n'a pas été touché récemment,
se trouve au début de l'OrderedDict.

Lorsqu'une éviction est nécessaire (ex : len(store) > max_items), le MemoryManager fait :

key, _ = self._store.popitem(last=False)

Ce qui retire le premier élément, donc le LRU.

Pourquoi LRU/MRU est idéal dans notre architecture

1. Les index sont lourds

Ils peuvent peser plusieurs centaines de Mo.
Il est donc crucial d'éviter de recharger inutilement depuis le disque.

2. Les RemoteIndexService sont stateless

Ils ne conservent rien : tout repose sur la RAM du daemon.
LRU/MRU garantit que les index réellement utilisés restent disponibles.

3. Le daemon est long-lived

Il doit s'auto-réguler sans intervention humaine.
LRU/MRU fournit une politique simple, déterministe et efficace.

4. Les thèmes ont chacun leur fréquence d'accès

Certains thèmes sont consultés souvent (MRU), d'autres rarement (LRU).
La politique s'adapte automatiquement à ces usages.

Résultat : une mémoire auto-optimisée

Grâce à LRU/MRU :

Les index actifs restent en RAM → latence minimale
Les index inactifs sont évincés → RAM maîtrisée
Le daemon ne recharge que si nécessaire → I/O minimisées
Le système reste stable même sous forte charge → robustesse

Construction des modèles : models.json et services.json

Bertrand Degoy — 2026-06-23T08:51:00Z

L'architecture v200 repose sur une séparation stricte entre la définition des modèles, leur construction centralisée, et la déclaration des services qui les consomment.
Les modèles sont décrits dans un fichier unique (`models.json`), puis construits une seule fois au démarrage par le `ModelsConfigurator`, avant d'être stockés dans `AppSettings` pour être partagés par l'ensemble du runtime.
Les services Pyro5, déclarés dans `services.json`, ne chargent jamais de modèles eux‑mêmes : ils se contentent d'exposer des capacités en s'appuyant sur les objets déjà initialisés, garantissant ainsi cohérence, performance et isolation des responsabilités.

Construction des modèles : `models.json` et `services.json`

1. Présentation générale : comment les modèles sont construits dans v200

L'architecture v200 repose sur une séparation stricte des responsabilités :

1. `models.json` décrit les modèles

Ce fichier déclare uniquement les modèles utilisés par le runtime :

embedding
slm
tokenizer
llm

Chaque entrée décrit :

model_name
model_path (optionnel)
backend
device
api_key_env (si backend = API) etc.

2. ModelsConfigurator construit les modèles

Le composant ModelsConfigurator :

lit models.json
instancie les modèles (HF, API, local, etc.)
crée les objets Python correspondants

Il ne connaît pas les services Pyro5.

3. AppSettingsManager stocke les modèles

Une fois construits, les modèles sont transmis à :

AppSettingsManager.load_models(...)

Ce composant :

crée un objet AppSettings
stocke les modèles dans des attributs statiques
verrouille la configuration

4. Les services Pyro5 consomment les modèles

Les services (EmbeddingServer, SLMServer, IndexServer, MemoryManager, RagReader) :

ne chargent pas de modèles
ne reçoivent pas de paramètres de modèle
récupèrent les modèles via :

from runtime_v2.settings.app_settings import AppSettings self.embedding = AppSettings.embedding
self.slm = AppSettings.slm
self.tokenizer = AppSettings.tokenizer
self.llm = AppSettings.llm

5. `services.json` décrit uniquement les services

Ce fichier :

déclare les services Pyro5
indique leur classe Python
fournit uniquement les paramètres nécessaires aux RPC (ex : nom d'un autre service)

Il ne doit jamais contenir de paramètres de modèle.

2. Comment écrire `models.json`

Voici la structure de base :

{ "__comment": "Source de ModelsConfigurator pour la configuration des modèles du runtime v200.", "embedding": { "__comment": "Embedding local basé sur SentenceTransformers (ST). Utilise BGE-small en mode léger, sans AutoModel/AutoTokenizer, pour éviter la surcharge mémoire des modèles HF.", "model_type": "embedding", "model_name": "BAAI/bge-small-en-v1.5", "model_path": "/home/iadnc/.models/bge-small", "backend": "st", "device": "cpu" }, "slm": { "__comment": "SLM local optionnel (TinyLlama, Phi, etc.). Null = désactivé.", "model_type": "causal_lm", "model_name": null, "model_path": null, "backend": null, "device": null }, "tokenizer": { "__comment": "Tokenizer HF externe (Mixtral), téléchargé via HF.", "model_type": "tokenizer", "model_name": "mistralai/Mixtral-8x7B-Instruct-v0.1", "model_path": null, "backend": "hf", "device": null }, "llm": { "__comment": "LLM principal via Daemon.", "model_type": "causal_lm", "backend": "mistral_daemon", "model_name": "mistral-medium-latest", "api_key_env": "MISTRAL_API_KEY", "daemon_host": "127.0.0.1", "daemon_port": 50050 }
}

Ou, plus ambitieux ( à condition que les backends aient été écrits) :

{ "__comment": "Configuration canonique v200 — aucun champ implicite, aucun type déduit automatiquement.", "llm_api": { "model_name": "mistral-medium-latest", "backend": "mistral_api", "model_type": "causal_lm", "api_key_env": "MISTRAL_API_KEY", "max_new_tokens": 2048, "temperature": 0.2 }, "llm_daemon": { "model_name": "mistral-medium-latest", "backend": "mistral_daemon", "model_type": "causal_lm", "api_key": "env:MISTRAL_API_KEY", "daemon_host": "127.0.0.1", "daemon_port": 50050, "max_new_tokens": 2048, "temperature": 0.0 }, "slm": { "model_name": "TinyLlama/TinyLlama-1.1B-Chat-v1.0", "backend": "hf_local", "model_type": "hf_causal_lm", "model_path": "/home/iadnc/.models/TinyLlama-1.1B-Chat-v1.0", "device": "cpu", "dtype": "float16", "max_new_tokens": 512, "temperature": 0.0 }, "embedding": { "model_name": "BAAI/bge-small-en-v1.5", "backend": "st", "model_type": "embedding", "model_path": "/home/iadnc/.models/bge-small", "device": "cpu" }, "tokenizer": { "model_name": "mistralai/Mixtral-8x7B-Instruct-v0.1", "backend": "hf", "model_type": "tokenizer", "device": "cpu" }, "service_router": { "model_name": "router-v1", "backend": "internal", "model_type": "router", "strategy": "round_robin", "targets": ["llm_api", "llm_daemon", "slm"] }, "reranker": { "model_name": "colbertv2", "backend": "hf_local", "model_type": "reranker", "model_path": "/home/iadnc/.models/colbertv2", "device": "cuda", "dtype": "float16" }, "vision_encoder": { "model_name": "openai/clip-vit-base-patch32", "backend": "hf_local", "model_type": "vision_encoder", "model_path": "/home/iadnc/.models/clip-vit-base-patch32", "device": "cuda" }, "audio_encoder": { "model_name": "facebook/wav2vec2-base-960h", "backend": "hf_local", "model_type": "audio_encoder", "model_path": "/home/iadnc/.models/wav2vec2", "device": "cpu" }, "http_service": { "model_name": "custom-service", "backend": "http", "model_type": "service", "service_url": "http://127.0.0.1:8080/infer", "timeout": 30 }
}

Règles :

Chaque modèle doit avoir un model_name
model_path peut être null si HF doit télécharger automatiquement
backend détermine le loader (hf, hf_local, mistral_api, etc.)
device peut être cpu, cuda, ou null
api_key est utilisé uniquement pour les backends API

3. Comment écrire `services.json`

Voici la version minimale, conforme à v200 :

{ "daemon": { "host": "127.0.0.1", "port": XXX }, "services": [ { "name": "llm.server", "class": "runtime_v21.services.llm.llm_server.LlmServer", "params": {} }, { "name": "slm.server", "class": "runtime_v21.services.llm.slm_server.SlmServer", "params": {} }, { "name": "memory.server", "class": "runtime_v21.services.memory_manager.MemoryManager", "params": {} } ], "index": { "loader": { "class": "runtime_v21.services.index.loaders.loader_manager.ThemeIndexLoaderManager", "params": {} }, "reserved_ram": 100000000 }
}, "tokenizer": { "model_name": "mistralai/Mixtral-8x7B-Instruct-v0.1", "backend": "hf", "model_type": "tokenizer", "device": "cpu" }
}

Règles :

Aucun service ne doit recevoir de modèle
→ pas de model, model_name, backend, device, etc.
Les services doivent recevoir uniquement :
- des noms de services Pyro5 (pour RPC)
- des paramètres métier (rare)
Les services doivent récupérer les modèles via AppSettings.

4. Résumé

Élément	Rôle	Contenu
`models.json`	Décrit les modèles	model_name, backend, device, path
`ModelsConfigurator`	Construit les modèles	HF, API, local
`AppSettingsManager`	Stocke les modèles	AppSettings.embedding, etc.
`services.json`	Décrit les services	classes, RPC, dépendances
Services Pyro5	Consomment les modèles	via AppSettings

Protocoles des API LLM

Bertrand Degoy — 2026-06-16T08:12:06Z

Ce document décrit les deux modes d'appel aux API utilisés par les modèles LLM dans l'architecture v200 : synchrone et streaming.

Protocoles d'appel LLM : synchrone vs streaming

Ce document décrit les deux modes d'appel utilisés par les modèles LLM dans l'architecture v200 :

appel synchrone (generate)
appel en streaming (stream_generate)

Les deux modes utilisent HTTP(S), mais pas le même protocole.

Dans la v200, les InternalLLM sont les seules classes responsables :

de la configuration backend (client, modèle, URL si HTTP)
de l'appel synchrone
de l'appel streaming
de la normalisation des réponses

1. Appel synchrone : HTTP POST classique

L'appel synchrone (generate) utilise un POST HTTP standard.

Caractéristiques

Une seule requête
Une seule réponse
Format JSON complet
Pas de flux
Pas de tokens intermédiaires

Exemple (OpenAI/Mistral-like)

POST /v1/chat/completions
Content-Type: application/json { "model": "mistral-large", "messages": [...]
}

Réponse :

200 OK
Content-Type: application/json { "id": "...", "choices": [ { "message": { "content": "réponse complète" } } ]
}

2. Appel streaming : HTTP POST + protocole de flux

L'appel stream_generate utilise également un POST HTTP, mais la réponse n'est pas un JSON unique.
Le serveur envoie un flux d'événements ou de chunks.

Deux protocoles sont utilisés selon les backends :

2.1. SSE (Server-Sent Events)

C'est le protocole utilisé par :

OpenAI
Mistral
Anthropic
Groq
LM Studio (mode OpenAI)

Caractéristiques

Content-Type: text/event-stream
Transfer-Encoding: chunked
Chaque ligne commence par data:
Chaque événement contient un fragment (delta)
Le flux se termine par data: [DONE]

Exemple

data: {"choices":[{"delta":{"content":"Bon"}}]}
data: {"choices":[{"delta":{"content":"jour"}}]}
data: {"choices":[{"delta":{"content":" !"}}]}
data: [DONE]

2.2. Chunked Transfer Encoding (Ollama)

Ollama n'utilise pas SSE mais un flux de JSON successifs, un par chunk.

Exemple

{"response": "Bon"}
{"response": "jour"}
{"response": " Bertrand"}
{"done": true}

Caractéristiques

Pas de data:
Pas de SSE
Chaque chunk est un JSON indépendant
Le client doit lire le flux chunk par chunk

3. Pourquoi deux protocoles différents ?

Parce que :

un appel synchrone renvoie une réponse complète
un streaming renvoie un flux de tokens

HTTP classique ne permet pas d'envoyer plusieurs réponses successives.
Les serveurs utilisent donc :

SSE → flux d'événements textuels
chunked transfer → flux de JSON partiels
WebSocket (rare) → flux bidirectionnel

4. Conséquences pour l'architecture v200

4.1. `generate()`

utilise un appel HTTP simple
renvoie un JSON complet
normalisation effectuée dans la classe LLM

4.2. `stream_generate()`

utilise SSE ou chunked transfer
lit les fragments au fur et à mesure
normalise chaque fragment en format v200 :

{ "delta": "texte" }
...
{ "delta": "", "meta": {...} }

Retourne un flux de chunks représentant la réponse en streaming. Contrat de l'interface :

La méthode doit produire un itérable de chunks.

Convention v200 (obligatoire pour toutes les implémentations) :
- Les chunks intermédiaires sont des dicts contenant : { "delta": "" }
- Le dernier chunk contient en plus des métadonnées : { "delta": "", "meta": {...} } Cette convention garantit un format standardisé pour toutes les
implémentations InternalLLM, indépendamment du backend utilisé.

5. Résumé

6. Exemple

from commons.models.internal.base import BaseGenerativeModel
from commons.models.response import Response
class MistralAPIInternalLLM(BaseGenerativeModel):
"""
Implémentation Mistral API pour v200.
Cette classe contient :
- la configuration backend (client, modèle)
- generate() : appel synchrone
- stream_generate() : appel SSE
- normalisation des réponses
"""
def __init__(self, client, model_name: str):
self.client = client
self.model_name = model_name
def generate(self, prompt: str, **kwargs) -> Response:
"""
Appel synchrone : requête HTTP complète, pas de streaming.
Le format exact de la réponse dépend du backend.
"""
raw = self.client.chat.completions.create(
model=self.model_name,
messages=[{"role": "user", "content": prompt}],
stream=False,
**kwargs,
)
try:
text = raw["choices"][0]["message"]["content"]
except Exception:
text = str(raw)
return Response(
response=text,
raw_response=raw,
source_nodes=None,
metadata={},
)
def stream_generate(self, prompt: str, **kwargs):
"""
Retourne un flux de chunks.
Le format exact dépend de l'implémentation.
Convention interne v200 :
- chunks intermédiaires : {"delta": "..."}
- chunk final : {"delta": "", "meta": {...}}
"""
stream = self.client.chat.completions.create(
model=self.model_name,
messages=[{"role": "user", "content": prompt}],
stream=True,
**kwargs,
)
final_message = None
for chunk in stream:
delta = ""
if chunk.choices:
c = chunk.choices[0]
if getattr(c, "delta", None) and getattr(c.delta, "content", None):
delta = c.delta.content or ""
if getattr(c, "message", None):
final_message = c.message
yield {"delta": delta}
yield {
"delta": "",
"meta": {
"raw_response": final_message,
"nodes": None,
"metadata": {},
},
}

Télécharger

ReActAgent(Workflow)

Bertrand Degoy — 2026-04-13T10:15:10Z

La boucle ReAct repose sur un principe simple : le workflow orchestre, l'agent raisonne. À chaque appel, génère un prompt, interroge le LLM, reconstruit une étape de raisonnement et laisse le finalizer décider de la suite. Une mécanique minimale côté workflow, une intelligence maximale côté agent.

La boucle de raisonnement ReAct

Le workflow considéré ici est celui de llamaindex.core.agent workflow de LlamaIndex version 0.14.10, avec le module indépendant workflows version 0.4.9.

Il s'agit d'un workflow synchrone, mono-agent, basé sur 5 événements, orchestré par Workflow.run() : boucle : LLM → Tool → LLM → Tool → … → FinalAnswer

Cette boucle simple permet d'imposer un fonctionnement ReAct strict : Thought ->Action -> Observation.

Les derniers développements de LlamaIndex ont éliminé ce mode de fonctionnement au profit d'un workflow multi-agent et asynchrone. Cela est contraire au principe de ReAct : Si l'on a besoin d'un traitement complexe on crée l'outil nécessaire. Le fonctionnement asynchrone n'a pas de sens au niveau de la boucle ReAct qui fonde son Thought sur l'Observation précédente comportant la totalité des réponses attendues. S'il doit y avoir du parallélisme, ce devra être géré au niveau de l'outil.

Comment `ReActAgent` s'insère dans le Workflow LlamaIndex

LlamaIndex ReActAgent, construit sur Workflow, fournit le code du step dans un workflow. Le workflow appelle :

BaseAgent.run_agent_step() → ReActAgent.take_step()

Donc :

le workflow = chef d'orchestre (encore un !)
l'agent = une étape du workflow
take_step() = la logique ReAct pour une étape

Comment sont construites les steps ReAct ?

En vérité : Le Workflow ne construit pas des steps ReAct. C'est ReActAgent qui les fait construire par le LLM. Le Workflow ne fait que :

appeler take_step()
attendre un AgentStepOutput (Thought, Action, Action Input ...)
décider avec ReActFinalizer si une nouvelle étape doit être exécutée

Voici ce qui se passe dans ReActAgent.take_step() pour construire une étape :

Étape 1 — Construire le prompt ReAct

L'agent génère le prompt ReAct qui fixe les règles que devra suivre le LLM pour élaborer les THOUGHT, ACTION et ACTION INPUT, pour appeler les outils etc. Le prompt contient également l'historique des échanges et, in fine, la question de l'utilisateur. Voici un exemple très naïf :

You are a ReAct agent.
First, think step-by-step and write:
THOUGHT:
Then, if needed, write:
ACTION:
ACTION INPUT:

Étape 2 — Appeler le LLM

L'agent appelle :

llm.stream(prompt)

Le LLM génère la réponse au prompt. → Le LLM produit progressivement, par petits fragments, les deltas.

Étape 3 — Le parser reconstruit les blocs

Le ReActStreamParser transforme les deltas en blocs :

THOUGHT: ...
ACTION: ...
OBSERVATION: ...
...
FINAL_ANSWER: ...

Étape 4 — Le ReActFinalizer décide si l'étape est terminée

Le finalizer :

valide les blocs
détecte les erreurs
empêche les boucles
décide si une nouvelle étape doit être lancée

Étape 5 — Le workflow relance `take_step()` si nécessaire

Si le finalizer dit “continue”, alors :

workflow → BaseAgent.run_agent_step → ReActAgent.take_step()

Et une nouvelle étape ReAct est produite.

En résumé : rôle du Workflow

Le workflow LlamaIndex ne fait qu'appeler take_step() en boucle.
ReActAgent.take_step() génère une étape ReAct en appelant le LLM.
Le ReActStreamParser reconstruit les blocs ReAct à partir des deltas.
Le ReActFinalizer décide si une nouvelle étape doit être lancée.
Le workflow relance take_step() si nécessaire.

Diagramme des classes

Voyez aussi :
– ReActEngine v1 : Finalizer et StreamParser
– ReActEngine v1 : Modules et traitements

RAG : Compression contextuelle

Bertrand Degoy — 2026-02-12T08:19:12Z

La contextual compression est un sujet qui est devenu central dans les RAG modernes.

C'est une technique qui permet de réduire dynamiquement - c'est à dire en fonction du contexte - la quantité de texte envoyée au LLM en ne gardant que ce qui est pertinent pour la requête.

On ne renvoit pas les documents bruts, mais une version compressée, filtrée, ou résumée, adaptée à la question.

C'est un pré‑processing intelligent du contexte.

C'est devenu indispensable

Parce que :

les fenêtres de contexte sont grandes mais pas infinies,
les chunks bruts sont souvent trop verbeux,
les embeddings récupèrent parfois trop de documents,
les modèles hallucinent moins quand le contexte est précis.

La contextual compression permet :

d'augmenter la précision,
de réduire le bruit,
d'améliorer la factualité,
de diminuer le coût.

Les 3 grandes familles de contextual compression

1. Compression par résumé (LLM summarization)

On récupère les documents pertinents, puis on demandes au LLM :

« Résume uniquement les parties utiles pour répondre à la requête X. »

C'est la version la plus simple et la plus efficace.

Exemple

Document : 3 pages
Requête : « Quels sont les effets secondaires du médicament ? »
Résumé compressé : 4 lignes ciblées

2. Compression par extraction (LLM extraction)

Le LLM ne résume pas : il extrait les passages pertinents.

« Extrait uniquement les phrases qui répondent à la question X. »

C'est plus précis et moins risqué que le résumé.

3. Compression par filtrage sémantique (embedding‑based filtering)

On fait un re‑ranking interne :

récupérer les chunks via embeddings.
re‑embed de chaque chunk par rapport à la requête.
élimination des chunks peu pertinents.

C'est du semantic pruning.

Comment ça s'intègre dans un pipeline RAG ?

Voici le pipeline classique :

User query
→ embedding de la requête
→ retrieval (top‑k documents)
→ contextual compression (résumé / extraction / filtrage)
→ Prompt final = system + historique + requête + contexte compressé
→ LLM

La compression intervient entre le retrieval et le prompt final.

Pourquoi c'est supérieur au RAG naïf ?

Sans compression :

envoit trop de texte,
dépasse la fenêtre,
ajoute du bruit,
augmente les hallucinations.

Avec compression :

n'envoie que l'essentiel,
reste dans la fenêtre,
augmente la précision,
réduit le coût.

Le point clé : la compression est contextuelle
Ce n'est pas un résumé générique.
C'est un résumé conditionné par la requête.

Exemple :

Requête A : « Quels sont les risques ? »
Requête B : « Quels sont les bénéfices ? »

Le même document donnera deux compressions différentes pour des requêtes différentes.

Notons que, par requête, on peut entendre historique + question. Ainsi, la même question de l'utilisateur, après avoir posé différentes questions et obtenu différentes réponses, une nouvelle question sera traitée en tenant compte des précédentes.

C'est ce qui rend la technique si puissante.

Les erreurs fréquentes

-résumer les documents avant le retrieval
→ tu perds de l'information utile

-compresser sans conditionner sur la requête
→ tu obtiens un résumé générique, inutile

-compresser trop tôt dans le pipeline
→ tu risques de biaiser la recherche

-compresser avec un modèle trop faible
→ tu introduis des erreurs dans le contexte

Comment faire une contextual compression robuste ?

Étape 1 — Retrieval large (top‑20 ou top‑50)

On récupère large pour ne rien rater.

Étape 2 — Re‑ranking (embedding ou cross‑encoder)

On réduit à top‑5 ou top‑10.

Étape 3 — Compression LLM (résumé/extraction)

On produit un contexte propre, court, précis.

Étape 4 — Prompt final

On injecte uniquement la version compressée.

Ce pipeline est beaucoup plus stable que le RAG naïf.

ReAct : le nommage des outils.

Bertrand Degoy — 2026-01-28T10:00:52Z

Dans la sélection d'un outil par le LLM, il apparaît que le nom de l'outil est prioritaire, et que la description est secondaire. De toute évidence, la description ne peut compléter un nom de fonction ambigu et ne servira au LLM qu'en deuxième intention.
Quelles sont les règles à appliquer pour le nommage des outils ?

Dans le choix de l'outil par le LLM, il apparait que le nom de la fonction (= le nom de l'outil) est totalement prioritaire, que la la Docstring vient ensuite, elle-même prioritaire sur la métadonnée 'description' [1] . De toute évidence, ni la Docstring ni la description ne peuvent corriger un nom de fonction ambigu, elle ne serviront qu'en cas de deuxième intention du LLM, après avoir constaté une erreur.

Exemple d'ambiguïté

Considérons un outil qui convertit une date lisible par un humain (human-readable date) en timestamp. Initialement nommé 'convert_date_to_timestamp'. On peut constater que l'usage de l'outil est mal compris par le LLM qui, notamment, peut tenter de l'utiliser à l'envers.

Le mot "date" est trop générique, et dans un contexte LLM, il peut désigner aussi bien une date lisible qu'un timestamp.

Pour éviter toute ambiguïté, il faut que le nom de l'outil encode clairement :

le type d'entrée attendu (ex. : texte lisible par un humain),
le type de sortie produit (ex. : timestamp numérique),
et idéalement, la direction de la conversion : l'entrée en tête, la sortie en queue.

Un meilleur choix serait : readable_date_to_timestamp

readable_date désambiguïse immédiatement : ce n'est pas un timestamp.
to_timestamp indique clairement la direction.
C'est court, typiquement LLM-friendly, et sans ambiguïté.

Ce qu'il faut éviter :

Des noms ambigus comme convert_dates ou parse_date (trop flous)
Des noms au singulier pour des fonctions vectorisées (ex. date_to_timestamp qui prend une liste)
Des noms inverses (timestamp_to_date) qui risquent d'être utilisés à contresens si mal nommés

Distinction entre fonction unitaire et vectorisée

L'outil readable_date_to_timestamp est 'unitaire' dans le sens où il n'effectue qu'une seule conversion.

Prenons le cas d'un outil qui transformerait une liste de dates humainement lisibles en la liste des timestamps correspondants. Comment nommer un tel outil ? Un nom comme readable_dates_to_timestamps sera bien interprété par un LLM comme une opération vectorisée (liste → liste), surtout si :

le nom est au pluriel (dates, timestamps),
il suit une convention claire et régulière dans l'ensemble des outils,
la Docstring ou l'intension associé confirme ce comportement,
on évite (faut-il le préciser ?) de créer des outils d'intention différente avec un nom similaire.

Pourquoi ce nom est bien compris :

readable_dates → explicite que l'entrée est une liste de dates lisibles.
to_timestamps → suggère une transformation vers une liste de timestamps.
Le pluriel des deux côtés induit une correspondance élément par élément.

Mais il y a quelques subtilités à garder en tête pour éviter toute confusion. C'est une convention que les LLM comprennent bien, surtout si :

on l'applique systématiquement (ex. : texts_to_embeddings, urls_to_titles, etc.),
il existe (comme dans notre exemple) la version unitaire.

l'outil expose une Docstring explicite et non contradictoire :

"""
Converts a list of human-readable date strings into a list of UNIX timestamps in milliseconds.
"""

on expose aussi une version unitaire : readable_date_to_timestamp → pour une seule date readable_dates_to_timestamps → pour une liste
on évite les inversions en exposant les outils inverses : timestamp_to_readable_date → pour une seule date timestamp_to_readable_date → pour une liste

Encore un défaut !

Cependant, notre exemple présente encore un défaut : la Docstring fait apparaître le timestamp comme étant un 'UNIX timestamps in milliseconds'. Or, fin 1990-début 2000 sont apparus les timestamp en microsecondes puis, dans les années 2010, en nanosecondes.

Le LLM risque de découvrir trop tard (en reprenant le raisonnement après avoir constaté l'erreur, si elle est détectée) que l'outil ne fonctionne qu'avec des timestamps en millisecondes !

Prenant modèle sur Python, il faut renommer nos fonctions avec timestamp_ms ou timestamp_ns [2] . Voici donc le jeu complet (pour un format millisecondes) : readable_date_to_timestamp_ms readable_dates_to_timestamps_ms timestamp_ms_to_readable_date timestamp_ms_to_readable_date

Sur ce sujet, voir également : ReAct : la carte des intentions : Intent Map

[1] La distinction entre Docstring et métadonnée 'description' existe dans l'objet FunctionTool mais pas dans le modèle de données MCP dans lequel il n'existe que la description de l'outil.

[2] Cependant, Python n'a pas de fonction pour traiter les microsecondes ; on adoptera timestamp_us ?

Les services IA de DnC

RagRuntime

RagRuntime — Présentation

1. Rôle général

2. Structure interne

Composants principaux

3. Modes de synthèse

Les modes de synthèse

Résumé de la problématique

1. Différence de traitement du contexte

2. Impact sur les capacités du modèle

3. Cas d'usage des modes stricts

4. Conséquence architecturale

Recommandation d'usage

Pertinence du reranker

1. Interaction générale entre reranker et modes

2. Effet par mode

Mode condense

Mode tree_summarize

Mode node_summarize

Mode tool

3. Utilité réelle du reranker

4. Synthèse

Recommandation

Le Daemon Pyro5

Position du problème

Rôle du daemon

Composants principaux

1. MemoryManager

2. InDaemonRagReader (service rag.reader)

Interaction avec le client

Avantages de cette architecture

v200 : Introduction, RagRuntime

1. Objectif : Modularité systémique

1.1. Modularité des modèles

1.2. Modularité des index

1.3. Rapidité via daemon Pyro5

2. Objectif : un RAG Engine indépendant d'API externes

2.1. Suppression des dépendances structurelles

2.2. un RAG Engine basé sur une API interne stable :

2.3. Normalisation systématique des résultats

2.4. Fallback local cohérent

Synthèse

Politique LRU/MRU

Politique LRU/MRU

MRU — Most Recently Used

LRU — Least Recently Used

Pourquoi LRU/MRU est idéal dans notre architecture

1. Les index sont lourds

2. Les RemoteIndexService sont stateless

3. Le daemon est long-lived

4. Les thèmes ont chacun leur fréquence d'accès

Résultat : une mémoire auto-optimisée

Construction des modèles : models.json et services.json

Construction des modèles : models.json et services.json

1. Présentation générale : comment les modèles sont construits dans v200

1. models.json décrit les modèles

2. ModelsConfigurator construit les modèles

3. AppSettingsManager stocke les modèles

4. Les services Pyro5 consomment les modèles

5. services.json décrit uniquement les services

2. Comment écrire models.json

Règles :

3. Comment écrire services.json

Règles :

4. Résumé

Protocoles des API LLM

Protocoles d'appel LLM : synchrone vs streaming

1. Appel synchrone : HTTP POST classique

Caractéristiques

Exemple (OpenAI/Mistral-like)

2. Appel streaming : HTTP POST + protocole de flux

2.1. SSE (Server-Sent Events)

Caractéristiques

Exemple

2.2. Chunked Transfer Encoding (Ollama)

Exemple

Caractéristiques

3. Pourquoi deux protocoles différents ?

4. Conséquences pour l'architecture v200

Construction des modèles : `models.json` et `services.json`

1. `models.json` décrit les modèles

5. `services.json` décrit uniquement les services

2. Comment écrire `models.json`

3. Comment écrire `services.json`

4.1. `generate()`

4.2. `stream_generate()`

Comment `ReActAgent` s'insère dans le Workflow LlamaIndex

Étape 5 — Le workflow relance `take_step()` si nécessaire