generative-ai-for-beginners 本地开发环境搭建全指南：四套方案、API 密钥管理与故障排查

本篇指南以本仓库 translations/da/00-course-setup/02-setup-local.md（英文原版见 00-course-setup/02-setup-local.md）为核心，系统性讲解如何把 generative-ai-for-beginners 这一共 21 课（覆盖提示词工程、RAG、AI Agent、微调、SLM 等主题）的生成式 AI 课程跑在你的个人电脑上。读完你将掌握四种互不冲突的本地运行方案（原生 Python 虚拟环境、VS Code Dev Container、Miniconda、经典 Jupyter），能安全地把 API 密钥写入 .env 并接入 Python 代码，同时获得一套可直接照做的常见问题排查表。

该课程的绝大多数动手练习都以 .py 脚本与 .ipynb notebook 形式分布于各课目录中（例如 08-building-search-applications/python/oai-solution.ipynb），因此"先搭好环境"是进入 21 课实战的第一步。

1. 环境准备：先检查这些前提工具

在动手之前，请先确认本机是否已具备下表所列工具。课程共提供 Option A/B/C/D 四套本地方案，你只需选择其中自己最顺手的一条，各方案最终都会通向完全相同的 21 课内容。

工具	版本 / 说明
Python	3.10 及以上（可在 Python 官网下载对应系统安装包）
Git	最新版本（macOS 随 Xcode 附带，Windows 使用 Git for Windows，Linux 用系统包管理器安装）
VS Code	可选但强烈推荐，用于打开仓库与运行 notebook
Docker Desktop	仅 Option B（Dev Container）需要，免费安装

💡 验证技巧：在终端里逐条执行以下命令，确认工具均已进入 PATH： python --version、git --version、docker --version、code --version

2. Option A —— 原生 Python + venv（最快上手）

这是最轻量的路线：不依赖 Docker，直接用系统 Python 创建隔离虚拟环境并安装依赖。

步骤 1：克隆仓库

git clone <your-repository-url>/generative-ai-for-beginners
cd generative-ai-for-beginners

说明：请把 <your-repository-url> 替换为你在代码托管平台实际 fork 到的仓库地址。

步骤 2：创建并激活虚拟环境

python -m venv .venv          # 创建虚拟环境
source .venv/bin/activate     # macOS / Linux 激活
.\.venv\Scripts\activate      # Windows PowerShell 激活

✅ 激活成功后，命令行提示符开头会出现 (.venv) 前缀，代表你已进入隔离环境，后续 pip 安装的包都会落在该环境内，不会污染系统 Python。

步骤 3：安装课程依赖

pip install -r requirements.txt

仓库根目录的 requirements.txt 锁定了本次课程实际使用的核心依赖，主要包括：openai>=1.12.0（OpenAI 兼容客户端）、python-dotenv（读取 .env）、tiktoken（tokenizer 示例）、azure-ai-inference（Azure AI 推理客户端）、以及 ipywidgets、numpy、matplotlib、pandas、tqdm、scikit-learn 等数据分析与可视化库。安装成功后，可直接跳至第 3 节"配置 API 密钥"。

3. Option B —— VS Code Dev Container（Docker 容器）

如果你希望"环境与云端 Codespaces 完全一致、彻底杜绝依赖漂移"，可以选用本方案。

为什么选它？ 容器内运行时与本仓库在 Codespaces 中使用的运行时相同；所有依赖一次性装入镜像，换机器不重装，团队协作时人人环境一致。

本仓库已经在根目录 .devcontainer/ 下内置了开发容器配置 .devcontainer/devcontainer.json。从该配置可以看到几个关键事实：

