Generative AI for Beginners 云端学习环境：GitHub Codespaces 零安装配置指南

本文基于课程仓库 00-course-setup 中的云端配置文档，讲解如何用 GitHub Codespaces 在浏览器中一键启动《Generative AI for Beginners》课程的开发环境：无需本地安装任何依赖，即可获得预置好 Python 3、Node.js、.NET、Java 等运行时的 VS Code 实例。读完本文，你将掌握 Codespace 的创建流程、API Key 的安全注入方式（Codespaces Secrets 与 .env 两种方案），并能看懂容器构建背后的 devcontainer 配置与仓库内的环境变量加载机制，从而独立完成课程全部编码实验。

为什么选择 GitHub Codespaces

对于不想在本地安装任何工具的学习者，Codespaces 提供了浏览器端的 VS Code 实例，且依赖全部预装。其核心收益如下（继承自课程文档 01-setup-cloud.md）：

收益	对你的意义
零安装	Chromebook、iPad、学校机房电脑都能直接上手
预构建开发容器	Python 3、Node.js、.NET、Java 已在容器内
免费额度	个人账户每月 120 core-hours / 60 GB-hours

提示：通过停止或删除闲置的 codespace 可以保持配额健康（View ▸ Command Palette ▸ Codespaces: Stop Codespace）。

创建 Codespace（一键完成）

操作流程只有两步：

1. Fork 课程仓库（仓库页面右上角 Fork 按钮）；
2. 在你的 fork 中点击 Code ▸ Codespaces ▸ Create codespace on main。

完成后，浏览器中的 VS Code 窗口会打开，开发容器开始构建。首次创建大约需要 2 分钟。

容器构建背后发生了什么

Codespaces 之所以"开箱即用"，是因为仓库根目录提供了完整的 .devcontainer 配置。从源码看，构建流程由三个文件驱动：

1. 基础镜像与规格：devcontainer.json 声明使用微软官方通用镜像 mcr.microsoft.com/devcontainers/universal:2.13，并声明 "hostRequirements": {"cpus": 4}，这正对应文档中"预构建 dev container，Python 3、Node.js、.NET、Java already inside"的承诺。
2. 依赖安装："updateContentCommand": "python3 -m pip install -r requirements.txt" 会在每次容器创建/更新时自动安装 Python 依赖。仓库的 requirements.txt 固定了课程所需的全部包，包括 ipywidgets、numpy、matplotlib、pandas、python-dotenv==1.2.2、openai>=1.12.0、tiktoken、azure-ai-inference、scikit-learn 等。
3. 后置脚本："postCreateCommand": "bash .devcontainer/post-create.sh" 执行 post-create.sh，其中补装 python-dotenv 与 openai，并安装 ruff black mypy pytest 等开发工具链（脚本注释说明这些与 .github/workflows/code-quality.yml 中的检查项一致，便于贡献者在本地复现 CI 检查）。

此外，devcontainer 还预配置了 VS Code 扩展：ms-python.python、ms-python.vscode-pylance、ms-toolsai.jupyter、ms-python.black-formatter、charliermarsh.ruff、esbenp.prettier-vscode、github.copilot 等，并开启了 editor.formatOnSave，Python 文件默认使用 Black 格式化。仓库还提供了一份 Conda 环境定义（env 名 dev，python 3.10 + openai + python-dotenv + azure-ai-inference），以及说明构建流程的 Setup.txt。

Python 版本方面，仓库根目录的 .python-version 锁定为 3.12.10，pyproject.toml 声明 requires-python >= 3.10，即课程代码兼容 Python 3.10–3.12。

安全地添加 API Key

课程代码需要通过环境变量访问模型服务，文档给出了两种方案。

方案 A：Codespaces Secrets（推荐）

1. 点击 ⚙️ 齿轮图标 → Command Palette → Codespaces: Manage user secret → Add a new secret；
2. Name 填 OPENAI_API_KEY；
3. Value 粘贴你的 key → Add secret。

到此为止——仓库中的代码会自动读取它。这一机制在仓库源码中有明确印证：共享工具模块 env_utils.py 提供 get_required_env() 与 validate_env_vars() 等函数，统一通过 os.getenv() 读取环境变量，缺失时抛出带提示的 ValueError（例如提示"请在 .env 文件或环境中设置"）；api_utils.py 中的 create_openai_client() 也会优先回退到 os.getenv("OPENAI_API_KEY")。这些行为由 tests/test_env_utils.py 等测试用例覆盖。Codespaces 会在容器启动时把 user secret 注入为环境变量，因此代码"自动拾取"无需任何额外配置。

方案 B：.env 文件（如确实需要）

cp .env.copy .env
code .env         # fill in OPENAI_API_KEY=your_key_here

模板文件 .env.copy 覆盖了课程可能用到的全部凭据变量，建议按需填写：

变量	用途	备注
OPENAI_API_KEY	OpenAI Provider 的 API key	方案 A 中注入的即此变量
AZURE_OPENAI_API_VERSION	Azure OpenAI API 版本	默认 '2024-10-21'（当前稳定 GA 版本）
AZURE_OPENAI_API_KEY / AZURE_OPENAI_ENDPOINT	Microsoft Foundry（原 Azure OpenAI Service）资源凭据	从 Foundry 门户获取
AZURE_OPENAI_DEPLOYMENT / AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT	聊天补全 / 嵌入模型部署名	例如 gpt-4o-mini、text-embedding-3-small
AZURE_INFERENCE_ENDPOINT / AZURE_INFERENCE_CREDENTIAL	Microsoft Foundry Models（多提供商模型目录）	一个 endpoint/key 覆盖 OpenAI、Meta、Mistral、Cohere、Microsoft 等
HUGGING_FACE_API_KEY	Hugging Face API/token	可选

注意：.env.copy 的注释与 00-course-setup/README.md 均说明：GitHub Models（及其 GITHUB_TOKEN 变量）将于 2026 年 7 月底退役，新场景应使用 Microsoft Foundry Models，从你的 Foundry 项目 "Overview" 页获取 endpoint 与 key。

使用 .env 方案时，各课节脚本通过 python-dotenv 加载，例如第 6 课的 oai-app.py 在开头调用 load_dotenv() 后再读取变量；env_utils.py 的 get_env_with_default() 还演示了带默认值的读取方式（如模型名默认值）。

常见问题排查

课程主 README（00-course-setup/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

如果最终决定改用本地环境（而非 Codespaces），可以继续参考同目录的 02-setup-local.md（本地安装）与 03-providers.md（各 LLM 提供商配置），环境就绪后即可进入 第 1 课：Generative AI 与 LLM 入门。