AI-For-Beginners 仓库开发与学习环境搭建全指南:conda 环境、Jupyter 工作流、测验应用部署与贡献实践

原创2026-10-01 12:43:311,661 阅读
文章标签:人工智能机器学习深度学习教程教育示例工程计算机视觉NLP强化学习

AI-For-Beginners 仓库开发与学习环境搭建全指南:conda 环境、Jupyter 工作流、测验应用部署与贡献实践

AI-For-Beginners 是一个面向初学者的 12 周、24 课时人工智能课程仓库,以 Jupyter Notebook 为核心载体,并配套 Vue.js 测验应用与 40+ 语言翻译。本文以仓库根目录的 AGENTS.md(开发者/Agent 环境指引文档)为主体,结合 environment.yml、requirements.txt、.devcontainer/devcontainer.json、etc/quiz-app/package.json 等仓库内实际配置文件,系统梳理从零搭建开发环境、运行 Notebook、启动测验应用、验证代码、构建部署到提交贡献的完整流程,帮助你快速把该课程仓库跑起来,并掌握其源码级的环境依赖细节。

仓库定位与整体架构

AI for Beginners 是一套覆盖人工智能基础知识的系统课程,仓库内包含使用 Jupyter Notebooks 的实战课程、测验(Quiz)与动手实验(Hands-on Lab)。课程内容覆盖以下主题:

核心技术栈:Python 3、Jupyter Notebooks、TensorFlow、PyTorch、Keras、OpenCV,以及用于测验应用的 Vue.js。

架构形态:这是一个按主题组织教学内容的仓库(Jupyter Notebooks 为主体),由 Vue.js 编写的测验应用(位于 etc/quiz-app/)与广泛的多语言支持作为补充。整个仓库没有传统意义上的构建过程,Notebook 直接运行,文档站点通过 Docsify 静态托管。

环境搭建:从 clone 到可运行的 Jupyter

课程设计为通过 Python + Jupyter Notebooks 运行,官方推荐使用 miniconda 管理虚拟环境。基础流程如下:

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/ai/AI-For-Beginners
cd AI-For-Beginners

# 基于 environment.yml 创建并激活 conda 环境
conda env create --name ai4beg --file environment.yml
conda activate ai4beg

# 启动 Jupyter Notebook(二选一)
jupyter notebook
# 或
jupyter lab

environment.yml 配置解读

仓库根目录的 environment.yml 与 .devcontainer/environment.yml 内容一致,是环境创建的权威依据。其关键设计如下:

  • channels:同时启用 defaults 与 conda-forge,保证包来源的完整性与稳定性;
  • conda 层依赖(含版本锁定):
依赖包 版本约束 说明
python 最新稳定版(不锁版本) 核心解释器
numpy 1.26 数值计算基础
matplotlib 3.9 可视化
scipy 1.13 科学计算
requests 2.32 数据集/模型下载
scikit-learn 不锁版本 经典机器学习
opencv conda-forge::opencv 计算机视觉课程核心依赖
jupyter / ipykernel / ipython / ipywidgets 不锁版本 Notebook 交互环境
pytorch、torchtext、torchvision、torchdata 来自 pytorch 频道 PyTorch 深度学习栈
  • pip 层依赖:通过 pip: -r requirements.txt 引入,将 requirements.txt 中声明的深度学习生态包注入环境,包括 tensorflow==2.17.0、keras==3.13.2、gensim==4.3.3、gym==0.26.2(强化学习)、nltk==3.10.0、huggingface、tensorflow-hub==0.16.1、tensorflow-datasets==4.9.6、tokenizers==0.20.0、seaborn==0.13.2 等。注意 AGENTS.md 中的依赖清单为概述性质,实际版本以 requirements.txt 为准。

环境创建采用双份配置文件的原因:根目录的 environment.yml 面向手动 conda 创建;.devcontainer/ 下的副本供容器化开发在构建阶段自动执行(见下文)。

备选方案:devcontainer 容器开发

