Les services IA de DnC

ReActEngine v1 : Modules et traitements

Bertrand Degoy — 2026-04-09T08:23:12Z

ReActEngine Mistral v1 est un moteur agentique modulaire, contrôlable et extensible, combinant RAG, outils personnalisés, sélection dynamique d'outils et génération finalisée.
Il est conçu pour les environnements multi-thèmes, multi-sources et nécessitant une auditabilité stricte du raisonnement et des actions.

Destinée à un public expert, voici une description de l'agent ReActEngine Mistral v104 fondé sur llama_index.core.agent.workflow.ReActAgent, intégrant Finalizer, ToolRouter, RAG, outils personnalisés et orchestration.

ReActEngine Mistral v104 — Description technique

1. Nature de l'agent

L'agent Mistral ReAct v104 est un moteur agentique basé sur le paradigme ReAct (Reasoning + Acting).
Il combine :

un LLM Mistral (via API),
un orchestrateur d'outils dont MCP,
un Finalizer pour la génération contrôlée,
un ToolRouter pour la sélection dynamique d'outils,
un RAG (Research Augmented Generation) modulaire basé sur l'agent de recherche Chat Engine Mistral utilisé par notre ChatBot simple.

Il s'appuie sur la classe ReActAgent du module llama_index.core.agent.workflow, plutôt que sur les agents préconstruits, afin de garantir :

un contrôle fin du cycle ReAct,
une meilleure auditabilité,
une intégration propre des outils personnalisés,
une compatibilité avec les pipelines agentiques complexes.

2. Architecture générale

2.1. Boucle ReAct

L'agent suit la logique décrite dans Synergizing Reasoning and Acting in Language Models :

Reasoning : le LLM produit une intention ou un plan.
Acting : l'agent appelle un outil.
Observation : l'outil renvoie un résultat.
Reasoning : le LLM intègre l'observation.
Final Answer : produit par le Finalizer.

: La boucle ReAct

2.2. Outils intégrés

L'agent combine trois familles d'outils :

A. RAG (QueryEngineTool)

Basé sur chat_engine_mistral_v1.3.x.
Utilise les index créés par RAG Manager ou IngestCmd.
Permet un RAG cohérent, multithème, multilingue.

B. Outils personnalisés (FunctionTools)

Fournissent des données temps réel (par exemple issues de WhatisWhat).
Les données sont injectées via MCP. Voir : ReAct et intégration des données temps réel avec MCP ( Model Context Protocol )
Exemples : météo, état d'un système, données métier, etc.

Voir également : RAG : Chat Engine ReAct avec outils

C. Outils généralistes

Calculs : arithmétique, statistique
Manipulation de texte
Utilitaires divers

3. Initialisation

3.1. `init(...)`

Deux modes d'initialisation :

Mode 1 : avec `ragkwargs`

Recommandé pour les applications modernes.
Le thème, la langue, le niveau de détail, etc. sont fournis dès l'instanciation.
L'agent est immédiatement opérationnel.

Mode 2 : sans `ragkwargs`

Héritage pour compatibilité ascendante.
L'application doit ensuite appeler start().
Adapté aux démons ou workers multi-thèmes.

Paramètres clés :

config : configuration globale (commune à IngestCmd, ChattyBot, ChattyWS…)
llmapikey : clé API MistralAI
token : jeton de sécurité pour les serveurs de données
ragkwargs : dictionnaire contenant au minimum :
- theme
- detail
- language

4. Méthode `start()`

Méthode héritée pour compatibilité avec les services REST ou workers persistants.

Elle :

complète l'initialisation selon le thème,
charge l'index si nécessaire,
permet aux applications stateful de fournir leur propre index (optimisation),
prépare l'agent ReAct pour le thème courant.

Retour : un objet ReActAgent prêt à l'emploi.

5. Gestion de l'historique — `set_history()`

Cette méthode :

reçoit un historique OpenAI-style :
[{ "role": "user", "content": "..." }, ...]
nettoie et compresse l'historique pour compatibilité ReAct,
stocke :
- self.conversation_history
- self.compressed_history

L'agent est statique :
→ l'application appelante doit gérer la persistance de l'historique et le transmettre avant chaque requête.

6. Exécution asynchrone — `stream(prompt)`

6.1. Fonctionnement

Pour chaque prompt :

ToolRouter sélectionne dynamiquement les outils pertinents
→ réduction du contexte, optimisation des coûts, meilleure précision.
L'agent ReAct est reconstruit avec uniquement les outils routés.
Un tote bag est préparé :
- historique compressé
- langue
- profil (ex. "expert")
Le ReActFinalizer gère la génération incrémentale.
La méthode retourne un AsyncGenerator.

6.2. Résilience

Toute exception est :

interceptée,
tracée via log_trace,
et la méthode renvoie le générateur déjà créé si possible.

7. Exécution synchrone — `get_engine_response()`

Fonctionnement :

récupère l'historique compressé si non fourni,
applique le ToolRouter,
exécute l'agent ReAct,
retourne une réponse complète (non streamée).

8. Toolkits dynamiques

Le moteur charge automatiquement :

un ToolKit généraliste (obligatoire),
un ToolKit spécifique au thème (optionnel).

Cela permet :

une modularité forte,
une isolation stricte des outils par thème,
une réduction du bruit dans la boucle ReAct.

9. Points clés de la version v104

Intégration du Finalizer (contrôle de la réponse finale).
Intégration du ToolRouter (sélection dynamique des outils).
Utilisation de ReActAgent(Workflow) plutôt que l'agent préconstruit, afin d'atteindre le cœur de la boucle ReAct et y apporter des améliorations .
Outils RAG encapsulés dans RagTool.
Compatibilité MCP pour les données temps réel.
Architecture stateless côté agent, stateful côté application.

10. Diagramme des échanges


ReActEngine v1 diagramme des échanges

Les modules de la partie gauche (ReActEngine, ToolRouter, ReActFinalizer, ReActStreamParser) ont été développés spécialement pour atteindre les objectifs du ReActEngine v1, tandis que la partie droite comprend les modules du ReActAgent(Workflow) de LlamaIndex avec quelques adaptations. Le LLM est une API de MistralAI.

Conseisl : Cliquez sur le diagramme pour le zoomer. Ouvrez le diagramme dans une autre fenêtre pour mieux suivre la suite.

10.1 Vision globale du flux

Utilisateur → ReActEngine : prompt.
ReActEngine → ToolRouter : sélection d'outils.
ReActEngine → ReActAgent : initialisation du pipeline.
Formatter → LLM : message formaté.
LLM → StreamParser : tokens bruts → blocs ReAct.
Parser → Agent : StepResult.
Workflow : décide de la suite (outil, raisonnement, final).
Finalizer : réponse finale.
ReActEngine → Utilisateur : streaming de la réponse.

10.2 Détail des échanges et des traitements

Utilisateur

Entrée : intention humaine, question, commande.
Traitement : aucun — c'est la source du prompt.
Sortie : prompt utilisateur envoyé au ReActEngine.

ReActEngine

