企业官网建设流程全解析

generative-ai-for-beginners 本地环境搭建指南：四套可选的开发方案与密钥安全配置

【免费下载链接】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是微软推出的 21 课生成式 AI 入门课程仓库，各章节同时提供 Python 代码、Jupyter Notebook 与 TypeScript/JavaScript 示例。本文面向希望在自己的笔记本上离线运行全部课程代码的开发者，系统讲解从「克隆仓库」到「密钥安全注入」的完整本地配置流程：官方提供了两条主线——(A) 原生 Python + venv 与 (B) VS Code Dev Container（Docker），另有 (C) Miniconda 与 (D) 经典 Jupyter 两条进阶路径。读完本文你将掌握四种环境的搭建方法、仓库依赖清单的真实含义，以及使用.env文件安全加载 API 凭据的正确姿势，从而平滑接续后续每一课的动手练习。

1. 前置条件：确认本机工具链

在开始前，请确认以下工具已安装到你的机器上。下表来自课程官方本地配置文档 translations/el/00-course-setup/02-setup-local.md 与 00-course-setup/02-setup-local.md（英文原文，两文结构一致）：

提示：安装完毕后，建议先在终端里验证工具是否可用：python --version、git --version、docker --version、code --version

值得补充的是，「Python 3.10+」并非随意设定：仓库根目录的 pyproject.toml 中requires-python = ">=3.10"，且开发工具链（black、mypy 等）的 target-version 均指向 py310 及以上，因此 3.10 是本仓库实际支持的基线版本。

2. 方案 A：原生 Python + 虚拟环境（最快捷）

如果你希望环境最轻、启动最快，优先选择本方案。它不依赖 Docker，只依赖本机 Python。

步骤 1：克隆仓库

课程要求先 fork 再克隆（便于你提交自己的练习代码），随后进入仓库根目录：

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

其中<your-github>请替换为你自己的 GitHub 用户名（fork 流程详见 00-course-setup/README.md）。

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

Python 官方虚拟环境工具venv能在项目目录内隔离出一份独立依赖，避免污染全局 Python：

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

✅ 激活成功的标志是命令行提示符前缀出现(.venv)——这表示你已经进入了该虚拟环境。

步骤 3：安装依赖

在激活状态下执行：

pip install -r requirements.txt

仓库根目录的 requirements.txt 实际内容如下（截至当前仓库版本），可见它既覆盖了主流 LLM 交互与可视化，也包含了 Notebook 运行所需的组件：

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

若希望进入课程开发/贡献模式，还可以按 pyproject.toml 中的dev可选依赖安装代码质量工具（black、isort、mypy、ruff、pytest），它们与本仓库 CI 的检查项保持一致。

安装完成后，即可跳到下文第 6 节配置 API 密钥。

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

本仓库自带一个基于「Universal 运行时镜像」的 development container，可同时支持 Python 3、.NET、Node.js 与 Java 开发。使用该方案的收益是：与 GitHub Codespaces 完全一致的环境，彻底消除依赖漂移（dependency drift）。

步骤 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 将基于 .devcontainer/devcontainer.json 构建镜像——首次构建约需 3 分钟。当终端提示符出现时，你就已经位于容器内部了。

为什么优先考虑它？与 Codespaces 环境完全一致，多人协作、提交 PR 时不会出现「我这能跑你那跑不了」的依赖偏差。

关于这套配置，仓库里的 .devcontainer/devcontainer.json 给出了源码级细节，值得解读：

• 基础镜像为mcr.microsoft.com/devcontainers/universal:2.13，因此容器内同时具备 Python 3 / .NET / Node.js / Java 运行时；
• hostRequirements.cpus = 4，即 Docker 至少为该容器预留 4 个 CPU 核心；
• updateContentCommand会在内容更新时执行python3 -m pip install -r requirements.txt，保证依赖自动就位；
• postCreateCommand调用 .devcontainer/post-create.sh，该脚本额外补装python-dotenv、openai以及ruff black mypy pytest等开发工具；
• customizations.vscode预装了 Python、Pylance、Jupyter、Black Formatter、Ruff、ESLint、Prettier 与 GitHub Copilot 扩展，并开启editor.formatOnSave，其中 Python 默认格式化器为 black、JS/TS 为 Prettier——打开仓库即可获得开箱即用的格式化体验。

4. 方案 C：Miniconda / Conda

Miniconda 是一个轻量级安装器，用于安装 Conda、Python 及若干常用包。Conda 本身是包管理器，擅长创建与切换不同的 Python 虚拟环境，尤其适合安装pip无法提供的二进制/平台相关包（本课程场景中的azure-ai-ml即属此类，可通过 Microsoft 频道获取）。

步骤 0：安装 Miniconda

按官方安装向导完成安装后验证：

conda --version

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

新建一个environment.yml文件。如果是在 Codespaces 中跟随操作，请将其放在.devcontainer目录内，即.devcontainer/environment.yml（本仓库根目录已存在一份由官方维护的真实范例，可直接对照参考 .devcontainer/environment.yml，其中name: dev、Python 锁定为 3.10.0，并包含openai、python-dotenv与 pip 安装的azure-ai-inference）。

步骤 2：填写环境文件

课程文档给出的模板如下：

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

字段含义：

