ML-For-Beginners/translations/uk/AGENTS.md

AGENTS.md

Огляд проєкту

Це Machine Learning for Beginners — комплексна навчальна програма на 12 тижнів, що складається з 26 уроків, які охоплюють класичні концепції машинного навчання за допомогою Python (переважно з використанням Scikit-learn) та R. Репозиторій створений як ресурс для самостійного навчання з практичними проєктами, тестами та завданнями. Кожен урок досліджує концепції ML через реальні дані з різних культур і регіонів світу.

Основні компоненти:

• Навчальний контент: 26 уроків, що охоплюють введення в ML, регресію, класифікацію, кластеризацію, NLP, часові ряди та навчання з підкріпленням
• Додаток для тестів: Додаток для тестування на основі Vue.js з оцінюванням до та після уроків
• Підтримка багатьох мов: Автоматичні переклади на 40+ мов за допомогою GitHub Actions
• Двомовна підтримка: Уроки доступні як у Python (Jupyter notebooks), так і в R (R Markdown файли)
• Навчання через проєкти: Кожна тема включає практичні проєкти та завдання

Структура репозиторію

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

Кожна папка уроку зазвичай містить:

• README.md - Основний контент уроку
• notebook.ipynb - Jupyter notebook для Python
• solution/ - Код рішення (версії для Python і R)
• assignment.md - Практичні вправи
• images/ - Візуальні ресурси

Команди для налаштування

Для уроків на Python

Більшість уроків використовують Jupyter notebooks. Встановіть необхідні залежності:

# 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

Для уроків на R

Уроки на R знаходяться в папках solution/R/ у форматі .rmd або .ipynb:

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

Для додатка тестів

Додаток тестів — це Vue.js-додаток, розташований у папці quiz-app/:

cd quiz-app
npm install

Для сайту документації

Щоб запустити документацію локально:

# Install Docsify
npm install -g docsify-cli

# Serve from repository root
docsify serve

# Access at http://localhost:3000

Робочий процес розробки

Робота з ноутбуками уроків

1. Перейдіть до папки уроку (наприклад, 2-Regression/1-Tools/)
2. Відкрийте Jupyter notebook:

   jupyter notebook notebook.ipynb
   

3. Пройдіть через контент уроку та вправи
4. Перевірте рішення в папці solution/, якщо потрібно

Розробка на Python

• Уроки використовують стандартні бібліотеки Python для аналізу даних
• Jupyter notebooks для інтерактивного навчання
• Код рішень доступний у папці solution/ кожного уроку

Розробка на R

• Уроки на R представлені у форматі .rmd (R Markdown)
• Рішення знаходяться в підкаталогах solution/R/
• Використовуйте RStudio або Jupyter з ядром R для запуску ноутбуків на R

Розробка додатка тестів

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

Інструкції з тестування

Тестування додатка тестів

cd quiz-app

# Lint code
npm run lint

# Build to verify no errors
npm run build

Примітка: Це переважно навчальний репозиторій. Автоматизовані тести для контенту уроків не передбачені. Перевірка здійснюється через:

• Виконання вправ уроків
• Успішне виконання комірок ноутбуків
• Зіставлення результатів з очікуваними у рішеннях

Рекомендації щодо стилю коду

Код на Python

• Дотримуйтесь стилю PEP 8
• Використовуйте зрозумілі, описові назви змінних
• Додавайте коментарі до складних операцій
• У Jupyter notebooks повинні бути markdown-комірки з поясненнями концепцій

JavaScript/Vue.js (додаток тестів)

• Дотримуйтесь стилю Vue.js
• Конфігурація ESLint у quiz-app/package.json
• Використовуйте npm run lint для перевірки та автоматичного виправлення проблем

Документація

• Markdown-файли повинні бути зрозумілими та добре структурованими
• Включайте приклади коду у блоки з огородженням
• Використовуйте відносні посилання для внутрішніх референсів
• Дотримуйтесь існуючих форматувальних конвенцій

Збірка та розгортання

Розгортання додатка тестів

Додаток тестів можна розгорнути на Azure Static Web Apps:

1. Попередні умови:

   • Обліковий запис Azure
   • Репозиторій GitHub (вже форкований)

2. Розгортання на Azure:

   • Створіть ресурс Azure Static Web App
   • Підключіть до репозиторію GitHub
   • Вкажіть розташування додатка: /quiz-app
   • Вкажіть розташування вихідних даних: dist
   • Azure автоматично створює GitHub Actions workflow

3. GitHub Actions Workflow:

   • Файл workflow створюється у .github/workflows/azure-static-web-apps-*.yml
   • Автоматично збирає та розгортає при пуші в основну гілку

PDF документація

Генерація PDF з документації:

npm install
npm run convert

Робочий процес перекладу

Важливо: Переклади автоматизовані через GitHub Actions за допомогою Co-op Translator.

