Exploitation — MacLustr LLM API
Nœud : m4mm (Mac mini M4 Pro, 48 Go) · code ~/apps/maclustr-llm (clone git, origin spbgit
maclustr-llm.git) · état ~/maclustr-llm-data/ (hors dépôt) · app mld maclustr-llm, épinglée.
~/maclustr-llm-data/
├── gateway.sqlite3 base (clés hachées, sessions, usage, audit) — mode 600
├── secret.key clé serveur des condensats — mode 600, À SAUVEGARDER avec la base
├── models/<modèle>/ poids MLX + INTEGRITY.json (SHA-256 vérifiés)
├── logs/ gateway.log, engine.log (rotation 5 × 20 Mo)
├── bench/ rapports de benchmarks (JSON)
└── backups/ sauvegardes quotidiennes (14 jours)Services
| Service launchd (session utilisateur) | Processus | Port |
|---|---|---|
ai.spboucher.maclustr-llm.engine |
moteur MLX (deploy/run-engine.sh) |
127.0.0.1:8811 |
ai.spboucher.maclustr-llm.gateway |
API Gateway (deploy/run-gateway.sh) |
8810 |
ai.spboucher.maclustr-llm.backup |
sauvegarde toutes les 24 h (scripts/backup.sh) |
— |
RunAtLoad + KeepAlive : démarrage à l'ouverture de session (automatique après une coupure de courant),
relance après tout arrêt. mld heal (toutes les 5 minutes depuis la passerelle du cluster) recharge un
service absent et rétablit la route publique.
U=gui/$(id -u)
launchctl print $U/ai.spboucher.maclustr-llm.engine | egrep 'state|pid|last exit'
launchctl kickstart -k $U/ai.spboucher.maclustr-llm.gateway # redémarrer la passerelle (~2 s)
launchctl kickstart -k $U/ai.spboucher.maclustr-llm.engine # recharger le modèle (~5 s, 503 pendant ce temps)
deploy/verify.sh https://llm.spboucher.ai # contrôle complet local + public
tail -f ~/maclustr-llm-data/logs/gateway.logArrêt propre : launchd envoie SIGTERM ; la passerelle laisse 30 s aux requêtes en cours, vide ses compteurs en base, puis s'arrête ; le moteur termine sa boucle et libère la mémoire GPU.
Administration locale (CLI)
Toujours depuis ~/apps/maclustr-llm, sur le Mac mini :
.venv/bin/maclustr-llm status # activation, Passkeys, sessions, clés
.venv/bin/maclustr-llm setup-link # activation initiale (lien 15 min, usage unique)
.venv/bin/maclustr-llm recover # Passkeys perdues : nouveau lien, révoque les sessions
.venv/bin/maclustr-llm revoke-sessions # ferme toutes les sessions admin
.venv/bin/maclustr-llm key create --name "SP Chat" --app "SP Chat" --priority internal
.venv/bin/maclustr-llm key list | revoke <id>Récupération de l'accès administrateur
- Se connecter au Mac mini (SSH ou clavier) — c'est la preuve d'accès exigée.
cd ~/apps/maclustr-llm && .venv/bin/maclustr-llm recover- Ouvrir le lien affiché, dans les 15 minutes, sur l'appareil qui portera la nouvelle Passkey.
- Dans le Dashboard → Sécurité : supprimer les Passkeys perdues.
Mise à jour
Le code se modifie sur le nœud (règle remote-first du cluster), puis se pousse sur spbgit.
cd ~/apps/maclustr-llm
git status && git pull --ff-only # ou modifier, tester, puis commit
scripts/ci.sh # lint, typage, tests, audit des dépendances (≈ 1 min)
scripts/backup.sh # sauvegarde avant changement
deploy/install.sh # dépendances verrouillées, migrations, rechargement des services
git tag -a vX.Y.Z -m "…" && git push origin main --tags- Passerelle seule (cas courant) :
launchctl kickstart -k gui/$(id -u)/ai.spboucher.maclustr-llm.gateway— interruption d'environ 2 secondes, le modèle reste chargé. - Site statique (
web/) : aucun redémarrage, les fichiers sont servis tels quels. - Dépendances : modifier
pyproject.toml,uv lock,scripts/ci.sh, commit deuv.lock. - Migration de base : ajouter une entrée à
MIGRATIONSdansdb.py(numérotée, transactionnelle) ; elle s'applique au démarrage. Ne jamais modifier une migration déjà appliquée.
Retour arrière
cd ~/apps/maclustr-llm
git log --oneline -5 && git checkout <tag-ou-commit-précédent>
deploy/install.sh # réinstalle les dépendances de cette version
scripts/backup.sh restore ~/maclustr-llm-data/backups/gateway-<date>.tar.gz # seulement si la base a migréLes migrations sont additives ; un retour de code sans restauration de base fonctionne tant que la version visée connaît le schéma. En cas de doute, restaurer la sauvegarde faite avant la mise à jour.
Retrait complet (rien d'autre n'a été modifié sur le nœud) :
mld retire maclustr-llm # depuis le laptop : arrête les services, retire la route publique
rm -rf ~/apps/maclustr-llm ~/maclustr-llm-data ~/Library/LaunchAgents/ai.spboucher.maclustr-llm.*.plistSauvegarde et restauration
scripts/backup.sh: copie cohérente de la base par l'API de sauvegarde en ligne de SQLite, contrôle d'intégrité, ajout desecret.key, archive en mode 600 dansbackups/, rotation à 14 jours.- Sans
secret.key, les clés API et les sessions de la base sont invérifiables : les deux vont ensemble. - Les poids ne sont pas sauvegardés :
scripts/model.py fetch <id>retélécharge la révision épinglée et revérifie les SHA-256. - Reconstruction sur un autre Mac : cloner le dépôt,
deploy/install.sh --no-services, restaurer l'archive,mld deploy maclustr-llm --node <nœud>(après avoir changé l'épinglage du manifeste).
Changer de modèle ou de réglages
- Télécharger et vérifier : ajouter le modèle à
config/models.json(dépôt + révision exacte), puis.venv/bin/python scripts/model.py fetch <id>. - Mesurer avant de servir :
bench/compare.sh <label> <dossier>(qualité + vitesse, moteur de mesure sur un port à part — nécessite d'arrêter le moteur de production si la mémoire ne suffit pas pour deux modèles). - Pointer
ENGINE_MODEL_DIR(deploy/engine.env) etengine_model(config/models.json) vers le modèle, ajustermax_active/token_budgetd'après les mesures, puis redémarrer moteur et passerelle.
Réglages du moteur (deploy/engine.env) et de la passerelle (deploy/gateway.env) : voir les commentaires
des fichiers ; surcharges locales non versionnées possibles dans ~/.config/maclustr-llm/{engine,gateway}.env.
Surveillance
- Public :
https://llm.spboucher.ai/status,GET /health(passerelle),GET /ready(moteur prêt). - Privé : Dashboard
/admin(vue générale, monitoring du Mac, analytics, journal d'audit). - Signaux à surveiller :
pressure≠normal, swap utilisé qui croît,rejected/queue_timeoutsqui augmentent (capacité atteinte), moteurhealthy: false.
Dépannage
| Symptôme | Cause probable | Action |
|---|---|---|
503 engine_unavailable |
moteur en cours de (re)chargement ou arrêté | launchctl print …engine, tail logs/engine.log |
503 engine_overloaded / queue_timeout |
plus de demande que de capacité | normal sous pointe ; voir Analytics, ajuster quotas ou max_active |
503 memory_pressure |
pression mémoire critique | chercher le processus gourmand (top -o mem), réduire token_budget |
| 504 en non-streaming | génération > 280 s | utiliser stream: true |
| Téléchargement de modèle figé | client Xet | scripts/model.py fetch force déjà HF_HUB_DISABLE_XET=1 |
| Passkey refusée (« clé d'accès non reconnue ») | Passkey supprimée ou autre domaine | maclustr-llm status, sinon recover |
| Site public en erreur 502 | tunnel ou passerelle arrêtés | mld status --live, mld heal, deploy/verify.sh https://llm.spboucher.ai |