企业官网建设流程全解析

Generative AI for Beginners 仓库协作开发全指南：21 课课程的环境配置、编码规范与自动化质量门禁

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

本指南基于本仓库的 AGENTS.md（贡献者与 AI 协作开发约定文档）整理，面向希望在本 21 课《生成式人工智能入门》课程仓库中搭建环境、运行示例、编写文档乃至提交代码改进的开发者。读完本文，你将掌握仓库从克隆到运行 Python/TypeScript/Jupyter 示例的完整流程、全部 API 环境变量清单、跨语言代码风格约束，以及由 GitHub Actions 自动执行的质量校验规则，可以直接照做并规避绝大多数提交时会被 CI 拦截的问题。

仓库定位：面向初学者的生成式 AI 21 课课程

正如 AGENTS.md 所描述，本仓库提供的是一套“21 课时、从基础概念到生产级应用开发”的生成式 AI 系统性课程。它是一套教学型（educational）代码库而非生产代码库：示例代码刻意保持简单、聚焦教学，每课彼此独立、可单独完成。与此同时，课程内容被结构化组织，便于讲解、演示和扩充。

课程内容分布在 21 个编号目录（00–21）中，每个目录通常包含：

• README.md：课程理论讲解、代码走读与视频链接；
• python/、typescript/、js-githubmodels/、dotnet/等子目录：对应语言的可运行代码示例与作业（assignment）；
• images/：课程配图。

目录编号与主题可对照查看各课的 README，例如04-prompt-engineering-fundamentals（提示工程基础）、06-text-generation-apps（文本生成应用）、07-building-chat-applications（聊天应用）、08-building-search-applications（检索应用）、15-rag-and-vector-databases（RAG 与向量数据库）、18-fine-tuning（微调）等。仓库级规范中还说明，课程类型分为“Learn”课（以 README 理论为主）与“Build”课（附带可运行的 Python/TypeScript 代码示例）。

技术栈总览

AGENTS 文档列出仓库使用的主要技术，这些内容与仓库根目录的 requirements.txt 和 package.json 相互印证：

从 requirements.txt 可以看到 Python 侧的实际锁定依赖（如openai>=1.12.0、python-dotenv==1.2.2、numpy==2.4.2、pandas==3.0.0）；Node 侧在根 package.json 中声明了@azure-rest/ai-inference、openai等依赖与docsify-to-pdf文档工具。

环境搭建：四步进入可运行状态

1. 克隆仓库并初始化 .env

所有需要调用 API 的课程都依赖根目录.env文件中的环境变量。仓库提供.env.copy作为模板，正式使用前先复制为.env再填入密钥：

git clone <当前仓库地址> cd generative-ai-for-beginners # 复制环境变量模板 cp .env.copy .env # 编辑 .env，填入你的 API Key 与 endpoint

.env已被仓库的.gitignore排除，因此API 凭据绝不能写入代码，只应保存在.env中。

2. Python 虚拟环境与依赖安装

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

3. Node.js/TypeScript 环境

# 根目录安装（用于文档工具链 docsify-to-pdf 等） npm install # 某一课的 TypeScript 示例需进入对应目录单独安装 cd 06-text-generation-apps/typescript/recipe-app npm install

以 recipe-app 示例 为例，仓库中每个 TypeScript 应用都自带package.json与tsconfig.json，npm install、npm run build、npm start是标准操作链路。

4. Dev Container：推荐的一键式环境

仓库根目录提供 .devcontainer/devcontainer.json 配置，适用于 GitHub Codespaces 或 VS Code 的 Dev Containers 扩展：

1. 在 GitHub Codespaces 或安装 Dev Containers 扩展的 VS Code 中打开仓库；
2. Dev Container 会自动完成三件事：
   • 依据requirements.txt安装 Python 依赖；
   • 执行 post-create 脚本；
   • 配置好 Jupyter kernel。

从源码看，容器基于通用镜像构建，并通过 devcontainer.json 的updateContentCommand安装requirements.txt、postCreateCommand触发 post-create.sh。该脚本除了补装 Python 侧python-dotenv、openai外，还会安装ruff black mypy pytest等开发工具，并说明“这些工具与 code-quality.yml 工作流一致，可在本地先行复现 CI 检查”。VS Code 侧已预置 Python、Jupyter、ESLint、Prettier、Black 等扩展，并开启editor.formatOnSave保存自动格式化。

.env 环境变量全清单与用途

课程中需要 API 访问的地方统一从.env读取环境变量。AGENTS 文档给出的变量及其用途如下，完整示例见仓库根目录的 .env.copy：