Entrée : prompt utilisateur.
Traitement : Détermine si le prompt nécessite des outils. Appelle le ToolRouter pour identifier les outils pertinents. Initialise un agent ReAct complet (Finalizer, Workflow, Formatter, Parser…). Lance la boucle de streaming (token-par-token).
Sortie : flux de tokens structurés (Thought / Action / Observation / FinalAnswer).

ToolRouter

Entrée : prompt brut.
Traitement : Analyse sémantique du prompt. Sélectionne les outils pertinents (toolbag).
Sortie : liste d'outils pertinents → renvoyée au ReActEngine.

ReActFinalizer

Entrée : instance d'agent ReAct.
Traitement : Surveille la fin du raisonnement. Détecte un FinalAnswer ou une condition d'arrêt. Nettoie et finalise la réponse.
Sortie : réponse finale propre, prête à être envoyée à l'utilisateur.

ReActStreamParser

Entrée : tokens bruts provenant du LLM. Traitement : Reconstitue les blocs ReAct (Thought, Action, Observation…). Filtre les artefacts, nettoie les tokens. Émet des fragments de réponse via un générateur asynchrone.
Sortie : tokens nettoyés + blocs ReAct structurés.

ReActAgent (modifié)

Entrée : message formaté (prompt + contexte + outils).
Traitement : Implémente la logique ReAct :
Thought → Action → Observation → Thought → …
Décide quand appeler un outil. Produit un StepResult à chaque itération.
Sortie : StepResult (structure contenant Thought/Action/Observation).

BaseWorkflowAgent (modifié)

Entrée : StepResult ou message intermédiaire.
Traitement : Gère la logique générique d'un agent (état, transitions, erreurs). Coordonne les appels entre Workflow, Formatter, Parser.
Sortie : instructions pour la prochaine étape du workflow.

ReActWorkflow

Entrée : StepResult + contexte d'exécution.
Traitement : Orchestration du cycle ReAct. Détermine si l'agent doit :
continuer à raisonner,
appeler un outil,
ou produire la réponse finale.
Sortie : nouvelle étape à exécuter (run_step).

ReActChatFormatter

Entrée : prompt utilisateur + état du workflow.
Traitement : Formate le message dans le style attendu par le LLM (system + user + tool instructions). Injecte les outils dans le prompt si nécessaire.
Sortie : message formaté envoyé au LLM.

ReActOutputParser (modifié)

Entrée : sortie brute du LLM. Traitement : Analyse la réponse du LLM. Extrait Thought / Action / Observation / FinalAnswer. Détecte les erreurs de format.
Sortie : StepResult structuré.

Modèle LLM

Entrée : message formaté (prompt complet).
Traitement : Génération token-par-token. Produit du texte brut sans structure interne explicite.
Sortie : tokens bruts → envoyés au StreamParser.

Mise en œuvre des outils dans notre ReActAgent

1. Les outils

L'agent s'appuie sur trois ToolKits complémentaires :

GeneralToolKit : outils génériques toujours disponibles.
ThemeToolKit : outils métier + un outil RAG pour accéder à la documentation interne.
ToolKit Temps Réel : outils connectés à des sources de données dynamiques (internes/externes).

Voir également : ReAct et intégration des données temps réel avec MCP ( Model Context Protocol )

2. L'outil RAG dans la boucle ReAct

Le RAG (Research Augmented Generation) est intégré comme un outil standard, accessible via la logique ReAct.

Rôle du RAG

Il permet à l'agent d'interroger la documentation interne de l'entreprise, composée de : documents historiques (rapports, notes, logs), référentiels documentaires (procédures, notices techniques), routines spécialisées pour guider le raisonnement dans des tâches répétitives.

Fonction dans ReAct

Le RAG est utilisé lorsque l'agent doit : vérifier une information interne, s'appuyer sur des documents de référence, exécuter une tâche nécessitant un contexte métier documenté.

Le RAG enrichit le raisonnement de l'agent en lui donnant accès à la connaissance interne, tout en restant orchestré par ReAct.

3. le ToolRouter

Le ToolRouter identifie automatiquement les outils les plus adaptés à une requête utilisateur grâce à un mécanisme de similarité vectorielle.

Fonctionnement :

Chaque outil possède une description textuelle (métadonnées). Voir : ReAct : la carte des intentions : Intent Map Les descriptions et la requête utilisateur sont vectorisées via un modèle d'embedding. Le routeur calcule la similarité cosinus entre la requête et chaque outil. Les outils sont classés par pertinence. Le ReActAgent choisit l'outil à appeler en fonction du classement et du contexte.

→ Le ToolRouter guide la boucle ReAct vers l'outil optimal au moment opportun.

Résultat : Un agent capable de combiner raisonnement, outils spécialisés, documentation interne et données temps réel.

Le module ModelLoaderFactory ( "la factory" )

Bertrand Degoy — 2026-04-02T07:22:02Z

Ce document explique la façon dont les modèles locaux sont créés et utilisés dans un environnement LlamaIndex.

On y détaille :
– les différences classes structurelles de modèles locaux, ce qui nécessite une abstraction pour LlamaIndex,
– comment le module ModelLoaderFactory ( "la factory" ) assure la création des modèles locaux et leur abstraction,
– le rôle du singleton AppSettings pour exposer les modèles.

Différences entre modèles HuggingFace, SentenceTransformer et modèles génériques

Tout d'abord, il faut considérer que :

le modèle d'embedding DOIT être celui utilisé par le LLM,
dans une architecture RAG, il doit être le même pour l'ingestion, la sélection et la génération.

Les modèles d'embeddings utilisés dans un pipeline RAG ou agentique n'appartiennent pas tous à la même famille. Ils diffèrent par leur format, leur API, leur manière de produire les embeddings et leur niveau de spécialisation. Comprendre ces différences aide à choisir le bon modèle et à structurer une architecture propre et stable.

Note : la factory peut également gérer de façon similaire des modèles 'causal LM' ( notamment des LLM ), on se concentre ici sur les modèles d'embedding.

Modèles HuggingFace (HF Encoders)

Les modèles HF de type encoder (comme BERT, RoBERTa, MPNet, BGE, E5, GTE, Jina) sont des modèles Transformers polyvalents. Ils ne sont pas conçus spécifiquement pour produire des embeddings, mais ils peuvent le faire.

Ils utilisent le format standard HuggingFace, avec des fichiers comme config.json, model.safetensors et tokenizer.json. Leur API repose sur l'appel direct du modèle avec un tokenizer, ce qui renvoie un tenseur PyTorch contenant les représentations de chaque token. Pour obtenir un embedding final, il faut appliquer un pooling manuel (par exemple une moyenne des tokens ou l'utilisation du token CLS).

Ces modèles sont très flexibles et peuvent servir à d'autres tâches que les embeddings, mais ils demandent plus de travail pour produire un vecteur cohérent et stable. Ils peuvent aussi être plus lourds en mémoire et en temps d'inférence.

Modèles SentenceTransformer (ST)

Les modèles SentenceTransformer sont construits à partir de modèles HF, mais ils sont spécialement adaptés pour produire des embeddings de phrases. Ils incluent un pipeline complet : tokenizer, modèle Transformer et couche de pooling intégrée.

