Generative AI for Beginners 课程起步指南：从 fork 仓库到本地环境配置的全流程实战

本指南源自 generative-ai-for-beginners 课程仓库的课程设置文档（英文原版 及其在 translations/fr/00-course-setup/README.md 的法语译版），系统讲解学习者开启本系列课程前需要完成的环境搭建：包括 fork 仓库、创建 GitHub Codespaces、安全注入 API 密钥、配置 .env 与 python-dotenv、在本地以 venv / Conda / Jupyter / Dev Container 等不同方式运行，并汇总常见故障的排查对照表。学完本篇，你将能独立选出一条适合自己的运行路径，让后续每一课的 Python 代码与 Jupyter Notebook 开箱即跑，把精力集中在生成式 AI 应用本身。

课程仓库共含 00 号课程准备目录与 01–21 号课程目录，涵盖概念课与编码课两种形态；本指南只解决"如何把环境跑起来"这一前置问题，后续从 01-introduction-to-genai 正式开始学习。

图为启动 Codespace 时 GitHub 界面弹出的操作对话框，用于确认在哪个分支、以何种配置创建云端开发容器。

一、安装前须知：课程结构与你需要准备什么

仓库目录以数字编号组织全部学习内容：

• 00-course-setup/：课程准备（fork、云端/本地环境、LLM 供应商选择），即本篇主题；
• 01-introduction-to-genai/ 至 21-meta/：21 个课程单元，覆盖提示词工程、文本/聊天/搜索/图像应用、RAG、函数调用、微调、SLM、Agent 等主题。

每个编码课目录内通常同时提供 .py 源码、.ipynb Notebook 与不同供应商（OpenAI、Azure OpenAI、Microsoft Foundry Models）的 assignment 文件。编码课的运行依赖托管 LLM 服务：你需要自己的账户与 API 密钥才能执行代码；在申请处理期间，各课的 README.md 中也能直接查看代码与输出结果。

要完成本课程，官方建议依次完成三步：fork 仓库 → 创建 Codespace → 安全添加密钥。

二、Step 1：fork 本仓库

打开课程仓库页面，点击右上角 Fork 按钮，将整个仓库复制到自己的 GitHub 账户下。这样你才能自由修改示例代码并独立完成各课练习。完成 fork 后，建议顺手 Star（🌟） 仓库，方便日后快速找回它及相关的衍生仓库。

说明：本课程官方原仓库为 GitHub 上的 microsoft/generative-ai-for-beginners；若在本地克隆，请使用你自己的 fork 地址，例如 git clone <你的仓库地址>。

三、Step 2：创建 GitHub Codespace

为了避免依赖冲突（如 Python 版本、包缺失、系统环境差异），官方推荐直接在 GitHub Codespaces 中运行本课程——它提供免费的浏览器版 VS Code，且所有依赖已在容器中预装。

在你自己 fork 后的仓库页面上操作：Code → Codespaces → New on main（即在 main 分支上新建）。首次启动时 Dev Container 会执行构建，通常需要约 2 分钟。

为什么推荐 Codespaces？对照表如下：

优势	对你的意义
零本地安装	Chromebook、iPad、机房电脑都能直接跑
预构建开发容器	Python 3、Node.js、.NET、Java 等运行时已内置
免费配额	个人账户每月包含可观的核时/存储配额

💡 小贴士：养成用完即停的习惯，可通过 View → Command Palette → Codespaces: Stop Codespace 停止空闲的 Codespace，节省配额。

2.1 添加密钥（安全方式，推荐）

1. 点击左下角 ⚙️ 齿轮图标 → Command Palette → 选择 Codespaces: Manage user secret → 添加新 secret；
2. 变量名填写 OPENAI_API_KEY，粘贴你的密钥值并保存。

仓库中的共享工具库正是按此约定读取密钥的，见 shared/python/api_utils.py 中的实现：

key = api_key or os.getenv("OPENAI_API_KEY")

即：只要在 Codespaces 或 .env 中提供了 OPENAI_API_KEY，课程代码会自动读取，无需在源码中硬编码。

四、Step 3：接下来去哪？

我想…	前往…
开始第 1 课	01-introduction-to-genai
离线学习	00-course-setup/02-setup-local.md
配置一个 LLM 供应商	00-course-setup/03-providers.md
认识其他学习者	加入官方 AI 社区 Discord（见仓库 README 中的链接）

五、.env 文件与 python-dotenv：密钥管理的标准姿势

无论哪种运行方式，都不要把 API 密钥写进代码并提交到公开仓库——这既可能引发安全问题，也可能被他人盗刷产生不必要的费用。课程仓库在根目录提供了密钥模板文件 .env.copy，其完整内容如下：

# OpenAI Provider
OPENAI_API_KEY='<add your OpenAI API key here>'

## Azure OpenAI in Microsoft Foundry
## (Azure OpenAI Service is now part of Microsoft Foundry: https://ai.azure.com)
AZURE_OPENAI_API_VERSION='2024-10-21' # Default is set! (current stable GA API version)
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 - one endpoint/key for OpenAI, Meta, Mistral, Cohere, Microsoft, and more.
##  Replaces GitHub Models, which retires end of July 2026.)
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>'

