企业官网建设流程全解析

generative-ai-for-beginners 本地环境配置实战：venv、Dev Container、Miniconda 与 Jupyter 四种部署路径及 .env 密钥管理

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

本篇基于 generative-ai-for-beginners 课程的《Local Setup》指南（意大利语版 02-setup-local.md），系统讲解如何在自有笔记本上搭建课程所需的开发环境：从四种运行方式（原生 Python 虚拟环境、VS Code Dev Container、Miniconda、经典 Jupyter）的完整操作步骤，到.env文件创建与 API 密钥安全管理。读完本文，你可以任选一条路径完成从零到可运行 Notebook 的全部配置，并理解仓库中 requirements.txt、.devcontainer/devcontainer.json 等配置文件背后的一致性设计。

1. 前置条件（Prerequisites）

文档要求读者优先在终端中验证工具链就绪，四条路径共享同一组前置条件：

在终端中执行以下命令逐一确认：

python --version git --version docker --version code --version

仓库根目录还包含 .python-version 与 pyproject.toml，前者是 pyenv 等工具读取的 Python 版本锁定文件，后者是仓库的 Python 项目配置；它们与文档要求的 "Python 3.10+" 共同界定了课程的运行环境前提。

2. 选项 A：原生 Python + 虚拟环境（最快路径）

2.1 克隆仓库

课程要求先 Fork 仓库到自己的账号（以便修改代码并完成挑战），然后克隆：

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

2.2 创建并激活虚拟环境

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

激活成功后，命令提示符应以(.venv)开头，表示当前 shell 已处于虚拟环境内部。

2.3 安装依赖

pip install -r requirements.txt

这一步是整个本地部署的核心。从 requirements.txt 的实际内容看，课程锁定的依赖集覆盖了 Notebook 交互、数据处理与模型调用三类场景：

ipywidgets==8.1.8 # Jupyter 交互式组件 numpy==2.4.2 # 数值计算 matplotlib==3.10.8 # 绑图 pandas==3.0.0 # 表格数据处理 tqdm==4.68.4 # 进度条 python-dotenv==1.2.2 # 加载 .env 环境变量（第 3 节密钥管理的基础） openai>=1.12.0 # OpenAI SDK（兼容 Azure / Foundry 端点） tiktoken # Token 计数，课程中讲解分词器原理 azure-ai-inference # Azure 推理 SDK scikit-learn # 机器学习（第 08 课 RAG/检索相关练习用到）

值得注意的是python-dotenv被显式锁定版本（1.2.2）且版本较高，说明课程把.env加载视为运行时的一等公民而非可选依赖——这也是后文排查ModuleNotFoundError: dotenv的直接依据。

3. 选项 B：VS Code Dev Container（Docker 容器化）

课程为仓库预置了 Dev Container，使用"Universal runtime"官方镜像，同一容器内支持 Python3、.NET、Node.js 与 Java 开发，与 GitHub Codespaces 环境完全一致，杜绝本地依赖漂移（dependency drift）。

3.1 配置文件源码解析

相关配置定义在仓库根目录 .devcontainer/devcontainer.json 中，关键字段如下：

• "image": "mcr.microsoft.com/devcontainers/universal:2.13"：采用微软官方 Universal 开发容器镜像（版本 2.13），这正是文档所说"支持多种语言运行时"的底层原因；
• "hostRequirements": { "cpus": 4 }：要求宿主机至少 4 核 CPU，资源不足时容器无法启动；
• "waitFor": "onCreateCommand"：等待创建命令完成后才标记容器就绪；
• "updateContentCommand": "python3 -m pip install -r requirements.txt"：工作区内容更新时自动重新安装 requirements.txt 中的依赖，保证代码与依赖版本同步；
• "postCreateCommand": "bash .devcontainer/post-create.sh"：容器创建后执行 .devcontainer/post-create.sh 做初始化；
• customizations.vscode.extensions：预装 Python、Pylance、Jupyter、black-formatter、ruff、ESLint、Prettier、GitHub Copilot 等扩展，并配置保存时自动格式化（editor.formatOnSave: true），Python 默认格式化器为 black。

从源码结构看，容器每次"内容更新"都会重跑pip install -r requirements.txt，因此选项 B 天然避免了"文档依赖与容器实际依赖不一致"的问题——这是它与选项 A 最大的工程差异。

3.2 操作步骤

Step 0 — 安装附加组件：Docker Desktop（确认docker --version可用）+ VS Code 扩展 Remote – Containers（扩展 ID：ms-vscode-remote.remote-containers）。

Step 1 — 在 VS Code 中打开仓库：File ▸ Open Folder… → 选择generative-ai-for-beginners目录。VS Code 检测到.devcontainer/目录后会弹出提示。

Step 2 — 在容器中重开：点击 "Reopen in Container"。Docker 首次构建镜像约需 3 分钟；当终端提示符出现时，说明你已进入容器内部。此时容器会自动执行updateContentCommand与postCreateCommand，无需手动pip install。

4. 选项 C：Miniconda

Miniconda 是安装 Conda 与 Python 的轻量级安装包；Conda 本身是包管理器，便于在不同 Python 虚拟环境与包之间创建和切换，也可安装pip渠道之外的包（如预编译二进制）。

4.1 Step 0 — 安装 Miniconda

按官方 MiniConda 安装指南完成安装后验证：

conda --version

4.2 Step 1 — 创建环境文件

新建environment.yml。若你在 Codespaces 中跟练，应放在.devcontainer目录下，即.devcontainer/environment.yml。

4.3 Step 2 — 填写环境文件

文档给出的模板如下：

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

