SPB Git

Repository Public

ARCHITECTURE.md 8.0 KB 130 lines markdown

1# Architecture — MacLustr LLM API23## Vue d'ensemble45```mermaid6flowchart LR7    C["Clients<br/>SDK OpenAI, apps web / macOS / iOS, agents"] -- HTTPS --> P["Caddy · BHS64<br/>TLS Let's Encrypt"]8    P -- "WireGuard wg1" --> G9    subgraph M["Mac mini M4 Pro · 48 Go (m4mm)"]10        G["API Gateway · :8810<br/>FastAPI / uvicorn"]11        E["Moteur MLX · 127.0.0.1:8811<br/>mlx_lm durci"]12        D[("SQLite WAL<br/>clés hachées, sessions,<br/>usage, audit")]13        W["Site statique<br/>docs · playground · dashboard"]14        G --> E15        G --- D16        G --- W17        E --> GPU["GPU M4 Pro (Metal)<br/>mémoire unifiée"]18    end19```2021Deux processus, deux responsabilités :2223| Processus | Rôle | Écoute | Service launchd |24|---|---|---|---|25| **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` |26| **Passerelle** (`maclustr_llm.app`) | tout le reste : API, sécurité, file, métriques, site | `:8810` (LAN + wg1) | `ai.spboucher.maclustr-llm.gateway` |2728La passerelle est indépendante du moteur : elle reste debout quand le moteur redémarre (réponses 50329`engine_unavailable`, `/ready` à 503, `/health` à 200) et reprend seule dès que le modèle est rechargé.3031## Moteur d'inférence3233`engine_main.py` lance le serveur de `mlx_lm` (Apple MLX, Metal) avec quatre durcissements :34351. **Modèle verrouillé** — le serveur d'origine charge (et télécharge) tout modèle nommé dans une requête ;36   ici seule la valeur `default_model` est acceptée, sans adaptateur ni modèle brouillon.372. **Préchargement et réchauffage** au démarrage ; `ready` ne passe à vrai qu'après une vraie génération.383. **`/internal/stats`** : mémoire MLX réelle (active, pic, cache), cache de préfixes, tailles de lot, versions.394. Plafonds mémoire MLX explicites, journal tournant, arrêt propre sur SIGTERM.4041Fonctions d'inférence réellement utilisées (toutes fournies par `mlx_lm` 0.32.2, rien n'est simulé) :4243| Fonction | Mécanisme |44|---|---|45| Chargement persistant | processus résident, modèle chargé une fois |46| Lot continu (continuous batching) | `BatchGenerator` : une requête rejoint le lot en cours sans attendre sa fin (`--decode-concurrency`) |47| Prefill par lots | `--prompt-concurrency`, `--prefill-step-size` |48| 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` |49| Streaming token par token | SSE, avec commentaires *keepalive* pendant le prefill |50| Annulation | fermer la connexion arrête la génération dans le lot |51| Tool calling | analyseur d'appels d'outils du gabarit Qwen3 |5253Non pris en charge par le moteur, donc **non annoncé** : décodage contraint par grammaire, `tool_choice`54forcé, embeddings, entrées image. Le mode JSON est une validation côté passerelle (voir plus bas).5556## Passerelle5758```59requête ─▶ Envelope (id, taille, CORS /v1, en-têtes de sécurité, journal)60        ─▶ authentification (clé API Bearer | session admin + CSRF)61        ─▶ validation Pydantic (schemas.py)            400 invalid_request62        ─▶ préparation (modèle, permissions, comptage) 403 / 404 / 400 context_length_exceeded63        ─▶ limites par clé (limits.py)                 42964        ─▶ ordonnanceur (scheduler.py)                 503 engine_overloaded / queue_timeout / memory_pressure65        ─▶ moteur MLX, en streaming (engine.py)        502 / 503 / 50466        ─▶ réponse OpenAI (JSON ou SSE) + enregistrement des compteurs67```6869| Module | Rôle |70|---|---|71| `app.py` | assemblage, intergiciel ASGI pur, gestion des erreurs |72| `routes_openai.py`, `schemas.py`, `inference.py` | API `/v1` : validation, exécution, formats OpenAI, mode JSON |73| `scheduler.py` | admission, file à priorités avec vieillissement, budget de tokens, routage multi-moteurs |74| `limits.py` | requêtes/min, tokens/min, quotas jour/mois, concurrence par clé, frein par IP |75| `engine.py` | client HTTP des moteurs, sonde de santé toutes les 5 s |76| `keys.py`, `security.py` | clés API (HMAC-SHA-256 à clé serveur), jetons |77| `auth.py`, `routes_admin.py` | Passkeys WebAuthn, lien d'activation, sessions, CSRF, auth récente, audit, API du Dashboard |78| `metrics.py`, `sysmon.py` | compteurs d'usage, percentiles, mesures réelles du Mac |79| `openapi.py` | contrat OpenAPI généré depuis les schémas réellement utilisés |80| `tokens.py` | comptage des tokens avec le tokenizer du modèle |81| `cli.py` | administration locale (lien d'activation, récupération, clés) |8283### Ordonnancement et contrôle de la mémoire8485- Chaque moteur a une capacité `max_active` (générations simultanées, regroupées en lot par MLX) et un86  **budget de tokens en vol** `token_budget` : la somme des `prompt + max_tokens` des requêtes actives ne le87  dépasse pas. C'est ce qui borne la mémoire des KV caches, proportionnelle au nombre de tokens en contexte.88  Une requête seule passe toujours, même au-delà du budget (elle est bornée par la fenêtre de contexte).89- Au-delà, file d'attente bornée (`MLLM_MAX_QUEUE`) ; file pleine → refus immédiat 503 avec `Retry-After`90  (backpressure : rien ne s'empile sans limite).91- Ordre de service : `score = rang × AGING_S − attente`. Rangs : `admin` 0, `internal` 1, `client` 2,92  `background` 3. Une requête de fond gagne un rang toutes les `AGING_S` secondes : **pas de famine**.93- Pression mémoire macOS (`kern.memorystatus_vm_pressure_level`, relevée toutes les 5 s) : `warn` → capacité94  divisée par deux ; `critical` → plus aucune admission (503 `memory_pressure`).9596### Mode JSON (sorties structurées)9798`response_format: json_object | json_schema` : la passerelle ajoute la consigne (et le schéma) au message99système, puis **valide** la sortie (`json.loads` + `jsonschema`). En non-streaming : un essai de réparation100automatique, puis 422 `json_validation_failed` plutôt qu'un JSON faux. En streaming, la consigne s'applique101mais la validité n'est pas garantie. Ce n'est pas un décodage contraint ; la documentation le dit.102103## Données et confidentialité104105SQLite (WAL) dans `~/maclustr-llm-data/gateway.sqlite3` (mode 600). Tables : `admin_users`, `passkeys`,106`setup_tokens`, `challenges`, `sessions`, `api_keys`, `usage_minute`, `request_log`, `audit_log`,107`sys_samples`, `settings`.108109- **Jamais stockés** : prompts, réponses, secrets en clair (clés API, jetons de session, jetons CSRF, jetons110  d'activation → seuls des condensats HMAC-SHA-256 à clé serveur).111- **Stockés** : compteurs par minute (requêtes, tokens, durées), métadonnées par requête (identifiant, clé,112  modèle, statut, tokens, durées — 30 jours), journal d'audit administratif, échantillons système (7 jours).113- Aucun appel sortant en fonctionnement : ni télémétrie, ni service LLM externe. Le seul trafic sortant est le114  téléchargement initial des poids depuis Hugging Face.115116## Évolution vers plusieurs nœuds117118Rien à réécrire : `config/models.json` déclare déjà des **modèles** (alias publics) et des **moteurs**119(`id`, `url`, modèles servis, `max_active`, `token_budget`, `weight`). L'ordonnanceur choisit, pour un modèle120donné, le moteur sain le moins chargé (pondéré), et la sonde de santé retire un moteur en panne.121122| Besoin futur | Ce qu'il faut faire |123|---|---|124| 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` |125| 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` |126| 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 |127| Monitoring centralisé | `/admin/api/overview` agrège déjà les statistiques de tous les moteurs déclarés |128129La V1 n'active rien de tout cela : un Mac, un moteur, un modèle.130
Files main
Menu

Theme