| # Architecture — Justifications techniques |
|
|
| > Ce document est **structuré dès la Phase 0** et rempli **au fur et à mesure**. |
| > Règle 7 du cahier des charges : **chaque choix technique est justifié ici**. |
| > Tant qu'une section est vide, elle porte la mention `⏳ À documenter (Phase N)`. |
|
|
| ## 0. Vue d'ensemble |
|
|
| Un **modèle unifié** traite toutes les modalités comme des **tokens** dans une |
| **séquence unique** : |
|
|
| ``` |
| texte ──► embeddings texte ─┐ |
| image ──► ViT maison ──► MLP ─┤ |
| audio ──► transformer mel ──► MLP ─┼──► séquence concaténée ──► transformer texte ──► logits |
| vidéo ──► (frames = images) + audio ┘ (avec tokens de délimitation) |
| ``` |
|
|
| **Pourquoi une séquence unique plutôt que des têtes séparées ?** |
| Parce qu'un seul décodeur autoregressif peut alors *conditionner* sa génération sur |
| n'importe quelle combinaison d'entrées, sans architecture ad hoc par tâche. Les tokens |
| de délimitation (`<|image_start|>`, `<|audio_start|>`, …) indiquent au modèle où une |
| modalité commence et finit. C'est le principe des VLM modernes, mais **réimplémenté |
| intégralement à la main**. |
|
|
| ## 1. Tokenizer (Phase 1) — ✅ implémenté, entraîné, testé |
|
|
| Choix retenus (voir aussi ADR-010) : |
|
|
| - **BPE** (`tokenizers.models.BPE`) plutôt qu'Unigram/SentencePiece : algorithme |
| déterministe, simple à auditer, excellent sur les langues à morphologie riche |
| comme le français. Entraînement **sur notre corpus**, aucun tokenizer pré-entraîné. |
| - **`pre_tokenizer = ByteLevel(add_prefix_space=False)`** : découpe au niveau des |
| octets. Conséquence : aucun caractère n'est jamais hors-vocabulaire, les accents |
| (é è ê à ç ù î ô œ æ), les emojis et tout script (japonais, arabe…) sont gérés |
| nativement. |
| - **`initial_alphabet = ByteLevel.alphabet()` (256 octets)** : première idée |
| fausse — sans cet alphabet initial, seuls les octets *vus dans le corpus* ont un |
| token, donc un emoji jamais vu était **perdu** au round-trip (vérifié |
| empiriquement). En forçant les 256 octets en tokens `0x00..0xFF`, `encode` → |
| `decode` devient un **round-trip exact** pour toute entrée. |
| - **`byte_fallback=True`** sur le modèle BPE : repli octet pour les caractères |
| inconnus. *(En `tokenizers` 0.23, `byte_fallback` est un paramètre du **modèle |
| BPE**, pas du trainer — un argument `byte_fallback` passé au trainer est ignoré |
| avec un warning. Corrigé dans le code.)* |
| - **`min_frequency=2`** : évite de figer des paires vues une seule fois. |
| - **Tokens spéciaux réservés en premier**, dans l'ordre canonique de |
| `src/tokenizer/special_tokens.py` → ids **0..18**, stables et connus à l'avance : |
| - base (4) : `<|pad|> <|bos|> <|eos|> <|unk|>` |
| - raisonnement/agent (6) : `<|think|> <|plan|> <|tool_call|> <|tool_result|> <|critic|> <|moe_route|>` |
| - modalités (9) : `<|image_start|> <|image_end|> <|image_pad|>`, idem audio et vidéo. |
| - la forme `<|...|>` garantit qu'aucun token spécial ne peut émerger d'une |
| fusion BPE sur du texte naturel nettoyé. |
| - **`vocab_size` est une borne supérieure, pas une garantie** : `BpeTrainer` ne |
| produit jamais plus que le nombre de fusions possibles. Sur ~150 Mo de français |
| on atteint bien **32000 exactement** (mesuré), mais sur un corpus pauvre le |
| vocab final serait plus petit → le script **échoue explicitement** plutôt que |
| de produire un tokenizer trompeur. |
| |
| **Résultat mesuré (local, sur cette machine CPU)** : corpus Wikipedia FR |
| (`wikimedia/wikipedia` `20231101.fr`, streaming, plafond 150 Mo), **32 000 |
| tokens**, **21,8 s**, round-trip exact sur accents/emojis/CJK/arabe. |
|
|
| **Corpus** : plafonné à ~150–200 Mo (au lieu des ~6 Go de Wikipedia FR complet), |
| pour tenir sur Colab et rester raisonnable en local. Documenté en ADR-010. |
| **Pas** d'en-tête de licence ni de boilerplate injecté dans le corpus (consigne |
| explicite). |
|
|
| ## 2. Transformer texte (Phase 2) — ✅ implémenté, testé |
|
|
| Modules : `src/model/{rope,attention,ffn,block,text_model}.py`. Aucun module |
| `transformers`, aucun `nn.MultiheadAttention` : projections, découpage en têtes, |
| masque causal, softmax et rotations RoPE sont **écrits à la main**. |
|
|
| ### 2.1 RoPE (Rotary Position Embedding) |
| **Choix** : RoPE plutôt qu'un embedding positionnel absolu appris. |
| **Justification** : |
| - En faisant tourner les paires de dimensions de Q et K d'un angle proportionnel |
| à la position, le produit scalaire `Q·K` **ne dépend que de l'écart relatif** |
| de position (test `test_rope_makes_attention_depend_on_relative_position`). |
| - **Zéro paramètre**, aucune limite intrinsèque de longueur. |
| - Meilleure **extrapolation** qu'un embedding absolu, et réutilisable tel quel |
| pour image/audio (une position = un indice dans la séquence). |
| - Chaque paire (2i, 2i+1) est une **rotation** → la norme est conservée |
| (test `test_rope_preserves_norm`). |
| Config : `rope_theta = 10000`, `head_dim` pair requis. |
|
|
| ### 2.2 Pre-norm + residual |
| x = x + Attention(LN(x)) |
| x = x + FFN(LN(x)) |
| **Justification** : le gradient traverse la connexion résiduelle **sans être |
| multiplié** par la norme → stabilise les réseaux profonds, rend le warmup moins |
| critique. Forme des transformers modernes. Test : `test_block_is_prenorm`. |
| |
| ### 2.3 Attention causale |
| Le masque est un triangulaire supérieur mis à `-inf` **avant** le softmax, donc |
| les poids vers le futur valent **exactement 0**. Preuves par test : |
| - `test_attention_is_strictly_causal` : modifier le futur ne change pas les sorties passées ; |
| - `test_model_is_causal` : idem au niveau des logits du modèle complet ; |
| - `test_attention_matches_manual_inference_for_second_token` : comparaison à un |
| calcul d'attention refait entièrement à la main. |
|
|
| ### 2.4 FFN GELU |
| MLP à deux couches, dimension cachée `ffn_mult * n_embd` (défaut 4). `lm_head` |
| lié aux embeddings (`tie_embeddings`) dans un profil, séparé dans l'autre. |
|
|
| ### 2.5 Paramètres : l'écart 50 M vs réalité |
| Point d'honnêteté déjà noté (valeurs **vérifiées** en Phase 0) : |
|
|
| Formule utilisée (vocab `V`, dim `E`, couches `L`, FFN `4E`, biais désactivés) : |
| ``` |
| params = V·E (embeddings) + L·(4E² + 8E² + 2E) + E (norm finale) [+ V·E si lm_head non lié] |
| ``` |
|
|
| | Profil | V | E | L | lm_head | Total | |
| |---|---|---|---|---|---| |
| | `text_model` (défaut, demandé) | 32000 | 384 | 6 | lié | **22.9 M** | |
| | `text_model` (idem) | 32000 | 384 | 6 | non lié | **35.2 M** | |
| | `text_model_50m` | 32000 | 512 | 6 | non lié | **51.6 M** | |
|
|
| Le profil demandé (`n_embd=384, n_layer=6`) ne fait donc **pas** 50 M. Le profil |
| `text_model_50m` (`n_embd=512, n_head=8, n_layer=6`, embeddings non liés) atteint |
| **51.6 M**. Les deux sont fournis ; l'écart est documenté, jamais masqué. |
| Ces tailles sont **recalculées à partir du vrai modèle** dans |
| `tests/test_phase0_params.py` (aucun chiffre codé en dur non vérifié). |
|
|
| ### 2.6 Résultats mesurés (local, CPU) |
| - Test unitaire `test_overfit_single_batch` : loss → **< 0.05** sur un lot unique. |
| - Démo réelle : mini-corpus FR (4 phrases × 40, `n_layer=4, n_embd=128`, 300 pas, |
| **68 s**) → loss **10.45 → 0.011**. Génération (T=0.7, top-k=40) : |
|
|
| > « Le chat noir dort sur le canapé du salon. Marie mange une pomme rouge dans le jardin. Les enfants jouent ensemble après… » |
|
|
| ### 2.7 Génération (`src/generate.py`) |
| Échantillonnage entièrement écrit à la main : **température**, **top-k**, |
| **top-p (nucleus)**, glouton, arrêt sur `<|eos|>`. Aucune fonction `model.generate`. |
|
|
| ### 2.8 Entraînement texte (Phase 3) |
| `src/data/prepare_text.py` + `src/train/train_text.py` + `src/evaluate.py`. |
|
|
| - **Données** : tokenisation du corpus en un tableau `uint16` (le vocab 32 000 |
| tient sur 16 bits → 2 octets/token), un `<|eos|>` après chaque document. |
| Découpe train/val **séquentielle** (la val est la fin du flux) pour éviter |
| toute fuite. `np.memmap` : aucune copie en RAM. Encodage par lots |
| (`encode_batch`, Rust) pour la vitesse. |
| - **Optimiseur** : AdamW, **weight decay 0.1 uniquement sur les matrices** |
| (`dim >= 2`), jamais sur les normes ni les biais — convention standard. |
| - **LR** : warmup linéaire puis cosinus jusqu'à `lr * min_lr_ratio`, planificateur |
| écrit à la main (testé : croissant puis décroissant, monotone après warmup). |
| - **Stabilité** : `clip_grad_norm_` (1.0), `autocast` (bf16/fp16 sur GPU, fp32 sur CPU). |
| - **Checkpoints** : `last.pt` et `best.pt` (sur val), logs `train_log.jsonl`. |
|
|
| **Résultat mesuré (local, CPU, 8 Mo de Wikipedia FR = 1,91 M tokens)** : |
| `n_layer=4, n_embd=128` (~9 M params), 300 pas en 258 s → loss **10.40 → 6.06**, |
| perplexité val **475**. Échantillon réel (T=0.7) : |
|
|
| > « La France est alors que les trois villes, les États-Unis, dans des plus de la plus de la ville. Le gouvernement et la fin de l'est que une première place de l'origine… » |
|
|
| À 300 pas sur 8 Mo, la cible **ppl < 30** n'est **pas** atteinte : elle demande le |
| run complet (~200 Mo, profil 50 M, plusieurs heures GPU — voir |
| `notebooks/02_train_text.ipynb`). Aucun résultat n'est annoncé sans mesure. |
|
|
| ## 3. Encodeur image (Phase 4) — ✅ implémenté, testé |
|
|
| Modules : `src/model/vit.py`, `src/model/projectors.py`, `src/data/toy_images.py`. |
|
|
| ### 3.1 Architecture |
| - **Patch embedding** : convolution noyau/pas `patch_size` → découpe l'image en |
| patchs non chevauchants et projette chacun en `n_embd`. Équivaut à une |
| projection linéaire par patch, mais plus simple à écrire. |
| - **Token CLS** appris (pool `cls`) ou moyenne des patchs (pool `mean`). |
| - **Positional embedding appris** : sur une grille 2D de taille **fixe et connue**, |
| un vecteur par position est simple et suffisant. **RoPE 2D n'apporte rien** ici, |
| donc on ne l'utilise pas pour l'image (il reste utilisé pour le texte). |
| - N blocs transformer + LayerNorm finale. |
|
|
| ### 3.2 Attention bidirectionnelle (bug réel corrigé) |
| Un encodeur d'image doit utiliser une attention **non causale** : chaque patch |
| (et le CLS) doit voir toute l'image. La première version réutilisait l'attention |
| **causale** du texte → le CLS, en position 0, ne voyait **aucun** patch et le |
| modèle restait bloqué à la perte de hasard (logits identiques pour toutes les |
| images, vérifié au débogage). Correction : drapeau `causal` sur l'attention |
| (`causal=True` pour le texte, `causal=False` pour image/audio). Un test de |
| régression (`test_encoder_is_bidirectional_not_causal`) empêche le retour du bug. |
|
|
| ### 3.3 Générateur d'images jouets (maison) |
| `src/data/toy_images.py` génère des images RGB 32×32 avec une forme colorée |
| (cercle / carré / triangle × rouge / vert / bleu = **9 classes**), une légende |
| française (« un cercle rouge ») et du bruit léger. Déterministe (seed), aucune |
| dépendance à des données externes. Sert aux Phases 4, 5 et 6. |
|
|
| ### 3.4 Projecteurs |
| `MLPProjector` : `LayerNorm → Linear → GELU → Linear` projette image/audio vers |
| `text_dim`. Un MLP (non linéaire) plutôt qu'une projection linéaire, pour un coût |
| modeste — c'est le composant qui aligne les modalités. |
|
|
| ### 3.5 Résultats mesurés (local, CPU) |
| - Classification 9 classes, 18 images, `n_embd=32`, 2 blocs : **acc > 0.9** |
| (overfit volontaire, jeu minuscule). |
| - Reconstruction (auto-encodeur) : **MSE < 0.05** après 120 pas. |
|
|
| ## 4. Alignement image-texte (Phase 5) — ✅ implémenté, testé |
|
|
| Modules : `src/model/clip.py`, `src/data/prepare_image_text.py`, |
| `src/train/train_clip.py`. |
|
|
| ### 4.1 Architecture |
| `CortexClip` = `VisionEncoder` (Phase 4) + transformer texte (Phase 2), chacun suivi |
| d'un `MLPProjector` vers un espace commun `embed_dim`, **normalisés L2**. La |
| similarité est le produit scalaire ; la température est une `logit_scale` apprise |
| (init `1/0.07`, plafonnée à 100). |
|
|
| ### 4.2 Loss contrastive symétrique |
| `contrastive_loss` (écrite à la main) : cross-entropy sur les lignes **et** les |
| colonnes, bonne paire sur la diagonale, moyenne des deux. Vérifié par tests : |
| diagonale forte → perte ≈ 0 ; similarités uniformes → perte = `log(batch)` ; |
| symétrie en échangeant image/texte. |
|
|
| ### 4.3 Deux pièges réels rencontrés (et corrigés) |
| 1. **Le pooling du texte incluait les tokens de padding.** Toutes les légendes se |
| ressemblaient. Correction : un **masque d'attention** (1 sur les vrais tokens, |
| 0 sur le PAD) est maintenant threadé jusqu'au pooling. |
| 2. **Les légendes se répètent dans le lot.** Avec 9 classes et 1800 images, un lot |
| aléatoire contient des légendes dupliquées : l'appariement image↔texte n'est plus |
| 1-1 et la perte symétrique devient **contradictoire → collapse** (perte figée à |
| `log(batch)`, embeddings alignés). Correction : `_build_batches` construit des |
| lots où **chaque légende apparaît une seule fois** (au plus une image par classe |
| et par lot). Sans ce correctif, même une architecture correcte ne converge pas. |
|
|
| Un lr trop élevé (3e-3 → 8e-3) provoque aussi un collapse ; **gradient clipping 1.0** |
| + lr modéré stabilisent l'entraînement. |
|
|
| ### 4.4 Métrique |
| `class_retrieval_accuracy` : retrieval image→texte **au niveau des classes** (banque |
| de légendes uniques), pas l'argmax diagonal (biaisé par les doublons). |
|
|
| ### 4.5 Résultats mesurés (local, CPU) |
| - Paires jouets 32×32 (9 classes), `embed_dim=64`, 2+2 blocs, **1200 pas en 126 s** : |
| loss **2.20 → 0.15**, retrieval val **0.81** (hasard 0.11). |
| - Sur 9 images/légendes uniques, retrieval diagonal **1.00** (loss → 0.00). |
|
|
| ## 5. Modèle multimodal génératif image+texte (Phase 6) — ✅ implémenté, testé |
|
|
| Modules : `src/model/vlm.py`, `src/train/train_vlm.py`, `src/model/text_model.py` |
| (ajout de `inputs_embeds`). |
|
|
| ### 5.1 Fusion par embeddings |
| Les patchs d'image (ViT, Phase 4) sont projetés dans l'espace texte puis **injectés |
| comme des « tokens d'image »** dans la séquence, encadrés par `<|image_start|>` … |
| `<|image_end|>`. On passe des `inputs_embeds` au transformer : features projetées |
| sur les positions d'image, embeddings de tokens ailleurs. Le décodeur causal voit |
| l'image avant de générer la réponse. |
|
|
| ### 5.2 Bug critique corrigé : décalage des labels |
| `CortexTextLM.forward` ne décale **pas** les targets (convention « décalage géré par |
| l'appelant », comme en Phase 3). Or `build_example` mettait d'abord `label[t] = ids[t]` |
| (non décalé) : le modèle prédisait le token qu'il voyait déjà → **loss triviale |
| (0.0006) et génération cassée**. Correction : `labels[t] = ids[t+1]` sur la réponse |
| (convention GPT). Un test vérifie l'invariant `labels[t] == ids[t+1]`. |
|
|
| ### 5.3 Masquage de la perte |
| `ignore_index=-100` ajouté à la cross-entropy : seules les positions de réponse |
| comptent. Vérifié par un test qui recalcule la CE à la main. |
|
|
| ### 5.4 Grounding visuel mesuré (local, CPU, 115 s, 400 pas) |
| Config `grid=32, patch=8` (16 tokens d'image), `n_layer=2, n_embd=64`. |
| - **Exactitude teacher-forced** (métrique honnête) : légende **0.85**, forme **0.80**, |
| couleur **1.00**, comptage **1.00** (hasard : forme 0.33, couleur 0.33). |
| - **Génération libre (greedy)** : 0.35 — bien plus faible à cause du **biais |
| d'exposition** sur un modèle aussi petit. On ne prétend donc pas que la génération |
| libre est bonne : le grounding visuel est réel, la génération reste fragile. |
|
|
| ### 5.5 Leçons de réglage |
| Un lr de 5e-3 collapsait la génération ; **2e-3 + gradient clipping 1.0** est stable. |
| Avec 16×16 et patch 8 (4 tokens seulement) le modèle ne voit pas la forme ; 32×32 |
| (16 tokens) le permet. |
|
|
| ## 6. Encodeur audio (Phase 7) — ✅ implémenté, testé |
|
|
| Modules : `src/data/audio_features.py`, `src/data/toy_audio.py`, |
| `src/model/audio_encoder.py`, `src/data/prepare_audio.py`, `src/train/train_audio.py`. |
|
|
| ### 6.1 Mel-spectrogramme écrit à la main |
| `torchaudio` n'étant pas installé dans l'environnement, l'extraction mel est |
| **entièrement maison** (encore plus « from scratch ») : STFT via `torch.fft`, fenêtre |
| de Hann périodique, banc de filtres mel triangulaires (`hz_to_mel`/`mel_to_hz`), |
| puis log. Vérifié par un test : un sinus pur de 1 kHz produit bien un pic de |
| magnitude à ~1 kHz. |
|
|
| ### 6.2 Architecture |
| Patch embedding (conv 2D sur le mel, patchs fréquence × temps) + **positional |
| embedding appris** + blocs transformer **bidirectionnels** (l'audio n'est pas causal : |
| le clip entier est visible). Un test vérifie la bidirectionnalité. Pooling moyen → |
| projecteur MLP → espace texte. |
|
|
| ### 6.3 Données — réduction de scope assumée |
| L'environnement de dev n'a pas d'accès audio (pas de Common Voice FR). On |
| **synthétise** des voyelles par un modèle de formants (F0 + F1/F2, deux hauteurs) : |
| **10 classes** (5 voyelles × grave/aigu). C'est un jeu jouet, pas de la parole réelle. |
| La transcription de **parole réelle** (Common Voice fr) reste à faire dans un |
| environnement avec audio ; le pipeline (mel → encodeur → décodeur) est identique. |
|
|
| ### 6.4 Résultats mesurés (local, CPU, 233 s, 600 pas) |
| - **Transcription** : teacher-forced **1.00**, génération libre **1.00** sur 10 classes |
| (hasard 0.10), loss 10.4 → 0.0005. Les voyelles synthétiques sont parfaitement |
| transcrites (« voyelle a grave », …). |
|
|
| ### 6.5 Fusion réutilisée |
| `build_modality_example` (généralisé en Phase 7) construit la séquence |
| `prompt <|audio_start|> [audio_pad × N] <|audio_end|> réponse`, avec labels décalés |
| comme pour l'image. |
|
|
| ## 7. Modèle multimodal complet texte + image + audio (Phase 8) — ✅ implémenté, testé |
|
|
| Modules : `src/model/multimodal.py`, `src/train/train_full_multimodal.py`. |
|
|
| ### 8.1 Un seul décodeur pour trois modalités |
| `CortexMultimodal` réunit le décodeur texte (Phase 2), l'encodeur ViT (Phase 4) et |
| l'encodeur audio (Phase 7). Chaque modalité est projetée (`MLPProjector`) puis |
| **injectée dans la même séquence** aux positions marquées par `<|image_pad|>` / |
| `<|audio_pad|>`. `assemble_embeds` remplace l'embedding du token par la feature |
| projetée ; le décodeur causal génère la réponse. |
|
|
| ### 8.2 Détail important : lignes du lot sans modalité |
| Dans un lot multi-tâches, certaines lignes n'ont ni image ni audio. On n'encode que |
| les **lignes concernées** (`mask.any(dim=1)`) avant d'affecter les embeddings, ce qui |
| évite un décalage de forme (bug rencontré puis corrigé). Un test dédié vérifie ce cas. |
|
|
| ### 8.3 Tâches et résultats mesurés (local, CPU, 328 s, 600 pas) |
| Tâches : `image` (« Décris l'image : »), `audio` (« Transcris : »), `mixte` |
| (« Image et audio : » -> « <légende> | <transcription> »). |
| - **Exactitude teacher-forced** : image **0.92**, audio **1.00**, mixte **0.93** |
| (hasard : image ~0.11, audio 0.10). |
| - **Génération libre mixte** : 0.17 — le modèle lit correctement les deux modalités |
| isolément, mais la génération libre conjointe reste fragile (biais d'exposition), |
| ce qui est attendu pour un modèle de cette taille. On ne le cache pas. |
|
|
| ### 8.4 Fusion réutilisable |
| `build_modality_example` (Phase 7) et `build_sequence` (Phase 8) partagent la même |
| convention : blocs de tokens spéciaux + labels décalés + `ignore_index=-100`. |
|
|
| ## 8. Vidéo — images + audio synchronisés (Phase 9) — ✅ implémenté, testé |
|
|
| Modules : `src/data/toy_video.py`, `src/model/multimodal.py::VideoEncoder`, |
| `src/train/train_video.py`. |
|
|
| ### 7.1 Données jouets — mouvement (tâche réellement temporelle) |
| Une vidéo = ``n_frames`` images d'une forme colorée qui **se déplace** horizontalement |
| (vers la droite ou la gauche), + une piste audio synthétique (Phase 7). 18 classes |
| (3 formes × 3 couleurs × 2 directions). La direction ne peut être lue qu'en comparant |
| les frames : un test vérifie que le centroïde horizontal croît (« droite ») ou décroît |
| (« gauche »). |
|
|
| ### 7.2 Architecture |
| `VideoEncoder` = un ViT (Phase 4) **partagé** sur chaque frame + un **embedding |
| temporel appris** par frame + un petit transformer **spatio-temporel** (bidirectionnel) |
| sur l'ensemble des `n_frames × n_patches` tokens. Un test vérifie que réordonner les |
| frames change les features (le modèle regarde bien le temps). Coût quadratique de |
| l'attention sur le nombre de tokens (limite documentée : on garde `n_frames` petit). |
|
|
| ### 7.3 Tâches et résultats mesurés (local, CPU, 98 s, 300 pas, 4 frames) |
| - « Décris la vidéo : » -> exactitude teacher-forced **0.78** ; |
| - « Que se passe-t-il ? » (frames + audio) -> **0.85** (hasard ~0.055). |
| - Génération libre 0.0 : non caché — décrire une vidéo en génération libre reste |
| hors de portée d'un modèle de cette taille ; le grounding est réel. |
|
|
| ## 9. Mixture-of-Experts — 20 experts, top-2 (Phase 10) — ✅ implémenté, entraîné, testé |
|
|
| Module : `src/model/moe.py`, entraînement `src/train/train_moe.py`. |
|
|
| ### 9.1 Pourquoi MoE |
| Un MoE **augmente la capacité** (nombre total de paramètres) **sans** augmenter le coût |
| de calcul par token : seuls les `top_k` experts activés sont traversés. On remplace les |
| FFN denses du transformer texte par `MoEFFN` (`n_experts=20`, `top_k=2`). |
|
|
| ### 9.2 Routeur (écrit à la main) |
| `router = Linear(n_embd, n_experts)` ; on garde les `top_k` plus grands logits, on |
| renormalise les portes, et on n'applique chaque expert qu'aux tokens qui le choisissent |
| (calcul épars). Pendant l'entraînement, un **bruit gaussien** (`jitter`) est ajouté aux |
| logits pour l'exploration. |
|
|
| ### 9.3 Loss auxiliaire d'équilibrage |
| Loss Switch-Transformer : `E * Σ_i f_i · P_i` (`f_i` = fraction de tokens routés vers |
| l'expert `i`, `P_i` = probabilité moyenne). Pénalise la concentration. Poids |
| `aux_loss_coef=0.01`. La perte totale = perte de langage + `aux_loss_coef * aux_loss`. |
|
|
| ### 9.4 Résultats mesurés (local, CPU, 400 pas, 373 s, corpus FR jouet) |
| - Perte val **0.0052**, **perplexité val 1.005** (le modèle apprend le corpus jouet). |
| - **Entropie de charge normalisée 0.9999** sur 20 experts → routage quasi parfaitement |
| équilibré, **0 expert mort**. |
| - **14 855 296** paramètres totaux vs **5 418 112** actifs par token (ratio ~2.7×) : |
| c'est le gain MoE — plus de capacité, coût par token borné par `top_k`. |
|
|
| ### 9.5 Coûts / limites |
| Tous les experts restent **résidents en mémoire** ; le routeur peut devenir instable |
| sans loss auxiliaire ; le débit d'entraînement dépend de l'implémentation éparse |
| (boucle par expert ici — suffisant à l'échelle jouet, à vectoriser pour du grand). |
|
|
| ## 10. Mémoire / « apprendre des cours » (Phase 11) — ✅ implémenté, testé |
|
|
| Modules : `src/memory/rag.py` (mode A), `src/memory/permanent.py` (mode B). |
|
|
| ### 10.1 Mode A — RAG (réaliste, recommandé) |
| Pipeline écrit à la main, sans service externe : |
| 1. **Découpage** d'un cours en passages (`chunk_text`, par phrases jusqu'à `max_words`). |
| 2. **Embeddings maison** par *feature hashing* déterministe (sac de mots signé, pondéré |
| par IDF), L2-normalisés. Aucun paramètre appris — honnête à petite échelle : deux |
| textes lexicalement proches le sont aussi vectoriellement (testé). |
| 3. **Index vectoriel numpy** (`VectorIndex`) : recherche par similarité cosinus. |
| 4. Un cours **vidéo** = transcription horodatée **+ légendes de frames clés** |
| (`add_video`) ; les sources (fichier, timestamps) sont conservées. |
| 5. Réponse **extractive** : le meilleur passage réel du cours est renvoyé verbatim, |
| avec sources et confiance (cosinus) — **pas d'hallucination** pour le mode A. |
| Une variante générative (`answer_with_model`) met le contexte dans le prompt. |
|
|
| ### 10.2 Mode B — apprentissage permanent : EXPÉRIMENTAL ET INSTABLE ⚠️ |
| Mise à jour des **poids** pendant l'ingestion (`PermanentLearner.ingest`) : quelques pas |
| de gradient AdamW (maison) sur le texte du cours, avec un **tampon de rejeu** pour |
| limiter l'oubli catastrophique. Avertissements tenus par des **tests** : |
| - après ingestion, la perte sur la leçon **chute** (mémorisation réelle) ; |
| - **sans rejeu**, la perte sur une phrase déjà apprise **augmente** — l'oubli |
| catastrophique est démontré, pas caché. |
| Ce mode **mémorise un texte court** et le restitue ; il **ne remplace pas** un |
| fine-tuning, peut **dégrader** d'autres capacités, et n'offre **aucune garantie** de |
| stabilité. Il est implémenté **en dernier** et présenté comme recherche. |
|
|
| ## 12. API · Démo · Publication (Phase 12) — ✅ implémenté, testé |
|
|
| ### 12.1 Moteur d'inférence unifié (`src/inference.py`) |
| `CortexEngine` rassemble le décodeur texte et les encodeurs image/audio/vidéo derrière |
| une API unique (`chat`, `describe_image`, `transcribe_audio`, `describe_video`). Les |
| entrées sont décodées sans dépendance lourde : images via numpy/Pillow, audio WAV via |
| `wave`, vidéo via tableau `(T,H,W,3)`. La fusion se fait par masques : les embeddings |
| du décodeur sont remplacés aux positions `image_pad`/`audio_pad`/`video_pad` par les |
| features projetées. `trained=False` tant qu'aucun checkpoint n'est chargé — **honnête** : |
| les poids sont alors l'initialisation aléatoire, seule la tuyauterie est réelle. |
|
|
| ### 12.2 API FastAPI (`src/api.py`) |
| Endpoints `/health`, `/capabilities`, `/chat`, `/vision`, `/audio`, `/video`, |
| `/memory/ingest`, `/memory/query`. Le checkpoint est choisi par `CORTEX_CHECKPOINT` |
| (jamais de secret en dur). Tests via `TestClient` (14 tests) — tournent sur CPU. |
|
|
| ### 12.3 Démo Gradio (`app/gradio_app.py`) |
| Onglets Texte/Image/Audio/Vidéo/Mémoire. Les handlers sont testés sans lancer de serveur. |
| |
| ### 12.4 Publication (`src/push_to_hub.py`, `Dockerfile`) |
| `push_to_hub` publie le dépôt, un `checkpoints/*.pt` optionnel et la carte de modèle |
| (front-matter avec `license: apache-2.0`). Le Dockerfile expose l'API (8000) et la démo |
| (7860) ; `HF_TOKEN`/`CORTEX_CHECKPOINT` sont fournis au runtime, jamais cuits dans l'image. |
| |
| ## 11. Limites assumées |
| |
| - Un modèle de quelques dizaines de millions de paramètres **ne raisonne pas** comme un |
| modèle de plusieurs centaines de milliards. Aucune équivalence ne sera prétendue. |
| - Entraînement réel limité par le matériel (CPU ici → Colab pour l'entraînement). |
| - Les résultats seront **mesurés**, jamais inventés. |
| |