需要说明的是，文档是一份快照式约定；以当前仓库为准时，.env.copy 已在注释中将 API 版本默认值更新标注为2024-10-21（当前稳定 GA 版本），并补充了 Microsoft Foundry 相关的资源说明。因此更稳妥的做法是：每次都以 .env.copy 为模板复制.env，而不是凭记忆手写变量。

cp .env.copy .env

随后为你要完成的课程填入相应变量，例如把AZURE_OPENAI_DEPLOYMENT填为你的部署名（如gpt-4o-mini）、AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT填为 Embeddings 部署名（如text-embedding-3-small）。注意：更新.env后必须重启应用，进程内缓存的旧值不会自动刷新。

运行课程示例的三种方式

Python 脚本

# 进入某课目录 cd 06-text-generation-apps/python # 运行脚本 python aoai-app.py

以 06-text-generation-apps/python 为例，同一课的aoai-app.py、oai-app.py等分别对应不同提供商实现。

TypeScript 应用

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

TS 侧的既定流程是“先 build 后 start”，并用nodemon支持开发期热重载。

Jupyter Notebooks

# 在仓库根目录启动 Jupyter jupyter notebook # 或者使用带 Jupyter 扩展的 VS Code

仓库在多课中提供了*.ipynb讲义式作业（例如 04 课的 Python 作业、08 课的检索应用作业），交互式体验更适合初学者。

代码风格：跨语言、跨提供商的命名约定

Python 侧

• 用python-dotenv管理环境变量；
• 通过openai库完成 API 交互；
• 使用pylint做静态检查（部分教学示例为保持简单会加# pylint: disable=all）；
• 遵循 PEP 8 命名规范；
• API 凭据只放在.env，绝不写在代码里。

补充一个源码证据：根目录 pyproject.toml 与tests/、shared/python/共同构成了当前仓库的 Python 工程质量面。其中 shared/python/api_utils.py 是“必须保持干净”的共享工具模块——这一点在 .github/workflows/code-quality.yml 中体现为ruff check shared/、black --check shared/会强制通过，而全仓库其他教学示例代码的 lint 属于“仅告警不阻断（advisory）”级别，因为课程示例刻意保持简单。

TypeScript 侧

• 用dotenv包加载环境变量；
• 各应用在自身tsconfig.json中定义 TS 配置；
• Azure 服务使用@azure/openai或@azure-rest/ai-inference；
• 用nodemon做开发期自动重载；
• 运行顺序固定为npm run build后再npm start。

通用约定

• 代码示例保持简单、面向教学，关键概念要有注释；
• 每课代码自成一体、可直接运行；
• 统一命名前缀：aoai-代表 Azure OpenAI、oai-代表 OpenAI API、githubmodels-代表 GitHub Models 实现——这个约定在 06 课 Python 目录（aoai-app.py、oai-app.py并存）等位置可直接观察到。

文档写作与多语言翻译规范

仓库对 Markdown 文档有严格的机器可校验约束，这部分与 .github/workflows/validate-markdown.yml 的检查项一一对应：

• 所有 URL 必须以text形式包裹，中间不得有多余空格；
• 相对链接必须以./或../开头；
• 指向微软域名的链接必须携带跟踪 ID：?WT.mc_id=academic-105485-koreyst；
• URL 中不得包含国家/地区语言标识（避免/en-us/之类路径）；
• 图片存放在本课的./images目录，命名要能表意；
• 文件名仅使用英文字母、数字与连字符。

翻译支持（40+ 语言自动化流水线）

• 仓库通过自动化 GitHub Actions 支持 40+ 种语言；
• 译文统一存放在translations/目录；
• 不要提交半成品翻译；机器直译的稿件不被接受；
• 翻译图片存放在translated_images/目录。

在当前工作区中可以看到translations/（每种语言约 40 个 Markdown + 28 个 Notebook）与translated_images/（每种语言约 145 张 webp 图片）均已落地，说明该多语言机制正在被实际执行。

质量门禁：提交前你必须知道的自动化校验

validate-markdown.yml：链接健康检查

仓库使用 GitHub Actions 做自动校验。对 PR 的 Markdown/IPynb 变更（translations/与translated_images/除外）依次执行：

1. 检查失效的相对路径（broken relative paths）；
2. 检查路径是否缺失跟踪 ID（paths tracking）；
3. 检查 URL 是否缺失跟踪 ID（URLs tracking）；
4. 检查 URL 是否带国家语言标识（locale，禁止/en-us/）；
5. 检查失效的外部 URL（broken external URLs）。

