用 GitHub Codespaces 免安装跑通生成式 AI 课程：generative-ai-for-beginners 云端环境搭建实战

用 GitHub Codespaces 免安装跑通生成式 AI 课程：generative-ai-for-beginners 云端环境搭建实战

【免费下载链接】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 课程仓库中的「课程环境准备 · 云端方案」文档（对应仓库 translations/et/00-course-setup/01-setup-cloud.md 与 00-course-setup/01-setup-cloud.md 的同主题英文原文）整理而成。核心回答一个问题：不想在本地装任何依赖时，如何用 GitHub Codespaces 在几分钟内获得一个 Python、Node.js、.NET、Java 全就绪的浏览器版 VS Code。读完你将掌握：一键 Fork 并创建 Codespace 的完整路径、课程预构建开发容器的真实配置、以及用 Codespaces Secrets 安全注入OPENAI_API_KEY（或回退到.env文件）的正确姿势，并了解常见故障的排查思路。

一、为什么这套课程建议直接上云？

本仓库是一个包含 21 讲内容的生成式 AI（GenAI）入门课程，动手环节覆盖 Python 文本生成应用、聊天机器人、向量检索、图像生成、函数调用、微调等，依赖涉及 OpenAI SDK、Azure OpenAI、tiktoken、dotenv 等多种环境。如果在本地逐一手动配置，很容易在依赖版本、虚拟环境上消耗大量时间。因此课程配套的环境说明给出了一条"云端零安装"路径，其理由可以概括为下表：

配额健康提醒

💡 保持配额健康的办法是及时停止（Stop）或删除（Delete）闲置的 Codespace，操作路径为：View ▸ Command Palette ▸Codespaces: Stop Codespace。容器虽然可以随时重建，但一直挂机的容器会持续消耗月度配额。

“预配置开发容器”并非一句口号，仓库根目录下的 .devcontainer/devcontainer.json 就是实打实的构建配方。从该文件可以看到：

• 使用官方通用镜像mcr.microsoft.com/devcontainers/universal:2.13——这是 GitHub Codespaces 的通用开发容器模板（基于 github/codespaces-jupyter 起步），Python、Node.js、.NET、Java、Jupyter 等运行时均已预装；
• 宿主要求至少cpus: 4，说明容器构建与后续跑模型推理时对算力有基本预期；
• updateContentCommand会在内容拉取后执行python3 -m pip install -r requirements.txt，即课程根目录 requirements.txt 中锁定的依赖（openai>=1.12.0、python-dotenv、tiktoken、azure-ai-inference、numpy、pandas、ipywidgets、scikit-learn等）会被自动安装；
• postCreateCommand会继续执行 .devcontainer/post-create.sh，补齐python-dotenv、openai以及ruff black mypy pytest等开发工具链；
• customizations.vscode段会预装ms-python.python、ms-python.vscode-pylance、ms-toolsai.jupyter、ms-python.black-formatter、charliermarsh.ruff、dbaeumer.vscode-eslint、esbenp.prettier-vscode等扩展，并开启保存即格式化，让入门者直接获得接近工程化的编辑体验。

这意味着你在浏览器里打开的那一刻，各章节示例代码的运行环境已经基本就绪，唯一需要你自己提供的就是后续提到的 API Key。

二、一键创建你的第一个 Codespace

整套流程只有两步，全程不需要本地命令行：

1. Fork 本仓库：点击仓库右上角的Fork按钮，把它复制到自己的 GitHub 账户下（Fork 之后你才能自由修改代码、提交作业）；
2. 在自己的 Fork 上创建 Codespace：点击Code ▸ Codespaces ▸ Create codespace on main，如上图所示，在 Codespaces 标签页中点击绿色Create codespace on main按钮。

操作完成后，浏览器会打开一个基于 VS Code 的窗口，并开始构建开发容器。首次构建大约需要2 分钟（取决于网络与镜像拉取速度），之后再次打开基本是秒级恢复。

课程配套的 00-course-setup/README.md 还给出了同一个流程的替代入口（Code → Codespaces → New on main），两者等价。如果不希望在云端而打算在本地运行，可参考同目录下的 00-course-setup/02-setup-local.md。

构建一旦卡住超过 10 分钟怎么办？详见文末「常见问题排查」章节，通常执行一次Rebuild Container即可恢复。

三、安全地注入 API Key：首选 Codespaces Secrets

课程代码（如各章的 Python 应用与 notebook）运行时需要读取 LLM 服务商凭据。把它们写进源码或普通文件是明显的安全隐患。课程给出了两种方案，其中方案 A 是官方推荐做法。

方案 A：Codespaces Secrets（推荐）

