SPB Git

Repository Public

OPERATIONS.md 7.6 KB

# 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.

text
~/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.

bash
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.log

Arrê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 :

bash
.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

  1. Se connecter au Mac mini (SSH ou clavier) — c'est la preuve d'accès exigée.
  2. cd ~/apps/maclustr-llm && .venv/bin/maclustr-llm recover
  3. Ouvrir le lien affiché, dans les 15 minutes, sur l'appareil qui portera la nouvelle Passkey.
  4. 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.

bash
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 de uv.lock.
  • Migration de base : ajouter une entrée à MIGRATIONS dans db.py (numérotée, transactionnelle) ; elle s'applique au démarrage. Ne jamais modifier une migration déjà appliquée.

# Retour arrière

bash
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) :

bash
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.*.plist

# Sauvegarde 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 de secret.key, archive en mode 600 dans backups/, 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

  1. 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>.
  2. 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).
  3. Pointer ENGINE_MODEL_DIR (deploy/engine.env) et engine_model (config/models.json) vers le modèle, ajuster max_active / token_budget d'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_timeouts qui augmentent (capacité atteinte), moteur healthy: 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
Files main
Menu

Theme