Generative AI for Beginners 仓库开发与协作指南环境搭建、代码规范与贡献流程全解读【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners导读AGENTS.md及其在 translations/hi/AGENTS.md 等 40 语言的翻译副本是本仓库面向开发者与贡献者的第一入口文档系统定义了从克隆代码、配置密钥、搭建开发环境到编写示例、通过 CI 校验、提交 PR 的完整协作规则。本文将这份指南作为主线结合仓库内真实配置文件与源码逐层拆解每一个可执行命令、每一项环境变量和每一条规范背后的落地细节帮助读者在几分钟内跑通课程示例并安全合规地向仓库提交高质量的代码与文档改动。项目概览21 课生成式 AI 课程的仓库形态这是一个面向初学者的生成式 AI 课程仓库共包含 21 个编号课程目录00-course-setup至21-meta覆盖从基础概念提示工程、LLM 对比到实战应用文本生成、聊天应用、搜索应用、图像应用、函数调用再到进阶主题RAG、AI Agent、微调、SLM的完整链路。仓库的技术选型可以从 requirements.txt 和 package.json 中直接确认Python 3.9 生态openai、python-dotenv、tiktoken、azure-ai-inference以及课程演示常用的pandas、numpy、matplotlibTypeScript / JavaScript 生态openaiAzure OpenAI 通过 v1 端点 Responses API、azure-rest/ai-inferenceMicrosoft Foundry Models模型服务商Azure OpenAI Service、OpenAI API、Microsoft Foundry ModelsGitHub Models 已进入退役期学习载体Jupyter Notebook 交互式练习、Dev Containers 统一开发环境。从 pyproject.toml 可以进一步确认项目正式声明requires-python 3.10并将openai1.0.0、python-dotenv1.0.0、azure-ai-inference1.0.0b1、tiktoken0.5.0列为项目级依赖——这与 AGENTS.md 中Python 3.9的描述互为印证具体以你本机实际安装的 Python 版本为准。仓库结构上每个课程目录都自包含README.md、代码示例与作业同时存在translations/40 语言的课程翻译、translated_images/翻译图片、shared/python/共享工具模块与tests/工具模块测试等辅助目录。环境搭建从克隆到可运行的三种路径1. 基础仓库初始化git clone https://github.com/microsoft/generative-ai-for-beginners.git cd generative-ai-for-beginners # 复制环境变量模板 cp .env.copy .env # 编辑 .env填入你的 API Key 与端点仓库根目录的 .env.copy 是唯一的配置模板覆盖 OpenAI、Azure OpenAIMicrosoft Foundry、Microsoft Foundry Models 与 Hugging Face 四类服务商且已预置默认值如AZURE_OPENAI_API_VERSION2024-10-21注释明确标注这是当前稳定 GA 版本。注意.env已被 .gitignore 忽略API 凭据绝不允许提交进版本库。2. Python 虚拟环境python3 -m venv venv # macOS/Linux: source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txtrequirements.txt 锁定了ipywidgets、numpy、matplotlib、pandas、tqdm、python-dotenv、openai1.12.0、tiktoken、azure-ai-inference、scikit-learn等课程所需的全部 Python 依赖。3. Node.js / TypeScript 环境# 安装根目录依赖文档工具链使用 npm install # 安装具体课程的 TypeScript 依赖 cd 06-text-generation-apps/typescript/recipe-app npm install以 06-text-generation-apps/typescript/recipe-app 为例每个 TypeScript 示例应用都自带独立的package.json与tsconfig.json遵循先构建后运行npm run build→npm start的固定节奏。4. Dev Container官方推荐仓库在 .devcontainer/devcontainer.json 中定义了完整的开发容器基础镜像mcr.microsoft.com/devcontainers/universal:2.13要求至少 4 核 CPU容器创建时自动执行python3 -m pip install -r requirements.txt安装 Python 依赖创建后自动运行 .devcontainer/post-create.sh 脚本预装 VS Code 扩展Python、Pylance、Jupyter、Black Formatter、Ruff、ESLint、Prettier、GitHub Copilot并预设 Python/JS/TS 的保存即格式化配置。值得注意的是.devcontainer/post-create.sh 会额外安装ruff、black、mypy、pytest四个开发工具脚本注释明确说明这是为了与 .github/workflows/code-quality.yml 中的检查保持一致让贡献者能在本地复现 CI——这为下文测试与验证章节提供了直接的仓库内证据。开发工作流环境变量与示例运行环境变量一览AGENTS.md 原文 仓库模板核对所有需要 API 访问的课程都通过.env中的环境变量获取配置完整清单如下与 .env.copy 逐一核对变量名用途OPENAI_API_KEYOpenAI API 认证AZURE_OPENAI_API_KEYAzure OpenAI现为 Microsoft Foundry 的一部分资源密钥AZURE_OPENAI_ENDPOINTAzure OpenAI 端点 URL形如https://resource-name.openai.azure.comAZURE_OPENAI_DEPLOYMENT聊天补全模型的部署名如gpt-4o-miniAZURE_OPENAI_EMBEDDINGS_DEPLOYMENT嵌入模型的部署名如text-embedding-3-smallAZURE_OPENAI_API_VERSIONAPI 版本默认2024-10-21当前稳定 GA 版本HUGGING_FACE_API_KEYHugging Face 模型认证AZURE_INFERENCE_ENDPOINTMicrosoft Foundry Models 端点多提供商模型目录形如https://resource-name.services.ai.azure.com/modelsAZURE_INFERENCE_CREDENTIALMicrosoft Foundry Models API 密钥替代即将退役的GITHUB_TOKEN仓库对这套约定做了双重落地一方面 shared/python/env_utils.py 提供get_required_env()与validate_env_vars()在变量缺失时抛出带指导信息的ValueError例如 Please set it in your .env file or environment另一方面课程示例直接使用os.environ[...]load_dotenv()见 06-text-generation-apps/python/aoai-app.py 的第 7–15 行先load_dotenv()载入.env再以base_urlf{os.environ[AZURE_OPENAI_ENDPOINT].rstrip(/)}/openai/v1/构造指向 Azure v1 端点的客户端。这与 shared/python/api_utils.py 中create_azure_openai_client()的实现完全一致——v1 端点承载 Responses API因此无需再单独传api_version。运行三种类型的示例# Python 示例 cd 06-text-generation-apps/python python aoai-app.py # TypeScript 示例先构建再运行 cd 06-text-generation-apps/typescript/recipe-app npm run build npm start # Jupyter Notebook jupyter notebook # 或在 VS Code 中安装 Jupyter 扩展直接打开仓库中的课程分为两类Learn 类课程以 README 文档与概念讲解为主Build 类课程提供 Python 与 TypeScript 的可运行代码。每个课程的 README 均包含理论、代码走读与视频链接。代码风格规范可读性与教育性的平衡Python 约定使用python-dotenv管理环境变量API 凭据只存.env绝不写入代码API 交互统一导入openai库部分示例为了教学简洁会加# pylint: disableall如 06-text-generation-apps/python/aoai-app.py 第 1 行遵循 PEP 8 命名规范文档要求使用pylint做 lint而仓库实际的质量基线可从 pyproject.toml 看到ruff开启 E/W/F/I/B/C4/UP/S 规则集black与isort统一 100 字符行长mypy以 Python 3.10 为基准做类型检查——贡献者本地跑一遍ruffblack即可与 CI 对齐。TypeScript 约定环境变量使用dotenv包每个应用自带tsconfig.jsonAzure 服务使用openai包客户端指向/openai/v1/端点并调用client.responses.createMicrosoft Foundry Models 使用azure-rest/ai-inference开发期用nodemon实现热重载运行前必须npm run build。通用命名约定AGENTS.md 明确要求前缀含义aoai-Azure OpenAI 示例oai-OpenAI API 示例githubmodels-Microsoft Foundry Models 示例沿用 GitHub Models 时代的旧前缀该命名在目录结构中可逐一验证例如 06-text-generation-apps/python 下同时存在aoai-app.py、oai-app.py、githubmodels-app.py。此外代码示例应当简洁、自包含、可独立运行并配以解释关键概念的注释。文档规范Markdown 链接与翻译工作流Markdown 风格硬性要求所有 URL 必须使用text形式包裹不得有多余空格相对链接必须以./或../开头所有指向 Microsoft 域名的链接必须携带追踪 ID?WT.mc_idacademic-105485-koreystURL 不得包含国家/地区专属 locale避免/en-us/之类路径图片存放在./images文件夹并使用描述性文件名文件名只允许英文字符、数字与短横线。多语言翻译流程仓库通过 GitHub Actions 自动支持 40 语言翻译文件存放于translations/翻译图片存放于translated_images/不提交部分翻译不接受机器翻译——课程内容的多语言维护依赖人工审校与 CI 协作个人贡献者不应手动编辑翻译文件更新由 GitHub Actions 统一处理。测试与验证PR 提交前的完整检查清单CI 自动检查Markdown 链接验证仓库通过 GitHub Actions 的validate-markdown.yml工作流自动校验损坏的相对路径broken relative paths路径上缺失追踪 IDmissing tracking IDs on pathsURL 上缺失追踪 IDmissing tracking IDs on URLs含国家 locale 的 URL损坏的外部 URL。这些检查项的失败示例可以从仓库根目录 images 中的评审注释截图直观看到github-check-paths-missing-tracking-comment.png、github-check-urls-missing-tracking-comment.png、github-check-country-locale-comment.png分别对应路径缺 ID、URL 缺 ID、locale 违规三类告警提交 PR 时需确保这些检查全部通过。手动测试AGENTS.md 规定的步骤Python 示例激活 venv 后运行脚本确认无报错TypeScript 示例执行npm install→npm run build→npm start环境变量确认.env中所有必需变量已正确配置API Key 对示例真实有效多提供商覆盖适用时同时用 Azure OpenAI 与 OpenAI API 测试支持 Microsoft Foundry Models 的示例也要验证。关于自动化测试的说明这是一个以教学为核心的仓库没有可运行的单元测试或集成测试。仓库的 tests 目录仅覆盖shared/python/下的工具函数如test_env_utils.py、test_api_utils.py、test_input_validation.py质量保障主要依赖示例代码的人工测试、GitHub Actions 的 Markdown 校验、社区对教学内容的评审。贡献流程提交高质量 PR 的完整路径提交前检查在 Python 和 TypeScript 两侧都测试代码改动适用时等待 PR 上的 Markdown 校验自动触发并全部通过确认所有 Microsoft URL 均带追踪 ID确认相对链接有效确认图片引用路径正确。PR 规范标题描述性写法如[Lesson 06] Fix Python example typo或Update README for lesson 08涉及问题时引用 issue 编号Fixes #123描述说明改了什么、为什么改链接相关问题代码改动需指明测试过哪些示例翻译类 PR 必须包含完整翻译的全部文件硬性要求签署 Microsoft CLA首个 PR 自动触发先 fork 再改每个逻辑改动一个 PR不混入无关修复PR 尽量聚焦且小。常见工作流模板新增代码示例进入对应课程目录 → 在python/或typescript/子目录创建示例 → 按{provider}-{example-name}.{py|ts|js}命名 → 用真实凭据测试 → 在课程 README 中记录新增的环境变量。更新文档编辑课程目录的 README.md → 遵守 Markdown 规范追踪 ID、相对链接→ 翻译交给 GitHub Actions勿手动编辑→ 验证所有链接有效。部署与发布说明仓库是教学项目没有部署流程。课程内容通过四条渠道触达学习者GitHub 仓库直接访问、GitHub Codespaces 即时开发环境、Microsoft Learn 官方学习平台同步、以及基于 docsify 构建的文档站点构建脚本见 docsifytopdf.jsnpm run convert可从 Markdown 生成 PDF。故障排查四类高频问题的解决路径Python 导入错误确认虚拟环境已激活 → 执行pip install -r requirements.txt→ 确认 Python 版本为 3.9项目声明为 3.10。TypeScript 构建错误在具体应用目录执行npm install→ 确认 Node.js 版本兼容 → 必要时清理node_modules后重装。API 认证错误确认.env存在且值正确 → 检查 API Key 是否有效、未过期 → 确认端点 URL 与你所在区域匹配。环境变量缺失将.env.copy复制为.env→ 填全当前课程所需的所有变量 → 更新.env后重启应用因为load_dotenv()通常在进程启动时读取。项目特色总结从这份开发者指南可以提炼出本仓库的四个核心设计取向教育优先示例刻意保持简单、聚焦概念讲解代码质量与教学清晰度之间取平衡每个课程自包含、可独立完成多提供商支持Azure OpenAI、OpenAI、Microsoft Foundry Models 一码多跑通过aoai-/oai-/githubmodels-前缀组织示例多语言协作40 语言内容由自动化翻译工作流 人工审校共同维护CI 驱动的质量门禁虽然不跑单元测试但通过 Markdown 链接校验、代码质量检查ruff/black/mypy/pytest见 pyproject.toml 与 .devcontainer/post-create.sh与人工测试在贡献入口处守住文档与代码质量。对初学者而言本文梳理的命令、变量与规范即是最高效的上手路线图对贡献者而言它是与 CI 检查对齐的合规手册。按此文档操作即可在几分钟内跑通第一节课例并稳妥地迈出第一次贡献。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考