按下面的六步流程即可完成密钥的本地配置：

① 定位到项目根目录：打开终端，进入课程仓库根目录。

② 创建 .env 文件：Unix 系系统使用：

touch .env

Windows 系统使用：

echo . > .env

也可以直接复制模板：

cp .env.copy .env

③ 编辑 .env 文件：用 VS Code、Notepad++ 等任意文本编辑器打开，将各占位符替换为真实凭证值。例如填入 Microsoft Foundry 项目端点与密钥：

AZURE_INFERENCE_ENDPOINT=your_foundry_endpoint_here
AZURE_INFERENCE_CREDENTIAL=your_foundry_api_key_here

说明：仓库英文版设置文档明确指出，GitHub Models（及其 GITHUB_TOKEN 变量）已于 2026 年 7 月底退役，统一改用 Microsoft Foundry Models（一组端点 + 一把密钥访问 OpenAI、Meta、Mistral、Cohere、Microsoft 等数百个模型）；部分早期译稿中出现的 GITHUB_TOKEN 写法已被 .env.copy 中的 AZURE_INFERENCE_ENDPOINT / AZURE_INFERENCE_CREDENTIAL 取代，请以 .env.copy 为准。

④ 保存文件：保存修改并关闭编辑器。.env 已被仓库的 .gitignore 忽略，切勿把它提交到版本库。

⑤ 安装 python-dotenv：用它把 .env 中的变量加载进 Python 应用：

pip install python-dotenv

⑥ 在 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 中读取。仓库的共享工具模块把这一套约定封装得更严谨：例如 shared/python/env_utils.py 提供了 get_required_env()（变量缺失即抛错）与 validate_env_vars()（批量校验必填项），对应的单元测试见 tests/test_env_utils.py；而 shared/python/api_utils.py 在构造 OpenAI / Azure OpenAI 客户端时都会优先读取 OPENAI_API_KEY 或 AZURE_OPENAI_API_KEY 等环境变量（缺少时报出明确提示）。

5.1 主要环境变量含义速查

变量	含义
OPENAI_API_KEY	调用非 Azure 的 OpenAI 端点所需授权密钥
AZURE_OPENAI_API_VERSION	Azure OpenAI API 版本（默认已设 2024-10-21，当前稳定 GA 版本）
AZURE_OPENAI_API_KEY	访问 Azure OpenAI（Microsoft Foundry 资源）的授权密钥
AZURE_OPENAI_ENDPOINT	Azure OpenAI 资源的部署端点
AZURE_OPENAI_DEPLOYMENT	文本生成（chat completion）模型部署名
AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT	文本嵌入（embeddings）模型部署名
AZURE_INFERENCE_ENDPOINT	Microsoft Foundry 项目端点（用于 Foundry Models）
AZURE_INFERENCE_CREDENTIAL	Microsoft Foundry 项目的 API 密钥
HUGGING_FACE_API_KEY	Hugging Face 访问令牌（用于鉴权，命名保持一致）

后两个 Azure OpenAI 变量分别对应"文本生成"与"向量检索（嵌入）"两类模型的默认部署，具体在相应课程的 assignment 中有详细说明。

六、在本地运行：克隆仓库与前置条件

本地运行需要安装 Python（建议 3.10+；仓库根目录还通过 .python-version 与 .devcontainer/environment.yml 锁定了 3.10.0），并准备好 Git。克隆命令如下：

git clone <你的仓库地址>
cd generative-ai-for-beginners

克隆完成后先安装根目录依赖清单 requirements.txt 中的包（含 python-dotenv==1.2.2、openai>=1.12.0、tiktoken、azure-ai-inference、ipywidgets、pandas、matplotlib 等）：

pip install -r requirements.txt

接下来可按需选择下方任一"可选步骤"完善你的开发环境。

七、可选步骤：四种增强玩法

7.1 安装 Miniconda / Conda 并创建虚拟环境

Miniconda 是 Conda 的轻量安装器。Conda 是包管理器，可方便地创建和切换不同的 Python 虚拟环境，尤其适合安装 pip 覆盖不到的包（例如微软 AI 库）。安装完成后用 conda --version 验证。

随后创建环境定义文件 environment.yml（若跟随 Codespaces 使用，请放在 .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 表示最新主版本）。仓库实际内置的 .devcontainer/environment.yml 内容为：

name: dev
channels:
 - defaults
dependencies:
- python=3.10.0
- openai
- python-dotenv
- pip
- pip:
  - azure-ai-inference

创建并激活环境：

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 使用 VS Code + Python 扩展

官方推荐（但不强制）使用 VS Code，并安装 Python 支持扩展。打开克隆后的仓库时，VS Code 会自动提示安装 Python 扩展。需要留意三点：

