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 的 00-course-setup课程环境准备模块展开内容以课程主页 00-course-setup/README.md含其在 translations/fi 的本地化版本为骨架系统讲解通过 GitHub Codespaces 云端开发、配置 LLM Provider 密钥、以及在本地用 Python、Conda、Docker 与 Jupyter 运行课程代码的完整方法。读完本文你将掌握从 0 到 1 搭建一套可运行生成式 AI 示例代码的开发环境并能对照仓库内的源码与配置文件排查常见环境问题。课程与配套环境概览本仓库是一套循序渐进的生成式 AI 学习课程。根据根目录 README.md 的说明课程包含 21 个相互独立的课题每个课题既可顺序学习也可按需单独切入部分课程被标注为 Learn讲解概念部分被标注为 Build概念 可运行代码示例尽可能同时提供 Python 与 TypeScript 实现。课程中的编码练习分布在各个章节的python/、typescript/、js-githubmodels/、dotnet/等子目录中并以.py、.ipynb、.ts等文件形式存在。因此无论选择哪种运行方式一套能执行 Python、能加载 notebook、能安全保存 API 密钥的环境是整个学习过程的共同前提。这也是 00-course-setup/README.md 作为第 0 课存在的原因它不讲解算法或提示词而是先帮你把环境一次配好。一、快速开始路线图Fork → Codespaces → 注入密钥对于想跳过本地安装、立即动手写代码的读者官方推荐的第一条路径是云端的 GitHub Codespaces它同时被 00-course-setup/01-setup-cloud.md 作为Cloud Setup独立成章。1. Fork 整个仓库首先将整个仓库 Fork 到自己的 GitHub 账号下以获得修改代码、完成作业挑战的权限。Fork 之后建议同步使用 Star 收藏便于日后找回本仓库及其关联仓库。2. 创建 Codespace为了避免运行代码时出现依赖版本冲突官方推荐直接在本课程的 GitHub Codespaces 中运行。操作路径为在你的 Fork 中点击Code → Codespaces → New on main上图中绿色按钮 Create codespace on main 即该入口。随后浏览器会打开一个 VS Code 窗口开发容器自动开始构建首次构建通常需要约 2 分钟。从仓库源码看Codespaces 的构建配置位于根目录 .devcontainer/devcontainer.json它基于mcr.microsoft.com/devcontainers/universal:2.13通用镜像启动内置了 Python、Node.js、.NET、Java 等运行时并通过updateContentCommand执行python3 -m pip install -r requirements.txt自动安装 requirements.txt 中锁定的依赖如openai、python-dotenv、ipywidgets、azure-ai-inference等再通过postCreateCommand运行 .devcontainer/post-create.sh 完成后续初始化。这正是打开即用、依赖零漂移的实现基础。3. 注入 API 密钥Codespaces Secrets为避免把密钥写进代码导致泄露推荐使用 Codespaces Secrets 保存凭据点击左下角 ⚙️ 齿轮图标 → 打开 Command Palette命令面板选择Codespaces: Manage User Secret → Add a new secret将密钥命名为OPENAI_API_KEY粘贴你的 Key保存即可。配置完成后代码会自动通过环境变量读取该密钥无需再在 Codespaces 内手工创建.env文件。二、常见问题速查表课程主页中文译本同英文版为开发中最常见的几个故障给出了标准修复动作完整对比如下症状修复方式容器构建卡住超过 10 分钟Codespaces → “Rebuild Container”重建容器python: command not found终端没有正确挂载点击新建一个bash终端OpenAI 返回401 UnauthorizedOPENAI_API_KEY填写错误或已过期VS Code 一直显示 “Dev container mounting…”刷新浏览器标签页——Codespaces 偶尔会失去连接Notebook 找不到内核Notebook 菜单 →Kernel → Select Kernel → Python 3而如果是在本地非 Codespaces运行00-course-setup/02-setup-local.md 还补充了更多本地场景的修复项例如 Windows 下pip无法构建 wheel 时执行pip install --upgrade pip setuptools wheel后重试出现ModuleNotFoundError: dotenv说明虚拟环境未正确安装依赖需重新执行pip install -r requirements.txtDocker 构建报 No space left 时应在 Docker Desktop → Settings → Resources 中调大磁盘配额等。三、配置 API 密钥.env文件的完整创建与加载流程无论走哪条运行路径最终都要为课程代码准备可用的 LLM 服务凭据。课程提供了统一的本地配置方案创建.env文件并配合python-dotenv加载。完整流程如下。1. 进入项目根目录cd path/to/your/project2. 创建.env文件在仓库根目录下已有官方提供的环境变量模板.env.copy见 .env.copy。推荐的做法是直接复制模板再编辑填充cp .env.copy .env如果希望手工创建空白文件Unix 系系统touch .envWindowsecho . .env3. 编辑.env按需填入凭据以当前仓库 .env.copy 为准课程支持的变量及含义如下表变量用途说明OPENAI_API_KEY非 Azure 的 OpenAI 端点的授权密钥AZURE_OPENAI_API_VERSIONAzure OpenAI 的 API 版本模板默认2024-10-21当前稳定 GA 版本已预置AZURE_OPENAI_API_KEYAzure OpenAI现并入 Microsoft Foundry资源的授权密钥AZURE_OPENAI_ENDPOINTAzure OpenAI 资源的已部署端点形如https://resource-name.openai.azure.comAZURE_OPENAI_DEPLOYMENT文本生成模型的部署名例如gpt-4o-miniAZURE_OPENAI_EMBEDDINGS_DEPLOYMENT文本嵌入模型的部署名例如text-embedding-3-smallAZURE_INFERENCE_ENDPOINTMicrosoft Foundry 项目的推理端点用于访问 Foundry Models 模型目录AZURE_INFERENCE_CREDENTIALMicrosoft Foundry 项目对应的 API 密钥HUGGING_FACE_API_KEYHugging Face 用户访问令牌Access Token课程中的作业文件按文件名标签区分所需 Provideraoai前缀需要 Azure OpenAI 端点与密钥oai前缀需要 OpenAI 端点与密钥hf需要 Hugging Face 令牌githubmodels需要 Foundry Models 端点与密钥GitHub Models 已于 2026 年 7 月底退役。你可以只配置自己需要的 Provider未配置的那部分作业会在缺少凭据时报错退出不影响其余内容。各 Provider 的注册与配置细节请参见 00-course-setup/03-providers.md。4. 保存文件并注意安全.env文件已被仓库的 .gitignore 忽略切勿把真实密钥提交到公开仓库否则可能引发安全问题甚至因密钥被滥用而产生意外费用。5. 安装python-dotenvpython-dotenv已包含在课程根目录 requirements.txt版本锁定为python-dotenv1.2.2也可单独安装pip install python-dotenv6. 在 Python 脚本中加载环境变量from dotenv import load_dotenv import os # 从 .env 文件加载环境变量 load_dotenv() # 读取变量 endpoint os.getenv(AZURE_INFERENCE_ENDPOINT) token os.getenv(AZURE_INFERENCE_CREDENTIAL) print(endpoint)仓库中的强制校验实践仓库还提供了比os.getenv更严谨的封装。在 shared/python/env_utils.py 中get_required_env会在变量缺失或为空时抛出带提示的ValueErrorvalidate_env_vars则一次性校验多个必填变量并返回映射get_env_with_default用于提供默认值。对应的单元测试位于 tests/test_env_utils.py其中验证了变量缺失抛ValueError且错误信息包含变量名、空字符串按缺失处理、可附带描述信息等行为。这意味着在真实课程代码中如果某个 Provider 变量未配置脚本会以清晰、可定位的错误而非晦涩的运行时异常来提醒你回头检查.env。四、在本地电脑运行课程代码若更希望在自有设备上运行00-course-setup/02-setup-local.md 给出了四条可选路径原生 Python 虚拟环境、VS Code Dev ContainerDocker、Miniconda、以及浏览器内的 Jupyter。它们最终都通向同一批课程内容可按习惯任选其一。前置条件工具版本 / 说明Python3.10 及以上Git最新版本VS Code可选但推荐Docker Desktop仅选项 BDev Container需要可在终端用python --version、git --version、docker --version、code --version逐一验证是否就绪。克隆仓库git clone https://github.com/microsoft/generative-ai-for-beginners cd generative-ai-for-beginners若已 Fork可将 URL 替换为你自己的 Fork 仓库地址。选项 A原生 Python最快python -m venv .venv # 创建虚拟环境 source .venv/bin/activate # macOS / Linux # Windows PowerShell 使用.\.venv\Scripts\activate当命令行提示符前缀出现(.venv)即代表已进入虚拟环境然后安装依赖pip install -r requirements.txt选项 BVS Code Dev ContainerDocker该仓库为课程准备了一个开发容器其配置定义在根目录 .devcontainer/devcontainer.jsonUniversal 运行时可同时支撑 Python、.NET、Node.js、Java 开发。这一选项的最大价值在于获得与 Codespaces 完全一致的开发环境杜绝依赖漂移。安装 Docker Desktop并确认docker --version可用同时安装 VS Code 的 Remote - Containers 扩展用 VS Code 打开仓库目录编辑器会检测到.devcontainer/并弹出提示点击 Reopen in Container首次构建镜像约需数分钟构建完成后即处于容器内部环境。需要注意如果 VS Code 提示在容器中重新打开而你希望使用本机已安装的 Python应拒绝该提示。选项 CMinicondaMiniconda 是 Conda、Python 及若干包的轻量安装器。Conda 本身是一个包管理器能方便地创建和切换 Python 虚拟环境且在pip无法提供的包时尤为好用。安装后先验证conda --version。接着创建环境描述文件environment.yml若使用 Codespaces应放在.devcontainer目录下即.devcontainer/environment.yml。仓库自带的 .devcontainer/environment.yml 是一个可直接参考的示例。文档给出的完整模板为name: environment-name channels: - defaults - microsoft dependencies: - pythonpython-version - openai - python-dotenv - pip - pip: - azure-ai-ml其中environment-name是你想给 Conda 环境取的名字python-version是期望的 Python 版本例如3表示最新大版本。随后在命令行执行conda env create --name ai4beg --file .devcontainer/environment.yml # .devcontainer 子路径仅适用于 Codespace 场景 conda activate ai4beg若用 conda 安装时遇到错误可手动执行conda install -c microsoft azure-ai-ml安装 Microsoft AI 相关库。选项 D浏览器中的经典 Jupyter / Jupyter Lab如果你偏爱 Jupyter 界面或不希望依赖 VS Code可以直接在浏览器中使用 Jupyter。启动前先进入课程目录然后运行jupyter notebook或jupyterhub启动后命令行窗口会打印访问 URL。打开该 URL 即可看到课程目录结构并进入任意*.ipynb文件例如 08-building-search-applications/python/oai-solution.ipynb。五、技术需求课程依赖哪个 LLM Provider编码类课程示例主要基于 LLM 托管端点API来运行需要通过合法凭据访问。课程讨论的 Provider 包括OpenAIGPT 系列、Azure OpenAI企业级能力取向、Microsoft Foundry Models单一端点与密钥访问数百个来自 OpenAI、Meta、Mistral、Cohere、Microsoft 等的模型作为已退役 GitHub Models 的直接替代品、Hugging Face开源模型与推理服务器以及可完全离线运行的本地方案Foundry Local / Ollama。若想完全脱离云订阅在自有设备上运行兼容的开源模型可参考 19-slm 章节提供的实操示例。在等待访问申请审批期间每个编码课配套的README.md都贴出了代码与输出结果可以先阅读、后运行。各 Provider 的完整注册方式、成本说明与端点获取步骤请参阅 00-course-setup/03-providers.md。六、环境就绪后的下一步完成上述配置后即可正式进入课程正文。课程将先从生成式 AI 与大语言模型的基础概念讲起再过渡到提示工程、文本/对话/搜索/图像等各类构建型应用建议从第 1 课 01-introduction-to-genai/README.md 开始如果需要设置具体 LLM Provider回到 00-course-setup/03-providers.md 对照配置即可。总而言之本仓库的环境配置遵循云端开箱即用 本地可复现的双轨设计想快速上手就 Fork 后直接进入 Codespaces 并通过 Codespaces Secrets 注入密钥想在本地深度复现则按 Python venv、Dev Container、Miniconda 或 Jupyter 四条路径之一准备环境再以.env.copy为模板补齐凭据。环境配好之后所有课程代码都只需load_dotenv()即可安全读取密钥并开始调用模型。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考