From df78dcc7551217ed8bd2ec9a89aca460830d8575 Mon Sep 17 00:00:00 2001 From: Antoine Van Elstraete Date: Tue, 8 Sep 2026 19:43:01 +0200 Subject: [PATCH] =?UTF-8?q?Recr=C3=A9er=20Guide-IA=20avec=20corrections=20?= =?UTF-8?q?HTTP=20et=20bon=20sub=5Furl?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Guide-IA.-.md | 156 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 156 insertions(+) create mode 100644 Guide-IA.-.md diff --git a/Guide-IA.-.md b/Guide-IA.-.md new file mode 100644 index 0000000..16c3cad --- /dev/null +++ b/Guide-IA.-.md @@ -0,0 +1,156 @@ +# Guide-IA + +## Introduction +L'IA dans **pronote-sync** permet de générer des **synthèses automatiques** à partir des données récupérées depuis Pronote (cours, devoirs, notes, etc.). Cette fonctionnalité est **optionnelle** et **désactivée par défaut** (`AI_ENABLED=false`). Elle n'est pas requise pour la synchronisation CalDAV ou XMPP. + +Pour une référence complète des variables de configuration, consultez le [tableau des variables dans la page Configuration](Configuration). + +--- + +## Fournisseurs supportés +Le projet supporte trois types de fournisseurs IA : + +- **`openai`** : API officielle d'OpenAI. +- **`litellm`** : Proxy LiteLLM, qui permet d'unifier plusieurs fournisseurs derrière une seule API compatible OpenAI. +- **`openai-compatible`** : Toute API compatible OpenAI (OpenRouter, Ollama, vLLM, etc.) avec une URL de base personnalisée. + +--- + +## OpenAI + +### Obtenir une clé API +1. Rendez-vous sur [platform.openai.com](https://platform.openai.com). +2. Connectez-vous ou créez un compte. +3. Allez dans **Dashboard** → **API keys**. +4. Cliquez sur **Create new secret key**. +5. Copiez la clé générée (elle commence par `sk-...`). + +### Configuration +- **URL de base** : `https://api.openai.com/v1` +- **Modèles recommandés** : `gpt-4o`, `gpt-4o-mini`, `o3-mini`, etc. + +### Exemple de configuration +```ini +AI_ENABLED=true +AI_PROVIDER=openai +AI_API_KEY=sk-votre-cle-api +AI_MODEL=gpt-4o-mini +``` + +--- + +## OpenRouter + +OpenRouter est un service qui agrège plusieurs fournisseurs IA (OpenAI, Anthropic, DeepSeek, Meta, etc.) sous une seule API compatible OpenAI. + +### Obtenir une clé API +1. Rendez-vous sur [openrouter.ai/keys](https://openrouter.ai/keys). +2. Connectez-vous ou créez un compte. +3. Cliquez sur **Create Key**. +4. Copiez la clé générée. + +### Configuration +- **Fournisseur** : `openai-compatible` +- **URL de base** : `https://openrouter.ai/api/v1` +- **Modèles** : Format `fournisseur/modele`, par exemple : + - `openai/gpt-4o` + - `anthropic/claude-3.5-sonnet` + - `deepseek/deepseek-chat` + - `meta-llama/llama-3.3-70b-instruct` + +### Exemple de configuration +```ini +AI_ENABLED=true +AI_PROVIDER=openai-compatible +AI_BASE_URL=https://openrouter.ai/api/v1 +AI_API_KEY=votre-cle-openrouter +AI_MODEL=openai/gpt-4o-mini +AI_ALLOW_INSECURE_HTTP=false +``` + +--- + +## Ollama (local) + +Ollama permet d'exécuter des modèles IA localement. **pronote-sync** peut s'y connecter via l'endpoint de compatibilité OpenAI. + +### Prérequis +- Ollama installé et fonctionnel sur votre machine. +- Un modèle téléchargé (ex. `llama3.2`, `mistral`, `qwen2.5`). + +### Configuration +- **URL de base** : `http://127.0.0.1:11434/v1` (endpoint de compatibilité OpenAI d'Ollama). +- **Clé API** : Ollama n'exige pas de clé API, mais la configuration attend une valeur non vide. Utilisez une valeur arbitraire comme `local-not-required`. +- **Modèles** : Utilisez le nom du modèle téléchargé (ex. `llama3.2`). + +### Lister les modèles disponibles +```bash +ollama list +``` + +### Exemple de configuration +```ini +AI_ENABLED=true +AI_PROVIDER=openai-compatible +AI_BASE_URL=http://127.0.0.1:11434/v1 +AI_API_KEY=local-not-required +AI_MODEL=llama3.2 +AI_ALLOW_INSECURE_HTTP=true +``` + +--- + +## LiteLLM (proxy) + +[LiteLLM](https://litellm.ai/) est un proxy open-source qui expose une API unifiée compatible OpenAI pour plusieurs fournisseurs (OpenAI, Anthropic, Azure, etc.). + +### Configuration +- **Fournisseur** : `litellm` +- **URL de base** : Par défaut, `http://localhost:4000/v1` (si LiteLLM est exécuté localement). +- **Clé API** : Configurez une clé maîtresse dans le `config.yaml` de LiteLLM ou utilisez celle générée au démarrage. + +### Exemple de configuration +```ini +AI_ENABLED=true +AI_PROVIDER=litellm +AI_BASE_URL=http://localhost:4000/v1 +AI_API_KEY=sk-litellm-master-key +AI_MODEL=gpt-4o-mini +``` + +--- + +## Sécurité + +### HTTPS obligatoire par défaut +- Par défaut, seules les URL en **HTTPS** sont acceptées pour `AI_BASE_URL`. Les URL en HTTP sont rejetées. + +### Autoriser HTTP avec `AI_ALLOW_INSECURE_HTTP` +- Lorsque `AI_ALLOW_INSECURE_HTTP=true`, les URL en **HTTP sont acceptées pour n'importe quel hôte** (pas seulement localhost). +- ⚠️ **Avertissement** : Cette option désactive la protection HTTPS pour toutes les URL du provider `openai-compatible`. Ne l'utilisez que pour des connexions locales (ex. Ollama sur `127.0.0.1`) ou dans un environnement de confiance. En production, utilisez toujours HTTPS. +- Exemple : `http://127.0.0.1:11434/v1` (Ollama local). + +### Clé API +- **Jamais dans l'URL** : Les credentials dans l'URL (ex. `user:pass@host`) sont **rejetés**. +- **Pas de paramètres sensibles dans la query string** : Les paramètres comme `?token` ou `?api_key=...` sont **rejetés**, même sans valeur. +- **Stockage sécurisé** : `AI_API_KEY` est stockée en `SecretStr` et masquée dans les logs. + +### URL complète requise +- **Aucune manipulation automatique de `/v1`** : L'URL doit être **complète et correcte**. Par exemple, `https://openrouter.ai/api/v1` est valide, mais `https://openrouter.ai/api` ne le sera pas. + +### Mode dégradé +- Si la configuration est **invalide** (URL malformée, clé manquante, etc.), la factory retourne `None` avec un **avertissement** (mode dégradé). Le pipeline fonctionne alors **sans IA**. + +--- + +## Mode dégradé à l'exécution + +Si l'IA échoue **pendant l'exécution** (erreur réseau, clé invalide, quota dépassé, etc.) : +- Le pipeline retourne un message **sans synthèse**. +- La synchronisation **CalDAV/XMPP reste fonctionnelle** et n'est pas affectée. + +--- + +## Liens utiles +→ [Configuration](Configuration) — Tableau complet des variables IA. +→ [Sécurité](Sécurité) — Bonnes pratiques pour la gestion des secrets. \ No newline at end of file