generative-ai-for-beginners 本地开发环境搭建实战：原生 Python、Dev Container、Miniconda 与 Jupyter 四种方案全解析

本文基于 generative-ai-for-beginners 课程仓库的本地环境安装文档（00-course-setup/02-setup-local.md）整理并扩充，面向希望在个人电脑上完整运行全部 21 节课代码的读者。你将掌握四种本地环境搭建路径——原生 Python 虚拟环境、VS Code Dev Container（Docker）、Miniconda 和浏览器 Jupyter——的完整操作步骤，并结合仓库中 requirements.txt、.devcontainer/devcontainer.json、.env.copy 等真实配置文件理解每一步背后的工程细节，最终能独立完成环境搭建、依赖安装与 API 密钥安全配置。

1. 四种本地运行路径概览

当你不想使用云端 Codespaces、而希望把一切都跑在自己笔记本上时，本地安装文档给出了四条可选路径：

路径	方案	适用人群
A	原生 Python + 虚拟环境（venv）	追求最快上手，本机已有 Python
B	VS Code Dev Container + Docker	希望零依赖漂移、环境与他人完全一致
C	Miniconda	需要管理多套 Python 环境或安装 pip 不可用的包
D	经典 Jupyter / JupyterLab（浏览器）	偏好浏览器界面，或不想用 VS Code

四条路径最终都通向同一套课程代码，可以任选其一。此外还有两种“混合模式”值得注意：路径 B 的环境与 GitHub Codespaces 完全一致，路径 C 的 environment.yml 在 Codespaces 中会放在 .devcontainer/ 子目录下。

2. 前置依赖检查

开始任何方案之前，先确认本机工具链是否齐备。文档给出的最低要求如下：

工具	版本 / 说明
Python	3.10 及以上
Git	最新版本（macOS 随 Xcode 附带，Windows 用 Git for Windows，Linux 用系统包管理器）
VS Code	可选但强烈推荐
Docker Desktop	仅选项 B 需要，可免费下载安装

小技巧：在终端中逐条执行 python --version、git --version、docker --version、code --version 即可快速验证。

这一 3.10 的门槛并非随意设定——仓库根目录的 pyproject.toml 中声明了 requires-python = ">=3.10"，且 black、mypy、ruff 等代码质量工具均以 py310 为最低目标版本。如果你安装了更新版本，仓库中的 .python-version 文件显示当前维护环境使用的是 3.12.10。

3. 选项 A：原生 Python 虚拟环境（最快）

这是最直接的方案，三步完成：

步骤 1：克隆仓库

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

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

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

激活成功后，终端提示符前会带上 (.venv) 前缀——这是你已进入隔离环境的标志。虚拟环境的作用是让课程依赖不会污染系统 Python，也不会与你在做的项目冲突。

步骤 3：安装依赖

pip install -r requirements.txt

这一步是选项 A 的核心。当前仓库的 requirements.txt 内容如下，值得逐项了解：

ipywidgets==8.1.8
numpy==2.4.2
matplotlib==3.10.8
pandas==3.0.0
tqdm==4.68.4
python-dotenv==1.2.2
openai>=1.12.0
tiktoken
azure-ai-inference
scikit-learn

从这份清单可以看出课程的代码形态：openai 与 azure-ai-inference 是访问大模型 API 的 SDK；python-dotenv 负责加载 .env 中的密钥（下节详述）；numpy、pandas、matplotlib、scikit-learn、tiktoken 支撑各课中的数据处理、可视化与分词练习；ipywidgets 则是 Notebook 交互组件。全部安装完成后，即可跳到第 6 节配置 API 密钥。

4. 选项 B：VS Code Dev Container（Docker）

仓库已经内置了一个开发容器（Dev Container）配置，采用支持 Python3、.NET、Node.js 和 Java 的通用运行时镜像，让你在容器内获得与 Codespaces 完全一致的环境，从根源上消除“在我机器上能跑”的依赖漂移问题。

步骤 0：安装配套工具

• Docker Desktop：确认 docker --version 可正常输出；
• VS Code 的 Remote – Containers 扩展（扩展 ID：ms-vscode-remote.remote-containers）。

