Generative AI for Beginners 课程环境搭建全指南：Fork、Codespaces、密钥管理与本地运行

本指南围绕 generative-ai-for-beginners 课程的「00-course-setup」开篇模块展开，系统讲解从零开始搭建学习与编码环境所需的全部步骤：fork 仓库、在 GitHub Codespaces 中创建开发环境、以安全方式注入 LLM API 密钥、通过 .env 管理本地密钥，以及在本机（原生 Python / Miniconda / Jupyter / Dev Container）多套方案下运行课程代码。读完本文，你将能够独立完成云端或本地的全链路环境配置，排除最常见的容器、终端与鉴权故障，并直接进入第一课开始实战。

该课程仓库共包含 21 课，分为讲解概念的 Learn 课与动手编码的 Build 课，每节课均可按需选择 Python 或 TypeScript 示例运行；而 00-course-setup 正是决定这些代码能否顺利跑起来的第一步。本文以西班牙语翻译版 translations/es/00-course-setup/README.md 为主体骨架，同时以仓库根目录的英文原版 00-course-setup/README.md、本地环境指南、LLM 提供商配置指南 及源码 shared/python 为佐证进行深化，确保每一步都可对照仓库实际文件落地。

第一步：Fork 仓库并收藏，获得可自由改动的副本

课程官方强烈建议先不要直接在只读的原仓库上操作，而是将它 fork 到自己名下的 GitHub 账户中。fork 之后你将获得一份完整的可写副本，可以自由修改任意代码、提交你的作业，并完成各课（assignment）挑战。

文档还建议顺手 star（收藏）该仓库，方便日后快速找回，也便于发现同一系列的相关仓库。若你更倾向于在本地快速拉取而不携带全部 50+ 语言翻译目录，仓库根目录 README.md 也给出了 git clone --filter=blob:none --sparse 的稀疏检出方案（配合 git sparse-checkout set --no-cone '/*' '!translations' '!translated_images'），可显著减少下载体积，同时保留完成课程所需的全部文件。

第二步：创建 GitHub Codespaces，零依赖启动云端开发环境

为了规避本地依赖冲突，最省心的方式是在云端运行本课程。在完成 fork 之后，进入你自己的仓库分支，依次点击 Code → Codespaces → New on main（或在 fork 中新建 on main 的 codespace），即可获得一个开箱即用的浏览器版 VS Code 实例。仓库根目录下存在 .devcontainer/devcontainer.json，它定义了包含 Python、Node.js、.NET 与 Java 等运行时的开发容器，因此 Codespaces 会据此自动完成预构建，无需手工安装任何组件。

2.1 通过 Codespaces Secrets 注入密钥

把 API 密钥直接写进代码或仓库文件是高危做法。正确姿势是使用 Codespaces 的 Secrets（密钥）功能：

1. 点击 ⚙️ 齿轮图标 → 打开 Command Palette → 选择 Codespaces: Manage user secret → Add a new secret；
2. 密钥名称填写 OPENAI_API_KEY，将你从模型服务商获取的密钥粘贴进去，保存即可。

课程中凡是需要读取该密钥的脚本，都会自动从环境变量 OPENAI_API_KEY 中获取值。仓库中 shared/python/api_utils.py 的 create_openai_client() 便直接体现了这一约定：未显式传参时它会读取 os.getenv("OPENAI_API_KEY")，取不到就抛出带有明确提示的 ValueError。

提示：Codespaces Secrets 只对 Codespaces 生效；如果你改用 Docker Desktop 或纯本地运行，仍然需要配置本地 .env 文件，详见下文。

第三步：规划学习路线：接下来去哪里

完成基础配置后，可按需进入下一环节：

我想……	前往……
开始第 1 课	01-introduction-to-genai/README.md
离线（本地）学习	00-course-setup/02-setup-local.md
配置一个 LLM 提供商	00-course-setup/03-providers.md
开始动手编码之前先了解仓库结构	仓库根目录 README

上表中前两项指向课程默认的英文正文与本地环境指南：正式开启课程内容见 第 1 课导论，云端环境补充见 00-course-setup/01-setup-cloud.md。

密钥与 .env：本地运行时的安全配置方案

无论你在哪台机器上跑练习代码，都不要把密钥硬编码进源码。仓库 .env 文件配合 python-dotenv 是文档给出的标准做法。

