diff --git a/README.MD b/README.MD index fdbf375..e2f11da 100644 --- a/README.MD +++ b/README.MD @@ -1,226 +1,235 @@ -# Système de Recommandation de Contenu - My Content - -Projet de développement d'un système de recommandation d'articles basé sur une architecture serverless Azure Functions avec interface utilisateur Streamlit. - - -## Livrables du Projet -1. **Application fonctionnelle** : Streamlit + Azure Functions déployée -2. **Code source versionné** : Repository GitHub complet -3. **Présentation technique** : Support PDF (docs/presentation.pdf) - - -## Vue d'ensemble - -Ce projet implémente un système de recommandation de contenu utilisant des algorithmes de filtrage collaboratif et basé sur le contenu. L'architecture serverless permet une mise à l'échelle automatique et un coût optimisé. - -### Fonctionnalités principales - -- **API de recommandation** : Azure Function retournant le top 5 des articles recommandés pour un utilisateur -- **Interface utilisateur** : Application Streamlit pour tester et démontrer le système -- **Algorithmes implémentés** : Content-Based Filtering avec embeddings pré-calculés -- **Architecture serverless** : Déploiement sur Azure Functions avec plan Consumption - - -## Analyse et Développement - -### Notebook Jupyter -- **Exploration des données** : Analyse du dataset Kaggle Globo.com -- **Implémentation des algorithmes** : Content-Based et Collaborative Filtering -- **Comparaison des approches** : Évaluation et choix technique -- **Optimisation ACP** : Réduction dimensionnelle 250D → 50D - -Localisation : `notebook/p10_notebook.ipynb` - -## Architecture - -### MVP Actuel -``` -[Interface Streamlit] → [Azure Functions API] → [Algorithme de recommandation] - ↓ - [Données embeddings + historique utilisateur] -``` - -### Composants -- **Frontend** : Streamlit (interface de test) -- **Backend** : Azure Functions (Python 3.12, Linux) -- **Algorithme** : Content-Based Filtering avec similarité cosinus -- **Données** : Embeddings articles (50D via PCA vs 250D embeddings originaux) + historique des clics - -## Structure synthétique du Projet - -``` -Project_10/ -├── azure-app/ # Azure Function -│ ├── function_app.py # Point d'entrée Azure Function -│ ├── requirements.txt # Dépendances Python -│ ├── host.json # Configuration Azure Functions -│ ├── local.settings.json # Configuration locale (non versionnée) -│ ├── data/ -│ │ ├── embeddings_azure_50d.pkl # Embeddings articles (PCA 50D) -│ │ └── clicks_sample.csv # Historique des clics utilisateurs -│ └── utils/ -│ ├── data_loader.py # Chargement et cache des données -│ └── content_based.py # Algorithme de recommandation -├── notebook/ -│ └── p10_notebook.ipynb # Analyse données + développement modèles -├── docs/ -│ ├── presentation.pdf # Support de présentation (15-25 slides) -│ └── illustrations/ # Schémas d'architecture et captures -├── streamlit_app.py # Interface utilisateur -├── streamlit_requirements.txt # Dépendances Streamlit -└── README.md -``` - -## Installation et Déploiement - -### Prérequis -- Python 3.12+ -- Azure CLI -- Azure Functions Core Tools -- Compte Azure - -### Déploiement Azure Functions - -1. **Connexion à Azure** -```bash -az login -``` - -2. **Création de l'infrastructure** -```bash -# Groupe de ressources -az group create --name rg-content-recommender --location francecentral - -# Compte de stockage -az storage account create --name [votre-nom-stockage-unique] \ - --resource-group rg-content-recommender \ - --location francecentral \ - --sku Standard_LRS - -# Function App Linux avec Python 3.12 -az functionapp create \ - --resource-group rg-content-recommender \ - --consumption-plan-location francecentral \ - --runtime python \ - --runtime-version 3.12 \ - --functions-version 4 \ - --name contentrecommender-linux \ - --storage-account stcontentrecommend2025 \ - --os-type Linux -``` - -3. **Déploiement du code** -```bash -# Depuis le dossier azure-app -func azure functionapp publish contentrecommender-linux -``` - -### Interface Streamlit - -1. **Installation des dépendances** -```bash -pip install -r streamlit_requirements.txt -``` - -2. **Lancement de l'interface** -```bash -streamlit run streamlit_app.py -``` - -## Utilisation - -### API Azure Functions - -**Endpoint** : `https://contentrecommender-linux.azurewebsites.net/api/recommend` - -**Paramètres** : -- `user_id` (int) : Identifiant de l'utilisateur (0-706) - -**Exemple d'appel** : -```bash -curl "https://contentrecommender-linux.azurewebsites.net/api/recommend?user_id=0" -``` - -**Réponse** : -```json -{ - "user_id": 0, - "recommendations": [157519, 157944, 159495, 156690, 162857] -} -``` - -### Interface Streamlit - -1. Configurer l'URL de l'API (local ou Azure) -2. Sélectionner un ID utilisateur -3. Obtenir les recommandations -4. Tester les fonctionnalités avancées - -## Algorithme de Recommandation - -### Content-Based Filtering - -1. **Chargement des données** : Embeddings pré-calculés et historique utilisateur -2. **Calcul du profil utilisateur** : Moyenne des embeddings des articles consultés -3. **Similarité cosinus** : Calcul avec tous les articles du catalogue -4. **Filtrage** : Exclusion des articles déjà vus -5. **Sélection** : Top 5 des articles les plus similaires - -### Optimisations - -- **Réduction dimensionnelle** : PCA 250D → 50D pour optimiser les performances Azure -- **Cache en mémoire** : Embeddings et données utilisateur chargés une seule fois -- **Architecture serverless** : Mise à l'échelle automatique selon la demande - -## Tests et Validation - -### Tests locaux -```bash -# Démarrage Azure Functions local -func start - -# Test de l'algorithme -python test_local.py -``` - -### Métriques de performance -- **Temps de réponse** : ~200ms par recommandation -- **Utilisateurs supportés** : 707 dans le dataset actuel -- **Articles disponibles** : 364,047 avec embeddings - -## Problèmes Connus et Solutions - -### Déploiement Azure -- **Python sur Windows** : Non supporté, utiliser Linux obligatoirement -- **Authentification** : Configurer `http_auth_level=func.AuthLevel.ANONYMOUS` -- **Erreurs "Service unavailable"** : Problèmes temporaires Azure, réessayer plus tard - -### Limitations actuelles -- **Cold start** : Première requête lente après période d'inactivité -- **Nouveaux utilisateurs** : Pas de gestion du problème de démarrage à froid -- **Mise à jour des données** : Processus manuel - -## Architecture Cible (Future) - -### Améliorations prévues -- **Gestion cold start** : Recommandations populaires pour nouveaux utilisateurs -- **Pipeline de données** : Mise à jour automatique des embeddings -- **Base de données** : Stockage persistant des profils utilisateur -- **API hybride** : Combinaison Content-Based + Collaborative Filtering -- **Cache distribué** : Précalcul des recommandations populaires - -## Technologies Utilisées - -- **Backend** : Azure Functions, Python 3.12 -- **Frontend** : Streamlit -- **ML/Data** : scikit-learn, pandas, numpy -- **Infrastructure** : Azure CLI, Azure Storage -- **Déploiement** : Azure Functions Core Tools - -## Auteur - -Projet réalisé dans le cadre d'une formation OpenClassrooms - Ingénieur IA. - -## Licence - +**Source de vérité** : https://git.gregoiremureau.com/grgmro/oc-p10-content-recommendation + +```bash +git clone https://git.gregoiremureau.com/grgmro/oc-p10-content-recommendation.git +git clone https://git.gregoiremureau.com/grgmro/oc-p10-content-recommendation.git +``` + +Dataset : voir `fetch-data.sh` (hors git si volumineux). + +# Système de Recommandation de Contenu - My Content + +Projet de développement d'un système de recommandation d'articles basé sur une architecture serverless Azure Functions avec interface utilisateur Streamlit. + + +## Livrables du Projet +1. **Application fonctionnelle** : Streamlit + Azure Functions déployée +2. **Code source versionné** : Repository GitHub complet +3. **Présentation technique** : Support PDF (docs/presentation.pdf) + + +## Vue d'ensemble + +Ce projet implémente un système de recommandation de contenu utilisant des algorithmes de filtrage collaboratif et basé sur le contenu. L'architecture serverless permet une mise à l'échelle automatique et un coût optimisé. + +### Fonctionnalités principales + +- **API de recommandation** : Azure Function retournant le top 5 des articles recommandés pour un utilisateur +- **Interface utilisateur** : Application Streamlit pour tester et démontrer le système +- **Algorithmes implémentés** : Content-Based Filtering avec embeddings pré-calculés +- **Architecture serverless** : Déploiement sur Azure Functions avec plan Consumption + + +## Analyse et Développement + +### Notebook Jupyter +- **Exploration des données** : Analyse du dataset Kaggle Globo.com +- **Implémentation des algorithmes** : Content-Based et Collaborative Filtering +- **Comparaison des approches** : Évaluation et choix technique +- **Optimisation ACP** : Réduction dimensionnelle 250D → 50D + +Localisation : `notebook/p10_notebook.ipynb` + +## Architecture + +### MVP Actuel +``` +[Interface Streamlit] → [Azure Functions API] → [Algorithme de recommandation] + ↓ + [Données embeddings + historique utilisateur] +``` + +### Composants +- **Frontend** : Streamlit (interface de test) +- **Backend** : Azure Functions (Python 3.12, Linux) +- **Algorithme** : Content-Based Filtering avec similarité cosinus +- **Données** : Embeddings articles (50D via PCA vs 250D embeddings originaux) + historique des clics + +## Structure synthétique du Projet + +``` +Project_10/ +├── azure-app/ # Azure Function +│ ├── function_app.py # Point d'entrée Azure Function +│ ├── requirements.txt # Dépendances Python +│ ├── host.json # Configuration Azure Functions +│ ├── local.settings.json # Configuration locale (non versionnée) +│ ├── data/ +│ │ ├── embeddings_azure_50d.pkl # Embeddings articles (PCA 50D) +│ │ └── clicks_sample.csv # Historique des clics utilisateurs +│ └── utils/ +│ ├── data_loader.py # Chargement et cache des données +│ └── content_based.py # Algorithme de recommandation +├── notebook/ +│ └── p10_notebook.ipynb # Analyse données + développement modèles +├── docs/ +│ ├── presentation.pdf # Support de présentation (15-25 slides) +│ └── illustrations/ # Schémas d'architecture et captures +├── streamlit_app.py # Interface utilisateur +├── streamlit_requirements.txt # Dépendances Streamlit +└── README.md +``` + +## Installation et Déploiement + +### Prérequis +- Python 3.12+ +- Azure CLI +- Azure Functions Core Tools +- Compte Azure + +### Déploiement Azure Functions + +1. **Connexion à Azure** +```bash +az login +``` + +2. **Création de l'infrastructure** +```bash +# Groupe de ressources +az group create --name rg-content-recommender --location francecentral + +# Compte de stockage +az storage account create --name [votre-nom-stockage-unique] \ + --resource-group rg-content-recommender \ + --location francecentral \ + --sku Standard_LRS + +# Function App Linux avec Python 3.12 +az functionapp create \ + --resource-group rg-content-recommender \ + --consumption-plan-location francecentral \ + --runtime python \ + --runtime-version 3.12 \ + --functions-version 4 \ + --name contentrecommender-linux \ + --storage-account stcontentrecommend2025 \ + --os-type Linux +``` + +3. **Déploiement du code** +```bash +# Depuis le dossier azure-app +func azure functionapp publish contentrecommender-linux +``` + +### Interface Streamlit + +1. **Installation des dépendances** +```bash +pip install -r streamlit_requirements.txt +``` + +2. **Lancement de l'interface** +```bash +streamlit run streamlit_app.py +``` + +## Utilisation + +### API Azure Functions + +**Endpoint** : `https://contentrecommender-linux.azurewebsites.net/api/recommend` + +**Paramètres** : +- `user_id` (int) : Identifiant de l'utilisateur (0-706) + +**Exemple d'appel** : +```bash +curl "https://contentrecommender-linux.azurewebsites.net/api/recommend?user_id=0" +``` + +**Réponse** : +```json +{ + "user_id": 0, + "recommendations": [157519, 157944, 159495, 156690, 162857] +} +``` + +### Interface Streamlit + +1. Configurer l'URL de l'API (local ou Azure) +2. Sélectionner un ID utilisateur +3. Obtenir les recommandations +4. Tester les fonctionnalités avancées + +## Algorithme de Recommandation + +### Content-Based Filtering + +1. **Chargement des données** : Embeddings pré-calculés et historique utilisateur +2. **Calcul du profil utilisateur** : Moyenne des embeddings des articles consultés +3. **Similarité cosinus** : Calcul avec tous les articles du catalogue +4. **Filtrage** : Exclusion des articles déjà vus +5. **Sélection** : Top 5 des articles les plus similaires + +### Optimisations + +- **Réduction dimensionnelle** : PCA 250D → 50D pour optimiser les performances Azure +- **Cache en mémoire** : Embeddings et données utilisateur chargés une seule fois +- **Architecture serverless** : Mise à l'échelle automatique selon la demande + +## Tests et Validation + +### Tests locaux +```bash +# Démarrage Azure Functions local +func start + +# Test de l'algorithme +python test_local.py +``` + +### Métriques de performance +- **Temps de réponse** : ~200ms par recommandation +- **Utilisateurs supportés** : 707 dans le dataset actuel +- **Articles disponibles** : 364,047 avec embeddings + +## Problèmes Connus et Solutions + +### Déploiement Azure +- **Python sur Windows** : Non supporté, utiliser Linux obligatoirement +- **Authentification** : Configurer `http_auth_level=func.AuthLevel.ANONYMOUS` +- **Erreurs "Service unavailable"** : Problèmes temporaires Azure, réessayer plus tard + +### Limitations actuelles +- **Cold start** : Première requête lente après période d'inactivité +- **Nouveaux utilisateurs** : Pas de gestion du problème de démarrage à froid +- **Mise à jour des données** : Processus manuel + +## Architecture Cible (Future) + +### Améliorations prévues +- **Gestion cold start** : Recommandations populaires pour nouveaux utilisateurs +- **Pipeline de données** : Mise à jour automatique des embeddings +- **Base de données** : Stockage persistant des profils utilisateur +- **API hybride** : Combinaison Content-Based + Collaborative Filtering +- **Cache distribué** : Précalcul des recommandations populaires + +## Technologies Utilisées + +- **Backend** : Azure Functions, Python 3.12 +- **Frontend** : Streamlit +- **ML/Data** : scikit-learn, pandas, numpy +- **Infrastructure** : Azure CLI, Azure Storage +- **Déploiement** : Azure Functions Core Tools + +## Auteur + +Projet réalisé dans le cadre d'une formation OpenClassrooms - Ingénieur IA. + +## Licence + Ce projet est à des fins éducatives uniquement. \ No newline at end of file diff --git a/fetch-data.sh b/fetch-data.sh new file mode 100755 index 0000000..3e39ade --- /dev/null +++ b/fetch-data.sh @@ -0,0 +1,9 @@ +#!/usr/bin/env bash +set -euo pipefail +cat <<'TXT' +P10 — recommandation de contenu + +Hors git : embeddings pickle (~73 Mo) et articles_metadata.csv. +Récupération : archive Nextcloud dossier « 10 Réalisez une application de recommandation… » +ou artefacts Azure du projet (non publics). +TXT