企业官网建设流程全解析

generative-ai-for-beginners 本地环境搭建全指南：四种安装路径与 API 密钥安全配置实战

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

本文以 translations/hu/00-course-setup/02-setup-local.md（本地搭建指南的匈牙利语翻译版）及英文原版 00-course-setup/02-setup-local.md 为主体，结合本仓库的依赖清单、环境变量工具源码与 Provider 配置文档展开。适合希望在自己笔记本上完整运行本课程 21 节课、练习各课时 notebook 与作业的开发者。读完后，你将掌握四种本地运行方式（原生 Python + venv、VS Code Dev Container、Miniconda、经典 Jupyter），能够正确安装课程依赖、配置.env环境变量文件，并通过仓库提供的工具函数安全读取 API 密钥。

1. 前置条件

在开始之前，请先确认本机具备以下工具。官方指南建议使用Python 3.10 及以上版本，其余工具按需准备：

安装完成后，在终端里用以下命令快速验证环境是否就绪：

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

💡提示：docker --version仅在安装 Docker Desktop 后可用；若你只走选项 A（原生 Python），可跳过 Docker 相关检查。

2. 选项 A – 原生 Python + venv（最快路径）

如果希望以最小依赖快速跑通课程代码，这是首选方案。

步骤 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)前缀，表示你已经进入虚拟环境。该目录已被仓库的 .gitignore（第 124 行）忽略，不会被提交。

步骤 3：安装依赖

pip install -r requirements.txt

仓库根目录的 requirements.txt 内容如下，它锁定了课程 notebook 运行所需的全部 Python 包：

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

其中几个关键依赖的用途：

• python-dotenv：负责从.env文件加载环境变量，第 4 节会详细使用；
• openai/azure-ai-inference：课程作业调用的模型服务 SDK（OpenAI 端点与 Microsoft Foundry 推理端点）；
• ipywidgets/matplotlib/pandas/numpy/scikit-learn：支撑各节课 notebook 中的数据可视化与机器学习示例；
• tiktoken：token 计数工具，在提示工程等课时中用于理解 token 消耗。

依赖装好后，直接跳到第 4 节配置 API 密钥即可开始学习。

3. 选项 B – VS Code Dev Container（Docker）

本仓库专门配置了开发容器（Dev Container），提供一个同时支持Python 3、.NET、Node.js 和 Java的统一运行时环境。相关配置定义在仓库根目录的.devcontainer/文件夹中（其中devcontainer.json是核心配置文件）。

为什么选这种方式？容器环境与 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 会构建镜像（首次构建约需 3 分钟）。当终端提示符出现时，你就已经处于容器内部了，可以直接使用与 Codespaces 相同的环境运行课程代码。

注意：Dev Container 与本地 venv 是两套相互独立的方案，建议只启用其中一种，避免 VS Code 反复提示“重新打开”（该问题的具体解法见第 7 节排错表）。

4. 选项 C – Miniconda

Miniconda 是 Conda 的精简安装器，用于安装 Conda、Python 及少量常用包。Conda 本身是一个包管理器，可以方便地创建、切换不同的 Python虚拟环境，并且能安装一些pip源里没有的包（例如 Microsoft 的 AI 库）。

步骤 0：安装 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

参数说明：

• name：环境名称，例如ai4beg；
• channels：包源渠道，microsoft渠道用于获取 Microsoft 的 AI 库；
• python=<python-version>：Python 版本号，例如3表示使用最新主版本；
• pip:段：通过 pip 额外安装azure-ai-ml等不在 conda 默认渠道中的包。

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

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

如果中途报错，可以参考 Conda 官方环境管理文档排查。另外，若使用 conda 时遇到 Microsoft AI 库缺失，可在终端手动执行：

conda install -c microsoft azure-ai-ml

这与环境文件中的microsoftchannel +azure-ai-ml依赖是等效的兜底方案。

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

适合人群：喜欢经典 Jupyter 界面，或不想依赖 VS Code 运行 notebook 的开发者。

步骤 1：启动 Jupyter

在终端/命令行中进入课程目录，执行：

jupyter notebook

或

jupyterhub

启动后，终端窗口会打印访问 URL。打开该 URL，即可看到课程目录大纲，并导航到任意*.ipynb文件。例如：

• 08-building-search-applications/python/oai-solution.ipynb
• 04-prompt-engineering-fundamentals/python/oai-assignment.ipynb

本课程几乎所有实战课时都在各章节的python/、typescript/、javascript/或dotnet/目录下提供了 notebook 与脚本，例如 08-building-search-applications/python 中的oai-solution.ipynb、aoai-solution.ipynb。

6. 配置 API 密钥（.env文件）

无论选择哪种运行方式，构建生成式 AI 应用时都必须妥善保管 API 密钥。官方指南明确建议：不要把 API 密钥直接写进代码——一旦提交到公开仓库，可能引发安全问题，甚至被恶意使用者消耗产生意外费用。

