企业官网建设流程全解析

generative-ai-for-beginners 课程环境配置指南：Fork、Codespaces、本地运行与 API 密钥管理

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

本篇以课程仓库的入门文档 translations/it/00-course-setup/README.md（其英文母版为 00-course-setup/README.md）为主体，完整梳理 generative-ai-for-beginners 课程的入门配置流程：如何 Fork 仓库并创建 Codespaces、如何安全地添加 API 密钥（Secrets 与.env两种方式）、如何在本机克隆运行，以及可选的 Miniconda、VS Code Dev Container、Jupyter 等替代方案。读完后，你可以独立完成课程环境搭建，并掌握课程配套的故障排查表与密钥管理机制的源码级实现原理。

1. 配置目标与前置认知

官方入门文档开宗明义：为确保学习成功，配置页说明了三个要点——配置步骤（Setup Steps）、技术要求（Technical Requirements）、遇到问题去哪里求助（Where to get help）。文档中给出的核心结论是：

• 为了避免运行课程代码时出现依赖问题，推荐使用 GitHub Codespaces 运行整个课程；
• 如果偏好离线/本地开发，可以走setup-local路线（见 00-course-setup/02-setup-local.md）；
• 各编程课依赖 Azure OpenAI Service（现已并入 Microsoft Foundry），运行代码需要服务访问权限与 API 密钥，各编程课都附带README.md，在等待密钥审批期间可以先阅读其中的代码与输出示例。

说明：入门文档的原文表述为"课程包含 6 个概念课与 6 个编程课"；从当前仓库目录结构看，课程已扩展为01至21共 21 个编号章节（外加00-course-setup配置章），如04-prompt-engineering-fundamentals、08-building-search-applications、18-fine-tuning等，其中编程课普遍提供 Python/JavaScript/.NET 多种实现。下文流程对两种规模均适用。

2. 配置步骤一：Fork 仓库

第一步是把整个仓库Fork到你自己的账号，这样你才能自由修改任意代码并完成课程挑战（Challenge）。文档同时建议给仓库"加星"以便日后快速找到它与关联仓库。

• 在仓库页面使用 Fork 按钮完成；
• 后续所有 Codespaces 操作都基于你 Fork 后的副本进行。

3. 配置步骤二：创建 Codespace

在你 Fork 的仓库中，按路径操作：Code ➜ Codespaces ➜ New on main（新界面中为 "Create codespace on main"）。这会基于仓库根目录的 .devcontainer/devcontainer.json 启动一个浏览器内 VS Code 实例，所有依赖预装完毕。

3.1 Dev Container 到底做了什么（源码级佐证）

.devcontainer/devcontainer.json 定义了 Codespaces/Dev Container 的完整行为，几个关键字段值得理解：

• "image": "mcr.microsoft.com/devcontainers/universal:2.13"：采用通用运行时镜像，从源码结构看一个容器内同时支持 Python、Node.js、.NET、Java 等课程各语言方向的代码；
• "hostRequirements": { "cpus": 4 }：声明至少 4 核的宿主要求；
• "updateContentCommand": "python3 -m pip install -r requirements.txt"：每次内容更新后自动安装 Python 依赖；
• "postCreateCommand": "bash .devcontainer/post-create.sh"：容器创建后执行 .devcontainer/post-create.sh。

.devcontainer/post-create.sh 会补充安装python-dotenv、openai，以及ruff black mypy pytest等本地质量工具（与 CI 检查保持一致）。而 requirements.txt 固定了课程核心依赖，包括openai>=1.12.0、python-dotenv==1.2.2、azure-ai-inference、tiktoken、numpy、pandas等——这也解释了为什么文档反复强调"在 Codespaces 里跑可以避免依赖问题"：依赖清单被锁定并由容器命令自动安装。

3.2 添加 Secret（推荐的密钥方式）

文档 2.1 节给出了精确路径：

1. ⚙️ 齿轮图标 ➜ Command Palette ➜ 输入Codespaces : Manage user secret➜Add a new secret；
2. 名称填OPENAI_API_KEY，粘贴你的密钥，保存。

这样做的收益是密钥不落盘、不入库，代码通过环境变量自动读取。仓库配套的 00-course-setup/01-setup-cloud.md 进一步说明：个人账号每月有免费配额（120 core-hours / 60 GB-hours），空闲时可通过View ▸ Command Palette ▸ Codespaces: Stop Codespace停止或删除 Codespace 以保护配额。

4. 配置步骤三：.env 文件与 python-dotenv

对于不在 Codespaces 内运行（或需要更灵活配置）的场景，文档给出了通过.env文件管理密钥的完整六步流程。其安全前提是：绝不把 API 密钥硬编码进代码或提交到公开仓库，否则可能被恶意使用并产生意外费用。

4.1 创建.env文件

• Unix 系统（macOS/Linux）：

  touch .env

• Windows：

  echo . > .env

4.2 写入密钥变量

入门文档（意大利语版 translations/it/00-course-setup/README.md）沿用了早期的写法：

