generative-ai-for-beginners 课程环境搭建完全指南：从 Fork 仓库、Codespaces 到 .env 密钥配置-港品优选

generative-ai-for-beginners 课程环境搭建完全指南：从 Fork 仓库、Codespaces 到 .env 密钥配置

【免费下载链接】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/README.md 及其孟加拉语翻译版 translations/bn/00-course-setup/README.md）整理，完整覆盖课程上手所需的三类技术能力：使用 GitHub Codespaces 在云端一键拉起开发环境并安全注入 API 密钥、在本地机器上搭建 Python（或 Miniconda/Jupyter/容器）运行环境、以及按仓库统一约定配置.env环境变量文件。读完并照做后，你可以独立排除课程中常见的启动故障，并顺利进入第一课学习生成式 AI 与 LLM 的基础概念。

需要说明的一点：translations/bn/00-course-setup/README.md 是通过 Co-op Translator 机器翻译服务生成的孟加拉语版本，其页脚免责声明明确指出原文档才是权威来源，重要信息建议以英文原版为准。下文在忠实呈现该文档全部操作内容的同时，结合仓库当前实际状态（如 requirements.txt、pyproject.toml、.devcontainer/ 与 shared/python/ 下的工具代码）补充了可验证的实现细节。

设置步骤总览：Fork、Codespaces 与 Secrets

要开始学习这门 21 课（涵盖概念课与编码课）的生成式 AI 课程，需要依次完成三步设置。

1. Fork 整个仓库

第一步是把整个仓库 Fork 到你自己的 GitHub 账号下，这样你才有权限修改任何代码、完成课程中的各项挑战（challenge）。同时建议给仓库加一颗 Star，方便日后快速找到本仓库及相关仓库。

2. 创建 Codespace

为避免运行代码时遇到任何依赖问题，官方推荐使用 GitHub Codespaces 来运行本课程。在你的 Fork 中按Code → Codespaces → New on main的路径操作即可。

2.1 添加一个 Secret

密钥不要写进代码或.env文件，而是用 Codespaces 的用户级 Secret 管理：

点击 ⚙️ 齿轮图标 → Command Palette → Codespaces: Manage user secret → Add a new secret；
变量名填写OPENAI_API_KEY，粘贴你的密钥值，点击 Save。

这一做法在仓库的 00-course-setup/01-setup-cloud.md 中同样被列为推荐方案（"Option A Codespaces Secrets — Recommended"），并且补充说明：个人账号每月有 120 core-hours / 60 GB-hours 的免费额度，空闲时建议及时停止或删除 Codespace（View ▸ Command Palette ▸Codespaces: Stop Codespace）以保护额度。

3. 下一步去哪

原文档给出的分流指引如下（下表链接已转换为从仓库根目录出发的路径）：

我想…	去这里
开始第 1 课	01-introduction-to-genai
离线/本地工作	setup-local.md
配置一个 LLM 提供商	providers.md
结识其他学习者	加入课程官方 Discord 社区

故障排查速查表

课程文档内置了一张面向 Codespaces 环境的排障表，覆盖容器构建、终端、鉴权、连接与 Notebook kernel 五类典型故障，原表完整保留如下：

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

本地开发场景的补充排障项（pip构建 wheel 失败、ModuleNotFoundError: dotenv、Docker 磁盘空间不足、venv 与容器双重提示等）见 00-course-setup/02-setup-local.md 的 Troubleshooting 章节。

创建`.env`文件并加载环境变量：仓库统一约定

无论用哪条运行路径，课程代码统一约定：不要把 API 密钥硬编码进代码，而是写入.env文件，再用python-dotenv在脚本中加载。原文档的六步操作流程如下。

第 1–2 步：创建.env文件。Unix 系系统（Linux/macOS）：

touch .env

Windows：

echo . > .env

第 3 步：编辑.env。用任意文本编辑器（VS Code、Notepad++ 等）打开，写入你的凭据。原文档以 GitHub Token 为例：

GITHUB_TOKEN=your_github_token_here

