|
|
# AGENTS.md
|
|
|
|
|
|
## 專案概述
|
|
|
|
|
|
這是 **機器學習初學者課程**，一個為期12週、共26課的完整課程，涵蓋使用 Python（主要使用 Scikit-learn）和 R 的經典機器學習概念。本儲存庫設計為自學資源，包含實作專案、測驗和作業。每節課透過來自世界各地不同文化和地區的真實數據探索機器學習概念。
|
|
|
|
|
|
主要內容：
|
|
|
- **教育內容**：26課涵蓋機器學習入門、回歸、分類、聚類、自然語言處理（NLP）、時間序列和強化學習
|
|
|
- **測驗應用程式**：基於 Vue.js 的測驗應用程式，提供課前和課後評估
|
|
|
- **多語言支持**：透過 GitHub Actions 自動翻譯至40多種語言
|
|
|
- **雙語支持**：課程提供 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` - Python Jupyter notebook
|
|
|
- `solution/` - 解答程式碼（Python 和 R 版本）
|
|
|
- `assignment.md` - 練習題
|
|
|
- `images/` - 視覺資源
|
|
|
|
|
|
## 設置指令
|
|
|
|
|
|
### Python 課程
|
|
|
|
|
|
大多數課程使用 Jupyter notebooks。安裝所需的依賴項：
|
|
|
|
|
|
```bash
|
|
|
# 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` 文件：
|
|
|
|
|
|
```bash
|
|
|
# Install R and required packages
|
|
|
# In R console:
|
|
|
install.packages(c("tidyverse", "tidymodels", "caret"))
|
|
|
```
|
|
|
|
|
|
### 測驗應用程式
|
|
|
|
|
|
測驗應用程式是一個位於 `quiz-app/` 資料夾中的 Vue.js 應用程式：
|
|
|
|
|
|
```bash
|
|
|
cd quiz-app
|
|
|
npm install
|
|
|
```
|
|
|
|
|
|
### 文件網站
|
|
|
|
|
|
本地運行文件網站：
|
|
|
|
|
|
```bash
|
|
|
# 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：
|
|
|
```bash
|
|
|
jupyter notebook notebook.ipynb
|
|
|
```
|
|
|
3. 完成課程內容和練習
|
|
|
4. 如有需要，可查看 `solution/` 資料夾中的解答
|
|
|
|
|
|
### Python 開發
|
|
|
|
|
|
- 課程使用標準的 Python 數據科學庫
|
|
|
- 使用 Jupyter notebooks 進行互動式學習
|
|
|
- 每個課程的 `solution/` 資料夾中提供解答程式碼
|
|
|
|
|
|
### R 開發
|
|
|
|
|
|
- R 課程以 `.rmd` 格式（R Markdown）提供
|
|
|
- 解答位於 `solution/R/` 子資料夾中
|
|
|
- 使用 RStudio 或帶有 R kernel 的 Jupyter 運行 R notebooks
|
|
|
|
|
|
### 測驗應用程式開發
|
|
|
|
|
|
```bash
|
|
|
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
|
|
|
```
|
|
|
|
|
|
## 測試說明
|
|
|
|
|
|
### 測驗應用程式測試
|
|
|
|
|
|
```bash
|
|
|
cd quiz-app
|
|
|
|
|
|
# Lint code
|
|
|
npm run lint
|
|
|
|
|
|
# Build to verify no errors
|
|
|
npm run build
|
|
|
```
|
|
|
|
|
|
**注意**：這主要是一個教育課程儲存庫，課程內容沒有自動化測試。驗證方式包括：
|
|
|
- 完成課程練習
|
|
|
- 成功運行 notebook 的每個單元格
|
|
|
- 將輸出與解答中的預期結果進行比對
|
|
|
|
|
|
## 程式碼風格指南
|
|
|
|
|
|
### Python 程式碼
|
|
|
- 遵循 PEP 8 風格指南
|
|
|
- 使用清晰、描述性的變數名稱
|
|
|
- 對複雜操作添加註解
|
|
|
- Jupyter notebooks 應包含解釋概念的 markdown 單元格
|
|
|
|
|
|
### JavaScript/Vue.js（測驗應用程式）
|
|
|
- 遵循 Vue.js 風格指南
|
|
|
- ESLint 配置位於 `quiz-app/package.json`
|
|
|
- 運行 `npm run lint` 檢查並自動修復問題
|
|
|
|
|
|
### 文件
|
|
|
- Markdown 文件應清晰且結構良好
|
|
|
- 在圍欄代碼塊中包含代碼示例
|
|
|
- 使用相對鏈接進行內部引用
|
|
|
- 遵循現有的格式約定
|
|
|
|
|
|
## 構建與部署
|
|
|
|
|
|
### 測驗應用程式部署
|
|
|
|
|
|
測驗應用程式可部署至 Azure 靜態網頁應用程式：
|
|
|
|
|
|
1. **先決條件**：
|
|
|
- Azure 帳戶
|
|
|
- GitHub 儲存庫（已分叉）
|
|
|
|
|
|
2. **部署至 Azure**：
|
|
|
- 創建 Azure 靜態網頁應用程式資源
|
|
|
- 連接至 GitHub 儲存庫
|
|
|
- 設置應用程式位置：`/quiz-app`
|
|
|
- 設置輸出位置：`dist`
|
|
|
- Azure 自動創建 GitHub Actions 工作流程
|
|
|
|
|
|
3. **GitHub Actions 工作流程**：
|
|
|
- 工作流程文件創建於 `.github/workflows/azure-static-web-apps-*.yml`
|
|
|
- 推送至主分支時自動構建和部署
|
|
|
|
|
|
### 文件 PDF
|
|
|
|
|
|
從文件生成 PDF：
|
|
|
|
|
|
```bash
|
|
|
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. **測試您的程式碼** - 確保所有 notebook 單元格成功運行
|
|
|
5. **驗證鏈接和圖片**是否正常工作
|
|
|
6. **提交拉取請求**並提供清晰的描述
|
|
|
|
|
|
### 拉取請求指南
|
|
|
|
|
|
- **標題格式**：`[章節] 簡要描述更改`
|
|
|
- 示例：`[回歸] 修正第5課中的拼寫錯誤`
|
|
|
- 示例：`[測驗應用程式] 更新依賴項`
|
|
|
- **提交前**：
|
|
|
- 確保所有 notebook 單元格無錯誤執行
|
|
|
- 如果修改測驗應用程式，運行 `npm run lint`
|
|
|
- 驗證 Markdown 格式
|
|
|
- 測試任何新的代碼示例
|
|
|
- **拉取請求必須包含**：
|
|
|
- 更改描述
|
|
|
- 更改原因
|
|
|
- 如果有 UI 更改，提供截圖
|
|
|
- **行為準則**：遵循 [Microsoft 開源行為準則](CODE_OF_CONDUCT.md)
|
|
|
- **CLA**：您需要簽署貢獻者許可協議
|
|
|
|
|
|
## 課程結構
|
|
|
|
|
|
每節課遵循一致的模式：
|
|
|
|
|
|
1. **課前測驗** - 測試基礎知識
|
|
|
2. **課程內容** - 書面指導和解釋
|
|
|
3. **代碼演示** - notebook 中的實作示例
|
|
|
4. **知識檢查** - 驗證學習進度
|
|
|
5. **挑戰** - 獨立應用概念
|
|
|
6. **作業** - 延伸練習
|
|
|
7. **課後測驗** - 評估學習成果
|
|
|
|
|
|
## 常用指令參考
|
|
|
|
|
|
```bash
|
|
|
# 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 集合**：[機器學習初學者模組](https://learn.microsoft.com/en-us/collections/qrqzamz1nn2wx3?WT.mc_id=academic-77952-bethanycheum)
|
|
|
- **測驗應用程式**：[線上測驗](https://ff-quizzes.netlify.app/en/ml/)
|
|
|
- **討論板**：[GitHub 討論](https://github.com/microsoft/ML-For-Beginners/discussions)
|
|
|
- **視頻講解**：[YouTube 播放列表](https://aka.ms/ml-beginners-videos)
|
|
|
|
|
|
## 關鍵技術
|
|
|
|
|
|
- **Python**：機器學習課程的主要語言（Scikit-learn、Pandas、NumPy、Matplotlib）
|
|
|
- **R**：使用 tidyverse、tidymodels、caret 的替代實現
|
|
|
- **Jupyter**：Python 課程的互動式筆記本
|
|
|
- **R Markdown**：R 課程的文件格式
|
|
|
- **Vue.js 3**：測驗應用程式框架
|
|
|
- **Flask**：機器學習模型部署的網頁應用框架
|
|
|
- **Docsify**：文件網站生成器
|
|
|
- **GitHub Actions**：CI/CD 和自動翻譯
|
|
|
|
|
|
## 安全考量
|
|
|
|
|
|
- **代碼中不包含秘密**：切勿提交 API 密鑰或憑證
|
|
|
- **依賴項**：保持 npm 和 pip 套件更新
|
|
|
- **用戶輸入**：Flask 網頁應用示例包含基本輸入驗證
|
|
|
- **敏感數據**：示例數據集是公開且非敏感的
|
|
|
|
|
|
## 疑難排解
|
|
|
|
|
|
### Jupyter Notebooks
|
|
|
|
|
|
- **內核問題**：如果單元格掛起，重啟內核：Kernel → Restart
|
|
|
- **導入錯誤**：確保使用 pip 安裝所有所需套件
|
|
|
- **路徑問題**：從包含 notebook 的目錄運行
|
|
|
|
|
|
### 測驗應用程式
|
|
|
|
|
|
- **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 套件
|
|
|
- **內核問題**：可能需要為 Jupyter 安裝 IRkernel
|
|
|
|
|
|
## 專案特定注意事項
|
|
|
|
|
|
- 這主要是一個 **學習課程**，而非生產代碼
|
|
|
- 重點在於透過 **實作練習理解機器學習概念**
|
|
|
- 代碼示例以 **清晰性優先於優化**
|
|
|
- 大多數課程是 **自包含的**，可獨立完成
|
|
|
- **提供解答**，但學習者應先嘗試完成練習
|
|
|
- 儲存庫使用 **Docsify** 生成網頁文件，無需構建步驟
|
|
|
- **手繪筆記**提供概念的視覺摘要
|
|
|
- **多語言支持**使內容全球可訪問
|
|
|
|
|
|
---
|
|
|
|
|
|
**免責聲明**：
|
|
|
本文件已使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。儘管我們致力於提供準確的翻譯，請注意自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於關鍵資訊，建議使用專業人工翻譯。我們對因使用此翻譯而引起的任何誤解或誤釋不承擔責任。 |