GITHUB_TOKEN=your_github_token_here

需要注意：从当前仓库的实际状态看，GitHub Models（及其GITHUB_TOKEN变量）已在 2026 年 7 月底退役，官方母版文档与 00-course-setup/02-setup-local.md 均已改为 Microsoft Foundry Models 的两个变量：

AZURE_INFERENCE_ENDPOINT=your_foundry_endpoint_here AZURE_INFERENCE_CREDENTIAL=your_foundry_api_key_here

仓库根目录提供了可直接复制的模板 .env.copy，它按 Provider 分区块注释了全部环境变量：

• OpenAI Provider：OPENAI_API_KEY；
• Azure OpenAI（Microsoft Foundry）：AZURE_OPENAI_API_VERSION（默认2024-10-21，即当前稳定 GA 版本）、AZURE_OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT（形如https://<resource-name>.openai.azure.com）、AZURE_OPENAI_DEPLOYMENT（如gpt-4o-mini）、AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT（如text-embedding-3-small）；
• Microsoft Foundry Models：AZURE_INFERENCE_ENDPOINT（形如https://<resource-name>.services.ai.azure.com/models）、AZURE_INFERENCE_CREDENTIAL；
• Hugging Face：HUGGING_FACE_API_KEY。

实际使用时可先执行cp .env.copy .env，再填入真实值。

4.3 安装并加载 python-dotenv

pip install python-dotenv

在 Python 脚本中：

from dotenv import load_dotenv import os # 从 .env 文件加载环境变量 load_dotenv() # 访问密钥变量（以 Foundry Models 为例） endpoint = os.getenv("AZURE_INFERENCE_ENDPOINT") token = os.getenv("AZURE_INFERENCE_CREDENTIAL") print(endpoint)

4.4 仓库源码中的密钥校验机制（纵深补充）

课程配套工具包 shared/python/env_utils.py 将"读密钥"这件事做成了带错误提示的 API，体现了文档流程背后的工程实践：

• get_required_env(var_name, description)：读取必需的环境变量，缺失或为空时抛出ValueError，并明确提示"请在 .env 文件或环境中设置"；
• validate_env_vars(*var_names)：批量校验多个变量（例如AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_API_KEY），一次性报出所有缺失项；
• get_env_with_default(var_name, default)：带默认值读取（如模型名回退到gpt-4o）。

shared/python/api_utils.py 则展示了密钥如何被消费：create_openai_client()从OPENAI_API_KEY构造 OpenAI 客户端；create_azure_openai_client()从AZURE_OPENAI_ENDPOINT/AZURE_OPENAI_API_KEY构造客户端，并把base_url指向<endpoint>/openai/v1/（v1 端点无需api_version）。对应的单元测试位于 tests/test_env_utils.py 与 tests/test_api_utils.py，覆盖变量缺失时抛错、批量校验等分支——这些测试正是对本文第 4 节"配置是否正确"的可验证依据。

5. 在本地计算机上运行

文档"How to Run locally on your computer"一节的要求很直接：本机安装任一受支持的 Python 版本 与 Conda 环境声明以 3.10 为基准），然后克隆仓库：

git clone https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners cd generative-ai-for-beginners

进入目录后建议先创建虚拟环境并安装依赖（这也是 00-course-setup/02-setup-local.md 中"Option A – Native Python"的最快路径）：

python -m venv .venv source .venv/bin/activate # macOS / Linux # .\.venv\Scripts\activate # Windows PowerShell pip install -r requirements.txt

💡 可在终端用python --version、git --version、code --version验证工具链就绪。

6. "接下来做什么"导航

文档的 "What's next" 表格给出四条明确的后续路径（此处链接已转换为仓库根相对路径）：

7. 故障排查（Troubleshooting）

文档给出的官方故障排查表应完整保留，遇到以下症状时按表处理：

本地路线（00-course-setup/02-setup-local.md）还补充了几条高频问题：python not found需把 Python 加入 PATH 或重开终端；Windows 上 pip 无法构建 wheel 时先执行pip install --upgrade pip setuptools wheel；ModuleNotFoundError: dotenv说明依赖没装全，重跑pip install -r requirements.txt；Docker 构建报No space left需在 Docker Desktop 设置中增大磁盘；同时启用 venv 与 container 两种方案时，VS Code 会反复提示重开，二者择一即可。

8. 可选步骤

8.1 安装 Miniconda

Miniconda 是安装 Conda、Python 及若干包的轻量安装器。Conda 作为包管理器，方便在不同 Python虚拟环境与包之间切换，也能安装pip渠道拿不到的包。文档给出的环境文件模板（environment.yml，若在 Codespaces 中则放在.devcontainer/environment.yml）：

name: <environment-name> channels: - defaults - microsoft dependencies: - python=<python-version> - openai - python-dotenv - pip - pip: - azure-ai-ml

