generative-ai-for-beginners 云环境实战：用 GitHub Codespaces 零安装运行 GenAI 课程

本篇技术指南讲解 generative-ai-for-beginners 课程的云端环境搭建方案：借助 GitHub Codespaces 获得一个预装全部依赖的浏览器版 VS Code 实例，完成 Fork 仓库、一键创建 Codespace，并以 Codespaces Secrets 或 .env 文件两种方式安全注入 LLM API 密钥。读完本文，你将能够不安装任何本地工具即可跑通课程中的全部 Python/Notebook 代码，并理解仓库内置 devcontainer 的构建细节与密钥校验机制。

1. 为什么选择 Codespaces：免安装的云开发环境

官方课程文档 00-course-setup/01-setup-cloud.md 给出的适用场景很明确：当你不想在本地安装任何东西时使用本指南。Codespaces 提供一个免费的、基于浏览器的 VS Code 实例，所有依赖预先安装完毕。

收益	对你的实际意义
零安装	Chromebook、iPad、学校实验室的 PC 上都能直接跑
预构建开发容器	Python 3、Node.js、.NET、Java 已经内置
免费配额	个人账户每月 120 core-hours / 60 GB-hours

提示：保持配额健康的方法是停止或删除闲置的 codespace： View ▸ Command Palette ▸ Codespaces: Stop Codespace。

从仓库结构看，这套方案能成立的根本原因是仓库根目录提供了完整的 .devcontainer/ 配置，使 GitHub 可以按统一配方自动构建出课程所需的全部运行环境，下文将逐层拆解。

2. 一键创建 Codespace

1. Fork 本仓库（页面右上角 Fork 按钮），课程 README 00-course-setup/README.md 也要求先 Fork 才能修改代码并完成挑战。
2. 在你的 fork 中，点击 Code ▸ Codespaces ▸ Create codespace on main。

随后浏览器中会打开一个 VS Code 窗口，dev container 开始构建，首次约需 2 分钟。

2.1 容器构建的幕后细节

devcontainer.json 定义了 Codespace 的完整配方，关键配置如下：

{
    "name": "Generative AI For Beginners",
    // 采用通用镜像：Python 3 / Node.js / .NET / Java 均预装
    "image": "mcr.microsoft.com/devcontainers/universal:2.13",
    "hostRequirements": { "cpus": 4 },      // 要求至少 4 核
    "waitFor": "onCreateCommand",
    "updateContentCommand": "python3 -m pip install -r requirements.txt", // 拉取新代码后重装 Python 依赖
    "postCreateCommand": "bash .devcontainer/post-create.sh",             // 容器创建后执行初始化脚本
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-python.python",
                "ms-python.vscode-pylance",
                "ms-toolsai.jupyter",
                "ms-python.black-formatter",
                "charliermarsh.ruff",
                "dbaeumer.vscode-eslint",
                "esbenp.prettier-vscode",
                "github.copilot"
            ]
        }
    }
}

两个阶段命令共同完成环境装配：

• updateContentCommand 执行 pip install -r requirements.txt，而 requirements.txt 锁定了课程全部 Python 依赖：ipywidgets、numpy、matplotlib、pandas、tqdm、python-dotenv、openai>=1.12.0、tiktoken、azure-ai-inference、scikit-learn。
• postCreateCommand 触发 post-create.sh，脚本中额外安装 python-dotenv、openai，以及开发者工具链 ruff、black、mypy、pytest——注释说明这套工具链与 CI 中 code-quality.yml 的检查一致，保证本地可复现 CI 结果。

因此文档中"首次约 2 分钟"的等待，正是上述镜像拉取 + 依赖安装的过程；"waitFor": "onCreateCommand" 保证初始化命令执行完毕前 VS Code 不会提前进入。

3. 安全地添加 API 密钥

课程代码需要调用 LLM API，密钥管理提供了两条路径，文档明确推荐选项 A。

3.1 选项 A：Codespaces Secrets（推荐）

1. ⚙️ 齿轮图标 -> Command Palette -> Codespaces: Manage user secret -> Add a new secret。
2. 名称（Name）：OPENAI_API_KEY。
3. 值（Value）：粘贴你的密钥，点击 Add secret。

至此完成——代码会自动拾取该密钥。这种方式下密钥存放在 GitHub 的用户级密钥库中，注入容器环境变量，不会落盘到仓库工作区，也无需担心误提交。