步骤 1：用 VS Code 打开仓库

菜单 文件 ▸ 打开文件夹… → 选择 generative-ai-for-beginners 目录。VS Code 检测到根目录下的 .devcontainer/ 文件夹后，会自动弹出提示。

步骤 2：重新打开到容器中

点击“Reopen in Container（在容器中重新打开）”。Docker 首次构建镜像大约需要 3 分钟，当新终端提示符出现时，你就已经在容器内部了。

底层发生了什么：解读 devcontainer.json

这一步的自动化逻辑全部写在 .devcontainer/devcontainer.json 中，值得逐行理解：

• "image": "mcr.microsoft.com/devcontainers/universal:2.13" —— 使用微软官方的 Universal 开发容器镜像，这就是文档所说的“同时支持 Python3/.NET/Node.js/Java”的来源；
• "hostRequirements": { "cpus": 4 } —— 要求宿主机至少 4 核 CPU；
• "updateContentCommand": "python3 -m pip install -r requirements.txt" —— 每次打开容器时自动同步 requirements.txt 中的依赖，保证环境与仓库代码匹配；
• "postCreateCommand": "bash .devcontainer/post-create.sh" —— 容器创建后执行 .devcontainer/post-create.sh。

再看 .devcontainer/post-create.sh 的实际内容：它先安装 python-dotenv 和 openai，随后再装上 ruff、black、mypy、pytest 等开发者工具。脚本注释特别说明，这些工具与仓库 CI 工作流的检查项保持一致——换句话说，容器内构建出的环境不仅能跑课程代码，还能让你在提交代码前本地复现 CI 的 lint、格式化和测试检查。

此外，customizations.vscode.extensions 中还预装了一批编辑器扩展（Python、Pylance、Jupyter、Black Formatter、Ruff、ESLint、Prettier、Copilot），并配置了保存时自动格式化（Python 用 Black、JS/TS 用 Prettier）。这就是“开箱即用”的具体含义。

5. 选项 C：Miniconda

Miniconda 是安装 Conda、Python 及少量基础包的轻量安装器。Conda 本身是一个包管理器，能让你方便地创建、切换多套 Python 虚拟环境，还能安装一些通过 pip 拿不到的包。

步骤 0：安装 Miniconda

按官方 MiniConda 安装指南完成后，用以下命令验证：

conda --version

步骤 1：创建环境描述文件

新建一个环境文件 environment.yml。如果你是在 Codespaces 中跟练，应把它放在 .devcontainer 目录下，即 .devcontainer/environment.yml。

步骤 2：填充环境文件

文档给出的模板如下：

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

其中 <environment-name> 是你要给 Conda 环境起的名字，<python-version> 是指定 Python 版本（如 3）。pip: 小节表示这部分依赖仍走 pip 安装。

仓库中真实提交了一份对应的 .devcontainer/environment.yml，可以对照它确认实际取值：

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

两者差异反映了仓库演进：真实文件将 Python 锁定为 3.10.0（与前置要求一致），并把 azure-ai-ml 换成了 azure-ai-inference——与 requirements.txt 中当前的推理 SDK 保持一致。

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

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

若使用 Conda 时遇到报错，可用 conda install -c microsoft azure-ai-ml 手动补装微软 AI 相关库。

6. 选项 D：经典 Jupyter / JupyterLab（浏览器中运行）

适合谁？ 喜欢经典 Jupyter 界面、或希望完全绕开 VS Code 直接在浏览器里跑 Notebook 的读者。

步骤 1：启动 Jupyter

在终端进入课程目录后执行：

jupyter notebook

或者（多用户场景）：

jupyterhub

启动后，命令行窗口会打印出一个访问 URL。在浏览器打开该地址，你应该能看到课程目录结构，并可导航到任意 *.ipynb 文件，例如 08-building-search-applications/python/oai-solution.ipynb。

7. 配置 API 密钥：.env 文件与 python-dotenv

API 密钥的安全管理是本地搭建的最后一环，也是安全实践的底线：绝不要把密钥写进代码。把密钥提交到公共仓库可能带来安全问题，甚至产生不预期的费用。

