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 ContainerDocker、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 容器路线时才必需。工具版本 / 说明Python3.10 及以上。本仓库通过.python-version将 Python 版本钉在3.12.10官方下载页为 python.orgGit最新版本macOS 随 Xcode 附带Windows 用 Git for WindowsLinux 用系统包管理器安装VS Code可选但强烈推荐code.visualstudio.comDocker Desktop仅 Option B 需要安装免费安装完成后打开终端依次执行下列命令验证全部就绪python --version git --version docker --version # 仅 Docker 路线需要 code --version # 仅 VS Code 路线需要提示若python命令报python not found请把 Python 加入系统 PATH 并重新打开终端后再试参见文末故障排查表。2. 方案 APython 原生 venv最快上手如果你只写 Python、想用最轻量的方式起步这是推荐路径。它的核心是克隆仓库 → 创建虚拟环境 → 按仓库 requirements.txt 安装依赖。2.1 克隆本仓库git clone https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners cd generative-ai-for-beginners2.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 是全部课程代码的统一依赖清单各依赖与用途对应如下依赖版本约束用途ipywidgets8.1.8为各课 notebook 提供交互式控件进度条、按钮、下拉选择numpy2.4.2数值计算课程中向量/矩阵运算的基础matplotlib3.10.8数据与模型指标可视化pandas3.0.0表格数据处理例如第 8 课搜索结果数据集tqdm4.68.4命令行/循环进度条python-dotenv1.2.2从.env文件加载环境变量见第 6 节openai1.12.0OpenAI 与 Azure OpenAI 官方 SDK要求 1.12 以覆盖新版 chat completions / embeddings APItiktoken最新OpenAI tokenizer用于 token 计数与上下文长度分析第 4 课等会用到azure-ai-inference最新Azure AI 推理 SDK对接 Microsoft Foundry 模型目录第 4、6、8、20、21 课的 Foundry 路径代码使用scikit-learn最新机器学习工具第 8 课搜索应用中的相似度/聚类环节使用安装完成后即可进入第 6 节配置 API 密钥然后开始各课练习。3. 方案 BVS Code Dev ContainerDocker如果你希望获得与 GitHub Codespaces完全一致的运行环境、彻底杜绝在我机器上能跑的依赖漂移问题请选择本方案。本仓库已内置完整的容器化开发配置。3.1 仓库内已有的容器配置相关配置集中在仓库根目录的.devcontainer/文件夹核心文件包括.devcontainer/devcontainer.json容器与 VS Code 集成声明.devcontainer/post-create.sh容器创建后自动执行的初始化脚本.devcontainer/environment.ymlConda 环境定义方案 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/等语言实现。关键配置项含义如下配置项值作用imagemcr.microsoft.com/devcontainers/universal:2.13微软 Universal 开发镜像预装多语言运行时hostRequirements.cpus4提示宿主至少分配 4 核updateContentCommandpython3 -m pip install -r requirements.txt内容同步/首次拉起时安装课程 Python 依赖postCreateCommandbash .devcontainer/post-create.sh容器创建后执行初始化脚本customizations.vscode.extensionsPython、Pylance、Jupyter、Black、Ruff、ESLint、Prettier、Copilot随容器自动安装的 VS Code 扩展其中 .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扩展 IDms-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. 方案 CMiniconda CondaConda 是跨 Python 的包与环境管理器特别适合需要在多个 Python 版本/环境之间切换、或要安装pip无法覆盖的二进制/平台包如azure-ai-ml的场景。Miniconda 是其轻量安装器conda.io 官网下载。4.1 安装并确认按 MiniConda 官方命令行快速安装指南完成安装后验证conda --version4.2 编写environment.yml新建一个环境定义文件environment.yml。如果同时在 Codespaces 中使用应放在.devcontainer/目录下即.devcontainer/environment.yml这样容器构建时会被自动识别。文档给出的通用模板如下其中environment-name、python-version需按需替换name: environment-name channels: - defaults - microsoft dependencies: - pythonpython-version - openai - python-dotenv - pip - pip: - azure-ai-ml字段含义与取值说明字段说明name环境名激活时用如ai4begchannels软件源通道defaults为 Conda 默认源microsoft提供微软 AI 库如azure-ai-mlpython指定 Python 版本如3.10.0dependenciesConda 级依赖pip:子段中的包通过pip通道安装azure-ai-mlAzure Machine Learning SDK通过 pip 段安装仓库实际使用的环境定义可查看 .devcontainer/environment.yml其内容为环境名dev、python3.10.0、openai、python-dotenv、pip并在pip:段安装了azure-ai-inferenceMicrosoft 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或者启动 JupyterHubjupyterhub启动后命令行窗口会显示可访问的 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 分步创建 .envStep 1 – 进入项目根目录cd path/to/your/project # 即 generative-ai-for-beginners 目录Step 2 – 创建.env文件Unix 系macOS/Linuxtouch .envWindowsecho . .envStep 3 – 编辑文件内容用 VS Code、Notepad 等文本编辑器打开.env把占位符替换为你的真实凭据。结合 .env.copy 与各课源码读取逻辑完整变量清单如下按提供商分组# OpenAI ProviderOpenAI 官方 OPENAI_API_KEYadd your OpenAI API key here # Azure OpenAI现已并入 Microsoft Foundry 门户 ai.azure.com 管理 AZURE_OPENAI_API_VERSION2024-10-21 # 默认即可当前稳定 GA API 版本 AZURE_OPENAI_API_KEYadd your Foundry resource key here AZURE_OPENAI_ENDPOINThttps://resource-name.openai.azure.com AZURE_OPENAI_DEPLOYMENTyour chat completion model deployment name, e.g. gpt-4o-mini AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTyour embeddings model deployment name, e.g. text-embedding-3-small # Microsoft Foundry Models多提供商模型目录OpenAI、Meta、Mistral、Cohere、Microsoft 等共用一个 endpoint/key AZURE_INFERENCE_ENDPOINThttps://resource-name.services.ai.azure.com/models AZURE_INFERENCE_CREDENTIALyour Microsoft Foundry Models API key here # Hugging Face HUGGING_FACE_API_KEYadd 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_KEYAzure OpenAI 路径读AZURE_OPENAI_*Foundry 路径读AZURE_INFERENCE_*以 .env.copy 注释为准即可。Step 4 – 保存文件完成。Step 5 – 安装python-dotenv若尚未随 requirements.txt 安装pip install python-dotenvStep 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. 环境就绪后下一步怎么走我想……前往……开始学习第 1 课生成式 AI 与 LLM 入门01-introduction-to-genai/README.md了解课程全貌与学习方法仓库根目录 README.md 与 00-course-setup/README.md配置某个 LLM 提供商OpenAI / Azure OpenAI / Foundry / Hugging Face00-course-setup/03-providers.md使用云端环境Codespaces / Foundry而非本地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 与容器两条路线请二选一venv或container调用返回 401 / 429 错误检查OPENAI_API_KEY等密钥值是否正确、是否超出请求速率限制rate limits使用 Conda 报错用微软源补装 AI 库conda install -c microsoft azure-ai-mlFoundry/GitHub Models 密钥相关报错核对 .env.copy 中的变量命名与当前提供商要求确认旧版GITHUB_TOKEN已被新版AZURE_INFERENCE_ENDPOINT/AZURE_INFERENCE_CREDENTIAL取代2026 年 7 月底后 GitHub Models 已退役按上述四选一路线完成环境搭建、并妥善配置.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 ContainerDocker、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 容器路线时才必需。工具版本 / 说明Python3.10 及以上。本仓库通过.python-version将 Python 版本钉在3.12.10官方下载页为 python.orgGit最新版本macOS 随 Xcode 附带Windows 用 Git for WindowsLinux 用系统包管理器安装VS Code可选但强烈推荐code.visualstudio.comDocker Desktop仅 Option B 需要安装免费安装完成后打开终端依次执行下列命令验证全部就绪python --version git --version docker --version # 仅 Docker 路线需要 code --version # 仅 VS Code 路线需要提示若python命令报python not found请把 Python 加入系统 PATH 并重新打开终端后再试参见文末故障排查表。2. 方案 APython 原生 venv最快上手如果你只写 Python、想用最轻量的方式起步这是推荐路径。它的核心是克隆仓库 → 创建虚拟环境 → 按仓库 requirements.txt 安装依赖。2.1 克隆本仓库git clone https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners cd generative-ai-for-beginners2.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 是全部课程代码的统一依赖清单各依赖与用途对应如下依赖版本约束用途ipywidgets8.1.8为各课 notebook 提供交互式控件进度条、按钮、下拉选择numpy2.4.2数值计算课程中向量/矩阵运算的基础matplotlib3.10.8数据与模型指标可视化pandas3.0.0表格数据处理例如第 8 课搜索结果数据集tqdm4.68.4命令行/循环进度条python-dotenv1.2.2从.env文件加载环境变量见第 6 节openai1.12.0OpenAI 与 Azure OpenAI 官方 SDK要求 1.12 以覆盖新版 chat completions / embeddings APItiktoken最新OpenAI tokenizer用于 token 计数与上下文长度分析第 4 课等会用到azure-ai-inference最新Azure AI 推理 SDK对接 Microsoft Foundry 模型目录第 4、6、8、20、21 课的 Foundry 路径代码使用scikit-learn最新机器学习工具第 8 课搜索应用中的相似度/聚类环节使用安装完成后即可进入第 6 节配置 API 密钥然后开始各课练习。3. 方案 BVS Code Dev ContainerDocker如果你希望获得与 GitHub Codespaces完全一致的运行环境、彻底杜绝在我机器上能跑的依赖漂移问题请选择本方案。本仓库已内置完整的容器化开发配置。3.1 仓库内已有的容器配置相关配置集中在仓库根目录的.devcontainer/文件夹核心文件包括.devcontainer/devcontainer.json容器与 VS Code 集成声明.devcontainer/post-create.sh容器创建后自动执行的初始化脚本.devcontainer/environment.ymlConda 环境定义方案 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/等语言实现。关键配置项含义如下配置项值作用imagemcr.microsoft.com/devcontainers/universal:2.13微软 Universal 开发镜像预装多语言运行时hostRequirements.cpus4提示宿主至少分配 4 核updateContentCommandpython3 -m pip install -r requirements.txt内容同步/首次拉起时安装课程 Python 依赖postCreateCommandbash .devcontainer/post-create.sh容器创建后执行初始化脚本customizations.vscode.extensionsPython、Pylance、Jupyter、Black、Ruff、ESLint、Prettier、Copilot随容器自动安装的 VS Code 扩展其中 .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扩展 IDms-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. 方案 CMiniconda CondaConda 是跨 Python 的包与环境管理器特别适合需要在多个 Python 版本/环境之间切换、或要安装pip无法覆盖的二进制/平台包如azure-ai-ml的场景。Miniconda 是其轻量安装器conda.io 官网下载。4.1 安装并确认按 MiniConda 官方命令行快速安装指南完成安装后验证conda --version4.2 编写environment.yml新建一个环境定义文件environment.yml。如果同时在 Codespaces 中使用应放在.devcontainer/目录下即.devcontainer/environment.yml这样容器构建时会被自动识别。文档给出的通用模板如下其中environment-name、python-version需按需替换name: environment-name channels: - defaults - microsoft dependencies: - pythonpython-version - openai - python-dotenv - pip - pip: - azure-ai-ml字段含义与取值说明字段说明name环境名激活时用如ai4begchannels软件源通道defaults为 Conda 默认源microsoft提供微软 AI 库如azure-ai-mlpython指定 Python 版本如3.10.0dependenciesConda 级依赖pip:子段中的包通过pip通道安装azure-ai-mlAzure Machine Learning SDK通过 pip 段安装仓库实际使用的环境定义可查看 .devcontainer/environment.yml其内容为环境名dev、python3.10.0、openai、python-dotenv、pip并在pip:段安装了azure-ai-inferenceMicrosoft 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或者启动 JupyterHubjupyterhub启动后命令行窗口会显示可访问的 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 分步创建 .envStep 1 – 进入项目根目录cd path/to/your/project # 即 generative-ai-for-beginners 目录Step 2 – 创建.env文件Unix 系macOS/Linuxtouch .envWindowsecho . .envStep 3 – 编辑文件内容用 VS Code、Notepad 等文本编辑器打开.env把占位符替换为你的真实凭据。结合 .env.copy 与各课源码读取逻辑完整变量清单如下按提供商分组# OpenAI ProviderOpenAI 官方 OPENAI_API_KEYadd your OpenAI API key here # Azure OpenAI现已并入 Microsoft Foundry 门户 ai.azure.com 管理 AZURE_OPENAI_API_VERSION2024-10-21 # 默认即可当前稳定 GA API 版本 AZURE_OPENAI_API_KEYadd your Foundry resource key here AZURE_OPENAI_ENDPOINThttps://resource-name.openai.azure.com AZURE_OPENAI_DEPLOYMENTyour chat completion model deployment name, e.g. gpt-4o-mini AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTyour embeddings model deployment name, e.g. text-embedding-3-small # Microsoft Foundry Models多提供商模型目录OpenAI、Meta、Mistral、Cohere、Microsoft 等共用一个 endpoint/key AZURE_INFERENCE_ENDPOINThttps://resource-name.services.ai.azure.com/models AZURE_INFERENCE_CREDENTIALyour Microsoft Foundry Models API key here # Hugging Face HUGGING_FACE_API_KEYadd 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_KEYAzure OpenAI 路径读AZURE_OPENAI_*Foundry 路径读AZURE_INFERENCE_*以 .env.copy 注释为准即可。Step 4 – 保存文件完成。Step 5 – 安装python-dotenv若尚未随 requirements.txt 安装pip install python-dotenvStep 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. 环境就绪后下一步怎么走我想……前往……开始学习第 1 课生成式 AI 与 LLM 入门01-introduction-to-genai/README.md了解课程全貌与学习方法仓库根目录 README.md 与 00-course-setup/README.md配置某个 LLM 提供商OpenAI / Azure OpenAI / Foundry / Hugging Face00-course-setup/03-providers.md使用云端环境Codespaces / Foundry而非本地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 与容器两条路线请二选一venv或container调用返回 401 / 429 错误检查OPENAI_API_KEY等密钥值是否正确、是否超出请求速率限制rate limits使用 Conda 报错用微软源补装 AI 库conda install -c microsoft azure-ai-mlFoundry/GitHub Models 密钥相关报错核对 .env.copy 中的变量命名与当前提供商要求确认旧版GITHUB_TOKEN已被新版AZURE_INFERENCE_ENDPOINT/AZURE_INFERENCE_CREDENTIAL取代2026 年 7 月底后 GitHub Models 已退役按上述四选一路线完成环境搭建、并妥善配置.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考