• 基础镜像：mcr.microsoft.com/devcontainers/universal:2.13（Universal runtime，同时支持 Python3、.NET、Node.js 与 Java 开发）；
• 硬件要求：hostRequirements.cpus: 4，即容器至少需要 4 核 CPU；
• 依赖安装：updateContentCommand 执行 python3 -m pip install -r requirements.txt；随后 postCreateCommand 运行 .devcontainer/post-create.sh，该脚本会额外安装 python-dotenv、openai，以及与本仓库质量门禁（code-quality 工作流）对应的开发工具 ruff、black、mypy、pytest；
• 预装扩展：配置中通过 customizations.vscode.extensions 预装了 Python/Pylance、Jupyter、Black Formatter、Ruff、ESLint、Prettier、GitHub Copilot 等扩展，并开启了"保存即格式化"（editor.formatOnSave）等设置。

步骤 0：安装额外组件

• 安装 Docker Desktop，并确认终端中 docker --version 可用；
• 在 VS Code 中安装 Remote – Containers 扩展（扩展 ID：ms-vscode-remote.remote-containers）。

步骤 1：在 VS Code 中打开仓库

File ▸ Open Folder… → 选择 generative-ai-for-beginners 文件夹。VS Code 会自动检测到 .devcontainer/，并弹出"在容器中重新打开"的提示。

步骤 2：重开进容器

点击 "Reopen in Container"。首次启动 Docker 需要构建镜像（约 3 分钟），当终端提示符重新出现时，你就已经位于容器内部，可以直接开始跑各课代码。

4. Option C —— Miniconda（面向科学计算的环境管理）

Miniconda 是 Conda 的轻量安装器，负责安装 Conda、Python 及少量默认包。Conda 本身是一个包管理器，能方便地创建与切换不同的 Python 虚拟环境 与包集合，尤其适合安装那些 pip 源中不可用的二进制包。

步骤 0：安装 Miniconda

按 Miniconda 官方安装指引完成安装后，验证：

conda --version

步骤 1：创建环境定义文件

新建一个 environment.yml。如果你在 Codespaces 里跟做，请把它放在 .devcontainer 目录下，即 .devcontainer/environment.yml。

步骤 2：填写环境文件

参考原文档，向 environment.yml 写入如下内容：

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

其中 <environment-name> 与 <python-version> 需替换为实际值。字段含义分别为：name 指定环境名；channels 声明包的来源频道；顶层 dependencies 安装 Conda 包（如 openai、python-dotenv），嵌套的 pip: 段则交给 pip 安装（如 azure-ai-ml）。

作为对照，仓库中已经内置了一份真实可用的同构文件 .devcontainer/environment.yml，其内容为：

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

可见其采用了 Python 3.10.0 固定版本，并通过 pip 段安装 azure-ai-inference（本课程多数推理示例使用的 Azure AI Inference 客户端）。

步骤 3：创建并激活 Conda 环境

在终端执行：

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

如果执行出错，可查阅 Conda 官方 environments 使用指南定位问题；若错误指向 Microsoft AI 库缺失，可执行 conda install -c microsoft azure-ai-ml 手动补装。

5. Option D —— 经典 Jupyter / Jupyter Lab（浏览器里跑 notebook）

适用人群：钟爱经典 Jupyter 界面，或希望不借助 VS Code 直接运行 notebook 的学习者。

在终端进入课程目录后，执行以下任一命令：

jupyter notebook

或

jupyterhub

命令会启动一个 Jupyter 实例，并在命令行窗口中打印访问 URL。浏览器打开该 URL 后即可看到课程总览，进而导航到任意 *.ipynb 文件，例如本仓库搜索类应用的官方解答 08-building-search-applications/python/oai-solution.ipynb。

6. 配置 API 密钥：.env 文件与密钥安全

构建任何调用 LLM 的应用，密钥安全都是第一要务。严禁把 API 密钥硬编码在代码里，更不要把它提交进公开仓库——一旦泄露，可能带来安全问题甚至被恶意调用产生不必要的费用。正确做法是使用 .env 文件存放密钥，并通过 python-dotenv 在运行时加载。

下面是逐步操作说明：

第 1 步：进入项目目录。 打开终端，cd 到要创建 .env 的项目根目录：

cd path/to/your/project