文档以逐字面方式（阿语版示例使用 GITHUB_TOKEN 变量）演示了 .env 的创建流程，完整继承如下六步：

1. 进入项目根目录：

   cd path/to/your/project
   

2. 创建 .env 文件：

   Unix 系统：

   touch .env
   

   Windows：

   echo . > .env
   

3. 编辑 .env：在文本编辑器（VS Code、Notepad++ 等）中写入你的凭据。阿语版文档示例为：

   GITHUB_TOKEN=your_github_token_here
   

   需要特别注意：仓库当前版本已经完成凭据体系迁移。英文主文档明确标注 GitHub Models 及其 GITHUB_TOKEN 变量将于 2026 年 7 月底退役，替代方案为 Microsoft Foundry Models。以仓库根目录的 .env.copy 为准，实际应填入的变量是：

   AZURE_INFERENCE_ENDPOINT=<your Foundry project endpoint, e.g. https://<resource-name>.services.ai.azure.com/models>
   AZURE_INFERENCE_CREDENTIAL=<your Foundry Models API key>
   

   更完整的 .env.copy 还预置了 OPENAI_API_KEY、AZURE_OPENAI_API_KEY/AZURE_OPENAI_ENDPOINT/AZURE_OPENAI_DEPLOYMENT 等 Azure OpenAI 变量与 HUGGING_FACE_API_KEY。各变量含义与获取方式详见 00-course-setup/03-providers.md——更高效的实际做法是直接执行 cp .env.copy .env 再填空。

4. 保存文件。

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

   pip install python-dotenv
   

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-dotenv”流程并非纸上谈兵。仓库中的课程代码统一通过 shared/python/env_utils.py 读取这些变量：get_required_env() 会在变量缺失或为空时抛出带明确提示的 ValueError（提示你去 .env 中设置），validate_env_vars() 则一次性校验多个必需变量。也就是说，若你第 7 节步骤没做对，课程脚本失败时给出的报错会直接指向 .env 配置问题，而不是含糊的 NoneType 错误。

安全性同样有仓库层面的保证：根目录的 .gitignore 在“Environments”一节中明确列出了 .env、.venv、env/、venv/ 等条目，所以 .env 永远不会被误提交——这也是文档反复强调“放心创建 .env”的底气所在。

8. 故障排查速查表

文档提供了本地搭建阶段最常见的七类症状与对策，完整继承如下：

症状	解决方案
python not found	将 Python 加入 PATH，或安装后重开终端
pip 无法构建 wheel（Windows）	执行 pip install --upgrade pip setuptools wheel 后重试
ModuleNotFoundError: dotenv	说明环境没装依赖，执行 pip install -r requirements.txt
Docker 构建失败 No space left	Docker Desktop ▸ 设置 ▸ 资源 → 增大虚拟磁盘大小
VS Code 反复提示“重新打开”	选项 A 与 B 同时处于激活状态，二选一（venv 或 容器）
OpenAI 401 / 429 错误	检查 OPENAI_API_KEY 取值 / 请求频率限制
使用 Conda 报错	用 conda install -c microsoft azure-ai-ml 补装微软 AI 库

其中“VS Code 反复提示重新打开”一条尤其值得展开：它正是选项 A 与 B 机制冲突的典型表现——venv 插件和 Dev Container 扩展都在争夺“用哪个解释器”，明确只激活一种路径即可消除弹窗。

9. 下一步

我想…	去哪里
开始第 1 课	01-introduction-to-genai/README.md
配置 LLM 服务商（OpenAI / Azure / Foundry / Hugging Face 等）	00-course-setup/03-providers.md
云端 Codespaces 路线	00-course-setup/01-setup-cloud.md

至此，环境搭建的全部要素——四条可选路径、requirements.txt 依赖清单、.env.copy 凭据模板、.gitignore 安全边界——均已就位。无论选择哪条路径，验证标准只有一条：在激活的环境中运行任一课程的 Python 脚本或 Notebook，能成功加载 .env 并调通模型 API，即代表本地环境搭建完成，可以正式进入课程学习。