SPB Git

Repository Public

RAPPORT-FINAL.md 7.1 KB

# Rapport final de déploiement — MacLustr LLM API

Date : 2026-11-19 · Version 1.0.0 · https://llm.spboucher.ai

# 1. Ce qui est en production

Élément État
Machine Mac mini M4 Pro, 48 Go (nœud m4mm du cluster), épinglé à ce projet dans mld
Modèle maclustr-qwen3 = mlx-community/Qwen3-30B-A3B-Instruct-2507-4bit, révision e9675aa3ca5f…, Apache-2.0, 14 fichiers vérifiés (SHA-256)
Moteur Apple MLX 0.32.4 / MLX-LM 0.32.2 (Metal), 127.0.0.1:8811, lot continu de 8, cache de préfixes 2 Go
Passerelle FastAPI, port 8810, base SQLite, site statique
Services launchd ai.spboucher.maclustr-llm.engine, .gateway, .backup (toutes les 24 h)
HTTPS Caddy sur la passerelle du cluster (certificat Let's Encrypt), WireGuard jusqu'au Mac mini
Code dépôt spbgit maclustr-llm.git, clone sur le nœud ~/apps/maclustr-llm, copie de création ~/Desktop/Cluster/projets/maclustr-llm

# 2. Critères d'acceptation

Critère Résultat Preuve
Le modèle fonctionne réellement sur le M4 Pro ✅ scripts/e2e_live.py : 14/14 contre la production
L'inférence utilise MLX localement ✅ moteur mlx_lm, /internal/stats (17,2 Go de mémoire MLX active), aucun appel sortant
Le modèle reste chargé entre les requêtes ✅ processus résident ; premier token en 111 ms
L'API fonctionne en HTTPS ✅ deploy/verify.sh https://llm.spboucher.ai
Les SDK compatibles OpenAI fonctionnent ✅ SDK officiel openai non modifié (tests + production)
Le streaming fonctionne ✅ 80 deltas reçus, usage final, à travers Caddy
Requêtes concurrentes gérées ✅ 1 à 16 clients, 0 erreur ; 8 actives + file au-delà
Mémoire sous contrôle ✅ pic 33,9 Go avec 82 000 tokens en vol, swap 0, pression normale ; budget de 48 000 tokens en production
Documentation publique accessible ✅ /, /docs/*, /status, /openapi.json
Le Playground utilise le vrai moteur ✅ appelle /v1/chat/completions ; aucun moteur simulé en production
Dashboard inaccessible sans authentification ✅ toutes les routes /admin/api/* → 401 (tests + production)
Passkey configurable par lien unique ✅ côté serveur et navigateur (authentificateur virtuel) tests/test_auth.py, parcours Playwright ; à faire par le propriétaire sur son appareil
Touch ID / Face ID sur appareils compatibles ⚠️ non vérifié sur appareil physique WebAuthn standard, vérification utilisateur exigée
Clés API créées et révoquées ✅ Dashboard, CLI, tests
Métriques réelles ✅ psutil, sysctl, ioreg, statistiques du moteur ; température signalée « non mesurable »
Le service redémarre correctement ✅ kill -9 du moteur : relancé et prêt en 1 s ; passerelle : 6 s
Benchmarks exécutés ✅ docs/BENCHMARKS.md, rapports bruts dans docs/bench-reports/
Tests de sécurité essentiels ✅ 15 tests d'authentification et de confidentialité
Performances et limites documentées ✅ docs/BENCHMARKS.md, page Performance du site

# 3. Mesures clés (production, à travers la passerelle)

Mesure Valeur
Flux unique 80,6 tokens/s, premier token 111 ms
8 générations simultanées 155,8 tokens/s au total, 20,4 par requête, premier token p95 695 ms
16 clients 156,8 tokens/s, 0 erreur (8 en file, premier token p50 13,3 s)
Cache de préfixes (2 304 tokens) 3 564 ms à froid → 147 ms
Prompt de 12 275 tokens jamais vu premier token en 27,4 s
Qualité (41 items) 40/41

# 4. Livrables

1–5. Code source, moteur MLX, modèle installé, API compatible OpenAI, passerelle sécurisée — src/maclustr_llm/ 6–8. Portail de documentation, Playground, Dashboard — web/ 9–10. Passkeys et lien d'activation unique — auth.py, cli.py, web/setup.html 11. Gestion des clés API — keys.py, Dashboard, CLI 12. Monitoring réel — sysmon.py, metrics.py 13. Benchmarks reproductibles — bench/, docs/BENCHMARKS.md 14–15. Services launchd et HTTPS — deploy/, manifeste mld 16. Tests automatisés — 53 tests + validation en production 17–19. Exploitation, récupération, sauvegarde et retour arrière — docs/OPERATIONS.md 20. Ce rapport, avec docs/AUDIT-INITIAL.md, ARCHITECTURE.md, SECURITY.md

# 5. Écarts par rapport au cahier des charges

Sujet Décision
Variante du modèle le cahier citait Qwen3-30B-A3B 4 bits ; la variante Instruct-2507 de la même famille est servie car elle obtient 40/41 contre 37/41 (38/41 avec raisonnement, six fois plus lent), à vitesse égale
Modèle secondaire aucun : Qwen3-8B est plus lent par flux (51,7 tokens/s) et moins bon (36/41)
/v1/responses, /v1/embeddings non implémentés, donc non annoncés
Sorties JSON validées côté serveur (réparation automatique, 422 sinon), pas contraintes par grammaire ; garantie en non-streaming
tool_choice auto et none seulement (le moteur ne sait pas forcer un outil)
Température du Mac non lisible sans privilèges : affichée « non mesurable »
Ajout de modèle depuis le Dashboard consultation et rechargement seulement ; l'ajout se fait par le catalogue (docs/OPERATIONS.md)
CI script local scripts/ci.sh (la forge spbgit n'exécute pas de pipelines)
Messages d'erreur de l'API en français

# 6. Reste à faire par le propriétaire

  1. Activer l'administrateur : sur le Mac mini, maclustr-llm setup-link, puis ouvrir le lien dans les 15 minutes sur l'appareil qui portera la Passkey. C'est aussi la première vérification réelle de Touch ID / Face ID.
  2. Créer une clé API par application dans le Dashboard, puis révoquer la clé « Validation e2e » créée pour les tests.
  3. Décider du redémarrage de Caddy sur la passerelle du cluster (voir § 7).

# 7. Incidents pendant le déploiement

  • Client Xet de Hugging Face figé : téléchargements bloqués à 67 Mo ; contourné par HTTP direct, intégrité revérifiée.
  • Fuite de place sous annulation (trouvée par les tests avant la mise en production) : un client qui se déconnectait en streaming ne rendait pas sa place au moteur. Corrigé (libération synchrone et idempotente, y compris quand le flux n'est jamais lu) ; couvert par quatre tests.
  • Caddy sur la passerelle du cluster : le rechargement qui a ajouté la route llm.spboucher.ai a appliqué la configuration (tous les sites répondent), mais l'API d'administration de Caddy ne répond plus et systemd le voit toujours « en rechargement ». Tant que Caddy n'est pas redémarré, aucune autre route du cluster ne peut être ajoutée ou déplacée. Un redémarrage coupe tous les sites publics une à deux secondes : laissé à la décision du propriétaire.
  • tunnelctl (passerelle du cluster) accepte désormais un fichier de directives par site (/etc/caddy/site-extras/<domaine>.caddy) ; celui de llm.spboucher.ai exclut /setup/* du journal d'accès. Sauvegarde de l'ancienne version : /usr/local/bin/tunnelctl.bak-20261119.
Files main
Menu

Theme