generative-ai-for-beginners 课程环境搭建完整指南：Fork、Codespaces、密钥管理与本地运行

本篇指南围绕开源课程 [generative-ai-for-beginners]（当前仓库的课程起步与设置说明，关联文档为 translations/cs/00-course-setup/README.md）展开，系统梳理从「Fork 仓库 → 创建 Codespaces → 安全存放 API 密钥 → 本地运行 → 配置 LLM 提供商」的完整链路。读完本文，你将能够独立搭好可运行课程代码的实验环境，并掌握 .env、Codespaces Secrets、Conda 虚拟环境与 Jupyter/容器等四种典型运行方式的选择与排障方法，直接进入后续 21 个章节的动手环节。

1. 为什么先看课程设置说明

课程仓库以章节目录形式组织（仓库根目录下可见 00-course-setup 至 21-meta 共 21 个编号章节）。其中 00-course-setup 目录是整个课程的「出发站」：它不讲授生成式 AI 本身，而是回答三个问题——课程如何运行、需要哪些技术前提、遇到问题去哪里求助。捷克语翻译版 translations/cs/00-course-setup/README.md 与仓库根级英文版 00-course-setup/README.md 内容一一对应，核心设置步骤包括：

1. Fork 课程仓库到自己的 GitHub 账户；
2. 创建 Codespaces（或在本地克隆运行）；
3. 安全地加入 LLM API 密钥；
4. 选一条适合自己的运行路径（云端 / 本地 / 容器 / Jupyter）；
5. 对照排查表解决最常见的启动故障。

课程中动手编码的部分依赖托管式 LLM 端点，需要持有相应服务商的 API 密钥。因此，密钥配置是整个环境搭建的关键一步——后续章节的 Python 代码会从环境变量中读取这些配置。

2. 云端零安装路线：Fork 仓库并创建 Codespaces

2.1 Fork 课程仓库

为能改动代码并完成章节作业，先把整个仓库 Fork 到自己的 GitHub 账户。Fork 之后你拥有可写副本，可以安全地修改任何代码。官方建议同时对仓库加星（Star），方便日后连同关联仓库一起快速找回。若你计划在本地修改后再提交作业，这也是提交 Pull Request 的前置动作（详见文末「参与贡献」小节）。

2.2 从 Fork 中一键创建 Codespace

推荐优先在 GitHub Codespaces 中运行课程，原因在于其内置预配置开发容器（Universal 运行时，覆盖 Python 3、.NET、Node.js、Java），可规避本机依赖冲突。

在你自己的 Fork 页面中操作：Code ▸ Codespaces ▸ New on main，即可在 main 分支上启动一个新的 codespace：

首次构建开发容器通常需要数分钟，之后每次打开都是秒级启动。仓库中的 .devcontainer/environment.yml 决定了容器内 Python 侧的关键依赖版本，实际内容为：

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

即容器内固定使用 Python 3.10.0，并预装 openai、python-dotenv 与微软的 azure-ai-inference SDK——这正是后续各章节代码实际 import 的对象，也正是你几乎无需手动安装依赖的原因。若构建流程异常，可在 Codespaces ➜ "Rebuild Container" 强制重建。

2.3 用 Codespaces Secrets 保存密钥（推荐）

将 API 密钥直接写进代码并提交到公共仓库会带来泄密与资费风险。Codespaces Secrets 是官方推荐的安全存放方式，配置步骤如下：

1. 点击左下角 ⚙️ 齿轮图标打开命令面板；
2. 选择 Codespaces : Manage user secret ➜ Add a new secret；
3. 名称填 OPENAI_API_KEY，值粘贴你的密钥，保存即可。

设置完成后，容器内的环境变量会被自动注入，课程代码无需任何改动即可读取。该方式仅对 Codespaces 生效；若你改用本地 Docker 或直接在本机运行，仍需走下文第 4 节的 .env 文件路线。

3. 下一步去哪：按目标选择路径

课程起步页用一张速查表帮你定位入口，本文将其内部链接统一转换为以仓库根目录为起点的相对路径，方便直接跳转：

我想……	前往……
开始第 1 课	01-introduction-to-genai
在本地离线工作	00-course-setup/02-setup-local.md
配置 LLM 提供商	00-course-setup/03-providers.md
只在浏览器中使用经典 Jupyter	00-course-setup/02-setup-local.md

此外，若你完全不想在本机安装任何东西、只想使用云端 Codespaces，可参考同为 00-course-setup 目录下的 01-setup-cloud.md，其中给出了更细的 Codespaces 一键创建与密钥配置说明。

4. 在本地电脑上运行：克隆与 Python 环境

本地运行的前提是安装某个版本的 Python（建议 3.10 及以上，仓库开发容器即固定于 3.10.0）。随后克隆仓库：