若不想在宿主机安装 Python 依赖,仓库提供了完整的容器化开发配置(.devcontainer/devcontainer.json):

  • 基础镜像:mcr.microsoft.com/devcontainers/miniconda,即内置 miniconda 的官方开发容器;
  • 宿主资源要求:至少 2 核 CPU(hostRequirements.cpus: 2);
  • VS Code 定制:自动安装 ms-python.python 与 ms-python.vscode-pylance 扩展,并将默认解释器指向 /opt/conda/bin/python,同时预置 pylint、flake8、black、mypy 等 lint/格式化工具路径;
  • 构建后命令:postCreateCommand 会自动执行 conda update conda -y && conda env create -f environment.yml,即进入容器即完成环境创建。

使用方式:在 VS Code 中打开仓库,按提示选择 "Reopen in Container" 即可自动完成上述配置。该方式对容器与 Docker 经验有要求,更适合进阶用户。

测验应用(Quiz App)搭建

测验应用是独立的 Vue.js 项目,位于 etc/quiz-app/。从 etc/quiz-app/package.json 可以看到:

  • Vue 2.x 技术栈:vue@^2.6.11,辅以 vue-i18n(国际化)与 vue-router(路由);
  • 构建工具:基于 @vue/cli-service ~5.0.8,脚本全部通过 vue-cli-service 驱动;
  • 代码规范:ESLint 配置内嵌于 package.json(plugin:vue/essential + eslint:recommended,parser 为 babel-eslint)。

启动与构建命令:

cd etc/quiz-app
npm install          # 安装依赖
npm run serve        # 开发服务器(热重载),默认 http://localhost:8080
npm run build        # 生产构建,产物输出到 etc/quiz-app/dist/
npm run lint         # 检查并自动修复代码问题

测验数据以按课时划分的 JSON 存放于 etc/quiz-app/src/assets/translations,其中英文原版为 en/ 下的 lesson-1.json 至 lesson-24.json,各翻译语言在对应目录中维护结构一致的 JSON,并通过 index.js 汇总导入。

开发工作流:三种主流方式

1. 本地开发(Jupyter / JupyterLab)

conda activate ai4beg
jupyter notebook   # 或 jupyter lab

在浏览器中进入课程目录(如 lessons/3-NeuralNetworks/03-Perceptron/),打开 .ipynb 文件逐单元格执行即可。Notebook 中的代码单元设计为尽量自包含,便于按学习节奏逐步运行。

2. VS Code + Python 扩展

  • 在 VS Code 中打开仓库根目录;
  • 安装 Python 扩展后,VS Code 会自动检测并使用已激活的 conda 环境(ai4beg);
  • .ipynb 文件可直接在 VS Code 内打开并交互执行。

更详细的本地运行说明可参考 lessons/0-course-setup/how-to-run.md,课程自学者还可参考 lessons/0-course-setup/setup.md 中 fork 仓库、先做课前测验、再阅读讲义、执行 Notebook、完成后测验与作业的完整自学路径。

3. 云端开发

  • GitHub Codespaces:在仓库页点击 Code → Codespaces → Create codespace on main,即可获得浏览器内可用的 VS Code 云环境,适合快速上手;
  • Binder:通过 README 中的 Binder 徽章在浏览器中启动 Jupyter 界面。需注意 Binder 提供的是基础计算资源,且屏蔽了部分公网访问,依赖在线下载模型/数据集的代码可能无法运行,训练速度在后期复杂课程中会明显偏慢。

面向进阶课程的 GPU 支持

课程后半段(CNN、GAN、Transformer 等)对 GPU 加速收益显著。可选的 GPU 运行环境包括:

  • Azure Data Science VM:使用支持 GPU 的 NC 系列虚拟机,直接克隆仓库到机器上学习;
  • Azure Machine Learning:使用其带 GPU 算力的 Notebook 功能;
  • Google Colab:逐个上传 Notebook 执行,提供免费 GPU 额度。

代码验证与测试策略

这是一个以学习内容为核心的教学仓库,没有传统意义上的软件测试套件。代码正确性验证主要依赖以下途径(AGENTS.md「Testing Instructions」章节):

  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 约定,面向教学场景;
  • 代码清晰可读,以学习优先于优化;
  • 关键概念辅以注释;
  • Notebook 友好:单元格尽量自包含;
  • 课程内容不设严格 lint 要求。

JavaScript / Vue.js(测验应用)

  • ESLint 配置见 etc/quiz-app/package.json;
  • 提交前执行 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 内容

