generative-ai-for-beginners 云环境配置指南用 GitHub Codespaces 零安装跑通全部课程代码【免费下载链接】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的云端配置文档01-setup-cloud.md 原文为意大利语版云环境教程系统讲解如何在不安装任何本地依赖的前提下通过 GitHub Codespaces 一键获得预装好 Python、Node.js、.NET、Java 等运行时与课程全部依赖的云端 VS Code 开发环境并将 LLM API Key 以 Secrets 或.env两种安全方式注入。读完本文你将理解该仓库 dev container 的自动配置链路devcontainer.json→post-create.sh→requirements.txt掌握配额管理技巧并能独立完成从 Fork 仓库到运行第一个课程 Notebook 的完整流程。1. 为什么选择 Codespaces云端方案适用于所有不便在本地安装开发环境的场景Chromebook、iPad、学校机房电脑等。官方文档给出了三条核心理由本文完整继承并补充了配额管理细节优势对你的实际意义零安装可运行于 Chromebook、iPad、学校机房 PC 等任意有浏览器的设备预构建 dev containerPython 3、Node.js、.NET、Java 运行时已内置依赖由仓库脚本自动安装免费配额个人账户每月120 core-hours / 60 GB-hours配额管理建议闲置的 codespace 会持续消耗配额。保持配额健康的做法是使用完工作区后停止Stop或直接删除闲置 codespace操作路径为View ▸ Command Palette ▸Codespaces: Stop Codespace。补充说明dev container 声明了 4 核 CPU 的宿主机要求见下文hostRequirementscodespace 的运行时长会按实际规格折算 core-hours因此及时停止闲置环境对配额控制尤为关键。2. dev container 的自动配置链路源码级拆解文档中说打开浏览器 VS Code 后 dev container 开始构建首次约 2 分钟。这个过程的每一步都由仓库根目录下的.devcontainer/配置文件驱动读源码可以精确知道等待期间发生了什么。2.1 容器规格.devcontainer/devcontainer.json{ name: Generative AI For Beginners, image: mcr.microsoft.com/devcontainers/universal:2.13, hostRequirements: { cpus: 4 }, waitFor: onCreateCommand, updateContentCommand: python3 -m pip install -r requirements.txt, 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 ] } } }逐项解读image: mcr.microsoft.com/devcontainers/universal:2.13采用微软官方 Universal Dev Container 镜像这正是文档中Python 3、Node.js、.NET、Java 已内置承诺的来源——通用镜像一次性打包了多语言运行时无需逐个安装。hostRequirements.cpus: 4要求宿主机至少 4 核低于此规格 Codespaces 会提示无法启动。updateContentCommand容器就绪后执行pip install -r requirements.txt安装课程全部 Python 依赖。该命令在每次容器重建update时都会执行保证依赖版本与仓库同步。postCreateCommand容器首次创建后执行bash .devcontainer/post-create.sh补齐requirements.txt未覆盖的依赖见 2.2。waitFor: onCreateCommandVS Code 界面会等待上述安装命令完成后再就绪即首次约 2 分钟的等待来源。customizations.vscode.extensions自动安装 Python、Pylance、Jupyter、Black、Ruff、ESLint、Prettier 与 GitHub Copilot 扩展同时把 Python 默认格式化器设为 Black、JavaScript/TypeScript 设为 Prettier并开启formatOnSave——这与仓库 CI 中 code-quality 工作流 执行的 lint/format 检查保持一致学员在云端产出的代码开箱即符合贡献规范。2.2 安装脚本.devcontainer/post-create.sh# Install OpenAI and Dotenv for Python pip install python-dotenv pip install openai # Install developer tooling for linting, formatting, type-checking, and tests. # These match the checks run in .github/workflows/code-quality.yml so # contributors can reproduce them locally before opening a pull request. pip install ruff black mypy pytest脚本注释明确说明安装的ruff、black、mypy、pytest与 CI 质量检查一一对应让贡献者在提交 PR 前可以在本地复现 CI 结果。python-dotenv的安装则直接服务于第 4 节.env方式——课程脚本靠它读取本地环境文件。2.3 依赖清单requirements.txtupdateContentCommand安装的完整依赖为ipywidgets8.1.8 numpy2.4.2 matplotlib3.10.8 pandas3.0.0 tqdm4.68.4 python-dotenv1.2.2 openai1.12.0 tiktoken azure-ai-inference scikit-learn注意python-dotenv与openai在此处均已声明openai1.12.0、python-dotenv1.2.2post-create.sh中再次pip install属于双重保险。另外根目录 .python-version 锁定 Python 版本为3.12.10.devcontainer/environment.yml 额外提供 Conda 环境定义python3.10.0、openai、python-dotenv、azure-ai-inference供偏好 conda 工作流的学员参考。3. 一键创建 Codespace文档给出的创建流程只有两步Fork 仓库点击右上角Fork按钮把generative-ai-for-beginners复制到你的 GitHub 账户课程要求在自己 fork 下改代码、完成练习。在你的 fork 中点击Code ▸ Codespaces ▸ Create codespace on main对应上图中的绿色按钮面板底部会显示该仓库 codespace 费用的承担方个人免费账户走月度免费配额。点击后浏览器中打开 VS Code 窗口dev container 按第 2 节的链路自动构建。首次创建约需 2 分钟期间 VS Code 处于加载状态属正常现象等待onCreateCommand完成即可waitFor机制保证了依赖装完才放行。4. 安全注入 API Key课程代码调用 LLM 必须持有密钥。文档提供两种方式推荐优先级依次为 A B。选项 ACodespaces Secrets推荐点击 VS Code 左下角 ⚙️ 齿轮图标 → 打开 Command Palette → 执行Codespaces: Manage user secret→Add a new secret名称填OPENAI_API_KEY值粘贴你的 API 密钥 → 点击Add secret。即完成——课程代码会自动发现该变量。其原理在第 5 节源码层面验证Codespaces Secrets 会在 codespace 环境中注入为同名环境变量代码通过os.getenv读取全程不落在磁盘上天然避免密钥被提交进 Git。选项 B.env文件确有需要时cp .env.copy .env code .env # fill in OPENAI_API_KEYyour_key_here仓库根目录的模板 .env.copy 声明了全部课程所需的环境变量复制后可按所选 Provider 填写变量用途备注OPENAI_API_KEYOpenAI 直连最简单仅需一项AZURE_OPENAI_API_VERSIONAzure OpenAI API 版本模板默认2024-10-21AZURE_OPENAI_API_KEY/AZURE_OPENAI_ENDPOINTAzure OpenAIMicrosoft Foundry资源密钥与端点端点形如https://resource-name.openai.azure.comAZURE_OPENAI_DEPLOYMENT对话补全模型部署名例gpt-4o-miniAZURE_OPENAI_EMBEDDINGS_DEPLOYMENT嵌入模型部署名例text-embedding-3-smallAZURE_INFERENCE_ENDPOINT/AZURE_INFERENCE_CREDENTIALMicrosoft Foundry Models多供应商目录取代即将退役的 GitHub Models从项目 Overview 页获取HUGGING_FACE_API_KEYHugging Face部分课程 Notebook 使用安全前提.gitignore已把.env列入忽略.gitignore 第 122–129 行# Environments段落因此即使填写真实密钥也不会误提交但相比之下选项 A 连文件都不落盘故仍为首选。5. 代码为什么能自动发现密钥源码级验证文档中代码会自动捡取 Secret并非空话仓库共享工具层的实现可以逐层印证。5.1 读取入口shared/python/env_utils.pyget_required_env(var_name, descriptionNone)L11–L35调用os.getenv(var_name)若变量缺失或为空抛出带引导信息的ValueError提示请在 .env 文件或环境中设置。因此无论密钥来自 Codespaces Secrets注入为环境变量还是.env文件由python-dotenv读入环境对代码而言都是同一条os.getenv路径validate_env_vars(*var_names)L38–L71批量校验多个变量如 Azure 场景需同时具备AZURE_OPENAI_ENDPOINT与AZURE_OPENAI_API_KEY一次性报出全部缺失项get_env_with_default(var_name, default)L74–L88带默认值读取例如模型名MODEL_NAME缺省回退。5.2 客户端构造shared/python/api_utils.pycreate_openai_clientL56–L88的关键逻辑key api_key or os.getenv(OPENAI_API_KEY) if not key: raise ValueError( OpenAI API key is required. Set OPENAI_API_KEY environment variable or pass api_key parameter. ) return OpenAI(api_keykey)即显式传参优先其次读OPENAI_API_KEY环境变量两者皆无则给出可操作的错误提示。同文件的create_azure_openai_clientL91 起则以同样模式读取AZURE_OPENAI_ENDPOINT/AZURE_OPENAI_API_KEY并固定走endpoint/openai/v1/的 v1 端点。这解释了第 4 节两种注入方式对课程代码完全等价的原因。此外部分课程脚本如 09-building-image-applications/python/aoai-app.py 开头会先执行dotenv.load_dotenv()这依赖的就是requirements.txt中安装的python-dotenv1.2.2与选项 B 的.env方案形成闭环。6. 常见问题排查云端环境偶发的连接/依赖问题课程总览页 00-course-setup/README.md 附有一张官方故障排查表一并收录在此症状处理方法容器构建卡住超过 10 分钟Codespaces 菜单 ➜Rebuild Container终端报python: command not found终端未挂接点击➜ 选bashOpenAI 返回401 UnauthorizedOPENAI_API_KEY错误或已过期VS Code 显示 Dev container mounting…刷新浏览器标签页Codespaces 偶发掉线Notebook 找不到内核Notebook 菜单 ➜Kernel ▸ Select Kernel ▸ Python 3小结本文以课程仓库的云配置文档为主线先用官方文档的三步流程Fork → 一键创建 codespace → 注入 API Key完成可运行的云端环境再沿devcontainer.json→post-create.sh→requirements.txt的配置链路还原2 分钟构建背后发生了什么并用 shared/python/env_utils.py 与 shared/python/api_utils.py 的源码证明了 Secrets 与.env两种方式最终殊途同归地汇入os.getenv读取路径。完成上述配置后即可进入课程第 1 课 01-introduction-to-genai 开始动手实践若你更倾向本地环境或需要更换 LLM 供应商可分别参考同目录的 02-setup-local.md 与 03-providers.md。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考