AntoineVe/college-infos
1
0
Fork 0
Code Issues 13 Pull Requests 1 Actions Packages Projects Releases 2 Wiki Activity
Page: GuideIA
Pages
Architecture Configuration Déploiement GuideAgendaTheorique GuideAgendaVacancesScolaires GuideBlog GuideCalDAV GuideIA GuidePronote GuideXMPP Home Sécurité
Clone
3
GuideIA
Antoine Van Elstraete edited this page 2026-09-08 19:44:48 +02:00
Table of Contents

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.

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.
  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

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.
  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

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

ollama list

Exemple de configuration

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 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

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 — Tableau complet des variables IA. → Sécurité — Bonnes pratiques pour la gestion des secrets.

Documentation