企业官网建设流程全解析

generative-ai-for-beginners 环境搭建完全指南：Fork、Codespaces 与本地跑通第一课

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

本指南以仓库课程初始化章节（对应translations/en/00-course-setup/README.md，仓库根目录的原文见 00-course-setup/README.md）为核心，系统讲解如何从零准备一个可运行 21 课 Generative AI 动手项目的开发环境。你将掌握 Fork 仓库、创建 GitHub Codespaces、安全托管 API Key、配置.env，并能在云上或本机（原生 Python、Conda、VS Code Dev Container、Jupyter）任一形态中运行课程代码，最终安全高效地进入 第 1 课：生成式 AI 与 LLM 入门。

一、课程环境概览与整体路线

这个仓库是一个开源课程项目（关于课程规模与定位可在仓库根目录的 pyproject.toml 与课程说明中确认），学习过程会涉及大量需要调用云端模型接口的 Notebook 与脚本（例如基于 OpenAI / Azure OpenAI / Hugging Face 的作业）。为了让你“零折腾”地聚焦学习本身，官方给出了完整的环境准备路线：

仓库还提供了整套共享工具代码用于环境变量的安全读取（shared/python/env_utils.py）与 OpenAI/Azure 客户端的创建（shared/python/api_utils.py），后文会结合这些源码说明“配置变量 → 被代码消费”的完整链路。

二、第一步：Fork 本仓库（获得可写副本）

课程要求你动手修改代码、完成挑战，因此需要把仓库 Fork 到自己的账号下。具体操作：

1. 打开仓库主页，点击右上角Fork，把整个仓库复制到你自己的账号中，得到可自由修改的副本；
2. 可选但推荐：顺手给仓库点一个Star（🌟），方便日后在“你 Star 过的仓库”里快速找回本仓库及其关联项目。

Fork 完成后，你既可以把它作为云端 Codespace 的基底，也可以本地git clone你自己的副本。

三、第二步：创建 Codespace，让环境“预装好”

为避免依赖安装带来的各类兼容性问题，官方推荐在GitHub Codespaces中运行本课程。在 GitHub 的云端开发环境中，仓库已通过预构建的开发容器帮你装好 Python、Node.js、.NET、Java 等运行时，首次启动大约需要几分钟构建容器。

在你自己的 Fork 副本中依次点击：Code → Codespaces → New on main（即基于main分支新建一个 codespace），浏览器就会打开一个云端的 VS Code 窗口并开始构建开发容器。

关于云端方案的更多细节（个人免费配额、停止/删除空闲 codespace 以节约配额的提示等）见 00-course-setup/01-setup-cloud.md。

3.1 用 Codespaces Secrets 安全保存密钥（推荐）

把 API Key 直接写进代码库是危险的。Codespaces 提供了“Secrets”机制，将密钥与代码隔离保存：

1. 点击左下角 ⚙️ 齿轮图标 →Command Palette；
2. 输入并执行Codespaces : Manage user secret→Add a new secret；
3. 名称填OPENAI_API_KEY，粘贴你的密钥后Save保存。

保存后，仓库里的代码会自动读取该密钥，你无需在仓库内落盘任何明文密钥。

3.2 备选：在 Codespace 里使用.env文件

如果你确实需要一份本地可见的.env（例如需要在多个 Provider 间切换），仓库也提供了现成模板。在 Codespace 终端中执行：

cp .env.copy .env code .env # 将占位符替换为真实 Key

仓库根目录确实存在 .env.copy 模板文件，所有需要填写的变量及其注释都列在其中。

四、第三步：安全配置 API Key 与.env文件

绝对不要把任何 API Key 写死在代码里：提交到公开仓库可能引发安全问题，甚至被他人盗用而产生费用。规范的姿势是把密钥放入python-dotenv读取的.env文件（该文件已被.gitignore忽略，不会进入版本库），或用 Codespaces Secrets 保存。下面是一份完整的六步流程：

1. 进入项目根目录

cd path/to/your/project