• 仓库自带 .devcontainer 目录，VS Code 会提示"在容器中重新打开"，如想使用本地 Python 版本，请拒绝该提示；
• 若选择容器方案，则需先装好 Docker，并在扩展市场安装 Dev Containers（ms-vscode-remote.remote-containers）；
• 仓库的容器配置见 .devcontainer/devcontainer.json，它基于 mcr.microsoft.com/devcontainers/universal:2.13 镜像，构建时会执行 python3 -m pip install -r requirements.txt 并运行 .devcontainer/post-create.sh，同时预装 Python/Pylance/Jupyter/Black/Ruff/ESLint/Prettier/Copilot 等扩展——这解释了为何 Codespaces 首次构建约需 2 分钟。

7.3 在浏览器中使用 Jupyter

喜欢经典 Jupyter 界面的读者，可在浏览器内直接使用 Notebook，同样具备自动补全、代码高亮等体验。在课程目录终端里执行：

jupyter notebook

或：

jupyterhub

启动后终端会打印访问 URL。打开该地址即可看到课程大纲，并跳转到任意 *.ipynb，例如 08-building-search-applications/python/oai-solution.ipynb（对应仓库 08-building-search-applications/python 目录下的 Notbook 文件）。

7.4 在容器中运行（进阶）

不想污染本地环境、又追求与 Codespaces 完全一致的环境，可以使用 Dev Container：仓库的 .devcontainer/devcontainer.json 允许 VS Code 把整个项目装进容器。容器方案在 Codespaces 之外需要安装 Docker，配置成本相对更高，官方建议只有熟悉容器技术的读者选用。

需要特别提醒：密钥安全。当使用 GitHub Codespaces 时，最安全的做法是使用 Codespaces Secrets（OPENAI_API_KEY 等保存在 GitHub 账户/仓库级 secret 中，自动注入到容器的环境变量），这样既不需要本地 .env，也不会把密钥写进任何代码文件；注意该方式仅对 Codespaces 生效，使用 Docker Desktop 本地容器时仍需配置 .env 文件。

八、故障排查对照表

官方文档针对高频问题给出了如下处置建议，请优先对照自查：

症状	解决办法
容器构建卡住超过 10 分钟	Codespaces → Rebuild Container（重建容器）
提示 python: command not found	终端未正确附着；点击 + → 新建 bash 终端
调用 OpenAI 返回 401 Unauthorized	OPENAI_API_KEY 错误或已过期，检查密钥值
VS Code 一直显示 “Dev container mounting…”	刷新浏览器标签页——Codespaces 偶尔会丢失连接
Notebook 内核缺失	Notebook 菜单 → Kernel ▸ Select Kernel ▸ Python 3
Windows 下 pip 无法构建 wheel	先执行 pip install --upgrade pip setuptools wheel 再重试
报 ModuleNotFoundError: dotenv	环境未装依赖，执行 pip install -r requirements.txt
Docker 构建失败报 No space left	Docker Desktop → Settings → Resources，调大磁盘配额
遇到 Conda 相关错误	执行 conda install -c microsoft azure-ai-ml

九、LLM 供应商配置与首次使用指引

不同课程的 assignment 会在文件名中标注其依赖的供应商标签：

• aoai：需要 Azure OpenAI 端点与密钥；
• oai：需要 OpenAI 端点与密钥；
• hf：需要 Hugging Face 令牌；
• githubmodels：需要 Microsoft Foundry Models 端点与密钥（GitHub Models 已于 2026 年 7 月底退役）。

你可以只配置一个、全部配置，或一个都不配——缺少凭证的相关练习会直接以认证错误退出。详细的注册、取密钥、填 .env 以及"如何从门户拿到 Azure OpenAI 端点/密钥、如何部署 gpt-4o-mini 与 text-embedding-3-small、如何在 Foundry 门户与本地离线供应商之间做选择"等完整说明，请阅读 00-course-setup/03-providers.md。快速上手指南分别收录于 00-course-setup/01-setup-cloud.md（云端 Codespaces）与 00-course-setup/02-setup-local.md（本地四种路径）。

首次使用 Azure OpenAI 服务时，官方建议先按其"创建并部署 Azure OpenAI Service 资源"的指南完成资源创建与模型部署；首次使用 OpenAI API 时，则按官方 quickstart 创建密钥并调用接口。两类服务都需要通过课程工具函数在运行时读取对应环境变量（AZURE_OPENAI_* 或 OPENAI_API_KEY）。

十、一起学习与参与贡献

本项目是完全开源的课程倡议。除课程文档外，仓库还提供 CONTRIBUTING.md（贡献指南）、CODE_OF_CONDUCT.md（行为准则）与社区支持渠道。若发现文档或代码问题，欢迎通过 Pull Request 或 Issue 反馈；参与开源也是推进生成式 AI 职业生涯的好方式。

社区提醒：如参与本仓库文本翻译，请不要使用机器翻译；社区会对译文进行人工审核，请仅在你精通的语言上提交翻译。

完成上述全部准备工作后，就可以正式进入第 1 课，开启生成式 AI 与 LLM 的系统学习之旅了。祝你编码愉快，愿你用生成式 AI 创造出令人兴奋的作品！