13 KiB

Raw Blame History

AGENTS.md

Aperçu du projet

Voici Machine Learning pour les débutants, un programme complet de 12 semaines et 26 leçons couvrant les concepts classiques de l'apprentissage automatique en utilisant Python (principalement avec Scikit-learn) et R. Ce dépôt est conçu comme une ressource d'apprentissage autonome avec des projets pratiques, des quiz et des devoirs. Chaque leçon explore les concepts de l'IA à travers des données réelles provenant de diverses cultures et régions du monde.

Principaux éléments :

Contenu éducatif : 26 leçons couvrant l'introduction à l'IA, la régression, la classification, le clustering, le NLP, les séries temporelles et l'apprentissage par renforcement
Application de quiz : Application de quiz basée sur Vue.js avec des évaluations avant et après les leçons
Support multilingue : Traductions automatiques dans plus de 40 langues via GitHub Actions
Support bilingue : Leçons disponibles en Python (notebooks Jupyter) et en R (fichiers R Markdown)
Apprentissage basé sur des projets : Chaque sujet inclut des projets pratiques et des devoirs

Structure du dépôt

ML-For-Beginners/
├── 1-Introduction/         # ML basics, history, fairness, techniques
├── 2-Regression/          # Regression models with Python/R
├── 3-Web-App/            # Flask web app for ML model deployment
├── 4-Classification/      # Classification algorithms
├── 5-Clustering/         # Clustering techniques
├── 6-NLP/               # Natural Language Processing
├── 7-TimeSeries/        # Time series forecasting
├── 8-Reinforcement/     # Reinforcement learning
├── 9-Real-World/        # Real-world ML applications
├── quiz-app/           # Vue.js quiz application
├── translations/       # Auto-generated translations
└── sketchnotes/       # Visual learning aids

Chaque dossier de leçon contient généralement :

README.md - Contenu principal de la leçon
notebook.ipynb - Notebook Jupyter en Python
solution/ - Code solution (versions Python et R)
assignment.md - Exercices pratiques
images/ - Ressources visuelles

Commandes d'installation

Pour les leçons en Python

La plupart des leçons utilisent des notebooks Jupyter. Installez les dépendances nécessaires :

# Install Python 3.8+ if not already installed
python --version

# Install Jupyter
pip install jupyter

# Install common ML libraries
pip install scikit-learn pandas numpy matplotlib seaborn

# For specific lessons, check lesson-specific requirements
# Example: Web App lesson
pip install flask

Pour les leçons en R

Les leçons en R se trouvent dans les dossiers solution/R/ sous forme de fichiers .rmd ou .ipynb :

# Install R and required packages
# In R console:
install.packages(c("tidyverse", "tidymodels", "caret"))

Pour l'application de quiz

L'application de quiz est une application Vue.js située dans le répertoire quiz-app/ :

cd quiz-app
npm install

Pour le site de documentation

Pour exécuter la documentation localement :

# Install Docsify
npm install -g docsify-cli

# Serve from repository root
docsify serve

# Access at http://localhost:3000

Flux de travail de développement

Travailler avec les notebooks de leçon

Accédez au répertoire de la leçon (par exemple, 2-Regression/1-Tools/)
Ouvrez le notebook Jupyter :
```
jupyter notebook notebook.ipynb
```
Parcourez le contenu de la leçon et les exercices
Consultez les solutions dans le dossier solution/ si nécessaire

Développement en Python

Les leçons utilisent les bibliothèques standards de science des données en Python
Notebooks Jupyter pour un apprentissage interactif
Code solution disponible dans le dossier solution/ de chaque leçon

Développement en R

Les leçons en R sont au format .rmd (R Markdown)
Solutions situées dans les sous-dossiers solution/R/
Utilisez RStudio ou Jupyter avec le noyau R pour exécuter les notebooks R

Développement de l'application de quiz

cd quiz-app

# Start development server
npm run serve
# Access at http://localhost:8080

