|
|
<!--
|
|
|
CO_OP_TRANSLATOR_METADATA:
|
|
|
{
|
|
|
"original_hash": "93fdaa0fd38836e50c4793e2f2f25e8b",
|
|
|
"translation_date": "2025-10-03T11:00:52+00:00",
|
|
|
"source_file": "AGENTS.md",
|
|
|
"language_code": "hk"
|
|
|
}
|
|
|
-->
|
|
|
# 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 靜態 Web 應用：
|
|
|
|
|
|
1. **先決條件**：
|
|
|
- Azure 帳戶
|
|
|
- GitHub 倉庫（已經 fork）
|
|
|
|
|
|
2. **部署到 Azure**：
|
|
|
- 創建 Azure 靜態 Web 應用資源
|
|
|
- 連接到 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. **Fork 倉庫**並創建功能分支
|
|
|
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 Discussions](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**：機器學習模型部署的 Web 應用框架
|
|
|
- **Docsify**：文檔網站生成器
|
|
|
- **GitHub Actions**：CI/CD 和自動翻譯
|
|
|
|
|
|
## 安全考量
|
|
|
|
|
|
- **代碼中不包含秘密信息**：切勿提交 API 密鑰或憑據
|
|
|
- **依賴項**：保持 npm 和 pip 包更新
|
|
|
- **用戶輸入**：Flask Web 應用示例包含基本輸入驗證
|
|
|
- **敏感數據**：示例數據集是公開且無敏感信息的
|
|
|
|
|
|
## 故障排除
|
|
|
|
|
|
### 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** 生成 Web 文檔，無需構建步驟
|
|
|
- **手繪筆記** 提供概念的視覺摘要
|
|
|
- **多語言支持** 使內容全球可訪問
|
|
|
|
|
|
---
|
|
|
|
|
|
**免責聲明**：
|
|
|
本文件已使用人工智能翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。儘管我們致力於提供準確的翻譯，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要信息，建議使用專業人工翻譯。我們對因使用此翻譯而引起的任何誤解或錯誤解釋概不負責。 |
