tika/trader-ml
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 4c-bis/4d : CNN Image vectorisé + Agent RL PPO + HMM persistence + scripts

Browse Source 
CNN Image (Phase 4c-bis) :
- chart_renderer.py : renderer numpy vectorisé (boucle 64 bougies, pas 12 000 fenêtres)
  → 1 068 img/s, GIL libéré entre itérations, API réactive pendant l'entraînement
- cnn_image_strategy_model.py : torch.set_num_threads(4) pour préserver l'event loop
- trading.py : asyncio.create_task() au lieu de background_tasks → hot-reloads non-bloquants

Agent RL PPO (Phase 4d) :
- src/ml/rl/ : TradingEnv (gymnasium), PPOModel (Actor-Critic MLP, GAE), RLStrategyModel
- src/strategies/rl_driven/ : RLDrivenStrategy (interface BaseStrategy complète)
- Routes API : POST /train-rl, GET /train-rl/{job_id}, GET /rl-models
- docs/RL_STRATEGY_GUIDE.md : documentation complète

HMM Persistence :
- regime_detector.py : save()/load()/needs_retrain()/is_trained (joblib + JSON meta)
- trading.py /ml/status : charge depuis disque si < 24h, re-entraîne + sauvegarde sinon
  → premier appel ~2s, appels suivants < 100ms

Scripts utilitaires :
- scripts/compare_strategies.py : backtest comparatif toutes stratégies (tabulate/JSON)
- scripts/quick_benchmark.py : comparaison wf_accuracy/precision des modèles ML sauvegardés
- reports/ : répertoire pour les rapports JSON générés

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tika
2026-03-10 22:40:52 +00:00
parent 80e1308a1e
commit ff8d58e1aa
13 changed files with 3873 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

236
docs/RL_STRATEGY_GUIDE.md Normal file
View File

