SPB Git

Repository Public

RAPPORT-FINAL.md 7.1 KB 100 lines markdown

1# Rapport final de déploiement — MacLustr LLM API23**Date : 2026-11-19 · Version 1.0.0 · https://llm.spboucher.ai**45## 1. Ce qui est en production67| Élément | État |8|---|---|9| Machine | Mac mini M4 Pro, 48 Go (nœud `m4mm` du cluster), épinglé à ce projet dans `mld` |10| 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) |11| 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 |12| Passerelle | FastAPI, port 8810, base SQLite, site statique |13| Services | launchd `ai.spboucher.maclustr-llm.engine`, `.gateway`, `.backup` (toutes les 24 h) |14| HTTPS | Caddy sur la passerelle du cluster (certificat Let's Encrypt), WireGuard jusqu'au Mac mini |15| 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` |1617## 2. Critères d'acceptation1819| Critère | Résultat | Preuve |20|---|---|---|21| Le modèle fonctionne réellement sur le M4 Pro | ✅ | `scripts/e2e_live.py` : 14/14 contre la production |22| L'inférence utilise MLX localement | ✅ | moteur `mlx_lm`, `/internal/stats` (17,2 Go de mémoire MLX active), aucun appel sortant |23| Le modèle reste chargé entre les requêtes | ✅ | processus résident ; premier token en 111 ms |24| L'API fonctionne en HTTPS | ✅ | `deploy/verify.sh https://llm.spboucher.ai` |25| Les SDK compatibles OpenAI fonctionnent | ✅ | SDK officiel `openai` non modifié (tests + production) |26| Le streaming fonctionne | ✅ | 80 deltas reçus, usage final, à travers Caddy |27| Requêtes concurrentes gérées | ✅ | 1 à 16 clients, 0 erreur ; 8 actives + file au-delà |28| 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 |29| Documentation publique accessible | ✅ | `/`, `/docs/*`, `/status`, `/openapi.json` |30| Le Playground utilise le vrai moteur | ✅ | appelle `/v1/chat/completions` ; aucun moteur simulé en production |31| Dashboard inaccessible sans authentification | ✅ | toutes les routes `/admin/api/*` → 401 (tests + production) |32| 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** |33| Touch ID / Face ID sur appareils compatibles | ⚠️ non vérifié sur appareil physique | WebAuthn standard, vérification utilisateur exigée |34| Clés API créées et révoquées | ✅ | Dashboard, CLI, tests |35| Métriques réelles | ✅ | psutil, sysctl, ioreg, statistiques du moteur ; température signalée « non mesurable » |36| Le service redémarre correctement | ✅ | `kill -9` du moteur : relancé et prêt en 1 s ; passerelle : 6 s |37| Benchmarks exécutés | ✅ | `docs/BENCHMARKS.md`, rapports bruts dans `docs/bench-reports/` |38| Tests de sécurité essentiels | ✅ | 15 tests d'authentification et de confidentialité |39| Performances et limites documentées | ✅ | `docs/BENCHMARKS.md`, page Performance du site |4041## 3. Mesures clés (production, à travers la passerelle)4243| Mesure | Valeur |44|---|---|45| Flux unique | 80,6 tokens/s, premier token 111 ms |46| 8 générations simultanées | 155,8 tokens/s au total, 20,4 par requête, premier token p95 695 ms |47| 16 clients | 156,8 tokens/s, 0 erreur (8 en file, premier token p50 13,3 s) |48| Cache de préfixes (2 304 tokens) | 3 564 ms à froid → 147 ms |49| Prompt de 12 275 tokens jamais vu | premier token en 27,4 s |50| Qualité (41 items) | 40/41 |5152## 4. Livrables53541–5. Code source, moteur MLX, modèle installé, API compatible OpenAI, passerelle sécurisée — `src/maclustr_llm/`556–8. Portail de documentation, Playground, Dashboard — `web/`569–10. Passkeys et lien d'activation unique — `auth.py`, `cli.py`, `web/setup.html`5711. Gestion des clés API — `keys.py`, Dashboard, CLI5812. Monitoring réel — `sysmon.py`, `metrics.py`5913. Benchmarks reproductibles — `bench/`, `docs/BENCHMARKS.md`6014–15. Services launchd et HTTPS — `deploy/`, manifeste `mld`6116. Tests automatisés — 53 tests + validation en production6217–19. Exploitation, récupération, sauvegarde et retour arrière — `docs/OPERATIONS.md`6320. Ce rapport, avec `docs/AUDIT-INITIAL.md`, `ARCHITECTURE.md`, `SECURITY.md`6465## 5. Écarts par rapport au cahier des charges6667| Sujet | Décision |68|---|---|69| 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 |70| Modèle secondaire | aucun : Qwen3-8B est plus lent par flux (51,7 tokens/s) et moins bon (36/41) |71| `/v1/responses`, `/v1/embeddings` | non implémentés, donc non annoncés |72| Sorties JSON | validées côté serveur (réparation automatique, 422 sinon), pas contraintes par grammaire ; garantie en non-streaming |73| `tool_choice` | `auto` et `none` seulement (le moteur ne sait pas forcer un outil) |74| Température du Mac | non lisible sans privilèges : affichée « non mesurable » |75| Ajout de modèle depuis le Dashboard | consultation et rechargement seulement ; l'ajout se fait par le catalogue (`docs/OPERATIONS.md`) |76| CI | script local `scripts/ci.sh` (la forge spbgit n'exécute pas de pipelines) |77| Messages d'erreur de l'API | en français |7879## 6. Reste à faire par le propriétaire80811. **Activer l'administrateur** : sur le Mac mini, `maclustr-llm setup-link`, puis ouvrir le lien dans les 15 minutes82   sur l'appareil qui portera la Passkey. C'est aussi la première vérification réelle de Touch ID / Face ID.832. Créer une clé API par application dans le Dashboard, puis révoquer la clé « Validation e2e » créée pour les tests.843. Décider du redémarrage de Caddy sur la passerelle du cluster (voir § 7).8586## 7. Incidents pendant le déploiement8788- **Client Xet de Hugging Face figé** : téléchargements bloqués à 67 Mo ; contourné par HTTP direct, intégrité revérifiée.89- **Fuite de place sous annulation** (trouvée par les tests avant la mise en production) : un client qui se90  déconnectait en streaming ne rendait pas sa place au moteur. Corrigé (libération synchrone et idempotente,91  y compris quand le flux n'est jamais lu) ; couvert par quatre tests.92- **Caddy sur la passerelle du cluster** : le rechargement qui a ajouté la route `llm.spboucher.ai` a appliqué la93  configuration (tous les sites répondent), mais l'API d'administration de Caddy ne répond plus et systemd le94  voit toujours « en rechargement ». Tant que Caddy n'est pas redémarré, aucune autre route du cluster ne peut être95  ajoutée ou déplacée. Un redémarrage coupe tous les sites publics une à deux secondes : laissé à la décision du96  propriétaire.97- `tunnelctl` (passerelle du cluster) accepte désormais un fichier de directives par site98  (`/etc/caddy/site-extras/<domaine>.caddy`) ; celui de `llm.spboucher.ai` exclut `/setup/*` du journal d'accès.99  Sauvegarde de l'ancienne version : `/usr/local/bin/tunnelctl.bak-20261119`.100
Files main
Menu

Theme