注意（以仓库当前状态为准）：英文主文档 00-course-setup/README.md 已更新——GitHub Models（及其GITHUB_TOKEN变量）将于 2026 年 7 月底退役，课程改用 Microsoft Foundry Models。当前 00-course-setup/03-providers.md 建议的.env内容包含以下变量（根目录提供了预填占位符的 .env.copy 可直接cp .env.copy .env复制使用）：
OPENAI_API_KEY—— OpenAI 服务的授权密钥；
AZURE_OPENAI_API_VERSION/AZURE_OPENAI_API_KEY/AZURE_OPENAI_ENDPOINT—— Azure OpenAI（现已并入 Microsoft Foundry）资源版本、密钥与端点；
AZURE_OPENAI_DEPLOYMENT/AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT—— 文本生成与向量嵌入两个模型部署名；
AZURE_INFERENCE_ENDPOINT/AZURE_INFERENCE_CREDENTIAL—— Microsoft Foundry Models 项目端点与密钥（即替代GITHUB_TOKEN的两个变量）；
HUGGING_FACE_API_KEY—— Hugging Face 访问令牌。
.env已被.gitignore忽略，切勿提交。

第 4 步：保存文件并关闭编辑器。

第 5 步：安装python-dotenv（若尚未安装）：

pip install python-dotenv

这一点可以直接在仓库中得到印证：requirements.txt 中固定了python-dotenv==1.2.2，pyproject.toml 的依赖清单同样声明了python-dotenv>=1.0.0。

第 6 步：在 Python 脚本中加载环境变量：

from dotenv import load_dotenv import os # 从 .env 文件加载环境变量 load_dotenv() # 访问变量（当前仓库推荐读取 Foundry Models 两个变量） endpoint = os.getenv("AZURE_INFERENCE_ENDPOINT") token = os.getenv("AZURE_INFERENCE_CREDENTIAL") print(endpoint)

源码印证：课程代码如何安全读取这些变量

从源码结构看，仓库在 shared/python/env_utils.py 中封装了三个取值函数，课程各练习代码统一经由它们读取上述变量，而不是各自直接os.getenv：

get_required_env(var_name, description)（env_utils.py#L11-L35）：读取单个必需变量，缺失或为空时抛出带提示的ValueError，错误信息明确要求"Please set it in your .env file or environment"；
validate_env_vars(*var_names)（env_utils.py#L38-L71）：一次校验多个变量，把所有缺失项汇总后一并报错；
get_env_with_default(var_name, default)（env_utils.py#L74-L88）：带默认值读取，例如MODEL_NAME缺省回退。

这些行为有配套的单测保障，见 tests/test_env_utils.py。客户端构造侧，shared/python/api_utils.py 的create_azure_openai_client（api_utils.py#L91-L144）会优先读取AZURE_OPENAI_ENDPOINT与AZURE_OPENAI_API_KEY两个环境变量，并将请求基址拼接为<endpoint>/openai/v1/；create_openai_client（api_utils.py#L56-L88）则读取OPENAI_API_KEY，缺失时抛出明确的ValueError。这也解释了排障表中"401 Unauthorized= 密钥错误/过期"的判定逻辑：鉴权失败几乎都发生在客户端构造或首请求阶段。

如何在自己的电脑上本地运行

在本地机器上运行代码，前提是安装任意一个受支持的 Python 版本——注意仓库 pyproject.toml 声明requires-python = ">=3.10"，并且 classifiers 中明确面向 3.10 / 3.11 / 3.12。

然后用 git 克隆仓库：

git clone https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners cd generative-ai-for-beginners

克隆完成后即可开始。进入课程目录后，推荐先安装仓库声明的依赖，使环境与 requirements.txt 对齐（其中含openai>=1.12.0、python-dotenv==1.2.2、azure-ai-inference、tiktoken、scikit-learn等，覆盖文本、嵌入与图像课所需的库）：

pip install -r requirements.txt

00-course-setup/02-setup-local.md 还给出了一条更稳妥的路径：先创建并激活 venv（python -m venv .venv，Linux/macOS 用source .venv/bin/activate，Windows PowerShell 用.\.venv\Scripts\activate）再安装依赖，避免污染系统 Python。

可选路径 A：安装 Miniconda

原文档将 Miniconda 列为可选方案：它是安装 Conda、Python 及少量包的轻量安装器。Conda 本身是包管理器，方便创建与切换不同的 Python 虚拟环境，也能安装pip上不可用的包。

安装好 Miniconda 后（若还没克隆则先克隆仓库），下一步是创建虚拟环境：新建一个环境文件environment.yml。如果在 Codespaces 中操作，应把它放在.devcontainer目录内，即.devcontainer/environment.yml（仓库当前确实提供了 .devcontainer/environment.yml 与 .devcontainer/devcontainer.json）。

原文档给出的环境文件内容如下，两个尖括号占位符分别填环境名（如ai4beg）与 Python 版本（如3表示最新主版本）：

name: <environment-name> channels: - defaults - microsoft dependencies: - python=<python-version> - openai - python-dotenv - pip - pip: - azure-ai-ml

