GenAI Environment Setup - CoursIA

Navigation : Index | Suivant >>

Module : 00-GenAI-Environment
Niveau : 🟢 Débutant
Technologies : OpenRouter, OpenAI, Docker, Configuration
Durée estimée : 15 minutes

🎯 Objectifs d’Apprentissage

Configurer l’environnement GenAI CoursIA complet
Valider les APIs OpenRouter et OpenAI
Tester la connectivité des services Docker (optionnel)

📚 Prérequis

Fichier .env configuré avec les clés API
Python 3.11+ avec dépendances installées
Accès réseau pour tests API

# Import guards - availability flags for external dependencies

try:
    from dotenv import load_dotenv
    DOTENV_AVAILABLE = True
except ImportError:
    DOTENV_AVAILABLE = False
    print(f'  dotenv non disponible - certaines fonctionnalites seront limitees')

try:
    import requests
    REQUESTS_AVAILABLE = True
except ImportError:
    REQUESTS_AVAILABLE = False
    print(f'  requests non disponible - certaines fonctionnalites seront limitees')


# Paramètres Papermill - JAMAIS modifier ce commentaire
# Parameters cell for MCP compatibility

# Configuration pour exécution batch/MCP
notebook_mode = "interactive"  # "interactive" ou "batch" 
api_provider = "openrouter"    # "openrouter", "openai", "local"
skip_widgets = False           # True pour mode batch MCP
debug_level = "INFO"           # "DEBUG", "INFO", "WARNING", "ERROR"
test_generation = True         # Effectuer un test de génération
validation_mode = "complete"   # "quick", "standard", "complete"

# Parameters
BATCH_MODE = "true"

Initialisation de l’environnement GenAI

Cette première section prepare l’environnement de travail pour l’ensemble des notebooks GenAI.

Chargements effectues : - Dependances Python : os, sys, pathlib, dotenv, requests, asyncio - Fichier .env : Chargement des variables d’environnement (cles API, URLs) - Helpers partages : Ajout du chemin vers les utilitaires communs - Configuration GenAI : Detection automatique du racine du module GenAI

Chemins critiques : - GENAI_ROOT : Racine du module GenAI (detecte automatiquement) - ENV_FILE : Fichier .env contenant les cles API - SHARED_PATH : Helpers partagees entre notebooks

Sortie attendue : - Confirmation du chargement de la configuration - Chemins absolus des repertoires utilises - Mode d’exécution (interactive ou batch) - Provider API selectionne (openrouter, openai, local)

Note technique : Le module autoreload permet de recharger automatiquement les modules modifiés pendant le développement.

# 🎯 OBJECTIF : Setup environnement GenAI standardisé CoursIA
# 📝 EXPLICATION : Configuration et validation complète des APIs et services
# ⚡ ACTION : Import des dépendances et chargement configuration

# Setup standardisé CoursIA GenAI
%load_ext autoreload
%autoreload 2

import os
import sys
from pathlib import Path
from dotenv import load_dotenv
from datetime import datetime
import json
import requests
import asyncio
from typing import Dict, List, Optional, Any

# Configuration paths CoursIA
GENAI_ROOT = Path.cwd() if '__file__' not in locals() else Path(__file__).parent
while GENAI_ROOT.name != 'GenAI' and len(GENAI_ROOT.parts) > 1:
    GENAI_ROOT = GENAI_ROOT.parent

ENV_FILE = GENAI_ROOT / '.env'
SHARED_PATH = GENAI_ROOT / 'shared' / 'helpers'

# Chargement environnement
config_loaded = False
if ENV_FILE.exists():
    load_dotenv(ENV_FILE)
    config_loaded = True
    print(f"✅ Configuration chargée depuis {ENV_FILE}")
else:
    print(f"⚠️  Fichier .env non trouvé : {ENV_FILE}")
    print("📖 Copiez .env.template vers .env et configurez vos clés API")

# Ajout helpers partagés
if SHARED_PATH.exists():
    sys.path.insert(0, str(SHARED_PATH.parent))
    print(f"📁 Helpers partagés ajoutés: {SHARED_PATH}")

