generative-ai-for-beginners 课程开发环境搭建指南：从 GitHub Codespaces 到本地运行的全流程配置

generative-ai-for-beginners 课程开发环境搭建指南：从 GitHub Codespaces 到本地运行的全流程配置

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

本指南围绕开源课程 generative-ai-for-beginners 的 00-course-setup（课程环境准备）模块展开，内容以课程主页 00-course-setup/README.md（含其在 translations/fi 的本地化版本）为骨架，系统讲解通过 GitHub Codespaces 云端开发、配置 LLM Provider 密钥、以及在本地用 Python、Conda、Docker 与 Jupyter 运行课程代码的完整方法。读完本文，你将掌握从 0 到 1 搭建一套可运行生成式 AI 示例代码的开发环境，并能对照仓库内的源码与配置文件排查常见环境问题。

课程与配套环境概览

本仓库是一套循序渐进的生成式 AI 学习课程。根据根目录 README.md 的说明，课程包含 21 个相互独立的课题，每个课题既可顺序学习也可按需单独切入；部分课程被标注为 "Learn"（讲解概念），部分被标注为 "Build"（概念 + 可运行代码示例，尽可能同时提供 Python 与 TypeScript 实现）。

课程中的编码练习分布在各个章节的python/、typescript/、js-githubmodels/、dotnet/等子目录中，并以.py、.ipynb、.ts等文件形式存在。因此，无论选择哪种运行方式，一套能执行 Python、能加载 notebook、能安全保存 API 密钥的环境，是整个学习过程的共同前提。这也是 00-course-setup/README.md 作为"第 0 课"存在的原因：它不讲解算法或提示词，而是先帮你把环境一次配好。

一、快速开始路线图：Fork → Codespaces → 注入密钥

对于想跳过本地安装、立即动手写代码的读者，官方推荐的第一条路径是云端的 GitHub Codespaces，它同时被 00-course-setup/01-setup-cloud.md 作为"Cloud Setup"独立成章。

1. Fork 整个仓库

首先将整个仓库 Fork 到自己的 GitHub 账号下，以获得修改代码、完成作业挑战的权限。Fork 之后，建议同步使用 Star 收藏，便于日后找回本仓库及其关联仓库。

2. 创建 Codespace

为了避免运行代码时出现依赖版本冲突，官方推荐直接在本课程的 GitHub Codespaces 中运行。操作路径为：在你的 Fork 中，点击Code → Codespaces → New on main（上图中绿色按钮 "Create codespace on main" 即该入口）。随后浏览器会打开一个 VS Code 窗口，开发容器自动开始构建，首次构建通常需要约 2 分钟。

从仓库源码看，Codespaces 的构建配置位于根目录 .devcontainer/devcontainer.json：它基于mcr.microsoft.com/devcontainers/universal:2.13通用镜像启动，内置了 Python、Node.js、.NET、Java 等运行时，并通过updateContentCommand执行python3 -m pip install -r requirements.txt自动安装 requirements.txt 中锁定的依赖（如openai、python-dotenv、ipywidgets、azure-ai-inference等），再通过postCreateCommand运行 .devcontainer/post-create.sh 完成后续初始化。这正是"打开即用、依赖零漂移"的实现基础。

3. 注入 API 密钥（Codespaces Secrets）

为避免把密钥写进代码导致泄露，推荐使用 Codespaces Secrets 保存凭据：

1. 点击左下角 ⚙️ 齿轮图标 → 打开 Command Palette（命令面板）；
2. 选择Codespaces: Manage User Secret → Add a new secret；
3. 将密钥命名为OPENAI_API_KEY，粘贴你的 Key，保存即可。

配置完成后，代码会自动通过环境变量读取该密钥，无需再在 Codespaces 内手工创建.env文件。

二、常见问题速查表

课程主页（中文译本同英文版）为开发中最常见的几个故障给出了标准修复动作，完整对比如下：

