317 lines
17 KiB
Markdown
317 lines
17 KiB
Markdown
# AGENTS.md
|
||
|
||
## Обзор проекта
|
||
|
||
AI for Beginners — это комплексная 12-недельная программа из 24 уроков, охватывающая основы искусственного интеллекта. Этот образовательный репозиторий включает практические занятия с использованием Jupyter Notebooks, тесты и лабораторные работы. Программа охватывает:
|
||
|
||
- Символьный ИИ с представлением знаний и экспертными системами
|
||
- Нейронные сети и глубокое обучение с TensorFlow и PyTorch
|
||
- Техники и архитектуры компьютерного зрения
|
||
- Обработка естественного языка (NLP), включая трансформеры и BERT
|
||
- Специализированные темы: генетические алгоритмы, обучение с подкреплением, системы с несколькими агентами
|
||
- Этика ИИ и принципы ответственного использования ИИ
|
||
|
||
**Основные технологии:** Python 3, Jupyter Notebooks, TensorFlow, PyTorch, Keras, OpenCV, Vue.js (для приложения с тестами)
|
||
|
||
**Архитектура:** Репозиторий образовательного контента с Jupyter Notebooks, организованный по тематическим областям, дополненный приложением для тестов на основе Vue.js и поддержкой нескольких языков.
|
||
|
||
## Команды для настройки
|
||
|
||
### Основная среда разработки (Python/Jupyter)
|
||
|
||
Программа разработана для работы с Python и Jupyter Notebooks. Рекомендуется использовать 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
|
||
```
|
||
|
||
### Альтернатива: использование devcontainer
|
||
|
||
```bash
|
||
# Open in VS Code and select "Reopen in Container" when prompted
|
||
# The devcontainer will automatically set up the environment
|
||
```
|
||
|
||
### Настройка приложения для тестов
|
||
|
||
Приложение для тестов — это отдельное приложение на Vue.js, расположенное в `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
|
||
```
|
||
|
||
## Рабочий процесс разработки
|
||
|
||
### Работа с Jupyter Notebooks
|
||
|
||
1. **Локальная разработка:**
|
||
- Активируйте среду conda: `conda activate ai4beg`
|
||
- Запустите Jupyter: `jupyter notebook` или `jupyter lab`
|
||
- Перейдите в папки уроков и откройте файлы `.ipynb`
|
||
- Запускайте ячейки интерактивно, чтобы следовать урокам
|
||
|
||
2. **VS Code с расширением Python:**
|
||
- Откройте репозиторий в VS Code
|
||
- Установите расширение Python
|
||
- VS Code автоматически обнаружит и использует среду conda
|
||
- Открывайте файлы `.ipynb` прямо в VS Code
|
||
|
||
3. **Облачная разработка:**
|
||
- **GitHub Codespaces:** Нажмите "Code" → "Codespaces" → "Create codespace on main"
|
||
- **Binder:** Используйте значок Binder в README для запуска в браузере
|
||
- Примечание: Binder имеет ограниченные ресурсы и некоторые ограничения на доступ к вебу
|
||
|
||
### Поддержка GPU для продвинутых уроков
|
||
|
||
Поздние уроки значительно выигрывают от ускорения с помощью GPU:
|
||
|
||
- **Azure Data Science VM:** Используйте виртуальные машины серии NC с поддержкой GPU
|
||
- **Azure Machine Learning:** Используйте функции ноутбуков с вычислениями на GPU
|
||
- **Google Colab:** Загружайте ноутбуки по отдельности (есть бесплатная поддержка GPU)
|
||
|
||
### Разработка приложения для тестов
|
||
|
||
```bash
|
||
cd etc/quiz-app
|
||
npm run serve # Hot-reload development server at http://localhost:8080
|
||
```
|
||
|
||
## Инструкции по тестированию
|
||
|
||
Этот репозиторий предназначен для обучения, а не для тестирования программного обеспечения. Традиционный набор тестов отсутствует.
|
||
|
||
### Подходы к проверке:
|
||
|
||
1. **Jupyter Notebooks:** Последовательно выполняйте ячейки, чтобы убедиться, что примеры кода работают
|
||
2. **Тестирование приложения для тестов:** Ручное тестирование через сервер разработки
|
||
3. **Проверка перевода:** Проверьте переведенный контент в папке `translations/`
|
||
4. **Линтинг приложения для тестов:** `npm run lint` в `etc/quiz-app/`
|
||
|
||
### Запуск примеров кода:
|
||
|
||
```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
|
||
```
|
||
|
||
## Стиль кода
|
||
|
||
### Стиль кода Python
|
||
|
||
- Стандартные соглашения Python для образовательного кода
|
||
- Понятный, читаемый код с приоритетом обучения над оптимизацией
|
||
- Комментарии, объясняющие ключевые концепции
|
||
- Удобство для Jupyter Notebook: ячейки должны быть максимально автономными
|
||
- Нет строгих требований к линтингу для контента уроков
|
||
|
||
### JavaScript/Vue.js (приложение для тестов)
|
||
|
||
- Конфигурация ESLint в `etc/quiz-app/package.json`
|
||
- Запустите `npm run lint`, чтобы проверить и автоматически исправить проблемы
|
||
- Соглашения Vue 2.x
|
||
- Архитектура на основе компонентов
|
||
|
||
### Организация файлов
|
||
|
||
```
|
||
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
|
||
```
|
||
|
||
## Сборка и развертывание
|
||
|
||
### Контент Jupyter
|
||
|
||
Процесс сборки не требуется — Jupyter Notebooks выполняются напрямую.
|
||
|
||
### Приложение для тестов
|
||
|
||
```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
|
||
```
|
||
|
||
### Сайт документации
|
||
|
||
Репозиторий использует Docsify для документации:
|
||
- `index.html` служит точкой входа
|
||
- Сборка не требуется — сайт обслуживается напрямую через GitHub Pages
|
||
- Доступ по адресу: https://microsoft.github.io/AI-For-Beginners/
|
||
|
||
## Руководство по внесению изменений
|
||
|
||
### Процесс Pull Request
|
||
|
||
1. **Формат заголовка:** Четкие, описательные заголовки, описывающие изменения
|
||
2. **Требование CLA:** Необходимо подписать Microsoft CLA (автоматическая проверка)
|
||
3. **Рекомендации по контенту:**
|
||
- Сохраняйте образовательный фокус и подход, ориентированный на новичков
|
||
- Тестируйте все примеры кода в ноутбуках
|
||
- Убедитесь, что ноутбуки выполняются от начала до конца
|
||
- Обновляйте переводы, если изменяете контент на английском
|
||
4. **Изменения в приложении для тестов:** Запустите `npm run lint` перед коммитом
|
||
|
||
### Внесение переводов
|
||
|
||
- Переводы автоматизируются через GitHub Actions с использованием co-op-translator
|
||
- Ручные переводы размещаются в `translations/<language-code>/`
|
||
- Переводы тестов находятся в `etc/quiz-app/src/assets/translations/`
|
||
- Поддерживаемые языки: более 40 языков (см. README для полного списка)
|
||
|
||
### Активные области для внесения изменений
|
||
|
||
См. `etc/CONTRIBUTING.md` для текущих потребностей:
|
||
- Разделы глубокого обучения с подкреплением
|
||
- Улучшения в обнаружении объектов
|
||
- Примеры распознавания именованных сущностей
|
||
- Обучение пользовательских эмбеддингов
|
||
|
||
## Конфигурация среды
|
||
|
||
### Необходимые зависимости
|
||
|
||
```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
|
||
```
|
||
|
||
### Переменные среды
|
||
|
||
Специальные переменные среды для базового использования не требуются.
|
||
|
||
Для развертывания в Azure (приложение для тестов):
|
||
- `AZURE_STATIC_WEB_APPS_API_TOKEN` (устанавливается автоматически Azure)
|
||
|
||
## Отладка и устранение неполадок
|
||
|
||
### Распространенные проблемы
|
||
|
||
**Проблема:** Ошибка при создании среды conda
|
||
- **Решение:** Сначала обновите conda: `conda update conda -y`
|
||
- Убедитесь, что достаточно места на диске (рекомендуется 50 ГБ)
|
||
|
||
**Проблема:** Ядро Jupyter не найдено
|
||
- **Решение:**
|
||
```bash
|
||
conda activate ai4beg
|
||
python -m ipykernel install --user --name ai4beg
|
||
```
|
||
|
||
**Проблема:** GPU не обнаружен в ноутбуках
|
||
- **Решение:**
|
||
- Проверьте установку CUDA: `nvidia-smi`
|
||
- Проверьте GPU в PyTorch: `python -c "import torch; print(torch.cuda.is_available())"`
|
||
- Проверьте GPU в TensorFlow: `python -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"`
|
||
|
||
**Проблема:** Приложение для тестов не запускается
|
||
- **Решение:**
|
||
```bash
|
||
cd etc/quiz-app
|
||
rm -rf node_modules package-lock.json
|
||
npm install
|
||
npm run serve
|
||
```
|
||
|
||
**Проблема:** Binder зависает или блокирует загрузки
|
||
- **Решение:** Используйте GitHub Codespaces или локальную настройку для лучшего доступа к ресурсам
|
||
|
||
### Проблемы с памятью
|
||
|
||
Некоторые уроки требуют значительного объема оперативной памяти (рекомендуется 8 ГБ+):
|
||
- Используйте облачные виртуальные машины для ресурсоемких уроков
|
||
- Закройте другие приложения при обучении моделей
|
||
- Уменьшите размеры пакетов в ноутбуках, если памяти недостаточно
|
||
|
||
## Дополнительные заметки
|
||
|
||
### Для преподавателей курса
|
||
|
||
- См. `lessons/0-course-setup/for-teachers.md` для руководства по преподаванию
|
||
- Уроки автономны и могут преподаваться последовательно или выбираться индивидуально
|
||
- Оценочное время: 12 недель при 2 уроках в неделю
|
||
|
||
### Облачные ресурсы
|
||
|
||
- **Azure для студентов:** Бесплатные кредиты доступны для студентов
|
||
- **Microsoft Learn:** Дополнительные учебные материалы, связанные с уроками
|
||
- **Binder:** Бесплатно, но ограниченные ресурсы и некоторые сетевые ограничения
|
||
|
||
### Варианты выполнения кода
|
||
|
||
1. **Локально (рекомендуется):** Полный контроль, лучшая производительность, поддержка GPU
|
||
2. **GitHub Codespaces:** Облачный VS Code, удобен для быстрого доступа
|
||
3. **Binder:** Jupyter в браузере, бесплатно, но ограничено
|
||
4. **Azure ML Notebooks:** Корпоративный вариант с поддержкой GPU
|
||
5. **Google Colab:** Загружайте ноутбуки по отдельности, доступен бесплатный уровень GPU
|
||
|
||
### Работа с ноутбуками
|
||
|
||
- Ноутбуки разработаны для выполнения ячейка за ячейкой в образовательных целях
|
||
- Многие ноутбуки загружают наборы данных при первом запуске (может занять время)
|
||
- Некоторые модели требуют GPU для разумного времени обучения
|
||
- Используются предварительно обученные модели, чтобы снизить требования к вычислениям
|
||
|
||
### Учет производительности
|
||
|
||
- Поздние уроки по компьютерному зрению (CNN, GAN) выигрывают от GPU
|
||
- Уроки по трансформерам NLP могут требовать значительного объема оперативной памяти
|
||
- Обучение с нуля полезно для обучения, но занимает много времени
|
||
- Примеры с переносом обучения минимизируют время обучения
|
||
|
||
---
|
||
|
||
**Отказ от ответственности**:
|
||
Этот документ был переведен с помощью сервиса автоматического перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия обеспечить точность, автоматические переводы могут содержать ошибки или неточности. Оригинальный документ на его родном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется профессиональный перевод человеком. Мы не несем ответственности за любые недоразумения или неправильные интерпретации, возникшие в результате использования данного перевода. |