Leur format est différent de celui de HuggingFace : ils utilisent des fichiers comme modules.json et des sous-dossiers tels que 0_Transformer/ et 1_Pooling/. Leur API est simple : une seule méthode encode(text) renvoie directement un vecteur numpy prêt à l'emploi.

Ces modèles sont optimisés pour la similarité sémantique, ce qui les rend particulièrement adaptés aux systèmes RAG, aux moteurs de recherche et aux tâches de clustering. Ils sont plus simples à utiliser que les modèles HF, mais moins flexibles pour d'autres usages.

Note : BAAI fournit ses modèles ( comme BAAI/bge-small-en-v1.5" ) sous les deux formats HF et ST.

Modèles génériques ou personnalisés

Il existe aussi des modèles qui ne suivent ni le format HF ni celui de SentenceTransformer. Ils peuvent être très simples, comme un modèle maison exposant une méthode embed(text), ou très spécialisés, comme un modèle ONNX ou quantisé avec une API minimale.

Ces modèles n'ont pas de format standard et leur API varie selon l'implémentation. Ils peuvent renvoyer des listes Python, des tenseurs ou d'autres structures. Ils sont souvent utilisés pour les tests, les prototypes ou les environnements très contraints.

Ils sont faciles à intégrer, mais nécessitent une couche d'abstraction pour garantir une sortie cohérente et éviter les comportements imprévisibles.

Pourquoi une architecture unifiée est nécessaire

Les différences entre HF, ST et les modèles génériques rendent indispensable une couche d'unification. Sans cela, chaque composant du système devrait gérer des formats différents, des API différentes et des comportements différents.

L' architecture décrite par la suite résout ce problème en trois étapes :

la factory installe et valide le modèle ;
le wrapper normalise les sorties et fournit une API interne stable ;
l'adapter expose une API compatible LlamaIndex.

Cette approche garantit que tous les modèles, quelle que soit leur origine, produisent des embeddings cohérents, normalisés et utilisables dans l'ensemble du pipeline.

Architecture de la création des embeddings locaux

Objectifs

Déterminisme total : aucun fallback, aucune heuristique.
Installation automatique au premier appel de la factory, sans lazy-loading des poids.
Compatibilité offline : tout fonctionne ensuite sans réseau.
Normalisation stricte : toujours retourner des list[float].
Séparation nette des responsabilités :
- Factory = installation/validation
- Wrapper = normalisation
- Adapter = API LlamaIndex
Assurer un point d'accès à l'API unique et global : Settings

1. Vue d'ensemble

Le système d'embeddings repose sur trois couches clairement séparées :

ModelLoaderFactory
- Installe, valide et instancie les modèles HF/ST.
- Garantit un fonctionnement déterministe, sans fallback ni heuristique.
UniversalEmbeddingWrapper Normalisation et abstraction du backend :
- Unifie tous les backends (HF, ST, générique).
- Fournit une API interne stable : embed(str) -> list[float].
LlamaIndexEmbeddingAdapter
- Expose l'API LlamaIndex (get_text_embedding, get_query_embedding).
- Utilise le wrapper pour garantir la normalisation.

Le résultat est stocké dans Settings.embed_model qui devient le singleton global pour tout le système.

2. Chargement du modèle via la factory

factory = ModelLoaderFactory() embedding = factory.create_embedding( model_path= "/home/iadnc/.models/bge-small, model_name= "BAAI/bge-small-en-v1.5", model_type= "sentence_transformer", device= "cuda"
)

Ce que fait la factory :

Sélectionne l'installateur approprié (HFInstaller, STInstaller).
Installe ou valide le modèle dans model_path.
Détecte le type réel du modèle (HF, ST, causal LM).
Vérifie la cohérence entre type déclaré et type détecté.
Instancie l'embedding RAM (HFEmbedding ou STEmbedding).

Résultat : un embedding brut, non encore adapté à LlamaIndex.

3. Construction du singleton `AppSettings.embed_model`

AppSettings.embed_model = create_llamaindex_embedding(embedding)

Cette fonction construit la chaîne API complète :

AppSettings.embed_model
├── wrapper (UniversalEmbeddingWrapper)
│ └── embedding (HFEmbedding ou STEmbedding)
└── get_*_embedding() (API LlamaIndex BaseEmbedding)

Architecture

 ┌──────────────────────────┐
 │ ModelLoaderFactory │
 │ (installation + RAM) │
 └─────────────┬────────────┘
 │
 ▼
 Embedding RAM instancié 
 
 HFEmbedding (HF) | STEmbedding (ST) | Generic 
 - tensor output | - numpy output | - list 
 - pooling manuel | - pooling intégré | - API custom
 
 │
 ▼
 ┌────────────────────────────────────┐
 │ UniversalEmbeddingWrapper │
 │ embed(str) -> list[float] │
 │ backend = HF / ST / generic │
 └─────────────────┬──────────────────┘
 │
 ▼
 ┌──────────────────────────────────────┐
 │ LlamaIndexEmbeddingAdapter │
 │ get_text_embedding() │
 │ get_query_embedding() │
 └──────────────────┬───────────────────┘
 │
 ▼
 ┌────────────────────────────────┐
 │ AppSettings.embed_model │
 │ (singleton global complet) │
 │ │
 │ ├── wrapper │
 │ │ └── embedding (HF/ST) │
 │ └── get_*_embedding() │
 └────────────────────────────────┘

Le singleton AppSettings permet d'accéder à trois niveaux d'API, chacun avec un rôle clair :

API interne :
AppSettings.embed_model.wrapper.embed("texte")
→ utilisée par les compresseurs, le RAG, les agents.
API LlamaIndex :
AppSettings.embed_model.get_text_embedding("texte")
→ utilisée par les index, retrievers, query engines.
API modèle brut :
AppSettings.embed_model.wrapper.embedding.model
→ utile pour debug, tests, opérations avancées.

4. Exemples d'usage

API interne (wrapper)

vec = AppSettings.embed_model.wrapper.embed("Bonjour")

API LlamaIndex

vec = AppSettings.embed_model.get_text_embedding("Bonjour")

API modèle HF/ST brut

hf_model = AppSettings.embed_model.wrapper.embedding.model

En savoir plus :
– AppSettings : un Singleton Global pour stabiliser les modèles face aux limites du singleton LlamaIndex

#! python3
# coding: utf8
# PythonApp/commons/model_loader_factory.py
'''
Classe ModelLoaderFactory
## Usage pour un modèle d'embedding :
embedding = factory.create_embedding(
...
)
app_settings.embed_model = create_llamaindex_embedding(embedding)
Voir : https://ia.dnc.global/Preparation-et-utilisation-des-modeles-locaux-pour-LlamaIndex.html
Auteur : B.Degoy bertrand@degoy.com
v 0.0.1
2026/02/16-20 (t=9h)
'''
# Standard imports
from typing import List
from pathlib import Path
import json
from sentence_transformers import SentenceTransformer
from transformers import AutoModel, AutoTokenizer, PreTrainedModel
# Third-party Imports
from llama_index.core.embeddings import BaseEmbedding
from huggingface_hub import hf_hub_download, list_repo_files
from langchain.embeddings.base import Embeddings as LCEmbeddings
#TODO Futurs installateurs (à ajouter progressivement) :
# from commons.installers.hf_seq2seq_installer import HFSeq2SeqInstaller
# from commons.installers.onnx_installer import ONNXInstaller
# from commons.installers.gguf_installer import GGUFInstaller
# Fonction utilitaire : assemble wrapper + adapter
def create_llamaindex_embedding(embedding):
wrapper = UniversalEmbeddingWrapper(embedding)
return LlamaIndexEmbeddingAdapter(
wrapper=wrapper,
model_name=embedding.model_name,
)
import numpy as np
class UniversalEmbeddingWrapper:
"""
Couche d'unification des embeddings garantissant une interface unique,
stable et normalisée pour tous les backends utilisés dans le système.
Cette classe encapsule un objet d'embedding arbitraire (HFEmbedding,
STEmbedding, modèle générique, mock de test, etc.) et fournit une API
minimale mais strictement définie :
embed(str) -> list[float]
indépendamment du backend réel. Elle élimine ainsi toute ambiguïté sur le
format de sortie et protège les couches supérieures (compresseurs,
LlamaIndexEmbeddingAdapter, moteurs RAG, etc.) contre les variations
d'implémentation des bibliothèques tierces.
Détection du backend
--------------------
Le wrapper identifie le type d'embedding fourni selon les attributs présents :
- SentenceTransformer → présence de `embed_documents`
- HFEmbedding custom → présence de `_get_text_embedding`
- Embedding générique → présence de `embed`
- Sinon → backend inconnu (erreur explicite)
Cette détection est volontairement simple, explicite et déterministe :
aucune heuristique, aucun fallback, aucune supposition implicite.
Normalisation des sorties
-------------------------
Les backends peuvent renvoyer différents formats :
- numpy.ndarray
- torch.Tensor
- list[float]
- objets HF/ST spécifiques
Le wrapper applique systématiquement :
- si l'objet possède `.tolist()` → conversion en liste Python
- si c'est déjà une liste → renvoi direct
- sinon → conversion explicite via `list(v)`
Garanties
---------
- Sortie toujours en `list[float]`, quel que soit le backend.
- Fonctionnement déterministe et compatible offline.
- Aucune prise en charge de `embed(list[str])` : la méthode ne traite
que des chaînes individuelles, conformément aux invariants du système.
- Protection contre les comportements implicites ou non documentés des
bibliothèques tierces.
Paramètres
----------
embedding : object
Instance d'un backend d'embedding (HF, ST, générique, mock, etc.)
fournissant au minimum une méthode d'encodage compatible avec l'un
des backends détectés.
"""
def __init__(self, embedding):
self.embedding = embedding
self.backend = self._detect_backend()
def _detect_backend(self):
if hasattr(self.embedding, "embed_documents"):
return "st_embedding"
if hasattr(self.embedding, "_get_text_embedding"):
return "hf_embedding"
if hasattr(self.embedding, "embed"):
return "generic_embedding"
return "unknown"
def embed(self, text: str) -> list[float]:
"""Normalise toutes les sorties en list[float]."""
if self.backend == "hf_embedding":
arr = self.embedding._get_text_embedding(text)
if isinstance(arr, list):
return arr
return arr.tolist()
if self.backend == "st_embedding":
arr_list = self.embedding.embed_documents([text])
v = arr_list[0]
if isinstance(v, list):
return v
return v.tolist()
if self.backend == "generic_embedding":
arr = self.embedding.embed(text)
if isinstance(arr, list):
return arr
return arr.tolist()
raise RuntimeError("Backend inconnu")
from llama_index.core.embeddings import BaseEmbedding
from pydantic import Field
from pydantic import ConfigDict
class LlamaIndexEmbeddingAdapter(BaseEmbedding):
"""
Adaptateur entre UniversalEmbeddingWrapper et l'API BaseEmbedding de LlamaIndex.
Cette classe fournit une couche d'intégration stable et minimale permettant
d'utiliser n'importe quel backend d'embeddings (HF, SentenceTransformer,
embeddings génériques, modèles locaux, etc.) au sein de LlamaIndex, tout en
respectant strictement les invariants du wrapper universel :
- Toutes les sorties sont normalisées en `list[float]`.
- Aucun appel `embed(list[str])` n'est autorisé : l'adapter boucle
explicitement sur les listes de textes.
- Les méthodes sync/async de BaseEmbedding sont correctement implémentées.
- Le comportement est déterministe et thread-safe.
Paramètres
----------
wrapper : UniversalEmbeddingWrapper
Wrapper unifié fournissant la méthode `embed(str) -> list[float]`.
L'adapter délègue tous les calculs d'embeddings à ce wrapper.
"""
#Pydantic v2
model_config = ConfigDict(extra="allow")
wrapper: object = Field(...)
model_name: str = Field(default="unknown")
def __init__(self, wrapper, model_name="unknown"):
super().__init__(
model_name=model_name,
wrapper=wrapper,
)
def describe(self) -> str:
cls = self.__class__.__name__
return (
f"{cls}:\n"
f" model_name : {self.model_name}\n"
f" wrapper : {self.wrapper.__class__.__name__}\n"
f" embedding : {self.wrapper.embedding.model_name}\n"
)
@property
def embedding_root(self):
return self.wrapper.embedding
def _to_list(self, v):
"""
Convertit un vecteur en liste Python.
Cette méthode garantit que les embeddings renvoyés par les backends
(NumPy, Torch, HF, ST, etc.) sont convertis proprement en `list[float]`.
Si `v` est déjà une liste Python, elle est renvoyée telle quelle.
Paramètres
----------
v : array-like
Vecteur d'embedding potentiel (numpy.ndarray, torch.Tensor, list).
Retour
------
list[float]
Embedding converti en liste Python.
"""
if hasattr(v, "tolist"):
return v.tolist()
return list(v)
# --- Méthodes privées requises par BaseEmbedding ---
def _get_query_embedding(self, query: str):
"""
Embedding d'une requête utilisateur (méthode interne LlamaIndex).
Cette méthode est appelée par LlamaIndex pour encoder les requêtes
textuelles. Elle délègue directement au wrapper universel, garantissant
une sortie normalisée en `list[float]`.
Paramètres
----------
query : str
Texte de la requête.
Retour
------
list[float]
Embedding de la requête.
"""
return self.wrapper.embed(query)
def _get_text_embedding(self, text: str):
"""
Embedding d'un document ou d'un chunk (méthode interne LlamaIndex).
LlamaIndex appelle cette méthode pour encoder les documents ou les
chunks lors de la construction d'index. Le wrapper universel garantit
une sortie cohérente et normalisée.
Paramètres
----------
text : str
Texte à encoder.
Retour
------
list[float]
Embedding du texte.
"""
return self.wrapper.embed(text)
async def _aget_query_embedding(self, query: str):
"""
Version asynchrone de l'embedding de requête.
Comme le wrapper universel ne fournit qu'une API synchrone, cette
méthode utilise `asyncio.to_thread` pour exécuter l'embedding dans un
thread séparé, garantissant la compatibilité avec les pipelines async
de LlamaIndex.
Paramètres
----------
query : str
Requête utilisateur.
Retour
------
list[float]
Embedding de la requête.
"""
# wrapper.embed() est sync, on passe par asyncio.to_thread
import asyncio
return await asyncio.to_thread(self.wrapper.embed, query)
# --- Méthodes publiques ---
def get_query_embedding(self, query: str):
"""
API publique LlamaIndex pour encoder une requête.
Cette méthode est un simple proxy vers `_get_query_embedding`, afin de
respecter l'interface publique de BaseEmbedding.
Paramètres
----------
query : str
Requête utilisateur.
Retour
------
list[float]
Embedding de la requête.
"""
return self._get_query_embedding(query)
def get_text_embedding(self, text: str):
"""
API publique LlamaIndex pour encoder un texte.
Proxy direct vers `_get_text_embedding`, utilisé par les indexeurs et
les moteurs de recherche internes de LlamaIndex.
Paramètres
----------
text : str
Texte à encoder.
Retour
------
list[float]
Embedding du texte.
"""
return self._get_text_embedding(text)
def get_text_embeddings(self, texts: list[str]):
"""
Encode une liste de textes.
Le wrapper universel ne supportant pas `embed(list[str])`, cette méthode
applique explicitement `embed()` sur chaque élément. Cela garantit une
compatibilité totale avec BaseEmbedding et évite les erreurs de type.
Paramètres
----------
texts : list[str]
Liste de textes à encoder.
Retour
------
list[list[float]]
Liste d'embeddings, un par texte.
"""
# wrapper n'a pas embed(list), on boucle
return [self.wrapper.embed(t) for t in texts]
class ModelLoaderFactory:
"""
Fabrique centralisée et déterministe pour l'installation, la validation et
l'instanciation des modèles d'embeddings et des modèles CausalLM.
Cette classe constitue le point d'entrée unique pour charger des modèles
locaux ou distants dans un environnement strictement contrôlé. Elle impose
une discipline forte : aucun comportement implicite, aucune heuristique,
aucune détection automatique du type de modèle. L'appelant doit fournir
explicitement le type attendu, et toute incohérence entre le type déclaré
et la structure réelle du modèle installé entraîne une erreur immédiate.
Rôle et garanties
-----------------
- Gestion centralisée de l'installation via des installateurs spécialisés
(HFInstaller, STInstaller, HFInstallerCausalLM).
- Validation stricte de la structure locale du modèle :
* HF : lecture de config.json + vérification des poids.
* SentenceTransformer : présence de modules.json + 1_Pooling.
- Aucun fallback, aucune récupération implicite, aucun accès réseau dans
les méthodes de création (l'installation peut télécharger, mais jamais
create_embedding / create_causal_lm).
- Fonctionnement 100 % déterministe et compatible offline après installation.
- Registry interne permettant de suivre les modèles chargés en RAM et de
les décharger proprement (GPU/CPU + GC).
Méthodes
------------
- create_embedding() :
Instancie un embedding RAM (HFEmbedding ou STEmbedding) après installation
et validation stricte du modèle.
- create_causal_lm() :
Instancie un moteur CausalLM local (HFCausalLMEngine) après validation.
- _select_installer() :
Sélection explicite de l'installateur en fonction du type déclaré.
- _detect_local_model_type() :
Détection stricte du type réel du modèle installé, sans heuristique.
- unload_model() :
Décharge proprement un modèle
"""
def __init__(self):
# Régistre interne
self._registry = {}
# Entrée principale : création d'un embedding RAM
def create_embedding(self, model_path: str, model_name: str, model_type: str, device: str = None):
"""
Crée un embedding RAM à partir d'un modèle local ou distant sans aucun comportement implicite.
Cette méthode ne tente jamais de déduire automatiquement le type de modèle. Le type
doit être fourni explicitement par l'appelant (ex. "hf_encoder", "sentence_transformer").
Aucun fallback, aucune heuristique et aucune détection distante (HuggingFace Hub) ne
sont effectués ( parce que c'est impossible du fait que les modèles en cache HF n'ont généralement pas de fichier config.json).
Toute incohérence entre le type déclaré et la structure du modèle installé entraîne une erreur explicite.
Pipeline :
1. Sélection de l'installateur correspondant au type déclaré.
- Aucun choix automatique : l'appelant est responsable du type.
- Si le type n'est pas supporté → RuntimeError.
2. Installation ou validation du modèle dans `model_path`.
- L'installateur garantit une installation idempotente et déterministe.
- Si le modèle est absent ou incomplet → installation complète.
- Si le modèle est présent → validation stricte.
- Aucun fallback, aucune récupération implicite.
3. Détection locale du type réel du modèle installé.
- Lecture de `config.json` (HF) ou `modules.json` (ST).
- Si la structure locale ne correspond pas au type déclaré → RuntimeError.
4. Instanciation de l'embedding RAM approprié.
- HFEmbedding pour "hf_encoder".
- STEmbedding pour "sentence_transformer".
- Aucun autre type n'est supporté.
Garanties :
- Fonctionnement strictement déterministe : aucun comportement caché.
- Compatibilité offline totale après installation.
- Pas d'accès réseau dans cette méthode.
- Pas de dépendance au cache HuggingFace Hub.
- Pas de heuristique, pas de fallback, pas de supposition.
- Validation systématique de la cohérence entre type déclaré et type détecté.
Paramètres :
model_path (str) :
Chemin local où installer ou valider le modèle.
Peut être un dossier vide ou un dossier contenant une installation existante.
model_name (str) :
Nom du modèle HuggingFace (ex. "BAAI/bge-small-en-v1.5").
Utilisé uniquement par l'installateur pour télécharger le modèle si nécessaire.
model_type (str) :
Type explicite du modèle. Doit être l'un des types supportés :
- "hf_encoder"
- "sentence_transformer"
Toute autre valeur entraîne une erreur immédiate.
device (str | None) :
Device d'exécution ("cpu", "cuda", etc.).
Si None → sélection automatique par l'embedding.
Retour :
Instance d'un embedding en RAM (CustomHFEmbedding, CustomSTEmbedding).
Exceptions :
RuntimeError :
- Type de modèle non supporté.
- Incohérence entre type déclaré et type détecté localement.
- Modèle local invalide ou structure incorrecte.
- Échec d'installation ou de validation.
"""
if model_type == "hf_causal_lm":
raise RuntimeError("[ModelLoaderFactory] Un modèle CausalLM ne peut pas être instancié comme embedding. Utiliser create_causal_lm")
# Installer le modèle via l'installateur défini
installer = self._select_installer(model_type)
local_path = installer.resolve(model_path, model_name)
# Détecter le type local pour validation
detected = self._detect_local_model_type(Path(local_path))
if model_type not in detected :
raise RuntimeError(
f"[ModelLoaderFactory] Incohérence : modèle déclaré '{model_type}' mais détecté '{detected}'"
)
# Instancier l'embedding RAM
if model_type == "sentence_transformer":
from commons.embeddings.st_embeddings import STEmbedding
embedding = STEmbedding(local_path, model_path, model_name, device)
self._registry[model_name] = embedding
return embedding
if model_type == "hf_encoder":
from commons.embeddings.hf_embeddings import HFEmbedding
embedding = HFEmbedding(local_path, device)
self._registry[model_name] = embedding
return embedding
raise RuntimeError(f"[ModelLoaderFactory] Aucun embedding disponible pour le type : {model_type}")
def create_causal_lm(self, model_path: str, model_name: str, device: str = None):
"""
Instancie un modèle HuggingFace CausalLM (génératif) en RAM de manière
strictement déterministe, après installation locale complète et validation
structurelle.
Cette méthode est l'équivalent "génération" de `create_embedding()`. Elle ne
traite que les modèles de type `hf_causal_lm`, c'est-à-dire les modèles
autoregressifs compatibles avec `AutoModelForCausalLM` (LLaMA, Mistral,
GPT-like, Qwen, Phi, Gemma, etc.).
Étapes garanties :
1. Installation stricte et idempotente via HFInstallerCausalLM :
- Téléchargement explicite de tous les fichiers du repo HF.
- Aucun fallback réseau après installation.
- Aucun recours au cache HF.
- Support des modèles sharded.
- Validation stricte de la structure CausalLM.
2. Détection locale du type réel du modèle via `_detect_local_model_type()`.
- Le type détecté doit être exactement "hf_causal_lm".
- Toute incohérence entraîne une erreur explicite.
3. Instanciation du moteur de génération HFCausalLMEngine :
- Chargement RAM du modèle.
- Configuration explicite du device.
- Enregistrement dans le registre interne pour réutilisation.
Paramètres :
model_path (str) :
Chemin local où le modèle doit être installé ou déjà présent.
Le dossier est créé si nécessaire.
model_name (str) :
Nom du modèle HuggingFace (repo_id) à installer et charger.
device (str, optionnel) :
Device explicite pour l'inférence ("cpu", "cuda", "cuda:0", etc.).
Si None, le moteur applique sa logique interne.
Retour :
HFCausalLMEngine :
Instance prête à l'emploi du modèle CausalLM chargé en RAM.
Exceptions :
RuntimeError :
- Le modèle installé n'est pas détecté comme "hf_causal_lm".
- Structure locale invalide ou incomplète.
- Installation impossible ou incohérente.
- Toute violation du contrat de déterminisme ou de validation.
Notes :
Cette méthode ne doit jamais être utilisée pour des embeddings.
Les modèles CausalLM sont distinct des encodeurs HF et des SentenceTransformers dans leur architecture.
"""
installer = HFInstallerCausalLM()
local_path = installer.resolve(model_path, model_name)
detected = self._detect_local_model_type(Path(local_path))
if detected != ["hf_causal_lm"]:
raise RuntimeError(
f"[ModelLoaderFactory] Incohérence : modèle déclaré 'hf_causal_lm' mais détecté '{detected}'"
)
from commons.llm.hf_causal_lm import HFCausalLMEngine
engine = HFCausalLMEngine(local_path, model_name, device)
self._registry[model_name] = engine
return engine
# Sélection de l'installateur
def _select_installer(self, model_type: str):
if model_type == "sentence_transformer":
from commons.installers.st_installer import STInstaller
return STInstaller()
if model_type == "hf_encoder":
from commons.installers.hf_installer import HFInstaller
return HFInstaller()
if model_type == "hf_causal_lm":
from commons.installers.hf_causal_installer import HFInstallerCausalLM
return HFInstallerCausalLM()
raise RuntimeError(f"[ModelLoaderFactory] Aucun installateur disponible pour le type : {model_type}")
def _detect_local_model_type(self, path: Path) -> str:
"""
Détermine les types réels d'un modèle installé localement en inspectant
uniquement la structure du dossier, sans heuristiques implicites ni
priorité arbitraire.
Certains modèles (ex. BAAI/BGE, E5, GTE, Jina) peuvent exposer
simultanément une structure HuggingFace et une structure
SentenceTransformer. Cette méthode détecte donc tous les formats
présents et renvoie une liste de types possibles.
Détection :
- Format HuggingFace (HF) si :
* un fichier config.json lisible contient un champ "model_type"
* au moins un fichier de poids HF est présent
(model.safetensors, pytorch_model.bin, *.index.json)
* si model_type in {llama, mistral, gpt2, qwen, phi, gemma}
-> "hf_causal_lm"
* sinon si model_type in {bert, roberta, mpnet, bge, e5, gte, jina}
-> "hf_encoder"
- Format SentenceTransformer si :
* modules.json est présent
* le dossier 1_Pooling/ existe
Retour :
Liste des types détectés, par exemple :
["hf_encoder"]
["sentence_transformer"]
["hf_encoder", "sentence_transformer"]
["hf_causal_lm"]
Exceptions :
RuntimeError si aucune structure valide n'est détectée ou si les
fichiers présents sont incohérents ou non supportés.
"""
types = []
# --- Détection HuggingFace ---
config_path = path / "config.json"
if config_path.exists():
try:
cfg = json.loads(config_path.read_text())
except Exception as e:
raise RuntimeError(f"[ModelLoaderFactory] config.json illisible dans {path} : {e}")
cfg_model_type = cfg.get("model_type", "").lower()
if not cfg_model_type:
raise RuntimeError(f"[ModelLoaderFactory] config.json ne contient pas 'model_type' dans {path}")
weight_files = [
"model.safetensors",
"pytorch_model.bin",
"pytorch_model.bin.index.json",
]
if any((path / wf).exists() for wf in weight_files):
causal_types = {"llama", "mistral", "gpt2", "qwen", "phi", "gemma"}
if cfg_model_type in causal_types:
types.append("hf_causal_lm")
else:
hf_supported = {"bert", "roberta", "mpnet", "bge", "e5", "gte", "jina"}
if cfg_model_type in hf_supported:
types.append("hf_encoder")
else:
raise RuntimeError(
f"[ModelLoaderFactory] Type HF non supporté : '{cfg_model_type}' dans {path}. "
f"Types supportés : {sorted(hf_supported)}"
)
# --- Détection SentenceTransformer ---
if (path / "modules.json").exists() and (path / "1_Pooling").exists():
types.append("sentence_transformer")
# --- Aucun type détecté ---
if not types:
raise RuntimeError(f"[ModelLoaderFactory] Impossible de déterminer le type de modèle dans {path}")
return types
def unload_model(self, model_name: str):
"""
Désinstalle complètement un modèle de la RAM, en supprimant toutes les
références Python connues, en nettoyant le registry interne, et en
vidant les caches PyTorch. Cette méthode garantit qu'aucun résidu
mémoire ne persiste après déchargement.
Règles contractuelles :
- Le modèle doit avoir été chargé via ModelLoaderFactory.
- Le registry interne doit contenir une entrée pour ce modèle.
- Le déchargement supprime :
- l'objet embedding (STEmbedding ou HFEmbedding)
- le modèle HF ou SentenceTransformer sous-jacent
- les buffers internes éventuels
- les références dans le registry
- Les caches PyTorch sont vidés explicitement.
- Aucun fallback, aucune suppression silencieuse.
Paramètres :
model_name (str) :
Nom du modèle tel qu'enregistré dans le registry RAM.
Exceptions :
RuntimeError :
- Si le modèle n'est pas présent dans le registry.
"""
# Vérifier la présence dans le registry
if model_name not in self._registry:
raise RuntimeError(
f"[ModelLoaderFactory] Impossible de décharger '{model_name}' : "
f"aucune entrée dans le registry RAM."
)
embedding = self._registry[model_name]
# Supprimer les références internes du wrapper
if hasattr(embedding, "model"):
del embedding.model
if hasattr(embedding, "tokenizer"):
del embedding.tokenizer
# Supprimer l'entrée du registry
del self._registry[model_name]
# Nettoyage PyTorch
try:
import torch
torch.cuda.empty_cache()
torch.cuda.ipc_collect()
except Exception:
pass # CPU-only ou PyTorch non installé
# Garbage collector Python
import gc
gc.collect()

Télécharger

AppSettings : un Singleton Global pour stabiliser les modèles face aux limites du singleton LlamaIndex

Bertrand Degoy — 2026-03-30T10:12:26Z

Dans une architecture utilisant LlamaIndex, la gestion des modèles (LLM, embeddings, tokenizer, etc.) repose sur des mécanismes internes du framework.

Ces mécanismes fonctionnent correctement dans des cas simples, mais présentent plusieurs limites structurelles dans un écosystème d'applications devant partager des modèles identiques.

Le “singleton” interne de LlamaIndex n'est ni strict, ni stable, et peut être réinitialisé ou modifié de manière implicite selon l'ordre des imports, les contextes d'exécution ou les workers. Cela conduit à des comportements non déterministes, difficiles à diagnostiquer, et parfois dangereux (modèles différents selon les modules ou les workers). Pour stabiliser l'ensemble, il est nécessaire d'introduire un singleton global explicite, contrôlé, verrouillé, traçable et idempotent : c'est le rôle de AppSettings et AppSettingsManager qui forment un système robuste plus strict et plus fiable que celui fourni par LlamaIndex, et adapté à une architecture modulaire, multi‑thread et multiprocess.

Introduction : pourquoi un Singleton global dédié ?

Dans une architecture utilisant LlamaIndex, la gestion des modèles (LLM, embeddings, tokenizer, versions) repose sur des mécanismes internes du framework. Ces mécanismes fonctionnent correctement dans des cas simples, mais présentent plusieurs limites structurelles lorsqu'on construit une application :

modulaire,
multi‑thread,
multi‑process (ex. plusieurs workers uvicorn/gunicorn),
ou composée de plusieurs modules indépendants devant partager des modèles identiques.

Ce texte documente :

le principe du Singleton global utilisé dans nos applications d'IA,
en quoi il diffère du “singleton” de LlamaIndex,
la structure et le rôle de AppSettings,
la logique et les responsabilités de AppSettingsManager,
les mécanismes d'initialisation, de verrouillage et de traçage.

1. Principe général

AppSettings est un singleton global destiné à contenir les objets critiques de l'application :

le modèle LLM,
le modèle d'embedding,
le tokenizer,
les versions associées.

Ce singleton est conçu pour être :

unique dans le processus,
initialisé une seule fois,
verrouillé après initialisation,
idempotent (les appels suivants ne modifient rien),
traçable (on sait qui a initialisé en premier).

Ce mécanisme garantit que toutes les parties de l'application utilisent les mêmes objets, sans risque de divergence ou de réinitialisation accidentelle.

2. Différence avec le “singleton” de LlamaIndex

LlamaIndex utilise un mécanisme interne d'initialisation (souvent via Settings ou des loaders) qui :

n'est pas global à l'application, mais local au framework,
peut être réinitialisé selon les contextes,
n'est pas conçu pour être partagé entre plusieurs modules indépendants,
ne fournit pas de verrou multi‑thread ou multi‑process,
ne trace pas l'origine de l'initialisation.

En résumé :

Aspect	Notre AppSettings	LlamaIndex Settings
Portée	Globale à l'application	Locale au framework
Initialisation	Unique, verrouillée	Réinitialisable
Idempotence	Oui	Non garanti
Traçage	Oui (stack + timestamp)	Non
Multi‑thread	Protégé	Non
Multi‑process	Protégé (file lock)	Non

Notre système est donc plus strict, plus robuste et plus adapté à une application multi‑modules.

3. Structure de AppSettings

AppSettings est un BaseModel Pydantic contenant les objets critiques :

llm: Optional[Any]
embed_model: Optional[Any]
tokenizer: Optional[Any]
versions: Optional[Dict[str, Any]]
locked: bool
initialized_by: Optional[str]
initialized_at: Optional[float]

Caractéristiques :

locked empêche toute modification après initialisation.
initialized_by contient la stack trace du premier appel.
initialized_at contient le timestamp d'initialisation.
extra = "forbid" empêche l'ajout d'attributs fantômes.
validate_assignment = True garantit un comportement fail‑closed.

4. Rôle de AppSettingsManager

AppSettingsManager est le seul point d'entrée pour modifier ou initialiser AppSettings.

Il fournit :

4.1. `load_models()`

Charge les objets critiques.
Capture la stack trace du premier appel.
Capture le timestamp.
Valide les objets.
Verrouille l'état.
Est idempotent : si déjà initialisé, ne fait rien.

4.2. `validate()`

Vérifie la présence de llm, embed_model, tokenizer.
Comporte un comportement fail‑closed.

4.3. `lock()`

Marque l'état comme immuable.

4.4. `describe()`

Retourne un dictionnaire d'introspection complet.

5. Sécurité multi‑thread et multi‑process

L'initialisation est protégée par deux verrous :

5.1. Verrou thread‑safe

_thread_lock = threading.Lock()

Empêche deux threads du même processus d'initialiser simultanément.

5.2. Verrou multi‑process (file lock)

_process_lock = FileLock("/tmp/appsettings_init.lock")

Empêche deux processus (ex. plusieurs workers uvicorn/gunicorn) d'initialiser simultanément.

Ce mécanisme garantit une initialisation unique, même dans un environnement multi‑workers.

6. Cycle de vie complet

Une application appelle load_models().
Le verrou multi‑process est acquis.
Le verrou multi‑thread est acquis.
Si locked == True → rien n'est fait.
Sinon :
- stack trace enregistrée,
- timestamp enregistré,
- objets chargés,
- validation stricte,
- verrouillage.
Les appels suivants sont silencieusement ignorés.


Diagramme de séquence: Ce diagramme illustre le processus par lequel elle obtient le singleton AppSettings pour accéder aux modèles dont elle a besoin

7. Avantages de cette architecture

Initialisation unique garantie.
Protection contre les réinitialisations accidentelles.
Sécurité multi‑thread et multi‑process.
Traçabilité complète.
Idempotence.
Isolation claire entre :
- le stockage global (AppSettings)
- la logique métier (AppSettingsManager)
- les configurateurs externes (ex. LlamaConfigurator).

8. Résumé

AppSettings et AppSettingsManager forment un système robuste permettant :

de centraliser les objets critiques,
de garantir une initialisation unique,
de sécuriser l'accès concurrent,
de tracer l'origine de l'initialisation,
de fournir une introspection complète.

Ce mécanisme est plus strict et plus fiable que celui fourni par LlamaIndex, et il est adapté à une architecture modulaire, multi‑thread et multiprocess.

La classe AppSettings

# app_settings.py
# coding: utf8
'''
Classe AppSettings
Remplace le singleton 'Settings' de LlamaIndex.
Le singleton de LlamaIndex n'est pas stable :
- il est réinitialisé par certains modules internes lors d'imports tardifs,
- il est mutable et non verrouillé,
- il est globalement partagé par tout LlamaIndex, et peut être écrasé silencieusement par des appels internes,
etc..
Auteur :
B.Degoy bertrand@degoy.com
'''
from functools import lru_cache
from pydantic import BaseModel, Field
from typing import Any, Optional, Dict
class AppSettings(BaseModel):
"""Singleton global contenant les objets critiques de l'application."""
llm: Optional[Any] = None
embed_model: Optional[Any] = None
tokenizer: Optional[Any] = None
versions: Optional[Dict[str, Any]] = None
locked: bool = Field(default=False, exclude=True)
initialized_by: Optional[str] = Field(default=None, exclude=False)
initialized_at: Optional[float] = None
class Config:
arbitrary_types_allowed = True
validate_assignment = True # fail-closed si mauvais type
extra = "forbid" # pas d'attributs fantômes
@lru_cache(maxsize=1)
def get_app_settings() -> AppSettings:
return AppSettings()

Télécharger

La classe AppSettingsManager

# app_settings_manager.py
# coding: utf8
'''
Classe AppSettingsManager
thread-safe, multiprocess-safe
Auteur :
B.Degoy bertrand@degoy.com
'''
import traceback, time
import commons.settings.app_settings
from pydantic import ValidationError
from commons.settings.app_settings import get_app_settings #j
# verrous multi-processus
from filelock import FileLock
import threading
# Verrou inter-processus
_process_lock = FileLock("/tmp/appsettings_init.lock") # répertoire standard pour les verrous inter-processus
# Verrou intra-processus (threads)
_thread_lock = threading.Lock()
class AppSettingsManager:
@staticmethod
def load_models(llm, embed_model, tokenizer, versions=None):
app = get_app_settings()
with _process_lock: # verrou multi-process
with _thread_lock: # verrou thread-safe
# Déjà chargé et verrouillé : OK, on ne fait rien
if app.locked:
# Optionnel : vérifier la cohérence
if (app.llm and app.embed_model and app.tokenizer):
return # idempotent, silencieux
else:
raise RuntimeError(
"[AppSettingsManager] AppSettings is locked but incomplete."
)
# Initialisation au premier appel :
# capturer la stack du premier appel
app.initialized_by = "".join(traceback.format_stack(limit=10))
app.initialized_at = time.time()
# on charge
app.llm = llm
app.embed_model = embed_model
app.tokenizer = tokenizer
app.versions = versions or None
AppSettingsManager.validate()
AppSettingsManager.lock()
@staticmethod
def validate():
"""Validation stricte fail-closed."""
app = get_app_settings()
if app.llm is None:
raise ValidationError("[AppSettingsManager] Missing LLM in AppSettings")
if app.embed_model is None:
raise ValidationError("[AppSettingsManager] Missing embed_model in AppSettings")
if app.tokenizer is None:
raise ValidationError("[AppSettingsManager] Missing tokenizer in AppSettings")
@staticmethod
def lock():
"""Empêche toute modification ultérieure."""
app = get_app_settings()
app.locked = True
@staticmethod
def describe() -> dict:
"""Introspection complète pour debug."""
app = get_app_settings()
return {
"llm": type(app.llm).__name__ if app.llm else None,
"embed_model": type(app.embed_model).__name__ if app.embed_model else None,
"tokenizer": type(app.tokenizer).__name__ if app.tokenizer else None,
"versions": app.versions,
"locked": app.locked,
"initialized_by": app.initialized_by,
"initialized_at": app.initialized_at,
}

Télécharger

Les services IA de DnC

ReActEngine v1 : Modules et traitements

ReActEngine Mistral v104 — Description technique

1. Nature de l'agent

2. Architecture générale

2.1. Boucle ReAct

2.2. Outils intégrés

A. RAG (QueryEngineTool)

B. Outils personnalisés (FunctionTools)

C. Outils généralistes

3. Initialisation

3.1. __init__(...)

Mode 1 : avec ragkwargs

Mode 2 : sans ragkwargs

4. Méthode start()

5. Gestion de l'historique — set_history()

6. Exécution asynchrone — stream(prompt)

6.1. Fonctionnement

6.2. Résilience

7. Exécution synchrone — get_engine_response()

8. Toolkits dynamiques

9. Points clés de la version v104

10. Diagramme des échanges

10.1 Vision globale du flux

10.2 Détail des échanges et des traitements

Utilisateur

ReActEngine

ToolRouter

ReActFinalizer

ReActStreamParser

ReActAgent (modifié)

BaseWorkflowAgent (modifié)

ReActWorkflow

ReActChatFormatter

ReActOutputParser (modifié)

Modèle LLM

Mise en œuvre des outils dans notre ReActAgent

1. Les outils

2. L'outil RAG dans la boucle ReAct

Rôle du RAG

Fonction dans ReAct

3. le ToolRouter

Le module ModelLoaderFactory ( "la factory" )

Différences entre modèles HuggingFace, SentenceTransformer et modèles génériques

Modèles HuggingFace (HF Encoders)

Modèles SentenceTransformer (ST)

Modèles génériques ou personnalisés

Pourquoi une architecture unifiée est nécessaire

Architecture de la création des embeddings locaux

Objectifs

1. Vue d'ensemble

2. Chargement du modèle via la factory

Ce que fait la factory :

3. Construction du singleton AppSettings.embed_model

Architecture

4. Exemples d'usage

API interne (wrapper)

API LlamaIndex

API modèle HF/ST brut

AppSettings : un Singleton Global pour stabiliser les modèles face aux limites du singleton LlamaIndex

Introduction : pourquoi un Singleton global dédié ?

1. Principe général

2. Différence avec le “singleton” de LlamaIndex

3. Structure de AppSettings

4. Rôle de AppSettingsManager

4.1. load_models()

4.2. validate()

4.3. lock()

4.4. describe()

5. Sécurité multi‑thread et multi‑process

5.1. Verrou thread‑safe

5.2. Verrou multi‑process (file lock)

6. Cycle de vie complet

7. Avantages de cette architecture

8. Résumé

La classe AppSettings

La classe AppSettingsManager

3.1. `init(...)`

Mode 1 : avec `ragkwargs`

Mode 2 : sans `ragkwargs`

4. Méthode `start()`

5. Gestion de l'historique — `set_history()`

6. Exécution asynchrone — `stream(prompt)`

7. Exécution synchrone — `get_engine_response()`

3. Construction du singleton `AppSettings.embed_model`

4.1. `load_models()`

4.2. `validate()`

4.3. `lock()`

4.4. `describe()`