Generative AI for Beginners 本地开发环境搭建实战指南：venv、Dev Container、Conda 与 Jupyter 四方案详解

Generative AI for Beginners 本地开发环境搭建实战指南：venv、Dev Container、Conda 与 Jupyter 四方案详解

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

本文基于本仓库课程设置文档 translations/es/00-course-setup/02-setup-local.md（对应英文原版 00-course-setup/02-setup-local.md）整理而成，系统讲解如何在自己的电脑上搭建可运行 21 节生成式 AI 实战课程的全部本地开发环境。文章提供四条可选的搭建路径：Python 原生 + 虚拟环境、VS Code Dev Container（Docker）、Miniconda + Conda、经典 Jupyter，并逐一给出前置依赖、可复制命令、依赖清单解析与.env密钥安全配置方法。读完本文你将具备从零初始化课程仓库、隔离 Python 环境、安装全部依赖、正确注入并读取各厂商 API 密钥的完整动手能力，可直接进入第 1 课 01-introduction-to-genai/README.md 开始学习。

如果你更倾向于无需本地安装的云端方案（GitHub Codespaces / Foundry 等），可先阅读配套的云端设置文档 00-course-setup/01-setup-cloud.md；本地与云端两条路线最终通向完全相同的 21 节课内容，选自己顺手的一条即可。

1. 前置要求：先确认本机工具链

无论选择下面哪一条路线，都建议先对照下表确认工具就绪。表中标注"仅 Option B 需要"的项，只有在走 Docker 容器路线时才必需。

安装完成后，打开终端依次执行下列命令验证全部就绪：

python --version git --version docker --version # 仅 Docker 路线需要 code --version # 仅 VS Code 路线需要

提示：若python命令报python not found，请把 Python 加入系统 PATH 并重新打开终端后再试（参见文末故障排查表）。

2. 方案 A：Python 原生 + venv（最快上手）

如果你只写 Python、想用最轻量的方式起步，这是推荐路径。它的核心是：克隆仓库 → 创建虚拟环境 → 按仓库 requirements.txt 安装依赖。

2.1 克隆本仓库

git clone https://gitcode.com/GitHub_Trending/ge/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)开头，说明你已进入隔离环境。此后pip install安装的所有包都只作用于本项目，不会污染系统级 Python。

2.3 安装课程依赖

pip install -r requirements.txt

仓库根目录的 requirements.txt 是全部课程代码的统一依赖清单，各依赖与用途对应如下：

安装完成后即可进入第 6 节配置 API 密钥，然后开始各课练习。

3. 方案 B：VS Code Dev Container（Docker）

如果你希望获得与 GitHub Codespaces完全一致的运行环境、彻底杜绝"在我机器上能跑"的依赖漂移问题，请选择本方案。本仓库已内置完整的容器化开发配置。

3.1 仓库内已有的容器配置

相关配置集中在仓库根目录的.devcontainer/文件夹，核心文件包括：

• .devcontainer/devcontainer.json：容器与 VS Code 集成声明；
• .devcontainer/post-create.sh：容器创建后自动执行的初始化脚本；
• .devcontainer/environment.yml：Conda 环境定义（方案 C 亦可复用）；
• .devcontainer/icon.svg：容器图标。

读取 .devcontainer/devcontainer.json 可以看到完整声明：该容器基于mcr.microsoft.com/devcontainers/universal:2.13通用开发镜像，内置 Universal runtime，可同时支撑Python3、.NET、Node.js 与 Java开发——这正对应本课程跨语言的教学设计（各课均同时提供python/、dotnet/、typescript/、js-githubmodels/等语言实现）。关键配置项含义如下：

其中 .devcontainer/post-create.sh 会额外安装python-dotenv、openai以及开发者工具链ruff black mypy pytest——脚本注释明确说明这组工具与.github/workflows/code-quality.yml中 CI 检查保持一致，意味着贡献者在本地即可复现仓库的代码质量检查（lint / 格式化 / 类型检查 / 测试）后再提交 PR。

3.2 操作步骤

Step 0 – 安装额外组件

• Docker Desktop：安装后确认docker --version能正常输出版本号；
• VS Code 扩展 Remote – Containers（扩展 ID：ms-vscode-remote.remote-containers）。

Step 1 – 用 VS Code 打开仓库菜单：文件 ▸ 打开文件夹… → 选择generative-ai-for-beginners。VS Code 会自动检测到根目录的.devcontainer/并弹出提示框。