而如果是在本地（非 Codespaces）运行，00-course-setup/02-setup-local.md 还补充了更多本地场景的修复项：例如 Windows 下pip无法构建 wheel 时执行pip install --upgrade pip setuptools wheel后重试；出现ModuleNotFoundError: dotenv说明虚拟环境未正确安装依赖，需重新执行pip install -r requirements.txt；Docker 构建报 "No space left" 时，应在 Docker Desktop → Settings → Resources 中调大磁盘配额等。

三、配置 API 密钥：.env文件的完整创建与加载流程

无论走哪条运行路径，最终都要为课程代码准备可用的 LLM 服务凭据。课程提供了统一的本地配置方案：创建.env文件并配合python-dotenv加载。完整流程如下。

1. 进入项目根目录

cd path/to/your/project

2. 创建.env文件

在仓库根目录下，已有官方提供的环境变量模板.env.copy（见 .env.copy）。推荐的做法是直接复制模板，再编辑填充：

cp .env.copy .env

如果希望手工创建空白文件：

• Unix 系系统：touch .env
• Windows：echo . > .env

3. 编辑.env，按需填入凭据

以当前仓库 .env.copy 为准，课程支持的变量及含义如下表：

课程中的作业文件按文件名标签区分所需 Provider：aoai前缀需要 Azure OpenAI 端点与密钥，oai前缀需要 OpenAI 端点与密钥，hf需要 Hugging Face 令牌，githubmodels需要 Foundry Models 端点与密钥（GitHub Models 已于 2026 年 7 月底退役）。你可以只配置自己需要的 Provider，未配置的那部分作业会在缺少凭据时报错退出，不影响其余内容。各 Provider 的注册与配置细节，请参见 00-course-setup/03-providers.md。

4. 保存文件并注意安全

.env文件已被仓库的 .gitignore 忽略，切勿把真实密钥提交到公开仓库，否则可能引发安全问题，甚至因密钥被滥用而产生意外费用。

5. 安装python-dotenv

python-dotenv已包含在课程根目录 requirements.txt（版本锁定为python-dotenv==1.2.2），也可单独安装：

pip install python-dotenv

6. 在 Python 脚本中加载环境变量

from dotenv import load_dotenv import os # 从 .env 文件加载环境变量 load_dotenv() # 读取变量 endpoint = os.getenv("AZURE_INFERENCE_ENDPOINT") token = os.getenv("AZURE_INFERENCE_CREDENTIAL") print(endpoint)

仓库中的"强制校验"实践

仓库还提供了比os.getenv更严谨的封装。在 shared/python/env_utils.py 中，get_required_env会在变量缺失或为空时抛出带提示的ValueError，validate_env_vars则一次性校验多个必填变量并返回映射，get_env_with_default用于提供默认值。对应的单元测试位于 tests/test_env_utils.py，其中验证了"变量缺失抛ValueError且错误信息包含变量名"、"空字符串按缺失处理"、"可附带描述信息"等行为。这意味着在真实课程代码中，如果某个 Provider 变量未配置，脚本会以清晰、可定位的错误而非晦涩的运行时异常来提醒你回头检查.env。

四、在本地电脑运行课程代码

若更希望在自有设备上运行，00-course-setup/02-setup-local.md 给出了四条可选路径：原生 Python + 虚拟环境、VS Code Dev Container（Docker）、Miniconda、以及浏览器内的 Jupyter。它们最终都通向同一批课程内容，可按习惯任选其一。

前置条件

可在终端用python --version、git --version、docker --version、code --version逐一验证是否就绪。

克隆仓库

git clone https://github.com/microsoft/generative-ai-for-beginners cd generative-ai-for-beginners

（若已 Fork，可将 URL 替换为你自己的 Fork 仓库地址。）

选项 A：原生 Python（最快）

python -m venv .venv # 创建虚拟环境 source .venv/bin/activate # macOS / Linux # Windows PowerShell 使用：.\.venv\Scripts\activate

当命令行提示符前缀出现(.venv)即代表已进入虚拟环境，然后安装依赖：