2. 创建.env文件

Unix 系系统：

touch .env

Windows 系统：

echo . > .env

3. 编辑.env，填入你的 Provider 凭据

用任意文本编辑器（VS Code、Notepad++ 等）打开.env，参考仓库根目录 .env.copy 模板的结构，把占位符替换成真实值。仓库各文档与代码目前使用的主要变量如下（关于 GitHub Models 退役与 Microsoft Foundry Models 接管的说明见下文“技术需求与 Provider 选择”）：

# OpenAI Provider OPENAI_API_KEY='<add your OpenAI API key here>' ## Azure OpenAI in Microsoft Foundry AZURE_OPENAI_API_VERSION='2024-10-21' AZURE_OPENAI_API_KEY='<add your Foundry resource key here>' AZURE_OPENAI_ENDPOINT='<add your Foundry resource endpoint here, e.g. https://<resource-name>.openai.azure.com>' AZURE_OPENAI_DEPLOYMENT='<add your chat completion model deployment name here, e.g. gpt-4o-mini>' AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='<add your embeddings model deployment name here, e.g. text-embedding-3-small>' ## Microsoft Foundry Models (multi-provider model catalog) 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>'

各变量的含义对照表：

说明：AZURE_OPENAI_DEPLOYMENT与AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT分别代表课程默认使用的文本生成与向量检索模型，具体如何在作业中使用，会在对应课程的任务说明中给出。各 Provider 如何注册账号、申请 Key、部署模型，完整指引在 00-course-setup/03-providers.md。

4. 保存文件并关闭编辑器

5. 安装python-dotenv（用于把.env中的变量加载进 Python 应用）：

pip install python-dotenv

仓库根目录 requirements.txt 中已固定python-dotenv==1.2.2，因此执行pip install -r requirements.txt亦可。

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

from dotenv import load_dotenv import os # 从 .env 文件加载环境变量 load_dotenv() # 读取 Microsoft Foundry Models 变量 endpoint = os.getenv("AZURE_INFERENCE_ENDPOINT") token = os.getenv("AZURE_INFERENCE_CREDENTIAL") print(endpoint)

到这里，你已经成功创建.env、写入凭据，并能在 Python 中读取它们。

4.1 源码侧：环境变量是如何被“消费”的

仓库并不要求你手写样板代码，而是把环境读取逻辑收敛进了 shared/python/env_utils.py：

• get_required_env(var_name, description)（shared/python/env_utils.py）：读取必填变量，缺失时抛出带变量名与用途提示的ValueError，提示内容会引导你去.env中补齐；
• validate_env_vars(*var_names)（shared/python/env_utils.py）：批量校验多个变量是否都已设置，并返回变量名到值的字典；
• get_env_with_default(var_name, default)（shared/python/env_utils.py）：为可选变量提供默认值。

客户端创建侧则由 shared/python/api_utils.py 负责：

• create_openai_client()（shared/python/api_utils.py）在没有显式传入 key 时自动读取OPENAI_API_KEY环境变量，缺失即抛出异常；
• create_azure_openai_client()（shared/python/api_utils.py）自动读取AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_API_KEY，并以<endpoint>/openai/v1/作为base_url构造客户端。

这意味着：只要.env或 Codespaces Secrets 配置正确，课程中的示例脚本便会自动取到凭据，不需要你改动任何共享代码。

五、常见问题排查（Troubleshooting）

环境搭建失败大多集中在容器构建、终端会话、密钥与 Notebook 内核四个方面。官方给出的对照表如下：

若配置的是本地环境而不是 Codespaces，可对照 00-course-setup/02-setup-local.md 末尾的排障表（如 Windows 下pip无法构建 wheel 时先pip install --upgrade pip setuptools wheel）。

六、在本机运行课程代码

如果你选择在自己电脑上运行，需要先安装某个版本的 Python。然后克隆仓库：

git clone https://github.com/<your-github>/generative-ai-for-beginners cd generative-ai-for-beginners