Step 2 – 在容器中重新打开点击提示框中的 “Reopen in Container”（在容器中重新打开）。Docker 首次构建镜像约需3 分钟，之后会缓存复用。当终端出现命令提示符时，说明你已经身处容器内，可以直接开始跑各课代码与 notebook。

为什么选择它？环境与 Codespaces 完全一致，杜绝依赖漂移；缺点是首次构建需要等待并占用磁盘空间（见故障排查中 "No space left" 的解决办法）。

4. 方案 C：Miniconda + Conda

Conda 是跨 Python 的包与环境管理器，特别适合需要在多个 Python 版本/环境之间切换、或要安装pip无法覆盖的二进制/平台包（如azure-ai-ml）的场景。Miniconda 是其轻量安装器（conda.io 官网下载）。

4.1 安装并确认

按 MiniConda 官方命令行快速安装指南完成安装后，验证：

conda --version

4.2 编写environment.yml

新建一个环境定义文件environment.yml。如果同时在 Codespaces 中使用，应放在.devcontainer/目录下（即.devcontainer/environment.yml），这样容器构建时会被自动识别。

文档给出的通用模板如下（其中<environment-name>、<python-version>需按需替换）：

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

字段含义与取值说明：

仓库实际使用的环境定义可查看 .devcontainer/environment.yml，其内容为：环境名dev、python=3.10.0、openai、python-dotenv、pip，并在pip:段安装了azure-ai-inference（Microsoft Foundry 推理 SDK），可作参考模板。

4.3 创建并激活环境

conda env create --name ai4beg --file .devcontainer/environment.yml # 若你的 environment.yml 放在项目根目录，则使用：conda env create --name ai4beg --file environment.yml conda activate ai4beg

其中子路径.devcontainer/仅适用于 Codespace 环境布局；本地使用时请指向你实际存放environment.yml的位置。激活成功后同样可以执行conda install -c microsoft azure-ai-ml补装微软 AI 库。遇到问题可参考 Conda 官方环境管理指南，或查阅本文第 8 节故障排查中 "Errors using Conda" 一栏。

5. 方案 D：经典 Jupyter / Jupyter Lab

若你偏爱经典 Jupyter 界面、或希望脱离 VS Code 直接运行课程 notebook，请选择本方案。仓库各课目录（如04-prompt-engineering-fundamentals/python/、06-text-generation-apps/python/、08-building-search-applications/python/）下散布着大量*.ipynb练习与解答文件。

5.1 启动 Jupyter

进入终端，先切换到课程根目录，然后执行：

jupyter notebook

或者启动 JupyterHub：

jupyterhub

启动后，命令行窗口会显示可访问的 URL（默认 http://localhost:8888）。打开该 URL，你会看到课程目录索引，可点入任意*.ipynb文件。例如：

• 08-building-search-applications/python/oai-solution.ipynb——第 8 课搜索应用（OpenAI 路径）参考解答；
• 06-text-generation-apps/python/oai-app.py——第 6 课文本生成应用的 Python 脚本实现（非 notebook 路线可运行python脚本替代）。

提示：请确保在运行前已完成依赖安装（方案 A 的pip install -r requirements.txt）并在.env中填好 API 密钥，否则 notebook 中的调用会报缺少密钥或缺失模块。

6. 添加并安全管理你的 API 密钥（.env）

把 API 密钥硬编码进源码是安全大忌——一旦提交到公开仓库，不仅会泄露凭据，还可能被恶意方盗用造成不必要的费用。本课程统一推荐使用.env文件 +python-dotenv的方式管理密钥。仓库根目录的 .env.copy 提供了完整的密钥变量参考模板（复制为.env后按注释填写即可）。

6.1 分步创建 .env

Step 1 – 进入项目根目录

cd path/to/your/project # 即 generative-ai-for-beginners 目录

Step 2 – 创建.env文件

Unix 系（macOS/Linux）：

touch .env

Windows：

echo . > .env

Step 3 – 编辑文件内容

用 VS Code、Notepad++ 等文本编辑器打开.env，把占位符替换为你的真实凭据。结合 .env.copy 与各课源码读取逻辑，完整变量清单如下（按提供商分组）：

