AI for Beginners 完整环境搭建与开发工作流指南:从 conda 到 Jupyter、Quiz 应用与 Azure 部署
AI for Beginners 完整环境搭建与开发工作流指南:从 conda 到 Jupyter、Quiz 应用与 Azure 部署
本文是一份围绕 AI-For-Beginners 开源课程仓库的环境搭建与开发运维手册,系统覆盖课程项目(12 周 / 24 课时)的本地与云端运行方式、Jupyter Notebooks 的三种开发工作流、GPU 加速配置、Vue.js 测验应用(quiz-app)的构建与部署、代码风格约定、依赖版本清单以及常见故障排除方案。读完本文,你将能够从零克隆仓库、创建可复现的 ai4beg 学习环境,并在本地、Codespaces、Binder 或 Azure 上稳定运行课程代码。
项目概览:一个面向所有人的 12 周 AI 课程仓库
AI for Beginners 是一个教育型内容仓库(非传统软件项目),核心交付物是 24 节循序渐进的教学课程,配套 Jupyter Notebooks、课前/课后测验(quiz)和动手实验(lab)。课程知识面覆盖:
- 符号 AI(Symbolic AI):知识表示(Knowledge Representation)与专家系统(Expert Systems)
- 神经网络与深度学习:基于 TensorFlow 和 PyTorch 两个主流框架的双轨实现
- 计算机视觉(Computer Vision):卷积网络、迁移学习、目标检测、图像分割等技术
- 自然语言处理(NLP):词向量、RNN、Transformer 与 BERT
- 专题方向:遗传算法、强化学习(Reinforcement Learning)、多智能体系统(Multi-Agent Systems)
- AI 伦理与负责任 AI 原则
关键技术栈:Python 3、Jupyter Notebooks、TensorFlow、PyTorch、Keras、OpenCV,以及用于测验应用的 Vue.js。
架构形态:内容按主题目录组织(见 lessons/),辅以一个基于 Vue.js 的测验应用(etc/quiz-app/)和覆盖 40+ 语言的多语言翻译支持(translations/)。这一结构在 AGENTS.md 项目概览一节有明确描述,并在仓库目录树中得到完全印证。
环境搭建:两套官方方案
方案一:miniconda(推荐主路径)
课程代码设计为在 Python + Jupyter Notebooks 中运行,官方推荐使用 miniconda 管理依赖:
# 克隆仓库
git clone https://github.com/microsoft/ai-for-beginners
cd ai-for-beginners
# 创建并激活 conda 环境
conda env create --name ai4beg --file environment.yml
conda activate ai4beg
# 启动 Jupyter Notebook
jupyter notebook
# 或启动 Jupyter Lab
jupyter lab
environment.yml 位于仓库根目录,它定义了 ai4beg 环境的完整依赖矩阵,其中核心内容包括:
- 交互组件:
ipykernel、ipython、ipywidgets、jupyter - 科学计算:
matplotlib=3.9、numpy=1.26、scipy=1.13、scikit-learn、pandas - 计算机视觉:
conda-forge::opencv - 深度学习框架:
pytorch::pytorch、pytorch::torchtext、pytorch::torchvision、pytorch::torchdata - 其余 Python 包:通过 pip 段落自动安装根目录 requirements.txt 中列出的全部内容
值得强调的是,environment.yml 中 pip 一节会执行 -r requirements.txt,也就是说conda 与 pip 两套依赖会一次到位。运行 conda env create 时务必确保有足够的磁盘空间(官方建议 50GB),因为 TensorFlow/PyTorch 及 CUDA 相关组件体积较大。
方案二:devcontainer(VS Code 容器化开发)
仓库同样支持 devcontainer 方式,适合希望隔离环境、避免污染本机的开发者:
# 在 VS Code 中打开仓库,按提示选择 "Reopen in Container"
# devcontainer 会自动完成环境初始化
测验应用的独立环境
测验应用是一个独立的 Vue.js 前端项目,位于 etc/quiz-app,需要 Node.js/npm 环境:
cd etc/quiz-app
npm install
npm run serve # 开发服务器
npm run build # 生产构建
npm run lint # 代码检查并自动修复
从 etc/quiz-app/package.json 可以看到其技术底座:vue@2.6.x(Vue 2.x 约定)、vue-i18n(多语言国际化)、vue-router,以及基于 @vue/cli-service 的 serve/build/lint 三个脚本命令。
开发工作流:三种运行 Jupyter 的方式
1. 本地开发
conda activate ai4beg
jupyter notebook # 或 jupyter lab
激活环境后,导航到 lessons/ 下对应的课程目录,打开 .ipynb 文件,按单元格顺序交互式执行,即可跟随课程进度。课程设计的核心原则是单元格尽量自包含,方便按顺序逐步运行。
2. VS Code + Python 扩展
- 用 VS Code 打开仓库
- 安装 Python 扩展
- VS Code 会自动识别并采用
ai4begconda 环境 - 直接双击打开
.ipynb文件即可在 VS Code 内部执行单元格
这种方式将 Notebook 的交互体验与 VS Code 的调试、智能提示能力结合,是日常迭代课程实验的高效路径。
3. 云端开发
- GitHub Codespaces:点击仓库的 "Code" → "Codespaces" → "Create codespace on main",即可获得浏览器内的 VS Code 云端环境
- Binder:通过 README 中的 Binder 徽章在浏览器中启动 Jupyter。注意 Binder 资源受限,且有部分网络访问限制(部分下载数据集的操作可能被阻断)
GPU 支持:进阶课程的加速前提
课程后半段的计算机视觉(CNN、GAN)、NLP 等课程对 GPU 有显著收益,官方给出了三种 GPU 运行途径:
- Azure Data Science VM:选用带 GPU 的 NC 系列虚拟机
- Azure Machine Learning:使用其 Notebook 功能 + GPU 计算实例
- Google Colab:单独上传 notebook,提供免费 GPU 额度
GPU 环境的可用性验证可参考下文"故障排除"中的检测命令。
测验应用(Quiz App)的开发与部署
本地开发
cd etc/quiz-app
npm run serve # 热重载开发服务器,默认 http://localhost:8080
生产构建与 Azure 部署
cd etc/quiz-app
npm run build # 输出到 etc/quiz-app/dist/
测验应用可部署到 Azure Static Web Apps,部署时 Azure 会在你的 GitHub 仓库自动创建 GitHub Actions 工作流(.github/workflows/azure-static-web-apps-<name>.yml),自动完成构建与发布。详细步骤见 etc/quiz-app/README.md,其工作流核心配置大致如下:
name: Azure Static Web Apps CI/CD
on:
push:
branches: [main]
pull_request:
types: [opened, synchronize, reopened, closed]
branches: [main]
jobs:
build_and_deploy_job:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- id: builddeploy
uses: Azure/static-web-apps-deploy@v1
with:
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
repo_token: ${{ secrets.GITHUB_TOKEN }}
action: "upload"
app_location: "etc/quiz-app" # 应用源码路径
output_location: "dist" # 构建产物目录
其中 AZURE_STATIC_WEB_APPS_API_TOKEN 由 Azure 在创建资源时自动注入为仓库 Secret,无需手动配置。
测验翻译的维护约定
测验内容按课时分组存放在 etc/quiz-app/src/assets/translations/ 下,英文版本为权威基准。若要新增一门语言的测验,需要同步修改该目录下的 index.js 导入、App.vue 中的语言下拉选项,并确保课程内测验链接带上 ?loc=<语言代码> 查询参数。课程中共有 40+ 组测验。
测试与验证:教育仓库的"质量关卡"
这是一个以教学内容为主的仓库,不存在传统意义的单元测试套件,其质量保障方式分为四类:
- Notebook 验证:按顺序执行各单元格,确认代码示例可运行
- 测验应用测试:通过开发服务器进行手工测试
- 翻译校验:检查
translations/目录下的多语言内容 - Lint 检查:在
etc/quiz-app/下运行npm run lint
运行代码示例的标准姿势:
# 先激活环境
conda activate ai4beg
# 直接运行 Python 脚本
python lessons/4-ComputerVision/07-ConvNets/pytorchcv.py
# 或以 Notebook 方式执行
jupyter notebook lessons/3-NeuralNetworks/03-Perceptron/Perceptron.ipynb
上面两个示例路径均为仓库中真实存在的文件,可作为你验证环境的"冒烟测试"入口。
代码风格与文件组织
Python 代码约定
- 遵循标准 Python 教育代码约定
- 代码以可读性优先、学习优先于优化
- 关键概念要求添加注释
- 面向 Jupyter:单元格尽量自包含
- 课程内容无强制 lint 要求
JavaScript / Vue.js(测验应用)
- ESLint 配置位于
etc/quiz-app/package.json(extends: plugin:vue/essential + eslint:recommended) - 提交前运行
npm run lint自动检查与修复 - 遵循 Vue 2.x 约定,采用基于组件的架构
仓库目录结构
lessons/
├── 0-course-setup/ # 课程准备说明
├── 1-Intro/ # AI 导论
├── 2-Symbolic/ # 符号 AI
├── 3-NeuralNetworks/ # 神经网络基础
├── 4-ComputerVision/ # 计算机视觉
├── 5-NLP/ # 自然语言处理
├── 6-Other/ # 其他 AI 技术
├── 7-Ethics/ # AI 伦理
└── X-Extras/ # 扩展内容
etc/
├── quiz-app/ # Vue.js 测验应用
└── quiz-src/ # 测验源文件
translations/ # 多语言翻译
构建与部署:Jupyter 与文档站点
Jupyter 内容:无需构建
Jupyter Notebooks 直接执行,不存在构建环节。
文档站点:Docsify
仓库使用 Docsify 作为文档入口(根目录 index.html 配置了 docsify-themeable 主题与 relativePath: true),无需构建,可直接通过 GitHub Pages 静态托管。也可以本地离线阅读:在仓库根目录执行 docsify serve,站点会运行于 localhost:3000。完整的 PDF 版课程大纲位于 etc/pdf/readme.pdf。
环境配置与依赖版本
核心依赖清单
课程依赖可分为 conda 层(深度学习框架与图像库)与 pip 层(NLP、强化学习等专项库),完整清单见根目录 environment.yml 与 requirements.txt。其中关键版本包括:
| 依赖 | 版本 | 来源 |
|---|---|---|
| tensorflow | 2.17.0 | requirements.txt |
| keras | 3.13.2 | requirements.txt |
| torch / torchvision / torchdata | conda 安装 | environment.yml |
| numpy | 1.26 | environment.yml |
| matplotlib | 3.9 | environment.yml |
| pandas | 2.2.2 | requirements.txt |
| opencv | conda-forge 渠道 | environment.yml |
| gensim | 4.3.3 | requirements.txt |
| gym | 0.26.2 | requirements.txt |
| nltk | 3.10.0 | requirements.txt |
| scikit-learn | conda 安装 | environment.yml |
| jupyter | conda 安装 | environment.yml |
注意:历史版本文档中列出的部分版本(如 keras 3.5.0)与当前仓库实际锁定版本存在细微出入,请以仓库根目录 requirements.txt 与 environment.yml 中的实际内容为准。
另外,binder/requirements.txt 提供了 Binder 场景下的独立依赖清单(TensorFlow 2.13、transformers 5.5.0 等),配合 binder/postBuild.sh 在 Binder 构建阶段完成环境准备,两套依赖清单互不干扰。
环境变量
- 基础使用无需任何特殊环境变量
- Azure 部署(测验应用)时会用到
AZURE_STATIC_WEB_APPS_API_TOKEN,由 Azure 自动注入
故障排除:常见问题速查
问题:conda 环境创建失败
- 先更新 conda:
conda update conda -y - 确认磁盘空间充足(建议 50GB)
问题:Jupyter 找不到内核
conda activate ai4beg
python -m ipykernel install --user --name ai4beg
问题:Notebook 中检测不到 GPU
- 检查 CUDA 安装:
nvidia-smi - 检查 PyTorch GPU:
python -c "import torch; print(torch.cuda.is_available())" - 检查 TensorFlow GPU:
python -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"
问题:测验应用无法启动
cd etc/quiz-app
rm -rf node_modules package-lock.json
npm install
npm run serve
问题:Binder 超时或阻断下载
- Binder 免费但资源受限,建议改用 GitHub Codespaces 或本地环境,以获得更稳定的资源访问
内存与性能注意事项
- 部分课程(尤其 NLP Transformer 类)需要显著 RAM(建议 8GB+)
- 训练模型时关闭其他大型应用
- 内存不足时可在 Notebook 中调小 batch size
- 课程多处使用预训练模型以降低计算需求;从头训练虽教育意义强但耗时较长,迁移学习示例可显著缩短训练时间
贡献指南:PR 流程与翻译协作
Pull Request 流程
- 标题格式:使用清晰、描述性的标题说明改动
- CLA 要求:必须签署 Microsoft CLA(自动化检查)
- 内容准则:保持教育导向与初学者友好风格;测试 Notebook 中所有代码示例;确保 Notebook 可端到端运行;若修改英文内容需同步更新翻译
- 测验应用改动:提交前先运行
npm run lint
翻译贡献
- 翻译由 GitHub Actions + co-op-translator 自动化完成
- 手工翻译内容放入
translations/<language-code>/ - 测验翻译位于
etc/quiz-app/src/assets/translations/ - 支持 40+ 种语言(完整列表见仓库根 README.md)
当前活跃的贡献方向
- 深度强化学习章节
- 目标检测改进
- 命名实体识别(NER)示例
- 自定义嵌入(Embedding)训练样例
给教师与自学者的补充说明
- 教师参考 lessons/0-course-setup/for-teachers.md 获取教学建议;各课时自包含,可顺序讲授也可单独选用
- 课程设计节奏为 12 周、每周 2 课时
- 学生可参考 lessons/0-course-setup/how-to-run.md 了解运行代码的完整指引
- 代码执行方式五选一:本地(推荐)(完全控制、性能最佳、支持 GPU)、GitHub Codespaces(快速云端)、Binder(免费但受限)、Azure ML Notebooks(企业级 GPU 支持)、Google Colab(免费 GPU 额度)
结语
AI for Beginners 仓库将"教学内容 + 可执行代码 + 测验评估"三者打通,其环境工程面的核心要点在于:以 environment.yml 一键复现完整 Python 深度学习栈,以 etc/quiz-app 承载测验应用的前后端交付,以 translations/ 实现多语言协作。无论你是学习者、讲师还是翻译贡献者,本文给出的命令、路径与排查思路均可直接落地使用——所有引用文件均可在当前仓库中直接打开验证。