pip install -r requirements.txt

选项 B：VS Code Dev Container（Docker）

该仓库为课程准备了一个开发容器，其配置定义在根目录 .devcontainer/devcontainer.json（Universal 运行时可同时支撑 Python、.NET、Node.js、Java 开发）。这一选项的最大价值在于：获得与 Codespaces 完全一致的开发环境，杜绝依赖漂移。

1. 安装 Docker Desktop，并确认docker --version可用；同时安装 VS Code 的 "Remote - Containers" 扩展；
2. 用 VS Code 打开仓库目录，编辑器会检测到.devcontainer/并弹出提示；
3. 点击 "Reopen in Container"，首次构建镜像约需数分钟，构建完成后即处于容器内部环境。

需要注意：如果 VS Code 提示"在容器中重新打开"，而你希望使用本机已安装的 Python，应拒绝该提示。

选项 C：Miniconda

Miniconda 是 Conda、Python 及若干包的轻量安装器。Conda 本身是一个包管理器，能方便地创建和切换 Python 虚拟环境，且在pip无法提供的包时尤为好用。安装后先验证conda --version。

接着创建环境描述文件environment.yml（若使用 Codespaces，应放在.devcontainer目录下，即.devcontainer/environment.yml）。仓库自带的 .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表示最新大版本）。随后在命令行执行：

conda env create --name ai4beg --file .devcontainer/environment.yml # .devcontainer 子路径仅适用于 Codespace 场景 conda activate ai4beg

若用 conda 安装时遇到错误，可手动执行conda install -c microsoft azure-ai-ml安装 Microsoft AI 相关库。

选项 D：浏览器中的经典 Jupyter / Jupyter Lab

如果你偏爱 Jupyter 界面，或不希望依赖 VS Code，可以直接在浏览器中使用 Jupyter。启动前先进入课程目录，然后运行：

jupyter notebook

或

jupyterhub

启动后，命令行窗口会打印访问 URL。打开该 URL 即可看到课程目录结构，并进入任意*.ipynb文件，例如 08-building-search-applications/python/oai-solution.ipynb。

五、技术需求：课程依赖哪个 LLM Provider

编码类课程示例主要基于 LLM 托管端点（API）来运行，需要通过合法凭据访问。课程讨论的 Provider 包括：OpenAI（GPT 系列）、Azure OpenAI（企业级能力取向）、Microsoft Foundry Models（单一端点与密钥访问数百个来自 OpenAI、Meta、Mistral、Cohere、Microsoft 等的模型，作为已退役 GitHub Models 的直接替代品）、Hugging Face（开源模型与推理服务器），以及可完全离线运行的本地方案（Foundry Local / Ollama）。若想完全脱离云订阅在自有设备上运行兼容的开源模型，可参考 19-slm 章节提供的实操示例。

在等待访问申请审批期间，每个编码课配套的README.md都贴出了代码与输出结果，可以先阅读、后运行。各 Provider 的完整注册方式、成本说明与端点获取步骤请参阅 00-course-setup/03-providers.md。

六、环境就绪后的下一步

完成上述配置后，即可正式进入课程正文。课程将先从生成式 AI 与大语言模型的基础概念讲起，再过渡到提示工程、文本/对话/搜索/图像等各类构建型应用，建议从第 1 课 01-introduction-to-genai/README.md 开始；如果需要设置具体 LLM Provider，回到 00-course-setup/03-providers.md 对照配置即可。

总而言之，本仓库的环境配置遵循"云端开箱即用 + 本地可复现"的双轨设计：想快速上手就 Fork 后直接进入 Codespaces 并通过 Codespaces Secrets 注入密钥；想在本地深度复现，则按 Python venv、Dev Container、Miniconda 或 Jupyter 四条路径之一准备环境，再以.env.copy为模板补齐凭据。环境配好之后，所有课程代码都只需load_dotenv()即可安全读取密钥并开始调用模型。

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