IngeniumDL/ingenium-expert-lms-3b-instruct-gguf

Ingenium Expert LMS 3B Instruct — GGUF (Ollama, CPU)

Paquet de déploiement complet du candidat Ingenium Expert LMS 3B Instruct : routeur grounded fusionné LoRA sur mistralai/Ministral-3-3B-Instruct-2512-BF16, converti en GGUF texte et quantifié Q8_0, servi par Ollama sur CPU. Frère cadet du candidat 8B/GPU (IngeniumDL/ingenium-expert-lms-8b-instruct) : même produit, même harnais, même dataset — seuls le modèle de base et le moteur d'inférence changent.

Le modèle ne récite pas les procédures depuis ses poids : il comprend la demande et route vers un registre fermé ; le harnais fourni dans ce paquet rend ensuite la fiche canonique. Utiliser les poids seuls, sans le harnais, retire le garde de périmètre, la validation de schéma et le rendu canonique — voir « Utilisation directe » plus bas pour ce que cela signifie concrètement.

Déployer avec Docker Compose (recommandé)

Prérequis : Linux x86-64, Docker, Docker Compose. Aucun GPU requis.

hf download IngeniumDL/ingenium-expert-lms-3b-instruct-gguf --local-dir ingenium-3b-gguf
cd ingenium-3b-gguf

GGUF_PATH=./ingenium-expert-lms-3b-instruct-grounded-v0.1.0-Q8_0.gguf \
  docker compose -f docker-compose.cpu.yml up --build --detach

Le premier démarrage construit l'image Ollama et crée le modèle à partir du GGUF (quelques dizaines de secondes). Le harnais attend qu'Ollama soit prêt avant de démarrer.

curl http://127.0.0.1:8080/health

curl -X POST http://127.0.0.1:8080/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Comment créer un utilisateur dans Moodle ?",
    "context": {
      "moodle_release": "4.5.12 (Build: 20260608)",
      "moodle_version_code": "2024100712",
      "branch": "405",
      "locale": "fr",
      "theme": "boost",
      "route_class": "admin_users",
      "capabilities": {"moodle/user:create": true}
    }
  }'

Arrêt propre :

docker compose -f docker-compose.cpu.yml down

Seul le harnais est exposé (127.0.0.1:8080) ; Ollama reste sur le réseau interne du compose et n'est jamais joignable directement, comme pour le paquet 8B/vLLM.

CLI de test utilisateur

Un client Go (CLI-LLM/ingenium-cli, Linux x86-64 statique) permet de tester la chaîne réelle CLI → harnais → Ollama sans manipuler le JSON de l'API :

chmod +x CLI-LLM/ingenium-cli
./CLI-LLM/ingenium-cli --profile learner "Comment déposer mon devoir dans Moodle ?"
./CLI-LLM/ingenium-cli --profile admin "Comment créer un utilisateur dans Moodle ?"

Le profil par défaut est learner. Les profils admin, teacher, learner et guest simulent uniquement les capacités du contexte de test, pas un mécanisme d'authentification.

Utilisation directe avec Ollama (sans harnais)

Pour inspecter le modèle seul, sans le harnais :

ollama create ingenium-expert-lms-3b-instruct -f deploy/ollama/Modelfile.ingenium-3b
ollama run ingenium-expert-lms-3b-instruct

Le Modelfile fourni est requis, pas seulement recommandé : Ollama ne traduit pas automatiquement le chat_template.jinja Mistral embarqué dans le GGUF. Sans le TEMPLATE explicite du Modelfile, Ollama retombe sur un gabarit brut qui ignore la structure système/utilisateur attendue par le modèle et dégrade fortement la qualité des réponses (constaté empiriquement).

Appelé seul, le modèle répond par un objet JSON routing-v1 — un guide_id (ou module_ids), un scope/status et une confiance, jamais les étapes détaillées ni le contenu d'une formation :

{"scope":"IN_DOMAIN","domain":"MOODLE_USAGE","status":"ANSWER","guide_id":"core.admin.user.create","confidence":"high"}

Sans le harnais, rien ne garantit que guide_id existe réellement dans un registre de procédures, que des étapes affichées à l'utilisateur sont correctes, ni que les capacités requises sont respectées. C'est le rôle du harnais fourni dans ce paquet (harness/, src/, config/, schemas/, data/) de refermer ces garanties.

Mode JSON — limite connue. response_format: {"type": "json_object"} est accepté par l'API compatible OpenAI d'Ollama mais n'est pas un décodage contraint par grammaire comme sur vLLM : la validité JSON constatée (800/800 sur la campagne de qualification scellée) repose sur l'entraînement du modèle, pas sur une garantie structurelle du moteur.

