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

326 lines
10 KiB
Markdown
Raw Blame History

<!--
CO_OP_TRANSLATOR_METADATA:
{
"original_hash": "6b11a37115944252ab3ed04e358d830d",
"translation_date": "2025-10-03T09:10:35+00:00",
"source_file": "AGENTS.md",
"language_code": "en"
}
-->
# 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:
```bash
# 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
```bash
# 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/`:
```bash
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
```bash
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:
```bash
# 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
```bash
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:
- `index.html` serves as the entry point
- No build is required - served directly via GitHub Pages
- Access at: https://microsoft.github.io/AI-For-Beginners/
## 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
```bash
# 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:**
```bash
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:**
```bash
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](https://github.com/Azure/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.
Reference in New Issue View Git Blame Copy Permalink