无需任何构建过程,Notebook 直接执行即可。

测验应用部署(Azure Static Web Apps)

cd etc/quiz-app

# 开发
npm run serve

# 生产构建,输出到 etc/quiz-app/dist/
npm run build

部署到 Azure Static Web Apps 的流程(详见 etc/quiz-app/README.md):

  1. 将代码推送到 GitHub 仓库;
  2. 在 Azure 门户创建 Static Web App 资源,选择订阅、资源组与区域;
  3. 部署详情中选择 GitHub 源、组织、仓库与分支;
  4. 构建详情中配置:构建预设选 Vue、应用位置 etc/quiz-app、输出位置 dist;
  5. Azure 会自动在仓库中创建 GitHub Actions 工作流文件(.github/workflows/azure-static-web-apps-<name>.yml),负责构建与部署;
  6. 在仓库 Actions 标签页监控部署,完成后应用即通过 Azure 提供的 URL 上线。

工作流示例要点:app_location: "etc/quiz-app" 指定应用源码路径,output_location: "dist" 指定构建产物目录,部署所需的 AZURE_STATIC_WEB_APPS_API_TOKEN 由 Azure 自动注入 secrets。

文档站点(Docsify)

仓库使用 Docsify 生成文档站点:

  • index.html 作为入口点;
  • 无需构建,可直接静态托管;
  • 本地离线预览:fork 仓库并安装 Docsify 后,在仓库根目录执行 docsify serve,站点运行于 localhost:3000。

贡献指南

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)训练样本。

环境配置详解

核心依赖速查

以下为运行课程的完整依赖清单概览(与 requirements.txt 对应的 pip 层):

tensorflow==2.17.0        keras==3.13.2
torch / torchvision       (经 conda pytorch 频道安装)
opencv                    (经 conda conda-forge 频道安装)
scikit-learn              numpy==1.26
pandas==2.2.2             matplotlib==3.9
gensim==4.3.3             nltk==3.10.0
gym==0.26.2               tensorflow-datasets / tensorflow-hub
jupyter

环境变量

  • 基础使用无需任何特殊环境变量;
  • 仅当测验应用部署 Azure 时需要 AZURE_STATIC_WEB_APPS_API_TOKEN(由 Azure 自动设置并注入 GitHub Actions secrets)。

调试与问题排查

常见问题

问题:conda 环境创建失败

conda update conda -y   # 先升级 conda

同时确保磁盘空间充足(建议 50GB)。

问题:Jupyter 找不到内核(Kernel)

conda activate ai4beg
python -m ipykernel install --user --name ai4beg

问题:Notebook 中检测不到 GPU

nvidia-smi   # 验证 CUDA 安装
python -c "import torch; print(torch.cuda.is_available())"
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 超时或阻止下载 改用 GitHub Codespaces 或本地环境,以获得更好的资源访问能力。

内存问题

部分课程需要显著内存(建议 8GB+):

  • 资源密集课程使用云 VM;
  • 训练模型时关闭其他占用内存的应用;
  • 内存不足时在 Notebook 中调小 batch size。

补充建议

面向课程讲师

代码执行方式优先级

方式 特点 适用场景
本地(推荐) 完全控制、性能最佳、支持 GPU 长期系统学习
GitHub Codespaces 云端 VS Code,开箱即用 快速访问、轻量体验
Binder 浏览器 Jupyter,免费但资源受限 临时试跑
Azure ML Notebooks 企业级、带 GPU 规模化训练
Google Colab 逐个上传 Notebook,免费 GPU 档位 单文件 GPU 实验

与 Notebook 配合的注意事项

  • 许多 Notebook 首次运行会下载数据集(耗时较长);
  • 部分模型为获得合理训练时长需要 GPU;
  • 仓库尽可能采用预训练模型以降低计算门槛;
  • 后期计算机视觉课程(CNN、GAN)与 NLP Transformer 课程对 GPU/内存需求较高;从头训练教学价值高但耗时,迁移学习示例可显著缩短训练时间。

免责声明:本文所对应的文档 AGENTS.md 由 AI 翻译服务 Co-op Translator 提供多语言版本(如 translations/bn/AGENTS.md),自动翻译可能存在误差或不一致,技术内容请以仓库根目录的英文原版为准。

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