# OpenAI Provider（OpenAI 官方） OPENAI_API_KEY='<add your OpenAI API key here>' # Azure OpenAI（现已并入 Microsoft Foundry 门户 ai.azure.com 管理） AZURE_OPENAI_API_VERSION='2024-10-21' # 默认即可，当前稳定 GA API 版本 AZURE_OPENAI_API_KEY='<add your Foundry resource key here>' AZURE_OPENAI_ENDPOINT='https://<resource-name>.openai.azure.com' AZURE_OPENAI_DEPLOYMENT='<your chat completion model deployment name, e.g. gpt-4o-mini>' AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='<your embeddings model deployment name, e.g. text-embedding-3-small>' # Microsoft Foundry Models（多提供商模型目录：OpenAI、Meta、Mistral、Cohere、Microsoft 等共用一个 endpoint/key） AZURE_INFERENCE_ENDPOINT='https://<resource-name>.services.ai.azure.com/models' AZURE_INFERENCE_CREDENTIAL='<your Microsoft Foundry Models API key here>' # Hugging Face HUGGING_FACE_API_KEY='<add your HuggingFace API or token here>'

需要特别说明两点（与本文档翻译版内容相关的版本差异）：

• 原翻译文档 translations/es/00-course-setup/02-setup-local.md 的密钥示例以 GitHub Models 的GITHUB_TOKEN为准；但仓库英文原版 00-course-setup/02-setup-local.md 已注明GitHub Models（及其GITHUB_TOKEN变量）将于 2026 年 7 月底退役，并改用 Microsoft Foundry Models 的AZURE_INFERENCE_ENDPOINT/AZURE_INFERENCE_CREDENTIAL两个变量，配置信息可在 Foundry 项目的 "Overview" 页面获取。
• 实际代码采用哪组变量，由各课脚本决定（OpenAI 路径读OPENAI_API_KEY，Azure OpenAI 路径读AZURE_OPENAI_*，Foundry 路径读AZURE_INFERENCE_*），以 .env.copy 注释为准即可。

Step 4 – 保存文件，完成。

Step 5 – 安装python-dotenv（若尚未随 requirements.txt 安装）：

pip install python-dotenv

Step 6 – 在 Python 代码中加载

from dotenv import load_dotenv import os # 从 .env 文件加载环境变量 load_dotenv() # 访问环境变量 github_token = os.getenv("GITHUB_TOKEN") # 旧版（GitHub Models） endpoint = os.getenv("AZURE_INFERENCE_ENDPOINT") # 新版（Microsoft Foundry） token = os.getenv("AZURE_INFERENCE_CREDENTIAL") print(github_token) print(endpoint)

6.2 仓库层面的密钥安全机制

除了规范，仓库还提供了代码级防护与工具函数：

• .gitignore已内置排除规则：根目录 .gitignore 中# Environments段落显式忽略了.env、.venv、env/、venv/等路径，确保.env不会被git add误提交。切勿手工强制提交.env。
• 共享工具函数统一校验：仓库在 shared/python/env_utils.py 提供了get_required_env()（取必填变量，缺失即抛出带说明的ValueError）、validate_env_vars(*names)（批量校验多个必填变量并返回字典）与get_env_with_default()（带默认值的读取），配合错误提示"Missing required environment variable: … Please set it in your .env file or environment"运行。相关行为有 tests/test_env_utils.py 等测试用例覆盖，各课脚本多通过这套工具读取配置，例如：

from shared.python.env_utils import validate_env_vars env = validate_env_vars("AZURE_OPENAI_ENDPOINT", "AZURE_OPENAI_API_KEY")

• 各提供商的完整配置指引收录于 00-course-setup/03-providers.md，创建/申请各类密钥前请先查阅该文档。

7. 环境就绪后：下一步怎么走

8. 故障排查速查表

按上述四选一路线完成环境搭建、并妥善配置.env密钥后，课程中所有 Python 脚本与 notebook（含 OpenAI、Azure OpenAI 与 Microsoft Foundry 三条代码路径）即可在本机顺畅运行，接下来就可以逐课推进，从第 1 课 LLM 基础一路实践到第 21 课 Meta Llama 开源模型应用。

说明：本文依据的是本仓库西语翻译目录下 translations/es/00-course-setup/02-setup-local.md 的本地环境配置文档，其中 API 密钥示例部分按仓库英文原版 00-course-setup/02-setup-local.md 及 .env.copy 的现行内容进行了同步更新（GitHub Models 退役 → Microsoft Foundry Models），其余操作步骤与四种环境方案均与原文保持一致并补充了仓库源码级佐证。

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