SPB Git

Repository Public

ARCHITECTURE.md 8.0 KB

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

  1. 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_model est acceptée, sans adaptateur ni modèle brouillon.
  2. Préchargement et réchauffage au démarrage ; ready ne passe à vrai qu'après une vraie génération.
  3. /internal/stats : mémoire MLX réelle (active, pic, cache), cache de préfixes, tailles de lot, versions.
  4. 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

text
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 vol token_budget : la somme des prompt + max_tokens des 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 avec Retry-After (backpressure : rien ne s'empile sans limite).
  • Ordre de service : score = rang × AGING_S − attente. Rangs : admin 0, internal 1, client 2, background 3. Une requête de fond gagne un rang toutes les AGING_S secondes : 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 (503 memory_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.

Files main
Menu

Theme