docs/vision.fr.md

# Couche vision — état réel

Ce document décrit la couche vision de CORTEX AI. Il est volontairement direct sur ce qui
fonctionne et ce qui ne fonctionne pas.

> **En une phrase.** CORTEX AI **n'est pas** aujourd'hui un modèle de compréhension d'images.
> Le dépôt contient une interface d'adaptation testée et un pont fonctionnel, mais pas un modèle
> multimodal complet.

---

## Pourquoi cette mise au point

Il est tentant, quand un dépôt contient un dossier `vision/`, de supposer que le modèle voit les
images. Ce n'est pas le cas ici. Le modèle de base n'a pas été modifié, aucun encodeur visuel
n'est inclus, et aucun poids de projecteur n'est fourni.

Dire cela clairement vaut mieux qu'une case cochée qui induirait en erreur.

---

## Les deux chemins disponibles

### 1. Le pont vision (fonctionnel)

C'est le chemin qui marche aujourd'hui, de bout en bout.

```text
IMAGE
  ↓
Modele image-vers-texte externe
  ↓
Observation textuelle
  ↓
[CORTEX VISION OBSERVATION] contexte texte
  ↓
Modele de texte CORTEX AI
```

Le principe : un modèle externe, explicitement choisi, produit une description de l'image. Cette
description est transformée en contexte textuel, puis transmise au modèle de texte.

```bash
python examples/vision_bridge.py /chemin/vers/image.jpg "Que voit-on ?"
```

**Ce que c'est :** un vrai chemin d'exécution sur image.
**Ce que ce n'est pas :** une fusion native de jetons d'image dans le cœur du modèle.

Le modèle de description est un modèle séparé, avec ses propres poids, téléchargés au premier
usage. Sa sortie est traitée comme une observation, et le modèle de texte est instruit de signaler
quand cette observation est insuffisante.

### 2. La fusion native (prototype)

Un prototype de fusion au niveau des tenseurs existe dans `cortex_ai/vision/native.py`.

```text
IMAGE
  ↓
Encodeur visuel
  ↓
Plongements d'image
  ↓
Projecteur
  ↓
Fusion par préfixe
  ↓
inputs_embeds
  ↓
Cœur de langage
```

Ce prototype a été validé contre un **vrai** encodeur (`google/siglip-base-patch16-224`) : 196
jetons d'image plus 8 jetons de texte donnent une séquence fusionnée de 204, avec des logits de
forme `(1, 204, 1000)`, et les plongements changent bien selon le contenu de l'image.

**Mais il n'a pas été validé contre le cœur réel de 1,65 billion de paramètres.** Ce prototype
tourne sur un cœur de test réduit.

---

## Entraîner le projecteur

Le dépôt contient un chemin d'entraînement de l'étape 1 : `cortex_ai/vision/train.py` et
`examples/train_vision_projector.py`.

```text
IMAGE -> SigLIP gele -> Projecteur (entraine) -> Fusion -> LM gele -> logits
```

Seul le projecteur est entraîné. L'encodeur et le modèle de langage restent gelés.

| Élément | Valeur mesurée |
|---|---|
| Taille cachée vision | 768 (`google/siglip-base-patch16-224`, 196 jetons par image) |
| Taille cachée du cœur de test | 128 (`EleutherAI/pythia-14m`) |
| Projecteur | `mlp`, 768 vers 128, **114 944 parametres** |
| Sequence fusionnee | 220 = 196 image + 24 texte |
| Execution de 60 pas | perte de 7,5445 a 5,1408 |
| Variation du projecteur | 669,6 |
| Variation encodeur / LM | exactement 0 |

Ces chiffres proviennent d'une exécution réelle sur une machine de développement à 4 cœurs, sans
GPU. Ils prouvent que la chaîne d'entraînement fonctionne, pas que le modèle final est multimodal.

### Trois pièges à connaître

**Le projecteur non entraîné produit du bruit.**
Un projecteur initialisé au hasard injecte du bruit dans le cœur. Vouloir « ne rien entraîner » et
« une vision qui fonctionne » sont deux objectifs incompatibles. Soit le projecteur est entraîné,
soit la sortie n'a pas de sens.

**L'entraînement n'est pas gratuit.**
Entraîner le projecteur seul, avec encodeur et cœur gelés, est l'option la moins coûteuse. Un
pré-entraînement multimodal complet sur 1,65 billion de paramètres ne se fait pas hors d'un
cluster.

**Le masque d'attention doit être recalculé.**
Passer le masque d'attention du texte dans une passe fusionnée échoue : les positions des jetons
d'image ont besoin de leurs propres entrées dans le masque.

---

## Ce qui manque pour que la vision fonctionne vraiment

Pour rendre la compréhension d'images opérationnelle, il faudrait :

1. Choisir un encodeur visuel et vérifier sa licence.
2. Fournir ou entraîner des poids de projecteur compatibles.
3. Écrire le chemin de fusion `inputs_embeds` dans le cœur réel.
4. Valider la chaîne complète image vers réponse sur du matériel adapté.

Aucune de ces quatre étapes n'est faite aujourd'hui.

---

## Fichiers concernés

| Chemin | Rôle |
|---|---|
| `cortex_ai/vision/core.py` | Interfaces encodeur, projecteur, fusion |
| `cortex_ai/vision/native.py` | Prototype de fusion native |
| `cortex_ai/vision/bridge.py` | Pont image-vers-texte fonctionnel |
| `cortex_ai/vision/train.py` | Entraînement du projecteur |
| `cortex_ai/vision/config.json` | Statut explicite et composants manquants |
| `examples/vision_bridge.py` | Exemple exécutable du pont |
| `examples/train_vision_projector.py` | Exemple exécutable d'entraînement |

---

## Résumé honnête

| Question | Réponse |
|---|---|
| Le pont image-vers-texte fonctionne-t-il ? | **Oui**, avec un modèle externe |
| La fusion native fonctionne-t-elle sur un cœur de test ? | **Oui** |
| La fusion native fonctionne-t-elle sur le vrai modèle ? | **Non, pas validée** |
| Le dépôt est-il un modèle de compréhension d'images ? | **Non** |
| Les poids du modèle de base ont-ils été modifiés pour la vision ? | **Non** |