RomanNum3ral
/
AI-For-Beginners
mirror of https://github.com/microsoft/AI-For-Beginners.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
AI-For-Beginners/translations/en/AGENTS.md

10 KiB
Raw Blame History

AGENTS.md

Project Overview

AI for Beginners is a comprehensive 12-week, 24-lesson curriculum that introduces the fundamentals of Artificial Intelligence. This educational repository includes practical lessons using Jupyter Notebooks, quizzes, and hands-on labs. The curriculum covers:

  • Symbolic AI, including Knowledge Representation and Expert Systems
  • Neural Networks and Deep Learning with TensorFlow and PyTorch
  • Computer Vision techniques and architectures
  • Natural Language Processing (NLP), including transformers and BERT
  • Specialized topics: Genetic Algorithms, Reinforcement Learning, Multi-Agent Systems
  • AI Ethics and principles of Responsible AI

Key Technologies: Python 3, Jupyter Notebooks, TensorFlow, PyTorch, Keras, OpenCV, Vue.js (for the quiz app)

Architecture: An educational content repository with Jupyter Notebooks organized by topic areas, supplemented by a Vue.js-based quiz application and extensive multi-language support.

Setup Commands

Primary Development Environment (Python/Jupyter)

The curriculum is designed to run with Python and Jupyter Notebooks. The recommended approach is using miniconda:

# Clone the repository
git clone https://github.com/microsoft/ai-for-beginners
cd ai-for-beginners

# Create and activate conda environment
conda env create --name ai4beg --file environment.yml
conda activate ai4beg

# Start Jupyter Notebook
jupyter notebook
# OR
jupyter lab

Alternative: Using devcontainer

# Open in VS Code and select "Reopen in Container" when prompted
# The devcontainer will automatically set up the environment

Quiz Application Setup

The quiz app is a separate Vue.js application located in etc/quiz-app/:

cd etc/quiz-app
npm install
npm run serve  # Development server
npm run build  # Production build
npm run lint   # Lint and fix files

Development Workflow

Working with Jupyter Notebooks

  1. Local Development:

    • Activate the conda environment: conda activate ai4beg
    • Start Jupyter: jupyter notebook or jupyter lab
    • Navigate to lesson folders and open .ipynb files
    • Run cells interactively to follow the lessons

  2. VS Code with Python Extension:

    • Open the repository in VS Code
    • Install the Python extension
    • VS Code automatically detects and uses the conda environment
    • Open .ipynb files directly in VS Code

  3. Cloud Development:

    • GitHub Codespaces: Click "Code" → "Codespaces" → "Create codespace on main"
    • Binder: Use the Binder badge on README to launch in the browser
    • Note: Binder has limited resources and some web access restrictions

GPU Support for Advanced Lessons

Later lessons benefit significantly from GPU acceleration:

  • Azure Data Science VM: Use NC-series VMs with GPU support
  • Azure Machine Learning: Use notebook features with GPU compute
  • Google Colab: Upload notebooks individually (offers free GPU support)

Quiz App Development

cd etc/quiz-app
npm run serve  # Hot-reload development server at http://localhost:8080

Testing Instructions

This is an educational repository focused on learning content rather than software testing. There is no traditional test suite.

Validation Approaches:

  1. Jupyter Notebooks: Execute cells sequentially to verify that code examples work
  2. Quiz App Testing: Perform manual testing via the development server
  3. Translation Validation: Check translated content in the translations/ folder
  4. Quiz App Linting: Run npm run lint in etc/quiz-app/

Running Code Examples:

# Activate environment first
conda activate ai4beg

# Run Python scripts directly
python lessons/4-ComputerVision/07-ConvNets/pytorchcv.py

# Or execute notebooks
jupyter notebook lessons/3-NeuralNetworks/03-Perceptron/Perceptron.ipynb

Code Style

Python Code Style

  • Follow standard Python conventions for educational code
  • Write clear, readable code that prioritizes learning over optimization
  • Include comments explaining key concepts
  • Ensure Jupyter Notebook cells are self-contained where possible
  • No strict linting requirements for lesson content

JavaScript/Vue.js (Quiz App)

  • ESLint configuration is in etc/quiz-app/package.json
  • Run npm run lint to check and auto-fix issues
  • Follow Vue 2.x conventions
  • Use a component-based architecture

File Organization

lessons/
  ├── 0-course-setup/          # Setup instructions
  ├── 1-Intro/                 # Introduction to AI
  ├── 2-Symbolic/              # Symbolic AI
  ├── 3-NeuralNetworks/        # Neural Networks basics
  ├── 4-ComputerVision/        # Computer Vision
  ├── 5-NLP/                   # Natural Language Processing
  ├── 6-Other/                 # Other AI techniques
  ├── 7-Ethics/                # AI Ethics
  └── X-Extras/                # Additional content