版本说明：GitHub Models（及其GITHUB_TOKEN变量）已于 2026 年 7 月底退役，本指南使用Microsoft Foundry Models替代；如需完全离线运行，可参考 Foundry Local。

下面是创建.env文件并加载凭证的完整步骤：

步骤 1：进入项目根目录

cd path/to/your/project

步骤 2：创建.env文件

Unix 系系统：

touch .env

Windows：

echo . > .env

步骤 3：编辑.env文件

用文本编辑器（VS Code、Notepad++ 等）打开，填入实际凭证，替换占位符：

AZURE_INFERENCE_ENDPOINT=your_foundry_endpoint_here AZURE_INFERENCE_CREDENTIAL=your_foundry_api_key_here

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

步骤 5：安装python-dotenv

pip install python-dotenv

（在选项 A 中该包已包含在requirements.txt内。）

步骤 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)

6.1 仓库推荐的更稳妥做法：.env.copy模板

除了手动创建，仓库还提供了现成的环境变量模板。在根目录找到.env.copy文件，它包含了课程用到的全部 Provider 变量，核心内容如下：

# OpenAI Provider OPENAI_API_KEY='<add your OpenAI API key here>' ## Azure OpenAI in Microsoft Foundry AZURE_OPENAI_API_VERSION='2024-10-21' # 已设置默认值（当前稳定 GA API 版本） AZURE_OPENAI_API_KEY='<add your Foundry resource key here>' AZURE_OPENAI_ENDPOINT='<add your Foundry resource endpoint here, e.g. https://<resource-name>.openai.azure.com>' AZURE_OPENAI_DEPLOYMENT='<add your chat completion model deployment name here, e.g. gpt-4o-mini>' AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='<add your embeddings model deployment name here, e.g. text-embedding-3-small>' ## Microsoft Foundry Models (multi-provider model catalog, replaces GitHub Models, which retires end of July 2026) AZURE_INFERENCE_ENDPOINT='<add your Microsoft Foundry project endpoint here>' AZURE_INFERENCE_CREDENTIAL='<add your Microsoft Foundry Models API key here>' ## Hugging Face HUGGING_FACE_API_KEY='<add your HuggingFace API or token here>'

复制模板并填充值：

cp .env.copy .env

该文件已被 .gitignore 忽略（第 123 行），可放心存放密钥。

6.2 各 Provider 变量速查表

来自 00-course-setup/03-providers.md 的完整变量说明：

各课程作业会通过文件名前缀标明所需的 Provider：aoai需要 Azure OpenAI 端点与密钥、oai需要 OpenAI 端点与密钥、hf需要 Hugging Face 令牌、githubmodels需要 Microsoft Foundry Models 端点与密钥（GitHub Models 已于 2026 年 7 月底退役）。你可以只配置其中一个、全部配置，或一个都不配——相关作业在缺少凭证时会直接报错，不影响其他章节学习。

6.3 源码中的环境变量实践：从工具函数到测试

仓库不只是把密钥加载停在load_dotenv()这一步，还在shared/python下封装了一组规范的环境变量读取工具 shared/python/env_utils.py，供课程脚本复用：

• get_required_env(var_name, description)：读取必需变量，未设置或为空时抛出带提示信息的ValueError（例如Missing required environment variable: OPENAI_API_KEY. Please set it in your .env file or environment.）；
• validate_env_vars(*var_names)：批量校验多个变量，一次性报告所有缺失项；
• get_env_with_default(var_name, default)：读取可带默认值的变量。

配套的单元测试 tests/test_env_utils.py 覆盖了这些函数的典型场景，例如test_get_required_env_missing_raises验证缺失变量会抛错、test_validate_env_vars_reports_all_missing验证批量缺失时错误信息会列出全部变量名、test_get_env_with_default_uses_default验证默认值回退逻辑。这组测试既是对工具函数的回归保障，也示范了如何在课程代码中安全地消费.env变量。

7. 排错指南

本地搭建过程中遇到问题，可对照下表排查：

8. 下一步行动

环境与密钥就绪后，按目标选择下一步：

9. 安全提醒

• 🔐永远不要把.env文件提交到仓库——它已被根目录 .gitignore（第 123 行.env）默认忽略；
• 使用 GitHub Codespaces 时，可选用 Codespaces Secrets 存储密钥而无需本地.env，但该方式仅对 Codespaces 生效，使用 Docker Desktop 仍需创建本地.env；
• 各 Provider 的完整申请与配置指引请查阅 00-course-setup/03-providers.md，其中包含 OpenAI、Azure OpenAI、Microsoft Foundry、Hugging Face 以及离线方案（Foundry Local / Ollama）的详细说明。

至此，你已经完成了本地开发环境搭建、依赖安装与密钥安全配置，可以正式开启 21 节课的生成式 AI 学习与实践之旅了。

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