创建 .env 文件

在项目根目录创建 .env 文件：

Unix 系系统：

touch .env

Windows：

echo . > .env

编辑 .env 文件

用 VS Code、Notepad++ 等任意文本编辑器打开 .env，在其中填入密钥。翻译文档中的示例使用 GitHub 令牌：

GITHUB_TOKEN=your_github_token_here

需要说明的是，该令牌示例面向早期的 GitHub Models 通道。当前仓库英文原版 00-course-setup/README.md 与 00-course-setup/03-providers.md 已明确：GitHub Models（及 GITHUB_TOKEN 变量）计划于 2026 年 7 月底退役，取而代之的是 Microsoft Foundry Models，使用 AZURE_INFERENCE_ENDPOINT 与 AZURE_INFERENCE_CREDENTIAL 两个变量。因此以本仓库当前状态为准，.env 更稳妥的填写方式是参照仓库根目录的模板文件 .env.copy，其中覆盖了 OpenAI、Azure OpenAI（现归属 Microsoft Foundry）、Microsoft Foundry Models 与 Hugging Face 四类提供商的完整变量名占位。而中文（或任意目标语言）翻译文档中的 GITHUB_TOKEN 示例可视为历史用法，机制与本指南完全一致：密钥永不入代码，只存于环境变量。

安装 python-dotenv 并加载变量

安装解析 .env 的依赖包：

pip install python-dotenv

在 Python 脚本中加载并读取变量：

from dotenv import load_dotenv
import os

# 从 .env 文件加载环境变量
load_dotenv()

# 读取 GITHUB_TOKEN（按 .env 中实际配置的变量名对应修改）
github_token = os.getenv("GITHUB_TOKEN")

print(github_token)

.env 已被仓库 .gitignore 覆盖，切勿将其提交到版本库。

仓库层面的源码佐证：更健壮的读取方式

课程仓库在 shared/python/env_utils.py 中对这种"从环境读密钥"的模式做了工程化封装，后续所有课程 Python 示例都可复用它：

• get_required_env(var_name, description)：取必填环境变量，缺失或为空时抛出 ValueError，并把变量用途写进错误信息，便于快速定位（实现见 env_utils.py）；
• validate_env_vars(*var_names)：一次性校验多个变量，返回 {变量名: 值} 字典，并一次性列出所有缺失项（实现见 env_utils.py）；
• get_env_with_default(var_name, default)：带默认值的读取，适合模型名这类可选配置。

这些行为均有单元测试覆盖，例如 tests/test_env_utils.py 中验证了：变量缺失时抛出 ValueError 且错误信息包含变量名、空字符串同样视为未设置、多个缺失变量会被一次性报告等。也就是说，你在练习中遇到的 Missing required environment variable: OPENAI_API_KEY 一类错误信息，正是由该模块统一生成的，含义是"密钥尚未注入环境"，而不是代码 bug。

如何在本机运行课程代码

在本地运行课程代码，前提是安装了任意较新版本的 Python。随后克隆仓库并进入目录：

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

如需安装 Python 运行依赖，可执行根目录 requirements.txt 对应的 pip install -r requirements.txt（注意：课程各代码目录下也常各自携带 requirements.txt，如 06-text-generation-apps/python/requirements.txt，按需安装即可）。完成后即可按任意一课目录下的 README.md 与作业文件开始练习。

常见问题排查

环境搭建阶段的高频故障与解决办法如下：

症状	解决办法
容器构建卡住超过 10 分钟	使用 Codespaces → “Rebuild Container” 重建容器
提示 python: command not found	终端没有正确挂载；点击 + → bash 重新打开终端
收到 OpenAI 返回的 401 Unauthorized	OPENAI_API_KEY 有误或已过期，请重新生成并更新密钥
VS Code 一直显示 “Dev container mounting…”	刷新浏览器标签页——Codespaces 偶尔会丢失连接
找不到 notebook 内核	在 notebook 菜单中执行 Kernel → Select Kernel → Python 3 重新选择内核

可选的进阶配置

文档同时提供了多条可选的本地运行路径，按你的偏好任选其一，殊途同归。

使用 Miniconda 管理 Python 环境

Miniconda 是一个轻量的安装器，用于安装 Conda 包管理器与 Python。Conda 的强项在于轻松创建、切换不同的虚拟环境，尤其适合安装那些 pip 源里没有的包（例如微软提供的 azure-ai-ml）。

