Skip to content

Commit ca7beb4

Browse files
docs(blog): tutoriel PPO avant / après, FR et EN (#124)
Texte visé par Abaddon, rejoué par Talos sur 2e9a24a (PASS). Lien vers la démo publique /demos/target-chasing/ppo.html, vérifiée en prod le 19/11. Image d'aperçu : capture réelle de la démo en prod. Co-authored-by: Lucius (IgnitionAI) <noreply@anthropic.com>
1 parent e6a9057 commit ca7beb4

5 files changed

Lines changed: 154 additions & 0 deletions

File tree

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
An agent that "learns" should prove it with its own logs, not with an animation. This demo compares a PPO policy before and after training on a deliberately tiny task, and shows numbers read from the files the training run produced.
2+
3+
**You will train the agent yourself, get the same numbers, then watch them replayed in the browser.**
4+
5+
[Try the PPO before / after demo](/demos/target-chasing/ppo.html)
6+
7+
## The task
8+
9+
A point moves on the segment [0, 1], starting at a random position between 0 and 0.4. At each step the agent picks one of two actions: move +0.15 or −0.15. The episode succeeds when the position passes 0.7 and stops after at most 25 steps. Success gives +1; each step without success costs −0.05. The agent observes one value: its position.
10+
11+
The protocol was frozen before any training in `packages/demo-target-chasing/ppo-experiment.json`: three seeds (11, 29, 47), 80 episodes per seed, a [32, 32] network, PPO with clip 0.2, gamma 0.99, GAE lambda 0.95, 4 epochs, batches of 16.
12+
13+
## Reproduce the training
14+
15+
Node.js 22 and pnpm 10.8.0 (used here: Node 22.23.4, pnpm 10.8.0).
16+
17+
```bash
18+
git clone https://github.com/IgnitionAI/ignition.git
19+
cd ignition
20+
git checkout 2e9a24a3a2f53000fefb7ce31eecbacb1bf5c104
21+
corepack enable
22+
pnpm install --frozen-lockfile
23+
pnpm --filter @ignitionai/core build
24+
pnpm --filter @ignitionai/backend-tfjs build
25+
node scripts/train-ppo-nav1d.mjs
26+
```
27+
28+
Both builds are required because the script loads the compiled packages (`dist/`). Training the three seeds took about 5 seconds on our machine (CPU, no `tfjs-node`; TensorFlow.js prints a warning that does not change the result).
29+
30+
| Seed | Mean of first 20 episodes | Mean of last 20 | Greedy eval before | after | gap |
31+
|---|---|---|---|---|---|
32+
| 11 | 0.4425 | 0.85 | 0.845 | 0.845 | 0 |
33+
| 29 | −0.18 | 0.8175 | −1.25 | 0.855 | 2.105 |
34+
| 47 | 0.1475 | 0.855 | 0.855 | 0.855 | 0 |
35+
36+
"Greedy" means the agent always takes its most likely action, on the same 20 starts before and after. These values match the repository: training is deterministic for these seeds. Only `manifest.json` (SHA, timestamps) and `train-result.json` change; restore with `git checkout -- packages/demo-target-chasing/public/ppo`. Artifact check: `pnpm exec vitest run packages/demo-target-chasing/test/ppo-artifacts.test.ts`, 4 tests pass.
37+
38+
## Read the result honestly
39+
40+
- All three seeds meet the pre-registered criterion (last 20 episodes beat the first 20).
41+
- In greedy evaluation, **only seed 29 changes**: seeds 11 and 47 were already correct before training. Their curve rises because the policy becomes less random, not because it finds a better action.
42+
- The demo therefore shows seed 29 by default, by a rule written in the manifest: largest before/after gap.
43+
- 80 episodes on a one-dimensional task: a demonstration of the mechanism, **not a benchmark**.
44+
45+
## Open the demo
46+
47+
```bash
48+
pnpm --filter target-chasing build
49+
cd packages/demo-target-chasing
50+
pnpm exec vite preview --host 127.0.0.1 --port 4173
51+
```
52+
53+
Open `http://127.0.0.1:4173/ppo.html`, or [the online demo](/demos/target-chasing/ppo.html). **Replay untrained** then **Play greedy episode**: −1.250 from 0.2. **Replay trained checkpoint** then **Play greedy episode**: 0.850. The curve comes from the `episodes.json` files. A missing training log (`episodes.json`) shows "PPO checkpoint/log absent". Limit observed on 19/11: if the trained checkpoint is missing, the page shows no message and stays on the untrained replay.
54+
55+
## Observed limits (19/11)
56+
57+
Under `vite preview` a missing file falls back to HTML with status 200, so the error message reads "(200)"; checked in a server-side browser (software rendering), not on a real phone.
Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
Un agent qui « apprend » doit le montrer sur ses propres journaux, pas sur une animation. Cette démo compare une politique PPO avant et après entraînement, sur une tâche volontairement minuscule, et affiche les chiffres lus dans les fichiers produits par l'entraînement.
2+
3+
**Vous allez entraîner l'agent vous-même, retrouver les mêmes chiffres, puis les voir rejoués dans le navigateur.**
4+
5+
[Essayer la démo PPO avant / après](/demos/target-chasing/ppo.html)
6+
7+
## La tâche
8+
9+
Un point se déplace sur un segment [0, 1]. Il part d'une position tirée au hasard entre 0 et 0,4. À chaque pas, l'agent choisit entre deux actions : avancer de 0,15 ou reculer de 0,15. L'épisode réussit si la position dépasse 0,7 ; il s'arrête au plus tard après 25 pas. Une réussite rapporte +1 ; chaque pas sans réussite coûte −0,05. L'agent n'observe qu'une valeur : sa position.
10+
11+
Le protocole a été figé avant tout entraînement dans `packages/demo-target-chasing/ppo-experiment.json` : trois graines (11, 29, 47), 80 épisodes par graine, un réseau [32, 32], PPO avec clip 0,2, gamma 0,99, GAE lambda 0,95, 4 époques, lots de 16.
12+
13+
## Reproduire l'entraînement
14+
15+
Node.js 22 et pnpm 10.8.0 (versions utilisées pour ce tuto : Node 22.23.4, pnpm 10.8.0).
16+
17+
```bash
18+
git clone https://github.com/IgnitionAI/ignition.git
19+
cd ignition
20+
git checkout 2e9a24a3a2f53000fefb7ce31eecbacb1bf5c104
21+
corepack enable
22+
pnpm install --frozen-lockfile
23+
pnpm --filter @ignitionai/core build
24+
pnpm --filter @ignitionai/backend-tfjs build
25+
node scripts/train-ppo-nav1d.mjs
26+
```
27+
28+
Les deux builds sont nécessaires : le script charge les paquets compilés (`dist/`). L'entraînement des trois graines a pris environ 5 secondes sur notre machine (CPU, sans `tfjs-node` ; TensorFlow.js le signale par un avertissement, sans effet sur le résultat).
29+
30+
Le script écrit une ligne par graine. Résultat obtenu :
31+
32+
| Graine | Moyenne des 20 premiers épisodes | Moyenne des 20 derniers | Évaluation gloutonne avant | après | écart |
33+
|---|---|---|---|---|---|
34+
| 11 | 0,4425 | 0,85 | 0,845 | 0,845 | 0 |
35+
| 29 | −0,18 | 0,8175 | −1,25 | 0,855 | 2,105 |
36+
| 47 | 0,1475 | 0,855 | 0,855 | 0,855 | 0 |
37+
38+
« Gloutonne » veut dire que l'agent prend toujours l'action la plus probable, sur les 20 mêmes départs avant et après.
39+
40+
Ces valeurs sont celles du dépôt : l'entraînement est déterministe pour ces graines. Seuls `manifest.json` (SHA et horodatage) et `train-result.json` changent. Pour revenir à l'état du dépôt :
41+
42+
```bash
43+
git checkout -- packages/demo-target-chasing/public/ppo
44+
```
45+
46+
Contrôle des artefacts :
47+
48+
```bash
49+
pnpm exec vitest run packages/demo-target-chasing/test/ppo-artifacts.test.ts
50+
```
51+
52+
Attendu : 4 tests passés.
53+
54+
## Lire honnêtement le résultat
55+
56+
- Les trois graines remplissent le critère fixé à l'avance (les 20 derniers épisodes font mieux que les 20 premiers).
57+
- Mais en évaluation gloutonne, **seule la graine 29 change** : les graines 11 et 47 étaient déjà correctes avant l'entraînement. Leur courbe monte parce que la politique devient moins aléatoire, pas parce qu'elle découvre une meilleure action.
58+
- La démo choisit donc la graine 29 par défaut, selon une règle écrite dans le manifest : le plus grand écart avant / après.
59+
- 80 épisodes sur une tâche à une dimension : c'est une démonstration du mécanisme, **pas un benchmark**.
60+
61+
## Ouvrir la démo
62+
63+
```bash
64+
pnpm --filter target-chasing build
65+
cd packages/demo-target-chasing
66+
pnpm exec vite preview --host 127.0.0.1 --port 4173
67+
```
68+
69+
Ouvrez `http://127.0.0.1:4173/ppo.html`, ou directement [la démo en ligne](/demos/target-chasing/ppo.html). La page charge le manifest, les journaux et les deux checkpoints de la graine 29 :
70+
71+
- **Rejouer la politique non entraînée**, puis **Jouer un épisode glouton** : depuis 0,2, la politique non entraînée obtient −1,250 ;
72+
- **Rejouer le checkpoint entraîné**, puis **Jouer un épisode glouton** : la politique entraînée obtient 0,850 ;
73+
- la courbe « Retour par épisode, lu dans les journaux JSON » vient des fichiers `episodes.json`, pas d'un calcul dans la page.
74+
75+
Si un journal d'entraînement manque (`episodes.json`), la page l'écrit (« Checkpoint ou journal PPO introuvable », « PPO checkpoint/log absent » en anglais). Limite observée le 19/11 : si c'est le checkpoint entraîné qui manque, la page n'affiche aucun message et reste sur le replay non entraîné.
76+
77+
## Limites observées (19/11)
78+
79+
- Sous `vite preview`, un fichier absent est remplacé par la page HTML avec un code 200 : le message d'erreur s'affiche bien, mais indique « (200) ».
80+
- Rendu vérifié dans un navigateur sur serveur (rendu logiciel) ; pas testé sur téléphone réel.
81+
- Adresse publique : après le merge et le déploiement de la PR #90 seulement.

‎packages/web/data/blog.en.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,10 @@
11
[
2+
{
3+
"slug": "ppo-avant-apres",
4+
"title": "PPO before / after: train an agent and check what it learned",
5+
"description": "A PPO policy on a tiny one-dimensional task, trained by you in a few seconds: three seeds, 80 episodes, greedy evaluation before and after, and what these numbers do not prove.",
6+
"imageAlt": "The PPO before / after demo page: seed 29, trained policy, return curve read from the logs."
7+
},
28
{
39
"slug": "space-dock-physique-pd",
410
"title": "Space Dock: docking cargo with Rapier, a reference PD controller and a trainable DQN",

‎packages/web/data/blog.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,14 @@
11
[
2+
{
3+
"environment": "target-chasing",
4+
"slug": "ppo-avant-apres",
5+
"title": "PPO avant / après : entraîner un agent et vérifier ce qu'il a appris",
6+
"description": "Une politique PPO sur une tâche minuscule à une dimension, entraînée vous-même en quelques secondes : trois graines, 80 épisodes, l'évaluation gloutonne avant et après, et ce que ces chiffres ne prouvent pas.",
7+
"date": "2026-11-19",
8+
"image": "/images/blog/target-chasing/ppo-avant-apres.png",
9+
"imageAlt": "La page de démo PPO avant / après : graine 29, politique entraînée, courbe des retours lue dans les journaux.",
10+
"example": "demo-target-chasing/ppo-experiment.json"
11+
},
212
{
313
"environment": "space-dock",
414
"slug": "space-dock-physique-pd",
193 KB
Loading

0 commit comments

Comments
 (0)