（课程官方原仓库地址为https://github.com/microsoft/generative-ai-for-beginners，实际使用中建议直接克隆你自己 Fork 的副本以便提交练习成果。）克隆完成后，还需要按第四节配置.env，或在对应课程目录内安装依赖。

仓库根目录的 requirements.txt 与 pyproject.toml 对 Python 版本有明确约定：requires-python = ">=3.10"，主要依赖包括openai>=1.12.0、python-dotenv==1.2.2、azure-ai-inference、tiktoken以及numpy/pandas/matplotlib等数据科学工具链。

七、可选的高级环境方案

官方环境准备不止一种，以下方案可按需选用：

7.1 方案 A：Miniconda + 虚拟环境

Miniconda 是 Conda 的轻量安装器。Conda 本身是一个包管理器，能方便地创建与切换不同的 Python虚拟环境，对pip装不了的包也很有用。

1. 按官方指南装好 Miniconda，验证：conda --version；
2. 若尚未克隆仓库，先完成克隆；
3. 创建环境描述文件environment.yml（在 Codespace 中请建在.devcontainer目录下，即.devcontainer/environment.yml），并填入：

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

<environment-name>是你想给环境起的名字；<python-version>是你想用的 Python 版本，例如3表示最新的 Python 3 大版本。

4. 用以下命令创建并激活环境：

conda env create --name ai4beg --file .devcontainer/environment.yml # 其中 .devcontainer 路径仅适用于 Codespace 场景 conda activate ai4beg

如果 Conda 解析频道报错，也可以手动安装微软 AI 库：

conda install -c microsoft azure-ai-ml

7.2 方案 B：VS Code + Python 扩展

官方推荐使用 Visual Studio Code 搭配Python 扩展（ID：ms-python.python）学习本课程，但这只是推荐而非硬性要求：

• 克隆并在 VS Code 中打开仓库后，VS Code 会自动建议你安装 Python 扩展；
• 仓库内含.devcontainer目录，因此打开时会提示是否“在容器中重新打开”项目；
• 注意：若你想使用本机安装的 Python，当 VS Code 提示以容器方式重开时，请选择拒绝，以继续使用本地 Python。

7.3 方案 C：浏览器里的 Jupyter

喜欢经典 Jupyter 界面、不想依赖 VS Code 的话，也可以在浏览器里跑课程。进入课程目录后执行：

jupyter notebook

或

jupyterhub

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

7.4 方案 D：在容器（Dev Container）中运行

不想在自己的电脑或 Codespace 里装环境，还可以使用容器。仓库的.devcontainer目录让 VS Code 可以把整个项目放进容器构建。在 Codespaces 之外使用此方案需要自行安装 Docker，工程量不小，只推荐有容器使用经验的开发者尝试。

在 GitHub Codespaces 中保护 API Key 的最佳实践是使用Codespaces Secrets，具体管理方式见 GitHub 官方的 Secrets 管理文档。

八、课程的技术需求与 Provider 选择

本课程中的编码作业可以（并非必须）配置为调用一个或多个 LLM Provider 的托管端点，例如 OpenAI、Azure OpenAI、Microsoft Foundry Models、Hugging Face；如果你想完全离线，也可以选择 Foundry Local 或 Ollama 在本机运行开源模型。你需要使用自己的账号来完成这些练习——作业都是可选的，你可以按兴趣配置其中一个、全部或一个都不配置。需要说明的是，仓库中的 00-course-setup/03-providers.md 明确提示：GitHub Models（及其GITHUB_TOKEN变量）将于 2026 年 7 月底停用，官方建议改用Microsoft Foundry Models（一个端点 + 一个 API Key 即可访问 OpenAI、Meta、Mistral、Cohere、Microsoft 等数百个模型），因此本指南沿用了 Foundry 相关的变量命名。

作业文件名会通过标签标明所需的 Provider：

• aoai：需要 Azure OpenAI 端点与 Key；
• oai：需要 OpenAI 端点与 Key；
• hf：需要 Hugging Face Token；
• githubmodels：需要 Microsoft Foundry Models 端点与 Key（对应 GitHub Models 退役后的替代方案）。