Contenu du paquet

Chemin	Rôle
ingenium-expert-lms-3b-instruct-grounded-v0.1.0-Q8_0.gguf	poids quantifiés Q8_0 (texte uniquement, tour vision exclue)
deploy/ollama/Modelfile.ingenium-3b	Modelfile Ollama (gabarit de chat, température, contexte) utilisé par le compose
schemas/	contrats context-v1, procedure-v1, module-v1, routing-v1 et response-v2
config/guides-v1.json, config/module-registry-v1.json	registres d'identifiants fermés
config/capabilities-v1.json	capacités Moodle acceptées dans le contexte
config/routing-prompt-v1.txt	system prompt envoyé au modèle par le harnais
data/procedures/, data/modules/	contenu canonique rendu par le harnais
harness/, src/	garde, correspondance catalogue, validation et rendu fail-closed
docker/ollama/, docker-compose.cpu.yml	image Ollama personnalisée et paquet de déploiement CPU
CLI-LLM/	binaire Linux x86-64 et sources Go du client
merge-report.json	inventaire SHA-256 du modèle fusionné
docs/creer-des-fiches.md	procédure détaillée pour ajouter de nouvelles connaissances (procédures, formations)

Entraînement et qualification

• base mistralai/Ministral-3-3B-Instruct-2512-BF16, révision d8d116d9345d21aa3df1b76bf8a9a1a29d0ced1e ;
• LoRA BF16 rang 32, alpha 64, dropout 0,05, longueur 2048, lot effectif 32, sur NVIDIA L40S ; arrêt anticipé à l'étape 80/100, meilleur checkpoint à l'étape 20 ;
• même dataset et mêmes 50 procédures / 7 modules que le candidat 8B ;
• fusionné, converti en GGUF texte avec llama.cpp (convert_hf_to_gguf.py puis llama-quantize … Q8_0) ;
• qualifié sur les mêmes 800 cas scellés que le 8B, servi entièrement sur CPU (15 vCPU, sans GPU) : décision exacte 98,0 % (784/800), adversarial 98/100, hors domaine 100/100, abstention sûre 215/215, latence du routeur p95 3,13 s.

Comparé au service 8B/vLLM qualifié (décision exacte 98,75 %, adversarial 96/100, p95 1,21 s sur GPU à concurrence 4), ce candidat CPU obtient une qualité quasi identique avec une latence plus élevée mais sans dépendance GPU.

Agrandir les connaissances (nouvelles procédures, nouvelles formations)

Le modèle ne récite jamais une procédure depuis ses poids : il choisit un identifiant dans un registre fermé (config/guides-v1.json, config/module-registry-v1.json), le harnais rend ensuite la fiche canonique stockée dans data/procedures/ ou data/modules/. Ajouter une connaissance consiste donc à enrichir ces registres, pas à réécrire le modèle :

• corriger une fiche déjà approuvée (texte d'une étape, capacité manquante) ne demande aucun réentraînement — le harnais sert la version corrigée dès que les fichiers sont régénérés ;
• ajouter un nouvel identifiant bénéficie d'une généralisation mesurée (95 à 100 % sur les procédures/modules holdout des campagnes scellées, le modèle raisonne sur la carte du candidat plutôt que de la mémoriser) mais un réentraînement reste recommandé pour une fiabilité de production.

La procédure complète — blueprint de la fiche, validation contre le code Moodle réel, enregistrement dans le registre de routage, requalification du routeur — est détaillée dans docs/creer-des-fiches.md.

Limites connues

• Fenêtre de contexte et route_class: "unknown". Une question du domaine MOODLE_USAGE reçue avec route_class: "unknown" fait retomber le harnais sur les 50 procédures complètes comme candidats, produisant un prompt d'environ 3700 tokens — au-delà des 2048 tokens vus à l'entraînement. num_ctx a été porté à 4096 dans le Modelfile pour éviter un échec de transport ; testé manuellement, le modèle a correctement identifié la procédure malgré cette longueur inhabituelle, mais avec une latence proche de 30 s et sans garantie de qualité au-delà de cet essai ponctuel. Cette lacune de couverture affecte probablement aussi le service 8B/vLLM, qui partage le même harnais.
• Débit. Ollama sert par défaut une requête à la fois (OLLAMA_NUM_PARALLEL=1) ; la qualification a été menée à concurrence 1.
• Statut POC. Données de fabrication synthétiques, revue métier indépendante requise avant toute utilisation réelle. Ne pas transmettre de données personnelles.

Traçabilité

Consulter merge-report.json pour l'inventaire SHA-256 du modèle fusionné, les révisions et versions logicielles.