在浏览器版 VS Code 中完成以下三步，即可把 Key 配置成对当前用户生效的 Codespace 密文：

1. 点击左下角⚙️ 齿轮图标→Command Palette（命令面板）→ 执行Codespaces: Manage user secret（管理用户级 Secret）→ 选择Add a new secret；
2. Name填OPENAI_API_KEY（名称必须严格一致）；
3. Value粘贴你的 API Key → 点击Add secret保存。

完成后无需重启或额外配置——课程代码会自动从环境变量中识别这个值。需要说明的是：

• 这类 Secret 是按“用户级”存储在 GitHub 侧并被加密注入容器的，不会出现在仓库文件里，也不会被git提交；
• 它对你名下的所有 Codespace 统一生效，换新项目、重建容器都不必重配；
• 变量缺失时并非“静默失败”。仓库在 shared/python/env_utils.py 中提供了get_required_env(var_name, description)与validate_env_vars(*var_names)两个校验工具：若os.getenv(var_name)为空，会抛出包含变量名与提示信息的ValueError（如Missing required environment variable: OPENAI_API_KEY... Please set it in your .env file or environment.）。从源码结构可以推断，课程的 Python 示例正是通过这类工具统一读取环境变量，这也是“自动识别”能够成立的前提。

方案 B：.env文件（确有需要时的回退方案）

如果你处于无法使用 Codespaces Secrets 的场景（例如部分组织策略限制），也可以使用本地.env文件：

cp .env.copy .env code .env # 填入 OPENAI_API_KEY=your_key_here

命令执行完毕后，用 VS Code 打开.env补全密钥。仓库根目录的 .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' # 默认已填（当前稳定 GA 版本） 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（多厂商模型目录，一个端点同时覆盖 OpenAI/Meta/Mistral 等） 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>'

关于各服务商的注册与取值细节，课程在 00-course-setup/03-providers.md 中有专门说明（如何获取 OpenAI / Azure OpenAI / Microsoft Foundry Models 的端点与密钥），建议首次使用时对照阅读。

需要强调.env方案的几个使用前提：

• 复制后立即补全并妥善保管：.env是敏感文件，虽然已被仓库的.gitignore排除、不会被提交，但它以明文存放在工作区，务必注意保密；
• 依赖 dotenv 库：课程根目录 requirements.txt 及 .devcontainer/post-create.sh 都已包含python-dotenv，notebook 与脚本运行时无需额外安装；
• 两条路线不冲突：当环境中同时存在 Secrets 注入的变量与.env文件时，实际以你使用的 API 客户端（openai、azure-ai-inference等）默认读取逻辑为准。课程官方仍以**方案 A（Secrets）**为首选，因为它避免把任何明文密钥留在文件系统里。

四、打开容器后：验证环境与后续路径

容器构建完成、密钥就绪后，可以快速验证三件事：

1. Python 可用：在集成终端执行python --version，应看到容器内置的 Python 3；
2. 依赖可导入：执行python -c "import openai, dotenv; print('ok')"，无报错即表示 OpenAI SDK 与 dotenv 已就位；
3. Notebook 内核正常：若打开.ipynb提示无内核，在 Notebook 菜单执行Kernel ▸ Select Kernel ▸ Python 3即可（详见下文排查表）。

完成上述环境准备后，下一步就进入正式课程：

• 第一篇正文：01-introduction-to-genai/README.md（生成式 AI 与 LLM 入门）；
• 云端以外的备选路径：00-course-setup/02-setup-local.md（本地安装）与 00-course-setup/03-providers.md（配置 LLM 服务商）；
• 想要先动手跑代码的，可以从 06-text-generation-apps/python/ 下的文本生成示例开始。

五、常见问题排查（基于课程官方环境文档整理）

结合课程环境说明 00-course-setup/README.md 中维护的 Troubleshooting 表，把 Codespace 使用中最高频的几类问题整理如下：

另外把第一节提到的配额管理再强调一次：月度 120 核时 / 60 GB 时对轻度学习足够，但如果让多个容器长期挂机，很快就会被耗尽。用完即停（Codespaces: Stop Codespace）、长期不用即删，是保证整个学习周期配额不断档的最有效手段。

六、小结

对绝大多数“只想学 AI、不想折腾环境”的入门者而言，GitHub Codespaces 是把本课程跑起来成本最低的路径：Fork → Create codespace on main → 注入 Secret → 打开第 1 讲，全程只需一个浏览器和大约两分钟等待。需要说明的是，免费配额数值（120 核时 / 60 GB 时）与容器镜像版本均以官方实时政策与仓库当前配置为准，如遇变动请以 GitHub 当前文档与仓库.devcontainer配置为最终依据。

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