Le parcours d'une question¶
Cette page suit le trajet complet d'une question d'utilisateur à travers Diapason, depuis le moment où elle entre par la ligne de commande ou par le SDK jusqu'à la réponse finale et à son enregistrement dans la télémétrie.
Le diagramme de séquence¶
sequenceDiagram
actor User as Utilisateur
participant CLI as CLI / SDK
participant CFG as Configuration et découverte
participant LRN as Apprentissage (aiguilleur)
participant AGT as Agent
participant MEM as Moteur de mémoire
participant CTX as Injection du contexte
participant ENG as Moteur d'inférence
participant TEL as Télémétrie
participant TRC as Collecteur de traces
User->>CLI: diapason ask "question" / j.ask("question")
CLI->>CFG: load_config()
CFG-->>CLI: DiapasonConfig (matériel, défauts du moteur)
CLI->>CFG: get_engine(config)
CFG-->>CLI: (engine_key, engine_instance)
CLI->>CFG: discover_engines() + discover_models()
CFG-->>CLI: modèles disponibles par moteur
alt Aucun modèle précisé
CLI->>LRN: select_model(RoutingContext)
LRN-->>CLI: model_key (par exemple "qwen3:8b")
end
alt Mode agent (drapeau --agent)
CLI->>AGT: agent.run(query, context)
AGT->>MEM: retrieve(query, top_k=5)
MEM-->>AGT: RetrievalResult[]
AGT->>CTX: inject_context(query, messages, backend)
CTX-->>AGT: messages avec le contexte en tête
loop Boucle d'appel d'outils (max_turns)
AGT->>ENG: generate(messages, model, tools)
ENG-->>AGT: {content, tool_calls, usage}
opt Des appels d'outils sont présents
AGT->>AGT: ToolExecutor.execute(tool_call)
AGT->>AGT: Ajouter les résultats d'outils aux messages
end
end
AGT-->>CLI: AgentResult(content, tool_results, turns)
else Mode direct (sans agent)
CLI->>MEM: retrieve(query)
MEM-->>CLI: RetrievalResult[]
CLI->>CTX: inject_context(query, messages, backend)
CTX-->>CLI: messages avec le contexte
CLI->>ENG: instrumented_generate(messages, model)
ENG-->>CLI: {content, usage}
end
CLI->>TEL: TelemetryStore enregistre les mesures
CLI->>TRC: TraceCollector enregistre la Trace
CLI-->>User: Le texte de la réponse
Le mode direct et le mode agent¶
Diapason traite une question par deux chemins possibles, choisis par le drapeau --agent en ligne de commande ou par le paramètre agent du SDK.
Le mode direct (celui par défaut)¶
En mode direct, la question part droit au moteur d'inférence, avec le contexte mémoire en option. C'est le chemin le plus court : un seul appel d'inférence, aucune boucle d'outils.
# En ligne de commande
diapason ask "Quelle est la capitale de la France ?"
# Dans le SDK
j = Diapason()
response = j.ask("Quelle est la capitale de la France ?")
Le mode agent¶
En mode agent, la question est prise en charge par un agent nommé, capable d'enchaîner plusieurs tours d'inférence et d'appeler des outils. L'OrchestratorAgent est le choix le plus courant : il ouvre une boucle d'appel d'outils sur plusieurs tours.
# En ligne de commande
diapason ask --agent orchestrator --tools calculator,think "Combien font 2^10 + 3^5 ?"
# Dans le SDK
response = j.ask("Combien font 2^10 + 3^5 ?", agent="orchestrator", tools=["calculator"])
Le parcours, étape par étape¶
Étape 1 : le chargement de la configuration¶
Tout commence par le chargement de la configuration du système :
Cette étape :
- Détecte le matériel de la machine (fabricant et modèle de la carte graphique, processeur, mémoire vive)
- Recommande le moteur d'inférence le mieux adapté au matériel détecté
- Superpose les réglages que tu as écrits toi-même dans le fichier TOML
- Rend une dataclass
DiapasonConfigportant tous les réglages
Étape 2 : la découverte du moteur¶
Le système cherche ensuite un moteur d'inférence en marche :
La découverte se déroule ainsi :
- Si un moteur précis a été demandé (drapeau
--engine), essayer celui-là - Sinon, essayer le moteur par défaut de la configuration (
"ollama", par exemple) - Si le moteur par défaut ne répond pas, sonder tous les moteurs enregistrés et prendre le premier en bonne santé
- Si aucun moteur n'est disponible, s'arrêter avec un message d'erreur
Étape 3 : la découverte des modèles et leur enregistrement¶
Une fois le moteur trouvé, le système découvre les modèles disponibles :
register_builtin_models() # Enregistre les modèles connus (le catalogue)
all_engines = discover_engines(config)
all_models = discover_models(all_engines)
for ek, model_ids in all_models.items():
merge_discovered_models(ek, model_ids) # Enregistre les modèles découverts à l'exécution
Étape 4 : l'aiguillage du modèle¶
Si aucun modèle n'a été précisé explicitement, la politique d'aiguillage en choisit un :
from diapason.learning import ensure_registered
from diapason.learning.router import build_routing_context
ensure_registered() # S'assure que les politiques d'apprentissage sont enregistrées
policy_key = router_policy or config.learning.routing.policy
router_cls = RouterPolicyRegistry.get(policy_key)
router = router_cls(
available_models=all_models.get(engine_name, []),
default_model=config.intelligence.default_model,
fallback_model=config.intelligence.fallback_model,
)
ctx = build_routing_context(query_text)
model_name = router.select_model(ctx)
La fonction build_routing_context() (dans learning/router.py) examine la question : motifs de code, mots-clés mathématiques, longueur, urgence. L'aiguilleur applique ensuite ses règles — heuristiques ou apprises — pour choisir le modèle le mieux adapté.
Étape 5 : l'injection du contexte mémoire¶
Si l'injection du contexte mémoire est active (true par défaut) et que le moteur de mémoire a des documents indexés :
backend = _get_memory_backend(config)
if backend is not None:
ctx_cfg = ContextConfig(
top_k=config.memory.context_top_k, # Défaut : 5
min_score=config.memory.context_min_score, # Défaut : 0.1
max_context_tokens=config.memory.context_max_tokens, # Défaut : 2048
)
messages = inject_context(query_text, messages, backend, config=ctx_cfg)
Les morceaux pertinents sont extraits du moteur de mémoire et placés en tête, dans un message système qui porte le contexte retrouvé et l'indication de sa source.
Couper l'injection du contexte
Passe --no-context en ligne de commande, ou context=False dans le SDK, pour sauter l'injection du contexte mémoire.
Étape 6 : la génération¶
En mode direct, la question part au moteur par l'enveloppe instrumentée :
result = instrumented_generate(
engine, messages,
model=model_name,
bus=bus,
temperature=temperature,
max_tokens=max_tokens,
)
L'enveloppe instrumented_generate() :
- Publie
INFERENCE_STARTsur le bus d'événements - Note l'heure de départ
- Appelle
engine.generate() - Note l'heure de fin et calcule la latence
- Publie
INFERENCE_END, avec les durées et le compte de jetons - Publie
TELEMETRY_RECORD, avec leTelemetryRecordcomplet
En mode agent, l'agent gère lui-même ses appels d'inférence et peut enchaîner plusieurs tours, avec des appels d'outils entre deux.
Étape 7 : l'exécution des outils (en mode agent seulement)¶
Quand l'OrchestratorAgent trouve des appels d'outils dans la réponse du modèle :
- Chaque appel d'outil est confié au
ToolExecutor - L'exécuteur publie
TOOL_CALL_START, lance l'outil, puis publieTOOL_CALL_END - Les résultats d'outils sont ajoutés à l'historique des messages, sous la forme de messages
TOOL - Les messages ainsi complétés repartent au moteur pour le tour suivant
- La boucle continue jusqu'à ce que le modèle réponde sans appel d'outil, ou que
max_turnssoit atteint
Étape 8 : l'enregistrement de la télémétrie¶
Après chaque appel d'inférence, un TelemetryRecord est créé puis conservé :
@dataclass(slots=True)
class TelemetryRecord:
timestamp: float
model_id: str
prompt_tokens: int
completion_tokens: int
total_tokens: int
latency_seconds: float
ttft: float # Délai jusqu'au premier jeton
cost_usd: float
energy_joules: float
power_watts: float
engine: str
agent: str
metadata: Dict[str, Any]
Le TelemetryStore s'abonne aux événements TELEMETRY_RECORD de l'EventBus et écrit les enregistrements dans ~/.diapason/telemetry.db.
Étape 9 : l'enregistrement de la trace¶
Quand un TraceCollector enveloppe l'agent, une Trace complète est bâtie à partir des événements capturés pendant l'exécution :
- Tous les événements
INFERENCE_START/ENDdeviennent des étapesGENERATE - Tous les événements
TOOL_CALL_START/ENDdeviennent des étapesTOOL_CALL - Tous les événements
MEMORY_RETRIEVEdeviennent des étapesRETRIEVE - Une dernière étape
RESPONDcapture la sortie - La trace est enregistrée dans le
TraceStore, etTRACE_COMPLETEest publié
Étape 10 : la remise de la réponse¶
La réponse finale est remise à l'utilisateur :
- En ligne de commande : écrite sur la sortie standard (ou en JSON avec
--json) - Dans le SDK : rendue comme chaîne par
ask(), ou comme dict parask_full()
Ce qui passe sur l'EventBus pendant une question¶
Voici les événements publiés au cours d'une question ordinaire, en mode agent :
AGENT_TURN_START {agent: "orchestrator", input: "Combien font 2+2 ?"}
INFERENCE_START {model: "qwen3:8b", engine: "ollama", turn: 1}
INFERENCE_END {model: "qwen3:8b", engine: "ollama", turn: 1}
TELEMETRY_RECORD {model_id: "qwen3:8b", latency: 0.8, tokens: 150}
TOOL_CALL_START {tool: "calculator", arguments: {expression: "2+2"}}
TOOL_CALL_END {tool: "calculator", success: true, latency: 0.01}
INFERENCE_START {model: "qwen3:8b", engine: "ollama", turn: 2}
INFERENCE_END {model: "qwen3:8b", engine: "ollama", turn: 2}
TELEMETRY_RECORD {model_id: "qwen3:8b", latency: 0.5, tokens: 80}
AGENT_TURN_END {agent: "orchestrator", turns: 2, content_length: 12}
TRACE_COMPLETE {trace: Trace(...)}
Le parcours d'une question dans le SDK¶
La classe Diapason, dans sdk.py, offre le même parcours par une API Python :
from diapason import Diapason
j = Diapason(model="qwen3:8b", engine_key="ollama")
# Le mode direct
response = j.ask("Bonjour")
# Le mode agent, avec des outils
response = j.ask(
"Combien font 2^10 ?",
agent="orchestrator",
tools=["calculator"],
)
# Le résultat complet, avec ses métadonnées
result = j.ask_full("Bonjour")
# {
# "content": "Bonjour ! Comment puis-je t'aider ?",
# "usage": {"prompt_tokens": 10, "completion_tokens": 15, "total_tokens": 25},
# "model": "qwen3:8b",
# "engine": "ollama",
# }
j.close()
Le SDK s'occupe tout seul de l'initialisation paresseuse du moteur, de la mise en place de la télémétrie, de l'injection du contexte mémoire et de la libération des ressources. La méthode ask() délègue à ask_full() et n'en extrait que la chaîne de contenu.