generative-ai-for-beginners 本地开发环境搭建从原生 venv、Dev Container 到 Conda 与 Jupyter 的四种路径及 API Key 配置【免费下载链接】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/Git/Docker 前置工具核验、原生 Python 虚拟环境、VS Code Dev ContainerDocker、Miniconda 与经典 Jupyter 四种本地运行方案以及.envAPI Key 的安全配置流程。读完并照做之后你可以在这四种环境中的任意一种里跑通课程全部 21 课的 Python 脚本与*.ipynb笔记本并正确接入模型 API 凭据。1. 前置条件与工具核验文档给出的前置要求如下表所有方案A/B/C/D都以这些工具为基础工具版本 / 说明Python3.10 及以上可从 Python 官网获取安装包Git最新版Xcode / Git for Windows / Linux 包管理器通常自带VS Code可选但推荐Docker Desktop仅选项 B 需要免费安装在终端中可用以下命令一次性核验python --version git --version docker --version code --version结合仓库实际配置可以进一步确认版本约束pyproject.toml 中声明requires-python 3.10且 Python classifiers 覆盖 3.10 / 3.11 / 3.12与文档 3.10 的要求一致仓库根目录的 .python-version 文件固定为3.12.10说明课程维护者实际使用的 Python 解释器版本.devcontainer/environment.yml 中则把 Conda 环境固定在python3.10.0。因此Python 3.10–3.12 是文档与仓库配置共同验证过的安全区间。2. 选项 A – 原生 Python 虚拟环境最快路径步骤 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)前缀——这是你已进入虚拟环境的标志。步骤 3安装依赖pip install -r requirements.txt这一步是本课程的单一事实来源。查看仓库根目录的 requirements.txt当前固定/声明的依赖为依赖版本约束在课程中的角色结合源码结构ipywidgets8.1.8Jupyter 笔记本中的交互式控件课程*.ipynb作业大量使用numpy2.4.2数值计算基础库matplotlib3.10.8数据/嵌入结果可视化pandas3.0.0表格数据处理如搜索应用课中的转录文本索引tqdm4.68.4批处理脚本的进度条如08-building-search-applications/scripts/中的数据处理脚本python-dotenv1.2.2从.env文件加载 API 凭据见第 6 节openai1.12.0OpenAI 兼容 API 客户端课程各课 Python 示例的主力 SDKtiktoken未锁版本Token 计数与分词示例azure-ai-inference未锁版本接入 Microsoft Foundry / Azure 推理服务的客户端scikit-learn未锁版本向量/嵌入相关课程的机器学习基础库可以看到requirements.txt与 pyproject.toml 的dependenciesopenai1.0.0、python-dotenv1.0.0、requests2.31.0、azure-ai-inference1.0.0b1、tiktoken0.5.0在核心 SDK 上保持一致pip install -r requirements.txt即把课程脚本、笔记本运行所需的全部第三方库一次性装齐之后即可跳转到添加 API Keys一节。3. 选项 B – VS Code Dev ContainerDocker 容器化开发本课程仓库在根目录提供了.devcontainer/开发容器配置仓库使用了一个通用运行时Universal runtime的 Dev Container 镜像可同时支持 Python 3、.NET、Node.js 和 Java 开发。相比选项 A其最大价值在于与 GitHub Codespaces 使用同一套环境杜绝依赖漂移dependency drift——你本地容器里的行为与云端 Codespaces 完全一致。仓库中该方案的全部实现证据集中在.devcontainer/目录逐文件拆解如下3.1devcontainer.json容器如何被构建.devcontainer/devcontainer.json 的关键字段{ name: Generative AI For Beginners, // 微软 MCR 的 Universal Dev Container 镜像2.13 版 image: mcr.microsoft.com/devcontainers/universal:2.13, // 宿主机至少需要 4 个 CPU 才能满足运行要求 hostRequirements: { cpus: 4 }, waitFor: onCreateCommand, // 容器内容更新时自动重装 Python 依赖 updateContentCommand: python3 -m pip install -r requirements.txt, // 容器首次创建后执行的初始化脚本 postCreateCommand: bash .devcontainer/post-create.sh, customizations: { vscode: { extensions: [ /* 7 个扩展 */ ], ... } } }从源码结构看有两个关键机制值得注意updateContentCommand每次向容器同步代码变更时都会重新执行pip install -r requirements.txt意味着你在容器里克隆/拉取新代码后依赖会自动对齐无需手动执行第 2 节选项 A 的步骤 3postCreateCommand容器创建完成后调用 .devcontainer/post-create.sh该脚本额外安装python-dotenv、openai以及ruff black mypy pytest四件套——脚本注释明确说明这套开发工具链与.github/workflows/code-quality.yml中 CI 执行的检查保持一致便于贡献者在提 PR 前本地复现质量门禁。customizations.vscode.extensions还预装了ms-python.python、ms-python.vscode-pylance、ms-toolsai.jupyter、ms-python.black-formatter、charliermarsh.ruff、dbaeumer.vscode-eslint、esbenp.prettier-vscode、github.copilot等扩展并配置了按语言分流的格式化器Python 用 BlackJS/TS 用 Prettier与 pyproject.toml 中[tool.black]、[tool.isort]、[tool.mypy]、[tool.ruff]、[tool.pytest.ini_options]的 lint/格式化/测试配置形成闭环。3.2 操作步骤步骤 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。Docker 开始构建镜像首次约 3 分钟。当新的终端提示符出现时你就已经身处容器内部——此时终端里的pip install、python等全部作用于容器环境。4. 选项 C – MinicondaConda 虚拟环境Miniconda 是一个轻量级安装器用于安装 Conda、Python 及少量基础包。Conda 本身是包管理器能让不同 Python虚拟环境与包的创建、切换更便捷对于pip渠道拿不到的二进制包也有独特价值例如文档故障排查表提到的 Microsoft AI 库需走conda install -c microsoft。步骤 0安装 Miniconda——按 Miniconda 官方安装指南操作后用以下命令核验conda --version步骤 1创建环境描述文件——新建一个environment.yml如果你是在 Codespaces 场景下跟随本文档操作则应将其放在.devcontainer目录内即.devcontainer/environment.yml。文档给出的内容模板name: environment-name channels: - defaults - microsoft dependencies: - pythonpython-version - openai - python-dotenv - pip - pip: - azure-ai-ml步骤 2按模板填充——把上段 YAML 写入你的environment.yml替换环境名与 Python 版本。步骤 3创建并激活 Conda 环境conda env create --name ai4beg --file .devcontainer/environment.yml # .devcontainer 子路径仅适用于 Codespace 场景 conda activate ai4beg结合仓库实际文件.devcontainer/environment.yml当前维护中的模板为name: dev channels: - defaults dependencies: - python3.10.0 - openai - python-dotenv - pip - pip: - azure-ai-inference注意与文档模板的两点差异仓库版本把环境名定为dev、Python 固定为3.10.0且推理 SDK 已由早期的azure-ai-ml演进为azure-ai-inference后者同样出现在 requirements.txt 中。如果你直接复用仓库文件conda env create --file .devcontainer/environment.yml即可得到与容器方案一致的依赖集合。遇到 Conda 环境问题时可参考 Conda 官方环境管理文档排查。5. 选项 D – 经典 Jupyter / JupyterLab浏览器内运行笔记本适用人群偏爱经典 Jupyter 界面或不想用 VS Code 跑笔记本的读者。步骤 1启动 Jupyter——进入终端cd到课程目录后执行jupyter notebook或者多用户场景jupyterhub命令会在终端窗口中打印出访问 URL。打开该 URL 后能看到课程目录大纲并可以打开任意*.ipynb笔记本例如08-building-search-applications/python/oai-solution.ipynb。Jupyter 本身无需单独安装requirements.txt中的ipywidgets8.1.8提供了笔记本内交互式控件的支持而 pyproject.toml 的开发依赖pytest等与 Dev Container 的post-create.sh表明课程在笔记本之外还配有可运行的 Python 脚本与测试见 tests/ 目录下的conftest.py与三个test_*.py文件。6. 配置 API Keys.env文件与python-dotenv构建任何应用时API Key 的安全保管都是重中之重。文档明确建议不要把 API Key 直接写死在代码里——把凭据提交到公开仓库可能招致安全问题甚至被人恶意利用产生额外费用。推荐做法是使用.env文件配合python-dotenv。时效说明以仓库英文源文档为准GitHub Models及其GITHUB_TOKEN变量将于 2026 年 7 月末退役文档现改用 Microsoft Foundry Models 作为多提供商模型入口。以下是文档给出的逐步操作流程6 步进入项目目录cd path/to/your/project创建.env文件——Unix 系系统touch .envWindowsecho . .env编辑.env文件——用任意文本编辑器打开写入凭据变量。文档的示例GITHUB_TOKENyour_github_token_here而当前仓库维护的模板.env.copy展示了实际使用的变量全集这是照抄模板 → 填值 → 重命名最可靠的做法# OpenAI Provider OPENAI_API_KEYadd your OpenAI API key here ## Azure OpenAI in Microsoft Foundry AZURE_OPENAI_API_VERSION2024-10-21 AZURE_OPENAI_API_KEYadd your Foundry resource key here AZURE_OPENAI_ENDPOINThttps://resource-name.openai.azure.com AZURE_OPENAI_DEPLOYMENTchat completion deployment, e.g. gpt-4o-mini AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTe.g. text-embedding-3-small ## Microsoft Foundry Models替代即将退役的 GitHub Models AZURE_INFERENCE_ENDPOINTFoundry project endpoint AZURE_INFERENCE_CREDENTIALFoundry Models API key ## Hugging Face HUGGING_FACE_API_KEYHuggingFace token仓库提供.env.copy而非直接提供.env正是为了让模板可入库、而真实凭据永不出库。保存文件。安装python-dotenv若尚未安装pip install python-dotenv该包已由 requirements.txt 锁定为python-dotenv1.2.2执行过步骤 3 的依赖安装则无需重复操作。在 Python 脚本中加载环境变量from dotenv import load_dotenv import os # 从 .env 文件加载环境变量 load_dotenv() # 访问凭据变量 token os.getenv(GITHUB_TOKEN) # 或按 .env.copy 的当前变量名 endpoint os.getenv(AZURE_INFERENCE_ENDPOINT) credential os.getenv(AZURE_INFERENCE_CREDENTIAL) print(endpoint) 最后一条铁律永远不要提交.env——仓库的 .gitignore 已包含对其的忽略规则。各模型提供商OpenAI、Foundry、Hugging Face 等的完整申请指引见 00-course-setup/03-providers.md。7. 下一步指引我想要…去哪里开始第 1 课01-introduction-to-genai/README.md配置一个 LLM 提供商00-course-setup/03-providers.md结识其他学习者加入课程官方 Discord 社区入口见课程 README.md8. 故障排查文档附带的排查表症状 → 解法覆盖四种方案中最高频的失败模式症状解决方案python not found将 Python 加入 PATH或在安装后重新打开终端pip无法构建 wheelWindows执行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安装 Microsoft AI 库注意仓库当前 environment.yml 已改用azure-ai-inference若课程脚本导入该包可pip install azure-ai-inference四条主线venv / Dev Container / Conda / Jupyter最终殊途同归依赖来自同一份requirements.txt凭据来自同一个.env课程 21 课的作业在任一环境中都能跑通。选择标准只有一条——哪个对你当下的机器最省心就用哪个。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
