10 KiB

Raw Blame History Unescape Escape

AGENTS.md

项目概述

这是机器学习入门，一个全面的12周、26课的课程体系，涵盖使用Python（主要是Scikit-learn）和R的经典机器学习概念。该仓库设计为一个自学资源，包含实践项目、测验和作业。每节课通过来自世界各地不同文化和地区的真实数据探索机器学习概念。

关键组成部分：

教育内容：26节课，涵盖机器学习简介、回归、分类、聚类、自然语言处理（NLP）、时间序列和强化学习
测验应用：基于Vue.js的测验应用，提供课前和课后评估
多语言支持：通过GitHub Actions自动翻译成40多种语言
双语言支持：课程内容同时提供Python（Jupyter笔记本）和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笔记本
solution/ - 解决方案代码（Python和R版本）
assignment.md - 练习题
images/ - 可视化资源

设置命令

针对Python课程

大多数课程使用Jupyter笔记本。安装所需依赖项：

# 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"))

针对测验应用

测验应用是一个位于quiz-app/目录中的Vue.js应用：

cd quiz-app
npm install

针对文档站点

本地运行文档：

# Install Docsify
npm install -g docsify-cli

# Serve from repository root
docsify serve

# Access at http://localhost:3000

开发工作流程

使用课程笔记本

进入课程目录（例如，2-Regression/1-Tools/）
打开Jupyter笔记本：
```
jupyter notebook notebook.ipynb
```
学习课程内容并完成练习
如有需要，可查看solution/文件夹中的解决方案

Python开发

课程使用标准的Python数据科学库
Jupyter笔记本用于交互式学习
每节课的solution/文件夹中提供解决方案代码

R开发

R课程以.rmd格式（R Markdown）提供
解决方案位于solution/R/子目录中
使用RStudio或带有R内核的Jupyter运行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笔记本应包含解释概念的Markdown单元格

JavaScript/Vue.js（测验应用）

遵循Vue.js风格指南
ESLint配置位于quiz-app/package.json
运行npm run lint检查并自动修复问题

文档

Markdown文件应清晰且结构良好
在代码块中包含代码示例
内部引用使用相对链接
遵循现有的格式约定

构建与部署

测验应用部署

测验应用可以部署到Azure静态Web应用：

先决条件：
- Azure账户
- GitHub仓库（已分叉）
部署到Azure：
- 创建Azure静态Web应用资源
- 连接到GitHub仓库
- 设置应用位置：/quiz-app
- 设置输出位置：dist
- Azure会自动创建GitHub Actions工作流
GitHub Actions工作流：
- 工作流文件创建于.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多种语言

贡献指南

针对内容贡献者

分叉仓库并创建一个功能分支
修改课程内容以添加或更新课程
不要修改翻译文件 - 它们是自动生成的
测试代码 - 确保所有笔记本单元格成功运行
验证链接和图片是否正常工作
提交拉取请求并提供清晰的描述

拉取请求指南

标题格式：[部分] 简要描述更改
- 示例：[回归] 修复第5课中的拼写错误
- 示例：[测验应用] 更新依赖项
提交前：
- 确保所有笔记本单元格无错误执行
- 如果修改了测验应用，运行npm run lint
- 验证Markdown格式
- 测试任何新的代码示例
拉取请求必须包括：
- 更改描述
- 更改原因
- 如果有UI更改，提供截图
行为准则：遵循Microsoft开源行为准则
CLA：需要签署贡献者许可协议

课程结构

每节课遵循一致的模式：

课前测验 - 测试基础知识
课程内容 - 书面说明和解释
代码演示 - 笔记本中的实践示例
知识检查 - 验证学习理解
挑战 - 独立应用概念
作业 - 扩展练习
课后测验 - 评估学习成果

常用命令参考

# 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集合：机器学习入门模块
测验应用：在线测验
讨论板：GitHub Discussions
视频讲解：YouTube播放列表

关键技术

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笔记本

内核问题：如果单元格挂起，请重启内核：内核 → 重启
导入错误：确保使用pip安装了所有必需的包
路径问题：从笔记本所在目录运行笔记本

测验应用

npm安装失败：清除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文档，无需构建步骤
手绘笔记提供概念的可视化总结
多语言支持使内容全球可访问

免责声明：
本文档使用AI翻译服务 Co-op Translator 进行翻译。尽管我们努力确保翻译的准确性，但请注意，自动翻译可能包含错误或不准确之处。原始语言的文档应被视为权威来源。对于关键信息，建议使用专业人工翻译。我们对因使用此翻译而产生的任何误解或误读不承担责任。

10 KiB Raw Blame History Unescape Escape