# Build for production
npm run build

# Lint and fix files
npm run lint

Instructions de test

Test de l'application de quiz

cd quiz-app

# Lint code
npm run lint

# Build to verify no errors
npm run build

Remarque : Il s'agit principalement d'un dépôt de programme éducatif. Il n'y a pas de tests automatisés pour le contenu des leçons. La validation se fait par :

La réalisation des exercices des leçons
L'exécution réussie des cellules des notebooks
La vérification des résultats par rapport aux solutions attendues

Directives de style de code

Code Python

Suivez les directives de style PEP 8
Utilisez des noms de variables clairs et descriptifs
Ajoutez des commentaires pour les opérations complexes
Les notebooks Jupyter doivent inclure des cellules markdown expliquant les concepts

JavaScript/Vue.js (Application de quiz)

Suivez le guide de style Vue.js
Configuration ESLint dans quiz-app/package.json
Exécutez npm run lint pour vérifier et corriger automatiquement les problèmes

Documentation

Les fichiers Markdown doivent être clairs et bien structurés
Incluez des exemples de code dans des blocs de code délimités
Utilisez des liens relatifs pour les références internes
Suivez les conventions de formatage existantes

Construction et déploiement

Déploiement de l'application de quiz

L'application de quiz peut être déployée sur Azure Static Web Apps :

Prérequis :
- Compte Azure
- Dépôt GitHub (déjà forké)
Déployer sur Azure :
- Créez une ressource Azure Static Web App
- Connectez-vous au dépôt GitHub
- Définissez l'emplacement de l'application : /quiz-app
- Définissez l'emplacement de sortie : dist
- Azure crée automatiquement un workflow GitHub Actions
Workflow GitHub Actions :
- Fichier de workflow créé dans .github/workflows/azure-static-web-apps-*.yml
- Construction et déploiement automatiques lors d'un push sur la branche principale

Documentation PDF

Générez un PDF à partir de la documentation :

npm install
npm run convert

Flux de travail de traduction

Important : Les traductions sont automatisées via GitHub Actions en utilisant Co-op Translator.

Les traductions sont générées automatiquement lorsque des modifications sont poussées sur la branche main
NE PAS traduire manuellement le contenu - le système s'en charge
Workflow défini dans .github/workflows/co-op-translator.yml
Utilise les services Azure AI/OpenAI pour la traduction
Prend en charge plus de 40 langues

Directives de contribution

Pour les contributeurs de contenu

Forkez le dépôt et créez une branche de fonctionnalité
Apportez des modifications au contenu des leçons si vous ajoutez ou mettez à jour des leçons
Ne modifiez pas les fichiers traduits - ils sont générés automatiquement
Testez votre code - assurez-vous que toutes les cellules des notebooks s'exécutent correctement
Vérifiez les liens et les images pour s'assurer qu'ils fonctionnent
Soumettez une pull request avec une description claire

Directives pour les pull requests

Format du titre : [Section] Brève description des modifications
- Exemple : [Regression] Correction d'une faute de frappe dans la leçon 5
- Exemple : [Quiz-App] Mise à jour des dépendances
Avant de soumettre :
- Assurez-vous que toutes les cellules des notebooks s'exécutent sans erreurs
- Exécutez npm run lint si vous modifiez l'application de quiz
- Vérifiez le formatage Markdown
- Testez tout nouvel exemple de code
La PR doit inclure :
- Description des modifications
- Raison des modifications
- Captures d'écran si des modifications de l'interface utilisateur sont apportées
Code de conduite : Suivez le Code de conduite Open Source de Microsoft
CLA : Vous devrez signer l'accord de licence de contributeur

Structure des leçons

Chaque leçon suit un modèle cohérent :

Quiz pré-lecture - Testez les connaissances de base
Contenu de la leçon - Instructions et explications écrites
Démonstrations de code - Exemples pratiques dans les notebooks
Vérifications des connaissances - Vérifiez la compréhension tout au long
Défi - Appliquez les concepts de manière autonome
Devoir - Pratique approfondie
Quiz post-lecture - Évaluez les résultats d'apprentissage

