AI for Beginners 完整环境搭建与开发工作流指南:从 conda 到 Jupyter、Quiz 应用与 Azure 部署

原创2026-09-30 23:38:402,597 阅读
文章标签:人工智能机器学习深度学习教程教育示例工程计算机视觉NLP强化学习

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 会自动识别并采用 ai4beg conda 环境
  • 直接双击打开 .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+ 组测验。

测试与验证:教育仓库的"质量关卡"

这是一个以教学内容为主的仓库,不存在传统意义的单元测试套件,其质量保障方式分为四类:

  1. Notebook 验证:按顺序执行各单元格,确认代码示例可运行
  2. 测验应用测试:通过开发服务器进行手工测试
  3. 翻译校验:检查 translations/ 目录下的多语言内容
  4. 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 流程

  1. 标题格式:使用清晰、描述性的标题说明改动
  2. CLA 要求:必须签署 Microsoft CLA(自动化检查)
  3. 内容准则:保持教育导向与初学者友好风格;测试 Notebook 中所有代码示例;确保 Notebook 可端到端运行;若修改英文内容需同步更新翻译
  4. 测验应用改动:提交前先运行 npm run lint

翻译贡献

  • 翻译由 GitHub Actions + co-op-translator 自动化完成
  • 手工翻译内容放入 translations/<language-code>/
  • 测验翻译位于 etc/quiz-app/src/assets/translations/
  • 支持 40+ 种语言(完整列表见仓库根 README.md)

当前活跃的贡献方向

详见 etc/CONTRIBUTING.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/ 实现多语言协作。无论你是学习者、讲师还是翻译贡献者,本文给出的命令、路径与排查思路均可直接落地使用——所有引用文件均可在当前仓库中直接打开验证。

登录后查看全文
AI-For-Beginners