print(f"🎨 GenAI CoursIA - Environment Setup")
print(f"📅 {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
print(f"🔧 Mode: {notebook_mode}, Provider: {api_provider}")

✅ Configuration chargée depuis D:\Dev\CoursIA\MyIA.AI.Notebooks\GenAI\.env
📁 Helpers partagés ajoutés: D:\Dev\CoursIA\MyIA.AI.Notebooks\GenAI\shared\helpers
🎨 GenAI CoursIA - Environment Setup
📅 2026-06-25 06:46:10
🔧 Mode: interactive, Provider: openrouter

Validation de l’environnement GenAI

Maintenant que l’environnement est charge, nous allons valider systematiquement tous ses composants.

Composantes a valider : 1. Fichier de configuration : Presence et validite du fichier .env 2. APIs externes : OpenRouter (requis) et OpenAI (optionnel) 3. Services Docker : Flux, SD, ComfyUI (si actives) 4. Repertoires de sortie : Creation automatique si necessaire

Fonctionnement : - La fonction validate_genai_environment() retourne un dictionnaire structure - Chaque composante est testee independamment - Les résultats sont synthetises dans un resume final - Le statut est stocke dans environment_status pour usage ulterieur

Cette approche modulaire permet d’identifier précisément quelle composante pose problème.

# 🔧 PARAMÈTRES : Validation environnement et APIs
# 📊 RÉSULTATS ATTENDUS : Status des APIs et configuration

def validate_genai_environment() -> Dict[str, Any]:
    """Validation environnement GenAI CoursIA"""
    status = {
        "config_loaded": config_loaded,
        "apis": {
            "openrouter": False,
            "openai": False
        },
        "docker_services": {
            "enabled": False,
            "flux": False,
            "sd": False,
            "comfyui": False
        },
        "environment": {
            "output_dir": None,
            "log_level": debug_level,
            "timeout": None
        }
    }
    
    # Validation APIs
    if os.getenv("OPENROUTER_API_KEY"):
        status["apis"]["openrouter"] = True
        print("✅ OpenRouter API configuré")
    else:
        print("❌ OpenRouter API manquant - Variable OPENROUTER_API_KEY")
    
    if os.getenv("OPENAI_API_KEY"):
        status["apis"]["openai"] = True
        print("✅ OpenAI API disponible")
    else:
        print("⚠️  OpenAI API manquant - Variable OPENAI_API_KEY (optionnel)")
    
    # Configuration Docker
    docker_enabled = os.getenv("DOCKER_ENABLED", "false").lower() == "true"
    status["docker_services"]["enabled"] = docker_enabled
    
    if docker_enabled:
        print("🐳 Docker activé - Test des services locaux...")
        # Test services Docker (sans bloquer)
        docker_services = {
            "flux": os.getenv("FLUX_API_URL", "http://localhost:8189"),
            "sd": os.getenv("SD_API_URL", "http://localhost:8190"),
            "comfyui": os.getenv("COMFYUI_API_URL", "http://localhost:8188")
        }
        
        for service, url in docker_services.items():
            try:
                response = requests.get(f"{url}/health", timeout=5)
                if response.status_code == 200:
                    status["docker_services"][service] = True
                    print(f"✅ Service {service}: {url}")
                else:
                    print(f"⚠️  Service {service}: Status {response.status_code}")
            except:
                print(f"❌ Service {service}: Non accessible ({url})")
    else:
        print("📱 Mode cloud uniquement (Docker désactivé)")
    
    # Configuration environnement
    status["environment"]["output_dir"] = os.getenv("GENAI_OUTPUT_DIR", "outputs/generated")
    status["environment"]["timeout"] = int(os.getenv("GENAI_TIMEOUT_SECONDS", "300"))
    
    # Création répertoire de sortie
    output_dir = Path(status["environment"]["output_dir"])
    output_dir.mkdir(parents=True, exist_ok=True)
    print(f"📁 Répertoire de sortie: {output_dir}")
    
    return status

# Validation automatique
environment_status = validate_genai_environment()

# Affichage résumé
apis_available = sum(environment_status["apis"].values())
docker_services = sum(environment_status["docker_services"].values()) - (1 if environment_status["docker_services"]["enabled"] else 0)

print(f"\n📊 RÉSUMÉ VALIDATION")
print(f"APIs disponibles: {apis_available}/2")
print(f"Services Docker: {docker_services}/3 ({'activé' if environment_status['docker_services']['enabled'] else 'désactivé'})")
print(f"Configuration: {'✅ Complète' if config_loaded and apis_available > 0 else '⚠️  Partielle'}")

✅ OpenRouter API configuré
✅ OpenAI API disponible
📱 Mode cloud uniquement (Docker désactivé)
📁 Répertoire de sortie: outputs\generated

📊 RÉSUMÉ VALIDATION
APIs disponibles: 2/2
Services Docker: 0/3 (désactivé)
Configuration: ✅ Complète

Analyse de la validation environnement

La fonction validate_genai_environment() a verifie les trois composantes de l’environnement GenAI.

Composantes verifiees :

Composante	Status verifie	Action corrective si erreur
Fichier .env	`config_loaded`	Créer le fichier depuis .env.example
OpenRouter API	`environment_status["apis"]["openrouter"]`	Ajouter OPENROUTER_API_KEY dans .env
OpenAI API	`environment_status["apis"]["openai"]`	Ajouter OPENAI_API_KEY dans .env (optionnel)
Docker	`environment_status["docker_services"]["enabled"]`	Demarrer Docker ou desactiver DOCKER_ENABLED

Variables exportees : - environment_status : Dictionnaire complet du statut - apis_available : Nombre d’APIs configurees (0-2) - docker_services : Nombre de services Docker actifs (0-3)

Note technique : Les services Docker sont testes uniquement si DOCKER_ENABLED=true dans le fichier .env. Par defaut, le mode cloud est utilise.

Test de generation d’image - Validation fonctionnelle

Après avoir verifie la configuration statique, nous allons tester la capacite reelle de l’API a generer du contenu.

Principe du test : - Envoyer une requête de generation d’image simple a l’API OpenAI (Direct) - Verifier que la requête aboutit (status HTTP 200) - Recuperer l’image generee, encodee en base64 (b64_json)

Pourquoi OpenAI Direct et non OpenRouter ? OpenRouter est un routeur de chat-completion : il n’expose pas d’endpoint /images/generations (un appel image renvoie 404). La generation d’images se valide donc via l’API OpenAI directe avec gpt-image-1 (le modèle image actuel d’OpenAI ; dall-e-3 est retire). Contrairement a dall-e-3, gpt-image-1 retourne l’image encodee en base64 (b64_json), pas une URL.

Attention : Ce test consomme des credits API (~$0.01 pour gpt-image-1 en qualite low). Pour des tests repetitifs sans cout, vous pouvez desactiver le test avec test_generation=False dans les paramètres Papermill.

Modèle utilise : gpt-image-1 via OpenAI Direct
Prompt : “A simple test image: colorful abstract shapes”
Resolution : 1024x1024 pixels
Qualite : low (cout minimal pour un smoke test de validation)

# 💡 ASTUCE : Test de génération simple pour validation fonctionnelle
# ⚠️  ATTENTION : Ce test utilise des crédits API (minimal)

async def test_image_generation():
    """Test de génération d'image pour validation"""
    
    if not test_generation:
        print("⏭️  Test de génération désactivé (test_generation=False)")
        return None
        
    if not any(environment_status["apis"].values()):
        print("❌ Aucune API disponible pour le test")
        return None
    
    print("🧪 Test génération d'image...")
    
    # OpenRouter = chat-completion uniquement (pas d'endpoint /images/generations ;
    # un appel image via OpenRouter renvoie 404). On valide donc la generation d'image
    # via OpenAI direct avec gpt-image-1 (le modele image actuel d'OpenAI ; dall-e-3 est
    # retire). gpt-image-1 retourne l'image en base64 (b64_json), pas une URL.
    if environment_status["apis"]["openai"]:
        try:
            headers = {
                'Authorization': f'Bearer {os.getenv("OPENAI_API_KEY")}',
                'Content-Type': 'application/json'
            }

            # gpt-image-1, qualite "low" = cout minimal pour un smoke test de validation
            payload = {
                'model': 'gpt-image-1',
                'prompt': 'A simple test image: colorful abstract shapes',
                'size': '1024x1024',
                'quality': 'low',
                'n': 1
            }

            print("📡 Appel API OpenAI (gpt-image-1)...")
            response = requests.post(
                'https://api.openai.com/v1/images/generations',
                headers=headers,
                json=payload,
                timeout=60
            )

            if response.status_code == 200:
                result = response.json()
                print("✅ Test génération réussi !")
                print(f"🎨 Modèle: {payload['model']}")
                print(f"📝 Prompt: {payload['prompt']}")

                if 'data' in result and len(result['data']) > 0:
                    # gpt-image-1 retourne b64_json (pas d'URL comme dall-e-3)
                    _b64 = result['data'][0].get('b64_json')
                    _url = result['data'][0].get('url')
                    if _b64:
                        print(f"🖼️  Image générée: base64 ({len(_b64)} chars)")
                        return {
                            'success': True,
                            'provider': 'openai',
                            'model': payload['model'],
                            'image_url': f"data:image/png;base64,{_b64[:60]}... (b64)"
                        }
                    elif _url:
                        print(f"🖼️  Image générée: {_url[:50]}...")
                        return {
                            'success': True,
                            'provider': 'openai',
                            'model': payload['model'],
                            'image_url': _url
                        }

                return {'success': True, 'provider': 'openai'}
            else:
                print(f"⚠️  Erreur API: {response.status_code}")
                print(f"Response: {response.text[:200]}...")

        except Exception as e:
            print(f"❌ Erreur test OpenAI: {str(e)[:100]}...")
    elif environment_status["apis"]["openrouter"]:
        print("ℹ️  OpenRouter configuré (chat-completion uniquement, pas de génération d'images)")
    
    print("✅ Validation APIs complétée (génération non testée)")
    return {'success': False, 'reason': 'api_available_but_generation_failed'}

# Exécution test si configuré
if validation_mode in ["standard", "complete"]:
    test_result = await test_image_generation()
else:
    print("⏭️  Test génération sauté (validation_mode='quick')")
    test_result = None

🧪 Test génération d'image...
📡 Appel API OpenAI (gpt-image-1)...
✅ Test génération réussi !
🎨 Modèle: gpt-image-1
📝 Prompt: A simple test image: colorful abstract shapes
🖼️  Image générée: base64 (1547260 chars)

Interpretation du test de generation

Le test de generation d’image a verifie la capacite de l’API a traiter une requête complete end-to-end.

Résultat attendu : - Si test_result['success'] est True : L’API fonctionne correctement - Si test_result['success'] est False : Consultez le message d’erreur affiche ci-dessus

Aspect	Details
API testee	OpenAI Direct (gpt-image-1)
Prompt	“A simple test image: colorful abstract shapes”
Resolution	1024x1024 pixels
Qualite	low (cout minimal)
Format retour	base64 (b64_json)
Cout estime	~$0.01 par generation

Note technique : Ce test consomme des credits API. Pour des tests repetitifs sans cout, desactivez le test avec test_generation=False dans les paramètres Papermill. Si seule l’API OpenRouter est configuree, la generation d’images est signalee comme non testee (OpenRouter = chat-completion uniquement).

Rapport de configuration et score de sante

Cette section finale genere un rapport synthetique de l’etat de votre environnement GenAI.

Objectifs du rapport : - Calculer un score de sante global (0-100) basé sur 4 critères - Generer des recommandations personnalisees selon les manques detectes - Sauvegarder le rapport pour reference future - Exporter les variables pour les notebooks suivants

Barème du score de sante : - Configuration .env chargee : +25 points - Au moins une API disponible : +50 points - Services Docker actifs : +15 points - Test de generation reussi : +10 points

Le rapport est sauvegarde dans le repertoire outputs/generated/ avec un timestamp unique.

# 📋 RAPPORT FINAL : Configuration et recommandations

# Génération rapport complet
setup_report = {
    "timestamp": datetime.now().isoformat(),
    "notebook_info": {
        "module": "00-GenAI-Environment",
        "notebook": "00-1-Environment-Setup",
        "mode": notebook_mode,
        "provider": api_provider
    },
    "environment_status": environment_status,
    "test_result": test_result,
    "validation_level": validation_mode,
    "recommendations": []
}

# Génération recommandations
if not config_loaded:
    setup_report["recommendations"].append("Configurer le fichier .env avec les clés API")

if not any(environment_status["apis"].values()):
    setup_report["recommendations"].append("Ajouter au moins une clé API (OpenRouter recommandé)")

if environment_status["docker_services"]["enabled"] and docker_services == 0:
    setup_report["recommendations"].append("Démarrer les services Docker ou désactiver DOCKER_ENABLED")

if test_result and not test_result.get('success'):
    setup_report["recommendations"].append("Vérifier la validité des clés API et les quotas")

# Calcul score de santé
health_score = 0
if config_loaded: health_score += 25
if any(environment_status["apis"].values()): health_score += 50
if docker_services > 0: health_score += 15
if test_result and test_result.get('success'): health_score += 10

setup_report["health_score"] = health_score

# Affichage rapport
print("\n" + "="*50)
print("📋 RAPPORT CONFIGURATION GENAI COURSIA")
print("="*50)

print(f"🏥 Score de santé: {health_score}/100")
print(f"⚙️  Configuration: {'✅ Chargée' if config_loaded else '❌ Manquante'}")
print(f"🌐 APIs disponibles: {apis_available}/2")
print(f"🐳 Services Docker: {docker_services}/3")

if test_result:
    if test_result.get('success'):
        print(f"✅ Test génération: Réussi ({test_result.get('provider', 'N/A')})")
    else:
        print(f"⚠️  Test génération: Échoué")

# Recommandations
if setup_report["recommendations"]:
    print("\n💡 RECOMMANDATIONS:")
    for i, rec in enumerate(setup_report["recommendations"], 1):
        print(f"{i}. {rec}")

# Status final
if health_score >= 75:
    status_final = "🎉 Environnement optimal - Tous les modules GenAI disponibles"
elif health_score >= 50:
    status_final = "✅ Environnement fonctionnel - Quelques optimisations possibles"
elif health_score >= 25:
    status_final = "⚠️  Environnement partiel - Configuration à compléter"
else:
    status_final = "❌ Environnement non configuré - Voir recommandations"

print(f"\n{status_final}")

# Sauvegarde rapport
report_path = Path(environment_status["environment"]["output_dir"]) / f"environment_setup_report_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
report_path.parent.mkdir(parents=True, exist_ok=True)

with open(report_path, 'w', encoding='utf-8') as f:
    json.dump(setup_report, f, indent=2, ensure_ascii=False, default=str)

print(f"\n💾 Rapport sauvegardé: {report_path}")
print("\n🚀 Environnement GenAI CoursIA prêt !")

# Export pour les autres notebooks
GENAI_ENVIRONMENT_STATUS = environment_status
GENAI_HEALTH_SCORE = health_score


==================================================
📋 RAPPORT CONFIGURATION GENAI COURSIA
==================================================
🏥 Score de santé: 85/100
⚙️  Configuration: ✅ Chargée
🌐 APIs disponibles: 2/2
🐳 Services Docker: 0/3
✅ Test génération: Réussi (openai)

🎉 Environnement optimal - Tous les modules GenAI disponibles

💾 Rapport sauvegardé: outputs\generated\environment_setup_report_20260625_064625.json

🚀 Environnement GenAI CoursIA prêt !

Conclusion du Notebook

Résumé des apprentissages

Ce notebook vous a permis de : 1. Configurer l’environnement GenAI avec le fichier .env 2. Valider les connexions API (OpenRouter, OpenAI) 3. Tester les services Docker optionnels 4. Générer un rapport de santé de l’environnement

Prochaines étapes

Si le score de santé est >= 75 : Passez au notebook 00-2-Docker-Services-Management
Si le score est entre 50-74 : Vérifiez les APIs manquantes dans votre fichier .env
Si le score est < 50 : Complétez la configuration en suivant les recommandations affichées ci-dessus

Note technique : Les variables GENAI_ENVIRONMENT_STATUS et GENAI_HEALTH_SCORE sont exportées pour usage dans les notebooks suivants. Vous pouvez les utiliser avec GENAI_ENVIRONMENT_STATUS["apis"]["openrouter"] par exemple.

Retour au sommet