其中<environment-name>为你想命名的 Conda 环境名，<python-version>为 Python 主版本号（如3）。仓库实际内置的 .devcontainer/environment.yml 可作参照：它声明了python=3.10.0、openai、python-dotenv，并通过 pip 安装azure-ai-inference。

创建并激活环境：

conda env create --name ai4beg --file .devcontainer/environment.yml # 注意：.devcontainer 子路径仅适用于 Codespace 配置 conda activate ai4beg

若 Conda 渠道报错，可用官方渠道手动安装微软 AI 库：

conda install -c microsoft azure-ai-ml

8.2 使用 VS Code + Python 扩展

文档推荐（但非强制）使用 VS Code 并安装 Python 支持扩展。三条注意事项：

• 在 VS Code 中打开课程仓库后，可以选择把项目放进容器运行——这正是 .devcontainer/ 特殊目录的作用；
• 克隆并打开目录后，VS Code 会自动建议你安装 Python 支持扩展，接受即可；
• 如果你要用本机已安装的 Python，当 VS Code 建议"在容器中重开仓库"时应拒绝该提示。

8.3 在浏览器中使用 Jupyter

也可以直接在浏览器里用 Jupyter 环境开发（经典 Jupyter 与 Jupyter Hub 均提供自动补全、语法高亮等体验）。进入课程目录后执行：

jupyter notebook

或

jupyterhub

启动后终端会打印访问 URL；打开后即可浏览课程目录并跳转到任意*.ipynb文件，例如 08-building-search-applications/python/oai-solution.ipynb。

8.4 使用容器运行

在"本地全量安装"与"Codespaces"之外，第三条路是用容器。仓库内的.devcontainer目录使 VS Code 能把整个项目搭建进容器。脱离 Codespaces 使用时需要本机安装 Docker，且有一定工作量，文档建议仅限有容器经验者采用（对应 00-course-setup/02-setup-local.md 的 Option B：确认docker --version可用、安装 Remote – Containers 扩展、打开仓库后点 "Reopen in Container"，首次构建约 3 分钟）。文档同时强调：在 Codespaces 场景下，Codespace Secrets 是保护 API 密钥的最佳方式之一，详见第 3.2 节。

9. 课程构成与技术要求

• 课程构成：入门文档表述为 6 个概念课 + 6 个编程课；当前仓库实际按01–21编号组织章节，概念课（如 01 简介、03 负责任地使用生成式 AI）与编程课（如 06 文本生成应用、08 搜索应用）交错编排。
• 编程课依赖：Azure OpenAI Service（现并入 Microsoft Foundry）。运行代码需要服务访问权限 + API 密钥，可提交访问申请。
• 等待审批期间：每门编程课都含README.md，可直接查看代码与输出，无需密钥也能跟进。

10. 首次使用 Azure OpenAI Service / OpenAI API

• 若你第一次接触Azure OpenAI Service：按官方指南创建并部署一个 Azure OpenAI Service 资源（门户方式），然后把 endpoint、API key、deployment 名称填入 .env.copy 对应字段（AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_API_KEY、AZURE_OPENAI_DEPLOYMENT）。
• 若你第一次接触OpenAI API：按官方 Quickstart 创建接口并使用，然后填入OPENAI_API_KEY。

完整的供应商选择与密钥获取步骤见 00-course-setup/03-providers.md。

11. 社区、贡献与下一步

• 认识其他学员：官方在 AI Community Discord 服务器设立了频道，方便与创业者、开发者、学生等交流；项目团队也会在该服务器上帮助学员。
• 贡献代码：这是一个开源项目。发现改进点或问题，请提交 Pull Request 或 issue（规范详见 CONTRIBUTING.md）；多数贡献需同意 Contributor License Agreement（CLA），CLA 机器人在 PR 上会自动标注；社区采用微软开源行为准则（CODE_OF_CONDUCT.md）。
• 翻译注意：文档明确提示——为仓库提供翻译时不要使用机器翻译，社区会人工校验，请只在你精通的语言上贡献。这也是 translations/ 目录下 40 余种语言目录（含本意第语版）的质量保障机制。

完成以上步骤后，就可以从 01-introduction-to-genai/README.md 开始第一课——生成式 AI 与 LLM 的介绍了。

12. 本文小结

• 云上最快路径：Fork ➜ 创建 Codespace（基于 .devcontainer/devcontainer.json 的通用镜像自动装好依赖）➜ 通过 User Secret 注入OPENAI_API_KEY。
• 本地标准路径：克隆仓库 ➜python -m venv+pip install -r [requirements.txt](https://link.gitcode.com/i/2af47d87423e40be1b0ccdb825085d3a)➜ 由 .env.copy 复制出.env并填入 Foundry/OpenAI 凭据。
• 可选增强：Miniconda 环境（.devcontainer/environment.yml 为参照）、Dev Container、浏览器 Jupyter。
• 排障：对照第 7 节的故障排查表；密钥读取与客户端构造的底层逻辑可结合 shared/python/env_utils.py、shared/python/api_utils.py 及其测试理解，配置是否正确可用测试用例直接验证。

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