# AGENTS.md ## Przegląd projektu AI for Beginners to kompleksowy 12-tygodniowy, 24-lekcyjny program nauczania obejmujący podstawy sztucznej inteligencji. Repozytorium edukacyjne zawiera praktyczne lekcje z użyciem Jupyter Notebooks, quizy oraz laboratoria praktyczne. Program nauczania obejmuje: - Symboliczną AI z reprezentacją wiedzy i systemami ekspertowymi - Sieci neuronowe i głębokie uczenie z TensorFlow i PyTorch - Techniki i architektury widzenia komputerowego - Przetwarzanie języka naturalnego (NLP), w tym transformery i BERT - Tematy specjalistyczne: algorytmy genetyczne, uczenie ze wzmocnieniem, systemy wieloagentowe - Etyka AI i zasady odpowiedzialnej sztucznej inteligencji **Kluczowe technologie:** Python 3, Jupyter Notebooks, TensorFlow, PyTorch, Keras, OpenCV, Vue.js (dla aplikacji quizowej) **Architektura:** Repozytorium treści edukacyjnych z Jupyter Notebooks zorganizowane według obszarów tematycznych, uzupełnione aplikacją quizową opartą na Vue.js oraz szerokim wsparciem wielojęzycznym. ## Polecenia konfiguracji ### Podstawowe środowisko programistyczne (Python/Jupyter) Program nauczania jest zaprojektowany do uruchamiania z Pythonem i Jupyter Notebooks. Zalecanym podejściem jest użycie 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 ``` ### Alternatywa: Użycie devcontainer ```bash # Open in VS Code and select "Reopen in Container" when prompted # The devcontainer will automatically set up the environment ``` ### Konfiguracja aplikacji quizowej Aplikacja quizowa to oddzielna aplikacja Vue.js znajdująca się w `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 ``` ## Przepływ pracy programistycznej ### Praca z Jupyter Notebooks 1. **Rozwój lokalny:** - Aktywuj środowisko conda: `conda activate ai4beg` - Uruchom Jupyter: `jupyter notebook` lub `jupyter lab` - Przejdź do folderów lekcji i otwórz pliki `.ipynb` - Uruchamiaj komórki interaktywnie, aby śledzić lekcje 2. **VS Code z rozszerzeniem Python:** - Otwórz repozytorium w VS Code - Zainstaluj rozszerzenie Python - VS Code automatycznie wykrywa i używa środowiska conda - Otwórz pliki `.ipynb` bezpośrednio w VS Code 3. **Rozwój w chmurze:** - **GitHub Codespaces:** Kliknij "Code" → "Codespaces" → "Create codespace on main" - **Binder:** Użyj odznaki Binder na README, aby uruchomić w przeglądarce - Uwaga: Binder ma ograniczone zasoby i pewne ograniczenia dostępu do sieci ### Wsparcie GPU dla zaawansowanych lekcji Późniejsze lekcje znacznie korzystają z przyspieszenia GPU: - **Azure Data Science VM:** Użyj maszyn NC-series z obsługą GPU - **Azure Machine Learning:** Użyj funkcji notebooków z obliczeniami GPU - **Google Colab:** Prześlij notatniki indywidualnie (dostępne darmowe wsparcie GPU) ### Rozwój aplikacji quizowej ```bash cd etc/quiz-app npm run serve # Hot-reload development server at http://localhost:8080 ``` ## Instrukcje testowania To repozytorium edukacyjne skupia się na treściach edukacyjnych, a nie na testowaniu oprogramowania. Nie ma tradycyjnego zestawu testów. ### Podejścia do walidacji: 1. **Jupyter Notebooks:** Uruchamiaj komórki sekwencyjnie, aby zweryfikować działanie przykładów kodu 2. **Testowanie aplikacji quizowej:** Testowanie ręczne za pomocą serwera deweloperskiego 3. **Walidacja tłumaczeń:** Sprawdź przetłumaczone treści w folderze `translations/` 4. **Linting aplikacji quizowej:** `npm run lint` w `etc/quiz-app/` ### Uruchamianie przykładów kodu: ```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 ``` ## Styl kodu ### Styl kodu Python - Standardowe konwencje Pythona dla kodu edukacyjnego - Jasny, czytelny kod, priorytetem jest nauka, a nie optymalizacja - Komentarze wyjaśniające kluczowe koncepcje - Przyjazne dla Jupyter Notebook: komórki powinny być możliwie samodzielne - Brak rygorystycznych wymagań lintingu dla treści lekcji ### JavaScript/Vue.js (aplikacja quizowa) - Konfiguracja ESLint w `etc/quiz-app/package.json` - Uruchom `npm run lint`, aby sprawdzić i automatycznie naprawić problemy - Konwencje Vue 2.x - Architektura oparta na komponentach ### Organizacja plików ``` 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 ``` ## Budowa i wdrożenie ### Treści Jupyter Nie wymaga procesu budowy - Jupyter Notebooks są uruchamiane bezpośrednio. ### Aplikacja quizowa ```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 ``` ### Strona dokumentacji Repozytorium używa Docsify do dokumentacji: - `index.html` służy jako punkt wejścia - Nie wymaga budowy - serwowane bezpośrednio przez GitHub Pages - Dostęp pod adresem: https://microsoft.github.io/AI-For-Beginners/ ## Wytyczne dotyczące wkładu ### Proces Pull Request 1. **Format tytułu:** Jasne, opisowe tytuły opisujące zmiany 2. **Wymóg CLA:** Microsoft CLA musi być podpisany (automatyczna kontrola) 3. **Wytyczne dotyczące treści:** - Zachowaj edukacyjny charakter i podejście przyjazne dla początkujących - Przetestuj wszystkie przykłady kodu w notatnikach - Upewnij się, że notatniki działają od początku do końca - Zaktualizuj tłumaczenia, jeśli zmieniasz treści w języku angielskim 4. **Zmiany w aplikacji quizowej:** Uruchom `npm run lint` przed zatwierdzeniem ### Wkład w tłumaczenia - Tłumaczenia są automatyzowane za pomocą GitHub Actions z użyciem co-op-translator - Ręczne tłumaczenia trafiają do `translations//` - Tłumaczenia quizów w `etc/quiz-app/src/assets/translations/` - Obsługiwane języki: ponad 40 języków (zobacz README dla pełnej listy) ### Aktywne obszary wkładu Zobacz `etc/CONTRIBUTING.md` dla aktualnych potrzeb: - Sekcje dotyczące głębokiego uczenia ze wzmocnieniem - Ulepszenia wykrywania obiektów - Przykłady rozpoznawania nazwanych jednostek - Próbki treningowe niestandardowych osadzeń ## Konfiguracja środowiska ### Wymagane zależności ```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 ``` ### Zmienne środowiskowe Nie są wymagane specjalne zmienne środowiskowe dla podstawowego użytkowania. Dla wdrożeń Azure (aplikacja quizowa): - `AZURE_STATIC_WEB_APPS_API_TOKEN` (ustawiane automatycznie przez Azure) ## Debugowanie i rozwiązywanie problemów ### Typowe problemy **Problem:** Tworzenie środowiska conda nie powiodło się - **Rozwiązanie:** Najpierw zaktualizuj conda: `conda update conda -y` - Upewnij się, że masz wystarczającą ilość miejsca na dysku (zalecane 50GB) **Problem:** Nie znaleziono jądra Jupyter - **Rozwiązanie:** ```bash conda activate ai4beg python -m ipykernel install --user --name ai4beg ``` **Problem:** GPU nie jest wykrywane w notatnikach - **Rozwiązanie:** - Zweryfikuj instalację CUDA: `nvidia-smi` - Sprawdź GPU w PyTorch: `python -c "import torch; print(torch.cuda.is_available())"` - Sprawdź GPU w TensorFlow: `python -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"` **Problem:** Aplikacja quizowa nie uruchamia się - **Rozwiązanie:** ```bash cd etc/quiz-app rm -rf node_modules package-lock.json npm install npm run serve ``` **Problem:** Binder przekracza limit czasu lub blokuje pobieranie - **Rozwiązanie:** Użyj GitHub Codespaces lub lokalnej konfiguracji dla lepszego dostępu do zasobów ### Problemy z pamięcią Niektóre lekcje wymagają znacznej ilości RAM (zalecane 8GB+): - Użyj maszyn w chmurze dla lekcji wymagających dużych zasobów - Zamknij inne aplikacje podczas trenowania modeli - Zmniejsz rozmiary partii w notatnikach, jeśli brakuje pamięci ## Dodatkowe uwagi ### Dla instruktorów kursu - Zobacz `lessons/0-course-setup/for-teachers.md` dla wskazówek dotyczących nauczania - Lekcje są samodzielne i mogą być prowadzone w kolejności lub wybierane indywidualnie - Szacowany czas: 12 tygodni przy 2 lekcjach tygodniowo ### Zasoby w chmurze - **Azure dla studentów:** Dostępne darmowe kredyty dla studentów - **Microsoft Learn:** Dodatkowe ścieżki edukacyjne powiązane w całym kursie - **Binder:** Darmowe, ale ograniczone zasoby i pewne ograniczenia sieciowe ### Opcje uruchamiania kodu 1. **Lokalnie (zalecane):** Pełna kontrola, najlepsza wydajność, wsparcie GPU 2. **GitHub Codespaces:** Chmurowe VS Code, dobre do szybkiego dostępu 3. **Binder:** Jupyter w przeglądarce, darmowe, ale ograniczone 4. **Azure ML Notebooks:** Opcja korporacyjna z obsługą GPU 5. **Google Colab:** Prześlij notatniki indywidualnie, dostępny darmowy poziom GPU ### Praca z notatnikami - Notatniki są zaprojektowane do uruchamiania komórka po komórce w celu nauki - Wiele notatników pobiera zestawy danych przy pierwszym uruchomieniu (może to zająć trochę czasu) - Niektóre modele wymagają GPU dla rozsądnych czasów treningu - Modele wstępnie wytrenowane są używane tam, gdzie to możliwe, aby zmniejszyć wymagania obliczeniowe ### Rozważania dotyczące wydajności - Późniejsze lekcje dotyczące widzenia komputerowego (CNN, GAN) korzystają z GPU - Lekcje dotyczące transformatorów NLP mogą wymagać znacznej ilości RAM - Trenowanie od podstaw jest edukacyjne, ale czasochłonne - Przykłady transfer learningu minimalizują czas treningu --- **Zastrzeżenie**: Ten dokument został przetłumaczony za pomocą usługi tłumaczenia AI [Co-op Translator](https://github.com/Azure/co-op-translator). Chociaż dokładamy wszelkich starań, aby tłumaczenie było precyzyjne, prosimy pamiętać, że automatyczne tłumaczenia mogą zawierać błędy lub nieścisłości. Oryginalny dokument w jego języku źródłowym powinien być uznawany za autorytatywne źródło. W przypadku informacji o kluczowym znaczeniu zaleca się skorzystanie z profesjonalnego tłumaczenia przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z użycia tego tłumaczenia.