etc/
  ├── quiz-app/                # Vue.js quiz application
  └── quiz-src/                # Quiz source files

translations/                  # Multi-language translations

Build and Deployment

Jupyter Content

No build process is required - Jupyter Notebooks are executed directly.

Quiz Application

cd etc/quiz-app

# Development
npm run serve

# Production build
npm run build  # Outputs to etc/quiz-app/dist/

# Deploy to Azure Static Web Apps
# Azure automatically creates GitHub Actions workflow
# See etc/quiz-app/README.md for detailed deployment instructions

Documentation Site

The repository uses Docsify for documentation:

Contributing Guidelines

Pull Request Process

  1. Title Format: Use clear, descriptive titles that explain the change
  2. CLA Requirement: Microsoft CLA must be signed (automated check)
  3. Content Guidelines:
    • Maintain an educational focus and beginner-friendly approach
    • Test all code examples in notebooks
    • Ensure notebooks run end-to-end
    • Update translations if modifying English content
  4. Quiz App Changes: Run npm run lint before committing

Translation Contributions

  • Translations are automated via GitHub Actions using co-op-translator
  • Manual translations go in translations/<language-code>/
  • Quiz translations are located in etc/quiz-app/src/assets/translations/
  • Supported languages: 40+ languages (see README for the full list)

Active Contribution Areas

See etc/CONTRIBUTING.md for current needs:

  • Deep Reinforcement Learning sections
  • Object Detection improvements
  • Named Entity Recognition examples
  • Custom embedding training samples

Environment Configuration

Required Dependencies

# Core Python packages (from requirements.txt)
tensorflow==2.17.0
torch (via conda)
torchvision (via conda)
keras==3.5.0
opencv (via conda)
scikit-learn
numpy==1.26
pandas==2.2.2
matplotlib==3.9
jupyter

Environment Variables

No special environment variables are required for basic usage.

For Azure deployments (quiz app):

  • AZURE_STATIC_WEB_APPS_API_TOKEN (set automatically by Azure)

Debugging and Troubleshooting

Common Issues

Issue: Conda environment creation fails

  • Solution: Update conda first: conda update conda -y
  • Ensure sufficient disk space (50GB recommended)

Issue: Jupyter kernel not found

  • Solution: 
    conda activate ai4beg
python -m ipykernel install --user --name ai4beg

Issue: GPU not detected in notebooks

  • Solution:
    • Verify CUDA installation: nvidia-smi
    • Check PyTorch GPU: python -c "import torch; print(torch.cuda.is_available())"
    • Check TensorFlow GPU: python -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"

Issue: Quiz app won't start

  • Solution: 
    cd etc/quiz-app
rm -rf node_modules package-lock.json
npm install
npm run serve

Issue: Binder times out or blocks downloads

  • Solution: Use GitHub Codespaces or local setup for better resource access

Memory Issues

Some lessons require significant RAM (8GB+ recommended):

  • Use cloud VMs for resource-intensive lessons
  • Close other applications when training models
  • Reduce batch sizes in notebooks if running out of memory

Additional Notes

For Course Instructors

  • See lessons/0-course-setup/for-teachers.md for teaching guidance
  • Lessons are self-contained and can be taught in sequence or selected individually
  • Estimated time: 12 weeks at 2 lessons per week

Cloud Resources

  • Azure for Students: Free credits available for students
  • Microsoft Learn: Supplementary learning paths linked throughout
  • Binder: Free but limited resources and some network restrictions

Code Execution Options

  1. Local (Recommended): Full control, best performance, GPU support
  2. GitHub Codespaces: Cloud-based VS Code, good for quick access
  3. Binder: Browser-based Jupyter, free but limited
  4. Azure ML Notebooks: Enterprise option with GPU support
  5. Google Colab: Upload notebooks individually, free GPU tier available

Working with Notebooks

  • Notebooks are designed to be run cell-by-cell for learning
  • Many notebooks download datasets on the first run (may take time)
  • Some models require GPU for reasonable training times
  • Pre-trained models are used where possible to reduce compute requirements

Performance Considerations

  • Later computer vision lessons (CNNs, GANs) benefit from GPU
  • NLP transformer lessons may require significant RAM
  • Training from scratch is educational but time-consuming
  • Transfer learning examples minimize training time

Disclaimer:
This document has been translated using the AI translation service Co-op Translator. While we aim for accuracy, please note that automated translations may contain errors or inaccuracies. The original document in its native language should be regarded as the authoritative source. For critical information, professional human translation is recommended. We are not responsible for any misunderstandings or misinterpretations resulting from the use of this translation.