generative-ai-for-beginners 本地环境搭建指南:四套可选的开发方案与密钥安全配置

generative-ai-for-beginners 本地环境搭建指南:四套可选的开发方案与密钥安全配置 generative-ai-for-beginners 本地环境搭建指南四套可选的开发方案与密钥安全配置【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginnersgenerative-ai-for-beginners是微软推出的 21 课生成式 AI 入门课程仓库各章节同时提供 Python 代码、Jupyter Notebook 与 TypeScript/JavaScript 示例。本文面向希望在自己的笔记本上离线运行全部课程代码的开发者系统讲解从「克隆仓库」到「密钥安全注入」的完整本地配置流程官方提供了两条主线——(A) 原生 Python venv 与 (B) VS Code Dev ContainerDocker另有 (C) Miniconda 与 (D) 经典 Jupyter 两条进阶路径。读完本文你将掌握四种环境的搭建方法、仓库依赖清单的真实含义以及使用.env文件安全加载 API 凭据的正确姿势从而平滑接续后续每一课的动手练习。1. 前置条件确认本机工具链在开始前请确认以下工具已安装到你的机器上。下表来自课程官方本地配置文档 translations/el/00-course-setup/02-setup-local.md 与 00-course-setup/02-setup-local.md英文原文两文结构一致工具版本 / 说明Python3.10 及以上从 python.org 官方渠道下载Git最新版macOS 随 Xcode、Windows 用 Git for Windows、Linux 用发行版包管理器VS Code可选但强烈推荐Docker Desktop仅方案 B 需要免费安装提示安装完毕后建议先在终端里验证工具是否可用python --version、git --version、docker --version、code --version值得补充的是「Python 3.10」并非随意设定仓库根目录的 pyproject.toml 中requires-python 3.10且开发工具链black、mypy 等的 target-version 均指向 py310 及以上因此 3.10 是本仓库实际支持的基线版本。2. 方案 A原生 Python 虚拟环境最快捷如果你希望环境最轻、启动最快优先选择本方案。它不依赖 Docker只依赖本机 Python。步骤 1克隆仓库课程要求先 fork 再克隆便于你提交自己的练习代码随后进入仓库根目录git clone https://github.com/your-github/generative-ai-for-beginners cd generative-ai-for-beginners其中your-github请替换为你自己的 GitHub 用户名fork 流程详见 00-course-setup/README.md。步骤 2创建并激活虚拟环境Python 官方虚拟环境工具venv能在项目目录内隔离出一份独立依赖避免污染全局 Pythonpython -m venv .venv # 创建虚拟环境 source .venv/bin/activate # macOS / Linux 激活 .\.venv\Scripts\activate # Windows PowerShell 激活✅ 激活成功的标志是命令行提示符前缀出现(.venv)——这表示你已经进入了该虚拟环境。步骤 3安装依赖在激活状态下执行pip install -r requirements.txt仓库根目录的 requirements.txt 实际内容如下截至当前仓库版本可见它既覆盖了主流 LLM 交互与可视化也包含了 Notebook 运行所需的组件ipywidgets8.1.8 numpy2.4.2 matplotlib3.10.8 pandas3.0.0 tqdm4.68.4 python-dotenv1.2.2 openai1.12.0 tiktoken azure-ai-inference scikit-learn若希望进入课程开发/贡献模式还可以按 pyproject.toml 中的dev可选依赖安装代码质量工具black、isort、mypy、ruff、pytest它们与本仓库 CI 的检查项保持一致。安装完成后即可跳到下文第 6 节配置 API 密钥。3. 方案 BVS Code Dev ContainerDocker本仓库自带一个基于「Universal 运行时镜像」的 development container可同时支持 Python 3、.NET、Node.js 与 Java 开发。使用该方案的收益是与 GitHub 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 ContainerDocker 将基于 .devcontainer/devcontainer.json 构建镜像——首次构建约需 3 分钟。当终端提示符出现时你就已经位于容器内部了。为什么优先考虑它与 Codespaces 环境完全一致多人协作、提交 PR 时不会出现「我这能跑你那跑不了」的依赖偏差。关于这套配置仓库里的 .devcontainer/devcontainer.json 给出了源码级细节值得解读基础镜像为mcr.microsoft.com/devcontainers/universal:2.13因此容器内同时具备 Python 3 / .NET / Node.js / Java 运行时hostRequirements.cpus 4即 Docker 至少为该容器预留 4 个 CPU 核心updateContentCommand会在内容更新时执行python3 -m pip install -r requirements.txt保证依赖自动就位postCreateCommand调用 .devcontainer/post-create.sh该脚本额外补装python-dotenv、openai以及ruff black mypy pytest等开发工具customizations.vscode预装了 Python、Pylance、Jupyter、Black Formatter、Ruff、ESLint、Prettier 与 GitHub Copilot 扩展并开启editor.formatOnSave其中 Python 默认格式化器为 black、JS/TS 为 Prettier——打开仓库即可获得开箱即用的格式化体验。4. 方案 CMiniconda / CondaMiniconda 是一个轻量级安装器用于安装 Conda、Python 及若干常用包。Conda 本身是包管理器擅长创建与切换不同的 Python 虚拟环境尤其适合安装pip无法提供的二进制/平台相关包本课程场景中的azure-ai-ml即属此类可通过 Microsoft 频道获取。步骤 0安装 Miniconda按官方安装向导完成安装后验证conda --version步骤 1创建环境描述文件新建一个environment.yml文件。如果是在 Codespaces 中跟随操作请将其放在.devcontainer目录内即.devcontainer/environment.yml本仓库根目录已存在一份由官方维护的真实范例可直接对照参考 .devcontainer/environment.yml其中name: dev、Python 锁定为 3.10.0并包含openai、python-dotenv与 pip 安装的azure-ai-inference。步骤 2填写环境文件课程文档给出的模板如下name: environment-name channels: - defaults - microsoft dependencies: - pythonpython-version - openai - python-dotenv - pip - pip: - azure-ai-ml字段含义name环境名称自由指定channels软件源其中microsoft用于拉取azure-ai-ml等微软 AI 库dependenciespythonpython-version用你想要的 Python 版本号替换如3.10openai与python-dotenv为课程代码核心依赖pip:子段声明只能从 PyPI 获取的包如azure-ai-ml。步骤 3创建并激活 Conda 环境conda env create --name ai4beg --file .devcontainer/environment.yml # .devcontainer 子路径仅适用于 Codespace 场景 conda activate ai4beg提示若在 Conda 安装微软 AI 库时遇到错误可直接执行conda install -c microsoft azure-ai-ml手工补装详见下文的故障排查表。5. 方案 D经典 Jupyter / Jupyter Lab浏览器内运行适用人群偏爱传统 Jupyter 交互、或不希望依赖 VS Code 即可运行 Notebook 的开发者。步骤 1启动 Jupyter在终端导航到课程目录后执行jupyter notebook或jupyterhubJupyter 实例启动后访问 URL 会显示在命令行窗口中。进入页面后即可看到课程大纲并导航到任意*.ipynb文件例如课程 08 的完整可运行解答 08-building-search-applications/python/oai-solution.ipynb该文件在本仓库中真实存在覆盖向量搜索/嵌入检索全流程。各章 Notebook 都位于对应课程的python/目录下例如 04-prompt-engineering-fundamentals/python/。6. 配置 API 密钥用.env文件安全托管凭据无论选择以上哪种环境构建任何调用 LLM 的应用前都必须妥善保管 API 密钥。切勿把密钥硬编码进代码——提交到公开仓库可能造成安全问题甚至被恶意使用者刷出巨额费用。推荐的做法在本项目根目录创建.env文件该文件已被 .gitignore 忽略不会进入版本控制按以下步骤完成密钥注入。步骤 1进入项目根目录cd path/to/your/project步骤 2创建.env文件Unix 系系统用touchWindows 用echotouch .envWindowsecho . .env步骤 3编辑文件并写入凭据用 VS Code、Notepad 等文本编辑器打开.env将占位符替换为真实值GITHUB_TOKENyour_github_token_here步骤 4保存文件保存更改并关闭编辑器。步骤 5安装python-dotenvpython-dotenv用于把.env中的变量加载为 Python 进程的环境变量。若尚未安装pip install python-dotenv该依赖同时已被 requirements.txt版本锁定python-dotenv1.2.2与 pyproject.tomlpython-dotenv1.0.0声明因此方案 A 安装依赖后通常无需重复安装。步骤 6在 Python 脚本中加载环境变量from dotenv import load_dotenv import os # 从 .env 文件加载环境变量 load_dotenv() # 读取 GITHUB_TOKEN github_token os.getenv(GITHUB_TOKEN) print(github_token)这样你就成功创建了.env、写入了凭据并在 Python 应用中加载了它。仓库中的安全实践佐证密钥「只进环境变量、绝不入库」在本仓库并非停留在口头约定而是有工程实现支撑课程代码广泛使用os.getenv(...)/os.environ[...]读取密钥仓库还封装了共享工具 shared/python/env_utils.py其中的get_required_env(var_name, description)会在关键环境变量缺失时抛出带提示的ValueError如Missing required environment variable: ... Please set it in your .env file or environmentvalidate_env_vars(*var_names)则支持一次性批量校验多个变量——这正是在 Notebook 里「没配密钥先报错、配置完即可跑通」的原因根目录存在一份 .env.copy 模板也是 00-course-setup/03-providers.md 官方文档推荐的做法把模板复制为.env后再填写能避免手写变量名出错cp .env.copy .env关于凭据变量的最新变化当前英文原版文档 00-course-setup/02-setup-local.md 已更新为 Microsoft Foundry Models 凭据变量AZURE_INFERENCE_ENDPOINT与AZURE_INFERENCE_CREDENTIAL因为 GitHub Models及其GITHUB_TOKEN预计于 2026 年 7 月底退役.env.copy中还提供了 OpenAIOPENAI_API_KEY、Azure OpenAIAZURE_OPENAI_*与 Hugging FaceHUGGING_FACE_API_KEY等多套占位变量。完整的多 Provider 申请、取值与配置指引见 providers.md。再次强调永远不要提交.env——它已被仓库的 .gitignore 忽略如自行改动务必保持忽略规则不变。7. 下一步做什么环境就绪后可按需求导航到对应内容我想……前往……开始第 1 课01-introduction-to-genai配置一个 LLM Providerproviders.md系统学习各课并查看全部章节课程根目录 README.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 库若环境长时间卡住尤其容器构建超过 10 分钟可优先执行Rebuild ContainerNotebook 内核缺失时在 Notebook 菜单中执行Kernel ▸ Select Kernel ▸ Python 3即可详见 00-course-setup/README.md 的故障排查小节。小结本文完整覆盖了在本地运行generative-ai-for-beginners课程的四条路径venv 最快、Dev Container 最一致、Conda 最擅长管理非 pip 依赖、Jupyter 最贴近 Notebook 原生体验。四条路径殊途同归——它们最终都会落到同一套仓库代码与同一个.env凭据机制上。你可以先选最顺手的一条跑通第 1 课再回到 providers.md 配置你偏好的模型供应商开启完整的生成式 AI 动手之旅。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考