可以观察到两点实际演进：真实环境精确锁定python=3.10.0；pip 子依赖使用的是azure-ai-inference（与 requirements.txt 第 9 行保持一致），而文档模板中的azure-ai-ml是较早的 Azure Machine Learning 包，按当前仓库依赖集应优先以azure-ai-inference为准。

4.4 Step 3 — 创建并激活 Conda 环境

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

遇到 Conda 报错时，可参考文档的排障表（见第 8 节）用conda install -c microsoft azure-ai-ml手动补装微软 AI 库。

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

适合偏爱经典 Jupyter 界面、或不想依赖 VS Code 的读者。

进入课程目录后执行：

jupyter notebook

或

jupyterhub

命令启动一个 Jupyter 实例，终端窗口会打印访问 URL。打开该 URL 后可看到课程目录树，能直接导航到任意*.ipynb文件，例如 08-building-search-applications/python/oai-solution.ipynb。

6. 添加 API Keys：.env 文件与密钥安全

6.1 为什么必须用 .env

构建任何类型的应用时，保障 API 密钥安全都至关重要。课程明确建议不要把 API key 直接写进代码：把这些凭据提交到公开仓库，若被恶意者利用，会造成安全问题乃至意料之外的账单费用。

6.2 六步创建 .env（文档完整步骤）

1. 进入项目目录：

   cd path/to/your/project

2. 创建.env文件：Unix 系统用touch，Windows 用echo：

   touch .env # Unix

   echo . > .env # Windows

3. 编辑.env：用任意文本编辑器（VS Code、Notepad++ 等）打开，添加凭据行，替换占位符：

   GITHUB_TOKEN=your_github_token_here

   注意版本差异：意大利语版本文档此处以GITHUB_TOKEN为例，而仓库当前主干（英语版 02-setup-local.md 与 00-course-setup/README.md）已改用 Microsoft Foundry Models 凭据。仓库根目录提供了权威的模板文件 .env.copy，内容覆盖三类提供方：

   # OpenAI Provider OPENAI_API_KEY='<your OpenAI API key>' # Azure OpenAI in Microsoft Foundry AZURE_OPENAI_API_VERSION='2024-10-21' AZURE_OPENAI_API_KEY='<your Foundry resource key>' AZURE_OPENAI_ENDPOINT='https://<resource-name>.openai.azure.com' AZURE_OPENAI_DEPLOYMENT='gpt-4o-mini' AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='text-embedding-3-small' # Microsoft Foundry Models（多提供方目录：OpenAI、Meta、Mistral、Cohere 等） AZURE_INFERENCE_ENDPOINT='https://<resource-name>.services.ai.azure.com/models' AZURE_INFERENCE_CREDENTIAL='<your Foundry Models API key>' # Hugging Face HUGGING_FACE_API_KEY='<your HuggingFace token>'

   从 .env.copy 的注释看，GitHub Models 及其GITHUB_TOKEN变量将于 2026 年 7 月底退役，因此实际操作时建议直接以.env.copy为模板创建.env，而非沿用文档中较旧的GITHUB_TOKEN示例。

4. 保存文件：保存修改并关闭编辑器。

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

   pip install python-dotenv

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

   from dotenv import load_dotenv import os # 从 .env 文件加载环境变量 load_dotenv() # 读取变量 github_token = os.getenv("GITHUB_TOKEN") print(github_token)

6.3 源码佐证：仓库如何消费这些环境变量

仓库在 shared/python/env_utils.py 中提供了标准化的环境变量访问层，把"漏配 .env"从晦涩的None值变成显式报错：

• get_required_env(var_name, description)：读取必填变量，未设置时抛出ValueError并提示 "Please set it in your .env file or environment"（见 env_utils.py）；
• validate_env_vars(*var_names)：批量校验多个变量，一次性列出所有缺失项（env_utils.py）；
• get_env_with_default(var_name, default)：读取带默认值的变量（env_utils.py）。

配套的 shared/python/api_utils.py 则展示凭据如何落到客户端：create_openai_client()从OPENAI_API_KEY读取密钥构造 OpenAI 客户端（api_utils.py），create_azure_openai_client()从AZURE_OPENAI_ENDPOINT/AZURE_OPENAI_API_KEY读取并拼接<endpoint>/openai/v1/作为 base_url（api_utils.py）。这正是.env中AZURE_OPENAI_*变量的消费方，可帮助读者把配置文件里的每个变量名与课程代码一一对应。

安全底线：.env永远不要提交到版本库——它已被 .gitignore 覆盖。各提供方的完整申请说明见 00-course-setup/03-providers.md。

7. 下一步（What's next?）

8. 故障排查（Troubleshooting）

文档给出的完整排查表，覆盖从 Python 基础到 Docker 磁盘的典型症状：

补充两条与源码证据相关的判断依据：ModuleNotFoundError: dotenv之所以指向pip install -r requirements.txt，是因为 requirements.txt 已将python-dotenv==1.2.2列为锁定依赖；而"VS Code 反复提示重开容器"的根因是本地 venv 与.devcontainer/容器方案同时生效，在 VS Code 中应显式只采用其中一种。

9. 小结

本文完整继承了课程《Local Setup》指南的四条本地部署路径与密钥管理流程，并结合仓库源码补充了三处关键细节：依赖清单 requirements.txt 的逐项用途、.devcontainer/devcontainer.json 中镜像、CPU 要求与依赖自更新命令的真实配置，以及 shared/python/env_utils.py 展示的环境变量校验机制。按任一路径完成配置后，即可直接进入 01-introduction-to-genai/README.md 开始学习；遇到凭据问题先查阅 00-course-setup/03-providers.md。

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