• name：环境名称，自由指定；
• channels：软件源，其中microsoft用于拉取azure-ai-ml等微软 AI 库；
• dependencies：python=<python-version>用你想要的 Python 版本号替换（如3.10）；openai与python-dotenv为课程代码核心依赖；pip:子段声明只能从 PyPI 获取的包，如azure-ai-ml。

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

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

提示：若在 Conda 安装微软 AI 库时遇到错误，可直接执行conda install -c microsoft azure-ai-ml手工补装（详见下文的故障排查表）。

5. 方案 D：经典 Jupyter / Jupyter Lab（浏览器内运行）

适用人群：偏爱传统 Jupyter 交互、或不希望依赖 VS Code 即可运行 Notebook 的开发者。

步骤 1：启动 Jupyter

在终端导航到课程目录后执行：

jupyter notebook

或

jupyterhub

Jupyter 实例启动后，访问 URL 会显示在命令行窗口中。进入页面后即可看到课程大纲，并导航到任意*.ipynb文件，例如课程 08 的完整可运行解答 08-building-search-applications/python/oai-solution.ipynb（该文件在本仓库中真实存在，覆盖向量搜索/嵌入检索全流程）。各章 Notebook 都位于对应课程的python/目录下，例如 04-prompt-engineering-fundamentals/python/。

6. 配置 API 密钥：用.env文件安全托管凭据

无论选择以上哪种环境，构建任何调用 LLM 的应用前都必须妥善保管 API 密钥。切勿把密钥硬编码进代码——提交到公开仓库可能造成安全问题，甚至被恶意使用者刷出巨额费用。

推荐的做法：在本项目根目录创建.env文件（该文件已被 .gitignore 忽略，不会进入版本控制），按以下步骤完成密钥注入。

步骤 1：进入项目根目录

cd path/to/your/project

步骤 2：创建.env文件

Unix 系系统用touch，Windows 用echo：

touch .env

Windows：

echo . > .env

步骤 3：编辑文件并写入凭据

用 VS Code、Notepad++ 等文本编辑器打开.env，将占位符替换为真实值：

GITHUB_TOKEN=your_github_token_here

步骤 4：保存文件

保存更改并关闭编辑器。

步骤 5：安装python-dotenv

python-dotenv用于把.env中的变量加载为 Python 进程的环境变量。若尚未安装：

pip install python-dotenv

该依赖同时已被 requirements.txt（版本锁定python-dotenv==1.2.2）与 pyproject.toml（python-dotenv>=1.0.0）声明，因此方案 A 安装依赖后通常无需重复安装。

步骤 6：在 Python 脚本中加载环境变量

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

这样你就成功创建了.env、写入了凭据并在 Python 应用中加载了它。

仓库中的安全实践佐证

密钥「只进环境变量、绝不入库」在本仓库并非停留在口头约定，而是有工程实现支撑：

• 课程代码广泛使用os.getenv(...)/os.environ[...]读取密钥；仓库还封装了共享工具 shared/python/env_utils.py，其中的get_required_env(var_name, description)会在关键环境变量缺失时抛出带提示的ValueError（如"Missing required environment variable: ... Please set it in your .env file or environment"），validate_env_vars(*var_names)则支持一次性批量校验多个变量——这正是在 Notebook 里「没配密钥先报错、配置完即可跑通」的原因；
• 根目录存在一份 .env.copy 模板（也是 00-course-setup/03-providers.md 官方文档推荐的做法）：把模板复制为.env后再填写，能避免手写变量名出错：

  cp .env.copy .env

关于凭据变量的最新变化：当前英文原版文档 00-course-setup/02-setup-local.md 已更新为 Microsoft Foundry Models 凭据变量（AZURE_INFERENCE_ENDPOINT与AZURE_INFERENCE_CREDENTIAL），因为 GitHub Models（及其GITHUB_TOKEN）预计于 2026 年 7 月底退役；.env.copy中还提供了 OpenAI（OPENAI_API_KEY）、Azure OpenAI（AZURE_OPENAI_*）与 Hugging Face（HUGGING_FACE_API_KEY）等多套占位变量。完整的多 Provider 申请、取值与配置指引见 providers.md。

🔐再次强调：永远不要提交.env——它已被仓库的 .gitignore 忽略，如自行改动务必保持忽略规则不变。

7. 下一步做什么？

环境就绪后，可按需求导航到对应内容：

8. 故障排查

无论选择哪条路径，都可能遇到环境类问题。课程文档整理了一张对症速查表：

若环境长时间卡住（尤其容器构建超过 10 分钟），可优先执行Rebuild Container；Notebook 内核缺失时，在 Notebook 菜单中执行Kernel ▸ Select Kernel ▸ Python 3即可（详见 00-course-setup/README.md 的故障排查小节）。

小结

本文完整覆盖了在本地运行generative-ai-for-beginners课程的四条路径：venv 最快、Dev Container 最一致、Conda 最擅长管理非 pip 依赖、Jupyter 最贴近 Notebook 原生体验。四条路径殊途同归——它们最终都会落到同一套仓库代码与同一个.env凭据机制上。你可以先选最顺手的一条跑通第 1 课，再回到 providers.md 配置你偏好的模型供应商，开启完整的生成式 AI 动手之旅。

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