• Переклади генеруються автоматично при внесенні змін у гілку main
• НЕ перекладайте контент вручну — система це робить автоматично
• Робочий процес визначений у .github/workflows/co-op-translator.yml
• Використовує сервіси Azure AI/OpenAI для перекладу
• Підтримує 40+ мов

Рекомендації для внесення змін

Для контентних авторів

1. Форкніть репозиторій і створіть гілку для змін
2. Внесіть зміни до контенту уроків, якщо додаєте/оновлюєте уроки
3. Не змінюйте перекладені файли — вони генеруються автоматично
4. Протестуйте ваш код — переконайтеся, що всі комірки ноутбуків виконуються успішно
5. Перевірте посилання та зображення на коректність
6. Надішліть pull request з чітким описом

Рекомендації для pull request

• Формат заголовка: [Розділ] Короткий опис змін
  • Приклад: [Regression] Виправлення помилки в уроці 5
  • Приклад: [Quiz-App] Оновлення залежностей
• Перед надсиланням:
  • Переконайтеся, що всі комірки ноутбуків виконуються без помилок
  • Виконайте npm run lint, якщо змінюєте додаток тестів
  • Перевірте форматування markdown
  • Протестуйте будь-які нові приклади коду
• PR повинен включати:
  • Опис змін
  • Причину змін
  • Скриншоти, якщо є зміни в UI
• Кодекс поведінки: Дотримуйтесь Microsoft Open Source Code of Conduct
• CLA: Вам потрібно буде підписати Contributor License Agreement

Структура уроку

Кожен урок має послідовну структуру:

1. Тест перед лекцією - Перевірка базових знань
2. Контент уроку - Письмові інструкції та пояснення
3. Демонстрація коду - Практичні приклади в ноутбуках
4. Перевірка знань - Перевірка розуміння протягом уроку
5. Завдання - Самостійне застосування концепцій
6. Домашнє завдання - Розширена практика
7. Тест після лекції - Оцінка результатів навчання

Довідник команд

# 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

Додаткові ресурси

• Колекція Microsoft Learn: Модулі ML для початківців
• Додаток тестів: Онлайн-тести
• Дошка обговорень: GitHub Discussions
• Відео-огляди: YouTube Playlist

Основні технології

• Python: Основна мова для уроків ML (Scikit-learn, Pandas, NumPy, Matplotlib)
• R: Альтернативна реалізація з використанням tidyverse, tidymodels, caret
• Jupyter: Інтерактивні ноутбуки для уроків на Python
• R Markdown: Документи для уроків на R
• Vue.js 3: Фреймворк для додатка тестів
• Flask: Фреймворк для веб-додатків для розгортання моделей ML
• Docsify: Генератор сайту документації
• GitHub Actions: CI/CD та автоматизовані переклади

Міркування щодо безпеки

• Ніяких секретів у коді: Ніколи не додавайте API-ключі або облікові дані
• Залежності: Оновлюйте пакети npm і pip
• Введення користувача: Приклади веб-додатків Flask включають базову перевірку введення
• Чутливі дані: Прикладові набори даних є публічними та не містять конфіденційної інформації

Вирішення проблем

Jupyter Notebooks

• Проблеми з ядром: Перезапустіть ядро, якщо комірки зависають: Kernel → Restart
• Помилки імпорту: Переконайтеся, що всі необхідні пакети встановлені через pip
• Проблеми з шляхами: Запускайте ноутбуки з їхньої папки

Додаток тестів

• npm install не працює: Очистіть кеш npm: npm cache clean --force
• Конфлікти портів: Змініть порт за допомогою: npm run serve -- --port 8081
• Помилки збірки: Видаліть node_modules і перевстановіть: rm -rf node_modules && npm install

Уроки на R

• Пакет не знайдено: Встановіть за допомогою: install.packages("package-name")
• Рендеринг RMarkdown: Переконайтеся, що пакет rmarkdown встановлений
• Проблеми з ядром: Можливо, потрібно встановити IRkernel для Jupyter

Примітки щодо проєкту

• Це переважно навчальна програма, а не код для продакшну
• Основна увага приділяється розумінню концепцій ML через практику
• Приклади коду пріоритетно зрозумілі, а не оптимізовані
• Більшість уроків самодостатні і можуть бути виконані незалежно
• Рішення надаються, але учні повинні спочатку спробувати виконати вправи
• Репозиторій використовує Docsify для веб-документації без етапу збірки
• Скетчноти забезпечують візуальні резюме концепцій
• Підтримка багатьох мов робить контент доступним глобально

---

Відмова від відповідальності:
Цей документ було перекладено за допомогою сервісу автоматичного перекладу Co-op Translator. Хоча ми прагнемо до точності, звертаємо вашу увагу, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ мовою оригіналу слід вважати авторитетним джерелом. Для отримання критично важливої інформації рекомендується професійний людський переклад. Ми не несемо відповідальності за будь-які непорозуміння або неправильні тлумачення, що виникли внаслідок використання цього перекладу.