AI-For-Beginners 仓库开发与学习环境搭建全指南:conda 环境、Jupyter 工作流、测验应用部署与贡献实践
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)。课程内容覆盖以下主题:
- 符号 AI(Symbolic AI):知识表示与专家系统(见 lessons/2-Symbolic)
- 神经网络与深度学习:基于 TensorFlow 和 PyTorch(见 lessons/3-NeuralNetworks)
- 计算机视觉:技术与架构(见 lessons/4-ComputerVision)
- 自然语言处理(NLP):包括 Transformer 与 BERT(见 lessons/5-NLP)
- 专题领域:遗传算法、强化学习、多智能体系统(见 lessons/6-Other)
- AI 伦理与负责任 AI 原则(见 lessons/7-Ethics)
核心技术栈: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」章节):
- 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 约定,面向教学场景;
- 代码清晰可读,以学习优先于优化;
- 关键概念辅以注释;
- 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):
- 将代码推送到 GitHub 仓库;
- 在 Azure 门户创建 Static Web App 资源,选择订阅、资源组与区域;
- 部署详情中选择 GitHub 源、组织、仓库与分支;
- 构建详情中配置:构建预设选 Vue、应用位置
etc/quiz-app、输出位置dist; - Azure 会自动在仓库中创建 GitHub Actions 工作流文件(
.github/workflows/azure-static-web-apps-<name>.yml),负责构建与部署; - 在仓库 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 流程
- 标题格式:清晰、描述性,说明改动内容;
- 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)训练样本。
环境配置详解
核心依赖速查
以下为运行课程的完整依赖清单概览(与 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。
补充建议
面向课程讲师
- 教学指引见 lessons/0-course-setup/for-teachers.md;
- 各课自包含,可按顺序整体讲授,也可单独选取;
- 计划时长:12 周,每周 2 课时。
代码执行方式优先级
| 方式 | 特点 | 适用场景 |
|---|---|---|
| 本地(推荐) | 完全控制、性能最佳、支持 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),自动翻译可能存在误差或不一致,技术内容请以仓库根目录的英文原版为准。