Référence des commandes courantes

# Python/Jupyter
jupyter notebook                    # Start Jupyter server
jupyter notebook notebook.ipynb     # Open specific notebook
pip install -r requirements.txt     # Install dependencies (where available)

# Quiz App
cd quiz-app
npm install                        # Install dependencies
npm run serve                      # Development server
npm run build                      # Production build
npm run lint                       # Lint and fix

# Documentation
docsify serve                      # Serve documentation locally
npm run convert                    # Generate PDF

# Git workflow
git checkout -b feature/my-change  # Create feature branch
git add .                         # Stage changes
git commit -m "Description"       # Commit changes
git push origin feature/my-change # Push to remote

Ressources supplémentaires

Collection Microsoft Learn : Modules ML pour les débutants
Application de quiz : Quiz en ligne
Forum de discussion : Discussions GitHub
Tutoriels vidéo : Playlist YouTube

Technologies clés

Python : Langage principal pour les leçons d'IA (Scikit-learn, Pandas, NumPy, Matplotlib)
R : Implémentation alternative utilisant tidyverse, tidymodels, caret
Jupyter : Notebooks interactifs pour les leçons en Python
R Markdown : Documents pour les leçons en R
Vue.js 3 : Framework de l'application de quiz
Flask : Framework d'application web pour le déploiement de modèles IA
Docsify : Générateur de site de documentation
GitHub Actions : CI/CD et traductions automatisées

Considérations de sécurité

Pas de secrets dans le code : Ne jamais inclure de clés API ou de identifiants
Dépendances : Maintenez les packages npm et pip à jour
Entrées utilisateur : Les exemples d'applications web Flask incluent une validation de base des entrées
Données sensibles : Les ensembles de données d'exemple sont publics et non sensibles

Résolution de problèmes

Notebooks Jupyter

Problèmes de noyau : Redémarrez le noyau si les cellules se bloquent : Kernel → Restart
Erreurs d'importation : Assurez-vous que tous les packages requis sont installés avec pip
Problèmes de chemin : Exécutez les notebooks depuis leur répertoire contenant

Application de quiz

Échec de npm install : Nettoyez le cache npm : npm cache clean --force
Conflits de port : Changez le port avec : npm run serve -- --port 8081
Erreurs de construction : Supprimez node_modules et réinstallez : rm -rf node_modules && npm install

Leçons en R

Package introuvable : Installez avec : install.packages("nom-du-package")
RMarkdown non rendu : Assurez-vous que le package rmarkdown est installé
Problèmes de noyau : Vous devrez peut-être installer IRkernel pour Jupyter

Notes spécifiques au projet

Il s'agit principalement d'un programme éducatif, et non de code de production
L'objectif est de comprendre les concepts de l'IA grâce à une pratique concrète
Les exemples de code privilégient la clarté plutôt que l'optimisation
La plupart des leçons sont autonomes et peuvent être réalisées indépendamment
Solutions fournies, mais les apprenants doivent d'abord tenter les exercices
Le dépôt utilise Docsify pour la documentation web sans étape de construction
Les Sketchnotes offrent des résumés visuels des concepts
Le support multilingue rend le contenu accessible à l'échelle mondiale

Avertissement :
Ce document a été traduit à l'aide du service de traduction automatique Co-op Translator. Bien que nous nous efforcions d'assurer l'exactitude, veuillez noter que les traductions automatisées peuvent contenir des erreurs ou des inexactitudes. Le document original dans sa langue d'origine doit être considéré comme la source faisant autorité. Pour des informations critiques, il est recommandé de recourir à une traduction professionnelle réalisée par un humain. Nous déclinons toute responsabilité en cas de malentendus ou d'interprétations erronées résultant de l'utilisation de cette traduction.

13 KiB Raw Blame History