安装好 Miniconda 并克隆仓库后，创建一个环境文件 environment.yml。若跟随 Codespaces 流程，则应放在 .devcontainer 目录下，即 .devcontainer/environment.yml。文件内容如下：

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

其中 <environment-name> 是你想给环境起的名字，<python-version> 是所需的 Python 版本，例如 3 表示当前最新大版本。若 conda 从该文件解析出错，可以退而用下面命令手动安装微软 AI 库：

conda install -c microsoft azure-ai-ml

随后创建并激活环境：

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

使用 VS Code 与 Python 扩展

官方推荐使用 VS Code 编辑器并安装 Python 支持扩展，但这只是建议而非强制要求。需要留意三点：

• 打开仓库时，VS Code 可能提示"在容器中重新打开"，这是由仓库内特殊的 .devcontainer 目录触发的；
• 克隆并打开目录后，VS Code 会自动建议安装 Python 支持扩展；
• 若你希望使用本机已安装的 Python，当 VS Code 建议重新在容器中打开仓库时，请拒绝该请求，以继续使用本地 Python。

在浏览器中使用 Jupyter

喜欢经典 Jupyter 界面、或不想依赖 VS Code 的读者，可以就地启动浏览器版 Jupyter。在课程目录下执行：

jupyter notebook

或

jupyterhub

启动后终端会给出访问 URL；打开后即可看到课程目录结构并进入任意 *.ipynb 文件。例如本仓库中的 08-building-search-applications/python/oai-solution.ipynb（对应 OAI 方案的搜索应用解法）。课程中大量练习以 notebook 形式提供，例如 04-prompt-engineering-fundamentals/python/oai-assignment.ipynb。

在容器中运行

除了本机或 Codespace，另一条路线是使用容器。仓库根目录的 .devcontainer 文件夹让 VS Code 可以把项目装进容器。Codespaces 之外使用容器需要自行安装 Docker，且初次构建镜像、配置卷等需要一定工作量，因此文档建议只有具备容器使用经验的读者选择该方案。若在 Codespaces 中又希望以容器方式管理 API 密钥，优先使用上文所述的 Codespaces Secrets 管理机制。

课程构成、技术需求与 LLM 提供商

本仓库的完整课程体系见根目录 README.md：共 21 课，既包含讲解生成式 AI / LLM 概念的 Learn 课，也包含动手实现的 Build 课。早期版本将课程划分为若干概念课与编码课，编码练习面向主流 LLM 服务；00-course-setup/03-providers.md 汇总了 OpenAI、Azure OpenAI、Microsoft Foundry Models、Hugging Face 以及完全离线的 Foundry Local / Ollama 等可选项的注册、成本与密钥说明，并解释了不同命名后缀的含义：

• aoai —— 需要 Azure OpenAI 的 endpoint 与密钥；
• oai —— 需要 OpenAI 的 endpoint 与密钥；
• hf —— 需要 Hugging Face 令牌；
• githubmodels —— 需要 Microsoft Foundry Models 的 endpoint 与密钥（承接 GitHub Models，后者 2026 年 7 月底退役）。

你可以只配置其中一家，也可以全部配置；未配置提供商的练习会在缺少凭据时报错退出。以第 06 课为例，仓库同时给出 06-text-generation-apps/python/aoai-app.py 与 06-text-generation-apps/python/oai-app.py 两套实现，便于对照 Azure OpenAI 与 OpenAI 两种接入方式的差异。如果你首次接触某个服务商，建议先通读仓库内的 00-course-setup/03-providers.md 中对应的创建资源与部署模型的章节，再回到本指南配置环境变量。

现在开始你的第一课

环境配置完成后，课程的正式旅程建议从 01-introduction-to-genai/README.md 起步，理解生成式 AI 与 LLM 的核心原理，随后逐步进入提示工程、文本生成、聊天应用、搜索应用与图像应用等各动手课程。仓库内还包含多语言翻译目录（如本指南所在的 translations/es），同一份课程内容可对照多语言版本学习。

每次开始新的 Codespace 或本地环境时，只需重复"注入密钥 → 选择内核 → 打开对应目录下的练习文件"三步即可无缝续学。祝你在生成式 AI 的学习与构建中获得乐趣。