git clone https://github.com/microsoft/generative-ai-for-beginners
cd generative-ai-for-beginners

若使用原生 Python，推荐配合虚拟环境（venv）隔离依赖：

python -m venv .venv          # 创建虚拟环境
source .venv/bin/activate     # macOS / Linux
.\.venv\Scripts\activate      # Windows PowerShell
pip install -r requirements.txt

命令提示符前出现 (.venv) 即代表已进入虚拟环境。课程根目录的 requirements.txt 与各章节的 requirements.txt（例如 06-text-generation-apps/python/requirements.txt）已声明全部依赖，一条 pip install 即可装齐。若你更习惯 Conda 或浏览器版 Jupyter，见第 6 节的可选方案。

5. 密钥管理核心：.env 文件全流程

无论走哪条运行路线，密钥配置原理都是统一的——把凭据放进环境变量，让代码从环境读取，而非硬编码进源码。以下流程把课程说明中的步骤串成可复制的完整清单。

5.1 从模板创建 .env

仓库根目录提供了带注释的凭据模板 .env.copy。先复制为 .env：

cp .env.copy .env

.env 已被 .gitignore 忽略，不会随 Git 提交，因此是存放密钥的安全位置（参见 本地设置指南 中的提醒：永远不要提交 .env）。

5.2 按提供商填写变量

.env.copy 中的变量即课程代码约定的读取名，覆盖了课程涉及的多个服务商：

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

## Azure OpenAI（现已并入 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>'
AZURE_OPENAI_DEPLOYMENT='<add your chat completion model deployment name here>'
AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='<add your embeddings model deployment name here>'

## Microsoft Foundry Models（一个端点/一把密钥访问多厂商模型）
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>'

各变量含义与取值来源可归纳如下（完整对照表见 00-course-setup/03-providers.md）：

变量	含义
HUGGING_FACE_API_KEY	Hugging Face 个人设置中的用户访问令牌
OPENAI_API_KEY	非 Azure 的 OpenAI 端点授权密钥
AZURE_OPENAI_API_KEY	Azure OpenAI 资源授权密钥
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 密钥

版本口径说明：捷克语翻译起步页的 .env 示例段落仍停留在旧版 GITHUB_TOKEN 流程；而当前仓库的英文起步页、本地设置指南、提供商配置 与根目录 .env.copy 均已切换为 Microsoft Foundry Models（AZURE_INFERENCE_ENDPOINT / AZURE_INFERENCE_CREDENTIAL）。原 GitHub Models 及其 GITHUB_TOKEN 变量已按计划退役，请以 Foundry Models 为准。

5.3 读取环境变量：python-dotenv 的标准用法

.env 本身不会被 Python 自动加载，需要借助 python-dotenv 包。先安装：

pip install python-dotenv

再在脚本中加载：

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)

5.4 仓库代码如何消费这些变量

「环境变量驱动配置」并非口头约定，而是仓库代码的既定事实。共享工具模块 shared/python/env_utils.py 提供了三个工具函数：

• get_required_env(var_name, description)：读取必需变量，缺失时抛出带提示的 ValueError（env_utils.py）；
• validate_env_vars(*var_names)：一次校验多个变量并返回 {变量名: 值} 字典，缺失列表会一并写入报错信息（env_utils.py）；
• get_env_with_default(var_name, default)：读取带默认值的可选变量（env_utils.py）。

对应测试见 tests/test_env_utils.py。这意味着如果你漏配密钥，各章节脚本启动时会立刻得到「Missing required environment variable: …」的明确报错，而不是令人困惑的运行时异常——这也是第 7 节排查表中 401 Unauthorized 等问题的根因入口。

6. 可选：按习惯挑选你的运行环境

起步页为不满足于默认路线的学习者提供了四种可选开发环境，均可独立跑通课程代码。

6.1 Miniconda / Conda 虚拟环境

Conda 的优势在于方便地在不同 Python 虚拟环境与包集合之间切换，也能安装 pip 覆盖不到的包。安装 Miniconda 后创建 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 表示最新的 3.x 主版本）。随后创建并激活环境：

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

若用 Conda 安装微软 AI 库时报错，可在终端手动执行：

conda install -c microsoft azure-ai-ml

需要提醒的是，仓库实际随附的 .devcontainer/environment.yml 比文档示例更精简（name: dev、python=3.10.0、额外引入 azure-ai-inference 而非 azure-ai-ml）。示例中的占位结构用于教学，实机环境请优先参考仓库内的真实文件。

6.2 VS Code + Python 扩展

课程推荐使用安装了 Python 支持扩展的 VS Code 作为编辑器，但这是建议而非硬性要求。值得记住的三条提示：