第 2 步：创建 .env 文件。 用文本编辑器新建即可；命令行下可用 touch（Unix 系）或 echo（Windows）：

touch .env        # Unix 系

echo . > .env     # Windows

第 3 步：编辑文件并写入密钥。 用 VS Code 等编辑器打开 .env，加入如下内容并把占位符替换为你的真实密钥（以本课程采用的 GitHub Token / Azure 推理凭据为例）：

GITHUB_TOKEN=your_github_token_here

版本口径说明：原文档写作时 GitHub Models 及其 GITHUB_TOKEN 变量为主要方案；而当前仓库主干代码已转向 Microsoft Foundry / Azure 推理端点。例如 06-text-generation-apps/python/githubmodels-app.py 中直接读取的已是 AZURE_INFERENCE_CREDENTIAL 与 AZURE_INFERENCE_ENDPOINT 两个变量，requirements.txt 也相应引入了 azure-ai-inference。因此实际填写变量名时，请以 00-course-setup/03-providers.md 中对应你所用供应商的最新说明为准。

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

第 5 步：安装 python-dotenv。 用它在 Python 应用中从 .env 加载环境变量：

pip install python-dotenv

第 6 步：在 Python 脚本中加载变量。 以读取 GITHUB_TOKEN 为例：

from dotenv import load_dotenv
import os

# 从 .env 文件加载环境变量
load_dotenv()

# 读取 GITHUB_TOKEN 变量
github_token = os.getenv("GITHUB_TOKEN")

print(github_token)

至此，你已经完成了 .env 创建、密钥写入与加载的完整闭环。仓库对此还有更工程化的封装：共享模块 shared/python/env_utils.py 提供了 get_required_env() 与 validate_env_vars()，一旦缺失关键变量会抛出带提示的 ValueError，方便在应用启动早期就暴露配置问题；其行为有对应的 tests/test_env_utils.py 测试用例兜底。

🔐 永远不要提交 .env——它已被写入仓库根目录 .gitignore（第 123 行 .env）。各供应商的完整密钥获取与配置说明见 03-providers.md。

7. 下一步去哪

环境就绪后，可根据下表规划学习路径：

我想……	前往
开始第 1 课	01-introduction-to-genai
配置 LLM 供应商	providers.md
与其他学习者交流	加入本课程官方社区（Discord）

8. 常见问题排查（Troubleshooting）

原文档沉淀了一张高价值的故障速查表，遇到报错时优先对照下表：

症状	解决方案
python not found	把 Python 加入 PATH，或在安装后重新打开终端
pip 在 Windows 上无法构建 wheels	执行 pip install --upgrade pip setuptools wheel 后重试
ModuleNotFoundError: dotenv	说明环境未正确安装依赖，运行 pip install -r requirements.txt
Docker 构建报错 No space left	Docker Desktop ▸ Settings ▸ Resources，调大磁盘配额
VS Code 反复提示重新打开容器	可能同时启用了两套方案，请二选一（venv 或 容器），避免环境冲突
OpenAI 401 / 429 错误	检查 API 密钥值是否正确 / 是否触发请求速率限制
使用 Conda 报错	用 conda install -c microsoft azure-ai-ml 安装 Microsoft AI 库

9. 方案选择小结

• 想最快跑通、机器干净：选 Option A（原生 Python + venv），一条 pip install -r requirements.txt 即可；
• 追求与 CI/Codespaces 完全一致、团队协作：选 Option B，仓库已内置 .devcontainer/devcontainer.json 全套配置；
• 从事科学计算、需要 Conda 生态：选 Option C，参考 .devcontainer/environment.yml 实文件；
• 只爱 Jupyter 交互式学习：选 Option D，直接对任意 *.ipynb（如 08-building-search-applications/python/oai-solution.ipynb）开跑。

无论选择哪条路径，最终都将进入完全相同的 21 课内容，从第 1 课的生成式 AI 原理一路学到 AI Agent 与 RAG 实战。