该流程完整定义在 .github/workflows/validate-markdown.yml 中，其中链接跟踪检查借助markdown-checker等工具实现。

code-quality.yml：代码质量门禁

除文档校验外，仓库对 Python/TypeScript 变更还有独立的 code-quality.yml：

• Python：对shared/执行严格的ruff check与black --check；对全仓库其余代码执行仅告警的ruff check .；并运行pytest tests/；
• JavaScript/TypeScript：执行 ESLint（.eslintrc.json提供规则），同样按“仅告警”策略处理教学示例。

值得注意的版本演进：AGENTS 文档在“Testing and Validation”一节说明仓库为教育型仓库、“没有需要运行的单元测试/集成测试”，校验以人工测试 + GitHub Actions Markdown 校验 + 社区评审为主。而当前仓库已经演进——根目录tests/下已有 conftest.py 及test_api_utils.py、test_env_utils.py、test_input_validation.py等 pytest 用例，且 code-quality.yml 明确将pytest tests/作为必过步骤，覆盖对象为shared/python/中的共享工具。因此更准确的理解是：课程教学示例不要求单元测试，但共享工具模块已有自动化测试保障。

提交前人工自查清单

在任何 PR 之前，对照以下清单自查：

• Python 示例：激活虚拟环境后实际运行脚本；
• TypeScript 示例：依次执行npm install、npm run build、npm start；
• 确认.env中的环境变量配置正确、API Key 对示例可用；
• 代码能无报错运行；适用时同时用 Azure OpenAI 与 OpenAI API 测试；
• 验证支持 GitHub Models 的示例在该提供商下也可运行。

Pull Request 规范与常见工作流

PR 提交要点

• 提交前：相关代码同时在 Python 与 TypeScript 下测试；Markdown 校验会在 PR 上自动触发；确保微软域名链接都带跟踪 ID；相对链接有效；图片引用正确；
• PR 标题建议：使用描述性标题，例如[Lesson 06] Fix Python example typo或Update README for lesson 08，可附带 issue 编号如Fixes #123；
• PR 描述：说明改了什么、为什么改，关联相关 issue；代码改动需注明测试过的示例；翻译类 PR 必须包含一次完整翻译的全部文件；
• 贡献要求：签署 Microsoft CLA（首个 PR 时自动触发）；先 fork 再提交；一个 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. 逐一测试所有链接有效。

常见故障排查手册

Python 导入报错：确认虚拟环境已激活；重跑pip install -r requirements.txt；检查 Python 版本为 3.9+。

TypeScript 编译报错：在应用目录内执行npm install；确认 Node.js 版本兼容；必要时清空node_modules后重装。

API 认证失败：检查.env是否存在且取值正确；确认 API Key 未过期、账号有效；确认 endpoint URL 与你所在区域一致。

环境变量缺失：从.env.copy复制生成.env；补齐该课程所需全部变量；更新后重启应用。

学习资料的分发渠道与配套文档

AGENTS 文档明确指出这是一个学习型仓库、没有生产部署环节，课程通过以下渠道消费：

1. 仓库本体：直接阅读代码与文档；
2. GitHub Codespaces：即开即用的预配置开发环境；
3. Microsoft Learn：内容可能被同步到官方学习平台；
4. docsify：基于 Markdown 构建的文档站（参见 docsifytopdf.js 与 package.json）。

如需从 Markdown 一键导出 PDF，可执行：

npm run convert

该命令调用的是 package.json 中docsify-to-pdf提供的convert脚本。

仓库内值得延伸阅读的协作配套文档包括：课程搭建指南、贡献指南、行为准则 与 安全策略。需要注意，根目录这份 AGENTS.md 才是当前仓库的权威版本，而 translations/en/AGENTS.md 等翻译副本是自动翻译快照，若两者存在细微差异（例如 API 版本默认值、提供商变量名），应以根目录文档与仓库实际配置文件为准。

结语：这是一份“人机皆宜”的课程开发契约

AGENTS.md 之所以在本仓库扮演枢纽角色，是因为它把环境搭建、运行方式、代码风格、文档规范、CI 质量门禁、PR 协作流程沉淀成了一份可执行、可校验的工程契约——无论人类贡献者还是 AI 编码 Agent，只要遵循这份约定，就能在 21 课庞大的多语言内容中安全地新增示例、修正文档而不会破坏课程的一致性。当你准备提交第一个 PR 时，不妨把本指南当作对照表：先跑通.env、装好依赖、让示例运行、过一遍 validate-markdown 与 code-quality 的检查项，剩下的就是一次小而聚焦的提交。

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