3.2 选项 B：.env 文件（确实需要时）

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

仓库根目录的 .env.copy 是一份带注释的完整模板，覆盖了课程涉及的全部供应商变量：

# OpenAI Provider
OPENAI_API_KEY='<add your OpenAI API key here>'

# Azure OpenAI in Microsoft Foundry
AZURE_OPENAI_API_VERSION='2024-10-21'
AZURE_OPENAI_API_KEY='<add your Foundry resource key here>'
AZURE_OPENAI_ENDPOINT='<add your Foundry resource endpoint here>'
AZURE_OPENAI_DEPLOYMENT='<add your chat completion model deployment name here>'
AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='<add your embeddings model deployment name here>'

# Microsoft Foundry Models
AZURE_INFERENCE_ENDPOINT='<add your Microsoft Foundry project endpoint here>'
AZURE_INFERENCE_CREDENTIAL='<add your Microsoft Foundry Models API key here>'

# Hugging Face
HUGGING_FACE_API_KEY='<add your HuggingFace API or token here>'

注意模板注释提示：GitHub Models（及其 GITHUB_TOKEN 变量）将于 2026 年 7 月底退役，仓库已转向 Microsoft Foundry Models 体系，因此 .env 中除了 OPENAI_API_KEY 还可能用到 AZURE_INFERENCE_ENDPOINT / AZURE_INFERENCE_CREDENTIAL 等变量，具体获取方式参见 00-course-setup/03-providers.md。使用 .env 路径时务必注意它已被 .gitignore 忽略，不要把真实密钥提交进仓库。

3.3 代码如何消费这些环境变量

"代码会自动拾取密钥"并非黑话，仓库有统一的实现。shared/python/env_utils.py 提供了 get_required_env：

def get_required_env(var_name: str, description: str | None = None) -> str:
    value = os.getenv(var_name)
    if not value:
        desc_part = f" ({description})" if description else ""
        raise ValueError(
            f"Missing required environment variable: {var_name}{desc_part}. "
            f"Please set it in your .env file or environment."
        )
    return value

同文件的 validate_env_vars 则支持一次校验多个变量（如 AZURE_OPENAI_ENDPOINT + AZURE_OPENAI_API_KEY），任一缺失即抛出带明确提示的 ValueError。也就是说：无论你通过 Codespaces Secrets 还是 .env 提供变量，只要最终出现在进程环境变量中，课程的示例脚本就能取到；缺失时会得到可定位的错误信息而非静默失败。而把 .env 载入进程环境的正是 requirements.txt 中固定的 python-dotenv==1.2.2，脚本内以 load_dotenv() 完成加载（用法示例见 00-course-setup/README.md）。

4. 配额管理与故障排查

配额管理：Codespace 处于"运行中"状态时才消耗 core-hours。空闲时通过 View ▸ Command Palette ▸ Codespaces: Stop Codespace 停止，或直接删除不再使用的 codespace，是保住每月 120 core-hours / 60 GB-hours 免费额度的最佳实践。

课程 00-course-setup/README.md 的 Troubleshooting 一节给出了云环境常见症状与修复方式，可直接作为排障清单：

症状	修复
容器构建卡住超过 10 分钟	Codespaces ➜ Rebuild Container
python: command not found	终端未附加；点击 + ➜ bash
OpenAI 返回 401 Unauthorized	OPENAI_API_KEY 错误或已过期
VS Code 显示 "Dev container mounting…"	刷新浏览器标签页（连接偶尔丢失）
Notebook 缺少 kernel	Notebook 菜单 ➜ Kernel ▸ Select Kernel ▸ Python 3

5. 与本地方案的关系及后续路径

本文档与 00-course-setup/02-setup-local.md 构成互补：后者面向"愿意在自己笔记本上跑"的读者，提供原生 Python 虚拟环境、VS Code Dev Container（Docker）、Miniconda 等选项；两者最终汇入同一批课程代码，且本地 Dev Container 方案复用同一份 devcontainer.json，因此不存在依赖漂移。如果你已具备容器经验，本地容器路线与本文云路线的环境是完全一致的。

环境就绪后，按 00-course-setup/README.md 的指引进入 01-introduction-to-genai 开始第一课；密钥供应商的具体申请与配置细节，继续参考 00-course-setup/03-providers.md。