尧图网页设计 
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/等子目录对应语言的可运行代码示例与作业assignmentimages/课程配图。目录编号与主题可对照查看各课的 README例如04-prompt-engineering-fundamentals提示工程基础、06-text-generation-apps文本生成应用、07-building-chat-applications聊天应用、08-building-search-applications检索应用、15-rag-and-vector-databasesRAG 与向量数据库、18-fine-tuning微调等。仓库级规范中还说明课程类型分为“Learn”课以 README 理论为主与“Build”课附带可运行的 Python/TypeScript 代码示例。技术栈总览AGENTS 文档列出仓库使用的主要技术这些内容与仓库根目录的 requirements.txt 和 package.json 相互印证层技术/依赖Python 3.9openai、python-dotenv、tiktoken、azure-ai-inference、pandas、numpy、matplotlib另含ipywidgets、tqdm、scikit-learn见 requirements.txtTypeScript/JavaScript Node.jsazure/openai、azure-rest/ai-inference、openai等包各应用自带package.json模型服务提供商Azure OpenAI Service、OpenAI API以及 GitHub Models 等多模型目录交互学习Jupyter Notebooks*.ipynb一致化开发环境Dev Containers.devcontainer从 requirements.txt 可以看到 Python 侧的实际锁定依赖如openai1.12.0、python-dotenv1.2.2、numpy2.4.2、pandas3.0.0Node 侧在根 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.txt3. 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.jsonnpm install、npm run build、npm start是标准操作链路。4. Dev Container推荐的一键式环境仓库根目录提供 .devcontainer/devcontainer.json 配置适用于 GitHub Codespaces 或 VS Code 的 Dev Containers 扩展在 GitHub Codespaces 或安装 Dev Containers 扩展的 VS Code 中打开仓库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环境变量用途OPENAI_API_KEYOpenAI APIAZURE_OPENAI_API_KEYAzure OpenAI ServiceAZURE_OPENAI_ENDPOINTAzure OpenAI 的 endpoint URLAZURE_OPENAI_DEPLOYMENT聊天补全模型的部署名称AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTEmbeddings 模型的部署名称AZURE_OPENAI_API_VERSIONAPI 版本文档记载默认2024-02-01HUGGING_FACE_API_KEYHugging Face 模型调用GITHUB_TOKENGitHub Models 调用需要说明的是文档是一份快照式约定以当前仓库为准时.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 startTS 侧的既定流程是“先 build 后 start”并用nodemon支持开发期热重载。Jupyter Notebooks# 在仓库根目录启动 Jupyter jupyter notebook # 或者使用带 Jupyter 扩展的 VS Code仓库在多课中提供了*.ipynb讲义式作业例如 04 课的 Python 作业、08 课的检索应用作业交互式体验更适合初学者。代码风格跨语言、跨提供商的命名约定Python 侧用python-dotenv管理环境变量通过openai库完成 API 交互使用pylint做静态检查部分教学示例为保持简单会加# pylint: disableall遵循 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_idacademic-105485-koreystURL 中不得包含国家/地区语言标识避免/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/除外依次执行检查失效的相对路径broken relative paths检查路径是否缺失跟踪 IDpaths tracking检查 URL 是否缺失跟踪 IDURLs tracking检查 URL 是否带国家语言标识locale禁止/en-us/检查失效的外部 URLbroken external URLs。该流程完整定义在 .github/workflows/validate-markdown.yml 中其中链接跟踪检查借助markdown-checker等工具实现。code-quality.yml代码质量门禁除文档校验外仓库对 Python/TypeScript 变更还有独立的 code-quality.ymlPython对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 #123PR 描述说明改了什么、为什么改关联相关 issue代码改动需注明测试过的示例翻译类 PR 必须包含一次完整翻译的全部文件贡献要求签署 Microsoft CLA首个 PR 时自动触发先 fork 再提交一个 PR 只做一次逻辑改动尽量小而聚焦。新增代码示例的标准流程进入对应课程目录在python/或typescript/子目录中创建示例遵循命名约定{provider}-{example-name}.{py|ts|js}使用真实 API 凭据实测若引入了新环境变量务必在课程 README 中补充说明。更新文档的标准流程编辑课程目录下的 README.md遵守 Markdown 规范跟踪 ID、相对链接格式翻译更新交给 GitHub Actions 处理不要手动编辑翻译逐一测试所有链接有效。常见故障排查手册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 文档明确指出这是一个学习型仓库、没有生产部署环节课程通过以下渠道消费仓库本体直接阅读代码与文档GitHub Codespaces即开即用的预配置开发环境Microsoft Learn内容可能被同步到官方学习平台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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Generative AI for Beginners 仓库协作开发全指南：21 课课程的环境配置、编码规范与自动化质量门禁
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/等子目录对应语言的可运行代码示例与作业assignmentimages/课程配图。目录编号与主题可对照查看各课的 README例如04-prompt-engineering-fundamentals提示工程基础、06-text-generation-apps文本生成应用、07-building-chat-applications聊天应用、08-building-search-applications检索应用、15-rag-and-vector-databasesRAG 与向量数据库、18-fine-tuning微调等。仓库级规范中还说明课程类型分为“Learn”课以 README 理论为主与“Build”课附带可运行的 Python/TypeScript 代码示例。技术栈总览AGENTS 文档列出仓库使用的主要技术这些内容与仓库根目录的 requirements.txt 和 package.json 相互印证层技术/依赖Python 3.9openai、python-dotenv、tiktoken、azure-ai-inference、pandas、numpy、matplotlib另含ipywidgets、tqdm、scikit-learn见 requirements.txtTypeScript/JavaScript Node.jsazure/openai、azure-rest/ai-inference、openai等包各应用自带package.json模型服务提供商Azure OpenAI Service、OpenAI API以及 GitHub Models 等多模型目录交互学习Jupyter Notebooks*.ipynb一致化开发环境Dev Containers.devcontainer从 requirements.txt 可以看到 Python 侧的实际锁定依赖如openai1.12.0、python-dotenv1.2.2、numpy2.4.2、pandas3.0.0Node 侧在根 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.txt3. 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.jsonnpm install、npm run build、npm start是标准操作链路。4. Dev Container推荐的一键式环境仓库根目录提供 .devcontainer/devcontainer.json 配置适用于 GitHub Codespaces 或 VS Code 的 Dev Containers 扩展在 GitHub Codespaces 或安装 Dev Containers 扩展的 VS Code 中打开仓库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环境变量用途OPENAI_API_KEYOpenAI APIAZURE_OPENAI_API_KEYAzure OpenAI ServiceAZURE_OPENAI_ENDPOINTAzure OpenAI 的 endpoint URLAZURE_OPENAI_DEPLOYMENT聊天补全模型的部署名称AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTEmbeddings 模型的部署名称AZURE_OPENAI_API_VERSIONAPI 版本文档记载默认2024-02-01HUGGING_FACE_API_KEYHugging Face 模型调用GITHUB_TOKENGitHub Models 调用需要说明的是文档是一份快照式约定以当前仓库为准时.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 startTS 侧的既定流程是“先 build 后 start”并用nodemon支持开发期热重载。Jupyter Notebooks# 在仓库根目录启动 Jupyter jupyter notebook # 或者使用带 Jupyter 扩展的 VS Code仓库在多课中提供了*.ipynb讲义式作业例如 04 课的 Python 作业、08 课的检索应用作业交互式体验更适合初学者。代码风格跨语言、跨提供商的命名约定Python 侧用python-dotenv管理环境变量通过openai库完成 API 交互使用pylint做静态检查部分教学示例为保持简单会加# pylint: disableall遵循 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_idacademic-105485-koreystURL 中不得包含国家/地区语言标识避免/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/除外依次执行检查失效的相对路径broken relative paths检查路径是否缺失跟踪 IDpaths tracking检查 URL 是否缺失跟踪 IDURLs tracking检查 URL 是否带国家语言标识locale禁止/en-us/检查失效的外部 URLbroken external URLs。该流程完整定义在 .github/workflows/validate-markdown.yml 中其中链接跟踪检查借助markdown-checker等工具实现。code-quality.yml代码质量门禁除文档校验外仓库对 Python/TypeScript 变更还有独立的 code-quality.ymlPython对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 #123PR 描述说明改了什么、为什么改关联相关 issue代码改动需注明测试过的示例翻译类 PR 必须包含一次完整翻译的全部文件贡献要求签署 Microsoft CLA首个 PR 时自动触发先 fork 再提交一个 PR 只做一次逻辑改动尽量小而聚焦。新增代码示例的标准流程进入对应课程目录在python/或typescript/子目录中创建示例遵循命名约定{provider}-{example-name}.{py|ts|js}使用真实 API 凭据实测若引入了新环境变量务必在课程 README 中补充说明。更新文档的标准流程编辑课程目录下的 README.md遵守 Markdown 规范跟踪 ID、相对链接格式翻译更新交给 GitHub Actions 处理不要手动编辑翻译逐一测试所有链接有效。常见故障排查手册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 文档明确指出这是一个学习型仓库、没有生产部署环节课程通过以下渠道消费仓库本体直接阅读代码与文档GitHub Codespaces即开即用的预配置开发环境Microsoft Learn内容可能被同步到官方学习平台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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考