Architecture — MacLustr LLM API
Vue d'ensemble
flowchart LR
C["Clients<br/>SDK OpenAI, apps web / macOS / iOS, agents"] -- HTTPS --> P["Caddy · BHS64<br/>TLS Let's Encrypt"]
P -- "WireGuard wg1" --> G
subgraph M["Mac mini M4 Pro · 48 Go (m4mm)"]
G["API Gateway · :8810<br/>FastAPI / uvicorn"]
E["Moteur MLX · 127.0.0.1:8811<br/>mlx_lm durci"]
D[("SQLite WAL<br/>clés hachées, sessions,<br/>usage, audit")]
W["Site statique<br/>docs · playground · dashboard"]
G --> E
G --- D
G --- W
E --> GPU["GPU M4 Pro (Metal)<br/>mémoire unifiée"]
end
Deux processus, deux responsabilités :
| Processus | Rôle | Écoute | Service launchd |
|---|---|---|---|
Moteur (maclustr_llm.engine_main) |
garde le modèle en mémoire GPU, génère | 127.0.0.1:8811 uniquement |
ai.spboucher.maclustr-llm.engine |
Passerelle (maclustr_llm.app) |
tout le reste : API, sécurité, file, métriques, site | :8810 (LAN + wg1) |
ai.spboucher.maclustr-llm.gateway |
La passerelle est indépendante du moteur : elle reste debout quand le moteur redémarre (réponses 503
engine_unavailable, /ready à 503, /health à 200) et reprend seule dès que le modèle est rechargé.
Moteur d'inférence
engine_main.py lance le serveur de mlx_lm (Apple MLX, Metal) avec quatre durcissements :
- Modèle verrouillé — le serveur d'origine charge (et télécharge) tout modèle nommé dans une requête ;
ici seule la valeur
default_modelest acceptée, sans adaptateur ni modèle brouillon. - Préchargement et réchauffage au démarrage ;
readyne passe à vrai qu'après une vraie génération. /internal/stats: mémoire MLX réelle (active, pic, cache), cache de préfixes, tailles de lot, versions.- Plafonds mémoire MLX explicites, journal tournant, arrêt propre sur SIGTERM.
Fonctions d'inférence réellement utilisées (toutes fournies par mlx_lm 0.32.2, rien n'est simulé) :
| Fonction | Mécanisme |
|---|---|
| Chargement persistant | processus résident, modèle chargé une fois |
| Lot continu (continuous batching) | BatchGenerator : une requête rejoint le lot en cours sans attendre sa fin (--decode-concurrency) |
| Prefill par lots | --prompt-concurrency, --prefill-step-size |
| Cache KV / cache de préfixes | LRUPromptCache borné en entrées et en octets : un préfixe déjà vu (prompt système, historique) n'est pas recalculé ; visible dans usage.prompt_tokens_details.cached_tokens |
| Streaming token par token | SSE, avec commentaires keepalive pendant le prefill |
| Annulation | fermer la connexion arrête la génération dans le lot |
| Tool calling | analyseur d'appels d'outils du gabarit Qwen3 |
Non pris en charge par le moteur, donc non annoncé : décodage contraint par grammaire, tool_choice
forcé, embeddings, entrées image. Le mode JSON est une validation côté passerelle (voir plus bas).
Passerelle
requête ─▶ Envelope (id, taille, CORS /v1, en-têtes de sécurité, journal)
─▶ authentification (clé API Bearer | session admin + CSRF)
─▶ validation Pydantic (schemas.py) 400 invalid_request
─▶ préparation (modèle, permissions, comptage) 403 / 404 / 400 context_length_exceeded
─▶ limites par clé (limits.py) 429
─▶ ordonnanceur (scheduler.py) 503 engine_overloaded / queue_timeout / memory_pressure
─▶ moteur MLX, en streaming (engine.py) 502 / 503 / 504
─▶ réponse OpenAI (JSON ou SSE) + enregistrement des compteurs| Module | Rôle |
|---|---|
app.py |
assemblage, intergiciel ASGI pur, gestion des erreurs |
routes_openai.py, schemas.py, inference.py |
API /v1 : validation, exécution, formats OpenAI, mode JSON |
scheduler.py |
admission, file à priorités avec vieillissement, budget de tokens, routage multi-moteurs |
limits.py |
requêtes/min, tokens/min, quotas jour/mois, concurrence par clé, frein par IP |
engine.py |
client HTTP des moteurs, sonde de santé toutes les 5 s |
keys.py, security.py |
clés API (HMAC-SHA-256 à clé serveur), jetons |
auth.py, routes_admin.py |
Passkeys WebAuthn, lien d'activation, sessions, CSRF, auth récente, audit, API du Dashboard |
metrics.py, sysmon.py |
compteurs d'usage, percentiles, mesures réelles du Mac |
openapi.py |
contrat OpenAPI généré depuis les schémas réellement utilisés |
tokens.py |
comptage des tokens avec le tokenizer du modèle |
cli.py |
administration locale (lien d'activation, récupération, clés) |
Ordonnancement et contrôle de la mémoire
- Chaque moteur a une capacité
max_active(générations simultanées, regroupées en lot par MLX) et un budget de tokens en voltoken_budget: la somme desprompt + max_tokensdes requêtes actives ne le dépasse pas. C'est ce qui borne la mémoire des KV caches, proportionnelle au nombre de tokens en contexte. Une requête seule passe toujours, même au-delà du budget (elle est bornée par la fenêtre de contexte). - Au-delà, file d'attente bornée (
MLLM_MAX_QUEUE) ; file pleine → refus immédiat 503 avecRetry-After(backpressure : rien ne s'empile sans limite). - Ordre de service :
score = rang × AGING_S − attente. Rangs :admin0,internal1,client2,background3. Une requête de fond gagne un rang toutes lesAGING_Ssecondes : pas de famine. - Pression mémoire macOS (
kern.memorystatus_vm_pressure_level, relevée toutes les 5 s) :warn→ capacité divisée par deux ;critical→ plus aucune admission (503memory_pressure).
Mode JSON (sorties structurées)
response_format: json_object | json_schema : la passerelle ajoute la consigne (et le schéma) au message
système, puis valide la sortie (json.loads + jsonschema). En non-streaming : un essai de réparation
automatique, puis 422 json_validation_failed plutôt qu'un JSON faux. En streaming, la consigne s'applique
mais la validité n'est pas garantie. Ce n'est pas un décodage contraint ; la documentation le dit.
Données et confidentialité
SQLite (WAL) dans ~/maclustr-llm-data/gateway.sqlite3 (mode 600). Tables : admin_users, passkeys,
setup_tokens, challenges, sessions, api_keys, usage_minute, request_log, audit_log,
sys_samples, settings.
- Jamais stockés : prompts, réponses, secrets en clair (clés API, jetons de session, jetons CSRF, jetons d'activation → seuls des condensats HMAC-SHA-256 à clé serveur).
- Stockés : compteurs par minute (requêtes, tokens, durées), métadonnées par requête (identifiant, clé, modèle, statut, tokens, durées — 30 jours), journal d'audit administratif, échantillons système (7 jours).
- Aucun appel sortant en fonctionnement : ni télémétrie, ni service LLM externe. Le seul trafic sortant est le téléchargement initial des poids depuis Hugging Face.
Évolution vers plusieurs nœuds
Rien à réécrire : config/models.json déclare déjà des modèles (alias publics) et des moteurs
(id, url, modèles servis, max_active, token_budget, weight). L'ordonnanceur choisit, pour un modèle
donné, le moteur sain le moins chargé (pondéré), et la sonde de santé retire un moteur en panne.
| Besoin futur | Ce qu'il faut faire |
|---|---|
| Deuxième modèle sur le même Mac | un moteur de plus (autre port, autre service launchd), une entrée dans models et dans engines |
| Répartir un modèle sur deux Mac | lancer le moteur sur le second nœud, l'ajouter dans engines avec la même liste models |
| Moteur distant | le moteur n'écoute qu'en bouclage : l'exposer au seul hôte de la passerelle par l'interface WireGuard du cluster (--host sur l'adresse wg1 + règle de pare-feu), jamais publiquement |
| Monitoring centralisé | /admin/api/overview agrège déjà les statistiques de tous les moteurs déclarés |
La V1 n'active rien de tout cela : un Mac, un moteur, un modèle.