# 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
- 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.
- Créer une clé API par application dans le Dashboard, puis révoquer la clé « Validation e2e » créée pour les tests.
- 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.