generative-ai-for-beginners 仓库开发者协作指南从环境配置、.env 变量到 Markdown 校验的完整工作流【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners本篇基于 translations/bg/AGENTS.mdBulgarian 译本与根目录 AGENTS.md 同源整理。它将讲清楚这个 21 课生成式 AI 教学仓库的开发者协作骨架如何搭建 Python/TypeScript/Dev Container 环境、如何配置.env中的多供应商 API 凭证、课程示例的运行方式、代码风格与 Markdown 校验规则以及 Pull Request 的提交要求。读完你可以独立完成克隆仓库 → 配好环境 → 跑通某课示例 → 按规范提交 PR的完整闭环。需要说明该文档是英文版 AGENTS.md 的保加利亚语机器/人工混合译文个别描述如 GitHub Models、API 版本默认值、Dev Container 镜像版本落后于仓库当前状态下文以仓库实际文件为准逐一校准。一、项目定位与仓库结构文档Преглед на проекта项目概览一节指出仓库包含一套21 课的课程大纲curriculum从生成式 AI 基础概念教到可生产级应用的构建面向初学者。仓库实际目录结构印证了这一点——00-course-setup到21-meta共 22 个编号课程目录每个目录下包含README.md、示例代码与任务assignment。关键技术栈文档列举均可在仓库中证实Python 3.9依赖见 requirements.txtopenai、python-dotenv、tiktoken、azure-ai-inference、pandas、numpy、matplotlib另外还锁定了ipywidgets、tqdm、scikit-learnTypeScript/JavaScriptNode.js 依赖见根目录 package.jsonopenai、azure-rest/ai-inference、azure/core-auth服务提供方Azure OpenAI Service、OpenAI API、GitHub Models据英文原版说明GitHub Models 将于 2026 年 7 月底退役正被 Microsoft Foundry Models 取代Jupyter Notebooks 用于交互式学习Dev Containers 提供一致的开发环境。仓库其他重要目录translations/——40 语言的课程翻译本文件即其中bg语言版本translated_images/——翻译后的图片按语言分目录存放.webp文件shared/python/与tests/——共享工具模块及其 pytest 测试下文校验一节说明集中式配置.env文件模板为 .env.copy。二、环境配置命令2.1 初始克隆与 .env 准备文档给出的初始设置命令# Clone the repository git clone https://github.com/microsoft/generative-ai-for-beginners.git cd generative-ai-for-beginners # Copy environment template cp .env.copy .env # Edit .env with your API keys and endpoints注意当前这份副本是仓库镜像本地使用时无需重新克隆直接在仓库根目录执行cp .env.copy .env即可。2.2 Python 虚拟环境# Create virtual environment python3 -m venv venv # Activate virtual environment # On macOS/Linux: source venv/bin/activate # On Windows: venv\Scripts\activate # Install dependencies pip install -r requirements.txt适用前提Python 3.9。当前 requirements.txt 中openai1.12.0、azure-ai-inference无版本锁定安装后即可运行各课 Python 示例。2.3 Node.js / TypeScript# Install root-level dependencies (for documentation tooling) npm install # For individual lesson TypeScript examples, navigate to the specific lesson: cd 06-text-generation-apps/typescript/recipe-app npm install根目录npm install安装的是文档工具依赖package.json 中docsify-to-pdf等而每课的 TypeScript 示例如 06-text-generation-apps/typescript/recipe-app拥有各自独立的package.json必须在示例目录下单独npm install。2.4 Dev Container推荐文档称仓库包含 GitHub Codespaces / VS Code Dev Containers 配置。实际配置为 .devcontainer/devcontainer.json基础镜像为mcr.microsoft.com/devcontainers/universal:2.13bg 译本写的 2.11.2 已过时以 devcontainer.json 为准updateContentCommand会在内容更新时执行python3 -m pip install -r requirements.txt自动安装 Python 依赖postCreateCommand执行 .devcontainer/post-create.sh该脚本额外安装python-dotenv、openai以及ruff、black、mypy、pytest等开发工具——脚本注释明确说明这些工具与 .github/workflows/code-quality.yml 中运行的检查一致让贡献者可以在本地复现 CI 检查预装 VS Code 扩展Python、Pylance、Jupyter、Black、Ruff、ESLint、Prettier、Copilot。也就是说在 Codespaces 或 VS Code Dev Containers 中打开仓库后依赖安装、Jupyter kernel 配置均为自动完成。三、环境变量多供应商 API 凭证文档列出所有需要 API 访问的共课后统一从.env读取变量。结合当前 .env.copy 的实际内容完整清单如下变量用途OPENAI_API_KEYOpenAI APIAZURE_OPENAI_API_KEYAzure OpenAI现已并入 Microsoft Foundry资源在 ai.azure.com 门户创建/管理环境变量名保持不变AZURE_OPENAI_ENDPOINTAzure OpenAI 资源 endpoint形如https://resource-name.openai.azure.comAZURE_OPENAI_DEPLOYMENT对话模型部署名例如gpt-4o-miniAZURE_OPENAI_EMBEDDINGS_DEPLOYMENT嵌入模型部署名例如text-embedding-3-smallAZURE_OPENAI_API_VERSIONAPI 版本。bg 译本写默认2024-02-01当前 .env.copy 中默认已是2024-10-21HUGGING_FACE_API_KEYHugging Face 模型AZURE_INFERENCE_ENDPOINTMicrosoft Foundry Models 多供应商模型目录 endpoint取代退役中的GITHUB_TOKENAZURE_INFERENCE_CREDENTIALMicrosoft Foundry Models API Key.env.copy中有一段关键注释Foundry Models 是一个 endpoint/key 即可访问 OpenAI、Meta、Mistral、Cohere、Microsoft 等多家模型的多供应商目录它取代了将于 2026 年 7 月底退役的 GitHub Models。因此若按 bg 译本填写GITHUB_TOKEN在当前的课示例中可能已经不适用——请以 .env.copy 中的AZURE_INFERENCE_ENDPOINT/AZURE_INFERENCE_CREDENTIAL为准。3.1 运行 Python 示例# Navigate to lesson directory cd 06-text-generation-apps/python # Run a Python script python aoai-app.pyaoai-前缀即文档命名约定Azure OpenAI 示例以aoai-开头、OpenAI API 示例以oai-开头、Foundry/GitHub Models 示例以githubmodels-开头该前缀为 GitHub Models 时代遗留。06-text-generation-apps/python 目录下可看到aoai-app.py、oai-app.py、githubmodels-app.py、aoai-study-buddy.py等一系列遵循该约定的脚本。3.2 运行 TypeScript 示例# Navigate to TypeScript app directory cd 06-text-generation-apps/typescript/recipe-app # Build the TypeScript code npm run build # Run the application npm start3.3 运行 Jupyter Notebooks# Start Jupyter in the repository root jupyter notebook也可以在 VS Code 中装 Jupyter 扩展直接打开.ipynb文件仓库内大量课程任务以 notebook 形式提供如 15-rag-and-vector-databases/notebook-rag-vector-databases.ipynb。3.4 两类课程Learn 与 BuildLearn 课以README.md文档和概念讲解为主例如 03-using-generative-ai-responsibly/README.mdBuild 课附带可运行的 Python 与 TypeScript 代码示例例如 06-text-generation-apps/README.md每课均有 README包含理论、代码讲解与视频内容链接。四、代码风格规范Python用python-dotenv管理环境变量用openai库进行 API 交互用pylint/ruff 做静态检查部分示例含# pylint: disableall以简化教学遵循 PEP 8 命名约定API 凭证一律存于.env绝不写进代码。TypeScript用dotenv包读取环境变量每个应用有自己的tsconfig.jsonbg 译本要求使用azure/openai或azure-rest/ai-inference访问 Azure 服务英文原版与当前依赖已更新为Azure OpenAI 走openai包的 v1 endpoint/openai/v1/client.responses.createFoundry Models 用azure-rest/ai-inference——这与 package.json 中dependencies的声明一致开发用nodemon热重载先npm run build再npm start。通用约定示例保持简单、教学导向关键概念要加注释解释每课代码必须自包含、可独立运行文件名一致化命名aoai-/oai-/githubmodels-前缀区分供应商。值得补充的仓库级证据CI 流水线 .github/workflows/code-quality.yml 对shared/目录强制执行ruff check与black --check并对全仓其余部分做建议性continue-on-error: true的 ruff 检查——注释解释原因是课程示例刻意保持简单。这印证了文档中代码质量与教学清晰度相平衡的定位。五、文档规范与翻译支持Markdown 风格与 CI 校验一一对应所有 URL 写成文本形式括号内外无多余空格相对链接必须以./或../开头所有指向 Microsoft 域名的链接必须携带跟踪参数?WT.mc_idacademic-105485-koreystURL 中不得出现国家特定 locale避免/en-us/图片存放于各课./images目录使用描述性英文命名英文字母、数字、连字符。这些规则不是建议而是被 .github/workflows/validate-markdown.yml 强制执行。该 workflow 在 PR 触及**.md/**.ipynb排除translations/**与translated_images/**时触发包含五个 jobcheck-broken-paths——检查断裂的相对路径check-paths-tracking——检查仓库内路径链接是否带跟踪 IDcheck-urls-tracking——对 PR 变更文件运行markdown-checker check_urls_tracking检查外部 URL 是否带跟踪 IDcheck-urls-locale——检查 URL 是否误带国家 localecheck-broken-urls——检查外部 URL 是否失效。翻译支持仓库通过自动化 GitHub Actions 支持 40 语言翻译存放于translations/本文件即 translations/bg/AGENTS.md其中还保留了课程目录结构translations/bg/00-course-setup…translations/bg/21-meta的完整镜像不允许提交部分翻译不接受机器翻译注意文档尾部的免责声明承认该 AGENTS.md 译文由 Co-op Translator AI 服务完成且自述原文为权威来源——这正是本文对过时之处以仓库实际文件为准校准的原因翻译后的图片存放于translated_images/按语言子目录如translated_images/bg/。六、测试与验证文档说无自动化测试但仓库已有 shared 工具测试bg 译本Без автоматизирани тестове无自动化测试一节写道这是教学仓库聚焦教程与示例没有单测或集成测试验证主要靠手工测试代码示例、GitHub Actions 的 Markdown 校验、社区对教育内容的评审。这一描述对课程示例仍然成立但需要补充当前仓库的真实状态仓库已有 tests/ 目录包含 tests/conftest.py、tests/test_api_utils.py、tests/test_env_utils.py、tests/test_input_validation.py针对shared/python/下的共享工具模块shared/python/env_utils.py 等做单元测试code-quality.yml 中的python-testsjob 会运行这些测试post-create.sh也预装了pytest供本地复现。因此准确的说法是课程示例本身无自动化测试靠手工验证而共享工具模块已有 pytest 覆盖并接入 CI。提交前自查清单文档原文要求检查 Markdown 链接上述 5 项 CI 检查全部通过手工测试Python 示例激活 venv 后实际运行TypeScript 示例走完npm install→npm run build→npm start确认环境变量配置正确、API Key 可用代码示例确保无错误运行在适用时同时测试 Azure OpenAI 与 OpenAI API在支持时验证 Foundry Models 路径。七、Pull Request 指南提交前适用时在 Python 与 TypeScript 两侧都测试代码改动Markdown 校验PR 自动触发所有 Microsoft URL 带跟踪 ID相对链接有效图片引用正确。PR 标题与描述描述性标题例如[Lesson 06] Fix Python example typo或Update README for lesson 08关联 issue 时写Fixes #123描述中说明改了什么、为什么改附相关 issue 链接代码改动要写明测试了哪些示例翻译 PR 必须包含完整翻译的全部文件。贡献要求签署 Microsoft CLA首次 PR 时自动先 Fork 仓库再改动一个 PR 只含一个逻辑改动保持小而聚焦。更完整的贡献流程见 CONTRIBUTING.md安全相关事项见 SECURITY.md行为准则见 CODE_OF_CONDUCT.md。八、常见工作流8.1 新增一个代码示例进入对应课程目录在python/或typescript/子目录创建示例遵循命名约定{provider}-{example-name}.{py|ts|js}即aoai-/oai-/githubmodels-前缀用真实 API 凭证测试将新增环境变量记录到课程 README。8.2 更新文档编辑课程目录下的 README.md遵循 Markdown 规范跟踪 ID、相对链接翻译由 GitHub Actions 处理不要手动改translations/测试所有链接有效。8.3 Dev Container 协作仓库自带 .devcontainer/devcontainer.json创建后脚本自动安装 Python 依赖见 .devcontainer/post-create.shPython 与 Jupyter 扩展预配置环境基于mcr.microsoft.com/devcontainers/universal:2.13。九、发布方式与文档站点文档Деплоймънт и публикуване一节明确这是学习仓库没有部署流程。课程内容的消费渠道有四个GitHub 仓库直接访问、GitHub Codespaces 即开即用的开发环境、Microsoft Learn 平台的内容分发、以及docsify构建的文档站点。生成 PDF 文档的命令来自 package.json 的convertscript 与 docsifytopdf.js# Generate PDF from documentation (if needed) npm run convertnpm run convert实际执行node_modules/.bin/docsify-to-pdf把仓库 Markdown 课程编译为 PDF。仓库内 presentations/ 目录下的课程演示稿pptx/pdf也属于同一发布产物体系。十、故障排查文档列出的四类常见问题与处理办法症状处理Python 导入错误确认虚拟环境已激活执行pip install -r requirements.txt确认 Python ≥ 3.9TypeScript 编译错误在具体应用目录而非仓库根执行npm install检查 Node.js 版本兼容性必要时删除node_modules重装API 认证错误确认.env存在且值正确确认 Key 未过期确认 endpoint URL 与所在区域匹配缺少环境变量cp .env.copy .env后按当前课程补齐所需项更新.env后重启应用补充一个排查入口各课程示例普遍通过 shared/python/env_utils.py 之类的共享工具读取与校验环境变量并有 tests/test_env_utils.py 保证其行为当遇到变量看似配置了但示例仍报错时可优先检查该课使用的工具函数实际读取的是哪几个变量名尤其是AZURE_OPENAI_*与AZURE_INFERENCE_*两组之间的差异。十一、小结translations/bg/AGENTS.md 作为课程仓库的开发者手册给出的是一套低门槛、强校验的协作模式环境侧用 Dev Container 与.env.copy模板抹平差异内容侧用Learn/Build 两类课程 供应商前缀命名保证示例自包含可运行质量侧用五个 Markdown 校验 job 手工测试 社区评审兜底。对贡献者而言掌握.env变量对照表 validate-markdown 五项检查 PR 清单这三张表就足以在这个多语言、多供应商、多语言栈的仓库中安全地贡献代码与文档。最后提醒该文档为保加利亚语译文涉及 API 版本现为2024-10-21、Foundry Models 凭证变量、Dev Container 镜像版本现为2.13等时效性内容请以仓库当前实际文件.env.copy、.devcontainer/devcontainer.json与英文原版 AGENTS.md 为准。【免费下载链接】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 仓库开发者协作指南从环境配置、.env 变量到 Markdown 校验的完整工作流【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners本篇基于 translations/bg/AGENTS.mdBulgarian 译本与根目录 AGENTS.md 同源整理。它将讲清楚这个 21 课生成式 AI 教学仓库的开发者协作骨架如何搭建 Python/TypeScript/Dev Container 环境、如何配置.env中的多供应商 API 凭证、课程示例的运行方式、代码风格与 Markdown 校验规则以及 Pull Request 的提交要求。读完你可以独立完成克隆仓库 → 配好环境 → 跑通某课示例 → 按规范提交 PR的完整闭环。需要说明该文档是英文版 AGENTS.md 的保加利亚语机器/人工混合译文个别描述如 GitHub Models、API 版本默认值、Dev Container 镜像版本落后于仓库当前状态下文以仓库实际文件为准逐一校准。一、项目定位与仓库结构文档Преглед на проекта项目概览一节指出仓库包含一套21 课的课程大纲curriculum从生成式 AI 基础概念教到可生产级应用的构建面向初学者。仓库实际目录结构印证了这一点——00-course-setup到21-meta共 22 个编号课程目录每个目录下包含README.md、示例代码与任务assignment。关键技术栈文档列举均可在仓库中证实Python 3.9依赖见 requirements.txtopenai、python-dotenv、tiktoken、azure-ai-inference、pandas、numpy、matplotlib另外还锁定了ipywidgets、tqdm、scikit-learnTypeScript/JavaScriptNode.js 依赖见根目录 package.jsonopenai、azure-rest/ai-inference、azure/core-auth服务提供方Azure OpenAI Service、OpenAI API、GitHub Models据英文原版说明GitHub Models 将于 2026 年 7 月底退役正被 Microsoft Foundry Models 取代Jupyter Notebooks 用于交互式学习Dev Containers 提供一致的开发环境。仓库其他重要目录translations/——40 语言的课程翻译本文件即其中bg语言版本translated_images/——翻译后的图片按语言分目录存放.webp文件shared/python/与tests/——共享工具模块及其 pytest 测试下文校验一节说明集中式配置.env文件模板为 .env.copy。二、环境配置命令2.1 初始克隆与 .env 准备文档给出的初始设置命令# Clone the repository git clone https://github.com/microsoft/generative-ai-for-beginners.git cd generative-ai-for-beginners # Copy environment template cp .env.copy .env # Edit .env with your API keys and endpoints注意当前这份副本是仓库镜像本地使用时无需重新克隆直接在仓库根目录执行cp .env.copy .env即可。2.2 Python 虚拟环境# Create virtual environment python3 -m venv venv # Activate virtual environment # On macOS/Linux: source venv/bin/activate # On Windows: venv\Scripts\activate # Install dependencies pip install -r requirements.txt适用前提Python 3.9。当前 requirements.txt 中openai1.12.0、azure-ai-inference无版本锁定安装后即可运行各课 Python 示例。2.3 Node.js / TypeScript# Install root-level dependencies (for documentation tooling) npm install # For individual lesson TypeScript examples, navigate to the specific lesson: cd 06-text-generation-apps/typescript/recipe-app npm install根目录npm install安装的是文档工具依赖package.json 中docsify-to-pdf等而每课的 TypeScript 示例如 06-text-generation-apps/typescript/recipe-app拥有各自独立的package.json必须在示例目录下单独npm install。2.4 Dev Container推荐文档称仓库包含 GitHub Codespaces / VS Code Dev Containers 配置。实际配置为 .devcontainer/devcontainer.json基础镜像为mcr.microsoft.com/devcontainers/universal:2.13bg 译本写的 2.11.2 已过时以 devcontainer.json 为准updateContentCommand会在内容更新时执行python3 -m pip install -r requirements.txt自动安装 Python 依赖postCreateCommand执行 .devcontainer/post-create.sh该脚本额外安装python-dotenv、openai以及ruff、black、mypy、pytest等开发工具——脚本注释明确说明这些工具与 .github/workflows/code-quality.yml 中运行的检查一致让贡献者可以在本地复现 CI 检查预装 VS Code 扩展Python、Pylance、Jupyter、Black、Ruff、ESLint、Prettier、Copilot。也就是说在 Codespaces 或 VS Code Dev Containers 中打开仓库后依赖安装、Jupyter kernel 配置均为自动完成。三、环境变量多供应商 API 凭证文档列出所有需要 API 访问的共课后统一从.env读取变量。结合当前 .env.copy 的实际内容完整清单如下变量用途OPENAI_API_KEYOpenAI APIAZURE_OPENAI_API_KEYAzure OpenAI现已并入 Microsoft Foundry资源在 ai.azure.com 门户创建/管理环境变量名保持不变AZURE_OPENAI_ENDPOINTAzure OpenAI 资源 endpoint形如https://resource-name.openai.azure.comAZURE_OPENAI_DEPLOYMENT对话模型部署名例如gpt-4o-miniAZURE_OPENAI_EMBEDDINGS_DEPLOYMENT嵌入模型部署名例如text-embedding-3-smallAZURE_OPENAI_API_VERSIONAPI 版本。bg 译本写默认2024-02-01当前 .env.copy 中默认已是2024-10-21HUGGING_FACE_API_KEYHugging Face 模型AZURE_INFERENCE_ENDPOINTMicrosoft Foundry Models 多供应商模型目录 endpoint取代退役中的GITHUB_TOKENAZURE_INFERENCE_CREDENTIALMicrosoft Foundry Models API Key.env.copy中有一段关键注释Foundry Models 是一个 endpoint/key 即可访问 OpenAI、Meta、Mistral、Cohere、Microsoft 等多家模型的多供应商目录它取代了将于 2026 年 7 月底退役的 GitHub Models。因此若按 bg 译本填写GITHUB_TOKEN在当前的课示例中可能已经不适用——请以 .env.copy 中的AZURE_INFERENCE_ENDPOINT/AZURE_INFERENCE_CREDENTIAL为准。3.1 运行 Python 示例# Navigate to lesson directory cd 06-text-generation-apps/python # Run a Python script python aoai-app.pyaoai-前缀即文档命名约定Azure OpenAI 示例以aoai-开头、OpenAI API 示例以oai-开头、Foundry/GitHub Models 示例以githubmodels-开头该前缀为 GitHub Models 时代遗留。06-text-generation-apps/python 目录下可看到aoai-app.py、oai-app.py、githubmodels-app.py、aoai-study-buddy.py等一系列遵循该约定的脚本。3.2 运行 TypeScript 示例# Navigate to TypeScript app directory cd 06-text-generation-apps/typescript/recipe-app # Build the TypeScript code npm run build # Run the application npm start3.3 运行 Jupyter Notebooks# Start Jupyter in the repository root jupyter notebook也可以在 VS Code 中装 Jupyter 扩展直接打开.ipynb文件仓库内大量课程任务以 notebook 形式提供如 15-rag-and-vector-databases/notebook-rag-vector-databases.ipynb。3.4 两类课程Learn 与 BuildLearn 课以README.md文档和概念讲解为主例如 03-using-generative-ai-responsibly/README.mdBuild 课附带可运行的 Python 与 TypeScript 代码示例例如 06-text-generation-apps/README.md每课均有 README包含理论、代码讲解与视频内容链接。四、代码风格规范Python用python-dotenv管理环境变量用openai库进行 API 交互用pylint/ruff 做静态检查部分示例含# pylint: disableall以简化教学遵循 PEP 8 命名约定API 凭证一律存于.env绝不写进代码。TypeScript用dotenv包读取环境变量每个应用有自己的tsconfig.jsonbg 译本要求使用azure/openai或azure-rest/ai-inference访问 Azure 服务英文原版与当前依赖已更新为Azure OpenAI 走openai包的 v1 endpoint/openai/v1/client.responses.createFoundry Models 用azure-rest/ai-inference——这与 package.json 中dependencies的声明一致开发用nodemon热重载先npm run build再npm start。通用约定示例保持简单、教学导向关键概念要加注释解释每课代码必须自包含、可独立运行文件名一致化命名aoai-/oai-/githubmodels-前缀区分供应商。值得补充的仓库级证据CI 流水线 .github/workflows/code-quality.yml 对shared/目录强制执行ruff check与black --check并对全仓其余部分做建议性continue-on-error: true的 ruff 检查——注释解释原因是课程示例刻意保持简单。这印证了文档中代码质量与教学清晰度相平衡的定位。五、文档规范与翻译支持Markdown 风格与 CI 校验一一对应所有 URL 写成文本形式括号内外无多余空格相对链接必须以./或../开头所有指向 Microsoft 域名的链接必须携带跟踪参数?WT.mc_idacademic-105485-koreystURL 中不得出现国家特定 locale避免/en-us/图片存放于各课./images目录使用描述性英文命名英文字母、数字、连字符。这些规则不是建议而是被 .github/workflows/validate-markdown.yml 强制执行。该 workflow 在 PR 触及**.md/**.ipynb排除translations/**与translated_images/**时触发包含五个 jobcheck-broken-paths——检查断裂的相对路径check-paths-tracking——检查仓库内路径链接是否带跟踪 IDcheck-urls-tracking——对 PR 变更文件运行markdown-checker check_urls_tracking检查外部 URL 是否带跟踪 IDcheck-urls-locale——检查 URL 是否误带国家 localecheck-broken-urls——检查外部 URL 是否失效。翻译支持仓库通过自动化 GitHub Actions 支持 40 语言翻译存放于translations/本文件即 translations/bg/AGENTS.md其中还保留了课程目录结构translations/bg/00-course-setup…translations/bg/21-meta的完整镜像不允许提交部分翻译不接受机器翻译注意文档尾部的免责声明承认该 AGENTS.md 译文由 Co-op Translator AI 服务完成且自述原文为权威来源——这正是本文对过时之处以仓库实际文件为准校准的原因翻译后的图片存放于translated_images/按语言子目录如translated_images/bg/。六、测试与验证文档说无自动化测试但仓库已有 shared 工具测试bg 译本Без автоматизирани тестове无自动化测试一节写道这是教学仓库聚焦教程与示例没有单测或集成测试验证主要靠手工测试代码示例、GitHub Actions 的 Markdown 校验、社区对教育内容的评审。这一描述对课程示例仍然成立但需要补充当前仓库的真实状态仓库已有 tests/ 目录包含 tests/conftest.py、tests/test_api_utils.py、tests/test_env_utils.py、tests/test_input_validation.py针对shared/python/下的共享工具模块shared/python/env_utils.py 等做单元测试code-quality.yml 中的python-testsjob 会运行这些测试post-create.sh也预装了pytest供本地复现。因此准确的说法是课程示例本身无自动化测试靠手工验证而共享工具模块已有 pytest 覆盖并接入 CI。提交前自查清单文档原文要求检查 Markdown 链接上述 5 项 CI 检查全部通过手工测试Python 示例激活 venv 后实际运行TypeScript 示例走完npm install→npm run build→npm start确认环境变量配置正确、API Key 可用代码示例确保无错误运行在适用时同时测试 Azure OpenAI 与 OpenAI API在支持时验证 Foundry Models 路径。七、Pull Request 指南提交前适用时在 Python 与 TypeScript 两侧都测试代码改动Markdown 校验PR 自动触发所有 Microsoft URL 带跟踪 ID相对链接有效图片引用正确。PR 标题与描述描述性标题例如[Lesson 06] Fix Python example typo或Update README for lesson 08关联 issue 时写Fixes #123描述中说明改了什么、为什么改附相关 issue 链接代码改动要写明测试了哪些示例翻译 PR 必须包含完整翻译的全部文件。贡献要求签署 Microsoft CLA首次 PR 时自动先 Fork 仓库再改动一个 PR 只含一个逻辑改动保持小而聚焦。更完整的贡献流程见 CONTRIBUTING.md安全相关事项见 SECURITY.md行为准则见 CODE_OF_CONDUCT.md。八、常见工作流8.1 新增一个代码示例进入对应课程目录在python/或typescript/子目录创建示例遵循命名约定{provider}-{example-name}.{py|ts|js}即aoai-/oai-/githubmodels-前缀用真实 API 凭证测试将新增环境变量记录到课程 README。8.2 更新文档编辑课程目录下的 README.md遵循 Markdown 规范跟踪 ID、相对链接翻译由 GitHub Actions 处理不要手动改translations/测试所有链接有效。8.3 Dev Container 协作仓库自带 .devcontainer/devcontainer.json创建后脚本自动安装 Python 依赖见 .devcontainer/post-create.shPython 与 Jupyter 扩展预配置环境基于mcr.microsoft.com/devcontainers/universal:2.13。九、发布方式与文档站点文档Деплоймънт и публикуване一节明确这是学习仓库没有部署流程。课程内容的消费渠道有四个GitHub 仓库直接访问、GitHub Codespaces 即开即用的开发环境、Microsoft Learn 平台的内容分发、以及docsify构建的文档站点。生成 PDF 文档的命令来自 package.json 的convertscript 与 docsifytopdf.js# Generate PDF from documentation (if needed) npm run convertnpm run convert实际执行node_modules/.bin/docsify-to-pdf把仓库 Markdown 课程编译为 PDF。仓库内 presentations/ 目录下的课程演示稿pptx/pdf也属于同一发布产物体系。十、故障排查文档列出的四类常见问题与处理办法症状处理Python 导入错误确认虚拟环境已激活执行pip install -r requirements.txt确认 Python ≥ 3.9TypeScript 编译错误在具体应用目录而非仓库根执行npm install检查 Node.js 版本兼容性必要时删除node_modules重装API 认证错误确认.env存在且值正确确认 Key 未过期确认 endpoint URL 与所在区域匹配缺少环境变量cp .env.copy .env后按当前课程补齐所需项更新.env后重启应用补充一个排查入口各课程示例普遍通过 shared/python/env_utils.py 之类的共享工具读取与校验环境变量并有 tests/test_env_utils.py 保证其行为当遇到变量看似配置了但示例仍报错时可优先检查该课使用的工具函数实际读取的是哪几个变量名尤其是AZURE_OPENAI_*与AZURE_INFERENCE_*两组之间的差异。十一、小结translations/bg/AGENTS.md 作为课程仓库的开发者手册给出的是一套低门槛、强校验的协作模式环境侧用 Dev Container 与.env.copy模板抹平差异内容侧用Learn/Build 两类课程 供应商前缀命名保证示例自包含可运行质量侧用五个 Markdown 校验 job 手工测试 社区评审兜底。对贡献者而言掌握.env变量对照表 validate-markdown 五项检查 PR 清单这三张表就足以在这个多语言、多供应商、多语言栈的仓库中安全地贡献代码与文档。最后提醒该文档为保加利亚语译文涉及 API 版本现为2024-10-21、Foundry Models 凭证变量、Dev Container 镜像版本现为2.13等时效性内容请以仓库当前实际文件.env.copy、.devcontainer/devcontainer.json与英文原版 AGENTS.md 为准。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