@@ -0,0 +1,236 @@
# RL Strategy Guide — Phase 4d (Reinforcement Learning)
## Vue d'ensemble
La Phase 4d introduit une stratégie pilotée par un agent de **Reinforcement Learning (RL)**
basé sur l'algorithme **PPO** (Proximal Policy Optimization). Contrairement aux stratégies
supervisées (XGBoost, CNN) qui s'entraînent sur des labels pré-calculés, l'agent RL apprend
directement par interaction avec un environnement de trading simulé (`TradingEnv`), sans avoir
besoin d'annotations explicites LONG/SHORT/NEUTRAL.
---
## Architecture
### Composants (implémentés par l'agent ml/rl/)
```
src/ml/rl/
├── trading_env.py # TradingEnv (Gymnasium) — environnement de simulation
├── ppo_model.py # PPOModel — réseau Actor-Critic (MLP)
└── rl_strategy_model.py # RLStrategyModel — interface train/predict/save/load
```
### Composants (cette phase)
```
src/strategies/rl_driven/
├── __init__.py # Export RLDrivenStrategy
└── rl_strategy.py # RLDrivenStrategy (hérite BaseStrategy)
```
### Pipeline d'entraînement PPO
```
Données OHLCV
│
▼
TradingEnv (Gymnasium)
├── Observation space : fenêtre glissante seq_len=20 barres (OHLCV normalisé)
├── Action space : {0=HOLD/NEUTRAL, 1=LONG, 2=SHORT}
└── Reward : P&L réalisé − pénalité drawdown − pénalité over-trading
│
▼
PPO Actor-Critic (MLP)
├── Actor : policy π(a|s) → distribution sur les actions
└── Critic : value function V(s) → estimation de la récompense future
│
▼
Optimisation sur total_timesteps pas
│
▼
RLStrategyModel.save()
├── models/rl_strategy/EURUSD_1h.zip (politique PPO)
└── models/rl_strategy/EURUSD_1h_meta.json
```
### Architecture Actor-Critic
L'agent PPO utilise un réseau MLP (Multi-Layer Perceptron) à deux têtes :
- **Actor** : prédit la distribution de probabilité sur les 3 actions (LONG/SHORT/NEUTRAL).
La confiance du signal correspond à `max(probas)`.
- **Critic** : estime la valeur d'état V(s) pour calculer l'avantage (advantage) utilisé
lors de la mise à jour de la politique.
Hyperparamètres PPO typiques :
| Paramètre | Valeur par défaut | Description |
|---------------|-------------------|----------------------------------------------|
| `gamma` | 0.99 | Facteur d'actualisation des récompenses |
| `clip_range` | 0.2 | Clipping ratio PPO (stabilité) |
| `n_steps` | 2048 | Nombre de pas par rollout |
| `batch_size` | 64 | Taille des mini-batches SGD |
| `n_epochs` | 10 | Passes sur chaque rollout |
| `ent_coef` | 0.01 | Coefficient d'entropie (exploration) |
---
## Lancer l'entraînement
### Via curl
```bash
# Lancer l'entraînement (tâche de fond)
curl -X POST http://localhost:8100/trading/train-rl \
-H "Content-Type: application/json" \
-d '{
"symbol": "EURUSD",
"timeframe": "1h",
"period": "2y",
"total_timesteps": 50000
}'
# Réponse
{
"job_id": "a1b2c3d4-...",
"status": "pending",
"symbol": "EURUSD",
"timeframe": "1h"
}
```
```bash
# Suivre l'avancement
curl http://localhost:8100/trading/train-rl/a1b2c3d4-...
# Réponse quand terminé
{
"job_id": "a1b2c3d4-...",
"status": "completed",
"symbol": "EURUSD",
"timeframe": "1h",
"avg_reward": 0.042,
"sharpe_env": 1.23,
"total_timesteps": 50000,
"trained_at": "2026-03-10T14:32:00"
}
```
```bash
# Lister les modèles disponibles
curl http://localhost:8100/trading/rl-models
# Réponse
{
"models": [
{
"symbol": "EURUSD",
"timeframe": "1h",
"avg_reward": 0.042,
"sharpe_env": 1.23,
"total_timesteps": 50000,
"trained_at": "2026-03-10T14:32:00"
}
],
"count": 1
}
```
### Paramètres de la requête
| Champ | Type | Défaut | Description |
|-------------------|-------|----------|---------------------------------------------------------|
| `symbol` | str | EURUSD | Paire de trading (ex: EURUSD, BTCUSDT) |
| `timeframe` | str | 1h | Timeframe (1m, 5m, 15m, 1h, 4h, 1d) |
| `period` | str | 2y | Historique d'entraînement (ex: 6m, 1y, 2y) |
| `total_timesteps` | int | 50000 | Nombre total de pas de simulation PPO |
**Recommandations `total_timesteps` :**
- 20 000 : entraînement rapide (test, ~5 min CPU)
- 50 000 : entraînement standard (défaut, ~15 min CPU)
- 200 000 : entraînement long, meilleure convergence (~1h CPU)
- 1 000 000 : entraînement poussé si GPU disponible
---
## Interpréter les métriques
### `avg_reward`
Récompense moyenne par pas de simulation sur les derniers rollouts d'évaluation.
- **< 0** : l'agent perd de l'argent en simulation → entraîner plus longtemps ou revoir la fonction de récompense
- **0 à 0.02** : agent neutre, légèrement profitable
- **> 0.05** : bon signal → tester en backtest réel
- **> 0.1** : excellent (attention au sur-apprentissage, vérifier out-of-sample)
### `sharpe_env`
Ratio de Sharpe calculé sur les épisodes de simulation (récompenses / écart-type des récompenses).
- **< 0.5** : insuffisant pour paper trading
- **0.5 – 1.0** : acceptable, à valider en backtest
- **> 1.5** : cible pour activation paper trading (conforme aux seuils du projet)
### Interprétation combinée
| `avg_reward` | `sharpe_env` | Interprétation |
|--------------|--------------|--------------------------------------------------------|
| négatif | quelconque | Agent non convergé — relancer avec plus de timesteps |
| 0 – 0.02 | < 1.0 | Apprentissage partiel — augmenter total_timesteps |
| > 0.03 | > 1.0 | Bon candidat — valider via POST /trading/backtest |
| > 0.05 | > 1.5 | Prêt pour paper trading (30 jours minimum) |
---
## Intégration avec le paper trading
Après l'entraînement, si un paper trading avec la stratégie `rl_driven` est actif,
le modèle est **automatiquement attaché** sans redémarrage.
Pour démarrer un paper trading RL :
```bash
curl -X POST http://localhost:8100/trading/paper/start \
-H "Content-Type: application/json" \
-d '{"strategy": "rl_driven", "symbol": "EURUSD"}'
```
La stratégie `RLDrivenStrategy` :
1. Charge le dernier modèle entraîné pour le symbole/timeframe
2. À chaque barre, fournit les 20 dernières bougies à l'agent (`seq_len=20`)
3. Si la confiance de l'agent >= `min_confidence` (défaut: 0.55), émet un signal
4. SL = `sl_atr_mult × ATR` (défaut: 1×ATR), TP = `tp_atr_mult × ATR` (défaut: 2×ATR)
---
## Notes techniques
### Threads PyTorch
L'entraînement fixe `torch.set_num_threads(4)` pour éviter la contention CPU dans
le container Docker. Adapter dans `docker-compose.yml` si le container dispose de plus de cœurs.
### Sauvegarde des modèles
Les modèles sont sauvegardés dans `models/rl_strategy/` (volume Docker monté) :
- `EURUSD_1h.zip` : politique PPO (format stable-baselines3)
- `EURUSD_1h_meta.json` : métadonnées (métriques, hyperparamètres, date)
### Import conditionnel
Le flag `RL_AVAILABLE` est `False` si PyTorch ou stable-baselines3 ne sont pas
installés. La stratégie dégrade gracieusement (aucun signal, aucune exception).
Pour activer : ajouter `stable-baselines3` et `gymnasium` dans `docker/requirements/api.txt`
puis reconstruire le container (`docker compose build --no-cache trading-api`).
---
## Seuils de validation (conforme au projet)
Avant activation du live trading, la stratégie RL doit satisfaire :
| Métrique | Seuil minimum |
|-----------------|---------------|
| Sharpe Ratio | ≥ 1.5 |
| Max Drawdown | ≤ 10% |
| Win Rate | ≥ 55% |
| Paper Trading | ≥ 30 jours |
Ces seuils s'appliquent au **backtest out-of-sample** et au **paper trading**, pas
aux métriques de simulation RL (`sharpe_env`) qui sont indicatives uniquement.