Guide des réglages pour agents mini-me (en langage simple)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217

# Guide des réglages pour agents mini-me (en langage simple)

*[English version](agent-settings-for-small-models.md)*

> Ce guide explique, sans jargon, ce que fait chaque réglage de configuration d'un agent mini-me, pourquoi il existe, quelle est sa valeur par défaut, et comment le régler **quand on fait tourner un petit modèle de langage en local** (celui qui tient sur ton laptop, pas un modèle géant dans le cloud).

## Pourquoi ces réglages existent

Un petit modèle local (quelques milliards de paramètres, tournant sur un CPU/GPU grand public) n'a pas les mêmes défauts qu'un gros modèle cloud :

- il est **lent** — surtout pour lire un long prompt (le "prompt processing"),
- il a une **mémoire (fenêtre de contexte) limitée** — souvent 8k à 32k tokens, parfois moins,
- il **boucle ou décroche** plus facilement (répète la même commande, oublie ce qu'il a déjà lu, part en vrille dans un raisonnement),
- il peut **halluciner** un résultat de commande qu'il n'a jamais vraiment exécuté.

Les réglages ci-dessous sont les garde-fous qui compensent ça : ils disent à l'agent "arrête-toi si tu es trop lent", "ne garde pas tout en mémoire", "ne tourne pas en rond indéfiniment", "ne renvoie pas un pavé de texte qui bouche ta propre mémoire".

Ils se règlent dans le fichier YAML de l'agent (`agent.*.yaml`), sous les mêmes noms de clés.

---

## 1. `contextWindow` — la taille de la mémoire du modèle

**En clair** : c'est la taille de la "mémoire de travail" du modèle, exprimée en tokens (un token ≈ 0,75 mot). Tout ce que l'agent a dit, lu, exécuté doit tenir dans cette mémoire. Quand elle est pleine, il faut faire de la place (voir section `context` plus bas).

- **Valeur par défaut** : `0`, ce qui veut dire "je ne sais pas, demande au serveur". Si le serveur (llama.cpp, Docker Model Runner...) expose sa taille de contexte configurée, mini-me l'utilise automatiquement.
- **Comment la régler** : en général, **ne la fixe pas toi-même** si ton serveur peut la communiquer automatiquement — laisse `0`. Ne la renseigne à la main que si ton serveur ne la rapporte pas, et mets alors la vraie valeur que tu as configurée côté serveur (ex: `-c 8192` sur `llama-server` → `contextWindow: 8192`).
- **Pour un petit modèle** : les petits modèles sont souvent livrés avec une fenêtre annoncée de 32k ou plus, mais **en pratique, la qualité se dégrade bien avant** d'atteindre cette limite. Mieux vaut connaître la vraie valeur utilisable pour que les calculs de compression du contexte (section 8) soient fiables.

---

## 2. `firstTokenTimeout` — le temps qu'on laisse au modèle pour *commencer* à répondre

**En clair** : avant même que le modèle produise son premier mot, le serveur doit *lire* tout le prompt (la question + l'historique + les instructions). Sur un petit modèle local, lire un prompt de 20-30k tokens peut prendre plusieurs minutes. Ce réglage dit : "j'attends jusqu'à combien de temps avant de considérer que ça a planté ?"

- **Valeur par défaut** : `3 minutes`.
- **Particularité** : si le serveur (llama.cpp) donne des nouvelles de sa progression de lecture pendant ce temps, le chronomètre est **remis à zéro** à chaque nouvelle. Donc en pratique, tant que le serveur progresse, ça ne coupera pas — ce timeout protège surtout contre un vrai blocage silencieux.
- **Comment la régler** :
  - Modèle petit (≤ 8B) avec un bon GPU : la valeur par défaut (3 min) suffit généralement.
  - Modèle plus gros (15-30B) ou machine modeste (CPU seul, peu de VRAM), ou prompts très longs (gros `AGENTS.md`, beaucoup d'historique) : monte à `5m` voire `10m`.
  - Règle d'or : **jamais plus court que `watchdogTimeout`** (voir juste après) — sinon la protection n'a pas de sens.

---

## 3. `watchdogTimeout` — le chien de garde pendant que le modèle *génère*

**En clair** : une fois que le modèle a commencé à répondre (ou à utiliser un outil), ce réglage surveille qu'il continue à produire quelque chose régulièrement. S'il reste silencieux plus longtemps que cette durée *sans rien produire de nouveau*, mini-me considère que la connexion est bloquée et coupe.

- **Valeur par défaut** : `20 secondes`.
- **Différence avec `firstTokenTimeout`** : `firstTokenTimeout` surveille le **démarrage** (lecture du prompt), `watchdogTimeout` surveille la **suite** (génération token par token, ou l'exécution d'un outil). C'est pour ça que `watchdogTimeout` est beaucoup plus court.
- **Comment la régler** :
  - Si l'agent a accès à l'outil `bash` et que des commandes peuvent légitimement prendre du temps (build, tests, téléchargements), **monte ce timeout en même temps que `bashTimeout`** : pendant qu'une commande bash tourne, le chien de garde continue de compter, donc si `bashTimeout` vaut `2m`, `watchdogTimeout` doit valoir au moins `2m` aussi, sinon mini-me couperait la commande avant qu'elle finisse.
  - Pour un usage "chat" simple sans gros outils : la valeur par défaut convient très bien, y compris sur un petit modèle lent (c'est la génération token-par-token qui compte, pas la vitesse globale).

---

## 4. `bashTimeout` — combien de temps une commande shell a le droit de tourner

**En clair** : quand l'agent exécute une commande (`bash`), c'est le temps maximum avant que mini-me la tue de force, même si elle n'a rien renvoyé.

- **Valeur par défaut** : `30 secondes`.
- **Comment la régler** :
  - Tâches rapides (lire un fichier, `git status`, `ls`) : le défaut de 30s est largement suffisant.
  - Tâches lourdes attendues (compilation, tests, installation de dépendances, longue recherche) : augmente franchement, par exemple `2m`, `5m`, voire plus selon le projet.
  - **Toujours augmenter `watchdogTimeout` en même temps** (voir section 3) — c'est le piège le plus courant : une commande se fait tuer par le chien de garde alors que `bashTimeout` lui laissait le temps.
  - Ce réglage ne dépend pas vraiment de la taille du modèle, mais du type de projet sur lequel l'agent travaille.

---

## 5. `maxTurns` — combien d'allers-retours modèle ↔ outils sont autorisés pour une seule question

**En clair** : pour répondre à une question, l'agent peut faire plusieurs tours : "je lance une commande" → "je regarde le résultat" → "j'en lance une autre" → etc. Ce réglage plafonne le nombre de ces tours avant que mini-me arrête l'agent (pour éviter qu'il boucle à l'infini).

- **Valeur par défaut** : `10`.
- **Valeur réellement utilisée dans les configurations livrées** : `40` — l'expérience montre que 10 est souvent trop bas pour des tâches de code réalistes avec un petit modèle, qui a besoin de plus d'itérations (relire, corriger, retenter) qu'un gros modèle.
- **Comment la régler** :
  - Tâche étroite, une seule action attendue (répondre à une question factuelle, un seul appel d'outil) : `8` à `15` suffit, et ça protège mieux contre les boucles.
  - Agent de développement généraliste (explorer du code, éditer, tester) : `40` à `60` est raisonnable, surtout avec un petit modèle qui a besoin de plusieurs essais.
  - Plus le modèle est petit/faible, plus il risque de boucler sans jamais conclure — associe un `maxTurns` généreux à une bonne détection de boucle plutôt que de mettre une valeur énorme "au cas où".

---

## 6. `maxOutput` — la taille maximale de ce qu'un outil peut renvoyer au modèle

**En clair** : si une commande `bash` renvoie 500 000 caractères (un gros fichier de log, par exemple), on ne veut pas que ça remplisse d'un coup toute la mémoire du modèle. Ce réglage tronque le résultat avant de le montrer au modèle.

- **Valeur par défaut** : `16000` caractères.
- **Comment ça tronque** : pas juste en coupant à la fin — mini-me garde le **début** du résultat et jusqu'à 2000 caractères de la **fin**, car souvent l'information utile (erreur, résumé) est à la fin d'une sortie longue.
- **Comment la régler** :
  - Petit modèle à fenêtre de contexte réduite (8k-16k tokens) : **baisse** cette valeur, par exemple `4000` à `8000`, pour qu'une seule commande ne consomme pas un tiers de la mémoire disponible.
  - Modèle avec une grande fenêtre de contexte, ou agent qui a vraiment besoin de voir des sorties complètes (ex: analyser un gros diff) : tu peux monter à `20000`-`30000`, mais garde en tête que chaque sortie "coûte" en tokens et accélère le moment où la compression du contexte (section 8) se déclenche.

---

## 7. `agentsMd` — comment l'agent lit ses instructions de projet

**En clair** : `AGENTS.md` (ou équivalent) contient les instructions propres au projet que l'agent doit suivre. Ce bloc de réglages contrôle si/comment ce fichier est chargé.

```yaml
agentsMd:
  enabled: true
  path: "AGENTS.md"
  maxChars: 0
```

- **`enabled`** — défaut : `true`. Active la lecture automatique du fichier.
- **`path`** — défaut : `"AGENTS.md"`. Le nom/chemin du fichier à lire.
- **`maxChars`** — défaut : `0` (= pas de limite).

### Le point important sur `maxChars`

Ce n'est **pas** une troncature. Si le fichier `AGENTS.md` dépasse `maxChars` caractères, il n'est **pas coupé** — il est **entièrement ignoré** (le code source dit explicitement : couper au milieu risquerait de supprimer justement la règle qui compte). La bannière de démarrage l'indique (`skipped (too long)`) plutôt que de faire semblant d'avoir lu le fichier en entier.

- **Comment la régler** :
  - **Même sans `maxChars`, mini-me te prévient** : la bannière de démarrage avertit quand `AGENTS.md` occupe **20 % ou plus** d'une fenêtre de contexte connue (estimation : nombre de caractères ÷ 3,5). Avec un petit modèle, c'est le signe qu'il faut raccourcir le fichier.
  - **`maxChars` est une limite stricte en plus de cet avertissement.** Avec un petit modèle à faible fenêtre, un `AGENTS.md` trop long peut consommer une grosse part de la mémoire avant même que la conversation commence. Fixer `maxChars` garantit qu'il ne la dépassera jamais : au-delà, le fichier est ignoré et la bannière le dit, et tu sais qu'il faut le raccourcir.
  - Pour calculer une valeur : 20 % de la fenêtre × 3,5. Exemple : fenêtre de 8192 tokens → 20 % = 1638 tokens → environ `maxChars: 5700`.
  - Si ton `AGENTS.md` est court (quelques centaines de lignes maximum) et que ton modèle a une fenêtre confortable (32k+), tu peux laisser `0`.

---

## 8. `context` — la compression automatique de l'historique

**En clair** : au fur et à mesure que la conversation avance, l'historique (questions, réponses, résultats de commandes) grandit. Sur un petit modèle à mémoire limitée, il arrive un moment où tout ne tient plus. Ce bloc décide **quand** et **comment** résumer automatiquement les anciens échanges pour faire de la place, sans perdre le fil.

```yaml
context:
  enabled: false
  threshold: 75
  maxMessages: 80
  keepLastTurns: 3
  summaryMaxTokens: 1200
  prompt: ""
  showStats: true
```

| Sous-réglage | Défaut | Ce qu'il fait | Comment le régler |
|---|---|---|---|
| `enabled` | `false` | Active la compression automatique. Même désactivé, tu peux toujours lancer une compression manuelle. | **Active-le (`true`) pour tout petit modèle local** — c'est la protection principale contre le "contexte plein" qui fait planter ou dégrader l'agent. |
| `threshold` | `75` (%) | Pourcentage de la fenêtre de contexte à partir duquel la compression se déclenche. 75 % laisse volontairement un quart de la mémoire libre pour la prochaine question, les résultats d'outils et la réponse. | Ne descends pas trop bas (tu compresserais trop souvent, donc tu perds en continuité) ; ne monte pas trop haut (tu risques de saturer avant que la compression ait pu agir). 70-80 % est une bonne plage. |
| `maxMessages` | `80` | Déclencheur de secours basé sur le *nombre* de messages, utilisé quand la taille de la fenêtre est inconnue (`contextWindow: 0` et serveur muet sur le sujet). Une commande = 2 messages (l'appel + le résultat), donc 80 ≈ 30 commandes d'historique. | Le code justifie 80 ainsi : c'est à peu près le moment où un modèle local de 12B commence à ralentir. Sur un modèle plus petit, tu peux baisser cette valeur si tu remarques que l'agent devient plus lent ou confus avant d'atteindre 80 messages. Mets `0` pour désactiver ce déclencheur si tu es sûr de connaître `contextWindow`. |
| `keepLastTurns` | `3` | Nombre de derniers tours de conversation gardés **intacts** (non résumés) — c'est là que l'agent "travaille" activement, le résumer le ferait rejouer ce qu'il vient juste de faire. | Garde au moins `2`-`3`. Monte-le un peu (`4`-`5`) si tu remarques que l'agent "oublie" une action toute récente juste après une compression. |
| `summaryMaxTokens` | `1200` | Taille maximale du résumé généré pour remplacer les vieux échanges. Ce plafond empêche un modèle qui dérape de produire un résumé qui lui-même remplit la fenêtre qu'on cherchait à vider. | Pour un petit modèle, ne monte pas trop ce chiffre : un résumé doit rester compact. `1200` convient à la plupart des cas ; descends à `600`-`800` si tu veux économiser encore plus de place. |
| `prompt` | `""` (prompt intégré) | Permet de remplacer le prompt utilisé pour demander le résumé. | Laisse vide sauf besoin spécifique (ex: vouloir que le résumé garde un format particulier). |
| `showStats` | `true` | Affiche une ligne d'info après chaque compression (combien de tokens économisés, etc.). | Laisse activé, c'est utile pour vérifier que la compression fait bien son travail — désactive seulement si tu veux une sortie plus silencieuse. |

**Astuce pratique** : la compression envoie le résumé au modèle **sans les outils actifs et sans le mode "raisonnement"**, justement pour que `summaryMaxTokens` ne soit pas gaspillé en réflexion plutôt qu'en résumé utile.

---

## Résumé — profils types

| Situation | `firstTokenTimeout` | `watchdogTimeout` | `bashTimeout` | `maxTurns` | `maxOutput` | `context.enabled` |
|---|---|---|---|---|---|---|
| Petit modèle (≤ 8B), tâches courtes/chat, sans `bash` ou avec des commandes de moins de 20 s | `3m` (défaut) | `20s` (défaut) | `30s` (défaut) | `15` | `8000` | `true` |
| Petit/moyen modèle, agent de code généraliste | `5m` | `2m` (aligné sur bashTimeout) | `2m` | `40` | `16000` | `true` |
| Modèle plus gros ou machine modeste (CPU) | `10m` | `5m` | `5m` | `40`-`60` | `16000`-`24000` | `true` |

Dans la première ligne, `watchdogTimeout` (20 s) est plus court que `bashTimeout` (30 s) : ce sont les valeurs par défaut, et elles ne conviennent que si aucune commande ne dure plus de 20 s. Dès que l'agent lance des commandes plus longues, aligne les deux comme dans les lignes suivantes (section 3).

Ces profils sont des points de départ, pas des vérités absolues — ajuste en observant le comportement réel de ton modèle (est-ce qu'il boucle, est-ce qu'il se fait couper trop tôt, est-ce que le contexte se remplit trop vite).

---

## 9. Section sampling — comment le modèle choisit ses mots

**En clair** : le "sampling" (échantillonnage), ce sont les réglages qui contrôlent la façon dont le modèle pioche le mot suivant parmi toutes les possibilités qu'il juge plausibles. C'est la partie qui décide si le modèle est **précis et prévisible** ou **créatif et varié**. Contrairement aux réglages précédents (timeouts, quotas), le sampling n'a pas de struct figée dans mini-me : c'est une liste libre de clés (`sampling:` dans le YAML) transmise quasiment telle quelle au serveur du modèle.

```yaml
sampling:
  temperature: 0.0
  top_p: 0.9
  max_tokens: 4096
```

Ce sont les trois seules clés définies par défaut dans mini-me. Les autres (`top_k`, `min_p`, `repeat_penalty`...) ne sont pas fixées par défaut — à toi de les ajouter si ton serveur/modèle les supporte et si tu en as besoin.

### `temperature` — le curseur "précis ↔ créatif"

**En clair** : plus elle est proche de `0`, plus le modèle choisit systématiquement le mot qu'il juge le plus probable (réponses stables, reproductibles, parfois un peu rigides). Plus elle monte vers `1` (ou au-delà), plus il accepte de piocher des mots moins évidents (réponses plus variées, mais aussi plus de risques d'erreurs ou d'écarts).

- **Défaut mini-me** : `0.0` — volontairement très bas, car mini-me est pensé pour un **agent de code**, où on veut de la précision et de la reproductibilité, pas de la créativité.
- **Comment la régler pour un petit modèle** :
  - Agent qui exécute des commandes, écrit du code, suit des instructions strictes : **garde `0.0`-`0.2`**. Un petit modèle est déjà plus sujet aux erreurs et aux boucles qu'un gros modèle ; une température basse réduit ce risque.
  - Agent conversationnel, créatif, ou qui doit reformuler/brainstormer : monte à `0.5`-`0.8`. Au-delà de `0.8`, un petit modèle part plus facilement en incohérence.

### `top_p` (nucleus sampling) — la largeur du choix

**En clair** : au lieu de considérer tous les mots possibles, le modèle ne regarde que le plus petit groupe de mots dont la probabilité cumulée atteint ce pourcentage. `top_p: 0.9` veut dire "ne considère que les mots qui, ensemble, couvrent 90 % de la probabilité — ignore la longue traîne improbable".

- **Défaut mini-me** : `0.9`.
- **Comment la régler** : combiné à une `temperature` basse, `0.9` est déjà un bon compromis "sûr" pour un petit modèle. Tu peux descendre à `0.8` si tu veux encore réduire les écarts bizarres ; inutile de monter plus haut pour un agent de code.

### `top_k` — limiter le nombre de candidats (optionnel, pas de défaut dans mini-me)

**En clair** : ne garde que les `k` mots les plus probables à chaque étape, et ignore tout le reste, quel que soit `top_p`.

- **Comment la régler** : les petits modèles (souvent Qwen, Gemma, Llama en petites tailles) n'ont pas tous la même sensibilité à `top_k` — certaines familles de modèles recommandent explicitement une valeur (par exemple `20`-`40`) dans leur fiche technique. **Vérifie les métadonnées/recommandations du modèle GGUF que tu utilises** plutôt que de deviner : un `top_k` mal choisi peut rendre un petit modèle plus répétitif ou au contraire plus instable.

### `repeat_penalty` / `min_p` — anti-répétition (optionnel, pas de défaut dans mini-me)

**En clair** : `repeat_penalty` pénalise le modèle s'il réutilise un mot déjà employé récemment (utile contre les boucles de répétition, un défaut classique des petits modèles). `min_p` est une alternative à `top_p` qui élimine les mots dont la probabilité est trop faible par rapport au mot le plus probable du moment.

- **Comment les régler** : ce sont typiquement les réglages qui **varient le plus d'une famille de modèle à l'autre** — il n'existe pas de valeur universelle. La bonne pratique est de reprendre les valeurs recommandées par la fiche du modèle (souvent indiquées dans les métadonnées GGUF ou la documentation du modèle) plutôt que d'improviser. Si l'agent répète des phrases ou des actions en boucle, c'est souvent le premier réglage à ajuster, avec le détecteur de boucle de mini-me et `maxTurns` (section 5).

### `max_tokens` — la longueur maximale d'une réponse

**En clair** : combien de tokens le modèle a le droit de générer en une seule réponse avant d'être coupé.

- **Défaut mini-me** : `4096`.
- **Comment la régler** : pour un petit modèle avec une fenêtre de contexte réduite, vérifie que `max_tokens` laisse assez de place dans la fenêtre pour le prompt lui-même — `max_tokens` + taille du prompt ne doit pas dépasser `contextWindow`. Baisse-le (`1024`-`2048`) si tes réponses doivent rester courtes (ex: classification, extraction) ; garde la valeur par défaut pour un agent qui doit écrire du code ou des explications plus longues.

### En résumé — philosophie du sampling dans mini-me

mini-me part du principe qu'un **petit modèle local est un agent de code avant tout**, donc ses réglages de sampling par défaut privilégient la **précision et la reproductibilité** (`temperature: 0.0`) plutôt que la créativité. C'est le point de départ le plus sûr pour limiter les erreurs, les hallucinations de résultats de commandes et les boucles — quitte à l'assouplir toi-même si ton usage est plus conversationnel ou créatif.

> Il n'existe pas aujourd'hui dans mini-me de "profil de sampling" automatique par famille de modèle — les valeurs par défaut sont génériques et volontairement conservatrices. Si tu changes de modèle, pense à revérifier ces réglages plutôt que de garder ceux d'un autre modèle par habitude.