generative-ai-for-beginners 零本地安装起步用 GitHub Codespaces 一键搭建生成式 AI 云端开发环境【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners关联文档translations/fa/00-course-setup/01-setup-cloud.md波斯语译本英文原版见 00-course-setup/01-setup-cloud.md本指南面向所有不想在本机安装任何依赖的读者讲解如何基于 generative-ai-for-beginners 这门 21 课时的生成式 AI 入门课程用 GitHub Codespaces 获得一个浏览器内、开箱即用的 VS Code 云端开发环境。读完本文你将掌握从 Fork 仓库到一键创建 Codespaces、再到用 Codespaces Secrets 安全注入OPENAI_API_KEY的完整流程并能理解仓库代码如何自动读取这些环境变量——从而无缝开始后续各课的动手练习。1. 为什么要使用 Codespaces零安装与免费配额在这门课程中绝大多数动手练习Notebook、Python 脚本、JavaScript/TypeScript 示例都需要 Python 3、Node.js 等运行时以及openai、python-dotenv等依赖。如果在本机逐一配置环境很容易在 Chromebook、iPad、学校机房电脑等受限设备上卡住。使用 Codespaces 恰好绕开了这个问题。按 00-course-setup/01-setup-cloud.md 的说明其核心收益可归纳为下表优势对学习者的实际意义✅ 无需任何本地安装在 Chromebook、iPad、学校实验室电脑上均可直接使用✅ 预构建的开发容器Python 3、Node.js、.NET、Java 等运行时已内置✅ 免费配额个人账户每月可获120 核时 / 60 GB 时120 core-hours / 60 GB-hours除了上述收益从仓库代码结构看课程还附带了配套的共享工具包shared/python/与完善的单元测试tests/说明该课程的练习对依赖齐全、命令可复现的开发环境要求较高——这正是 Codespaces 这类预置容器环境的用武之地。省额提示为保住每月免费配额请及时停止或删除不再使用的 Codespaces打开View ▸ Command Palette执行Codespaces: Stop Codespace即可。2. 一键创建 Codespace创建过程完全在浏览器内完成无需安装任何命令行工具整体流程如下在仓库页面右上角点击Fork将本仓库 fork 到自己的 GitHub 账号下fork 后可自由修改代码、完成课程中的挑战在你的 fork 中点击Code ▸ Codespaces ▸ Create codespace on main。点击后浏览器会打开一个 VS Code 窗口云端开发容器随即开始构建。首次构建大约需要2 分钟此后再次打开同一 Codespace 会明显更快。容器构建完成后终端、Python 解释器、Jupyter/Notebook 支持等都已就绪可直接进入对应课程的目录运行代码。补充说明如果你选择不适用云端环境而是本机运行请参考配套的 00-course-setup/02-setup-local.md00-course-setup/README.md 中整理了完整的容器构建卡住超 10 分钟 → 执行 Codespaces ➜ Rebuild ContainerNotebook 内核缺失 → Notebook 菜单 ➜ Kernel ▸ Select Kernel ▸ Python 3等常见故障排查对照表遇到问题时可按表操作。3. 安全地注入 API 密钥Codespaces Secrets课程中的多数动手任务需要调用 LLM 服务商的云端端点仓库约定通过OPENAI_API_KEY等环境变量传递凭证服务商注册与各变量含义详见 00-course-setup/03-providers.md。在云端环境中暴露明文密钥是不可取的文档推荐两种方式按安全性优先排序如下。方法 ACodespaces Secrets推荐Codespaces Secrets 将密钥加密保存在你的 GitHub 账号/仓库级别只在运行时注入容器不会出现在仓库文件或提交历史里。配置步骤点击左下角齿轮 ⚙️ 图标 → 打开 Command Palette → 执行Codespaces: Manage user secret→ 选择Add a new secretName填OPENAI_API_KEYValue粘贴你的真实 API 密钥 → 点击Add secret。完成后无需任何额外配置课程代码会在运行时自动找到这个变量。这正是方法 A 被称为 Recommended 的原因密钥既不落盘、不随 fork 传播也不会被误提交。方法 B.env文件仅在确有需要时如果某些场景确实需要本地方案例如在 Docker Desktop 而非 Codespaces 中运行可改用.env文件cp .env.copy .env code .env # 填入 OPENAI_API_KEYyour_key_here仓库根目录的 .env.copy 是官方提供的环境变量模板除OPENAI_API_KEY外还预置了本课程全部可用的服务商变量占位包括# OpenAI Provider OPENAI_API_KEYadd your OpenAI API key here # Azure OpenAI现归属于 Microsoft Foundry见 ai.azure.com AZURE_OPENAI_API_VERSION2024-10-21 # 默认值已设置当前稳定 GA API 版本 AZURE_OPENAI_API_KEYadd your Foundry resource key here AZURE_OPENAI_ENDPOINTadd your Foundry resource endpoint here, e.g. https://resource-name.openai.azure.com AZURE_OPENAI_DEPLOYMENTadd your chat completion model deployment name here, e.g. gpt-4o-mini AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTadd your embeddings model deployment name here, e.g. text-embedding-3-small # Microsoft Foundry Models多模型目录单端点 单密钥访问 OpenAI、Meta、Mistral 等 AZURE_INFERENCE_ENDPOINTadd your Microsoft Foundry project endpoint here AZURE_INFERENCE_CREDENTIALadd your Microsoft Foundry Models API key here # Hugging Face HUGGING_FACE_API_KEYadd your HuggingFace API or token here.env本身已被仓库的.gitignore忽略从而避免密钥被提交进版本库。需要留意的是方法 B 主要面向不使用 Codespaces 的场景若你坚持用 Codespaces 又想走.env务必确认该文件不会被提交到 fork 中。关于每个变量的取值位置与获取步骤请对照 00-course-setup/03-providers.md 中的说明逐一填写。4. 仓库代码是如何自动找到这些密钥的为什么填好变量就万事大吉从源码可以印证环境变量约定是课程代码的统一入口。首先shared/python/env_utils.py 提供了三组环境变量读取工具get_required_env(var_name, description)读取必需变量若未设置或为空抛出带变量名与用途说明的ValueErrorvalidate_env_vars(*var_names)一次性校验多个变量将缺失项汇总后统一报错便于快速定位配置遗漏get_env_with_default(var_name, default)读取带默认值的可选变量。其次shared/python/api_utils.py 中的客户端工厂函数会在调用时直接读取环境变量构造 OpenAI 客户端create_openai_client()当未显式传入api_key时自动读取os.getenv(OPENAI_API_KEY)缺失则抛出引导性错误create_azure_openai_client()自动读取AZURE_OPENAI_ENDPOINT与AZURE_OPENAI_API_KEY并拼接为endpoint/openai/v1/的 v1 端点。换言之无论你用 Codespaces Secrets方法 A把OPENAI_API_KEY注入环境还是用.env方法 B配合python-dotenv加载对上层代码而言都是同一个os.getenv读取路径——这正是文档里Thats it—our code will pick it up automatically背后真正的实现机制。这些约定不是拍脑袋定的仓库在 tests/test_env_utils.py 中为上述行为编写了完整测试例如缺失变量时断言抛出包含变量名的ValueErrortest_get_required_env_missing_raises、空值同样报错test_get_required_env_empty_raises、validate_env_vars会一次性汇总所有缺失项test_validate_env_vars_reports_all_missing。因此若运行某个作业时报Missing required environment variable: OPENAI_API_KEY直接对照报错信息检查对应的 Secrets 或.env配置即可。5. 验证环境并开始第一课完成密钥注入后可在 Codespaces 终端中执行以下命令快速验证# 确认环境变量已注入注意不要在任何地方打印真实密钥值 python -c import os; print(OPENAI_API_KEY is set:, bool(os.getenv(OPENAI_API_KEY)))确认输出为OPENAI_API_KEY is set: True后即可回到课程主目录开始学习。课程 21 个课时的目录与动手 Notebook 都位于仓库根目录下的NN-lesson-name/python/*.ipynb例如第一课课程导览与学习路径总览见 00-course-setup/README.md正式内容从第一课 01-introduction-to-genai/README.md生成式 AI 与 LLM 入门开始其中包含带aoai、oai、githubmodels、hf前缀标识的作业文件分别对应 Azure OpenAI、OpenAI、Microsoft Foundry Models、Hugging Face 等不同服务商——你在第 3 节配置的密钥决定了哪些作业可以直接运行若某门课要求你先在某个服务商开通账户、再配置对应变量请先阅读 00-course-setup/03-providers.md 完成.env或 Secrets 的补齐。至此一条Fork → Codespaces → 注入密钥 → 跑通第一课的云端学习链路已经打通。接下来你可以随时停止不用的 Codespace 以节省配额也可以在此基础上选择本地环境00-course-setup/02-setup-local.md与其余服务商作为进阶选项。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 generative-ai-for-beginners 零本地安装起步：用 GitHub Codespaces 一键搭建生成式 AI 云端开发环境
generative-ai-for-beginners 零本地安装起步用 GitHub Codespaces 一键搭建生成式 AI 云端开发环境【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners关联文档translations/fa/00-course-setup/01-setup-cloud.md波斯语译本英文原版见 00-course-setup/01-setup-cloud.md本指南面向所有不想在本机安装任何依赖的读者讲解如何基于 generative-ai-for-beginners 这门 21 课时的生成式 AI 入门课程用 GitHub Codespaces 获得一个浏览器内、开箱即用的 VS Code 云端开发环境。读完本文你将掌握从 Fork 仓库到一键创建 Codespaces、再到用 Codespaces Secrets 安全注入OPENAI_API_KEY的完整流程并能理解仓库代码如何自动读取这些环境变量——从而无缝开始后续各课的动手练习。1. 为什么要使用 Codespaces零安装与免费配额在这门课程中绝大多数动手练习Notebook、Python 脚本、JavaScript/TypeScript 示例都需要 Python 3、Node.js 等运行时以及openai、python-dotenv等依赖。如果在本机逐一配置环境很容易在 Chromebook、iPad、学校机房电脑等受限设备上卡住。使用 Codespaces 恰好绕开了这个问题。按 00-course-setup/01-setup-cloud.md 的说明其核心收益可归纳为下表优势对学习者的实际意义✅ 无需任何本地安装在 Chromebook、iPad、学校实验室电脑上均可直接使用✅ 预构建的开发容器Python 3、Node.js、.NET、Java 等运行时已内置✅ 免费配额个人账户每月可获120 核时 / 60 GB 时120 core-hours / 60 GB-hours除了上述收益从仓库代码结构看课程还附带了配套的共享工具包shared/python/与完善的单元测试tests/说明该课程的练习对依赖齐全、命令可复现的开发环境要求较高——这正是 Codespaces 这类预置容器环境的用武之地。省额提示为保住每月免费配额请及时停止或删除不再使用的 Codespaces打开View ▸ Command Palette执行Codespaces: Stop Codespace即可。2. 一键创建 Codespace创建过程完全在浏览器内完成无需安装任何命令行工具整体流程如下在仓库页面右上角点击Fork将本仓库 fork 到自己的 GitHub 账号下fork 后可自由修改代码、完成课程中的挑战在你的 fork 中点击Code ▸ Codespaces ▸ Create codespace on main。点击后浏览器会打开一个 VS Code 窗口云端开发容器随即开始构建。首次构建大约需要2 分钟此后再次打开同一 Codespace 会明显更快。容器构建完成后终端、Python 解释器、Jupyter/Notebook 支持等都已就绪可直接进入对应课程的目录运行代码。补充说明如果你选择不适用云端环境而是本机运行请参考配套的 00-course-setup/02-setup-local.md00-course-setup/README.md 中整理了完整的容器构建卡住超 10 分钟 → 执行 Codespaces ➜ Rebuild ContainerNotebook 内核缺失 → Notebook 菜单 ➜ Kernel ▸ Select Kernel ▸ Python 3等常见故障排查对照表遇到问题时可按表操作。3. 安全地注入 API 密钥Codespaces Secrets课程中的多数动手任务需要调用 LLM 服务商的云端端点仓库约定通过OPENAI_API_KEY等环境变量传递凭证服务商注册与各变量含义详见 00-course-setup/03-providers.md。在云端环境中暴露明文密钥是不可取的文档推荐两种方式按安全性优先排序如下。方法 ACodespaces Secrets推荐Codespaces Secrets 将密钥加密保存在你的 GitHub 账号/仓库级别只在运行时注入容器不会出现在仓库文件或提交历史里。配置步骤点击左下角齿轮 ⚙️ 图标 → 打开 Command Palette → 执行Codespaces: Manage user secret→ 选择Add a new secretName填OPENAI_API_KEYValue粘贴你的真实 API 密钥 → 点击Add secret。完成后无需任何额外配置课程代码会在运行时自动找到这个变量。这正是方法 A 被称为 Recommended 的原因密钥既不落盘、不随 fork 传播也不会被误提交。方法 B.env文件仅在确有需要时如果某些场景确实需要本地方案例如在 Docker Desktop 而非 Codespaces 中运行可改用.env文件cp .env.copy .env code .env # 填入 OPENAI_API_KEYyour_key_here仓库根目录的 .env.copy 是官方提供的环境变量模板除OPENAI_API_KEY外还预置了本课程全部可用的服务商变量占位包括# OpenAI Provider OPENAI_API_KEYadd your OpenAI API key here # Azure OpenAI现归属于 Microsoft Foundry见 ai.azure.com AZURE_OPENAI_API_VERSION2024-10-21 # 默认值已设置当前稳定 GA API 版本 AZURE_OPENAI_API_KEYadd your Foundry resource key here AZURE_OPENAI_ENDPOINTadd your Foundry resource endpoint here, e.g. https://resource-name.openai.azure.com AZURE_OPENAI_DEPLOYMENTadd your chat completion model deployment name here, e.g. gpt-4o-mini AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTadd your embeddings model deployment name here, e.g. text-embedding-3-small # Microsoft Foundry Models多模型目录单端点 单密钥访问 OpenAI、Meta、Mistral 等 AZURE_INFERENCE_ENDPOINTadd your Microsoft Foundry project endpoint here AZURE_INFERENCE_CREDENTIALadd your Microsoft Foundry Models API key here # Hugging Face HUGGING_FACE_API_KEYadd your HuggingFace API or token here.env本身已被仓库的.gitignore忽略从而避免密钥被提交进版本库。需要留意的是方法 B 主要面向不使用 Codespaces 的场景若你坚持用 Codespaces 又想走.env务必确认该文件不会被提交到 fork 中。关于每个变量的取值位置与获取步骤请对照 00-course-setup/03-providers.md 中的说明逐一填写。4. 仓库代码是如何自动找到这些密钥的为什么填好变量就万事大吉从源码可以印证环境变量约定是课程代码的统一入口。首先shared/python/env_utils.py 提供了三组环境变量读取工具get_required_env(var_name, description)读取必需变量若未设置或为空抛出带变量名与用途说明的ValueErrorvalidate_env_vars(*var_names)一次性校验多个变量将缺失项汇总后统一报错便于快速定位配置遗漏get_env_with_default(var_name, default)读取带默认值的可选变量。其次shared/python/api_utils.py 中的客户端工厂函数会在调用时直接读取环境变量构造 OpenAI 客户端create_openai_client()当未显式传入api_key时自动读取os.getenv(OPENAI_API_KEY)缺失则抛出引导性错误create_azure_openai_client()自动读取AZURE_OPENAI_ENDPOINT与AZURE_OPENAI_API_KEY并拼接为endpoint/openai/v1/的 v1 端点。换言之无论你用 Codespaces Secrets方法 A把OPENAI_API_KEY注入环境还是用.env方法 B配合python-dotenv加载对上层代码而言都是同一个os.getenv读取路径——这正是文档里Thats it—our code will pick it up automatically背后真正的实现机制。这些约定不是拍脑袋定的仓库在 tests/test_env_utils.py 中为上述行为编写了完整测试例如缺失变量时断言抛出包含变量名的ValueErrortest_get_required_env_missing_raises、空值同样报错test_get_required_env_empty_raises、validate_env_vars会一次性汇总所有缺失项test_validate_env_vars_reports_all_missing。因此若运行某个作业时报Missing required environment variable: OPENAI_API_KEY直接对照报错信息检查对应的 Secrets 或.env配置即可。5. 验证环境并开始第一课完成密钥注入后可在 Codespaces 终端中执行以下命令快速验证# 确认环境变量已注入注意不要在任何地方打印真实密钥值 python -c import os; print(OPENAI_API_KEY is set:, bool(os.getenv(OPENAI_API_KEY)))确认输出为OPENAI_API_KEY is set: True后即可回到课程主目录开始学习。课程 21 个课时的目录与动手 Notebook 都位于仓库根目录下的NN-lesson-name/python/*.ipynb例如第一课课程导览与学习路径总览见 00-course-setup/README.md正式内容从第一课 01-introduction-to-genai/README.md生成式 AI 与 LLM 入门开始其中包含带aoai、oai、githubmodels、hf前缀标识的作业文件分别对应 Azure OpenAI、OpenAI、Microsoft Foundry Models、Hugging Face 等不同服务商——你在第 3 节配置的密钥决定了哪些作业可以直接运行若某门课要求你先在某个服务商开通账户、再配置对应变量请先阅读 00-course-setup/03-providers.md 完成.env或 Secrets 的补齐。至此一条Fork → Codespaces → 注入密钥 → 跑通第一课的云端学习链路已经打通。接下来你可以随时停止不用的 Codespace 以节省配额也可以在此基础上选择本地环境00-course-setup/02-setup-local.md与其余服务商作为进阶选项。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考