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/测试。关键技术栈层面技术选型PythonPython 3.9依赖openai、python-dotenv、tiktoken、azure-ai-inference、pandas、numpy、matplotlib等见 requirements.txtTypeScript/JavaScriptNode.js依赖openai经 v1 端点对接 Azure OpenAI Responses API、azure-rest/ai-inference对接 Microsoft Foundry Models服务提供商Azure OpenAI Service、OpenAI API、Microsoft Foundry Models交互式学习Jupyter Notebooks大量*.ipynb作业文件开发环境Dev ContainersGitHub Codespaces / VS Code保证环境一致其中根目录 package.json 还声明了文档工具链依赖docsify-to-pdf用于把 Markdown 课程转为 PDF以及 TypeScript 示例所需的核心依赖azure-rest/ai-inference与openai。环境搭建克隆、Python venv、Node.js 与 Dev ContainerAGENTS.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等交互与数据处理库确保openai1.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 扩展。容器启动后会自动完成依据requirements.txt安装 Python 依赖执行 post-create 脚本.devcontainer/post-create.sh完成初始化配置好 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 定义了如下变量变量名用途备注OPENAI_API_KEYOpenAI API官方 OpenAI 平台密钥AZURE_OPENAI_API_VERSIONAzure OpenAI API 版本当前仓库默认2024-10-21.env.copy 中标明为当前稳定 GA 版本AZURE_OPENAI_API_KEYAzure OpenAI / Foundry 资源密钥Azure OpenAI Service 现已并入 Microsoft FoundryAZURE_OPENAI_ENDPOINTAzure OpenAI 端点 URL形如https://resource-name.openai.azure.comAZURE_OPENAI_DEPLOYMENTChat completion 模型部署名如gpt-4o-miniAZURE_OPENAI_EMBEDDINGS_DEPLOYMENTEmbeddings 模型部署名如text-embedding-3-smallAZURE_INFERENCE_ENDPOINTMicrosoft Foundry Models 端点多提供商模型目录形如https://resource.services.ai.azure.com/modelsAZURE_INFERENCE_CREDENTIALMicrosoft Foundry Models API Key替代将于 2026 年 7 月底退役的 GitHub Models 所用GITHUB_TOKENHUGGING_FACE_API_KEYHugging Face 模型用于 19-slm 等课程的开放模型场景注意克罗地亚语版 translations/hr/AGENTS.md 是较早的翻译快照其中仍记录着GITHUB_TOKEN与AZURE_OPENAI_API_VERSION2024-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 NotebookPython 示例cd 06-text-generation-apps/python python aoai-app.py06-text-generation-apps/python目录内同时提供了多种实现命名即区分提供商aoai-app.py/aoai-app-recipe.pyAzure OpenAIFoundry版本oai-app.py/oai-app-recipe.pyOpenAI API 版本githubmodels-app.pyMicrosoft Foundry ModelsGitHub 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.mdBuild 课程包含 Python 与 TypeScript 的可运行代码如 06-text-generation-apps、07-building-chat-applications。代码风格约定命名即契约仓库对多提供商并存场景采用了一套前缀命名契约这是阅读与贡献代码时最需要遵守的规则前缀对应提供商aoai-Azure OpenAIFoundry 资源oai-OpenAI APIgithubmodels-Microsoft Foundry ModelsGitHub Models 时代遗留前缀沿用至今这一约定贯穿文件名aoai-app.py、oai-history-bot.py、githubmodels-app.py等与示例中的变量命名。Python 约定使用python-dotenv管理环境变量通过openai库与 API 交互使用pylint做静态检查部分示例为保持简洁加了# pylint: disableall注释遵循 PEP 8 命名规范凭据只存.env。TypeScript 约定使用dotenv包加载环境变量每个应用自带tsconfig.json配置Azure OpenAI 场景用openai包指向/openai/v1/端点并调用client.responses.createMicrosoft Foundry Models 场景用azure-rest/ai-inference开发期用nodemon自动重载先npm run build再npm start。通用原则代码示例保持简单、具有教学性用注释解释关键概念每节课的代码应当自包含、可独立运行命名保持一致上述三前缀。文档与 Markdown 规范链接、跟踪 ID 与翻译流水线Markdown 风格检查清单所有 URL 必须写成text格式不允许多余空格相对链接必须以./或../开头注意本文按仓库规范展示时已统一转换为以仓库根目录为起点的路径所有指向 Microsoft 域名的链接必须带跟踪 ID?WT.mc_idacademic-105485-koreystURL 中不得出现国家地区路径如/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 中的失效的相对路径路径上缺失跟踪 IDURL 上缺失跟踪 ID带国家地区路径的 URL失效的外部 URL。手动测试清单Python 示例激活 venv 后实际运行脚本确认无导入与运行错误TypeScript 示例依次执行npm install、npm run build、npm start环境变量确认.env配置正确、API Key 与示例代码配合可用多提供商覆盖凡适用处同时用 Azure OpenAI 与 OpenAI API 测试支持处再用 Microsoft Foundry Models 验证。关于自动化测试的说明这是一个教育性仓库定位是教程与示例因此没有单元测试或集成测试可供运行与shared/与tests/中少量工具类测试并存——tests/下的test_env_utils.py等仅针对共享工具函数。验证主要由三类活动构成示例代码的手动测试、GitHub Actions 的 Markdown 校验、社区对教育内容的评审。Pull Request 提交流程提交前检查在适用处同时测试 Python 与 TypeScript 代码改动运行 Markdown 校验PR 时自动触发确认所有 Microsoft URL 均带跟踪 ID确认相对链接有效确认图片引用正确。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 聚焦且小。常见工作流新增一个代码示例进入对应课程目录在python/或typescript/子目录中创建示例遵循命名约定{provider}-{example-name}.{py|ts|js}用真实 API 凭据测试在课程 README 中补充新增的环境变量说明。更新文档编辑课程目录中的README.md遵守 Markdown 规范跟踪 ID、相对链接翻译更新由 GitHub Actions 处理不要手动编辑译文验证所有链接有效。使用 Dev Container 开发仓库自带.devcontainer/devcontainer.jsonpost-create 脚本自动安装 Python 依赖Python 与 Jupyter 扩展预配置完成基础镜像为mcr.microsoft.com/devcontainers/universal:2.11.2。发布渠道与文档站点作为教育仓库本仓库没有部署流程课程内容通过以下渠道消费仓库本体直接访问代码与文档GitHub Codespaces开箱即用的预配置开发环境Microsoft Learn内容可能被聚合到官方学习平台docsify基于 Markdown 构建的文档站。若需要把课程文档导出为 PDF可执行根目录 package.json 中声明的脚本npm run convert该命令调用docsify-to-pdf对应脚本见 docsifytopdf.js。故障排查速查表AGENTS.md给出了四类最常见问题的定位思路症状排查方向Python 导入错误确认虚拟环境已激活重跑pip install -r requirements.txt确认 Python 版本为 3.9TypeScript 构建错误在具体应用目录执行npm install确认 Node.js 版本兼容必要时清理node_modules重装API 认证错误确认.env存在且值正确确认 API Key 有效未过期确认端点 URL 与你的区域匹配缺少环境变量将.env.copy复制为.env填全当前课程所需变量更新后重启应用此外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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考