generative-ai-for-beginners 仓库协作指南：21 课生成式 AI 课程的环境搭建、代码规范与贡献流程全解析

generative-ai-for-beginners 仓库协作指南：21 课生成式 AI 课程的环境搭建、代码规范与贡献流程全解析

【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners

本篇文章以仓库根目录的AGENTS.md（克罗地亚语翻译版，并对照英文原版）为骨架，系统拆解generative-ai-for-beginners这一开源课程仓库的完整协作方式：从仓库结构、Python / Node.js / Dev Container 环境搭建、.env凭据管理，到代码风格约定、Markdown 文档规范、测试验证流程与 Pull Request 提交流程。无论你是想跑通全部 21 节课的代码示例，还是想向课程贡献新示例、修正翻译或改进文档，读完本文即可获得一份可直接照做的操作手册。

仓库全貌：21 节课、三种语言实现、40+ 语言翻译

generative-ai-for-beginners是一个面向初学者的生成式 AI 课程仓库，包含 21 个编号课程目录（00–21），覆盖从生成式 AI 基础概念到可投产应用构建的完整路径。根据 AGENTS.md 的说明，仓库具有以下结构特征：

• 21 个编号课程目录（00-course-setup至21-meta），每个目录内含 README 文档、代码示例与作业（assignment）；
• 多语言实现：Python、TypeScript，部分课程还提供 .NET 示例（如 06-text-generation-apps/dotnet、07-building-chat-applications/dotnet）；
• 多语言翻译目录：translations/下有超过 40 种语言的版本（ar、zh-CN、hr、ja、ko、de、fr 等，每种语言约 40 个 Markdown 文档与 28 个 Jupyter Notebook）；
• 集中式配置：所有 API 凭据统一通过.env文件管理，以 .env.copy 为模板；
• 共享工具库：shared/python/提供环境变量与 API 客户端封装，配套tests/测试。

关键技术栈

其中根目录 package.json 还声明了文档工具链依赖（docsify-to-pdf用于把 Markdown 课程转为 PDF），以及 TypeScript 示例所需的核心依赖@azure-rest/ai-inference与openai。

环境搭建：克隆、Python venv、Node.js 与 Dev Container

AGENTS.md提供了四层递进的环境搭建方案，从"本地最小可用"到"容器化一键就绪"。

1. 初始克隆与 .env 模板

git clone <本仓库地址> cd generative-ai-for-beginners # 复制环境变量模板 cp .env.copy .env # 用你自己的 API Key 和 Endpoint 编辑 .env

克隆后务必执行cp .env.copy .env——几乎所有需要调用 API 的课程示例都依赖.env中的配置。

2. Python 虚拟环境

# 创建虚拟环境 python3 -m venv venv # 激活虚拟环境 # macOS/Linux: source venv/bin/activate # Windows: venv\Scripts\activate # 安装依赖 pip install -r requirements.txt

根目录 requirements.txt 已锁定课程所需的全部 Python 依赖（含ipywidgets、scikit-learn、tqdm等交互与数据处理库），确保openai>=1.12.0与azure-ai-inference等版本可用。

3. Node.js / TypeScript 环境

# 安装根级依赖（用于文档工具链） npm install # 进入具体课程的 TypeScript 示例目录单独安装 cd 06-text-generation-apps/typescript/recipe-app npm install

每个 TypeScript 示例应用都有独立的package.json与tsconfig.json，因此需要在应用目录内执行安装与构建，而不能只在仓库根目录装一次。

4. Dev Container（推荐）

仓库包含.devcontainer配置，适用于 GitHub Codespaces 或 VS Code Dev Containers 扩展。容器启动后会自动完成：

1. 依据requirements.txt安装 Python 依赖；
2. 执行 post-create 脚本（.devcontainer/post-create.sh）完成初始化；
3. 配置好 Jupyter kernel。

容器镜像基于mcr.microsoft.com/devcontainers/universal:2.11.2，并预置 Python 与 Jupyter 扩展。这种方式能彻底规避"本机能跑、别人环境跑不起来"的依赖问题，是 00-course-setup/README.md 中推荐的课程启动方式（在该文档中还有 Codespace Secrets 的配置说明，可避免把 API Key 写进代码）。

环境变量与凭据管理：一份 .env 覆盖全部课程

所有需要 API 访问的课程都通过.env中定义的环境变量获取凭据。以当前仓库实际内容为准，.env.copy 定义了如下变量：

注意：克罗地亚语版 translations/hr/AGENTS.md 是较早的翻译快照，其中仍记录着GITHUB_TOKEN与AZURE_OPENAI_API_VERSION=2024-02-01。英文原版 AGENTS.md 与 .env.copy 已更新为AZURE_INFERENCE_CREDENTIAL与2024-10-21，并以 Microsoft Foundry Models 取代即将退役的 GitHub Models。实操时请以英文原版与.env.copy为准。

源码级佐证：共享环境变量工具