• 打开仓库时，VS Code 会因仓库内的 .devcontainer 目录而建议「在容器中重新打开」，这是启用开发容器能力的入口；
• 克隆并打开目录后，VS Code 通常会自动提示安装 Python 扩展；
• 若你希望使用本机已安装的 Python（而非容器），请拒绝「Reopen in Container」的请求。

6.3 浏览器里的 Jupyter

偏爱经典笔记本界面的学习者，可以在浏览器中直接使用 Jupyter / Jupyter Hub。在课程目录的终端执行：

jupyter notebook

或

jupyterhub

启动后，命令窗口会打印访问 URL；打开后可见课程目录大纲，并可直接进入任意 *.ipynb 文件，例如 08-building-search-applications/python/oai-solution.ipynb。课堂各章节的 notebook 均带有可直接查看的代码与输出，即便暂未申请到模型服务也能先读代码。

6.4 完整开发容器（Docker）

仓库中的 .devcontainer 目录让 VS Code 能够把项目整体装入容器，从而获得与 Codespaces 完全一致的运行时、避免依赖漂移。注意：在 Codespaces 之外使用该方案需要自行安装 Docker 并完成较繁琐的初始化，起步页明确建议只有熟悉容器的用户选择此路线。

7. 常见问题排查速查表

起步文档给出了高频故障与对应修复，整理如下：

症状	修复方法
容器构建卡住超过 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

本地运行时另有几类典型问题（补充自 00-course-setup/02-setup-local.md）：python not found 需将 Python 加入 PATH 或安装后重开终端；Windows 下 pip 无法构建 wheel 时可先执行 pip install --upgrade pip setuptools wheel；ModuleNotFoundError: dotenv 说明环境依赖未安装，回到 pip install -r requirements.txt；Docker 构建报 No space left 时在 Docker Desktop ▸ Settings ▸ Resources 中调大磁盘配额；OpenAI 报 401/429 则检查密钥值与请求限流。

8. 课程内容与技术前提

当前仓库共编排了 21 个编号章节（00-course-setup 至 21-meta）。编码类章节基于 Azure OpenAI 等托管 LLM 服务，运行代码需要服务访问权与 API 密钥；在等待申请审批期间，每个编码章节都自带 README.md，可以先行查看代码与输出。

第一次使用某家服务时，建议先走一遍该服务官方的资源创建流程：

• Azure OpenAI：在 Azure/AI Foundry 中创建并部署资源，通常至少需要一个文本生成模型部署（课程推荐 gpt-4o-mini）与一个文本嵌入模型部署（推荐 text-embedding-3-small），随后把部署名填回 AZURE_OPENAI_DEPLOYMENT / AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT；
• OpenAI：注册账户后在 API 密钥页创建密钥，填入 OPENAI_API_KEY；
• Microsoft Foundry Models：在 Foundry 项目模型目录中部署模型（如 gpt-4o-mini），从项目 Overview 页复制端点与密钥，填入 AZURE_INFERENCE_ENDPOINT 与 AZURE_INFERENCE_CREDENTIAL；
• Hugging Face：在个人设置 Access Tokens 中新建令牌，填入 HUGGING_FACE_API_KEY，切勿公开分享。

如果你希望完全不依赖云订阅，也可以在自有设备上运行兼容的开源模型，例如 Foundry Local（自动选择 NPU/GPU/CPU 执行后端并暴露 OpenAI 兼容端点）或 Ollama（本地运行 Llama、Phi、Mistral、Gemma 等），详见 19-slm 章节。

各章节作业文件通过在文件名中打标表明所需的提供商凭据：aoai 需要 Azure OpenAI 端点与密钥、oai 需要 OpenAI 端点与密钥、hf 需要 Hugging Face 令牌、githubmodels 对应 Foundry Models（原 GitHub Models 已退役）。你可以按兴趣配置其中一个、多个或全部提供商，未配置的服务仅会让对应作业在缺少凭据时报错，不影响其他练习。

9. 常见疑问与参与方式

• 遇到环境问题向谁求助？ 官方在社区聊天服务器（Discord）建立了课程频道，项目团队也会驻留其中解答学习者问题；
• 如何贡献？ 本课程是开源项目，发现可改进之处可提交 Pull Request 或登记 issue。多数贡献需同意 Contributor License Agreement（CLA），CLA-bot 会在提交 PR 时自动判断并给出引导；
• 翻译注意：仓库明确要求不使用机器翻译，所有翻译会经社区核验，因此只应在自己精通的语种上志愿翻译。

10. 现在就出发

环境就绪后，就从生成式 AI 与 LLM 的入门章节开始吧——第 1 课：生成式 AI 与 LLM 入门。这里会解释什么是大语言模型、tokenizer 如何工作、LLM 能做什么，并带你认识后续各章将反复使用的核心概念。一次成功的环境配置，是后续 21 个章节顺畅运行的最好铺垫。