然后在命令行执行：

conda env create --name ai4beg --file .devcontainer/environment.yml # .devcontainer 子路径仅适用于 Codespace 设置 conda activate ai4beg

如果 Conda 过程中报错，可在终端手动安装 Microsoft AI 库作为兜底：

conda install -c microsoft azure-ai-ml

可选路径 B：VS Code + Python 支持扩展

课程推荐使用 Visual Studio Code 编辑器配合其 Python 支持扩展。需要强调这是建议而非硬性要求。原文档给出三条实践提示：

在 VS Code 中打开课程仓库时，会提示把项目设置到容器内运行——这正是仓库里特殊的 .devcontainer 目录的作用；
克隆并在 VS Code 中打开目录后，编辑器会自动建议安装 Python 支持扩展；
若 VS Code 建议"在容器中重新打开"仓库，请选择拒绝，以使用本地安装的 Python。

仓库还附带了 vs.code-profile 配置文件，可进一步还原课程作者推荐的工作区配置。

可选路径 C：在浏览器中使用 Jupyter

也可以完全在浏览器里用经典 Jupyter 或 Jupyter Hub 开发，二者都提供自动补全、代码高亮等体验。在终端进入课程目录后执行：

jupyter notebook

或

jupyterhub

启动后命令行窗口会打印访问 URL，打开即可看到课程大纲，并能导航到任意*.ipynb文件，例如 08-building-search-applications/python/oai-solution.ipynb。

可选路径 D：在容器中运行

在本地或 Codespace 里手工配置一切之外，还有一种选择是使用容器。课程仓库的 .devcontainer/ 目录让 VS Code 能够把项目直接搭建进容器。除了 Codespaces，本地跑容器需要安装 Docker，且配置有一定工作量，因此原文档建议仅推荐给有容器使用经验的学习者。

使用 GitHub Codespaces 时，保护 API 密钥的最佳方式之一是用 Codespace Secrets 管理凭据。00-course-setup/02-setup-local.md 的 Option B 同样基于这套devcontainer.json机制，并强调其价值在于"与 Codespaces 环境完全一致，无依赖漂移"。

课程结构与技术要求

课程包含 6 节概念课与 6 节编码课（后续章节逐步扩展到 21 课）。编码课使用 Azure OpenAI 服务，运行这些代码需要 Azure OpenAI 服务访问权限和一个 API 键，可通过官方申请入口提交申请获取。

在等待申请处理期间，每个编码课目录下都附带了README.md，可以直接查看代码与示例输出，不必等到服务开通才能学习。

首次使用 Azure OpenAI 服务与 OpenAI API

原文档为两类首次使用者各给了一条入门指引：

首次使用 Azure OpenAI 服务：按官方"创建并部署 Azure OpenAI 服务资源"的门户向导操作，拿到资源端点、密钥与模型部署；00-course-setup/03-providers.md 进一步细化了操作——在 Azure 门户侧边栏点击Keys and Endpoint → Show Keys取得 KEY 1 与 Endpoint，再经Model deployments进入 Microsoft Foundry 门户查看部署名，课程建议的部署组合是文本生成用gpt-4o-mini、文本嵌入用text-embedding-3-small；
首次使用 OpenAI API：按 OpenAI 平台的 Quickstart 指引创建并使用接口，取得密钥后填入.env的OPENAI_API_KEY。

结识其他学习者

课程团队在官方 AI Community Discord 服务器中为学员开设了专门频道，这是结识志向相同的创业者、构建者、学生和所有想提升生成式 AI 技能的人的好渠道，项目团队成员也会在该服务器中为学员答疑。

贡献指南

本课程是开源项目。如果你看到可改进之处或问题，可以创建 Pull Request 或提交 GitHub issue，项目团队会跟踪所有贡献。

大多数贡献需要同意 CLA（Contributor License Agreement），声明你有权授予项目使用你的贡献的权利；提交 PR 后 CLA-bot 会自动判断并添加相应标签或评论，按机器人指引操作即可，且整个 CLA 体系只需完成一次。
该项目采用 Microsoft 开源行为准则，疑问可按 FAQ 处理或联系项目方。
特别提示（原文档加粗强调）：为仓库翻译时请勿使用机器翻译。翻译将由社区校验，因此只为你熟练掌握的语言报名做翻译志愿者——这一点从本仓库 translations/ 目录覆盖 40 余种语言的规模上也可以看出对翻译质量的重视。

让我们开始

完成上述准备后，就可以从 01-introduction-to-genai 这一课开始，正式进入生成式 AI 与 LLM 的世界。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析