# Gemma 3n : Comment exécuter et fine-tuner
Le modèle multimodal Gemma 3n de Google gère les entrées image, audio, vidéo et texte. Disponible en tailles 2B et 4B, il prend en charge 140 langues pour les tâches textuelles et multimodales. Vous pouvez maintenant exécuter et affiner **Gemma-3n-E4B** et **E2B** localement en utilisant [Unsloth](https://github.com/unslothai/unsloth).
> **Affinez Gemma 3n avec notre** [**notebook Colab gratuit**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Gemma3N_\(4B\)-Conversational.ipynb)
Gemma 3n dispose de **32K de longueur de contexte**, 30s d'entrée audio, OCR, reconnaissance automatique de la parole (ASR) et traduction vocale via des invites.
Tutoriel d'exécutionTutoriel de fine-tuningCorrections + Analyse technique
**Uploads Unsloth Gemma 3n (Instruct) avec configurations optimales :**
**Voir tous nos uploads Gemma 3n incluant la base et d'autres formats dans** [**notre collection ici**](https://huggingface.co/collections/unsloth/gemma-3n-685d3874830e49e1c93f9339)**.**
## 🖥️ Exécution de Gemma 3n
Actuellement Gemma 3n est uniquement pris en charge au format **texte** pour l'inférence.
{% hint style="info" %}
Nous avons [corrigé des problèmes](#fixes-for-gemma-3n) avec des GGUF qui ne fonctionnaient pas correctement uniquement dans Ollama. Veuillez retélécharger si vous utilisez Ollama.
{% endhint %}
### :gear: Paramètres officiels recommandés
Selon l'équipe Gemma, les paramètres officiels recommandés pour l'inférence :
`temperature = 1.0, top_k = 64, top_p = 0.95, min_p = 0.0`
* Température de 1.0
* Top\_K de 64
* Min\_P de 0.00 (optionnel, mais 0.01 fonctionne bien, la valeur par défaut de llama.cpp est 0.1)
* Top\_P de 0.95
* Pénalité de répétition de 1.0. (1.0 signifie désactivé dans llama.cpp et transformers)
* Modèle de chat :
<bos><start_of_turn>user\nHello!<end_of_turn>\n<start_of_turn>model\nHey there!<end_of_turn>\n<start_of_turn>user\nWhat is 1+1?<end_of_turn>\n<start_of_turn>model\n
* Modèle de chat avec `\n`retours à la ligne rendus (sauf pour le dernier)
{% code overflow="wrap" %}
```
user
Hello!model
Hey there!user
What is 1+1?model\n
```
{% endcode %}
{% hint style="danger" %}
llama.cpp et d'autres moteurs d'inférence ajoutent automatiquement un \ - NE PAS ajouter DEUX tokens \ ! Vous devez ignorer le \ lors de la création d'invites pour le modèle !
{% endhint %}
### :llama: Tutoriel : Comment exécuter Gemma 3n dans Ollama
{% hint style="success" %}
Veuillez retélécharger les quants Gemma 3N ou supprimer les anciens via Ollama car il y a des corrections de bugs. Vous pouvez faire ce qui suit pour supprimer l'ancien fichier et le rafraîchir :
```
ollama rm hf.co/unsloth/gemma-3n-E4B-it-GGUF:UD-Q4_K_XL
ollama run hf.co/unsloth/gemma-3n-E4B-it-GGUF:UD-Q4_K_XL
```
{% endhint %}
1. Installez `ollama` si vous ne l'avez pas encore fait !
```bash
apt-get update
apt-get install pciutils -y
curl -fsSL https://ollama.com/install.sh | sh
```
2. Exécutez le modèle ! Notez que vous pouvez appeler `ollama serve`dans un autre terminal si cela échoue ! Nous incluons toutes nos corrections et paramètres suggérés (température, etc.) dans `params` dans notre upload Hugging Face !
```bash
ollama run hf.co/unsloth/gemma-3n-E4B-it-GGUF:UD-Q4_K_XL
```
### 📖 Tutoriel : Comment exécuter Gemma 3n dans llama.cpp
{% hint style="info" %}
Nous souhaitons d'abord remercier [Xuan-Son Nguyen](https://x.com/ngxson) de Hugging Face, [Georgi Gerganov](https://x.com/ggerganov) de l'équipe llama.cpp pour avoir fait fonctionner Gemma 3N dans llama.cpp !
{% endhint %}
1. Obtenez le dernier `llama.cpp` sur [GitHub ici](https://github.com/ggml-org/llama.cpp). Vous pouvez également suivre les instructions de construction ci-dessous. Changez `-DGGML_CUDA=ON` en `-DGGML_CUDA=OFF` si vous n'avez pas de GPU ou si vous souhaitez simplement une inférence CPU. **Pour les appareils Apple Mac / Metal**, définissez `-DGGML_CUDA=OFF` puis continuez comme d'habitude - le support Metal est activé par défaut.
```bash
apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone https://github.com/ggml-org/llama.cpp
cmake llama.cpp -B llama.cpp/build \
-DBUILD_SHARED_LIBS=ON -DGGML_CUDA=ON -DLLAMA_CURL=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-quantize llama-cli llama-gguf-split llama-mtmd-cli
cp llama.cpp/build/bin/llama-* llama.cpp
```
2. Si vous voulez utiliser `llama.cpp` directement pour charger des modèles, vous pouvez faire ce qui suit : (:Q4\_K\_XL) est le type de quantification. Vous pouvez aussi télécharger via Hugging Face (point 3). C'est similaire à `ollama run`
```bash
./llama.cpp/llama-cli -hf unsloth/gemma-3n-E4B-it-GGUF:UD-Q4_K_XL -ngl 99 --jinja
```
3. **OU** téléchargez le modèle via (après avoir installé `pip install huggingface_hub hf_transfer` ). Vous pouvez choisir Q4\_K\_M, ou d'autres versions quantifiées (comme BF16 en précision complète).
```python
# !pip install huggingface_hub hf_transfer
import os
os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "1"
from huggingface_hub import snapshot_download
snapshot_download(
repo_id = "unsloth/gemma-3n-E4B-it-GGUF",
local_dir = "unsloth/gemma-3n-E4B-it-GGUF",
allow_patterns = ["*UD-Q4_K_XL*", "mmproj-BF16.gguf"], # Pour Q4_K_XL
)
```
4. Exécutez le modèle.
5. Éditez `--threads 32` pour le nombre de threads CPU, `--ctx-size 32768` pour la longueur de contexte (Gemma 3 prend en charge 32K de longueur de contexte !), `--n-gpu-layers 99` pour le déchargement GPU concernant le nombre de couches. Essayez de l'ajuster si votre GPU manque de mémoire. Supprimez-le également si vous n'utilisez que le CPU pour l'inférence.
6. Pour le mode conversation :
```bash
./llama.cpp/llama-cli \
--model unsloth/gemma-3n-E4B-it-GGUF/gemma-3n-E4B-it-UD-Q4_K_XL.gguf \
--mmproj unsloth/gemma-3n-E4B-it-GGUF/mmproj-BF16.gguf \
--ctx-size 32768 \
--n-gpu-layers 99 \
--seed 3407 \
--prio 2 \
--temp 1.0 \
--repeat-penalty 1.0 \
--min-p 0.00 \
--top-k 64 \
--top-p 0.95
```
7. Pour le mode non-conversation pour tester Flappy Bird :
```bash
./llama.cpp/llama-cli \
--model unsloth/gemma-3n-E4B-it-GGUF/gemma-3n-E4B-it-UD-Q4_K_XL.gguf \
--mmproj unsloth/gemma-3n-E4B-it-GGUF/mmproj-BF16.gguf \
--ctx-size 32768 \
--n-gpu-layers 99 \
--seed 3407 \
--prio 2 \
--temp 1.0 \
--repeat-penalty 1.0 \
--min-p 0.00 \
--top-k 64 \
--top-p 0.95 \
-no-cnv \
--prompt "user\nCreate a Flappy Bird game in Python. You must include these things:\n1. You must use pygame.\n2. The background color should be randomly chosen and is a light shade. Start with a light blue color.\n3. Pressing SPACE multiple times will accelerate the bird.\n4. The bird's shape should be randomly chosen as a square, circle or triangle. The color should be randomly chosen as a dark color.\n5. Place on the bottom some land colored as dark brown or yellow chosen randomly.\n6. Make a score shown on the top right side. Increment if you pass pipes and don't hit them.\n7. Make randomly spaced pipes with enough space. Color them randomly as dark green or light brown or a dark gray shade.\n8. When you lose, show the best score. Make the text inside the screen. Pressing q or Esc will quit the game. Restarting is pressing SPACE again.\nThe final game should be inside a markdown section in Python. Check your code for errors and fix them before the final markdown section.\nmodel\n"
```
{% hint style="danger" %}
N'oubliez pas de supprimer \ car Gemma 3N ajoute automatiquement un \ !
{% endhint %}
## 🦥 Fine-tuning de Gemma 3n avec Unsloth
Gemma 3n, comme [Gemma 3](https://unsloth.ai/docs/fr/modeles/tutorials/gemma-3-how-to-run-and-fine-tune/..#unsloth-fine-tuning-fixes-for-gemma-3), a eu des problèmes d'exécution sur **GPU Flotat16 tels que les Tesla T4 dans Colab**. Vous rencontrerez des NaN et des infinis si vous ne corrigez pas Gemma 3n pour l'inférence ou le fine-tuning. [Plus d'informations ci-dessous](#infinities-and-nan-gradients-and-activations).
* Affinez Gemma 3n-E4B avec notre [notebook Colab gratuit](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Gemma3N_\(4B\)-Conversational.ipynb)
* **Audio :** Affinez Gemma 3n-E4B avec notre [**Notebook audio uniquement**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Gemma3N_\(4B\)-Audio.ipynb)
* **Vision** : Affinez Gemma 3n-E4B avec notre [**Notebook vision uniquement**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Gemma3N_\(4B\)-Vision.ipynb)
Nous avons également constaté que, parce que l'architecture unique de Gemma 3n réutilise les états cachés dans l'encodeur vision, cela pose une autre particularité intéressante avec [Gradient Checkpointing décrit ci-dessous](#gradient-checkpointing-issues)
**Unsloth est le seul framework qui fonctionne sur des machines float16 pour l'inférence et l'entraînement de Gemma 3n.** Cela signifie que les notebooks Colab avec GPU Tesla T4 gratuits fonctionnent également ! Dans l'ensemble, Unsloth rend l'entraînement de Gemma 3n 1,5x plus rapide, utilise 50 % moins de VRAM et permet des longueurs de contexte 4x plus longues.
Nos notebooks Colab gratuits pour Gemma 3n sont par défaut configurés pour affiner les couches textuelles. Si vous voulez affiner aussi les couches vision ou audio, sachez que cela nécessitera beaucoup plus de VRAM - au-delà des 15 Go fournis gratuitement par Colab ou Kaggle. Vous *pouvez* toujours affiner toutes les couches incluant audio et vision et Unsloth vous permet aussi d'affiner seulement des zones spécifiques, comme uniquement la vision. Ajustez simplement selon vos besoins :
```python
model = FastVisionModel.get_peft_model(
model,
finetune_vision_layers = False, # False si vous n'affinez pas les couches vision
finetune_language_layers = True, # False si vous n'affinez pas les couches langage
finetune_attention_modules = True, # False si vous n'affinez pas les couches d'attention
finetune_mlp_modules = True, # False si vous n'affinez pas les couches MLP
)
```
#### :trophy:Contenu bonus
Nous avons aussi entendu que vous vouliez un **Notebook Vision pour Gemma 3 (4B)** alors le voici :
* Affinez Gemma 3 (4B) avec support Vision en utilisant notre [notebook Colab gratuit](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Gemma3_\(4B\)-Vision.ipynb)
{% hint style="info" %}
Si vous aimez Kaggle, Google organise une compétition où le meilleur modèle affiné avec Gemma 3n et Unsloth remportera un prix de 10 000 $ ! [Voir plus ici](https://www.kaggle.com/competitions/google-gemma-3n-hackathon).
{% endhint %}
## 🐛Corrections pour Gemma 3n
### :sparkles:Problèmes & corrections GGUF
Grâce aux discussions de [Michael](https://github.com/mxyng) de l'équipe Ollama et aussi [Xuan](https://x.com/ngxson) de Hugging Face, il y avait 2 problèmes que nous avons dû corriger spécifiquement pour les GGUF :
1. Le `add_shared_kv_layers` paramètre a été accidentellement encodé en `float32` ce qui est acceptable, mais devient légèrement compliqué à décoder du côté d'Ollama - un simple changement en `uint32` résout le problème. [Pull request](https://github.com/ggml-org/llama.cpp/pull/14450) traitant ce problème.
2. Le `per_layer_token_embd` la couche devrait être en Q8\_0 en précision. Tout ce qui est inférieur ne fonctionne pas correctement et génère des erreurs dans le moteur Ollama - pour réduire les problèmes pour notre communauté, nous avons mis tout cela en Q8\_0 dans tous les quants - malheureusement cela utilise plus d'espace.
1. Comme une [mise à jour](https://huggingface.co/unsloth/gemma-3n-E4B-it-GGUF/discussions/4), [Matt](https://huggingface.co/WBB2500) a mentionné que nous pouvons également utiliser Q4\_0, Q4\_1, Q5\_0, Q5\_1 pour les embeddings - et nous avons confirmé que cela fonctionne aussi dans Ollama ! Cela signifie encore une fois que les quants plus petits en 2, 3 et 4 bits sont plus petits en taille, et n'ont pas besoin de Q8\_0 !
## :infinity:Infinis et gradients/activations NaN
{% columns %}
{% column %}
Gemma 3n, tout comme Gemma 3, a des problèmes sur les GPU FP16 (par ex. les Tesla T4 dans Colab).
Nos corrections précédentes pour Gemma 3 sont [discutées ici](https://unsloth.ai/docs/fr/modeles/tutorials/gemma-3-how-to-run-and-fine-tune). Pour Gemma 3, nous avons constaté que les activations dépassent la plage maximale du float16 de **65504.**
**Gemma 3N n'a pas ce problème d'activation, mais nous avons quand même rencontré des infinis !**
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
Pour comprendre l'origine de ces infinis, nous avons tracé les valeurs absolues maximales des entrées de poids pour Gemma 3N, et nous voyons ci-dessous :
Nous constatons que les croix vertes sont les poids de convolution Conv2D. On peut voir que l'amplitude des couches Conv2D est en moyenne beaucoup plus grande.
Ci-dessous se trouve un tableau des poids Conv2D qui ont de grandes amplitudes. Notre hypothèse est que lors d'une opération Conv2D, de grands poids se multiplient et se somment, et **malheureusement dépassent par hasard la plage maximale du float16 de 65504.** Bfloat16 convient, car sa plage maximale est de 10^38.
| Nom | Max |
| -------------------------------------- | --------- |
| msfa.ffn.pw\_proj.conv.weight | 98.000000 |
| blocks.2.21.attn.key.down\_conv.weight | 37.000000 |
| blocks.2.32.pw\_exp.conv.weight | 34.750000 |
| blocks.2.30.pw\_exp.conv.weight | 33.750000 |
| blocks.2.34.pw\_exp.conv.weight | 33.750000 |
### :sparkler:Solution aux infinis
La solution naïve est de `promouvoir` tous les poids Conv2D en float32 (si bfloat16 n'est pas disponible). Mais cela augmenterait l'utilisation de la VRAM. Pour y remédier, nous utilisons plutôt `autocast` à la volée pour promouvoir les poids et les entrées en float32, et ainsi nous effectuons l'accumulation en float32 dans le cadre de la multiplication matricielle elle-même, sans avoir à promouvoir les poids.
{% hint style="success" %}
Unsloth est le seul framework qui permet l'inférence et l'entraînement de Gemma 3n sur des GPU float16, donc les notebooks Colab avec Tesla T4 gratuits fonctionnent !
{% endhint %}
### :checkered\_flag:Problèmes de Gradient Checkpointing
Nous avons trouvé que l'encodeur vision de Gemma 3N est également assez unique car il réutilise les états cachés. Cela limite malheureusement l'utilisation du [Gradient Checkpointing d'Unsloth](https://unsloth.ai/blog/long-context), qui aurait pu réduire significativement l'utilisation de la VRAM, puisque cela ne peut pas être appliqué à l'encodeur Vision.
Cependant, nous avons tout de même réussi à tirer parti de **le compilateur automatique d'Unsloth** pour optimiser Gemma 3N !
### :cactus:Pertes élevées pendant le fine-tuning
Nous avons aussi constaté que les pertes sont étonnamment très élevées au début du fine-tuning - de l'ordre de 6 à 7, mais elles diminuent rapidement avec le temps. Nous émettons l'hypothèse que cela peut venir de 2 possibilités :
1. Il pourrait y avoir un problème d'implémentation, mais cela est peu probable étant donné que l'inférence semble fonctionner.
2. **Les modèles multimodaux semblent toujours exhiber ce comportement** - nous avons constaté que la perte de Llama 3.2 Vision commence à 3 ou 4, Pixtral autour de 8, et Qwen 2.5 VL aussi autour de 4. Parce que Gemma 3N inclut aussi l'audio, cela pourrait amplifier la perte de départ. Mais ce n'est qu'une hypothèse. Nous avons aussi constaté que quantifier Qwen 2.5 VL 72B Instruct produit des scores de perplexité extrêmement élevés autour de 30 environ, mais le modèle fonctionne néanmoins correctement.
{% hint style="success" %}
**Affinez Gemma 3n avec notre** [**notebook Colab gratuit**](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Gemma3N_\(4B\)-Conversational.ipynb)
{% endhint %}
## 🛠️ Analyse technique
### Gemma 3n : MatFormer
Qu'y a-t-il de si spécial chez Gemma 3n ? Il est basé sur [l'architecture Matryoshka Transformer ou MatFormer](https://arxiv.org/abs/2310.07707) signifiant que chaque couche/bloc de transformeur intègre/niche des FFN de tailles progressivement plus petites. Pensez-y comme des tasses de tailles progressivement plus petites imbriquées les unes dans les autres. L'entraînement est effectué de sorte qu'au moment de l'inférence vous puissiez choisir la taille souhaitée et tirer le meilleur parti des performances des modèles plus grands.
Il existe aussi un Per Layer Embedding qui peut être mis en cache pour réduire l'utilisation de la mémoire à l'inférence. Ainsi, le modèle 2B (E2B) est un sous-réseau à l'intérieur du modèle 4B (alias 5.44B) qui est obtenu à la fois par la mise en cache du Per Layer Embedding et en sautant les composants audio et vision pour se concentrer uniquement sur le texte.
L'architecture MatFormer est typiquement entraînée avec des sous-modèles espacés exponentiellement, alias de tailles `S`, `S/2, S/4, S/8` etc. dans chacune des couches. Ainsi, au moment de l'entraînement, les entrées sont transmises au hasard à travers l'un des sous-blocs mentionnés, donnant à chaque sous-bloc une chance égale d'apprendre. Maintenant l'avantage est que, au moment de l'inférence, si vous voulez que le modèle soit 1/4 de la taille originale, vous pouvez choisir `S/4` tailles de sous-blocs dans chaque couche.
Vous pouvez aussi choisir de **mélanger et assortir** où vous choisissez par exemple, `S/4` une taille de sous-bloc d'une couche, `S/2` taille de sous-bloc d'une autre couche et `S/8` taille de sous-bloc d'une autre couche. En fait, vous pouvez changer les sous-modèles que vous choisissez en fonction de l'entrée elle-même si vous le souhaitez. C'est essentiellement comme choisir votre propre structure à chaque couche. Donc en entraînant un modèle d'une taille particulière, vous créez exponentiellement de nombreux modèles de tailles plus petites. Aucun apprentissage n'est perdu. Plutôt astucieux, non ?
.png?alt=media)