仓库用shared/python/封装了环境变量的安全读取逻辑，这正是各课程示例读取.env的底层实现。shared/python/env_utils.py 提供三个核心函数：

• get_required_env(var_name, description)：读取必填变量，缺失或为空时抛出带提示信息的ValueError（第 11-35 行）；
• validate_env_vars(*var_names)：一次性校验多个变量，缺失时在错误信息中列出全部缺失项（第 38-71 行）；
• get_env_with_default(var_name, default)：读取带默认值的变量（第 74-88 行）。

配套测试 tests/test_env_utils.py 验证了这些边界行为：缺失变量抛错、空字符串抛错、多变量同时缺失时错误信息完整列出等，可作为"配置必须显式、失败必须可诊断"这一仓库约定的证据。

同样在shared/python/中，shared/python/api_utils.py 的create_azure_openai_client（第 91-144 行）演示了 Azure OpenAI 客户端的标准构造方式：读取AZURE_OPENAI_ENDPOINT与AZURE_OPENAI_API_KEY，将客户端指向<endpoint>/openai/v1/端点以启用 Responses API，且无需传api_version。这与.env.copy中"变量名不变"的说明完全呼应。

在 Python 中加载凭据

按 00-course-setup/README.md 的标准写法：

from dotenv import load_dotenv import os load_dotenv() # 从 .env 加载环境变量 endpoint = os.getenv("AZURE_INFERENCE_ENDPOINT") token = os.getenv("AZURE_INFERENCE_CREDENTIAL")

核心纪律只有一条：API 凭据永远只放.env，绝不写进代码（代码风格指南中对此有明确要求）。

运行课程示例：Python、TypeScript 与 Jupyter Notebook

Python 示例

cd 06-text-generation-apps/python python aoai-app.py

06-text-generation-apps/python目录内同时提供了多种实现，命名即区分提供商：

• aoai-app.py/aoai-app-recipe.py：Azure OpenAI（Foundry）版本；
• oai-app.py/oai-app-recipe.py：OpenAI API 版本；
• githubmodels-app.py：Microsoft Foundry Models（GitHub Models 时代遗留前缀）版本。

TypeScript 示例

cd 06-text-generation-apps/typescript/recipe-app npm run build # 先编译 npm start # 再运行

TypeScript 应用遵循"先构建后运行"的固定流程，开发时可借助nodemon实现改动后自动重载（见 06-text-generation-apps/typescript/recipe-app）。

Jupyter Notebook

# 在仓库根目录启动 Jupyter jupyter notebook

或用 VS Code + Jupyter 扩展直接打开*.ipynb。每个 Build 类课程都配有*-assignment.ipynb与*-solution.ipynb（如 08-building-search-applications/python/oai-solution.ipynb），便于对照学习。

两类课程形态

• "Learn" 课程：以README.md文档与概念讲解为主（如 01-introduction-to-genai/README.md）；
• "Build" 课程：包含 Python 与 TypeScript 的可运行代码（如 06-text-generation-apps、07-building-chat-applications）。

代码风格约定：命名即契约

仓库对多提供商并存场景采用了一套前缀命名契约，这是阅读与贡献代码时最需要遵守的规则：

这一约定贯穿文件名（aoai-app.py、oai-history-bot.py、githubmodels-app.py等）与示例中的变量命名。

Python 约定

• 使用python-dotenv管理环境变量；
• 通过openai库与 API 交互；
• 使用pylint做静态检查（部分示例为保持简洁加了# pylint: disable=all注释）；
• 遵循 PEP 8 命名规范；
• 凭据只存.env。

TypeScript 约定

• 使用dotenv包加载环境变量；
• 每个应用自带tsconfig.json配置；
• Azure OpenAI 场景用openai包指向/openai/v1/端点并调用client.responses.create；Microsoft Foundry Models 场景用@azure-rest/ai-inference；
• 开发期用nodemon自动重载；
• 先npm run build再npm start。

通用原则

• 代码示例保持简单、具有教学性；
• 用注释解释关键概念；
• 每节课的代码应当自包含、可独立运行；
• 命名保持一致（上述三前缀）。

文档与 Markdown 规范：链接、跟踪 ID 与翻译流水线

Markdown 风格检查清单

• 所有 URL 必须写成text格式，不允许多余空格；
• 相对链接必须以./或../开头（注意：本文按仓库规范展示时已统一转换为以仓库根目录为起点的路径）；
• 所有指向 Microsoft 域名的链接必须带跟踪 ID：?WT.mc_id=academic-105485-koreyst；
• URL 中不得出现国家地区路径（如/en-us/）；
• 图片存放于各课程./images目录，使用描述性文件名；
• 文件名仅使用英文字符、数字与连字符。

多语言翻译机制

