企业官网建设流程全解析

从零搭建本地开发环境：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

本文是《Generative AI for Beginners》课程本地环境配置的完整实战指南。如果你更希望在自己的笔记本上运行全部课程代码（而不是使用云端的 GitHub Codespaces），这篇指南将带你走完从克隆仓库、创建 Python 虚拟环境、安装依赖，到安全配置 LLM Provider API 密钥的全过程。读完本文，你将能够独立搭建四种可选环境（原生 Python + venv、VS Code Dev Container、Miniconda、经典 Jupyter），并掌握基于.env文件的安全密钥管理方法，为后续 21 节课的实验做好准备。

1. 环境搭建概览与前置条件

本课程仓库（当前目录即generative-ai-for-beginners）的核心实验载体是大量 Python 脚本与 Jupyter Notebook（分布在 01-introduction-to-genai 至 21-meta 各章节中），因此本地环境需要一套能运行 Python 3.10+、加载依赖并能安全注入 API 密钥的开发环境。

课程提供了两条主线、四种具体路径，任选其一即可，它们最终通向完全相同的课程内容：

• 方案 A：原生 Python + 虚拟环境（venv）—— 最快上手，零额外依赖；
• 方案 B：VS Code Dev Container（Docker）—— 与云端 Codespaces 完全一致的隔离环境，杜绝依赖漂移；
• 方案 C：Miniconda—— 适合需要管理多个 Python 版本与 conda 生态包的场景；
• 方案 D：经典 Jupyter / Jupyter Lab—— 偏好浏览器内 Notebook 界面、不想使用 VS Code 的开发者。

在开始之前，请确认以下工具的版本符合要求：

💡提示：打开终端依次执行python --version、git --version、docker --version、code --version，可以一次性验证这些工具是否都已就绪。

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

步骤 1：克隆本仓库

git clone https://github.com/<your-github>/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)开头，说明你已经进入虚拟环境，后续pip安装的包都会隔离在这个环境内，不会污染系统 Python。

步骤 3：安装依赖

pip install -r requirements.txt

根目录的 requirements.txt 已锁定课程所需的核心依赖，包括openai>=1.12.0（OpenAI / 兼容 SDK）、python-dotenv==1.2.2（加载.env文件）、azure-ai-inference（Azure AI Inference / Foundry Models 客户端）、tiktoken（分词工具）以及numpy、pandas、matplotlib、scikit-learn、tqdm、ipywidgets等数据与可视化组件。安装完成后即可跳到本文第 6 节配置 API 密钥。

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

本仓库内置了开发容器（Development Container） 配置，其运行时（Universal runtime）同时支持 Python3、.NET、Node.js 和 Java 开发。相关配置定义在仓库根目录.devcontainer/文件夹下的devcontainer.json文件中。

为什么选这个方案？容器环境与云端 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"。首次构建镜像大约需要 3 分钟。当终端提示符出现时，说明你已经处于容器内部，所有依赖（Python 3、Node.js、.NET、Java 运行时）都已预装完毕，可以直接开始实验。

4. 方案 C：Miniconda

Miniconda 是一个轻量级安装器，用于安装 Conda 包管理器、Python 及少量必要包。Conda 本身是包管理器，可以方便地创建和切换不同的 Python 虚拟环境与包组合，还能安装pip无法提供的非 Python 依赖。

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

注意channels中加入了microsoft频道，这是安装微软 Azure AI 相关库（如azure-ai-ml）的前提；pip小节用于安装仅通过 PyPI 分发的包。

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

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

提示：--file参数指向的环境文件路径可根据你的实际情况调整；若遇到环境创建问题，可参考 Conda 官方环境管理文档。

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（第 8 课《构建搜索应用》的 OpenAI 方案答案 Notebook）。

提示：如果提示找不到jupyter命令，请先确认你已在对应虚拟环境中安装了ipywidgets等 Notebook 依赖（可执行pip install -r requirements.txt一次性补齐）。

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

无论选择哪种环境，构建生成式 AI 应用时都必须妥善保管 API 密钥。绝不建议把密钥硬编码进代码——一旦提交到公开仓库，可能引发安全泄露，甚至被恶意调用产生额外费用。下面是推荐的安全做法。

步骤 1：进入项目目录

cd path/to/your/project

步骤 2：创建.env文件

Unix 系系统：

touch .env

Windows：

echo . > .env

步骤 3：填入密钥变量

用 VS Code、Notepad++ 或任意编辑器打开.env并写入密钥。注意：本课程原印尼语文档中的示例使用GITHUB_TOKEN（对应已退役的 GitHub Models），当前仓库已全面迁移到Microsoft Foundry Models方案。以仓库根目录的 .env.copy 为最新权威模板，其关键变量如下：

# OpenAI Provider OPENAI_API_KEY='<add your OpenAI API key here>' ## Azure OpenAI in Microsoft Foundry AZURE_OPENAI_API_VERSION='2024-10-21' # 默认已设置（当前稳定 GA 版本） 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（多厂商模型目录，一个端点 + 一个密钥） 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，然后逐一替换=右侧的占位符。各变量的含义如下：

各 Provider 的详细注册、获取密钥与部署模型的完整指引见 00-course-setup/03-providers.md；无需云订阅、完全离线的 Foundry Local / Ollama 方案可参考 19-slm/README.md 中的实操示例。

步骤 4：保存文件并安装 python-dotenv

pip install python-dotenv

步骤 5：在 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)

完成以上步骤后，密钥即安全地注入到你的 Python 应用中。

🔐绝不要提交.env文件——它已被列入仓库的.gitignore，仓库中的 .env.copy 才是用于共享的模板。这一安全实践在仓库源码中也有对应体现：共享工具模块 shared/python/env_utils.py 提供了get_required_env()与validate_env_vars()等函数，在读取缺失的必需环境变量时会抛出带明确提示的ValueError（如Missing required environment variable: OPENAI_API_KEY. Please set it in your .env file or environment.），帮助你在运行任何课程脚本前快速定位密钥配置问题；get_env_with_default()则用于为可选参数（如默认模型名）提供回退值。

7. 下一步：进入课程学习

环境与密钥就绪后，你可以按需选择：

8. 常见问题排查

至此，你已经掌握了本课程全部四种本地环境搭建路径与一套安全可靠的密钥管理流程。选择最适合你习惯的方案，即可无缝开始 21 节课的生成式 AI 实战之旅。

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