La primitive Intelligence¶
La primitive Intelligence représente le modèle — son identité, ses poids, son format de quantification, sa chaîne de repli, et le catalogue des modèles connus avec leurs métadonnées détaillées. Elle ne porte plus la logique de routage : l'analyse des requêtes et la sélection du modèle ont déménagé dans la primitive Apprentissage.
Son rôle¶
La primitive Intelligence répond à une seule question : quel est le modèle ? Elle tient un catalogue des modèles connus avec leurs métadonnées (nombre de paramètres, longueur de contexte, besoins en VRAM, moteurs compatibles) et offre des fonctions d'aide pour enregistrer les modèles intégrés et y fusionner les modèles découverts à l'exécution auprès des moteurs en marche.
Elle apporte trois capacités clés :
- Le catalogue de modèles — un registre des modèles connus avec leurs métadonnées (nombre de paramètres, longueur de contexte, besoins en VRAM, moteurs compatibles)
- La découverte automatique — la fusion, dans le catalogue, des modèles découverts auprès des moteurs en marche
- La configuration du modèle —
IntelligenceConfigporte l'identité du modèle local, les chemins de ses poids, sa quantification et son moteur préféré
Le routage a déménagé
L'analyse des requêtes (build_routing_context) et la sélection du modèle (HeuristicRouter, l'ABC RouterPolicy) vivent désormais dans la primitive Apprentissage. Des ré-exports de compatibilité ascendante restent dans intelligence/_stubs.py et intelligence/router.py, pour que le code existant continue de fonctionner.
ModelSpec¶
Tout modèle du système est décrit par une dataclass ModelSpec, définie dans core/types.py :
@dataclass(slots=True)
class ModelSpec:
model_id: str # Identifiant unique (par exemple "qwen3:8b")
name: str # Nom lisible par un humain
parameter_count_b: float # Nombre total de paramètres, en milliards
context_length: int # Fenêtre de contexte maximale (en jetons)
active_parameter_count_b: Optional[float] # Paramètres actifs MoE (None si le modèle est dense)
quantization: Quantization # Format de quantification (none, fp8, int4, etc.)
min_vram_gb: float # VRAM minimale requise
supported_engines: Sequence[str] # Moteurs capables de faire tourner ce modèle
provider: str # Fournisseur du modèle (par exemple "alibaba", "meta")
requires_api_key: bool # Faut-il une clé d'API distante
metadata: Dict[str, Any] # Métadonnées supplémentaires (tarif, architecture)
Les modèles s'enregistrent dans le ModelRegistry :
from diapason.core.registry import ModelRegistry
# Enregistrer un modèle
ModelRegistry.register_value("qwen3:8b", ModelSpec(
model_id="qwen3:8b",
name="Qwen3 8B",
parameter_count_b=8.2,
context_length=32768,
supported_engines=("vllm", "ollama", "llamacpp", "sglang"),
provider="alibaba",
))
Le catalogue de modèles¶
Le catalogue intégré est défini dans intelligence/model_catalog.py, sous la forme de la liste BUILTIN_MODELS. Il couvre trois catégories de modèles :
Les modèles locaux — denses¶
| ID du modèle | Nom | Paramètres | Contexte | Moteurs compatibles |
|---|---|---|---|---|
qwen3:8b |
Qwen3 8B | 8.2B | 32K | vLLM, Ollama, llama.cpp, SGLang |
qwen3:32b |
Qwen3 32B | 32B | 32K | Ollama, vLLM |
llama3.3:70b |
Llama 3.3 70B | 70B | 128K | Ollama, vLLM |
llama3.2:3b |
Llama 3.2 3B | 3B | 128K | Ollama, vLLM, llama.cpp |
deepseek-coder-v2:16b |
DeepSeek Coder V2 16B | 16B | 128K | Ollama, vLLM |
mistral:7b |
Mistral 7B | 7B | 32K | Ollama, vLLM, llama.cpp |
Les modèles locaux — mélange d'experts (MoE)¶
| ID du modèle | Nom | Paramètres totaux / actifs | Contexte | VRAM minimale |
|---|---|---|---|---|
gpt-oss:120b |
GPT-OSS 120B | 117B / 5.1B | 128K | 12 Go |
glm-4.7-flash |
GLM 4.7 Flash | 30B / 3B | 128K | 8 Go |
trinity-mini |
Trinity Mini | 26B / 3B | 128K | 8 Go |
Les modèles distants¶
| ID du modèle | Fournisseur | Contexte | Tarif (entrée/sortie par million de jetons) |
|---|---|---|---|
gpt-4o |
OpenAI | 128K | 2,50 $ / 10,00 $ |
gpt-4o-mini |
OpenAI | 128K | 0,15 $ / 0,60 $ |
gpt-5-mini |
OpenAI | 400K | 0,25 $ / 2,00 $ |
claude-sonnet-4-20250514 |
Anthropic | 200K | 3,00 $ / 15,00 $ |
claude-opus-4-20250514 |
Anthropic | 200K | 15,00 $ / 75,00 $ |
claude-opus-4-6 |
Anthropic | 200K | 5,00 $ / 25,00 $ |
gemini-2.5-pro |
1M | 1,25 $ / 10,00 $ | |
gemini-2.5-flash |
1M | 0,30 $ / 2,50 $ |
Enregistrer les modèles intégrés¶
La fonction register_builtin_models() peuple le ModelRegistry avec tous les modèles intégrés. Elle saute ceux qui sont déjà enregistrés : on peut donc l'appeler plusieurs fois sans risque.
from diapason.intelligence import register_builtin_models
register_builtin_models()
# Tous les BUILTIN_MODELS sont maintenant dans le ModelRegistry
La découverte automatique : fusionner les modèles trouvés à l'exécution¶
Quand les moteurs sont découverts à l'exécution, ils annoncent des modèles qui ne sont pas forcément au catalogue intégré. La fonction merge_discovered_models() leur crée des entrées ModelSpec minimales :
from diapason.intelligence import merge_discovered_models
# Les modèles annoncés par Ollama qui ne sont pas au catalogue
merge_discovered_models("ollama", ["phi3:3.8b", "codellama:7b"])
Pour chaque identifiant de modèle absent du registre, une ModelSpec est créée avec l'identifiant du modèle à la fois comme model_id et comme name, et des valeurs nulles par défaut pour les champs inconnus. Le système de routage peut ainsi choisir parmi tous les modèles disponibles, même ceux dont il n'a aucune métadonnée.
IntelligenceConfig¶
La dataclass IntelligenceConfig (dans core/config.py) porte l'identité complète du modèle que le système est configuré pour utiliser, ainsi que les paramètres d'échantillonnage par défaut de la génération :
@dataclass(slots=True)
class IntelligenceConfig:
"""Le modèle — identité, chemins, quantification, chaîne de repli et défauts de génération."""
default_model: str = "" # Clé du modèle principal (par exemple "qwen3:8b")
fallback_model: str = "" # Repli quand le modèle par défaut est indisponible
model_path: str = "" # Poids locaux (dépôt HF, fichier GGUF, etc.)
checkpoint_path: str = "" # Chemin du point de contrôle ou de l'adaptateur (LoRA, par exemple)
quantization: str = "none" # none, fp8, int8, int4, gguf_q4, gguf_q8
preferred_engine: str = "" # Impose un moteur pour ce modèle (par exemple "vllm")
provider: str = "" # local, openai, anthropic, google
# Défauts de génération (chaque appel peut les écraser)
temperature: float = 0.7
max_tokens: int = 1024
top_p: float = 0.9
top_k: int = 40
repetition_penalty: float = 1.0
stop_sequences: str = "" # Chaînes d'arrêt séparées par des virgules
Les champs d'identité du modèle¶
| Champ | Type | Défaut | Description |
|---|---|---|---|
default_model |
str |
"" |
La clé du modèle principal dans le registre. Résolue au démarrage ; elle l'emporte sur tout défaut du moteur. |
fallback_model |
str |
"" |
Utilisé quand le modèle par défaut n'est disponible sur aucun moteur en marche. |
model_path |
str |
"" |
Chemin ou identifiant de dépôt HuggingFace des poids locaux ("./models/qwen3-8b.gguf" ou "Qwen/Qwen3-8B", par exemple). |
checkpoint_path |
str |
"" |
Chemin d'un point de contrôle affiné ou d'un dossier d'adaptateur LoRA. |
quantization |
str |
"none" |
Format de quantification. Valeurs acceptées : none, fp8, int8, int4, gguf_q4, gguf_q8. |
preferred_engine |
str |
"" |
Quand il est posé, SystemBuilder, sdk.py et cli/ask.py prennent cette clé de moteur au lieu de config.engine.default. |
provider |
str |
"" |
Indice sur le fournisseur du modèle : local, openai, anthropic, google. Le moteur Cloud s'en sert pour router les appels d'API. |
Les champs de défauts de génération¶
Ces champs fixent les paramètres d'échantillonnage par défaut de chaque appel d'inférence. Un appel donné peut les écraser en passant des arguments nommés à engine.generate().
| Champ | Type | Défaut | Description |
|---|---|---|---|
temperature |
float |
0.7 |
Température d'échantillonnage. Plus elle est basse, plus la sortie est déterministe ; plus elle est haute, plus elle varie. |
max_tokens |
int |
1024 |
Nombre maximum de jetons à générer par appel. |
top_p |
float |
0.9 |
Masse de probabilité de l'échantillonnage par noyau. À chaque étape, seuls les jetons qui composent la masse top-p sont considérés. |
top_k |
int |
40 |
Échantillonnage top-k : à chaque étape, seuls les k jetons les plus probables sont considérés. |
repetition_penalty |
float |
1.0 |
Pénalise les suites de jetons répétées. Au-delà de 1.0, la répétition diminue. |
stop_sequences |
str |
"" |
Chaînes d'arrêt séparées par des virgules. La génération s'arrête dès qu'une de ces chaînes apparaît dans la sortie. |
Déménagé depuis Agent
Les paramètres de génération (temperature, max_tokens) vivaient auparavant sous [agent] dans le fichier de configuration. Ils vivent désormais sous [intelligence]. Les anciennes configurations qui les portent sous [agent] sont migrées automatiquement au chargement. Voir le guide de migration de la configuration pour le détail.
La configuration TOML¶
[intelligence]
default_model = "qwen3:8b"
fallback_model = "llama3.2:3b"
temperature = 0.7
max_tokens = 1024
# top_p = 0.9
# top_k = 40
# repetition_penalty = 1.0
# stop_sequences = ""
# Pour imposer des poids locaux (facultatif)
# model_path = "./models/qwen3-8b-instruct.gguf"
# checkpoint_path = "./checkpoints/my-lora"
# quantization = "gguf_q4"
# Le moteur choisi pour ce modèle (prioritaire sur [engine].default)
# preferred_engine = "vllm"
# Le fournisseur, pour les modèles distants
# provider = "openai"
L'ordre de priorité du choix du moteur¶
Au moment de décider quel moteur utiliser, SystemBuilder, sdk.py et cli/ask.py regardent config.intelligence.preferred_engine avant config.engine.default :
1. L'option --engine de la CLI, ou le paramètre engine_key= du SDK
2. config.intelligence.preferred_engine ← le nouveau champ
3. config.engine.default
4. Le premier moteur en bonne santé découvert à l'exécution
Tu peux ainsi épingler un modèle donné à un moteur donné sans toucher au moteur par défaut du système. Un modèle quantifié en GGUF, par exemple, peut être épinglé à llamacpp pendant que le défaut global reste ollama :
[engine]
default = "ollama"
[intelligence]
default_model = "llama3.2:3b"
model_path = "./models/llama-3.2-3b.Q4_K_M.gguf"
quantization = "gguf_q4"
preferred_engine = "llamacpp"
L'API publique¶
intelligence/__init__.py exporte exactement trois noms :
from diapason.intelligence import (
BUILTIN_MODELS, # List[ModelSpec] — le catalogue intégré complet
merge_discovered_models, # (engine_key, model_ids) -> None
register_builtin_models, # () -> None
)
Les cales de compatibilité ascendante¶
Les noms suivants restent importables depuis diapason.intelligence par des modules-cales, mais leur emplacement canonique a changé :
| Nom | Ancien emplacement | Emplacement canonique |
|---|---|---|
RouterPolicy |
intelligence/_stubs.py |
learning/_stubs.py |
QueryAnalyzer |
intelligence/_stubs.py |
learning/_stubs.py |
HeuristicRouter |
intelligence/router.py |
learning/router.py |
build_routing_context |
intelligence/router.py |
learning/router.py |
DefaultQueryAnalyzer |
intelligence/router.py |
learning/router.py |
Le code neuf doit importer depuis les emplacements canoniques learning.*. Les cales de intelligence/_stubs.py et intelligence/router.py ne sont gardées que pour la compatibilité ascendante.
L'intégration avec Apprentissage¶
La primitive Apprentissage consomme le catalogue de modèles pour prendre ses décisions de routage. HeuristicRouter et TraceDrivenPolicy lisent tous deux le ModelRegistry pour comparer les tailles des modèles au moment de départager des candidats. Voir la documentation Apprentissage et traces pour tout le détail des politiques de routage, de l'ABC RouterPolicy et de la boucle de rétroaction guidée par les traces.