从零搭建本地开发环境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—— 最快上手零额外依赖方案 BVS Code Dev ContainerDocker—— 与云端 Codespaces 完全一致的隔离环境杜绝依赖漂移方案 CMiniconda—— 适合需要管理多个 Python 版本与 conda 生态包的场景方案 D经典 Jupyter / Jupyter Lab—— 偏好浏览器内 Notebook 界面、不想使用 VS Code 的开发者。在开始之前请确认以下工具的版本符合要求工具版本 / 说明Python3.10 及以上可从 python.org 官方渠道获取Git最新版macOS 随 Xcode 附带、Windows 使用 Git for Windows、Linux 使用包管理器安装VS Code可选但推荐code.visualstudio.com 官方渠道Docker Desktop仅方案 B 需要免费安装提示打开终端依次执行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 已锁定课程所需的核心依赖包括openai1.12.0OpenAI / 兼容 SDK、python-dotenv1.2.2加载.env文件、azure-ai-inferenceAzure AI Inference / Foundry Models 客户端、tiktoken分词工具以及numpy、pandas、matplotlib、scikit-learn、tqdm、ipywidgets等数据与可视化组件。安装完成后即可跳到本文第 6 节配置 API 密钥。3. 方案 BVS Code Dev ContainerDocker本仓库内置了开发容器Development Container 配置其运行时Universal runtime同时支持 Python3、.NET、Node.js 和 Java 开发。相关配置定义在仓库根目录.devcontainer/文件夹下的devcontainer.json文件中。为什么选这个方案容器环境与云端 Codespaces 完全一致本地与云端之间不存在依赖漂移dependency drift团队成员都能在相同的环境中复现实验结果。步骤 0安装额外工具安装 Docker Desktop并确认docker --version能正常输出版本号在 VS Code 中安装Remote – Containers扩展扩展 IDms-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. 方案 CMinicondaMiniconda 是一个轻量级安装器用于安装 Conda 包管理器、Python 及少量必要包。Conda 本身是包管理器可以方便地创建和切换不同的 Python 虚拟环境与包组合还能安装pip无法提供的非 Python 依赖。步骤 0安装 Miniconda按照官方安装指南完成安装后验证conda --version步骤 1创建环境文件新建一个环境文件environment.yml。如果你正在跟随 Codespaces 教程操作请将该文件放在.devcontainer目录下即.devcontainer/environment.yml。步骤 2填充环境文件将以下内容写入你的environment.ymlname: environment-name channels: - defaults - microsoft dependencies: - pythonpython-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 .envWindowsecho . .env步骤 3填入密钥变量用 VS Code、Notepad 或任意编辑器打开.env并写入密钥。注意本课程原印尼语文档中的示例使用GITHUB_TOKEN对应已退役的 GitHub Models当前仓库已全面迁移到Microsoft Foundry Models方案。以仓库根目录的 .env.copy 为最新权威模板其关键变量如下# OpenAI Provider OPENAI_API_KEYadd your OpenAI API key here ## Azure OpenAI in Microsoft Foundry AZURE_OPENAI_API_VERSION2024-10-21 # 默认已设置当前稳定 GA 版本 AZURE_OPENAI_API_KEYadd your Foundry resource key here AZURE_OPENAI_ENDPOINTadd your Foundry resource endpoint here, e.g. https://resource-name.openai.azure.com AZURE_OPENAI_DEPLOYMENTadd your chat completion model deployment name here, e.g. gpt-4o-mini AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTadd your embeddings model deployment name here, e.g. text-embedding-3-small ## Microsoft Foundry Models多厂商模型目录一个端点 一个密钥 AZURE_INFERENCE_ENDPOINTadd your Microsoft Foundry project endpoint here AZURE_INFERENCE_CREDENTIALadd your Microsoft Foundry Models API key here ## Hugging Face HUGGING_FACE_API_KEYadd your HuggingFace API or token here更便捷的做法是直接复制模板cp .env.copy .env然后逐一替换右侧的占位符。各变量的含义如下变量说明OPENAI_API_KEY非 Azure OpenAI 端点的服务授权密钥AZURE_OPENAI_API_KEYAzure OpenAI / Foundry 资源的授权密钥AZURE_OPENAI_ENDPOINTAzure OpenAI 资源的已部署端点AZURE_OPENAI_DEPLOYMENT文本生成模型的部署名推荐gpt-4o-miniAZURE_OPENAI_EMBEDDINGS_DEPLOYMENT文本嵌入模型的部署名推荐text-embedding-3-smallAZURE_INFERENCE_ENDPOINTMicrosoft Foundry 项目端点用于 Foundry ModelsAZURE_INFERENCE_CREDENTIALMicrosoft Foundry 项目 API 密钥HUGGING_FACE_API_KEYHugging Face 用户访问令牌Access Token各 Provider 的详细注册、获取密钥与部署模型的完整指引见 00-course-setup/03-providers.md无需云订阅、完全离线的 Foundry Local / Ollama 方案可参考 19-slm/README.md 中的实操示例。步骤 4保存文件并安装 python-dotenvpip 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. 下一步进入课程学习环境与密钥就绪后你可以按需选择我想…前往…开始第 1 课01-introduction-to-genai/README.md配置 LLM Provider00-course-setup/03-providers.md使用云端零安装方案00-course-setup/01-setup-cloud.md8. 常见问题排查症状解决方案python not found将 Python 添加到 PATH或安装后重新打开终端pip无法构建 wheelsWindows执行pip install --upgrade pip setuptools wheel后重试ModuleNotFoundError: dotenv运行pip install -r requirements.txt说明环境依赖未安装完整Docker 构建失败报No space leftDocker Desktop ▸Settings▸Resources调大磁盘容量VS Code 反复提示重新打开你可能同时启用了两种方案请二选一venv或containerOpenAI 401 / 429 错误检查OPENAI_API_KEY取值是否正确、是否超出请求速率限制使用 Conda 时出错使用conda install -c microsoft azure-ai-ml安装微软 AI 库至此你已经掌握了本课程全部四种本地环境搭建路径与一套安全可靠的密钥管理流程。选择最适合你习惯的方案即可无缝开始 21 节课的生成式 AI 实战之旅。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/11 13:35:34 · 阅读 1.2k 从零搭建本地开发环境：generative-ai-for-beginners 的四种方案与 API 密钥安全配置指南
从零搭建本地开发环境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—— 最快上手零额外依赖方案 BVS Code Dev ContainerDocker—— 与云端 Codespaces 完全一致的隔离环境杜绝依赖漂移方案 CMiniconda—— 适合需要管理多个 Python 版本与 conda 生态包的场景方案 D经典 Jupyter / Jupyter Lab—— 偏好浏览器内 Notebook 界面、不想使用 VS Code 的开发者。在开始之前请确认以下工具的版本符合要求工具版本 / 说明Python3.10 及以上可从 python.org 官方渠道获取Git最新版macOS 随 Xcode 附带、Windows 使用 Git for Windows、Linux 使用包管理器安装VS Code可选但推荐code.visualstudio.com 官方渠道Docker Desktop仅方案 B 需要免费安装提示打开终端依次执行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 已锁定课程所需的核心依赖包括openai1.12.0OpenAI / 兼容 SDK、python-dotenv1.2.2加载.env文件、azure-ai-inferenceAzure AI Inference / Foundry Models 客户端、tiktoken分词工具以及numpy、pandas、matplotlib、scikit-learn、tqdm、ipywidgets等数据与可视化组件。安装完成后即可跳到本文第 6 节配置 API 密钥。3. 方案 BVS Code Dev ContainerDocker本仓库内置了开发容器Development Container 配置其运行时Universal runtime同时支持 Python3、.NET、Node.js 和 Java 开发。相关配置定义在仓库根目录.devcontainer/文件夹下的devcontainer.json文件中。为什么选这个方案容器环境与云端 Codespaces 完全一致本地与云端之间不存在依赖漂移dependency drift团队成员都能在相同的环境中复现实验结果。步骤 0安装额外工具安装 Docker Desktop并确认docker --version能正常输出版本号在 VS Code 中安装Remote – Containers扩展扩展 IDms-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. 方案 CMinicondaMiniconda 是一个轻量级安装器用于安装 Conda 包管理器、Python 及少量必要包。Conda 本身是包管理器可以方便地创建和切换不同的 Python 虚拟环境与包组合还能安装pip无法提供的非 Python 依赖。步骤 0安装 Miniconda按照官方安装指南完成安装后验证conda --version步骤 1创建环境文件新建一个环境文件environment.yml。如果你正在跟随 Codespaces 教程操作请将该文件放在.devcontainer目录下即.devcontainer/environment.yml。步骤 2填充环境文件将以下内容写入你的environment.ymlname: environment-name channels: - defaults - microsoft dependencies: - pythonpython-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 .envWindowsecho . .env步骤 3填入密钥变量用 VS Code、Notepad 或任意编辑器打开.env并写入密钥。注意本课程原印尼语文档中的示例使用GITHUB_TOKEN对应已退役的 GitHub Models当前仓库已全面迁移到Microsoft Foundry Models方案。以仓库根目录的 .env.copy 为最新权威模板其关键变量如下# OpenAI Provider OPENAI_API_KEYadd your OpenAI API key here ## Azure OpenAI in Microsoft Foundry AZURE_OPENAI_API_VERSION2024-10-21 # 默认已设置当前稳定 GA 版本 AZURE_OPENAI_API_KEYadd your Foundry resource key here AZURE_OPENAI_ENDPOINTadd your Foundry resource endpoint here, e.g. https://resource-name.openai.azure.com AZURE_OPENAI_DEPLOYMENTadd your chat completion model deployment name here, e.g. gpt-4o-mini AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTadd your embeddings model deployment name here, e.g. text-embedding-3-small ## Microsoft Foundry Models多厂商模型目录一个端点 一个密钥 AZURE_INFERENCE_ENDPOINTadd your Microsoft Foundry project endpoint here AZURE_INFERENCE_CREDENTIALadd your Microsoft Foundry Models API key here ## Hugging Face HUGGING_FACE_API_KEYadd your HuggingFace API or token here更便捷的做法是直接复制模板cp .env.copy .env然后逐一替换右侧的占位符。各变量的含义如下变量说明OPENAI_API_KEY非 Azure OpenAI 端点的服务授权密钥AZURE_OPENAI_API_KEYAzure OpenAI / Foundry 资源的授权密钥AZURE_OPENAI_ENDPOINTAzure OpenAI 资源的已部署端点AZURE_OPENAI_DEPLOYMENT文本生成模型的部署名推荐gpt-4o-miniAZURE_OPENAI_EMBEDDINGS_DEPLOYMENT文本嵌入模型的部署名推荐text-embedding-3-smallAZURE_INFERENCE_ENDPOINTMicrosoft Foundry 项目端点用于 Foundry ModelsAZURE_INFERENCE_CREDENTIALMicrosoft Foundry 项目 API 密钥HUGGING_FACE_API_KEYHugging Face 用户访问令牌Access Token各 Provider 的详细注册、获取密钥与部署模型的完整指引见 00-course-setup/03-providers.md无需云订阅、完全离线的 Foundry Local / Ollama 方案可参考 19-slm/README.md 中的实操示例。步骤 4保存文件并安装 python-dotenvpip 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. 下一步进入课程学习环境与密钥就绪后你可以按需选择我想…前往…开始第 1 课01-introduction-to-genai/README.md配置 LLM Provider00-course-setup/03-providers.md使用云端零安装方案00-course-setup/01-setup-cloud.md8. 常见问题排查症状解决方案python not found将 Python 添加到 PATH或安装后重新打开终端pip无法构建 wheelsWindows执行pip install --upgrade pip setuptools wheel后重试ModuleNotFoundError: dotenv运行pip install -r requirements.txt说明环境依赖未安装完整Docker 构建失败报No space leftDocker Desktop ▸Settings▸Resources调大磁盘容量VS Code 反复提示重新打开你可能同时启用了两种方案请二选一venv或containerOpenAI 401 / 429 错误检查OPENAI_API_KEY取值是否正确、是否超出请求速率限制使用 Conda 时出错使用conda install -c microsoft azure-ai-ml安装微软 AI 库至此你已经掌握了本课程全部四种本地环境搭建路径与一套安全可靠的密钥管理流程。选择最适合你习惯的方案即可无缝开始 21 节课的生成式 AI 实战之旅。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考