你可以只配置其中一部分。未配置对应凭据的作业在运行时自然报错，不影响其他课程的推进。

8.1 如何获取各 Provider 的端点与密钥

• Azure OpenAI：登录 Azure Portal，在左侧菜单进入Keys and Endpoint，点击Show Keys即可看到 KEY 1、KEY 2 与 Endpoint；用 KEY 1 作为AZURE_OPENAI_API_KEY、Endpoint 作为AZURE_OPENAI_ENDPOINT。随后在Model deployments里点击进入 Microsoft Foundry 门户（旧入口为 “Manage Deployments”），查看已部署模型：推荐部署一个文本生成模型（如gpt-4o-mini）与一个文本嵌入模型（如text-embedding-3-small），并把部署名填入AZURE_OPENAI_DEPLOYMENT与AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT。
• OpenAI：在 OpenAI 平台账号页创建 API Key，填入OPENAI_API_KEY。
• Hugging Face：在个人资料的 Access Tokens 里为本项目新建一个 Token，填入HUGGING_FACE_API_KEY（技术上它不是 API Key 而是鉴权 Token，此处沿用统一命名）。请不要公开分享该 Token。
• Microsoft Foundry Models：进入 Microsoft Foundry 创建（或打开）一个项目，在模型目录中部署一个模型（例如gpt-4o-mini），然后在项目Overview页复制endpoint与API key，分别填入AZURE_INFERENCE_ENDPOINT与AZURE_INFERENCE_CREDENTIAL。
• 离线 Provider：不需要任何云订阅时，可选用 Foundry Local（自动选择 NPU/GPU/CPU 并暴露 OpenAI 兼容端点）或 Ollama（本地运行 Llama、Phi、Mistral、Gemma 等开源模型的流行选择）。离线方案的动手示例可参考 19-slm/README.md。

每个 Provider 的注册成本、Key 获取入口、Playground 等更多细节，都整理在 00-course-setup/03-providers.md 的对比表中。

8.2 在等待申请期间可以做什么

Azure OpenAI 这类服务有时需要先提交申请、等待审批。在等待期间，每个编码课程目录下的README.md都内嵌了代码与运行结果展示，你可以先阅读、理解代码逻辑，等凭据到位后再实际运行 Notebook。

九、验证环境是否就绪

配置完成后，可以用下面这个最小的 Python 片段做自检——它能确认python-dotenv可导入、.env能被加载、关键变量已读取（不输出密钥本身）：

python -c "from dotenv import load_dotenv; import os; load_dotenv(); assert os.getenv('OPENAI_API_KEY') or os.getenv('AZURE_OPENAI_API_KEY') or os.getenv('AZURE_INFERENCE_CREDENTIAL'); print('env OK')"

更进一步，可以尝试调用共享模块的校验函数。仓库的单元测试也覆盖了这些逻辑（见 tests/ 下的test_env_utils.py等），如果你后续修改了共享代码，可参考 pyproject.toml 中配置的pytest运行测试。按官方文档的约定，“缺少凭据”只会让对应作业在运行时报错（相关作业会给出清晰的缺失变量提示），不会破坏整个课程仓库。

十、学完准备后，如何开始

完成上述步骤后，你已具备完整的运行环境。接下来推荐按 00-course-setup/README.md 的路线进入学习主线：从 第 1 课：生成式 AI 与 LLM 入门 开始，然后一路推进到提示工程、文本/图像/搜索应用、Function Calling、RAG、微调、AI Agent 等章节（目录编号01…21）。如果你在学习中遇到问题，官方在 AI 社区 Discord 中设有学习者频道，项目团队也会在该频道协助答疑；本课程同时是开源项目，欢迎以 Pull Request 或 Issue 的方式提出改进——需要注意按贡献规范提交，且翻译类贡献不接受机器翻译结果，请只在精通的语言上参与翻译。

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