• 仓库通过自动化 GitHub Actions 支持 40+ 语言；
• 译文统一存放于translations/目录（如 translations/hr、translations/zh-CN）；
• 翻译后的图片存放于translated_images/目录（同样按语言分子目录）；
• 禁止提交半成品译文；
• 不接受机器翻译（要求人工校对，翻译者须精通目标语言）——克罗地亚语版 AGENTS.md 末尾的免责声明即说明其由 Co-op Translator 自动翻译生成、以英文原版为权威来源。

测试与验证：CI 检查 + 手动测试双轨制

GitHub Actions 自动校验（validate-markdown.yml）

该工作流会在 PR 时自动检查 Markdown 中的：

• 失效的相对路径；
• 路径上缺失跟踪 ID；
• URL 上缺失跟踪 ID；
• 带国家地区路径的 URL；
• 失效的外部 URL。

手动测试清单

1. Python 示例：激活 venv 后实际运行脚本，确认无导入与运行错误；
2. TypeScript 示例：依次执行npm install、npm run build、npm start；
3. 环境变量：确认.env配置正确、API Key 与示例代码配合可用；
4. 多提供商覆盖：凡适用处，同时用 Azure OpenAI 与 OpenAI API 测试；支持处再用 Microsoft Foundry Models 验证。

关于自动化测试的说明

这是一个教育性仓库，定位是教程与示例，因此没有单元测试或集成测试可供运行（与shared/与tests/中少量工具类测试并存——tests/下的test_env_utils.py等仅针对共享工具函数）。验证主要由三类活动构成：示例代码的手动测试、GitHub Actions 的 Markdown 校验、社区对教育内容的评审。

Pull Request 提交流程

提交前检查

1. 在适用处同时测试 Python 与 TypeScript 代码改动；
2. 运行 Markdown 校验（PR 时自动触发）；
3. 确认所有 Microsoft URL 均带跟踪 ID；
4. 确认相对链接有效；
5. 确认图片引用正确。

PR 标题格式

使用描述性标题，例如：

• [Lekcija 06] Ispravak tipfelera u Python primjeru（课程 06 Python 示例拼写修正）；
• Ažuriranje README za lekciju 08（更新课程 08 README）；
• 涉及 Issue 时注明编号，如Fixes #123。

PR 描述要求

• 说明改了什么、为什么改；
• 关联相关 Issue；
• 代码改动须说明测试过哪些示例；
• 翻译类 PR 必须包含完整翻译的全部文件（禁止部分翻译）。

贡献者要求

• 首次提交时自动签署 Microsoft CLA；
• 先 Fork 到自己的账号再改动；
• 一个逻辑改动对应一个 PR（不混入无关修复）；
• 尽量保持 PR 聚焦且小。

常见工作流

新增一个代码示例

1. 进入对应课程目录；
2. 在python/或typescript/子目录中创建示例；
3. 遵循命名约定{provider}-{example-name}.{py|ts|js}；
4. 用真实 API 凭据测试；
5. 在课程 README 中补充新增的环境变量说明。

更新文档

1. 编辑课程目录中的README.md；
2. 遵守 Markdown 规范（跟踪 ID、相对链接）；
3. 翻译更新由 GitHub Actions 处理（不要手动编辑译文）；
4. 验证所有链接有效。

使用 Dev Container 开发

1. 仓库自带.devcontainer/devcontainer.json；
2. post-create 脚本自动安装 Python 依赖；
3. Python 与 Jupyter 扩展预配置完成；
4. 基础镜像为mcr.microsoft.com/devcontainers/universal:2.11.2。

发布渠道与文档站点

作为教育仓库，本仓库没有部署流程，课程内容通过以下渠道消费：

1. 仓库本体：直接访问代码与文档；
2. GitHub Codespaces：开箱即用的预配置开发环境；
3. Microsoft Learn：内容可能被聚合到官方学习平台；
4. docsify：基于 Markdown 构建的文档站。

若需要把课程文档导出为 PDF，可执行根目录 package.json 中声明的脚本：

npm run convert

该命令调用docsify-to-pdf（对应脚本见 docsifytopdf.js）。

故障排查速查表

AGENTS.md给出了四类最常见问题的定位思路：

此外，00-course-setup/README.md 还补充了容器构建卡住、python: command not found、401 Unauthorized、Notebook kernel 缺失等 Codespaces 场景的修复建议。

项目定位与边界

最后需要明确本仓库的自我定位（见 AGENTS.md 末尾与克罗地亚语版 "Project-Specific Notes"）：

• 这是教育性仓库，专注学习而非生产代码；
• 示例有意保持简单，以教学清晰度优先，代码质量与教学性相平衡；
• 每节课自包含，可独立完成；
• 支持多种 API 提供商：Azure OpenAI、OpenAI、Microsoft Foundry Models；
• 内容多语言化，配自动化翻译工作流；
• 社区支持在官方 Discord 频道进行。

理解这些边界，你就能正确预期"哪些代码可以直接上线、哪些只是教学示意"，从而更高效地利用这套 21 课课程体系入门生成式 AI。

【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners